feat(cli): --json field-select, --jq, auth token, doc --from-url

Output ergonomics:
- `--json` accepts a comma-separated field list (gh-parity); selects
  named keys from the per-command payload. Bare `--json` keeps the
  full shape.
- `--jq <expr>` evaluates a gojq expression over the JSON; pairs with
  `--json field-list` so projection runs before jq.
- `--version` is a global cobra flag in addition to the `version`
  subcommand; both render the same line.
- Per-command `--help` now renders the available JSON field list under
  "JSON fields available via `--json id,name,...`" (field-discovery
  parity with gh / kubectl `-o jsonpath`).

New commands:
- `auth token` — print the active context's credential to stdout for
  shell command substitution (`WEKNORA_TOKEN=$(weknora auth token)`).
  Default: raw secret, no trailing newline. `--json` emits
  `{token, mode, context}`.
- `doc upload --from-url <URL>` — ingest a remote URL via the SDK
  `CreateKnowledgeFromURL`. `--name` forwarded as `FileName` so the
  server's known-extension heuristic upgrades crawl-mode to
  file-download-mode where appropriate.

Includes the simplify post-review polish pass (field-filter unit
tests, --json/--jq compose check, agent_help copy fixes).
This commit is contained in:
nullkey
2026-05-14 23:28:14 +08:00
committed by lyingbug
parent 4fb089d4d7
commit 1b20b06f5e
81 changed files with 2351 additions and 642 deletions
+37 -22
View File
@@ -36,12 +36,17 @@ import (
sdk "github.com/Tencent/WeKnora/client"
)
// chatFields enumerates the fields surfaced for `--json` discovery on `chat`.
// Mirrors the chatData struct json tags.
var chatFields = []string{
"answer", "references", "session_id", "assistant_message_id", "kb_id", "query",
}
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
@@ -56,12 +61,12 @@ type chatService interface {
// continue a conversation: the answer text, retrieval references, and the
// session pointer to thread follow-ups.
type chatData struct {
Answer string `json:"answer"`
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"`
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>`.
@@ -72,20 +77,24 @@ func NewCmd(f *cmdutil.Factory) *cobra.Command {
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.
--session 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 a32a63ff-fb36-4874-bcaa-30f48570a694
weknora chat "Summarise this design doc" --kb my-kb --json
weknora chat "Continue?" --session-id sess_abc`,
weknora chat "Continue?" --session 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")
}
jopts, err := cmdutil.CheckJSONFlags(c)
if err != nil {
return err
}
kbID, err := f.ResolveKB(c)
if err != nil {
return err
@@ -95,20 +104,20 @@ Modes:
if err != nil {
return err
}
return runChat(c.Context(), opts, cli)
return runChat(c.Context(), opts, jopts, cli)
},
}
cmd.Flags().String("kb", "", "Knowledge base UUID or name (overrides project link / env)")
cmd.Flags().StringVar(&opts.SessionID, "session-id", "", "Continue an existing chat session (skip auto-create)")
cmd.Flags().StringVar(&opts.SessionID, "session", "", "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)")
agent.SetAgentHelp(cmd, "Streams an LLM answer over SSE. Agent / non-TTY callers should pass --json so the full {answer, references, session_id, assistant_message_id} envelope is emitted at completion (no partial chunks). Pass --session-id to thread follow-ups. Errors: server.session_create_failed when auto-create fails; local.sse_stream_aborted on mid-stream disconnect.")
cmdutil.AddJSONFlags(cmd, chatFields)
agent.SetAgentHelp(cmd, "Streams an LLM answer over SSE. Agent / non-TTY callers should pass --json so the full {answer, references, session_id, assistant_message_id} envelope is emitted at completion (no partial chunks). Pass --session to thread follow-ups. Errors: server.session_create_failed when auto-create fails; local.sse_stream_aborted on mid-stream disconnect.")
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 {
func runChat(ctx context.Context, opts *Options, jopts *cmdutil.JSONOptions, svc chatService) error {
if opts.Query == "" {
return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, "query argument cannot be empty")
}
@@ -121,6 +130,8 @@ func runChat(ctx context.Context, opts *Options, svc chatService) error {
return cmdutil.NewError(cmdutil.CodeServerError, "chat: no SDK client available")
}
jsonOut := jopts.Enabled()
sessionID := opts.SessionID
autoCreated := false
if sessionID == "" {
@@ -142,14 +153,14 @@ func runChat(ctx context.Context, opts *Options, svc chatService) error {
// 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
streamMode := iostreams.IO.IsStdoutTTY() && !opts.NoStream && !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)
// when the caller already supplied --session.
if autoCreated && !jsonOut {
fmt.Fprintf(iostreams.IO.Err, "session: %s (use --session to continue)\n", sessionID)
}
req := &sdk.KnowledgeQARequest{
@@ -176,10 +187,10 @@ func runChat(ctx context.Context, opts *Options, svc chatService) error {
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.
// tokens, especially on ^C) can still recover with --session.
// 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)
if autoCreated && !jsonOut {
fmt.Fprintf(iostreams.IO.Err, "session: %s (resume with --session %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) {
@@ -209,7 +220,7 @@ func runChat(ctx context.Context, opts *Options, svc chatService) error {
answer := acc.Result()
references := acc.References
if opts.JSONOut {
if 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
@@ -224,7 +235,11 @@ func runChat(ctx context.Context, opts *Options, svc chatService) error {
KBID: opts.KBID,
Query: opts.Query,
}
return cmdutil.NewJSONExporter().Write(iostreams.IO.Out, format.Success(data, &format.Meta{KBID: opts.KBID}))
return format.WriteEnvelopeFiltered(
iostreams.IO.Out,
format.Success(data, &format.Meta{KBID: opts.KBID}),
jopts.Fields, jopts.JQ,
)
}
// Human / non-JSON paths: streaming mode already wrote the answer body
+15 -15
View File
@@ -73,7 +73,7 @@ func TestChat_StreamMode(t *testing.T) {
},
}
opts := &Options{Query: "hi", KBID: "kb_1"}
if err := runChat(context.Background(), opts, svc); err != nil {
if err := runChat(context.Background(), opts, nil, svc); err != nil {
t.Fatalf("runChat: %v", err)
}
got := out.String()
@@ -111,8 +111,8 @@ func TestChat_JSONMode(t *testing.T) {
{ResponseType: sdk.ResponseTypeComplete, Done: true},
},
}
opts := &Options{Query: "q", KBID: "kb_42", JSONOut: true}
if err := runChat(context.Background(), opts, svc); err != nil {
opts := &Options{Query: "q", KBID: "kb_42"}
if err := runChat(context.Background(), opts, &cmdutil.JSONOptions{}, svc); err != nil {
t.Fatalf("runChat: %v", err)
}
@@ -174,7 +174,7 @@ func TestChat_NoStreamFlag(t *testing.T) {
},
}
opts := &Options{Query: "q", KBID: "kb", NoStream: true}
if err := runChat(context.Background(), opts, svc); err != nil {
if err := runChat(context.Background(), opts, nil, svc); err != nil {
t.Fatalf("runChat: %v", err)
}
written = out.String()
@@ -193,7 +193,7 @@ func TestChat_NonTTY_AccumulateMode(t *testing.T) {
},
}
opts := &Options{Query: "q", KBID: "kb"}
if err := runChat(context.Background(), opts, svc); err != nil {
if err := runChat(context.Background(), opts, nil, svc); err != nil {
t.Fatalf("runChat: %v", err)
}
if !strings.Contains(out.String(), "piped") {
@@ -207,18 +207,18 @@ func TestChat_SessionIDProvided(t *testing.T) {
streamEvents: []*sdk.StreamResponse{{ResponseType: sdk.ResponseTypeComplete, Done: true}},
}
opts := &Options{Query: "q", KBID: "kb", SessionID: "sess_existing"}
if err := runChat(context.Background(), opts, svc); err != nil {
if err := runChat(context.Background(), opts, nil, svc); err != nil {
t.Fatalf("runChat: %v", err)
}
if svc.createCalled {
t.Error("CreateSession must NOT be invoked when --session-id is provided")
t.Error("CreateSession must NOT be invoked when --session 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())
t.Errorf("unexpected session hint emitted with explicit --session: %q", errBuf.String())
}
}
@@ -227,7 +227,7 @@ func TestChat_KBIDRequired(t *testing.T) {
svc := &fakeChatService{}
// Run with KBID empty (bypassing the cobra resolver).
opts := &Options{Query: "q"}
err := runChat(context.Background(), opts, svc)
err := runChat(context.Background(), opts, nil, svc)
if err == nil {
t.Fatal("expected error, got nil")
}
@@ -247,7 +247,7 @@ func TestChat_EmptyQuery(t *testing.T) {
_, _ = iostreams.SetForTest(t)
svc := &fakeChatService{}
opts := &Options{Query: "", KBID: "kb"}
err := runChat(context.Background(), opts, svc)
err := runChat(context.Background(), opts, nil, svc)
if err == nil {
t.Fatal("expected error, got nil")
}
@@ -268,7 +268,7 @@ func TestChat_SDKError_PreStream(t *testing.T) {
streamErr: errors.New("HTTP error 401: token rejected"),
}
opts := &Options{Query: "q", KBID: "kb"}
err := runChat(context.Background(), opts, svc)
err := runChat(context.Background(), opts, nil, svc)
if err == nil {
t.Fatal("expected error, got nil")
}
@@ -290,7 +290,7 @@ func TestChat_SDKError_MidStream_AbortsAsSSE(t *testing.T) {
streamErr: errors.New("connection reset"),
}
opts := &Options{Query: "q", KBID: "kb"}
err := runChat(context.Background(), opts, svc)
err := runChat(context.Background(), opts, nil, svc)
if err == nil {
t.Fatal("expected error, got nil")
}
@@ -309,7 +309,7 @@ func TestChat_ContextCancelled(t *testing.T) {
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)
err := runChat(ctx, opts, nil, svc)
if err == nil {
t.Fatal("expected error, got nil")
}
@@ -328,7 +328,7 @@ func TestChat_SessionCreateFails(t *testing.T) {
createSessionErr: errors.New("dial tcp: connection refused"),
}
opts := &Options{Query: "q", KBID: "kb"}
err := runChat(context.Background(), opts, svc)
err := runChat(context.Background(), opts, nil, svc)
if err == nil {
t.Fatal("expected error, got nil")
}
@@ -353,7 +353,7 @@ func TestChat_SessionCreate404SurfacesNotFound(t *testing.T) {
createSessionErr: errors.New("HTTP error 404: tenant not found"),
}
opts := &Options{Query: "q", KBID: "kb"}
err := runChat(context.Background(), opts, svc)
err := runChat(context.Background(), opts, nil, svc)
if err == nil {
t.Fatal("expected error, got nil")
}