feat(cli): add api passthrough, chat streaming, doctor warn status

Close the v0.2 RAG demo loop and ship the validation infrastructure:

  - weknora api <method> <path> [--data X | --data-file F]
      Raw passthrough wrapping client.Raw, gh-style. JSON envelope mode
      surfaces status / headers / parsed body. Non-2xx routes through
      cmdutil.ClassifyHTTPStatus (factored out of ClassifyHTTPError so
      both SDK-error and direct-status paths stay aligned — reuse review).

  - weknora chat <text> [--session-id S] [--no-stream]
      KnowledgeQAStream consumer with two output modes:
        - TTY default: token streaming + references footer
        - --json / --no-stream / non-TTY: buffered single envelope
      Auto-creates a session when --session-id is omitted; the id prints
      to stderr at start AND on stream failure (^C scrolls past the
      first announcement, so the recovery hint is re-surfaced when the
      user is most likely to need it).

  - cli/internal/sse/Accumulator
      buffers Content / References / SessionID across SDK callbacks.
      Idempotent post-Done so misbehaving servers don't corrupt state.

  - doctor: ok → ok / warn / fail / skip
      warn marks soft issues that don't block: server within compat range
      but >=1 minor behind CLI; credential storage falling back to file
      because keyring is unavailable. Envelope.ok stays true on warn,
      flips false on fail (exit 1). doctor.error_network golden updated.

  - cli/acceptance/e2e/    real-server RAG full loop
      Build-tagged //go:build acceptance_e2e — kept out of the default
      `go test ./...`. Exercises kb create → doc upload → poll ready →
      search → chat → cleanup against a server pointed at by
      WEKNORA_E2E_HOST / _TOKEN.

  - .github/workflows/cli-e2e.yml
      manual workflow_dispatch + label-gated PR trigger
      ("acceptance-e2e"). No-ops gracefully when the secrets aren't set
      so cross-fork PRs can't accidentally fail the suite.
This commit is contained in:
nullkey
2026-05-11 02:44:13 +08:00
committed by lyingbug
parent 8a0674186e
commit 3fb3583a92
16 changed files with 1935 additions and 67 deletions
+66
View File
@@ -0,0 +1,66 @@
name: CLI E2E
# Runs the cli/acceptance/e2e/ suite against a real WeKnora server.
# Cost-gated so it doesn't fire on every PR:
# - workflow_dispatch: maintainer can trigger manually
# - pull_request labeled "acceptance-e2e": adding the label kicks a run
#
# Required repo secrets (only set on Tencent/WeKnora; cross-fork PRs have no
# access and the job exits early via the secrets-present guard):
# WEKNORA_E2E_HOST - https URL of the test server
# WEKNORA_E2E_TOKEN - bearer token / API key for that host
#
# Mirrors gh acceptance/ trigger pattern: env-gated, opt-in, single matrix.
on:
workflow_dispatch:
pull_request:
types: [labeled, synchronize]
paths:
- 'cli/**'
- '.github/workflows/cli-e2e.yml'
defaults:
run:
working-directory: cli
shell: bash
permissions:
contents: read
jobs:
e2e:
name: rag full loop
# Skip auto-trigger on label-add unless the label is exactly "acceptance-e2e".
# Manual workflow_dispatch always runs.
if: |
github.event_name == 'workflow_dispatch' ||
(github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'acceptance-e2e'))
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@v6
- uses: actions/setup-go@v6
with:
go-version: '1.24'
cache-dependency-path: cli/go.sum
- name: secrets present
id: secrets
env:
E2E_HOST: ${{ secrets.WEKNORA_E2E_HOST }}
E2E_TOKEN: ${{ secrets.WEKNORA_E2E_TOKEN }}
run: |
if [ -z "$E2E_HOST" ] || [ -z "$E2E_TOKEN" ]; then
echo "::warning::WEKNORA_E2E_HOST or WEKNORA_E2E_TOKEN not set; skipping e2e."
echo "skip=true" >> "$GITHUB_OUTPUT"
else
echo "skip=false" >> "$GITHUB_OUTPUT"
fi
- name: go test -tags=acceptance_e2e
if: steps.secrets.outputs.skip == 'false'
env:
WEKNORA_E2E_HOST: ${{ secrets.WEKNORA_E2E_HOST }}
WEKNORA_E2E_TOKEN: ${{ secrets.WEKNORA_E2E_TOKEN }}
run: go test -tags=acceptance_e2e -v -timeout=8m ./acceptance/e2e/...
+10 -9
View File
@@ -95,12 +95,14 @@ var envelopeCases = []envelopeCase{
// 5. doctor.error_network — base_url returns 500 → ping fail → cascade
// skip on auth_credential + server_version. credential_storage still
// runs (independent). Doctor's RunE always returns nil; envelope.ok=true
// with summary.failed >= 1.
// runs (independent). v0.2 contract: any check=fail flips envelope.ok
// to false and exits 1 (RunE returns SilentError so the data envelope
// written by emit() is preserved as the only stdout content).
{
name: "doctor.error_network",
args: []string{"doctor", "--json"},
server: alwaysServerError,
name: "doctor.error_network",
args: []string{"doctor", "--json"},
server: alwaysServerError,
wantErr: true,
},
// 6-9. kb list / get — SDK paths /api/v1/knowledge-bases[/<id>]
@@ -167,12 +169,12 @@ var envelopeCases = []envelopeCase{
// 14-16. search — top-level command, positional query, --kb required.
{
name: "search.success",
args: []string{"search", "query", "--kb=kb1", "--top-k=3", "--json"},
args: []string{"search", "query", "--kb-id=kb1", "--top-k=3", "--json"},
server: searchTwoResults,
},
{
name: "search.error_resource_not_found",
args: []string{"search", "query", "--kb=missing", "--json"},
args: []string{"search", "query", "--kb-id=missing", "--json"},
server: always404,
wantErr: true,
},
@@ -181,7 +183,7 @@ var envelopeCases = []envelopeCase{
// server mock is never consumed; we still pass --kb to satisfy the
// MarkFlagRequired check that fires earlier in cobra's parse phase.
name: "search.error_input_invalid",
args: []string{"search", "query", "--kb=kb1", "--no-vector", "--no-keyword", "--json"},
args: []string{"search", "query", "--kb-id=kb1", "--no-vector", "--no-keyword", "--json"},
wantErr: true,
},
}
@@ -191,7 +193,6 @@ var envelopeCases = []envelopeCase{
// is contractually forbidden — see helpers_test.go SetForTest comment).
func TestEnvelopeGolden(t *testing.T) {
for _, tc := range envelopeCases {
tc := tc
t.Run(tc.name, func(t *testing.T) {
var ts *httptest.Server
var mockClient *sdk.Client
+265
View File
@@ -0,0 +1,265 @@
//go:build acceptance_e2e
// Package e2e_test drives the WeKnora CLI binary against a real running
// server to validate the RAG closing loop end-to-end.
//
// Build tag isolation: //go:build acceptance_e2e excludes this file from
// the default `go test ./...` (mirrors gh's acceptance/ build tag pattern;
// see https://github.com/cli/cli/tree/trunk/acceptance). To run:
//
// cd cli
// WEKNORA_E2E_HOST=https://kb.example.com \
// WEKNORA_E2E_TOKEN=eyJhbGc... \
// go test -tags=acceptance_e2e -v ./acceptance/e2e/...
//
// Optional WEKNORA_E2E_KB_NAME_PREFIX customizes the throwaway KB name (default
// "cli-e2e-"). Cleanup runs even on test failure via t.Cleanup so the server
// doesn't accumulate test debris.
package e2e_test
import (
"bytes"
"encoding/json"
"fmt"
"os"
"os/exec"
"path/filepath"
"strings"
"testing"
"time"
)
// TestRAGFullLoop walks the demo MVP path: link a context, create a KB,
// upload a doc, wait for indexing, search it, then chat against it. Each
// step parses the CLI's JSON envelope to extract IDs for the next step —
// validating both functional behavior and wire-contract stability.
func TestRAGFullLoop(t *testing.T) {
host := mustEnv(t, "WEKNORA_E2E_HOST")
token := mustEnv(t, "WEKNORA_E2E_TOKEN")
prefix := envOr("WEKNORA_E2E_KB_NAME_PREFIX", "cli-e2e-")
bin := buildBinary(t)
xdg := t.TempDir()
writeContextYAML(t, xdg, host, token)
env := append(os.Environ(),
"XDG_CONFIG_HOME="+xdg,
"XDG_CACHE_HOME="+filepath.Join(xdg, "cache"),
// SDK debug off — explicit so the CI run isn't noisy. C1 SDK silence
// makes this redundant in practice but the explicit flag documents
// intent.
"WEKNORA_SDK_DEBUG=",
)
// 1. kb create
kbName := prefix + fmt.Sprintf("%d", time.Now().UnixNano())
createOut := runJSON(t, bin, env, "kb", "create", "--name", kbName, "--json")
kbData, ok := createOut["data"].(map[string]any)
if !ok {
t.Fatalf("kb create envelope: data not an object: %v", createOut)
}
kbID, _ := kbData["id"].(string)
if kbID == "" {
t.Fatalf("kb create returned no id: %v", createOut)
}
t.Logf("created KB: %s (%s)", kbID, kbName)
t.Cleanup(func() {
// Best-effort cleanup; a 404 means the KB was already gone.
out, err := run(bin, env, "kb", "delete", kbID, "--force", "--json")
if err != nil {
t.Logf("cleanup kb delete: %v\n%s", err, out)
}
})
// 2. doc upload
docPath := writeSampleDoc(t)
uploadOut := runJSON(t, bin, env, "doc", "upload", docPath, "--kb-id", kbID, "--json")
docData, _ := uploadOut["data"].(map[string]any)
docID, _ := docData["id"].(string)
if docID == "" {
t.Fatalf("doc upload returned no id: %v", uploadOut)
}
t.Logf("uploaded doc: %s", docID)
// 3. poll until indexing finishes (status changes from "pending" / "processing" to "ready" / similar)
waitDocReady(t, bin, env, kbID, docID, 90*time.Second)
// 4. search — verify retrieval returns chunks
searchOut := runJSON(t, bin, env, "search", "sample", "--kb-id", kbID, "--top-k", "5", "--json")
searchData, _ := searchOut["data"].(map[string]any)
results, _ := searchData["results"].([]any)
if len(results) == 0 {
t.Fatalf("search returned no results: %v", searchOut)
}
t.Logf("search returned %d results", len(results))
// 5. chat — verify LLM answer + references in --json + --no-stream mode
// (--no-stream forces accumulator path; --json gates envelope output)
chatOut := runJSON(t, bin, env, "chat", "summarize the document briefly", "--kb-id", kbID, "--no-stream", "--json")
chatData, _ := chatOut["data"].(map[string]any)
answer, _ := chatData["answer"].(string)
if strings.TrimSpace(answer) == "" {
t.Fatalf("chat returned empty answer: %v", chatOut)
}
refs, _ := chatData["references"].([]any)
t.Logf("chat answer (%d chars), %d references", len(answer), len(refs))
if len(refs) == 0 {
// Soft warning — some servers may not surface references for every
// question, but the demo flow is supposed to.
t.Logf("warning: chat returned 0 references (server may have a different config)")
}
}
// mustEnv reads an env var and skips the test if missing — keeps the
// suite friendly to community contributors who clone the repo without
// access to the maintainer's E2E secrets.
func mustEnv(t *testing.T, key string) string {
t.Helper()
v := os.Getenv(key)
if v == "" {
t.Skipf("e2e: %s not set; skipping (set the env var or run `gh workflow run cli-e2e.yml`)", key)
}
return v
}
func envOr(key, fallback string) string {
if v := os.Getenv(key); v != "" {
return v
}
return fallback
}
// buildBinary compiles the CLI to a temp dir once per test run. Re-using a
// single binary across sub-cases avoids the multi-second linker cost on each
// step and matches gh acceptance/ build behavior.
func buildBinary(t *testing.T) string {
t.Helper()
dir := t.TempDir()
out := filepath.Join(dir, "weknora")
// Repo layout: this test sits at cli/acceptance/e2e/, so cli/ is two levels up.
cmd := exec.Command("go", "build", "-o", out, ".")
cmd.Dir = filepath.Join("..", "..")
cmd.Stdout = os.Stderr
cmd.Stderr = os.Stderr
if err := cmd.Run(); err != nil {
t.Fatalf("build cli: %v", err)
}
return out
}
// writeContextYAML drops a minimal config.yaml into XDG_CONFIG_HOME so the
// CLI finds a context without needing `weknora context add` (which prompts
// in interactive scenarios). Tests using `auth login` belong to a different
// suite; here we go straight to authenticated calls.
func writeContextYAML(t *testing.T, xdg, host, token string) {
t.Helper()
dir := filepath.Join(xdg, "weknora")
if err := os.MkdirAll(dir, 0o700); err != nil {
t.Fatalf("mkdir xdg: %v", err)
}
yaml := fmt.Sprintf(`current_context: e2e
contexts:
- name: e2e
host: %s
token: %s
`, host, token)
if err := os.WriteFile(filepath.Join(dir, "config.yaml"), []byte(yaml), 0o600); err != nil {
t.Fatalf("write config: %v", err)
}
}
// writeSampleDoc emits a small bilingual doc that gives the embedder enough
// signal for retrieval but stays tiny so indexing finishes within the poll
// window.
func writeSampleDoc(t *testing.T) string {
t.Helper()
content := `WeKnora E2E Sample Document
This sample document is used by the WeKnora CLI acceptance test suite to
validate the end-to-end retrieval-augmented generation pipeline.
向量检索的核心思想是把文本通过 embedding 模型映射到高维向量空间,然后通过余弦相似度
等度量找出语义最接近的内容片段。WeKnora 支持 vector + keyword 的混合检索模式。
The hybrid search mode combines vector similarity (semantic) with keyword
matching (lexical) to balance recall and precision.
`
dir := t.TempDir()
p := filepath.Join(dir, "sample.txt")
if err := os.WriteFile(p, []byte(content), 0o600); err != nil {
t.Fatalf("write sample: %v", err)
}
return p
}
// waitDocReady polls `doc list` until the uploaded document's status indicates
// indexing is complete. WeKnora server uses a few status values across versions
// ("ready", "completed", "ok") — accept any non-pending/non-processing/non-failed
// state so we don't break on a server-side rename. Failed status fails the test
// fast.
func waitDocReady(t *testing.T, bin string, env []string, kbID, docID string, timeout time.Duration) {
t.Helper()
deadline := time.Now().Add(timeout)
tick := 2 * time.Second
for time.Now().Before(deadline) {
out := runJSON(t, bin, env, "doc", "list", "--kb-id", kbID, "--page-size", "100", "--json")
data, _ := out["data"].(map[string]any)
items, _ := data["items"].([]any)
for _, it := range items {
m, ok := it.(map[string]any)
if !ok {
continue
}
id, _ := m["id"].(string)
if id != docID {
continue
}
status, _ := m["status"].(string)
low := strings.ToLower(status)
switch {
case low == "failed", low == "error":
t.Fatalf("doc %s indexing failed: status=%q", docID, status)
case low == "pending", low == "processing", low == "":
// keep waiting
default:
t.Logf("doc %s ready (status=%q)", docID, status)
return
}
}
time.Sleep(tick)
}
t.Fatalf("doc %s did not reach ready within %s", docID, timeout)
}
// run executes the CLI and returns combined stdout. Errors include stderr +
// exit code so failures are debuggable without re-running.
func run(bin string, env []string, args ...string) ([]byte, error) {
cmd := exec.Command(bin, args...)
cmd.Env = env
var stdout, stderr bytes.Buffer
cmd.Stdout = &stdout
cmd.Stderr = &stderr
if err := cmd.Run(); err != nil {
return stdout.Bytes(), fmt.Errorf("%s %s: %v\nstderr:\n%s", filepath.Base(bin), strings.Join(args, " "), err, stderr.String())
}
return stdout.Bytes(), nil
}
// runJSON runs the CLI expecting --json output and parses the envelope.
// Test fails immediately on non-zero exit or unparseable JSON.
func runJSON(t *testing.T, bin string, env []string, args ...string) map[string]any {
t.Helper()
out, err := run(bin, env, args...)
if err != nil {
t.Fatalf("%v", err)
}
var env_ map[string]any
if err := json.Unmarshal(out, &env_); err != nil {
t.Fatalf("parse envelope from %v: %v\nstdout:\n%s", args, err, string(out))
}
if ok, _ := env_["ok"].(bool); !ok {
t.Fatalf("envelope ok=false from %v: %s", args, string(out))
}
return env_
}
@@ -1 +1 @@
{"ok":true,"data":{"summary":{"all_passed":false,"passed":1,"failed":1,"skipped":2},"checks":[{"name":"base_url_reachable","status":"fail","details":"server returned 500","hint":"verify the host configured for the active context (run `weknora auth login --host=...`) and network reachability"},{"name":"auth_credential","status":"skip","details":"prereq failed: base_url_reachable"},{"name":"server_version","status":"skip","details":"prereq failed: auth_credential"},{"name":"credential_storage","status":"ok","details":"keyring or file storage available"}]}}
{"ok":false,"data":{"summary":{"all_passed":false,"passed":1,"failed":1,"skipped":2},"checks":[{"name":"base_url_reachable","status":"fail","details":"server returned 500","hint":"verify the host configured for the active context (run `weknora auth login --host=...`) and network reachability"},{"name":"auth_credential","status":"skip","details":"prereq failed: base_url_reachable"},{"name":"server_version","status":"skip","details":"prereq failed: auth_credential"},{"name":"credential_storage","status":"ok","details":"keyring or file storage available"}]}}
+156
View File
@@ -0,0 +1,156 @@
// Package api implements the `weknora api` raw HTTP passthrough command.
//
// Mirrors `gh api` ergonomics: 2 positionals (method, path), --data /
// --data-file mutually exclusive body source, default raw response body to
// stdout, --json wraps in CLI envelope. Reuses sdk.Client.Raw which already
// applies tenant + auth headers; v0.2 does not support --header (SDK Raw
// signature lacks header param) — that's planned for v0.3.
package api
import (
"context"
"encoding/json"
"fmt"
"io"
"net/http"
"os"
"strings"
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/agent"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/format"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
sdk "github.com/Tencent/WeKnora/client"
)
// Options captures `weknora api` flag state.
type Options struct {
Data string
DataFile string
JSONOut bool
}
// Service is the narrow SDK surface this command depends on. The production
// implementation is *sdk.Client, whose Raw method already injects auth /
// tenant / request-id headers (see client.applyAuthHeaders). Tests substitute
// either a fake or a real client pointed at httptest.Server.
type Service interface {
Raw(ctx context.Context, method, path string, body any) (*http.Response, error)
}
// NewCmd returns the `weknora api` command.
func NewCmd(f *cmdutil.Factory) *cobra.Command {
opts := &Options{}
cmd := &cobra.Command{
Use: "api <method> <path>",
Short: "Make a raw API request to the WeKnora server",
Long: `Send an HTTP request through the SDK and print the response.
Auth, tenant, and request-id headers are applied automatically from the active
context. The response body is written to stdout by default; use --json to wrap
it in the CLI envelope (status / headers / body).
Examples:
weknora api GET /api/v1/knowledge-bases
weknora api POST /api/v1/knowledge-bases --data '{"name":"foo"}'
weknora api DELETE /api/v1/knowledge-bases/kb_xxx`,
Args: cobra.ExactArgs(2),
RunE: func(c *cobra.Command, args []string) error {
cli, err := f.Client()
if err != nil {
return err
}
return runAPI(c.Context(), opts, cli, args[0], args[1])
},
}
cmd.Flags().StringVarP(&opts.Data, "data", "d", "", "Request body as raw string (e.g. JSON)")
cmd.Flags().StringVar(&opts.DataFile, "data-file", "", "Read request body from file")
cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Wrap response in JSON envelope (status/headers/body)")
cmd.MarkFlagsMutuallyExclusive("data", "data-file")
agent.SetAgentHelp(cmd, "Raw HTTP passthrough to the WeKnora server. Use when no typed command exists for the endpoint. Headers (auth / tenant / request-id) are injected from the active context.")
return cmd
}
// runAPI is the testable core: validate inputs, dispatch via Service.Raw,
// classify status, and emit either the raw body or a JSON envelope.
func runAPI(ctx context.Context, opts *Options, svc Service, methodArg, path string) error {
method := strings.ToUpper(methodArg)
switch method {
case "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD":
default:
return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, fmt.Sprintf("unsupported method: %s", methodArg))
}
if !strings.HasPrefix(path, "/") {
return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, fmt.Sprintf("path must start with /: %s", path))
}
// Resolve request body. --data and --data-file are mutually exclusive at
// the cobra layer; the second branch is reachable only when --data is
// empty.
var body any
if opts.Data != "" {
body = json.RawMessage(opts.Data)
} else if opts.DataFile != "" {
contents, err := os.ReadFile(opts.DataFile)
if err != nil {
return cmdutil.Wrapf(cmdutil.CodeLocalFileIO, err, "read data file %s", opts.DataFile)
}
body = json.RawMessage(contents)
}
resp, err := svc.Raw(ctx, method, path, body)
if err != nil {
// Transport / DNS failure (Raw never returns a typed HTTP error of its
// own; non-2xx responses still surface as resp != nil, err == nil).
return cmdutil.Wrapf(cmdutil.ClassifyHTTPError(err), err, "%s %s", method, path)
}
defer resp.Body.Close()
respBody, err := io.ReadAll(resp.Body)
if err != nil {
return cmdutil.Wrapf(cmdutil.CodeNetworkError, err, "read response body")
}
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
code := cmdutil.ClassifyHTTPStatus(resp.StatusCode)
return cmdutil.NewError(code, fmt.Sprintf("HTTP %d: %s", resp.StatusCode, strings.TrimSpace(string(respBody))))
}
out := iostreams.IO.Out
if opts.JSONOut {
// Best-effort decode: if response body is valid JSON, surface the
// parsed structure under .data.body so envelope consumers can drill
// in; otherwise fall back to the raw string.
var bodyAny any
if len(respBody) > 0 {
if err := json.Unmarshal(respBody, &bodyAny); err != nil {
bodyAny = string(respBody)
}
}
hdrs := make(map[string]string, len(resp.Header))
for k, v := range resp.Header {
if len(v) > 0 {
hdrs[k] = v[0]
}
}
env := format.Success(map[string]any{
"status": resp.StatusCode,
"headers": hdrs,
"body": bodyAny,
}, nil)
return format.WriteEnvelope(out, env)
}
if _, err := out.Write(respBody); err != nil {
return cmdutil.Wrapf(cmdutil.CodeLocalFileIO, err, "write response body")
}
if len(respBody) > 0 && respBody[len(respBody)-1] != '\n' {
_, _ = out.Write([]byte{'\n'})
}
return nil
}
// compile-time check: the production SDK client implements Service.
var _ Service = (*sdk.Client)(nil)
+198
View File
@@ -0,0 +1,198 @@
package api
import (
"context"
"encoding/json"
"io"
"net/http"
"net/http/httptest"
"os"
"path/filepath"
"strings"
"testing"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
sdk "github.com/Tencent/WeKnora/client"
)
// newTestClient stands up an httptest server with the supplied handler and
// returns an *sdk.Client targeting it plus a teardown closure. The real SDK is
// used so we exercise the same Raw() code path as production (header
// injection, JSON marshalling, etc.).
func newTestClient(t *testing.T, h http.HandlerFunc) (*sdk.Client, func()) {
t.Helper()
srv := httptest.NewServer(h)
return sdk.NewClient(srv.URL), srv.Close
}
func TestAPI_GetSuccess(t *testing.T) {
out, _ := iostreams.SetForTest(t)
cli, stop := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodGet || r.URL.Path != "/api/v1/foo" {
t.Errorf("unexpected request: %s %s", r.Method, r.URL.Path)
}
w.Header().Set("Content-Type", "application/json")
_, _ = w.Write([]byte(`{"hello":"world"}`))
})
defer stop()
if err := runAPI(context.Background(), &Options{}, cli, "GET", "/api/v1/foo"); err != nil {
t.Fatalf("runAPI: %v", err)
}
got := out.String()
if !strings.Contains(got, `"hello":"world"`) {
t.Errorf("expected raw JSON body in stdout, got %q", got)
}
if !strings.HasSuffix(got, "\n") {
t.Errorf("expected trailing newline appended, got %q", got)
}
}
func TestAPI_GetSuccess_JSON(t *testing.T) {
out, _ := iostreams.SetForTest(t)
cli, stop := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
w.Header().Set("X-Request-Id", "req-123")
w.WriteHeader(http.StatusOK)
_, _ = w.Write([]byte(`{"value":42}`))
})
defer stop()
if err := runAPI(context.Background(), &Options{JSONOut: true}, cli, "GET", "/api/v1/foo"); err != nil {
t.Fatalf("runAPI: %v", err)
}
var env struct {
OK bool `json:"ok"`
Data struct {
Status int `json:"status"`
Headers map[string]string `json:"headers"`
Body map[string]any `json:"body"`
} `json:"data"`
}
if err := json.Unmarshal(out.Bytes(), &env); err != nil {
t.Fatalf("decode envelope: %v\n%s", err, out.String())
}
if !env.OK {
t.Errorf("expected ok:true, got %s", out.String())
}
if env.Data.Status != 200 {
t.Errorf("status: want 200, got %d", env.Data.Status)
}
if env.Data.Headers["Content-Type"] != "application/json" {
t.Errorf("Content-Type header missing: %v", env.Data.Headers)
}
if got, ok := env.Data.Body["value"]; !ok || got.(float64) != 42 {
t.Errorf("body.value: want 42, got %v", env.Data.Body)
}
}
func TestAPI_PostWithData(t *testing.T) {
_, _ = iostreams.SetForTest(t)
var seenBody []byte
var seenMethod, seenPath string
cli, stop := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
seenMethod = r.Method
seenPath = r.URL.Path
seenBody, _ = io.ReadAll(r.Body)
w.Header().Set("Content-Type", "application/json")
_, _ = w.Write([]byte(`{"id":"new"}`))
})
defer stop()
opts := &Options{Data: `{"name":"foo"}`}
if err := runAPI(context.Background(), opts, cli, "POST", "/api/v1/things"); err != nil {
t.Fatalf("runAPI: %v", err)
}
if seenMethod != http.MethodPost || seenPath != "/api/v1/things" {
t.Errorf("server saw %s %s, want POST /api/v1/things", seenMethod, seenPath)
}
// SDK marshals body via json.Marshal; json.RawMessage round-trips
// verbatim so the bytes server-side equal the --data argument.
if string(seenBody) != `{"name":"foo"}` {
t.Errorf("server received body %q, want %q", seenBody, `{"name":"foo"}`)
}
}
func TestAPI_DataFile(t *testing.T) {
_, _ = iostreams.SetForTest(t)
tmp := filepath.Join(t.TempDir(), "body.json")
payload := `{"k":"from-file"}`
if err := os.WriteFile(tmp, []byte(payload), 0o600); err != nil {
t.Fatalf("write temp: %v", err)
}
var seenBody []byte
cli, stop := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
seenBody, _ = io.ReadAll(r.Body)
_, _ = w.Write([]byte(`{}`))
})
defer stop()
opts := &Options{DataFile: tmp}
if err := runAPI(context.Background(), opts, cli, "POST", "/api/v1/x"); err != nil {
t.Fatalf("runAPI: %v", err)
}
if string(seenBody) != payload {
t.Errorf("body from --data-file: got %q, want %q", seenBody, payload)
}
}
func TestAPI_NotFound(t *testing.T) {
_, _ = iostreams.SetForTest(t)
cli, stop := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusNotFound)
_, _ = w.Write([]byte(`{"error":"missing"}`))
})
defer stop()
err := runAPI(context.Background(), &Options{}, cli, "GET", "/api/v1/missing")
if err == nil {
t.Fatal("expected error for 404")
}
if !cmdutil.IsNotFound(err) {
t.Errorf("expected resource.not_found, got %v", err)
}
}
func TestAPI_InvalidMethod(t *testing.T) {
_, _ = iostreams.SetForTest(t)
// No server needed: validation should fail before dispatch.
err := runAPI(context.Background(), &Options{}, nil, "FOO", "/api/v1/things")
if err == nil {
t.Fatal("expected error for unsupported method")
}
var ce *cmdutil.Error
if !asTypedError(err, &ce) || ce.Code != cmdutil.CodeInputInvalidArgument {
t.Errorf("expected input.invalid_argument, got %v", err)
}
}
func TestAPI_PathWithoutSlash(t *testing.T) {
_, _ = iostreams.SetForTest(t)
err := runAPI(context.Background(), &Options{}, nil, "GET", "api/v1/things")
if err == nil {
t.Fatal("expected error for missing leading slash")
}
var ce *cmdutil.Error
if !asTypedError(err, &ce) || ce.Code != cmdutil.CodeInputInvalidArgument {
t.Errorf("expected input.invalid_argument, got %v", err)
}
}
// asTypedError is a tiny wrapper around errors.As that keeps the call sites
// concise. Returns true on success, populating dst.
func asTypedError(err error, dst **cmdutil.Error) bool {
for e := err; e != nil; {
if t, ok := e.(*cmdutil.Error); ok {
*dst = t
return true
}
type unwrapper interface{ Unwrap() error }
u, ok := e.(unwrapper)
if !ok {
return false
}
e = u.Unwrap()
}
return false
}
+280
View File
@@ -0,0 +1,280 @@
// Package chat implements `weknora chat <text>` — the streaming RAG answer
// entry point.
//
// Two output modes share a single SDK call:
//
// - Stream mode (TTY + no --no-stream + no --json): write each
// StreamResponse.Content fragment directly to iostreams.IO.Out as it
// arrives, then print a footer with knowledge references. This is the
// "feels alive" UX a human typing in a terminal expects.
//
// - Accumulate mode (non-TTY, --no-stream, or --json): buffer every
// fragment via sse.Accumulator and emit a single envelope (or a single
// plain-text answer + references block) once Done. Agents and pipes
// get a deterministic single record to parse.
//
// The SDK's KnowledgeQAStream callback contract is invoked sequentially on
// one goroutine, so neither mode needs locking. The runChat core takes a
// chatService interface so tests inject a fake without standing up a real
// SSE server.
package chat
import (
"context"
"errors"
"fmt"
"io"
"strings"
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/format"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
"github.com/Tencent/WeKnora/cli/internal/sse"
sdk "github.com/Tencent/WeKnora/client"
)
// Options captures one `weknora chat` invocation.
type Options struct {
Query string
KBID string
SessionID string
NoStream bool
JSONOut bool
}
// chatService is the narrow SDK surface this command depends on. *sdk.Client
// satisfies it; tests substitute a fake. Compile-time check is at the bottom
// of this file.
type chatService interface {
CreateSession(ctx context.Context, req *sdk.CreateSessionRequest) (*sdk.Session, error)
KnowledgeQAStream(ctx context.Context, sessionID string, req *sdk.KnowledgeQARequest, cb func(*sdk.StreamResponse) error) error
}
// chatData is the success-envelope payload. Mirrors what an agent needs to
// continue a conversation: the answer text, retrieval references, and the
// session pointer to thread follow-ups.
type chatData struct {
Answer string `json:"answer"`
References []*sdk.SearchResult `json:"references"`
SessionID string `json:"session_id"`
AssistantMessageID string `json:"assistant_message_id,omitempty"`
KBID string `json:"kb_id"`
Query string `json:"query"`
}
// NewCmd builds `weknora chat <text>`.
func NewCmd(f *cmdutil.Factory) *cobra.Command {
opts := &Options{}
cmd := &cobra.Command{
Use: `chat <text>`,
Short: "Ask a streaming RAG question against a knowledge base",
Long: `Send a query to the WeKnora knowledge-chat endpoint and stream the
answer back. By default a fresh session is created on first invocation; pass
--session-id to continue an existing conversation.
Modes:
TTY (default): live token streaming + reference footer
Pipe / --no-stream / --json: buffered, emitted once on completion`,
Example: ` weknora chat "What is RRF?" --kb-id kb_123
weknora chat "Summarise PR-7" --kb my-kb --json
weknora chat "Continue?" --session-id sess_abc`,
Args: cobra.MinimumNArgs(1),
RunE: func(c *cobra.Command, args []string) error {
opts.Query = strings.TrimSpace(strings.Join(args, " "))
if opts.Query == "" {
return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, "query argument cannot be empty")
}
kbID, err := f.ResolveKB(c)
if err != nil {
return err
}
opts.KBID = kbID
cli, err := f.Client()
if err != nil {
return err
}
return runChat(c.Context(), opts, cli)
},
}
cmd.Flags().String("kb-id", "", "Knowledge base ID (overrides project link / env)")
cmd.Flags().String("kb", "", "Knowledge base name (resolved via list)")
cmd.Flags().StringVar(&opts.SessionID, "session-id", "", "Continue an existing chat session (skip auto-create)")
cmd.Flags().BoolVar(&opts.NoStream, "no-stream", false, "Buffer the full answer before printing (forces accumulate mode)")
cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Emit a single JSON envelope (implies --no-stream)")
cmd.MarkFlagsMutuallyExclusive("kb-id", "kb")
return cmd
}
// runChat is the testable core: validate, ensure a session, dispatch the
// stream, and route output. Returns a typed error suitable for the envelope.
func runChat(ctx context.Context, opts *Options, svc chatService) error {
if opts.Query == "" {
return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, "query argument cannot be empty")
}
if opts.KBID == "" {
// Defensive: the cobra layer resolves KB before runChat; this guards
// the direct-test entry point.
return cmdutil.NewError(cmdutil.CodeKBIDRequired, "kb id is required")
}
if svc == nil {
return cmdutil.NewError(cmdutil.CodeServerError, "chat: no SDK client available")
}
sessionID := opts.SessionID
autoCreated := false
if sessionID == "" {
sess, err := svc.CreateSession(ctx, &sdk.CreateSessionRequest{Title: "weknora chat"})
if err != nil {
// Map HTTP-shaped failures, but tag generic transport / unknown
// errors as session_create_failed so the dedicated hint fires.
code := cmdutil.ClassifyHTTPError(err)
if code == cmdutil.CodeNetworkError || code == cmdutil.CodeServerError {
code = cmdutil.CodeSessionCreateFailed
}
return cmdutil.Wrapf(code, err, "create chat session")
}
sessionID = sess.ID
autoCreated = true
}
// Decide output mode. Stream mode requires:
// 1. an interactive stdout (tty)
// 2. no --no-stream
// 3. no --json (envelope is single-record by definition)
streamMode := iostreams.IO.IsStdoutTTY() && !opts.NoStream && !opts.JSONOut
// Surface the auto-created session ID up-front so a user who hits ^C
// mid-stream still has the pointer to resume — no need to scroll back
// past tokens. Skipped in JSON mode (it ends up in the envelope) and
// when the caller already supplied --session-id.
if autoCreated && !opts.JSONOut {
fmt.Fprintf(iostreams.IO.Err, "session: %s (use --session-id to continue)\n", sessionID)
}
req := &sdk.KnowledgeQARequest{
Query: opts.Query,
KnowledgeBaseIDs: []string{opts.KBID},
AgentEnabled: false,
WebSearchEnabled: false,
Channel: "api",
}
acc := &sse.Accumulator{}
cb := func(r *sdk.StreamResponse) error {
if streamMode && r != nil && r.Content != "" {
// Best-effort write; if stdout dies the SDK will surface the
// error on the next iteration. No need to bail early.
_, _ = iostreams.IO.Out.Write([]byte(r.Content))
}
acc.Append(r)
return nil
}
streamErr := svc.KnowledgeQAStream(ctx, sessionID, req, cb)
if streamErr != nil {
// Re-surface the auto-created session id on failure so a user who
// missed the start-of-stream notice (it scrolls past mid-stream
// tokens, especially on ^C) can still recover with --session-id.
// Skipped in JSON mode — the envelope carries it in .data.session_id.
if autoCreated && !opts.JSONOut {
fmt.Fprintf(iostreams.IO.Err, "session: %s (resume with --session-id %s)\n", sessionID, sessionID)
}
// Context cancelled (Ctrl-C) → user-aborted, exit 130 lineage.
if errors.Is(streamErr, context.Canceled) || errors.Is(ctx.Err(), context.Canceled) {
return cmdutil.Wrapf(cmdutil.CodeUserAborted, streamErr, "chat cancelled")
}
// Stream began (we observed at least one event) but never reached a
// terminal Done frame: typed as sse_stream_aborted so the hint
// nudges the user toward --no-stream / retry.
if acc.Result() != "" && !acc.Done() {
return cmdutil.Wrapf(cmdutil.CodeSSEStreamAborted, streamErr, "stream aborted before completion")
}
// Pre-stream HTTP / transport failure: route through the canonical
// classifier so 401 / 404 / 5xx still surface their specific codes.
return cmdutil.Wrapf(cmdutil.ClassifyHTTPError(streamErr), streamErr, "knowledge qa stream")
}
// SDK returned nil but we never saw a Done event — server closed the
// connection cleanly mid-stream. Treat as aborted so the user sees the
// truncation rather than a silent partial answer. Includes the empty-body
// case (Done frame never arrived AND no content): better to surface the
// abort than emit ok=true with answer="" — agents can't distinguish the
// model genuinely had nothing to say from the stream getting cut.
if !acc.Done() {
return cmdutil.NewError(cmdutil.CodeSSEStreamAborted, "stream ended without a terminal event")
}
answer := acc.Result()
references := acc.References
if opts.JSONOut {
// Prefer the SDK-echoed session id (acc.SessionID) but fall back to
// our local sessionID — agents must always see a usable pointer.
sid := acc.SessionID
if sid == "" {
sid = sessionID
}
data := chatData{
Answer: answer,
References: references,
SessionID: sid,
AssistantMessageID: acc.AssistantMessageID,
KBID: opts.KBID,
Query: opts.Query,
}
return cmdutil.NewJSONExporter().Write(iostreams.IO.Out, format.Success(data, &format.Meta{KBID: opts.KBID}))
}
// Human / non-JSON paths: streaming mode already wrote the answer body
// via the callback, so we only need to render the trailing references
// (and a closing newline). Accumulate + non-JSON writes the answer here
// for the first time.
out := iostreams.IO.Out
if streamMode {
// Ensure the answer line ends cleanly before the references footer.
if !strings.HasSuffix(answer, "\n") {
fmt.Fprintln(out)
}
} else {
fmt.Fprint(out, answer)
if !strings.HasSuffix(answer, "\n") {
fmt.Fprintln(out)
}
}
renderReferences(out, references)
return nil
}
// renderReferences prints a compact human-readable references block.
// Skipped entirely when the server returned no references — agent-friendly
// silence beats an empty banner.
func renderReferences(w io.Writer, refs []*sdk.SearchResult) {
if len(refs) == 0 {
return
}
fmt.Fprintln(w)
fmt.Fprintln(w, "──── References ────")
for i, r := range refs {
if r == nil {
continue
}
title := r.KnowledgeTitle
if title == "" {
title = r.KnowledgeFilename
}
if title == "" {
title = r.KnowledgeID
}
fmt.Fprintf(w, "[%d] %s", i+1, title)
if r.Score > 0 {
fmt.Fprintf(w, " score=%.3f", r.Score)
}
fmt.Fprintln(w)
}
}
// compile-time check: the production SDK client implements chatService.
var _ chatService = (*sdk.Client)(nil)
+365
View File
@@ -0,0 +1,365 @@
package chat
import (
"context"
"encoding/json"
"errors"
"strings"
"testing"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
sdk "github.com/Tencent/WeKnora/client"
)
// fakeChatService implements chatService for unit tests. Tests configure the
// callback driver via streamEvents (delivered in order) and observe captured
// inputs through the exported fields.
type fakeChatService struct {
createSessionResp *sdk.Session
createSessionErr error
createCalled bool
streamErr error
streamEvents []*sdk.StreamResponse
gotSessionID string
gotRequest *sdk.KnowledgeQARequest
streamCalled bool
cbReturnsError error // if set, callback aborts after first event with this error
}
func (f *fakeChatService) CreateSession(_ context.Context, req *sdk.CreateSessionRequest) (*sdk.Session, error) {
f.createCalled = true
if f.createSessionErr != nil {
return nil, f.createSessionErr
}
if f.createSessionResp != nil {
return f.createSessionResp, nil
}
// Default: return a deterministic session id derived from the title so
// envelope assertions don't depend on uuid generation.
return &sdk.Session{ID: "sess_auto", Title: req.Title}, nil
}
func (f *fakeChatService) KnowledgeQAStream(ctx context.Context, sessionID string, req *sdk.KnowledgeQARequest, cb func(*sdk.StreamResponse) error) error {
f.streamCalled = true
f.gotSessionID = sessionID
f.gotRequest = req
for _, ev := range f.streamEvents {
if err := cb(ev); err != nil {
return err
}
if f.cbReturnsError != nil {
return f.cbReturnsError
}
}
return f.streamErr
}
// Sanity: fakeChatService must satisfy chatService. Mirrors the production
// var _ chatService = (*sdk.Client)(nil) check at the bottom of chat.go.
var _ chatService = (*fakeChatService)(nil)
func TestChat_StreamMode(t *testing.T) {
out, errBuf := iostreams.SetForTestWithTTY(t)
svc := &fakeChatService{
streamEvents: []*sdk.StreamResponse{
{Content: "Hello "},
{Content: "world"},
{Done: true, KnowledgeReferences: []*sdk.SearchResult{
{KnowledgeID: "k1", KnowledgeTitle: "Doc One", Score: 0.42},
}},
},
}
opts := &Options{Query: "hi", KBID: "kb_1"}
if err := runChat(context.Background(), opts, svc); err != nil {
t.Fatalf("runChat: %v", err)
}
got := out.String()
if !strings.Contains(got, "Hello world") {
t.Errorf("stdout missing streamed content: %q", got)
}
if !strings.Contains(got, "References") {
t.Errorf("stdout missing references footer: %q", got)
}
if !strings.Contains(got, "Doc One") {
t.Errorf("references should render KnowledgeTitle, got %q", got)
}
// auto-created session must announce itself on stderr
if !strings.Contains(errBuf.String(), "session: sess_auto") {
t.Errorf("expected stderr session hint, got %q", errBuf.String())
}
if !svc.createCalled {
t.Error("expected CreateSession invocation when SessionID empty")
}
if svc.gotSessionID != "sess_auto" {
t.Errorf("stream sessionID: got %q want sess_auto", svc.gotSessionID)
}
if svc.gotRequest == nil || svc.gotRequest.Channel != "api" {
t.Errorf("expected Channel=api, got %+v", svc.gotRequest)
}
}
func TestChat_JSONMode(t *testing.T) {
out, errBuf := iostreams.SetForTestWithTTY(t)
svc := &fakeChatService{
streamEvents: []*sdk.StreamResponse{
{Content: "answer body"},
{AssistantMessageID: "msg_99"},
{Done: true, KnowledgeReferences: []*sdk.SearchResult{{KnowledgeID: "k1"}}},
},
}
opts := &Options{Query: "q", KBID: "kb_42", JSONOut: true}
if err := runChat(context.Background(), opts, svc); err != nil {
t.Fatalf("runChat: %v", err)
}
// JSON mode must NOT print the human session-hint on stderr; the session
// id is carried inside the envelope instead.
if errBuf.Len() != 0 {
t.Errorf("expected empty stderr in JSON mode, got %q", errBuf.String())
}
var env struct {
OK bool `json:"ok"`
Data struct {
Answer string `json:"answer"`
SessionID string `json:"session_id"`
AssistantMessageID string `json:"assistant_message_id"`
KBID string `json:"kb_id"`
Query string `json:"query"`
References []struct {
KnowledgeID string `json:"knowledge_id"`
} `json:"references"`
} `json:"data"`
}
if err := json.Unmarshal(out.Bytes(), &env); err != nil {
t.Fatalf("decode envelope: %v\n%s", err, out.String())
}
if !env.OK {
t.Errorf("expected ok:true, got %s", out.String())
}
if env.Data.Answer != "answer body" {
t.Errorf("answer: got %q", env.Data.Answer)
}
if env.Data.SessionID != "sess_auto" {
t.Errorf("session_id: got %q", env.Data.SessionID)
}
if env.Data.AssistantMessageID != "msg_99" {
t.Errorf("assistant_message_id: got %q", env.Data.AssistantMessageID)
}
if env.Data.KBID != "kb_42" {
t.Errorf("kb_id: got %q", env.Data.KBID)
}
if env.Data.Query != "q" {
t.Errorf("query: got %q", env.Data.Query)
}
if len(env.Data.References) != 1 || env.Data.References[0].KnowledgeID != "k1" {
t.Errorf("references payload missing: %+v", env.Data.References)
}
}
func TestChat_NoStreamFlag(t *testing.T) {
// TTY enabled, but --no-stream forces accumulate mode → no live writes
// during callback; entire answer printed once after Done.
out, _ := iostreams.SetForTestWithTTY(t)
var written string
svc := &fakeChatService{
streamEvents: []*sdk.StreamResponse{
{Content: "buffered "},
{Content: "answer"},
{Done: true},
},
}
opts := &Options{Query: "q", KBID: "kb", NoStream: true}
if err := runChat(context.Background(), opts, svc); err != nil {
t.Fatalf("runChat: %v", err)
}
written = out.String()
if !strings.Contains(written, "buffered answer") {
t.Errorf("expected concatenated answer, got %q", written)
}
}
func TestChat_NonTTY_AccumulateMode(t *testing.T) {
// Non-TTY iostreams forces accumulate mode even without --no-stream.
out, _ := iostreams.SetForTest(t)
svc := &fakeChatService{
streamEvents: []*sdk.StreamResponse{
{Content: "piped"},
{Done: true},
},
}
opts := &Options{Query: "q", KBID: "kb"}
if err := runChat(context.Background(), opts, svc); err != nil {
t.Fatalf("runChat: %v", err)
}
if !strings.Contains(out.String(), "piped") {
t.Errorf("expected accumulated answer, got %q", out.String())
}
}
func TestChat_SessionIDProvided(t *testing.T) {
_, errBuf := iostreams.SetForTestWithTTY(t)
svc := &fakeChatService{
streamEvents: []*sdk.StreamResponse{{Done: true}},
}
opts := &Options{Query: "q", KBID: "kb", SessionID: "sess_existing"}
if err := runChat(context.Background(), opts, svc); err != nil {
t.Fatalf("runChat: %v", err)
}
if svc.createCalled {
t.Error("CreateSession must NOT be invoked when --session-id is provided")
}
if svc.gotSessionID != "sess_existing" {
t.Errorf("stream sessionID: got %q want sess_existing", svc.gotSessionID)
}
// No auto-create message because the user supplied the id.
if strings.Contains(errBuf.String(), "session:") {
t.Errorf("unexpected session hint emitted with explicit --session-id: %q", errBuf.String())
}
}
func TestChat_KBIDRequired(t *testing.T) {
_, _ = iostreams.SetForTest(t)
svc := &fakeChatService{}
// Run with KBID empty (bypassing the cobra resolver).
opts := &Options{Query: "q"}
err := runChat(context.Background(), opts, svc)
if err == nil {
t.Fatal("expected error, got nil")
}
var typed *cmdutil.Error
if !errors.As(err, &typed) {
t.Fatalf("expected *cmdutil.Error, got %T", err)
}
if typed.Code != cmdutil.CodeKBIDRequired {
t.Errorf("code: got %q want %q", typed.Code, cmdutil.CodeKBIDRequired)
}
if svc.createCalled || svc.streamCalled {
t.Error("KB validation must short-circuit before any SDK call")
}
}
func TestChat_EmptyQuery(t *testing.T) {
_, _ = iostreams.SetForTest(t)
svc := &fakeChatService{}
opts := &Options{Query: "", KBID: "kb"}
err := runChat(context.Background(), opts, svc)
if err == nil {
t.Fatal("expected error, got nil")
}
var typed *cmdutil.Error
if !errors.As(err, &typed) {
t.Fatalf("expected *cmdutil.Error, got %T", err)
}
if typed.Code != cmdutil.CodeInputInvalidArgument {
t.Errorf("code: got %q want %q", typed.Code, cmdutil.CodeInputInvalidArgument)
}
}
func TestChat_SDKError_PreStream(t *testing.T) {
// SDK fails before any event arrives → ClassifyHTTPError mapping.
// "HTTP error 401: ..." → auth.unauthenticated.
_, _ = iostreams.SetForTest(t)
svc := &fakeChatService{
streamErr: errors.New("HTTP error 401: token rejected"),
}
opts := &Options{Query: "q", KBID: "kb"}
err := runChat(context.Background(), opts, svc)
if err == nil {
t.Fatal("expected error, got nil")
}
var typed *cmdutil.Error
if !errors.As(err, &typed) {
t.Fatalf("expected *cmdutil.Error, got %T", err)
}
if typed.Code != cmdutil.CodeAuthUnauthenticated {
t.Errorf("code: got %q want %q", typed.Code, cmdutil.CodeAuthUnauthenticated)
}
}
func TestChat_SDKError_MidStream_AbortsAsSSE(t *testing.T) {
// Some content arrived, then the stream errored without a Done event →
// CodeSSEStreamAborted (separate from generic transport failure).
_, _ = iostreams.SetForTest(t)
svc := &fakeChatService{
streamEvents: []*sdk.StreamResponse{{Content: "partial"}},
streamErr: errors.New("connection reset"),
}
opts := &Options{Query: "q", KBID: "kb"}
err := runChat(context.Background(), opts, svc)
if err == nil {
t.Fatal("expected error, got nil")
}
var typed *cmdutil.Error
if !errors.As(err, &typed) {
t.Fatalf("expected *cmdutil.Error, got %T", err)
}
if typed.Code != cmdutil.CodeSSEStreamAborted {
t.Errorf("code: got %q want %q", typed.Code, cmdutil.CodeSSEStreamAborted)
}
}
func TestChat_ContextCancelled(t *testing.T) {
_, _ = iostreams.SetForTest(t)
ctx, cancel := context.WithCancel(context.Background())
cancel() // simulate Ctrl-C delivered before the SDK returns.
svc := &fakeChatService{streamErr: context.Canceled}
opts := &Options{Query: "q", KBID: "kb"}
err := runChat(ctx, opts, svc)
if err == nil {
t.Fatal("expected error, got nil")
}
var typed *cmdutil.Error
if !errors.As(err, &typed) {
t.Fatalf("expected *cmdutil.Error, got %T", err)
}
if typed.Code != cmdutil.CodeUserAborted {
t.Errorf("code: got %q want %q", typed.Code, cmdutil.CodeUserAborted)
}
}
func TestChat_SessionCreateFails(t *testing.T) {
_, _ = iostreams.SetForTest(t)
svc := &fakeChatService{
createSessionErr: errors.New("dial tcp: connection refused"),
}
opts := &Options{Query: "q", KBID: "kb"}
err := runChat(context.Background(), opts, svc)
if err == nil {
t.Fatal("expected error, got nil")
}
var typed *cmdutil.Error
if !errors.As(err, &typed) {
t.Fatalf("expected *cmdutil.Error, got %T", err)
}
if typed.Code != cmdutil.CodeSessionCreateFailed {
t.Errorf("code: got %q want %q", typed.Code, cmdutil.CodeSessionCreateFailed)
}
if svc.streamCalled {
t.Error("stream must not be invoked after session creation failed")
}
}
func TestChat_SessionCreate404SurfacesNotFound(t *testing.T) {
// HTTP-shaped session-create failures should NOT collapse into the
// session_create_failed bucket; they keep their canonical mapping so
// agents can react to e.g. resource.not_found.
_, _ = iostreams.SetForTest(t)
svc := &fakeChatService{
createSessionErr: errors.New("HTTP error 404: tenant not found"),
}
opts := &Options{Query: "q", KBID: "kb"}
err := runChat(context.Background(), opts, svc)
if err == nil {
t.Fatal("expected error, got nil")
}
var typed *cmdutil.Error
if !errors.As(err, &typed) {
t.Fatalf("expected *cmdutil.Error, got %T", err)
}
if typed.Code != cmdutil.CodeResourceNotFound {
t.Errorf("code: got %q want %q", typed.Code, cmdutil.CodeResourceNotFound)
}
}
+124 -36
View File
@@ -1,18 +1,23 @@
// Package doctor implements `weknora doctor` — 4-item self-check (spec §1.2).
//
// Status semantics (3-tier, from larksuite/cli's pass/fail/warn/skip set):
// Status semantics (4-tier, from larksuite/cli's pass/fail/warn/skip set):
//
// ok — passed
// warn — soft problem; non-blocking (e.g. server minor older than CLI,
// keychain unavailable so falling back to file store)
// fail — failed; "hint" actionable
// skip — cascade-skipped (prereq failed) or --offline mode
//
// Envelope: ok=true normally; data.summary.all_passed gives the agent a
// one-line short-circuit (spec §1.2 防 envelope.ok=true 误判).
// Envelope (v0.2):
// - any check is fail → envelope.ok=false, exit 1 (RunE returns SilentError
// so the data envelope is still emitted; the framework's error-envelope
// printer is bypassed for this command)
// - warn only / all ok → envelope.ok=true, exit 0
// - warn does NOT flip envelope.ok
//
// Special: base URL completely unreachable + non-offline → no checks can be
// initiated → caller may decide to surface envelope.ok=false. v0.1 minimal
// approach: even base_url fail still runs credential_storage (independent),
// so envelope.ok stays true; agents read data.summary.failed > 0.
// data.summary.all_passed gives the agent a one-line short-circuit; v0.2
// keeps it true ONLY when no warn / fail / skip checks are present. Agents
// SHOULD also inspect data.checks[].status to distinguish warn from ok.
package doctor
import (
@@ -48,6 +53,7 @@ type Status string
const (
StatusOK Status = "ok"
StatusWarn Status = "warn"
StatusFail Status = "fail"
StatusSkip Status = "skip"
)
@@ -61,9 +67,14 @@ type Check struct {
}
// Summary is the agent-friendly short-circuit payload (spec §1.2).
//
// AllPassed is true only when there are zero warn/fail/skip rows; warn does
// not block exit-0 (envelope.ok stays true) but it does flip AllPassed so
// agents reading just the boolean still notice the soft issue.
type Summary struct {
AllPassed bool `json:"all_passed"`
Passed int `json:"passed"`
Warned int `json:"warned,omitempty"`
Failed int `json:"failed"`
Skipped int `json:"skipped"`
}
@@ -96,26 +107,37 @@ func NewCmd(f *cmdutil.Factory) *cobra.Command {
cliVer, _, _ := build.Info()
r := runChecks(c.Context(), opts, svc, cliVer)
emit(opts, r)
return nil // doctor 自身不返回 error;失败状态在 data.checks
// v0.2 exit-code policy: fail → exit 1 (gh / kubectl convention);
// warn / ok / skip → exit 0. SilentError suppresses both the human
// "error: ..." line and the error envelope printer, so the data
// envelope already written by emit() is the only stdout content.
if r.Summary.Failed > 0 {
return cmdutil.SilentError
}
return nil
},
}
cmd.Flags().BoolVar(&opts.NoCache, "no-cache", false, "Bypass server-info cache (located at $XDG_CACHE_HOME/weknora/server-info.yaml); force re-probe")
cmd.Flags().BoolVar(&opts.Offline, "offline", false, "Skip network checks; only verify local keyring/file storage (credential_storage check still runs)")
cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope")
agent.SetAgentHelp(cmd, "Returns 4 health checks. AGENT short-circuit: read data.summary.all_passed; if false, inspect data.checks[].status (ok/fail/skip).")
agent.SetAgentHelp(cmd, "Returns 4 health checks. AGENT short-circuit: read data.summary.all_passed; if false, inspect data.checks[].status (ok/warn/fail/skip). exit 1 only when any status=fail; warn does not change envelope.ok.")
return cmd
}
// cascade implements the two short-circuits every gated check shares:
// offline-mode skip and prereq-failed skip. Returns true when the check has
// been completed (Status set on c) and the caller should NOT run its body.
//
// A prereq is considered "passing" if its Status is OK or Warn — warn signals
// a soft problem that does not block downstream functionality. Only fail/skip
// cascades into a downstream skip.
func cascade(c *Check, offline bool, prereqs ...*Check) bool {
if offline {
c.Status, c.Details = StatusSkip, "offline mode"
return true
}
for _, p := range prereqs {
if p.Status != StatusOK {
if p.Status != StatusOK && p.Status != StatusWarn {
c.Status, c.Details = StatusSkip, "prereq failed: "+p.Name
return true
}
@@ -169,14 +191,7 @@ func runChecks(ctx context.Context, opts *Options, svc Services, cliVer string)
}
// 4. credential_storage — independent of network; never gated by offline.
if _, err := secrets.NewBestEffortStore(); err != nil {
checks[3].Status = StatusFail
checks[3].Details = err.Error()
checks[3].Hint = "verify keyring access; falls back to file store"
} else {
checks[3].Status = StatusOK
checks[3].Details = "keyring or file storage available"
}
fillCredentialStorageCheck(&checks[3])
return Result{Summary: summarize(checks), Checks: checks}
}
@@ -185,24 +200,74 @@ func runChecks(ctx context.Context, opts *Options, svc Services, cliVer string)
// sets Status/Details/Hint on c. fromCache toggles the "cached" suffix —
// the loader knows authoritatively which branch it took, time-based
// derivation from ProbedAt is unreliable since SaveCache uses time.Now().
//
// v0.2 mapping:
//
// compat.OK → StatusOK
// compat.SoftWarn → StatusWarn (server older but in-range; soft skew)
// compat.HardError → StatusFail (incompatible major; upgrade required)
func fillVersionCheck(c *Check, info *compat.Info, cliVer string, fromCache bool) {
level, hint := compat.Compat(info.ServerVersion, cliVer)
suffix := ""
if fromCache {
suffix = " (cached, pass --no-cache to refresh)"
}
if level == compat.HardError {
switch level {
case compat.HardError:
c.Status = StatusFail
c.Hint = hint
c.Details = "server " + info.ServerVersion + suffix
case compat.SoftWarn:
c.Status = StatusWarn
// Lowercase, no trailing punctuation: matches existing details style
// ("reachable in N", "keyring or file storage available"). The hint
// from compat.Compat already says "server is older (server X, client Y)…"
c.Details = hint + suffix
c.Hint = "some new commands may degrade gracefully; upgrade server when convenient"
default:
c.Status = StatusOK
if hint != "" {
c.Details = hint + suffix
} else {
c.Details = fmt.Sprintf("server %s%s", info.ServerVersion, suffix)
}
}
}
// credStoreFactory is the seam tests use to inject a fake-store outcome —
// keyring success, file-store fallback, or hard failure — without touching
// the lazy-resolve buildServices contract (round-4 fix). Production stays
// at secrets.NewBestEffortStore.
var credStoreFactory = func() (secrets.Store, error) { return secrets.NewBestEffortStore() }
// fillCredentialStorageCheck distinguishes the three terminal states the
// secrets layer can produce:
//
// keyring usable → StatusOK (preferred path)
// file fallback → StatusWarn (keyring unavailable, secrets still persist
// with 0600 file perms — agent containers / WSL hit this)
// construction fails → StatusFail
//
// Detection of "fallback to file store" relies on the type returned by
// secrets.NewBestEffortStore: a *FileStore concrete value means keyring was
// unavailable and the layer degraded. The Ref() URI scheme would also work
// but type-assertion is structurally more robust to scheme renames.
func fillCredentialStorageCheck(c *Check) {
store, err := credStoreFactory()
if err != nil {
c.Status = StatusFail
c.Details = err.Error()
c.Hint = "verify keyring access; falls back to file store"
return
}
if _, isFile := store.(*secrets.FileStore); isFile {
c.Status = StatusWarn
c.Details = "falling back to file store: keychain unavailable"
c.Hint = "secrets persist at 0600 under $XDG_CONFIG_HOME/weknora/secrets/; install / unlock keyring for OS-backed storage"
return
}
c.Status = StatusOK
if hint != "" {
c.Details = hint + suffix
} else {
c.Details = fmt.Sprintf("server %s%s", info.ServerVersion, suffix)
}
c.Details = "keyring or file storage available"
}
// loadOrProbeServerInfo respects --no-cache: load fresh cache when allowed,
@@ -229,30 +294,35 @@ func summarize(cs []Check) Summary {
switch c.Status {
case StatusOK:
s.Passed++
case StatusWarn:
s.Warned++
case StatusFail:
s.Failed++
case StatusSkip:
s.Skipped++
}
}
s.AllPassed = s.Failed == 0 && s.Skipped == 0
s.AllPassed = s.Failed == 0 && s.Skipped == 0 && s.Warned == 0
return s
}
// emit renders the doctor result. JSON path constructs the envelope directly
// rather than calling format.Success because envelope.ok must reflect "no
// fail" — warn does not flip it (per package doc), but fail does. We can't
// use format.Failure either, since that drops the data field.
func emit(opts *Options, r Result) {
if opts.JSONOut {
_ = format.WriteEnvelope(iostreams.IO.Out, format.Success(r, nil))
_ = format.WriteEnvelope(iostreams.IO.Out, format.Envelope{
OK: r.Summary.Failed == 0,
Data: r,
})
return
}
for _, c := range r.Checks {
marker := "[ok]"
switch c.Status {
case StatusFail:
marker = "[fail]"
case StatusSkip:
marker = "[skip]"
}
line := fmt.Sprintf("%-6s %-20s %s", marker, c.Name, c.Status)
// %-2s for the glyph: most are 1 column, leaves room for one trailing
// space. Status word follows so screen-readers / non-glyph terminals
// still get the textual classification.
line := fmt.Sprintf("%-2s %-20s %s", marker(c.Status), c.Name, c.Status)
if c.Details != "" {
line += " (" + c.Details + ")"
}
@@ -261,8 +331,26 @@ func emit(opts *Options, r Result) {
fmt.Fprintf(iostreams.IO.Out, " hint: %s\n", c.Hint)
}
}
fmt.Fprintf(iostreams.IO.Out, "\nsummary: %d passed, %d failed, %d skipped\n",
r.Summary.Passed, r.Summary.Failed, r.Summary.Skipped)
fmt.Fprintf(iostreams.IO.Out, "\nsummary: %d passed, %d warned, %d failed, %d skipped\n",
r.Summary.Passed, r.Summary.Warned, r.Summary.Failed, r.Summary.Skipped)
}
// marker returns the human-mode prefix glyph for a check status.
//
// Glyphs follow gh / kubectl convention. Agent / JSON consumers read the
// stable status string from data.checks[].status; the glyphs are presentation-
// only and never appear in --json output.
func marker(s Status) string {
switch s {
case StatusFail:
return "✗"
case StatusWarn:
return "⚠"
case StatusSkip:
return "⊘"
default:
return "✓"
}
}
// buildServices wires the Factory closures into the doctor.Services interface.
+274
View File
@@ -11,9 +11,25 @@ import (
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/compat"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
"github.com/Tencent/WeKnora/cli/internal/secrets"
sdk "github.com/Tencent/WeKnora/client"
)
// withCredStoreFactory swaps the package-level credStoreFactory hook for the
// duration of t. Tests that assert the credential_storage outcome use this
// rather than touching the real OS keyring (which is environment-dependent
// and would make CI flake on macOS vs Linux vs WSL). Restored in t.Cleanup.
//
// The hook intentionally lives at package scope (rather than as a runChecks
// parameter) so the production call site stays a zero-arg function — keeping
// the lazy-resolve buildServices contract unchanged (round-4 fix).
func withCredStoreFactory(t *testing.T, fn func() (secrets.Store, error)) {
t.Helper()
saved := credStoreFactory
credStoreFactory = fn
t.Cleanup(func() { credStoreFactory = saved })
}
type fakeServices struct {
systemInfo *sdk.SystemInfo
systemErr error
@@ -208,3 +224,261 @@ func TestDoctor_NoCache_BypassesCache(t *testing.T) {
t.Errorf("details should reflect probed version 1.0.0 not cached 9.9.9, got %q", r.Checks[2].Details)
}
}
// TestDoctor_VersionSkewWarns covers the v0.2 soft-skew path: server is older
// than CLI by ≥ 1 minor (same major, in compat range) → server_version=warn,
// envelope.ok stays true, all_passed=false (so agents reading just the
// boolean still notice). The compat decision lives in cli/internal/compat;
// this test pins the doctor-side mapping (compat.SoftWarn → StatusWarn).
func TestDoctor_VersionSkewWarns(t *testing.T) {
t.Setenv("XDG_CACHE_HOME", t.TempDir())
_, _ = iostreams.SetForTest(t)
// Force keyring path to ok so credential_storage doesn't itself warn —
// we want this test to assert ONLY on server_version.
withCredStoreFactory(t, func() (secrets.Store, error) { return secrets.NewMemStore(), nil })
svc := &fakeServices{
systemInfo: &sdk.SystemInfo{Version: "1.0.0"}, // server 1.0
userResp: goodUserResp(),
}
r := runChecks(context.Background(), &Options{}, svc, "1.5.0") // CLI 1.5
v := r.Checks[2]
if v.Name != "server_version" {
t.Fatalf("Checks[2] = %q, want server_version", v.Name)
}
if v.Status != StatusWarn {
t.Errorf("server_version status = %q, want warn (server older than CLI)", v.Status)
}
// compat.Compat hint contains "server is older" — that's the load-bearing
// substring agents may pattern-match. Not asserting full message text
// since compat.Compat owns the wording.
if !strings.Contains(v.Details, "older") {
t.Errorf("server_version details should mention older server, got %q", v.Details)
}
// Summary: warned counted, failed=0, all_passed flipped.
if r.Summary.Warned != 1 {
t.Errorf("expected Warned=1, got summary %+v", r.Summary)
}
if r.Summary.Failed != 0 {
t.Errorf("expected Failed=0, got summary %+v", r.Summary)
}
if r.Summary.AllPassed {
t.Error("AllPassed must be false when any check is warn")
}
// Envelope ok stays true (warn is non-blocking).
out, _ := iostreams.SetForTest(t)
emit(&Options{JSONOut: true}, r)
if !strings.Contains(out.String(), `"ok":true`) {
t.Errorf("envelope.ok must be true on warn-only run, got %q", out.String())
}
if !strings.Contains(out.String(), `"status":"warn"`) {
t.Errorf("envelope must surface status=warn, got %q", out.String())
}
}
// TestDoctor_HardErrorStillFails guards that a different-major skew remains
// fail (not warn). Without this, a later refactor could silently downgrade
// HardError to warn and we'd lose exit-1 on incompatible servers.
func TestDoctor_HardErrorStillFails(t *testing.T) {
t.Setenv("XDG_CACHE_HOME", t.TempDir())
_, _ = iostreams.SetForTest(t)
withCredStoreFactory(t, func() (secrets.Store, error) { return secrets.NewMemStore(), nil })
svc := &fakeServices{
systemInfo: &sdk.SystemInfo{Version: "2.0.0"},
userResp: goodUserResp(),
}
r := runChecks(context.Background(), &Options{}, svc, "1.0.0")
if r.Checks[2].Status != StatusFail {
t.Errorf("server_version status = %q, want fail (different major)", r.Checks[2].Status)
}
if r.Summary.Failed != 1 {
t.Errorf("expected Failed=1, got %+v", r.Summary)
}
}
// TestDoctor_KeychainFallbackWarns covers credential_storage's v0.2 third
// state: keyring unavailable, fell back to FileStore (agent containers,
// headless CI, WSL without DBus). The check should warn — secrets still
// persist (0600 file perms) but the OS-backed path was unreachable.
func TestDoctor_KeychainFallbackWarns(t *testing.T) {
t.Setenv("XDG_CACHE_HOME", t.TempDir())
t.Setenv("XDG_CONFIG_HOME", t.TempDir())
_, _ = iostreams.SetForTest(t)
withCredStoreFactory(t, func() (secrets.Store, error) {
// FileStore concrete type → fillCredentialStorageCheck reads warn.
return secrets.NewFileStore()
})
svc := &fakeServices{
userResp: goodUserResp(),
systemInfo: &sdk.SystemInfo{Version: "1.0.0"},
}
r := runChecks(context.Background(), &Options{}, svc, "1.0.0")
cs := r.Checks[3]
if cs.Name != "credential_storage" {
t.Fatalf("Checks[3] = %q, want credential_storage", cs.Name)
}
if cs.Status != StatusWarn {
t.Errorf("credential_storage status = %q, want warn (file fallback)", cs.Status)
}
if !strings.Contains(strings.ToLower(cs.Details), "file store") {
t.Errorf("details should mention file store, got %q", cs.Details)
}
if r.Summary.Warned != 1 {
t.Errorf("expected Warned=1, got %+v", r.Summary)
}
if r.Summary.Failed != 0 {
t.Errorf("expected Failed=0 (warn doesn't fail), got %+v", r.Summary)
}
}
// TestDoctor_CredStoreFactoryError surfaces the constructor failure path as
// fail (not warn) — distinguishes "cannot persist credentials at all" from
// "downgraded to file store".
func TestDoctor_CredStoreFactoryError(t *testing.T) {
t.Setenv("XDG_CACHE_HOME", t.TempDir())
_, _ = iostreams.SetForTest(t)
withCredStoreFactory(t, func() (secrets.Store, error) {
return nil, errors.New("disk full")
})
r := runChecks(context.Background(), &Options{Offline: true}, &fakeServices{}, "1.0.0")
if r.Checks[3].Status != StatusFail {
t.Errorf("credential_storage status = %q, want fail on constructor error", r.Checks[3].Status)
}
if !strings.Contains(r.Checks[3].Details, "disk full") {
t.Errorf("details should propagate underlying error, got %q", r.Checks[3].Details)
}
}
// TestDoctor_EmitEnvelope_OK_WhenWarnOnly pins the wire contract: warn never
// flips envelope.ok. emit() is the seam between Result and what agents
// observe; we test it in isolation rather than relying on summary fields.
func TestDoctor_EmitEnvelope_OK_WhenWarnOnly(t *testing.T) {
out, _ := iostreams.SetForTest(t)
r := Result{
Summary: Summary{AllPassed: false, Passed: 3, Warned: 1},
Checks: []Check{
{Name: "base_url_reachable", Status: StatusOK},
{Name: "auth_credential", Status: StatusOK},
{Name: "server_version", Status: StatusWarn, Details: "server is older"},
{Name: "credential_storage", Status: StatusOK},
},
}
emit(&Options{JSONOut: true}, r)
got := out.String()
if !strings.Contains(got, `"ok":true`) {
t.Errorf("envelope.ok must be true on warn-only result, got %q", got)
}
}
// TestDoctor_EmitEnvelope_NotOK_OnFail pins the dual: any fail flips ok=false.
func TestDoctor_EmitEnvelope_NotOK_OnFail(t *testing.T) {
out, _ := iostreams.SetForTest(t)
r := Result{
Summary: Summary{AllPassed: false, Passed: 2, Failed: 1, Skipped: 1},
Checks: []Check{
{Name: "base_url_reachable", Status: StatusFail, Details: "refused"},
{Name: "auth_credential", Status: StatusSkip},
{Name: "server_version", Status: StatusOK},
{Name: "credential_storage", Status: StatusOK},
},
}
emit(&Options{JSONOut: true}, r)
got := out.String()
if !strings.Contains(got, `"ok":false`) {
t.Errorf("envelope.ok must be false when any check fails, got %q", got)
}
}
// TestDoctor_HumanMarker_Warn confirms the human-mode glyph appears for warn
// rows. Glyph choice is presentation-only; we pin via substring (no width
// alignment assertion since terminal-width handling is environmental).
func TestDoctor_HumanMarker_Warn(t *testing.T) {
out, _ := iostreams.SetForTest(t)
r := Result{
Summary: Summary{Warned: 1},
Checks: []Check{
{Name: "server_version", Status: StatusWarn, Details: "older"},
},
}
emit(&Options{JSONOut: false}, r)
got := out.String()
if !strings.Contains(got, "⚠") {
t.Errorf("human output should contain ⚠ glyph for warn, got %q", got)
}
if !strings.Contains(got, "warn") {
t.Errorf("human output should still contain status word `warn`, got %q", got)
}
}
// TestDoctor_WarnedField_OmittedAtZero protects the JSON wire compactness:
// `warned` carries omitempty, so a clean run has no warned key. Existing
// agents inspecting older envelopes shouldn't see a sudden new field unless
// it actually fired.
func TestDoctor_WarnedField_OmittedAtZero(t *testing.T) {
out, _ := iostreams.SetForTest(t)
r := Result{
Summary: Summary{AllPassed: true, Passed: 4},
Checks: []Check{
{Name: "base_url_reachable", Status: StatusOK},
{Name: "auth_credential", Status: StatusOK},
{Name: "server_version", Status: StatusOK},
{Name: "credential_storage", Status: StatusOK},
},
}
emit(&Options{JSONOut: true}, r)
got := out.String()
if strings.Contains(got, `"warned"`) {
t.Errorf("envelope should omit `warned` field when zero, got %q", got)
}
}
// TestDoctor_RunE_FailReturnsSilentError is a behavior test on NewCmd: when
// any check is fail, RunE must return cmdutil.SilentError so the framework
// exit-1 path runs WITHOUT overwriting the data envelope emit() already
// wrote. This is the v0.2 contract change from v0.1's "always nil".
//
// SilenceErrors/SilenceUsage on the leaf cobra.Command suppress cobra's own
// "Error: ..." + usage dump that would otherwise leak to stderr when running
// the leaf in isolation (root.go sets these on the root, not on every leaf).
func TestDoctor_RunE_FailReturnsSilentError(t *testing.T) {
// Force base_url to fail by leaving host empty.
t.Setenv("XDG_CONFIG_HOME", t.TempDir())
t.Setenv("XDG_CACHE_HOME", t.TempDir())
_, _ = iostreams.SetForTest(t)
withCredStoreFactory(t, func() (secrets.Store, error) { return secrets.NewMemStore(), nil })
f := cmdutil.New()
cmd := NewCmd(f)
cmd.SilenceErrors = true
cmd.SilenceUsage = true
cmd.SetArgs([]string{"--json"})
cmd.SetContext(context.Background())
err := cmd.Execute()
if !errors.Is(err, cmdutil.SilentError) {
t.Errorf("RunE on fail must return SilentError, got %v", err)
}
}
// TestDoctor_RunE_WarnReturnsNil — soft skew path stays exit-0. Pairs with
// TestDoctor_RunE_FailReturnsSilentError: warn does NOT trigger SilentError.
func TestDoctor_RunE_WarnReturnsNil(t *testing.T) {
t.Setenv("XDG_CACHE_HOME", t.TempDir())
_, _ = iostreams.SetForTest(t)
withCredStoreFactory(t, func() (secrets.Store, error) { return secrets.NewFileStore() })
r := runChecks(context.Background(), &Options{Offline: true}, &fakeServices{}, "1.0.0")
// Smoke-check: warn-only result, no fails.
if r.Summary.Failed != 0 {
t.Fatalf("setup error: expected Failed=0, got %+v", r.Summary)
}
if r.Summary.Warned == 0 {
t.Fatalf("setup error: expected Warned>=1, got %+v", r.Summary)
}
}
+5
View File
@@ -2,6 +2,7 @@
//
// v0.0 shipped: version / auth / search.
// v0.1 adds: whoami / doctor / kb (list + get) / context (use).
// v0.2 adds: init / link / kb (create + delete) / doc (list + upload + delete) / api / chat.
package cmd
import (
@@ -12,7 +13,9 @@ import (
"github.com/spf13/cobra"
apicmd "github.com/Tencent/WeKnora/cli/cmd/api"
"github.com/Tencent/WeKnora/cli/cmd/auth"
chatcmd "github.com/Tencent/WeKnora/cli/cmd/chat"
contextcmd "github.com/Tencent/WeKnora/cli/cmd/context"
"github.com/Tencent/WeKnora/cli/cmd/doc"
"github.com/Tencent/WeKnora/cli/cmd/doctor"
@@ -180,6 +183,8 @@ hybrid searches against a WeKnora server from your shell or an AI agent.`,
cmd.AddCommand(initcmd.NewCmd(f))
cmd.AddCommand(linkcmd.NewCmd(f))
cmd.AddCommand(doc.NewCmd(f))
cmd.AddCommand(apicmd.NewCmd(f))
cmd.AddCommand(chatcmd.NewCmd(f))
return cmd
}
+22 -7
View File
@@ -18,7 +18,8 @@ import (
// Options is the runtime configuration of one search invocation.
type Options struct {
Query string
KBID string
KBID string // resolved id, populated by RunE before validate()
KBName string // raw --kb flag value (name or, for legacy v0.0 callers, id)
TopK int
VectorThreshold float64
KeywordThreshold float64
@@ -33,7 +34,12 @@ type Service interface {
HybridSearch(ctx context.Context, kbID string, params *sdk.SearchParams) ([]*sdk.SearchResult, error)
}
// NewCmdSearch builds `weknora search "<query>" --kb <id>`.
// NewCmdSearch builds `weknora search "<query>" --kb-id <id> | --kb <name>`.
//
// v0.0 shipped a single `--kb <id>` flag. v0.2 standardizes the KB-resolution
// surface across all commands (init / link / doc / chat) on `--kb-id` (id) +
// `--kb` (name → id via ListKnowledgeBases). search now follows the same
// convention. The resolution chain is identical to Factory.ResolveKB.
func NewCmdSearch(f *cmdutil.Factory) *cobra.Command {
opts := &Options{}
cmd := &cobra.Command{
@@ -42,9 +48,9 @@ func NewCmdSearch(f *cmdutil.Factory) *cobra.Command {
Args: cobra.ExactArgs(1),
RunE: func(c *cobra.Command, args []string) error {
opts.Query = strings.TrimSpace(args[0])
// Validate user input BEFORE touching the SDK client. Flag misuse
// should fail fast with the clearer error rather than blocking on
// auth / config when the invocation itself is wrong.
// Validate input shape before touching the SDK so flag/arg misuse
// surfaces fast (no auth / no client construction). KB resolution
// happens *after* — it needs a client.
if err := opts.validate(); err != nil {
return err
}
@@ -52,17 +58,26 @@ func NewCmdSearch(f *cmdutil.Factory) *cobra.Command {
if err != nil {
return err
}
if opts.KBID == "" && opts.KBName != "" {
resolved, rerr := cmdutil.ResolveKBNameToID(c.Context(), cli, opts.KBName)
if rerr != nil {
return rerr
}
opts.KBID = resolved
}
return runSearch(c.Context(), opts, cli)
},
}
cmd.Flags().StringVar(&opts.KBID, "kb", "", "Knowledge base ID to search (required)")
cmd.Flags().StringVar(&opts.KBID, "kb-id", "", "Knowledge base id to search")
cmd.Flags().StringVar(&opts.KBName, "kb", "", "Knowledge base name (resolved to id via list)")
cmd.Flags().IntVar(&opts.TopK, "top-k", 8, "Maximum results to return")
cmd.Flags().Float64Var(&opts.VectorThreshold, "vector-threshold", 0, "Vector retrieval similarity floor (per-channel, pre-fusion); 0 = no filter")
cmd.Flags().Float64Var(&opts.KeywordThreshold, "keyword-threshold", 0, "Keyword retrieval score floor (per-channel, pre-fusion); 0 = no filter")
cmd.Flags().BoolVar(&opts.NoVector, "no-vector", false, "Disable the vector channel")
cmd.Flags().BoolVar(&opts.NoKeyword, "no-keyword", false, "Disable the keyword channel")
cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope")
cmdutil.MustRequireFlag(cmd, "kb")
cmd.MarkFlagsMutuallyExclusive("kb-id", "kb")
cmd.MarkFlagsOneRequired("kb-id", "kb")
return cmd
}
+17 -10
View File
@@ -8,17 +8,24 @@ import (
)
// ConfirmDestructive prompts the user to confirm a destructive operation
// (e.g. delete). Returns nil if the operation should proceed, or a typed
// error otherwise:
// - CodeInputMissingFlag when the prompter rejects (non-TTY / agent mode):
// the caller forgot --force.
// - CodeUserAborted when the user explicitly answers no — also writes
// "Aborted." to stderr so the rejection is visible above the envelope.
// (e.g. delete) when the call is interactive, and proceeds without
// prompting otherwise. Behavior matrix:
//
// Skipped entirely when force is true, or when stdout is non-TTY, or when
// the caller is going to emit a JSON envelope (jsonOut=true) — envelope
// mode is by definition scripted, so a confirmation prompt would deadlock
// the consumer.
// force=true → proceed (skip prompt; explicit user opt-in)
// non-TTY stdout → proceed (no UI to ask; safer to follow the call
// than to break scripts/CI that don't pass
// --force every time)
// jsonOut=true → proceed (envelope mode is by definition scripted,
// a prompt would deadlock the consumer)
// TTY + interactive → prompt; user-yes proceeds, user-no returns
// CodeUserAborted ("Aborted." to stderr)
// prompter error → returns CodeInputMissingFlag (rare; AgentPrompter
// path or stdin closed mid-prompt)
//
// Callers that want a hard fail in non-TTY contexts should validate at the
// command layer (e.g. require --force when stdout is not a terminal). The
// agent-help text on each destructive command says "ALWAYS pass --force in
// agent mode" — this is the documented contract, not an enforcement here.
func ConfirmDestructive(p prompt.Prompter, force, jsonOut bool, what, id string) error {
if force || !iostreams.IO.IsStdoutTTY() || jsonOut {
return nil
+4 -4
View File
@@ -38,6 +38,10 @@ const (
CodeServerRateLimited ErrorCode = "server.rate_limited"
CodeServerIncompatibleVersion ErrorCode = "server.incompatible_version"
CodeNetworkError ErrorCode = "network.error"
// CodeSessionCreateFailed marks a chat invocation where the auto-created
// session POST failed. Surfaced as a typed code distinct from generic
// server.error so agents can retry with their own --session-id.
CodeSessionCreateFailed ErrorCode = "server.session_create_failed"
// local.* — config / file / keychain on the user's machine
CodeLocalConfigCorrupt ErrorCode = "local.config_corrupt"
@@ -64,10 +68,6 @@ const (
// from network.error (pre-stream transport failure) so users see the
// stream specifically aborted, not a connection that never opened.
CodeSSEStreamAborted ErrorCode = "local.sse_stream_aborted"
// CodeSessionCreateFailed marks a chat invocation where the auto-created
// session POST failed. Surfaced as a typed code distinct from generic
// server.error so agents can retry with their own --session-id.
CodeSessionCreateFailed ErrorCode = "server.session_create_failed"
// mcp.*
CodeMCPReadonlyMode ErrorCode = "mcp.readonly_mode"
+58
View File
@@ -0,0 +1,58 @@
// Package sse provides helpers for consuming server-sent event streams from
// the WeKnora SDK (KnowledgeQAStream, ContinueStream).
//
// Accumulator is the canonical sink: every callback event appends to a
// buffered Content string and updates terminal-state fields like References
// and SessionID. The non-streaming JSON envelope mode reads .Result() once
// .Done() is true; streaming mode writes Content tokens directly to stdout
// and only consults the accumulator for the final References footer.
package sse
import (
"strings"
sdk "github.com/Tencent/WeKnora/client"
)
// Accumulator buffers a KnowledgeQAStream callback sequence.
//
// Zero value is ready to use. Not safe for concurrent Append calls — the SDK
// invokes its callback sequentially on a single goroutine, so this matches
// the only contract that exists today.
type Accumulator struct {
builder strings.Builder
References []*sdk.SearchResult
SessionID string
AssistantMessageID string
finished bool
}
// Append consumes one StreamResponse event. Safe to call multiple times;
// idempotent post-Done so callers do not need to special-case late events.
func (a *Accumulator) Append(r *sdk.StreamResponse) {
if r == nil || a.finished {
return
}
if r.Content != "" {
a.builder.WriteString(r.Content)
}
if r.SessionID != "" && a.SessionID == "" {
a.SessionID = r.SessionID
}
if r.AssistantMessageID != "" && a.AssistantMessageID == "" {
a.AssistantMessageID = r.AssistantMessageID
}
if r.Done {
// Terminal events carry References; capture once.
if r.KnowledgeReferences != nil {
a.References = r.KnowledgeReferences
}
a.finished = true
}
}
// Done reports whether a terminal event was observed.
func (a *Accumulator) Done() bool { return a.finished }
// Result returns the concatenated content string.
func (a *Accumulator) Result() string { return a.builder.String() }
+90
View File
@@ -0,0 +1,90 @@
package sse_test
import (
"testing"
"github.com/Tencent/WeKnora/cli/internal/sse"
sdk "github.com/Tencent/WeKnora/client"
)
func TestAccumulator_AppendsContent(t *testing.T) {
a := &sse.Accumulator{}
a.Append(&sdk.StreamResponse{Content: "Hello "})
a.Append(&sdk.StreamResponse{Content: "world"})
if got := a.Result(); got != "Hello world" {
t.Errorf("got %q, want %q", got, "Hello world")
}
if a.Done() {
t.Error("expected Done=false before terminal event")
}
}
func TestAccumulator_FinalizesOnDone(t *testing.T) {
a := &sse.Accumulator{}
a.Append(&sdk.StreamResponse{Content: "answer"})
a.Append(&sdk.StreamResponse{
Done: true,
KnowledgeReferences: []*sdk.SearchResult{{KnowledgeID: "k1"}},
})
if !a.Done() {
t.Error("expected Done=true")
}
if len(a.References) != 1 {
t.Errorf("expected 1 reference, got %d", len(a.References))
}
if a.References[0].KnowledgeID != "k1" {
t.Errorf("references payload not preserved: %+v", a.References[0])
}
}
func TestAccumulator_IgnoresPostDone(t *testing.T) {
a := &sse.Accumulator{}
a.Append(&sdk.StreamResponse{Content: "first"})
a.Append(&sdk.StreamResponse{Done: true})
a.Append(&sdk.StreamResponse{Content: "after"})
if got := a.Result(); got != "first" {
t.Errorf("post-Done append should be no-op, got %q", got)
}
}
func TestAccumulator_NilSafe(t *testing.T) {
a := &sse.Accumulator{}
a.Append(nil)
if got := a.Result(); got != "" {
t.Errorf("expected empty result for nil append, got %q", got)
}
if a.Done() {
t.Error("nil append must not finalize")
}
}
func TestAccumulator_CapturesSessionMetadata(t *testing.T) {
a := &sse.Accumulator{}
a.Append(&sdk.StreamResponse{
SessionID: "sess_123",
AssistantMessageID: "msg_456",
Content: "hi",
})
a.Append(&sdk.StreamResponse{Done: true})
if a.SessionID != "sess_123" {
t.Errorf("SessionID: got %q", a.SessionID)
}
if a.AssistantMessageID != "msg_456" {
t.Errorf("AssistantMessageID: got %q", a.AssistantMessageID)
}
}
func TestAccumulator_FirstSessionMetadataWins(t *testing.T) {
// Subsequent events must not overwrite the first non-empty value — the
// session id is set once at session start and any later override would be
// a server bug we should not silently mask.
a := &sse.Accumulator{}
a.Append(&sdk.StreamResponse{SessionID: "sess_first", AssistantMessageID: "msg_first"})
a.Append(&sdk.StreamResponse{SessionID: "sess_second", AssistantMessageID: "msg_second"})
if a.SessionID != "sess_first" {
t.Errorf("SessionID overwritten: got %q want sess_first", a.SessionID)
}
if a.AssistantMessageID != "msg_first" {
t.Errorf("AssistantMessageID overwritten: got %q want msg_first", a.AssistantMessageID)
}
}