feat(cli)!: add agent-first chat and session ask output modes
This commit is contained in:
+13
-7
@@ -77,11 +77,15 @@ token (emitting as a JSON array is planned for v0.8).
|
||||
`detail` carries structured per-error context (e.g. `unknown_subcommand`'s
|
||||
`available[]` list).
|
||||
|
||||
### NDJSON event stream (chat / session ask)
|
||||
### Buffered JSON and NDJSON streams (chat / session ask)
|
||||
|
||||
`--format json` and `--format ndjson` both produce one JSON event per line —
|
||||
no envelope wrapping. The CLI injects exactly one event (`init`) at the head;
|
||||
all subsequent events pass through verbatim from the SDK:
|
||||
`--format json` (the default) buffers the SSE stream and emits one normal
|
||||
success envelope whose `data.events` contains answer events by default.
|
||||
`--reference` adds `kb_id` / `chunk_id` / `parent_chunk_id` indexes;
|
||||
`--verbose` adds reasoning, tool, metadata, and lifecycle events. `--format
|
||||
text` renders the same projection live.
|
||||
`--format ndjson` is the raw event/debug surface: the CLI injects exactly one
|
||||
`init` event at the head and passes all subsequent SDK events through verbatim:
|
||||
|
||||
```
|
||||
{"type":"init","session_id":"...","kb_id":"...","profile":"...","agent_id":"..."}
|
||||
@@ -91,7 +95,9 @@ all subsequent events pass through verbatim from the SDK:
|
||||
{"type":"complete","done":true}
|
||||
```
|
||||
|
||||
For prose rendering, pass `--format text`.
|
||||
MCP `chat` / `session_ask` return the same `events` shape and accept
|
||||
`reference` / `verbose` booleans. NDJSON ignores both presentation flags and
|
||||
always stays raw.
|
||||
|
||||
### `_notice` evolution policy
|
||||
|
||||
@@ -170,8 +176,8 @@ is or isn't aligned with.
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **WeKnora** | streaming commands (`chat`, `session ask`) emit bare `{type:...}` per line; no envelope |
|
||||
| **Rationale** | This matches established practice across NDJSON-emitting CLIs and webhook protocols. A streaming envelope requires unwrap before dispatch — net burden with no benefit. |
|
||||
| **WeKnora** | `chat` / `session ask --format ndjson` emit bare `{type:...}` per line; default JSON buffers a bounded answer-event projection into one envelope |
|
||||
| **Rationale** | This matches established practice across NDJSON-emitting CLIs and webhook protocols. Each complete line can be decoded and dispatched as it arrives; the buffered envelope is reserved for normal JSON mode. |
|
||||
|
||||
### 5. No `schema_version` field in payload
|
||||
|
||||
|
||||
+25
-1
@@ -12,6 +12,29 @@ CLI history before v0.3 is recorded in the project root
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
### Breaking
|
||||
- `chat` and `session ask` now distinguish JSON from NDJSON: the default
|
||||
`--format json` buffers a bounded answer-event projection into one
|
||||
`{ok:true,data:{events:[...]}}` envelope; use `--format ndjson` for the
|
||||
complete raw event stream.
|
||||
- JSON, text, and MCP chat/session output hide reasoning, tools, lifecycle
|
||||
frames, and references by default. `--reference` adds bounded `kb_id` /
|
||||
`chunk_id` / `parent_chunk_id` indexes; `--verbose` adds execution events.
|
||||
|
||||
### Added
|
||||
- `chat` / `session ask --reference` includes indexed citations, while
|
||||
`--verbose` includes reasoning, tools, and lifecycle events. MCP `chat` /
|
||||
`session_ask` expose the same controls through `reference` / `verbose` inputs.
|
||||
- Buffered chat/session errors include the auto-created `session_id` in
|
||||
`error.detail` so interrupted sessions remain recoverable.
|
||||
|
||||
### Changed
|
||||
- JSON, text, and MCP now share one event projector and filtering policy.
|
||||
- Projected references contain lookup indexes only; fetch full
|
||||
passages with `chunk view <chunk_id>` or `chunk view <parent_chunk_id>`.
|
||||
- NDJSON remains an unmodified SDK event trace, including reasoning and full
|
||||
reference payloads.
|
||||
|
||||
### Fixed
|
||||
- Streaming SDK calls are no longer cut off by the client's default 30-second
|
||||
timeout (explicit `WithTimeout` values remain honored), and SSE data lines
|
||||
@@ -20,7 +43,8 @@ CLI history before v0.3 is recorded in the project root
|
||||
even when the server leaves the HTTP connection open.
|
||||
- Agent accumulation now waits for `response_type=complete` instead of treating
|
||||
per-event `done:true` markers as completion of the whole run.
|
||||
- Reference `parent_chunk_id` / `sub_chunk_id` fields now survive SDK unmarshal.
|
||||
- Reference `knowledge_base_id`, `parent_chunk_id`, and `sub_chunk_id` fields
|
||||
now survive SDK unmarshal.
|
||||
|
||||
## [0.9.0] - 2026-06-10
|
||||
|
||||
|
||||
+4
-2
@@ -252,8 +252,10 @@ is the guard against unintended writes.
|
||||
|
||||
### Other AI-agent ergonomics
|
||||
|
||||
- For chat / session ask in AI-agent contexts, pass `--format json` —
|
||||
streaming tokens to stdout makes JSON parsing impossible.
|
||||
- For chat / session ask in AI-agent contexts, pass `--format json` for a
|
||||
bounded answer-event envelope. Add `--reference` for indexed citations,
|
||||
`--verbose` for reasoning/tools/lifecycle events, or `--format ndjson` for
|
||||
the unmodified raw stream.
|
||||
- `--format json` composes with the global `--profile <name>` for
|
||||
single-shot profile overrides without disk writes.
|
||||
- `weknora mcp serve` exposes a curated read-only tool surface over
|
||||
|
||||
+135
-71
@@ -1,21 +1,22 @@
|
||||
// Package chat implements `weknora chat <text>` - the streaming RAG answer
|
||||
// entry point.
|
||||
//
|
||||
// Two output modes share a single SDK call:
|
||||
// Three output modes share a single SDK call:
|
||||
//
|
||||
// - Stream mode (TTY + --format text): 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.
|
||||
// - JSON mode (--format json, the default): buffer a bounded projection of
|
||||
// the stream into one success envelope. The default projection contains
|
||||
// answer events only; --reference adds indexed citations and --verbose
|
||||
// adds reasoning, tools, and lifecycle frames.
|
||||
//
|
||||
// - NDJSON mode (--format json / --format ndjson / pipe): inject a CLI
|
||||
// "init" event at stream head, then pass through every SDK event verbatim
|
||||
// as NDJSON lines. Agents and pipes get a live event stream they can
|
||||
// parse incrementally. --format json routes here too — buffered JSON
|
||||
// envelope makes no sense for a streaming command.
|
||||
// - Text mode (--format text): render the same projection as JSON
|
||||
// directly to iostreams.IO.Out as it arrives.
|
||||
//
|
||||
// - NDJSON mode (--format ndjson): inject a CLI "init" event at stream
|
||||
// head, then pass through every SDK event verbatim as NDJSON lines —
|
||||
// the raw protocol trace, for debugging / advanced consumers.
|
||||
//
|
||||
// The SDK's KnowledgeQAStream callback contract is invoked sequentially on
|
||||
// one goroutine, so neither mode needs locking. The runChat core takes a
|
||||
// one goroutine, so no mode needs locking. The runChat core takes a
|
||||
// ChatService interface so tests inject a fake without standing up a real
|
||||
// SSE server.
|
||||
package chat
|
||||
@@ -28,26 +29,31 @@ import (
|
||||
"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/output"
|
||||
"github.com/Tencent/WeKnora/cli/internal/sse"
|
||||
sdk "github.com/Tencent/WeKnora/client"
|
||||
)
|
||||
|
||||
// chatFields enumerates the NDJSON init-event fields surfaced for
|
||||
// `--format json` / `--format ndjson` discovery on `chat`. Reflects the
|
||||
// InitEvent head line + the raw SDK event vocabulary.
|
||||
// chatFields enumerates the fields surfaced for `--jq` projection discovery
|
||||
// on `chat`: the json object's data fields + the raw SDK event vocabulary
|
||||
// used by --format ndjson.
|
||||
var chatFields = []string{
|
||||
"session_id", "kb_id",
|
||||
// SDK event fields (pass-through): response_type, content, done,
|
||||
// knowledge_references, assistant_message_id, session_id
|
||||
"events", "session_id", "assistant_message_id", "kb_id", "query",
|
||||
// NDJSON init + SDK event fields.
|
||||
"type", "kb_id", "profile", "response_type", "content", "done", "knowledge_references", "data",
|
||||
}
|
||||
|
||||
type Options struct {
|
||||
Query string
|
||||
KBID string
|
||||
SessionID string
|
||||
// Reference adds bounded kb_id/chunk_id reference events to JSON/text.
|
||||
Reference bool
|
||||
// Verbose surfaces the projected execution trace in JSON/text,
|
||||
// including reasoning, tools, and lifecycle events.
|
||||
// NDJSON is always raw and is unaffected by presentation flags.
|
||||
Verbose bool
|
||||
}
|
||||
|
||||
// ChatService is the narrow SDK surface this command depends on. *sdk.Client
|
||||
@@ -69,12 +75,14 @@ answer back. By default a fresh session is created on first invocation; pass
|
||||
--session to continue an existing conversation.
|
||||
|
||||
Modes:
|
||||
--format text: live token streaming + reference footer
|
||||
--format json / --format ndjson / pipe (default): NDJSON event stream —
|
||||
one init line at head (session_id, kb_id),
|
||||
then raw SDK events verbatim. Both json
|
||||
and ndjson flags produce the same NDJSON
|
||||
stream.`,
|
||||
--format json (default): one JSON envelope with answer events
|
||||
--format text: live human-readable answer stream
|
||||
--format ndjson: raw NDJSON event stream — init line (session_id,
|
||||
kb_id) then SDK events verbatim. Debug / advanced.
|
||||
|
||||
Pass --reference to include bounded kb_id/chunk_id reference indexes. Pass
|
||||
--verbose to include reasoning, tool activity, and lifecycle frames. Combine
|
||||
both flags for the complete projected stream.`,
|
||||
Example: ` weknora chat "What is RRF?" --kb a32a63ff-fb36-4874-bcaa-30f48570a694
|
||||
weknora chat "Summarise this design doc" --kb my-kb --format json
|
||||
weknora chat "Continue?" --session sess_abc`,
|
||||
@@ -103,12 +111,17 @@ Modes:
|
||||
}
|
||||
cmdutil.AddKBFlag(cmd)
|
||||
cmd.Flags().StringVar(&opts.SessionID, "session", "", "Continue an existing chat session (skip auto-create)")
|
||||
cmd.Flags().BoolVar(&opts.Reference, "reference", false, "Include indexed references in JSON/text output")
|
||||
cmd.Flags().BoolVar(&opts.Verbose, "verbose", false, "Include reasoning, tools, and lifecycle events in JSON/text output")
|
||||
cmdutil.AddFormatFlag(cmd, chatFields...)
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "Ask a streaming RAG question against a knowledge base. Produces an NDJSON event stream: init line (session_id, kb_id) then raw SDK events. Use --format json or --format ndjson.",
|
||||
UsedFor: "Ask a RAG question against a knowledge base. Default JSON returns a bounded answer-event projection. --reference adds indexed citations; --verbose adds reasoning, tools, and lifecycle events. --format ndjson streams raw SDK events; --format text renders the selected events live.",
|
||||
RequiredFlags: []string{"--kb"},
|
||||
Examples: []string{`weknora chat "What is RRF?" --kb kb_abc --format json`},
|
||||
Output: "NDJSON stream: {type:init, session_id, kb_id} then SDK events (response_type, content, done, knowledge_references, ...)",
|
||||
Examples: []string{
|
||||
`weknora chat "What is RRF?" --kb kb_abc`,
|
||||
`weknora chat "What is RRF?" --kb kb_abc --jq '[.data.events[].content] | join("")'`,
|
||||
},
|
||||
Output: "Default --format json: {ok,data:{events:[answer...],session_id,kb_id,query}}. --reference adds kb_id/chunk_id reference events; --verbose adds execution events. --format ndjson remains raw.",
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
@@ -128,11 +141,8 @@ func runChat(ctx context.Context, opts *Options, fopts *cmdutil.FormatOptions, s
|
||||
return cmdutil.NewError(cmdutil.CodeServerError, "chat: no SDK client available")
|
||||
}
|
||||
|
||||
// Streaming commands route --format json AND --format ndjson to the
|
||||
// NDJSON event-stream path. A buffered envelope makes no sense for a
|
||||
// streaming command. Only --format text uses the live renderer.
|
||||
ndjsonMode := fopts != nil && (fopts.Mode == cmdutil.FormatJSON || fopts.Mode == cmdutil.FormatNDJSON)
|
||||
|
||||
// --format selects the output shape: json (default) accumulates and
|
||||
// emits one object, ndjson streams raw SDK events, text renders live.
|
||||
sessionID := opts.SessionID
|
||||
autoCreated := false
|
||||
if sessionID == "" {
|
||||
@@ -156,13 +166,16 @@ func runChat(ctx context.Context, opts *Options, fopts *cmdutil.FormatOptions, s
|
||||
autoCreated = true
|
||||
}
|
||||
|
||||
if ndjsonMode {
|
||||
if fopts != nil && fopts.Mode == cmdutil.FormatNDJSON {
|
||||
return runChatNDJSON(ctx, opts, sessionID, svc)
|
||||
}
|
||||
if fopts != nil && fopts.Mode == cmdutil.FormatJSON {
|
||||
return runChatJSON(ctx, opts, fopts, sessionID, svc)
|
||||
}
|
||||
|
||||
// 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 NDJSON mode (it appears in the init event).
|
||||
// past tokens. Skipped in json/ndjson mode (session_id is in the output).
|
||||
if autoCreated {
|
||||
fmt.Fprintf(iostreams.IO.Err, "session: %s (use --session to continue)\n", sessionID)
|
||||
}
|
||||
@@ -170,10 +183,9 @@ func runChat(ctx context.Context, opts *Options, fopts *cmdutil.FormatOptions, s
|
||||
return runChatText(ctx, opts, sessionID, autoCreated, svc)
|
||||
}
|
||||
|
||||
// runChatNDJSON handles --format json and --format ndjson paths.
|
||||
// Emits a CLI init event at stream head, then passes every SDK event through
|
||||
// verbatim as NDJSON lines. No buffering — callers parse the stream
|
||||
// incrementally.
|
||||
// runChatNDJSON handles the --format ndjson path: emits a CLI init event at
|
||||
// stream head, then passes every SDK event through verbatim as NDJSON lines.
|
||||
// No buffering — callers parse the stream incrementally.
|
||||
func runChatNDJSON(ctx context.Context, opts *Options, sessionID string, svc ChatService) error {
|
||||
w := iostreams.IO.Out
|
||||
|
||||
@@ -198,6 +210,8 @@ func runChatNDJSON(ctx context.Context, opts *Options, sessionID string, svc Cha
|
||||
Channel: "api",
|
||||
}
|
||||
cb := func(r *sdk.StreamResponse) error {
|
||||
// NDJSON is the raw protocol/debug surface: do not filter events or
|
||||
// mutate their payloads. JSON/text modes own presentation filtering.
|
||||
return output.EmitSDKEvent(w, r)
|
||||
}
|
||||
if err := svc.KnowledgeQAStream(ctx, sessionID, req, cb); err != nil {
|
||||
@@ -209,12 +223,9 @@ func runChatNDJSON(ctx context.Context, opts *Options, sessionID string, svc Cha
|
||||
return nil
|
||||
}
|
||||
|
||||
// runChatText handles the --format text path. Streams content fragments
|
||||
// live on TTY; accumulates then renders on non-TTY pipes.
|
||||
// runChatText handles the --format text path. It renders the same
|
||||
// projection as JSON immediately for both terminals and pipes.
|
||||
func runChatText(ctx context.Context, opts *Options, sessionID string, autoCreated bool, svc ChatService) error {
|
||||
// Stream mode requires an interactive stdout.
|
||||
streamMode := iostreams.IO.IsStdoutTTY()
|
||||
|
||||
req := &sdk.KnowledgeQARequest{
|
||||
Query: opts.Query,
|
||||
KnowledgeBaseIDs: []string{opts.KBID},
|
||||
@@ -223,16 +234,15 @@ func runChatText(ctx context.Context, opts *Options, sessionID string, autoCreat
|
||||
Channel: "api",
|
||||
}
|
||||
|
||||
acc := &sse.Accumulator{}
|
||||
projector := sse.NewProjector(opts.Verbose, opts.Reference, opts.KBID)
|
||||
renderer := sse.NewTextRenderer(iostreams.IO.Out, opts.Verbose)
|
||||
|
||||
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))
|
||||
event, include := projector.Chat(r)
|
||||
if !include {
|
||||
return nil
|
||||
}
|
||||
acc.Append(r)
|
||||
return nil
|
||||
return renderer.Write(event)
|
||||
}
|
||||
|
||||
streamErr := svc.KnowledgeQAStream(ctx, sessionID, req, cb)
|
||||
@@ -250,7 +260,7 @@ func runChatText(ctx context.Context, opts *Options, sessionID string, autoCreat
|
||||
// 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 a retry.
|
||||
if acc.Result() != "" && !acc.Done() {
|
||||
if projector.Seen() && !projector.Done() {
|
||||
return cmdutil.Wrapf(cmdutil.CodeSSEStreamAborted, streamErr, "stream aborted before completion")
|
||||
}
|
||||
// Pre-stream HTTP / transport failure: route through the canonical
|
||||
@@ -264,30 +274,84 @@ func runChatText(ctx context.Context, opts *Options, sessionID string, autoCreat
|
||||
// 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() {
|
||||
if !projector.Done() {
|
||||
return cmdutil.NewError(cmdutil.CodeSSEStreamAborted, "stream ended without a terminal event")
|
||||
}
|
||||
return renderer.Close()
|
||||
}
|
||||
|
||||
answer := acc.Result()
|
||||
references := acc.References
|
||||
|
||||
// Streaming mode already wrote the answer body via the callback, so we
|
||||
// only need to render the trailing references (and a closing newline).
|
||||
// Non-TTY accumulate path 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)
|
||||
}
|
||||
// runChatJSON handles the --format json path (the default): collect the
|
||||
// projection and emit it in one normal success envelope.
|
||||
func runChatJSON(ctx context.Context, opts *Options, fopts *cmdutil.FormatOptions, sessionID string, svc ChatService) error {
|
||||
req := &sdk.KnowledgeQARequest{
|
||||
Query: opts.Query,
|
||||
KnowledgeBaseIDs: []string{opts.KBID},
|
||||
AgentEnabled: false,
|
||||
WebSearchEnabled: false,
|
||||
Channel: "api",
|
||||
}
|
||||
format.WriteReferences(out, references)
|
||||
return nil
|
||||
|
||||
projector := sse.NewProjector(opts.Verbose, opts.Reference, opts.KBID)
|
||||
events := make([]sse.ProjectedEvent, 0)
|
||||
cb := func(r *sdk.StreamResponse) error {
|
||||
if event, include := projector.Chat(r); include {
|
||||
events = append(events, event)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
if err := svc.KnowledgeQAStream(ctx, sessionID, req, cb); err != nil {
|
||||
if cmdutil.IsCancelled(ctx, err) {
|
||||
return chatStreamError(cmdutil.Wrapf(cmdutil.CodeOperationCancelled, err, "chat cancelled"), sessionID, projector.AssistantMessageID())
|
||||
}
|
||||
return chatStreamError(cmdutil.WrapHTTP(err, "knowledge qa stream"), sessionID, projector.AssistantMessageID())
|
||||
}
|
||||
if !projector.Done() {
|
||||
return chatStreamError(
|
||||
cmdutil.NewError(cmdutil.CodeSSEStreamAborted, "stream ended without a terminal event"),
|
||||
sessionID,
|
||||
projector.AssistantMessageID(),
|
||||
)
|
||||
}
|
||||
|
||||
sid := projector.SessionID()
|
||||
if sid == "" {
|
||||
sid = sessionID
|
||||
}
|
||||
data := chatResult{
|
||||
Events: events,
|
||||
SessionID: sid,
|
||||
AssistantMessageID: projector.AssistantMessageID(),
|
||||
KBID: opts.KBID,
|
||||
Query: opts.Query,
|
||||
}
|
||||
|
||||
// Reaching here means fopts.Mode is FormatJSON (the only caller). Route
|
||||
// through FormatOptions.Emit so --jq projection and the success-envelope
|
||||
// contract apply, matching every other non-streaming command. A nil fopts
|
||||
// (direct-test entry) defaults to JSON so the object still emits.
|
||||
if fopts == nil {
|
||||
fopts = &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}
|
||||
}
|
||||
return fopts.Emit(iostreams.IO.Out, data, nil)
|
||||
}
|
||||
|
||||
func chatStreamError(err *cmdutil.Error, sessionID, assistantMessageID string) *cmdutil.Error {
|
||||
detail := map[string]any{"session_id": sessionID}
|
||||
if assistantMessageID != "" {
|
||||
detail["assistant_message_id"] = assistantMessageID
|
||||
}
|
||||
return err.WithDetail(detail)
|
||||
}
|
||||
|
||||
// chatResult is the --format json data payload. The projector controls default
|
||||
// versus verbose coverage.
|
||||
type chatResult struct {
|
||||
Events []sse.ProjectedEvent `json:"events"`
|
||||
SessionID string `json:"session_id"`
|
||||
AssistantMessageID string `json:"assistant_message_id,omitempty"`
|
||||
KBID string `json:"kb_id"`
|
||||
Query string `json:"query"`
|
||||
}
|
||||
|
||||
// compile-time check: the production SDK client implements ChatService.
|
||||
|
||||
+198
-53
@@ -9,6 +9,7 @@ import (
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
||||
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
||||
"github.com/Tencent/WeKnora/cli/internal/sse"
|
||||
sdk "github.com/Tencent/WeKnora/client"
|
||||
)
|
||||
|
||||
@@ -86,11 +87,8 @@ func TestChat_StreamMode(t *testing.T) {
|
||||
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)
|
||||
if strings.Contains(got, "references") || strings.Contains(got, "Doc One") {
|
||||
t.Errorf("default text output leaked references: %q", got)
|
||||
}
|
||||
// auto-created session must announce itself on stderr
|
||||
if !strings.Contains(errBuf.String(), "session: sess_auto") {
|
||||
@@ -107,7 +105,7 @@ func TestChat_StreamMode(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// TestChat_NDJSON_FirstLineIsInit verifies that the NDJSON path (--format json)
|
||||
// TestChat_NDJSON_FirstLineIsInit verifies that the NDJSON path (--format ndjson)
|
||||
// always injects an "init" line first carrying session_id and kb_id.
|
||||
func TestChat_NDJSON_FirstLineIsInit(t *testing.T) {
|
||||
out, errBuf := iostreams.SetForTest(t)
|
||||
@@ -119,7 +117,7 @@ func TestChat_NDJSON_FirstLineIsInit(t *testing.T) {
|
||||
},
|
||||
}
|
||||
opts := &Options{Query: "q", KBID: "kb_42"}
|
||||
fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}
|
||||
fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatNDJSON}
|
||||
if err := runChat(context.Background(), opts, fopts, svc); err != nil {
|
||||
t.Fatalf("runChat: %v", err)
|
||||
}
|
||||
@@ -164,7 +162,7 @@ func TestChat_NDJSON_PassthroughEvents(t *testing.T) {
|
||||
},
|
||||
}
|
||||
opts := &Options{Query: "q", KBID: "kb_x"}
|
||||
fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}
|
||||
fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatNDJSON}
|
||||
if err := runChat(context.Background(), opts, fopts, svc); err != nil {
|
||||
t.Fatalf("runChat: %v", err)
|
||||
}
|
||||
@@ -183,34 +181,7 @@ func TestChat_NDJSON_PassthroughEvents(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// TestChat_NDJSON_JSONEqualsNDJSON verifies that --format json and --format ndjson
|
||||
// produce identical byte output on a streaming command.
|
||||
func TestChat_NDJSON_JSONEqualsNDJSON(t *testing.T) {
|
||||
events := []*sdk.StreamResponse{
|
||||
{ResponseType: sdk.ResponseTypeAnswer, Content: "hello"},
|
||||
{ResponseType: sdk.ResponseTypeComplete, Done: true},
|
||||
}
|
||||
|
||||
runWith := func(mode cmdutil.FormatMode) string {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &fakeChatService{streamEvents: events}
|
||||
opts := &Options{Query: "q", KBID: "kb_x"}
|
||||
fopts := &cmdutil.FormatOptions{Mode: mode}
|
||||
if err := runChat(context.Background(), opts, fopts, svc); err != nil {
|
||||
t.Fatalf("runChat(%s): %v", mode, err)
|
||||
}
|
||||
return out.String()
|
||||
}
|
||||
|
||||
jsonOut := runWith(cmdutil.FormatJSON)
|
||||
ndjsonOut := runWith(cmdutil.FormatNDJSON)
|
||||
if jsonOut != ndjsonOut {
|
||||
t.Errorf("--format json and --format ndjson differ:\n json: %q\n ndjson: %q", jsonOut, ndjsonOut)
|
||||
}
|
||||
}
|
||||
|
||||
func TestChat_NonTTY_AccumulateMode(t *testing.T) {
|
||||
// Non-TTY iostreams forces accumulate mode.
|
||||
func TestChat_NonTTY_StreamsSameProjection(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &fakeChatService{
|
||||
streamEvents: []*sdk.StreamResponse{
|
||||
@@ -227,6 +198,24 @@ func TestChat_NonTTY_AccumulateMode(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
func TestChat_NonTTY_VerboseIncludesThinking(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &fakeChatService{
|
||||
streamEvents: []*sdk.StreamResponse{
|
||||
{ResponseType: sdk.ResponseTypeThinking, Content: "REASONING"},
|
||||
{ResponseType: sdk.ResponseTypeAnswer, Content: "answer"},
|
||||
{ResponseType: sdk.ResponseTypeComplete, Done: true},
|
||||
},
|
||||
}
|
||||
opts := &Options{Query: "q", KBID: "kb", Verbose: true}
|
||||
if err := runChat(context.Background(), opts, textOpts(), svc); err != nil {
|
||||
t.Fatalf("runChat: %v", err)
|
||||
}
|
||||
if got := out.String(); !strings.Contains(got, "REASONING") || !strings.Contains(got, "answer") {
|
||||
t.Errorf("non-TTY verbose output missing thinking or answer: %q", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestChat_SessionIDProvided(t *testing.T) {
|
||||
_, errBuf := iostreams.SetForTestWithTTY(t)
|
||||
svc := &fakeChatService{
|
||||
@@ -430,8 +419,8 @@ func TestChat_NDJSON_InitIncludesProfile(t *testing.T) {
|
||||
}
|
||||
|
||||
func TestChat_FormatNDJSON_PassthroughsSDKEvents(t *testing.T) {
|
||||
// Fake stream emits 3 events: thinking, answer, complete.
|
||||
// With the init injection, total output is 4 lines (1 init + 3 SDK events).
|
||||
// NDJSON is the raw protocol surface: every SDK event passes through,
|
||||
// including reasoning, regardless of the presentation-oriented --verbose.
|
||||
svc := &fakeChatService{
|
||||
streamEvents: []*sdk.StreamResponse{
|
||||
{ResponseType: sdk.ResponseTypeThinking, Content: "search KB"},
|
||||
@@ -447,11 +436,23 @@ func TestChat_FormatNDJSON_PassthroughsSDKEvents(t *testing.T) {
|
||||
t.Fatalf("runChat: %v", err)
|
||||
}
|
||||
lines := strings.Split(strings.TrimRight(out.String(), "\n"), "\n")
|
||||
// 1 init + 3 SDK events = 4 lines.
|
||||
// 1 init + thinking + answer + complete = 4 lines.
|
||||
if len(lines) != 4 {
|
||||
t.Fatalf("got %d lines, want 4:\n%s", len(lines), out.String())
|
||||
}
|
||||
|
||||
sawThinking := false
|
||||
for i, line := range lines {
|
||||
var ev map[string]any
|
||||
if err := json.Unmarshal([]byte(line), &ev); err != nil {
|
||||
t.Fatalf("line %d not JSON: %v", i+1, err)
|
||||
}
|
||||
if ev["response_type"] == "thinking" {
|
||||
sawThinking = true
|
||||
}
|
||||
}
|
||||
if !sawThinking {
|
||||
t.Error("thinking event was filtered from raw NDJSON output")
|
||||
}
|
||||
// First line: CLI-injected init event.
|
||||
var initLine map[string]any
|
||||
if err := json.Unmarshal([]byte(lines[0]), &initLine); err != nil {
|
||||
@@ -460,8 +461,30 @@ func TestChat_FormatNDJSON_PassthroughsSDKEvents(t *testing.T) {
|
||||
if initLine["type"] != "init" {
|
||||
t.Errorf("first line type=%v, want init", initLine["type"])
|
||||
}
|
||||
}
|
||||
|
||||
// Second line: thinking event (SDK passthrough).
|
||||
func TestChat_FormatNDJSON_VerboseDoesNotAlterRawStream(t *testing.T) {
|
||||
// --verbose is presentation-only; NDJSON remains the same raw stream and
|
||||
// therefore still contains thinking alongside answer + complete.
|
||||
svc := &fakeChatService{
|
||||
streamEvents: []*sdk.StreamResponse{
|
||||
{ResponseType: sdk.ResponseTypeThinking, Content: "search KB"},
|
||||
{ResponseType: sdk.ResponseTypeAnswer, Content: "hello"},
|
||||
{ResponseType: sdk.ResponseTypeComplete, Done: true, SessionID: "sess_x"},
|
||||
},
|
||||
}
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
|
||||
opts := &Options{Query: "hi", KBID: "kb_x", Verbose: true}
|
||||
fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatNDJSON}
|
||||
if err := runChat(context.Background(), opts, fopts, svc); err != nil {
|
||||
t.Fatalf("runChat: %v", err)
|
||||
}
|
||||
lines := strings.Split(strings.TrimRight(out.String(), "\n"), "\n")
|
||||
// 1 init + thinking + answer + complete = 4 lines.
|
||||
if len(lines) != 4 {
|
||||
t.Fatalf("got %d lines, want 4:\n%s", len(lines), out.String())
|
||||
}
|
||||
var second map[string]any
|
||||
if err := json.Unmarshal([]byte(lines[1]), &second); err != nil {
|
||||
t.Fatalf("line 2 not JSON: %v", err)
|
||||
@@ -469,20 +492,142 @@ func TestChat_FormatNDJSON_PassthroughsSDKEvents(t *testing.T) {
|
||||
if second["response_type"] != "thinking" {
|
||||
t.Errorf("second event response_type=%v, want thinking", second["response_type"])
|
||||
}
|
||||
// Third line: answer.
|
||||
var third map[string]any
|
||||
if err := json.Unmarshal([]byte(lines[2]), &third); err != nil {
|
||||
t.Fatalf("line 3 not JSON: %v", err)
|
||||
}
|
||||
|
||||
func TestChat_FormatJSON_ReferenceAddsIndexes(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &fakeChatService{
|
||||
streamEvents: []*sdk.StreamResponse{
|
||||
{ResponseType: sdk.ResponseTypeAnswer, Content: "the answer"},
|
||||
{ResponseType: sdk.ResponseTypeReferences, KnowledgeReferences: []*sdk.SearchResult{
|
||||
{ID: "c1", Content: "BULKY FULL CHUNK CONTENT", ParentChunkID: "p1", KnowledgeTitle: "Doc One", Score: 0.5},
|
||||
}},
|
||||
{ResponseType: sdk.ResponseTypeComplete, Done: true, SessionID: "sess_auto"},
|
||||
},
|
||||
}
|
||||
if third["response_type"] != "answer" {
|
||||
t.Errorf("third event response_type=%v, want answer", third["response_type"])
|
||||
opts := &Options{Query: "hi", KBID: "kb_1", Reference: true}
|
||||
fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}
|
||||
if err := runChat(context.Background(), opts, fopts, svc); err != nil {
|
||||
t.Fatalf("runChat: %v", err)
|
||||
}
|
||||
// Fourth line: complete with done=true.
|
||||
var fourth map[string]any
|
||||
if err := json.Unmarshal([]byte(lines[3]), &fourth); err != nil {
|
||||
t.Fatalf("line 4 not JSON: %v", err)
|
||||
// A single envelope, not multiple NDJSON lines.
|
||||
outStr := strings.TrimRight(out.String(), "\n")
|
||||
if strings.Contains(outStr, "\n") {
|
||||
t.Fatalf("expected single-line envelope, got multiple lines:\n%s", outStr)
|
||||
}
|
||||
if fourth["done"] != true {
|
||||
t.Errorf("fourth event done=%v, want true", fourth["done"])
|
||||
var env struct {
|
||||
OK bool `json:"ok"`
|
||||
Data struct {
|
||||
Events []sse.ProjectedEvent `json:"events"`
|
||||
SessionID string `json:"session_id"`
|
||||
} `json:"data"`
|
||||
}
|
||||
if err := json.Unmarshal([]byte(outStr), &env); err != nil {
|
||||
t.Fatalf("envelope not JSON: %v\n%s", err, outStr)
|
||||
}
|
||||
if !env.OK {
|
||||
t.Error("ok=false, want true")
|
||||
}
|
||||
wantTypes := []string{"answer", "references"}
|
||||
if len(env.Data.Events) != len(wantTypes) {
|
||||
t.Fatalf("events=%+v", env.Data.Events)
|
||||
}
|
||||
for i, want := range wantTypes {
|
||||
if env.Data.Events[i].ResponseType != want {
|
||||
t.Errorf("events[%d].response_type=%q, want %q", i, env.Data.Events[i].ResponseType, want)
|
||||
}
|
||||
}
|
||||
refs := env.Data.Events[1].KnowledgeReferences
|
||||
if len(refs) != 1 || refs[0].KBID != "kb_1" || refs[0].ChunkID != "c1" || refs[0].ParentChunkID != "p1" {
|
||||
t.Errorf("reference indexes=%+v", refs)
|
||||
}
|
||||
if env.Data.SessionID == "" {
|
||||
t.Error("session_id empty")
|
||||
}
|
||||
}
|
||||
|
||||
func TestChat_FormatNDJSON_PreservesReflection(t *testing.T) {
|
||||
// Reflection is part of the raw SDK protocol and must not be filtered.
|
||||
svc := &fakeChatService{
|
||||
streamEvents: []*sdk.StreamResponse{
|
||||
{ResponseType: sdk.ResponseTypeReflection, Content: "reflecting"},
|
||||
{ResponseType: sdk.ResponseTypeAnswer, Content: "hello"},
|
||||
{ResponseType: sdk.ResponseTypeComplete, Done: true, SessionID: "sess_x"},
|
||||
},
|
||||
}
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
|
||||
opts := &Options{Query: "hi", KBID: "kb_x"}
|
||||
fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatNDJSON}
|
||||
if err := runChat(context.Background(), opts, fopts, svc); err != nil {
|
||||
t.Fatalf("runChat: %v", err)
|
||||
}
|
||||
sawReflection := false
|
||||
for i, line := range strings.Split(strings.TrimRight(out.String(), "\n"), "\n") {
|
||||
var ev map[string]any
|
||||
if err := json.Unmarshal([]byte(line), &ev); err != nil {
|
||||
t.Fatalf("line %d not JSON: %v", i+1, err)
|
||||
}
|
||||
if ev["response_type"] == "reflection" {
|
||||
sawReflection = true
|
||||
}
|
||||
}
|
||||
if !sawReflection {
|
||||
t.Error("reflection event was filtered from raw NDJSON output")
|
||||
}
|
||||
}
|
||||
|
||||
func TestChat_FormatJSON_HonorsJQ(t *testing.T) {
|
||||
// --format json routes through FormatOptions.Emit, so --jq projects the
|
||||
// envelope instead of dumping it whole. Guards the agent output protocol
|
||||
// contract: consumers can join answer event fragments.
|
||||
svc := &fakeChatService{
|
||||
streamEvents: []*sdk.StreamResponse{
|
||||
{ResponseType: sdk.ResponseTypeAnswer, Content: "the answer"},
|
||||
{ResponseType: sdk.ResponseTypeReferences, KnowledgeReferences: []*sdk.SearchResult{
|
||||
{ID: "c1", Content: "bulk", KnowledgeTitle: "Doc"},
|
||||
}},
|
||||
{ResponseType: sdk.ResponseTypeComplete, Done: true, SessionID: "sess_x"},
|
||||
},
|
||||
}
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
|
||||
opts := &Options{Query: "hi", KBID: "kb_1"}
|
||||
fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON, JQ: `[.data.events[].content] | join("")`}
|
||||
if err := runChat(context.Background(), opts, fopts, svc); err != nil {
|
||||
t.Fatalf("runChat: %v", err)
|
||||
}
|
||||
got := strings.TrimSpace(out.String())
|
||||
if !strings.Contains(got, "the answer") {
|
||||
t.Errorf("jq output missing projected answer: %q", got)
|
||||
}
|
||||
// A projection must not dump the full envelope scaffolding.
|
||||
if strings.Contains(got, "references") || strings.Contains(got, "session_id") {
|
||||
t.Errorf("jq output looks like a full envelope, not a projection: %q", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestChat_FormatJSON_StreamErrorIncludesSessionDetail(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
svc := &fakeChatService{
|
||||
streamEvents: []*sdk.StreamResponse{{
|
||||
ResponseType: sdk.ResponseTypeAgentQuery,
|
||||
AssistantMessageID: "msg_123",
|
||||
}},
|
||||
streamErr: errors.New("connection reset"),
|
||||
}
|
||||
err := runChat(
|
||||
context.Background(),
|
||||
&Options{Query: "q", KBID: "kb"},
|
||||
&cmdutil.FormatOptions{Mode: cmdutil.FormatJSON},
|
||||
svc,
|
||||
)
|
||||
var typed *cmdutil.Error
|
||||
if !errors.As(err, &typed) {
|
||||
t.Fatalf("expected *cmdutil.Error, got %v", err)
|
||||
}
|
||||
detail, ok := typed.Detail.(map[string]any)
|
||||
if !ok || detail["session_id"] != "sess_auto" || detail["assistant_message_id"] != "msg_123" {
|
||||
t.Errorf("error detail=%v, want session and assistant message ids", typed.Detail)
|
||||
}
|
||||
}
|
||||
|
||||
+106
-79
@@ -3,26 +3,24 @@ package sessioncmd
|
||||
import (
|
||||
"context"
|
||||
"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/output"
|
||||
"github.com/Tencent/WeKnora/cli/internal/sse"
|
||||
sdk "github.com/Tencent/WeKnora/client"
|
||||
)
|
||||
|
||||
// sessionAskFields enumerates the NDJSON init-event fields surfaced for
|
||||
// `--format json` / `--format ndjson` discovery on `session ask`. Reflects
|
||||
// the InitEvent head line + the raw SDK agent event vocabulary.
|
||||
// sessionAskFields enumerates the fields surfaced for `--jq` projection
|
||||
// discovery on `session ask`: the json object's data fields + the raw SDK
|
||||
// agent event vocabulary used by --format ndjson.
|
||||
var sessionAskFields = []string{
|
||||
"session_id", "agent_id",
|
||||
// SDK event fields (pass-through): response_type, content, done,
|
||||
// knowledge_references, tool_call_id, tool_result
|
||||
"events", "session_id", "agent_id", "query",
|
||||
// NDJSON init + SDK event fields.
|
||||
"type", "profile", "response_type", "content", "done", "knowledge_references", "data",
|
||||
}
|
||||
|
||||
// AskOptions captures `session ask` flag state.
|
||||
@@ -30,6 +28,12 @@ type AskOptions struct {
|
||||
AgentID string
|
||||
Query string
|
||||
SessionID string // --session: continue an existing session (skip auto-create)
|
||||
// Reference adds bounded kb_id/chunk_id reference events to JSON/text.
|
||||
Reference bool
|
||||
// Verbose surfaces the projected execution trace in JSON/text,
|
||||
// including reasoning, tools, and lifecycle events.
|
||||
// NDJSON is always raw and is unaffected by presentation flags.
|
||||
Verbose bool
|
||||
}
|
||||
|
||||
// AskService is the narrow SDK surface this command depends on.
|
||||
@@ -60,12 +64,14 @@ The 'weknora agent' subtree handles CRUD only (list / view / create /
|
||||
edit / delete / status / check).
|
||||
|
||||
Modes:
|
||||
--format text: live answer streaming + tool-trace footer
|
||||
--format json / --format ndjson / pipe (default): NDJSON event stream —
|
||||
one init line at head (session_id, agent_id),
|
||||
then raw SDK agent events verbatim. Both
|
||||
json and ndjson flags produce the same
|
||||
NDJSON stream.`,
|
||||
--format json (default): one JSON envelope with answer events
|
||||
--format text: live human-readable answer stream
|
||||
--format ndjson: raw NDJSON event stream — init line (session_id,
|
||||
agent_id) then SDK agent events verbatim. Debug.
|
||||
|
||||
Pass --reference to include bounded kb_id/chunk_id reference indexes. Pass
|
||||
--verbose to include reasoning, tool activity, and lifecycle frames. Combine
|
||||
both flags for the complete projected stream.`,
|
||||
Example: ` weknora session ask --agent ag_x "Summarize Q3 sales"
|
||||
weknora session ask --session sess_x --agent ag_x "Follow-up question"
|
||||
weknora session ask --agent ag_x "Multi-step task" --format ndjson`,
|
||||
@@ -87,15 +93,18 @@ Modes:
|
||||
cmd.Flags().StringVarP(&opts.AgentID, "agent", "a", "", "Agent ID to invoke (required)")
|
||||
_ = cmd.MarkFlagRequired("agent")
|
||||
cmd.Flags().StringVar(&opts.SessionID, "session", "", "Continue an existing chat session (skip auto-create)")
|
||||
cmd.Flags().BoolVar(&opts.Reference, "reference", false, "Include indexed references in JSON/text output")
|
||||
cmd.Flags().BoolVar(&opts.Verbose, "verbose", false, "Include reasoning, tools, and lifecycle events in JSON/text output")
|
||||
cmdutil.AddFormatFlag(cmd, sessionAskFields...)
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "Invoke a custom agent in a session context. Produces an NDJSON event stream: init line (session_id, agent_id) then raw SDK agent events. Use --format json or --format ndjson.",
|
||||
UsedFor: "Invoke a custom agent in a session context. Default JSON returns a bounded answer-event projection. --reference adds indexed citations; --verbose adds reasoning, tools, and lifecycle events. --format ndjson streams raw SDK agent events; --format text renders the selected events live.",
|
||||
RequiredFlags: []string{"--agent"},
|
||||
Examples: []string{
|
||||
`weknora session ask --agent ag_x "Summarize Q3 sales" --format json`,
|
||||
`weknora session ask --session sess_x --agent ag_x "Follow-up question" --format json`,
|
||||
`weknora session ask --agent ag_x "Summarize Q3 sales"`,
|
||||
`weknora session ask --agent ag_x "Summarize Q3 sales" --jq '[.data.events[].content] | join("")'`,
|
||||
`weknora session ask --session sess_x --agent ag_x "Follow-up question"`,
|
||||
},
|
||||
Output: "NDJSON stream: {type:init, session_id, agent_id} then SDK agent events (response_type, content, done, knowledge_references, ...)",
|
||||
Output: "Default --format json: {ok,data:{events:[answer...],session_id,agent_id,query}}. --reference adds kb_id/chunk_id reference events; --verbose adds execution events. --format ndjson remains raw.",
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
@@ -111,11 +120,8 @@ func runAsk(ctx context.Context, opts *AskOptions, fopts *cmdutil.FormatOptions,
|
||||
return cmdutil.NewError(cmdutil.CodeServerError, "session ask: no SDK client available")
|
||||
}
|
||||
|
||||
// Streaming commands route --format json AND --format ndjson to the
|
||||
// NDJSON event-stream path. A buffered envelope makes no sense for a
|
||||
// streaming command. Only --format text uses the live renderer.
|
||||
ndjsonMode := fopts != nil && (fopts.Mode == cmdutil.FormatJSON || fopts.Mode == cmdutil.FormatNDJSON)
|
||||
|
||||
// --format selects the output shape: json (default) accumulates and
|
||||
// emits one object, ndjson streams raw SDK agent events, text renders.
|
||||
sessionID := opts.SessionID
|
||||
autoCreated := false
|
||||
if sessionID == "" {
|
||||
@@ -134,13 +140,16 @@ func runAsk(ctx context.Context, opts *AskOptions, fopts *cmdutil.FormatOptions,
|
||||
autoCreated = true
|
||||
}
|
||||
|
||||
if ndjsonMode {
|
||||
if fopts != nil && fopts.Mode == cmdutil.FormatNDJSON {
|
||||
return runAskNDJSON(ctx, opts, sessionID, svc)
|
||||
}
|
||||
if fopts != nil && fopts.Mode == cmdutil.FormatJSON {
|
||||
return runAskJSON(ctx, opts, fopts, sessionID, svc)
|
||||
}
|
||||
|
||||
// Surface auto-created session id up-front so a ^C mid-stream still
|
||||
// leaves a recoverable pointer. Skipped in NDJSON mode (it appears in
|
||||
// the init event).
|
||||
// leaves a recoverable pointer. Skipped in json/ndjson mode (session_id
|
||||
// is in the output).
|
||||
if autoCreated {
|
||||
fmt.Fprintf(iostreams.IO.Err, "session: %s (use --session to continue)\n", sessionID)
|
||||
}
|
||||
@@ -148,9 +157,9 @@ func runAsk(ctx context.Context, opts *AskOptions, fopts *cmdutil.FormatOptions,
|
||||
return runAskText(ctx, opts, sessionID, autoCreated, svc)
|
||||
}
|
||||
|
||||
// runAskNDJSON handles --format json and --format ndjson paths.
|
||||
// Emits a CLI init event at stream head, then passes every SDK agent event
|
||||
// through verbatim as NDJSON lines. No buffering.
|
||||
// runAskNDJSON handles the --format ndjson path: emits a CLI init event at
|
||||
// stream head, then passes every SDK agent event through verbatim as NDJSON
|
||||
// lines. No buffering.
|
||||
func runAskNDJSON(ctx context.Context, opts *AskOptions, sessionID string, svc AskService) error {
|
||||
w := iostreams.IO.Out
|
||||
|
||||
@@ -173,6 +182,8 @@ func runAskNDJSON(ctx context.Context, opts *AskOptions, sessionID string, svc A
|
||||
Channel: "api",
|
||||
}
|
||||
cb := func(r *sdk.AgentStreamResponse) error {
|
||||
// NDJSON is the raw protocol/debug surface: do not filter events or
|
||||
// mutate their payloads. JSON/text modes own presentation filtering.
|
||||
return output.EmitSDKEvent(w, r)
|
||||
}
|
||||
if err := svc.AgentQAStreamWithRequest(ctx, sessionID, req, cb); err != nil {
|
||||
@@ -184,12 +195,9 @@ func runAskNDJSON(ctx context.Context, opts *AskOptions, sessionID string, svc A
|
||||
return nil
|
||||
}
|
||||
|
||||
// runAskText handles the --format text path. Streams answer fragments
|
||||
// live on TTY; accumulates then renders on non-TTY pipes.
|
||||
// runAskText handles the --format text path. It renders the same
|
||||
// projection as JSON immediately for both terminals and pipes.
|
||||
func runAskText(ctx context.Context, opts *AskOptions, sessionID string, autoCreated bool, svc AskService) error {
|
||||
// Stream mode requires an interactive stdout.
|
||||
streamMode := iostreams.IO.IsStdoutTTY()
|
||||
|
||||
req := &sdk.AgentQARequest{
|
||||
Query: opts.Query,
|
||||
AgentEnabled: true,
|
||||
@@ -197,13 +205,14 @@ func runAskText(ctx context.Context, opts *AskOptions, sessionID string, autoCre
|
||||
Channel: "api",
|
||||
}
|
||||
|
||||
acc := &sse.AgentAccumulator{}
|
||||
projector := sse.NewProjector(opts.Verbose, opts.Reference, "")
|
||||
renderer := sse.NewTextRenderer(iostreams.IO.Out, opts.Verbose)
|
||||
cb := func(r *sdk.AgentStreamResponse) error {
|
||||
if streamMode && r != nil && r.ResponseType == sdk.AgentResponseTypeAnswer && r.Content != "" {
|
||||
_, _ = iostreams.IO.Out.Write([]byte(r.Content))
|
||||
event, include := projector.Agent(r)
|
||||
if !include {
|
||||
return nil
|
||||
}
|
||||
acc.Append(r)
|
||||
return nil
|
||||
return renderer.Write(event)
|
||||
}
|
||||
|
||||
streamErr := svc.AgentQAStreamWithRequest(ctx, sessionID, req, cb)
|
||||
@@ -214,61 +223,79 @@ func runAskText(ctx context.Context, opts *AskOptions, sessionID string, autoCre
|
||||
if cmdutil.IsCancelled(ctx, streamErr) {
|
||||
return cmdutil.Wrapf(cmdutil.CodeOperationCancelled, streamErr, "session ask cancelled")
|
||||
}
|
||||
if acc.Answer() != "" && !acc.Done() {
|
||||
if projector.Seen() && !projector.Done() {
|
||||
return cmdutil.Wrapf(cmdutil.CodeSSEStreamAborted, streamErr, "stream aborted before completion")
|
||||
}
|
||||
return cmdutil.WrapHTTP(streamErr, "agent-chat stream")
|
||||
}
|
||||
|
||||
// Server closed cleanly but never sent a Done event — treat as aborted
|
||||
// Server closed cleanly but never sent a complete event — treat as aborted
|
||||
// so agents don't silently emit a truncated answer as ok=true.
|
||||
if !acc.Done() {
|
||||
if !projector.Done() {
|
||||
return cmdutil.NewError(cmdutil.CodeSSEStreamAborted, "stream ended without a terminal event")
|
||||
}
|
||||
|
||||
answer := acc.Answer()
|
||||
out := iostreams.IO.Out
|
||||
if streamMode {
|
||||
if !strings.HasSuffix(answer, "\n") {
|
||||
fmt.Fprintln(out)
|
||||
}
|
||||
} else {
|
||||
fmt.Fprint(out, answer)
|
||||
if !strings.HasSuffix(answer, "\n") {
|
||||
fmt.Fprintln(out)
|
||||
}
|
||||
}
|
||||
renderAskToolTrace(out, acc.ToolEvents)
|
||||
format.WriteReferences(out, acc.References)
|
||||
return nil
|
||||
return renderer.Close()
|
||||
}
|
||||
|
||||
// renderAskToolTrace prints a compact tool-event footer in --format text
|
||||
// mode. Skipped when the agent emitted no tool events — silent beats an
|
||||
// empty banner.
|
||||
func renderAskToolTrace(w io.Writer, events []sse.AgentToolEvent) {
|
||||
if len(events) == 0 {
|
||||
return
|
||||
// runAskJSON handles the --format json path (the default): collect the
|
||||
// projection and emit it in one normal success envelope.
|
||||
func runAskJSON(ctx context.Context, opts *AskOptions, fopts *cmdutil.FormatOptions, sessionID string, svc AskService) error {
|
||||
req := &sdk.AgentQARequest{
|
||||
Query: opts.Query,
|
||||
AgentEnabled: true,
|
||||
AgentID: opts.AgentID,
|
||||
Channel: "api",
|
||||
}
|
||||
fmt.Fprintln(w)
|
||||
fmt.Fprintln(w, "──── Tool trace ────")
|
||||
for i, e := range events {
|
||||
fmt.Fprintf(w, "[%d] %s", i+1, e.Kind)
|
||||
if e.Result != "" {
|
||||
fmt.Fprintf(w, " %s", truncateAskInline(e.Result, 80))
|
||||
|
||||
projector := sse.NewProjector(opts.Verbose, opts.Reference, "")
|
||||
events := make([]sse.ProjectedEvent, 0)
|
||||
cb := func(r *sdk.AgentStreamResponse) error {
|
||||
if event, include := projector.Agent(r); include {
|
||||
events = append(events, event)
|
||||
}
|
||||
fmt.Fprintln(w)
|
||||
return nil
|
||||
}
|
||||
|
||||
if err := svc.AgentQAStreamWithRequest(ctx, sessionID, req, cb); err != nil {
|
||||
if cmdutil.IsCancelled(ctx, err) {
|
||||
return askStreamError(cmdutil.Wrapf(cmdutil.CodeOperationCancelled, err, "session ask cancelled"), sessionID)
|
||||
}
|
||||
return askStreamError(cmdutil.WrapHTTP(err, "agent-chat stream"), sessionID)
|
||||
}
|
||||
if !projector.Done() {
|
||||
return askStreamError(
|
||||
cmdutil.NewError(cmdutil.CodeSSEStreamAborted, "stream ended without a terminal event"),
|
||||
sessionID,
|
||||
)
|
||||
}
|
||||
|
||||
data := askResult{
|
||||
Events: events,
|
||||
SessionID: sessionID,
|
||||
AgentID: opts.AgentID,
|
||||
Query: opts.Query,
|
||||
}
|
||||
|
||||
// Reaching here means fopts.Mode is FormatJSON (the only caller). Route
|
||||
// through FormatOptions.Emit so --jq projection and the success-envelope
|
||||
// contract apply. A nil fopts (direct-test entry) defaults to JSON.
|
||||
if fopts == nil {
|
||||
fopts = &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}
|
||||
}
|
||||
return fopts.Emit(iostreams.IO.Out, data, nil)
|
||||
}
|
||||
|
||||
// truncateAskInline shrinks a multi-line result to a single line + ellipsis
|
||||
// for the text tool-trace footer.
|
||||
func truncateAskInline(s string, maxLen int) string {
|
||||
s = strings.ReplaceAll(s, "\n", " ")
|
||||
if len(s) <= maxLen {
|
||||
return s
|
||||
}
|
||||
return s[:maxLen-1] + "…"
|
||||
func askStreamError(err *cmdutil.Error, sessionID string) *cmdutil.Error {
|
||||
return err.WithDetail(map[string]any{"session_id": sessionID})
|
||||
}
|
||||
|
||||
// askResult is the --format json data payload. The projector controls default
|
||||
// versus verbose coverage.
|
||||
type askResult struct {
|
||||
Events []sse.ProjectedEvent `json:"events"`
|
||||
SessionID string `json:"session_id"`
|
||||
AgentID string `json:"agent_id"`
|
||||
Query string `json:"query"`
|
||||
}
|
||||
|
||||
// compile-time check: production SDK client satisfies AskService.
|
||||
|
||||
+227
-30
@@ -10,6 +10,7 @@ import (
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
||||
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
||||
"github.com/Tencent/WeKnora/cli/internal/sse"
|
||||
sdk "github.com/Tencent/WeKnora/client"
|
||||
)
|
||||
|
||||
@@ -69,19 +70,19 @@ func textOpts() *cmdutil.FormatOptions {
|
||||
return &cmdutil.FormatOptions{Mode: cmdutil.FormatText}
|
||||
}
|
||||
|
||||
// ndjsonOpts returns a FormatOptions for the NDJSON event-stream path.
|
||||
// --format json routes here too for streaming commands.
|
||||
// ndjsonOpts returns a FormatOptions for the NDJSON event-stream path
|
||||
// (--format ndjson: raw SDK agent events, one per line).
|
||||
func ndjsonOpts() *cmdutil.FormatOptions {
|
||||
return &cmdutil.FormatOptions{Mode: cmdutil.FormatNDJSON}
|
||||
}
|
||||
|
||||
// jsonOpts returns a FormatOptions configured for the JSON path.
|
||||
// In v0.7 --format json routes to the NDJSON stream path for streaming commands.
|
||||
// jsonOpts returns a FormatOptions configured for the JSON object path
|
||||
// (--format json: one accumulated {ok,data} envelope).
|
||||
func jsonOpts() *cmdutil.FormatOptions {
|
||||
return &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}
|
||||
}
|
||||
|
||||
// TestSessionAsk_NDJSON_FirstLineIsInit verifies that the NDJSON path (--format json)
|
||||
// TestSessionAsk_NDJSON_FirstLineIsInit verifies that the NDJSON path (--format ndjson)
|
||||
// always injects an "init" line first, carrying session_id and agent_id.
|
||||
func TestSessionAsk_NDJSON_FirstLineIsInit(t *testing.T) {
|
||||
out, errBuf := iostreams.SetForTest(t)
|
||||
@@ -92,7 +93,7 @@ func TestSessionAsk_NDJSON_FirstLineIsInit(t *testing.T) {
|
||||
},
|
||||
}
|
||||
opts := &AskOptions{AgentID: "ag_x", Query: "ping"}
|
||||
if err := runAsk(context.Background(), opts, jsonOpts(), svc); err != nil {
|
||||
if err := runAsk(context.Background(), opts, ndjsonOpts(), svc); err != nil {
|
||||
t.Fatalf("runAsk: %v", err)
|
||||
}
|
||||
|
||||
@@ -134,7 +135,7 @@ func TestSessionAsk_NDJSON_PassthroughEvents(t *testing.T) {
|
||||
},
|
||||
}
|
||||
opts := &AskOptions{AgentID: "ag_x", Query: "hi"}
|
||||
if err := runAsk(context.Background(), opts, jsonOpts(), svc); err != nil {
|
||||
if err := runAsk(context.Background(), opts, ndjsonOpts(), svc); err != nil {
|
||||
t.Fatalf("runAsk: %v", err)
|
||||
}
|
||||
|
||||
@@ -152,29 +153,155 @@ func TestSessionAsk_NDJSON_PassthroughEvents(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// TestSessionAsk_NDJSON_JSONEqualsNDJSON verifies that --format json and --format ndjson
|
||||
// produce identical NDJSON streams for session ask.
|
||||
func TestSessionAsk_NDJSON_JSONEqualsNDJSON(t *testing.T) {
|
||||
events := []*sdk.AgentStreamResponse{
|
||||
answerEvent("hello"),
|
||||
// TestSessionAsk_FormatJSON_EmitsSingleEnvelope verifies that default JSON
|
||||
// keeps answer events only.
|
||||
func TestSessionAsk_FormatJSON_EmitsSingleEnvelope(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &scriptedAskSvc{events: []*sdk.AgentStreamResponse{
|
||||
// Per-event Done markers are not terminal for the whole agent run.
|
||||
{ResponseType: sdk.AgentResponseTypeThinking, Content: "hidden reasoning", Done: true},
|
||||
toolCallEvent("call_1", "knowledge_search"),
|
||||
referencesEvent([]*sdk.SearchResult{{ID: "c1", Content: "BULKY PASSAGE", KnowledgeTitle: "Doc"}}),
|
||||
answerEvent("the answer"),
|
||||
{ResponseType: sdk.AgentResponseTypeAnswer, Done: true},
|
||||
doneEvent(),
|
||||
}}
|
||||
opts := &AskOptions{AgentID: "ag_x", Query: "hi"}
|
||||
if err := runAsk(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc); err != nil {
|
||||
t.Fatalf("runAsk: %v", err)
|
||||
}
|
||||
|
||||
runWith := func(mode cmdutil.FormatMode) string {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &scriptedAskSvc{events: events}
|
||||
opts := &AskOptions{AgentID: "ag_x", Query: "q"}
|
||||
fopts := &cmdutil.FormatOptions{Mode: mode}
|
||||
if err := runAsk(context.Background(), opts, fopts, svc); err != nil {
|
||||
t.Fatalf("runAsk(%s): %v", mode, err)
|
||||
// A single envelope, not multiple NDJSON lines.
|
||||
outStr := strings.TrimRight(out.String(), "\n")
|
||||
if strings.Contains(outStr, "\n") {
|
||||
t.Fatalf("expected single-line envelope, got multiple lines:\n%s", outStr)
|
||||
}
|
||||
var env struct {
|
||||
OK bool `json:"ok"`
|
||||
Data struct {
|
||||
Events []sse.ProjectedEvent `json:"events"`
|
||||
SessionID string `json:"session_id"`
|
||||
AgentID string `json:"agent_id"`
|
||||
Query string `json:"query"`
|
||||
} `json:"data"`
|
||||
}
|
||||
if err := json.Unmarshal([]byte(outStr), &env); err != nil {
|
||||
t.Fatalf("envelope not JSON: %v\n%s", err, outStr)
|
||||
}
|
||||
if !env.OK {
|
||||
t.Error("ok=false, want true")
|
||||
}
|
||||
if len(env.Data.Events) != 2 {
|
||||
t.Fatalf("events=%+v, want two answer frames", env.Data.Events)
|
||||
}
|
||||
for i, event := range env.Data.Events {
|
||||
if event.ResponseType != "answer" {
|
||||
t.Errorf("events[%d].response_type=%q, want answer", i, event.ResponseType)
|
||||
}
|
||||
return out.String()
|
||||
}
|
||||
if env.Data.Events[0].Content != "the answer" {
|
||||
t.Errorf("answer content=%q", env.Data.Events[0].Content)
|
||||
}
|
||||
if env.Data.AgentID != "ag_x" || env.Data.Query != "hi" {
|
||||
t.Errorf("echo fields: agent_id=%q query=%q", env.Data.AgentID, env.Data.Query)
|
||||
}
|
||||
if env.Data.SessionID == "" {
|
||||
t.Error("session_id empty")
|
||||
}
|
||||
}
|
||||
|
||||
jsonOut := runWith(cmdutil.FormatJSON)
|
||||
ndjsonOut := runWith(cmdutil.FormatNDJSON)
|
||||
if jsonOut != ndjsonOut {
|
||||
t.Errorf("--format json and --format ndjson differ:\n json: %q\n ndjson: %q", jsonOut, ndjsonOut)
|
||||
func TestSessionAsk_FormatJSON_VerboseAndReferenceIncludeBothDetailClasses(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &scriptedAskSvc{events: []*sdk.AgentStreamResponse{
|
||||
{ID: "think", ResponseType: sdk.AgentResponseTypeThinking, Content: "reasoning", Done: true},
|
||||
toolCallEvent("call_1", "knowledge_search"),
|
||||
referencesEvent([]*sdk.SearchResult{{ID: "c1", KnowledgeBaseID: "kb1", ParentChunkID: "p1", Content: "BULK"}}),
|
||||
answerEvent("answer [chunk:c1]"),
|
||||
doneEvent(),
|
||||
}}
|
||||
opts := &AskOptions{AgentID: "ag_x", Query: "hi", Verbose: true, Reference: true}
|
||||
if err := runAsk(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc); err != nil {
|
||||
t.Fatalf("runAsk: %v", err)
|
||||
}
|
||||
var env struct {
|
||||
Data struct {
|
||||
Events []sse.ProjectedEvent `json:"events"`
|
||||
} `json:"data"`
|
||||
}
|
||||
if err := json.Unmarshal(out.Bytes(), &env); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
want := []string{"thinking", "tool_call", "references", "answer", "complete"}
|
||||
if len(env.Data.Events) != len(want) {
|
||||
t.Fatalf("events=%+v", env.Data.Events)
|
||||
}
|
||||
for i, responseType := range want {
|
||||
if env.Data.Events[i].ResponseType != responseType {
|
||||
t.Errorf("events[%d]=%q, want %q", i, env.Data.Events[i].ResponseType, responseType)
|
||||
}
|
||||
}
|
||||
refs := env.Data.Events[2].KnowledgeReferences
|
||||
if len(refs) != 1 || refs[0].KBID != "kb1" || refs[0].ChunkID != "c1" || refs[0].ParentChunkID != "p1" {
|
||||
t.Errorf("reference indexes=%+v", refs)
|
||||
}
|
||||
}
|
||||
|
||||
// TestSessionAsk_Text_VerboseIncludesThinking verifies the --format text path
|
||||
// honors --verbose: the agent's thinking streams inline with the answer.
|
||||
// (Regresses the original bug: runAskText ignored opts.Verbose entirely, so
|
||||
// thinking never appeared in text mode under any flag.)
|
||||
func TestSessionAsk_Text_VerboseIncludesThinking(t *testing.T) {
|
||||
out, _ := iostreams.SetForTestWithTTY(t)
|
||||
svc := &scriptedAskSvc{events: []*sdk.AgentStreamResponse{
|
||||
{ResponseType: sdk.AgentResponseTypeThinking, Content: "REASONING"},
|
||||
answerEvent("answer"),
|
||||
doneEvent(),
|
||||
}}
|
||||
opts := &AskOptions{AgentID: "ag_x", Query: "hi", Verbose: true}
|
||||
if err := runAsk(context.Background(), opts, textOpts(), svc); err != nil {
|
||||
t.Fatalf("runAsk: %v", err)
|
||||
}
|
||||
if !strings.Contains(out.String(), "REASONING") {
|
||||
t.Errorf("verbose text output missing thinking: %q", out.String())
|
||||
}
|
||||
if !strings.Contains(out.String(), "answer") {
|
||||
t.Errorf("answer body missing: %q", out.String())
|
||||
}
|
||||
}
|
||||
|
||||
func TestSessionAsk_Text_NonTTYVerboseIncludesThinking(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &scriptedAskSvc{events: []*sdk.AgentStreamResponse{
|
||||
{ResponseType: sdk.AgentResponseTypeThinking, Content: "REASONING", Done: true},
|
||||
answerEvent("answer"),
|
||||
doneEvent(),
|
||||
}}
|
||||
opts := &AskOptions{AgentID: "ag_x", Query: "hi", Verbose: true}
|
||||
if err := runAsk(context.Background(), opts, textOpts(), svc); err != nil {
|
||||
t.Fatalf("runAsk: %v", err)
|
||||
}
|
||||
if got := out.String(); !strings.Contains(got, "REASONING") || !strings.Contains(got, "answer") {
|
||||
t.Errorf("non-TTY verbose output missing thinking or answer: %q", got)
|
||||
}
|
||||
}
|
||||
|
||||
// TestSessionAsk_Text_HidesThinkingByDefault: without --verbose the text path
|
||||
// must NOT stream the reasoning pass, only the answer.
|
||||
func TestSessionAsk_Text_HidesThinkingByDefault(t *testing.T) {
|
||||
out, _ := iostreams.SetForTestWithTTY(t)
|
||||
svc := &scriptedAskSvc{events: []*sdk.AgentStreamResponse{
|
||||
{ResponseType: sdk.AgentResponseTypeThinking, Content: "REASONING"},
|
||||
answerEvent("answer"),
|
||||
doneEvent(),
|
||||
}}
|
||||
opts := &AskOptions{AgentID: "ag_x", Query: "hi"}
|
||||
if err := runAsk(context.Background(), opts, textOpts(), svc); err != nil {
|
||||
t.Fatalf("runAsk: %v", err)
|
||||
}
|
||||
if strings.Contains(out.String(), "REASONING") {
|
||||
t.Errorf("non-verbose text output leaked thinking: %q", out.String())
|
||||
}
|
||||
if !strings.Contains(out.String(), "answer") {
|
||||
t.Errorf("answer body missing: %q", out.String())
|
||||
}
|
||||
}
|
||||
|
||||
@@ -280,6 +407,25 @@ func TestSessionAsk_NoDoneEvent_MapsToSSEStreamAborted(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
func TestSessionAsk_FormatJSON_StreamErrorIncludesSessionDetail(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
svc := &scriptedAskSvc{streamErr: errors.New("connection reset")}
|
||||
err := runAsk(
|
||||
context.Background(),
|
||||
&AskOptions{AgentID: "ag", Query: "x"},
|
||||
jsonOpts(),
|
||||
svc,
|
||||
)
|
||||
var typed *cmdutil.Error
|
||||
if !errors.As(err, &typed) {
|
||||
t.Fatalf("expected *cmdutil.Error, got %v", err)
|
||||
}
|
||||
detail, ok := typed.Detail.(map[string]any)
|
||||
if !ok || detail["session_id"] != "sess_auto" {
|
||||
t.Errorf("error detail=%v, want auto-created session_id", typed.Detail)
|
||||
}
|
||||
}
|
||||
|
||||
func TestSessionAsk_CreateSessionFails_MapsToSessionCreateFailed(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
svc := &scriptedAskSvc{createErr: errors.New("connection refused")}
|
||||
@@ -311,8 +457,8 @@ func TestSessionAsk_Cancellation_MapsToOperationCancelled(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// Sanity: text-mode output writes the answer body and a tool-trace footer.
|
||||
func TestSessionAsk_Text_Accumulate_PrintsAnswerAndFooter(t *testing.T) {
|
||||
// Default text writes answer events but filters tool events.
|
||||
func TestSessionAsk_Text_DefaultHidesTools(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &scriptedAskSvc{events: []*sdk.AgentStreamResponse{
|
||||
answerEvent("hello"),
|
||||
@@ -327,8 +473,8 @@ func TestSessionAsk_Text_Accumulate_PrintsAnswerAndFooter(t *testing.T) {
|
||||
if !strings.Contains(got, "hello") {
|
||||
t.Errorf("answer body missing: %q", got)
|
||||
}
|
||||
if !strings.Contains(got, "Tool trace") {
|
||||
t.Errorf("tool trace footer missing: %q", got)
|
||||
if strings.Contains(got, "tool_call") || strings.Contains(got, "knowledge_search") {
|
||||
t.Errorf("default text output leaked tool event: %q", got)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -437,7 +583,7 @@ func TestSessionAsk_NDJSON_IncludesReferencesViaSDKEvent(t *testing.T) {
|
||||
},
|
||||
}
|
||||
opts := &AskOptions{AgentID: "ag_x", Query: "ping"}
|
||||
if err := runAsk(context.Background(), opts, jsonOpts(), svc); err != nil {
|
||||
if err := runAsk(context.Background(), opts, ndjsonOpts(), svc); err != nil {
|
||||
t.Fatalf("runAsk: %v", err)
|
||||
}
|
||||
|
||||
@@ -463,3 +609,54 @@ func TestSessionAsk_NDJSON_IncludesReferencesViaSDKEvent(t *testing.T) {
|
||||
t.Errorf("expected references event at line 3, got response_type=%v", refsLine["response_type"])
|
||||
}
|
||||
}
|
||||
|
||||
func TestSessionAsk_NDJSON_PreservesReferencesAndThinking(t *testing.T) {
|
||||
// NDJSON is the raw protocol surface: reasoning and full reference payloads
|
||||
// pass through unchanged. Index projection is limited to JSON/text/MCP.
|
||||
svc := &scriptedAskSvc{
|
||||
events: []*sdk.AgentStreamResponse{
|
||||
{ResponseType: sdk.AgentResponseTypeThinking, Content: "reasoning"},
|
||||
referencesEvent([]*sdk.SearchResult{{ID: "c1", Content: "BULKY PASSAGE", KnowledgeTitle: "Doc"}}),
|
||||
answerEvent("hello"),
|
||||
doneEvent(),
|
||||
},
|
||||
}
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
|
||||
opts := &AskOptions{AgentID: "ag_x", Query: "hi"}
|
||||
if err := runAsk(context.Background(), opts, ndjsonOpts(), svc); err != nil {
|
||||
t.Fatalf("runAsk: %v", err)
|
||||
}
|
||||
|
||||
var refsLine map[string]any
|
||||
sawThinking := false
|
||||
for _, line := range strings.Split(strings.TrimRight(out.String(), "\n"), "\n") {
|
||||
var ev map[string]any
|
||||
if err := json.Unmarshal([]byte(line), &ev); err != nil {
|
||||
continue
|
||||
}
|
||||
if ev["response_type"] == "thinking" {
|
||||
sawThinking = true
|
||||
}
|
||||
if ev["response_type"] == "references" {
|
||||
refsLine = ev
|
||||
}
|
||||
}
|
||||
if !sawThinking {
|
||||
t.Error("thinking event was filtered from raw NDJSON output")
|
||||
}
|
||||
if refsLine == nil {
|
||||
t.Fatal("references event not emitted")
|
||||
}
|
||||
refs, _ := refsLine["knowledge_references"].([]any)
|
||||
if len(refs) != 1 {
|
||||
t.Fatalf("knowledge_references=%d, want 1", len(refs))
|
||||
}
|
||||
first, _ := refs[0].(map[string]any)
|
||||
if first["content"] != "BULKY PASSAGE" {
|
||||
t.Errorf("references[0].content=%v, want original content", first["content"])
|
||||
}
|
||||
if first["id"] != "c1" {
|
||||
t.Errorf("references[0].id=%v, want c1", first["id"])
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,37 +1,36 @@
|
||||
package format
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"io"
|
||||
import sdk "github.com/Tencent/WeKnora/client"
|
||||
|
||||
sdk "github.com/Tencent/WeKnora/client"
|
||||
)
|
||||
// ReferenceIndex is the bounded citation pointer exposed by projected JSON,
|
||||
// text, and MCP output. ChunkID is the chunk the model cited; ParentChunkID is
|
||||
// retained when callers prefer to fetch the larger self-contained passage.
|
||||
// Full chunk text and retrieval metadata remain available only in raw NDJSON.
|
||||
type ReferenceIndex struct {
|
||||
KBID string `json:"kb_id,omitempty"`
|
||||
ChunkID string `json:"chunk_id"`
|
||||
ParentChunkID string `json:"parent_chunk_id,omitempty"`
|
||||
}
|
||||
|
||||
// WriteReferences renders the compact references footer used by chat and
|
||||
// agent invoke: a horizontal rule, one numbered line per reference,
|
||||
// best-available title + optional score. Skipped entirely when refs is
|
||||
// empty - agent-friendly silence beats an empty banner.
|
||||
func WriteReferences(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 {
|
||||
// IndexReferences projects full SDK search results into stable lookup keys.
|
||||
// It never mutates the SDK events, which keeps the raw NDJSON path lossless.
|
||||
// fallbackKBID is used by `chat`, whose single KB is known by the CLI even
|
||||
// when an older server omits knowledge_base_id from a reference.
|
||||
func IndexReferences(refs []*sdk.SearchResult, fallbackKBID string) []ReferenceIndex {
|
||||
indexes := make([]ReferenceIndex, 0, len(refs))
|
||||
for _, r := range refs {
|
||||
if r == nil || r.ID == "" {
|
||||
continue
|
||||
}
|
||||
title := r.KnowledgeTitle
|
||||
if title == "" {
|
||||
title = r.KnowledgeFilename
|
||||
kbID := r.KnowledgeBaseID
|
||||
if kbID == "" {
|
||||
kbID = fallbackKBID
|
||||
}
|
||||
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)
|
||||
indexes = append(indexes, ReferenceIndex{
|
||||
KBID: kbID,
|
||||
ChunkID: r.ID,
|
||||
ParentChunkID: r.ParentChunkID,
|
||||
})
|
||||
}
|
||||
return indexes
|
||||
}
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
package format
|
||||
|
||||
import (
|
||||
"testing"
|
||||
|
||||
sdk "github.com/Tencent/WeKnora/client"
|
||||
)
|
||||
|
||||
func TestIndexReferences_ProjectsLookupFieldsWithoutMutation(t *testing.T) {
|
||||
refs := []*sdk.SearchResult{
|
||||
{ID: "c1", Content: "bulky passage one", KnowledgeBaseID: "kb1", ParentChunkID: "p1", KnowledgeTitle: "Doc One", Score: 0.5},
|
||||
{ID: "c2", Content: "bulky passage two", ParentChunkID: "p2"},
|
||||
nil,
|
||||
}
|
||||
got := IndexReferences(refs, "fallback")
|
||||
|
||||
if len(got) != 2 {
|
||||
t.Fatalf("indexes=%d, want 2", len(got))
|
||||
}
|
||||
if got[0].KBID != "kb1" || got[0].ChunkID != "c1" || got[0].ParentChunkID != "p1" {
|
||||
t.Errorf("first index=%+v", got[0])
|
||||
}
|
||||
if got[1].KBID != "fallback" || got[1].ChunkID != "c2" {
|
||||
t.Errorf("fallback index=%+v", got[1])
|
||||
}
|
||||
if refs[0].Content != "bulky passage one" || refs[1].Content != "bulky passage two" {
|
||||
t.Errorf("source references mutated: %+v", refs)
|
||||
}
|
||||
}
|
||||
|
||||
func TestIndexReferences_NilSafe(t *testing.T) {
|
||||
if got := IndexReferences(nil, ""); len(got) != 0 {
|
||||
t.Errorf("nil indexes=%+v", got)
|
||||
}
|
||||
if got := IndexReferences([]*sdk.SearchResult{nil, nil}, ""); len(got) != 0 {
|
||||
t.Errorf("nil-entry indexes=%+v", got)
|
||||
}
|
||||
}
|
||||
+34
-34
@@ -431,22 +431,22 @@ type chatInput struct {
|
||||
KBID string `json:"kb_id" jsonschema:"knowledge base ID to chat against"`
|
||||
Query string `json:"query" jsonschema:"user query"`
|
||||
SessionID string `json:"session_id,omitempty" jsonschema:"existing session to continue; auto-created when empty"`
|
||||
Reference bool `json:"reference,omitempty" jsonschema:"include indexed references"`
|
||||
Verbose bool `json:"verbose,omitempty" jsonschema:"include reasoning, tools, and lifecycle events"`
|
||||
}
|
||||
|
||||
type chatOutput struct {
|
||||
Answer string `json:"answer"`
|
||||
References []*sdk.SearchResult `json:"references"`
|
||||
Thinking string `json:"thinking,omitempty"` // reasoning text from response_type=thinking; empty for non-reasoning models
|
||||
SessionID string `json:"session_id"`
|
||||
AssistantMessageID string `json:"assistant_message_id,omitempty"`
|
||||
KBID string `json:"kb_id"`
|
||||
Query string `json:"query"`
|
||||
Events []sse.ProjectedEvent `json:"events"`
|
||||
SessionID string `json:"session_id"`
|
||||
AssistantMessageID string `json:"assistant_message_id,omitempty"`
|
||||
KBID string `json:"kb_id"`
|
||||
Query string `json:"query"`
|
||||
}
|
||||
|
||||
func addChat(server *mcpsdk.Server, svc chatService) {
|
||||
mcpsdk.AddTool(server, &mcpsdk.Tool{
|
||||
Name: "chat",
|
||||
Description: "Stream a RAG answer from the LLM, grounded in the given knowledge base. The SSE stream is accumulated server-side (MCP tools/call has no standard partial-response, so this is NOT streaming); the tool returns the full accumulated response once the stream completes. Pass session_id to continue a multi-turn conversation; otherwise a fresh session is auto-created.",
|
||||
Description: "Run a RAG answer against a knowledge base. Returns a bounded answer-event projection by default; reference=true adds indexed citations and verbose=true adds reasoning, tool, and lifecycle events. MCP tools/call is buffered rather than streaming. Pass session_id to continue a conversation.",
|
||||
Annotations: &mcpsdk.ToolAnnotations{
|
||||
Title: "Chat with KB (Streaming RAG)",
|
||||
DestructiveHint: bptr(false),
|
||||
@@ -475,27 +475,28 @@ func addChat(server *mcpsdk.Server, svc chatService) {
|
||||
AgentEnabled: false,
|
||||
Channel: "api",
|
||||
}
|
||||
acc := &sse.Accumulator{}
|
||||
projector := sse.NewProjector(in.Verbose, in.Reference, in.KBID)
|
||||
events := make([]sse.ProjectedEvent, 0)
|
||||
streamErr := svc.KnowledgeQAStream(ctx, sessionID, req, func(r *sdk.StreamResponse) error {
|
||||
acc.Append(r)
|
||||
if event, include := projector.Chat(r); include {
|
||||
events = append(events, event)
|
||||
}
|
||||
return nil
|
||||
})
|
||||
if streamErr != nil {
|
||||
return toolErrorResult(cmdutil.WrapHTTP(streamErr, "knowledge qa stream")), nil, nil
|
||||
}
|
||||
if !acc.Done() {
|
||||
if !projector.Done() {
|
||||
return toolErrorResult(cmdutil.NewError(cmdutil.CodeSSEStreamAborted, "stream ended without a terminal event")), nil, nil
|
||||
}
|
||||
sid := acc.SessionID
|
||||
sid := projector.SessionID()
|
||||
if sid == "" {
|
||||
sid = sessionID
|
||||
}
|
||||
return successResult(chatOutput{
|
||||
Answer: acc.Result(),
|
||||
References: acc.References,
|
||||
Thinking: acc.Thinking(),
|
||||
Events: events,
|
||||
SessionID: sid,
|
||||
AssistantMessageID: acc.AssistantMessageID,
|
||||
AssistantMessageID: projector.AssistantMessageID(),
|
||||
KBID: in.KBID,
|
||||
Query: in.Query,
|
||||
}), nil, nil
|
||||
@@ -539,22 +540,21 @@ type sessionAskInput struct {
|
||||
AgentID string `json:"agent_id" jsonschema:"custom agent ID"`
|
||||
Query string `json:"query" jsonschema:"user query"`
|
||||
SessionID string `json:"session_id,omitempty" jsonschema:"existing session to continue; auto-created when empty"`
|
||||
Reference bool `json:"reference,omitempty" jsonschema:"include indexed references"`
|
||||
Verbose bool `json:"verbose,omitempty" jsonschema:"include reasoning, tools, and lifecycle events"`
|
||||
}
|
||||
|
||||
type sessionAskOutput struct {
|
||||
Answer string `json:"answer"`
|
||||
References []*sdk.SearchResult `json:"references"`
|
||||
ToolEvents []sse.AgentToolEvent `json:"tool_events,omitempty"`
|
||||
Thinking string `json:"thinking,omitempty"`
|
||||
SessionID string `json:"session_id"`
|
||||
AgentID string `json:"agent_id"`
|
||||
Query string `json:"query"`
|
||||
Events []sse.ProjectedEvent `json:"events"`
|
||||
SessionID string `json:"session_id"`
|
||||
AgentID string `json:"agent_id"`
|
||||
Query string `json:"query"`
|
||||
}
|
||||
|
||||
func addSessionAsk(server *mcpsdk.Server, svc sessionAskService) {
|
||||
mcpsdk.AddTool(server, &mcpsdk.Tool{
|
||||
Name: "session_ask",
|
||||
Description: "Run a query through a custom agent via `session ask --agent` (system prompt + tool allow-list + KB scope). The agent's SSE stream is accumulated server-side (MCP tools/call has no standard partial-response, so this is NOT streaming); the tool returns the final accumulated response once the stream completes.",
|
||||
Description: "Run a query through a custom agent. Returns a bounded answer-event projection by default; reference=true adds indexed citations and verbose=true adds reasoning, tool, and lifecycle events. MCP tools/call is buffered rather than streaming.",
|
||||
Annotations: &mcpsdk.ToolAnnotations{
|
||||
Title: "Ask a Custom Agent (session ask --agent)",
|
||||
DestructiveHint: bptr(false),
|
||||
@@ -569,7 +569,8 @@ func addSessionAsk(server *mcpsdk.Server, svc sessionAskService) {
|
||||
if strings.TrimSpace(in.Query) == "" {
|
||||
return toolErrorResult(cmdutil.NewError(cmdutil.CodeInputMissingFlag, "query cannot be empty")), nil, nil
|
||||
}
|
||||
acc := &sse.AgentAccumulator{}
|
||||
projector := sse.NewProjector(in.Verbose, in.Reference, "")
|
||||
events := make([]sse.ProjectedEvent, 0)
|
||||
req := &sdk.AgentQARequest{
|
||||
Query: in.Query,
|
||||
AgentEnabled: true,
|
||||
@@ -587,23 +588,22 @@ func addSessionAsk(server *mcpsdk.Server, svc sessionAskService) {
|
||||
sessionID = sess.ID
|
||||
}
|
||||
streamErr := svc.AgentQAStreamWithRequest(ctx, sessionID, req, func(r *sdk.AgentStreamResponse) error {
|
||||
acc.Append(r)
|
||||
if event, include := projector.Agent(r); include {
|
||||
events = append(events, event)
|
||||
}
|
||||
return nil
|
||||
})
|
||||
if streamErr != nil {
|
||||
return toolErrorResult(cmdutil.WrapHTTP(streamErr, "agent-chat stream")), nil, nil
|
||||
}
|
||||
if !acc.Done() {
|
||||
if !projector.Done() {
|
||||
return toolErrorResult(cmdutil.NewError(cmdutil.CodeSSEStreamAborted, "stream ended without a terminal event")), nil, nil
|
||||
}
|
||||
return successResult(sessionAskOutput{
|
||||
Answer: acc.Answer(),
|
||||
References: acc.References,
|
||||
ToolEvents: acc.ToolEvents,
|
||||
Thinking: acc.Thinking(),
|
||||
SessionID: sessionID,
|
||||
AgentID: in.AgentID,
|
||||
Query: in.Query,
|
||||
Events: events,
|
||||
SessionID: sessionID,
|
||||
AgentID: in.AgentID,
|
||||
Query: in.Query,
|
||||
}), nil, nil
|
||||
})
|
||||
}
|
||||
|
||||
@@ -423,30 +423,37 @@ func TestTool_SearchChunks_PassesMatchCountFromLimit(t *testing.T) {
|
||||
assert.Equal(t, 50, svc.calls.hybridParams.MatchCount, "MCP search_chunks must thread limit into SearchParams.MatchCount")
|
||||
}
|
||||
|
||||
func TestTool_Chat_AccumulateAnswerAndReferences(t *testing.T) {
|
||||
func TestTool_Chat_DefaultReturnsAnswerEventsOnly(t *testing.T) {
|
||||
svc := &fakeSvc{
|
||||
kbStreamEvents: []*sdk.StreamResponse{
|
||||
{Content: "Hello "},
|
||||
{Content: "world."},
|
||||
{KnowledgeReferences: []*sdk.SearchResult{{KnowledgeID: "k1"}}},
|
||||
{KnowledgeReferences: []*sdk.SearchResult{{
|
||||
ID: "c1",
|
||||
KnowledgeID: "k1",
|
||||
ParentChunkID: "p1",
|
||||
Content: "bulky passage",
|
||||
}}},
|
||||
{ResponseType: sdk.ResponseTypeComplete},
|
||||
},
|
||||
}
|
||||
c, _ := newTestServer(t, svc)
|
||||
var out chatOutput
|
||||
callTool(t, c, "chat", map[string]any{"kb_id": "kb_x", "query": "ping"}, &out)
|
||||
if out.Answer != "Hello world." {
|
||||
t.Errorf("answer = %q", out.Answer)
|
||||
if len(out.Events) != 2 || out.Events[0].Content != "Hello " || out.Events[1].Content != "world." {
|
||||
t.Errorf("answer events=%+v", out.Events)
|
||||
}
|
||||
if len(out.References) != 1 || out.References[0].KnowledgeID != "k1" {
|
||||
t.Errorf("references missing: %+v", out.References)
|
||||
for _, event := range out.Events {
|
||||
if event.ResponseType != "answer" || len(event.KnowledgeReferences) != 0 {
|
||||
t.Errorf("default output leaked non-answer data: %+v", event)
|
||||
}
|
||||
}
|
||||
if out.SessionID != "sess_auto" {
|
||||
t.Errorf("session_id = %q, want sess_auto", out.SessionID)
|
||||
}
|
||||
}
|
||||
|
||||
func TestMCP_ChatToolReturnsThinking(t *testing.T) {
|
||||
func TestMCP_ChatVerbosePreservesThinking(t *testing.T) {
|
||||
svc := &fakeSvc{
|
||||
kbStreamEvents: []*sdk.StreamResponse{
|
||||
{ResponseType: sdk.ResponseTypeThinking, Content: "let me reason..."},
|
||||
@@ -456,12 +463,15 @@ func TestMCP_ChatToolReturnsThinking(t *testing.T) {
|
||||
}
|
||||
c, _ := newTestServer(t, svc)
|
||||
var out chatOutput
|
||||
callTool(t, c, "chat", map[string]any{"kb_id": "kb_x", "query": "deep question"}, &out)
|
||||
if out.Thinking != "let me reason..." {
|
||||
t.Errorf("thinking = %q, want %q", out.Thinking, "let me reason...")
|
||||
callTool(t, c, "chat", map[string]any{"kb_id": "kb_x", "query": "deep question", "verbose": true}, &out)
|
||||
want := []string{"thinking", "answer", "complete"}
|
||||
if len(out.Events) != len(want) {
|
||||
t.Fatalf("events=%+v", out.Events)
|
||||
}
|
||||
if out.Answer != "final answer" {
|
||||
t.Errorf("answer = %q, want %q", out.Answer, "final answer")
|
||||
for i, responseType := range want {
|
||||
if out.Events[i].ResponseType != responseType {
|
||||
t.Errorf("events[%d]=%q, want %q", i, out.Events[i].ResponseType, responseType)
|
||||
}
|
||||
}
|
||||
if out.KBID != "kb_x" {
|
||||
t.Errorf("kb_id = %q, want %q", out.KBID, "kb_x")
|
||||
@@ -471,23 +481,35 @@ func TestMCP_ChatToolReturnsThinking(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
func TestMCP_SessionAskToolReturnsToolCalls(t *testing.T) {
|
||||
func TestMCP_SessionAskVerboseAndReferenceReturnsBothDetailClasses(t *testing.T) {
|
||||
svc := &fakeSvc{
|
||||
agentEvents: []*sdk.AgentStreamResponse{
|
||||
{ResponseType: sdk.AgentResponseTypeThinking, Content: "agent thinks"},
|
||||
{ResponseType: sdk.AgentResponseTypeToolCall, ID: "tc1", Content: "knowledge_search"},
|
||||
{ResponseType: sdk.AgentResponseTypeReferences, KnowledgeReferences: []*sdk.SearchResult{{
|
||||
ID: "c1",
|
||||
ParentChunkID: "p1",
|
||||
Content: "bulky passage",
|
||||
}}},
|
||||
{ResponseType: sdk.AgentResponseTypeAnswer, Content: "agent answer"},
|
||||
{ResponseType: sdk.AgentResponseTypeComplete, Done: true},
|
||||
},
|
||||
}
|
||||
c, _ := newTestServer(t, svc)
|
||||
var out sessionAskOutput
|
||||
callTool(t, c, "session_ask", map[string]any{"agent_id": "ag1", "query": "tool question"}, &out)
|
||||
if out.Thinking != "agent thinks" {
|
||||
t.Errorf("thinking = %q, want %q", out.Thinking, "agent thinks")
|
||||
callTool(t, c, "session_ask", map[string]any{"agent_id": "ag1", "query": "tool question", "verbose": true, "reference": true}, &out)
|
||||
want := []string{"thinking", "tool_call", "references", "answer", "complete"}
|
||||
if len(out.Events) != len(want) {
|
||||
t.Fatalf("events=%+v", out.Events)
|
||||
}
|
||||
if len(out.ToolEvents) != 1 || out.ToolEvents[0].ID != "tc1" {
|
||||
t.Errorf("tool_events = %+v, want 1 event with id tc1", out.ToolEvents)
|
||||
for i, responseType := range want {
|
||||
if out.Events[i].ResponseType != responseType {
|
||||
t.Errorf("events[%d]=%q, want %q", i, out.Events[i].ResponseType, responseType)
|
||||
}
|
||||
}
|
||||
refs := out.Events[2].KnowledgeReferences
|
||||
if len(refs) != 1 || refs[0].ChunkID != "c1" || refs[0].ParentChunkID != "p1" {
|
||||
t.Errorf("reference indexes=%+v", refs)
|
||||
}
|
||||
if out.Query != "tool question" {
|
||||
t.Errorf("query = %q, want %q", out.Query, "tool question")
|
||||
@@ -529,11 +551,8 @@ func TestTool_SessionAsk(t *testing.T) {
|
||||
c, _ := newTestServer(t, svc)
|
||||
var out sessionAskOutput
|
||||
callTool(t, c, "session_ask", map[string]any{"agent_id": "ag1", "query": "x"}, &out)
|
||||
if out.Answer != "result" {
|
||||
t.Errorf("answer = %q", out.Answer)
|
||||
}
|
||||
if len(out.ToolEvents) != 1 {
|
||||
t.Errorf("tool_calls len = %d, want 1", len(out.ToolEvents))
|
||||
if len(out.Events) != 1 || out.Events[0].ResponseType != "answer" || out.Events[0].Content != "result" {
|
||||
t.Errorf("default events=%+v", out.Events)
|
||||
}
|
||||
if out.AgentID != "ag1" {
|
||||
t.Errorf("agent_id = %q", out.AgentID)
|
||||
|
||||
@@ -65,7 +65,12 @@ func (a *Accumulator) Append(r *sdk.StreamResponse) {
|
||||
a.AssistantMessageID = r.AssistantMessageID
|
||||
}
|
||||
// Capture references whenever they arrive - they may land on a
|
||||
// dedicated `references` event before the terminal `complete`.
|
||||
// dedicated `references` event before the terminal `complete`. Strip the
|
||||
// bulky per-chunk Content so the buffered envelope stays small: agents
|
||||
// consume the index (id / parent_chunk_id / title / score / snippet) and
|
||||
// fetch full passages on demand via `chunk view`. This runs after SSE
|
||||
// parsing, so it governs outgoing envelope size — the incoming line-size
|
||||
// limit is the scanner buffer's job, not this one.
|
||||
if r.KnowledgeReferences != nil {
|
||||
a.References = r.KnowledgeReferences
|
||||
}
|
||||
|
||||
@@ -13,6 +13,9 @@ func TestAgentAccumulator_FinalizesOnlyOnComplete(t *testing.T) {
|
||||
{ResponseType: sdk.AgentResponseTypeThinking, Content: "think", Done: true},
|
||||
{ResponseType: sdk.AgentResponseTypeToolCall, ID: "call_1", Content: "search"},
|
||||
{ResponseType: sdk.AgentResponseTypeReflection, Content: "reflect", Done: true},
|
||||
{ResponseType: sdk.AgentResponseTypeReferences, KnowledgeReferences: []*sdk.SearchResult{
|
||||
{ID: "chunk_1", Content: "bulky passage"},
|
||||
}},
|
||||
{ResponseType: sdk.AgentResponseTypeAnswer, Content: "final answer", Done: true},
|
||||
}
|
||||
for _, event := range preTerminal {
|
||||
@@ -35,6 +38,9 @@ func TestAgentAccumulator_FinalizesOnlyOnComplete(t *testing.T) {
|
||||
if len(a.ToolEvents) != 1 {
|
||||
t.Errorf("tool_events=%d, want 1", len(a.ToolEvents))
|
||||
}
|
||||
if len(a.References) != 1 || a.References[0].Content != "bulky passage" {
|
||||
t.Errorf("references were not preserved: %+v", a.References)
|
||||
}
|
||||
|
||||
a.Append(&sdk.AgentStreamResponse{ResponseType: sdk.AgentResponseTypeAnswer, Content: "late"})
|
||||
if got := a.Answer(); got != "final answer" {
|
||||
|
||||
@@ -0,0 +1,283 @@
|
||||
package sse
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"io"
|
||||
"strings"
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/format"
|
||||
sdk "github.com/Tencent/WeKnora/client"
|
||||
)
|
||||
|
||||
// ProjectedEvent is the bounded event representation shared by
|
||||
// buffered JSON, human-readable text, and MCP tool results. It deliberately
|
||||
// mirrors the SDK field names so consumers can move between projected JSON and
|
||||
// raw NDJSON without learning a second event vocabulary.
|
||||
type ProjectedEvent struct {
|
||||
ID string `json:"id,omitempty"`
|
||||
ResponseType string `json:"response_type"`
|
||||
Content string `json:"content,omitempty"`
|
||||
Done bool `json:"done"`
|
||||
KnowledgeReferences []format.ReferenceIndex `json:"knowledge_references,omitempty"`
|
||||
SessionID string `json:"session_id,omitempty"`
|
||||
AssistantMessageID string `json:"assistant_message_id,omitempty"`
|
||||
ToolCalls []sdk.LLMToolCall `json:"tool_calls,omitempty"`
|
||||
Data map[string]any `json:"data,omitempty"`
|
||||
}
|
||||
|
||||
// Projector observes every SDK frame for lifecycle state, then returns the
|
||||
// presentation event selected by the output contract. Default output keeps
|
||||
// answer frames only. Reference enables bounded citation events; verbose
|
||||
// enables execution and lifecycle events.
|
||||
type Projector struct {
|
||||
verbose bool
|
||||
reference bool
|
||||
fallbackKBID string
|
||||
seen bool
|
||||
done bool
|
||||
sessionID string
|
||||
assistantMessageID string
|
||||
}
|
||||
|
||||
func NewProjector(verbose, reference bool, fallbackKBID string) *Projector {
|
||||
return &Projector{verbose: verbose, reference: reference, fallbackKBID: fallbackKBID}
|
||||
}
|
||||
|
||||
func (p *Projector) Seen() bool { return p.seen }
|
||||
func (p *Projector) Done() bool { return p.done }
|
||||
func (p *Projector) SessionID() string { return p.sessionID }
|
||||
func (p *Projector) AssistantMessageID() string { return p.assistantMessageID }
|
||||
|
||||
// Chat consumes one KnowledgeQAStream frame.
|
||||
func (p *Projector) Chat(r *sdk.StreamResponse) (ProjectedEvent, bool) {
|
||||
if r == nil || p.done {
|
||||
return ProjectedEvent{}, false
|
||||
}
|
||||
p.seen = true
|
||||
if p.sessionID == "" && r.SessionID != "" {
|
||||
p.sessionID = r.SessionID
|
||||
}
|
||||
if p.assistantMessageID == "" && r.AssistantMessageID != "" {
|
||||
p.assistantMessageID = r.AssistantMessageID
|
||||
}
|
||||
if r.ResponseType == sdk.ResponseTypeComplete {
|
||||
p.done = true
|
||||
}
|
||||
|
||||
responseType := string(r.ResponseType)
|
||||
isAnswer := r.ResponseType == sdk.ResponseTypeAnswer || (r.ResponseType == "" && r.Content != "")
|
||||
isReference := r.ResponseType == sdk.ResponseTypeReferences
|
||||
include := isAnswer || (p.verbose && !isReference) || (p.reference && isReference)
|
||||
if !include && p.reference && len(r.KnowledgeReferences) > 0 {
|
||||
return p.chatReferenceEvent(r), true
|
||||
}
|
||||
if !include {
|
||||
return ProjectedEvent{}, false
|
||||
}
|
||||
if responseType == "" {
|
||||
responseType = string(sdk.ResponseTypeAnswer)
|
||||
}
|
||||
event := ProjectedEvent{
|
||||
ID: r.ID,
|
||||
ResponseType: responseType,
|
||||
Content: r.Content,
|
||||
Done: r.Done,
|
||||
SessionID: r.SessionID,
|
||||
AssistantMessageID: r.AssistantMessageID,
|
||||
ToolCalls: r.ToolCalls,
|
||||
Data: r.Data,
|
||||
}
|
||||
if p.reference {
|
||||
event.KnowledgeReferences = format.IndexReferences(r.KnowledgeReferences, p.fallbackKBID)
|
||||
}
|
||||
return event, true
|
||||
}
|
||||
|
||||
// Agent consumes one AgentQAStream frame.
|
||||
func (p *Projector) Agent(r *sdk.AgentStreamResponse) (ProjectedEvent, bool) {
|
||||
if r == nil || p.done {
|
||||
return ProjectedEvent{}, false
|
||||
}
|
||||
p.seen = true
|
||||
if r.ResponseType == sdk.AgentResponseTypeComplete {
|
||||
p.done = true
|
||||
}
|
||||
|
||||
isAnswer := r.ResponseType == sdk.AgentResponseTypeAnswer
|
||||
isReference := r.ResponseType == sdk.AgentResponseTypeReferences
|
||||
include := isAnswer || (p.verbose && !isReference) || (p.reference && isReference)
|
||||
if !include && p.reference && len(r.KnowledgeReferences) > 0 {
|
||||
return p.agentReferenceEvent(r), true
|
||||
}
|
||||
if !include {
|
||||
return ProjectedEvent{}, false
|
||||
}
|
||||
event := ProjectedEvent{
|
||||
ID: r.ID,
|
||||
ResponseType: string(r.ResponseType),
|
||||
Content: r.Content,
|
||||
Done: r.Done,
|
||||
Data: r.Data,
|
||||
}
|
||||
if p.reference {
|
||||
event.KnowledgeReferences = format.IndexReferences(r.KnowledgeReferences, p.fallbackKBID)
|
||||
}
|
||||
return event, true
|
||||
}
|
||||
|
||||
func (p *Projector) chatReferenceEvent(r *sdk.StreamResponse) ProjectedEvent {
|
||||
return ProjectedEvent{
|
||||
ID: r.ID,
|
||||
ResponseType: string(sdk.ResponseTypeReferences),
|
||||
Done: r.Done,
|
||||
KnowledgeReferences: format.IndexReferences(r.KnowledgeReferences, p.fallbackKBID),
|
||||
SessionID: r.SessionID,
|
||||
AssistantMessageID: r.AssistantMessageID,
|
||||
}
|
||||
}
|
||||
|
||||
func (p *Projector) agentReferenceEvent(r *sdk.AgentStreamResponse) ProjectedEvent {
|
||||
return ProjectedEvent{
|
||||
ID: r.ID,
|
||||
ResponseType: string(sdk.AgentResponseTypeReferences),
|
||||
Done: r.Done,
|
||||
KnowledgeReferences: format.IndexReferences(r.KnowledgeReferences, p.fallbackKBID),
|
||||
}
|
||||
}
|
||||
|
||||
// TextRenderer writes projected events as a human-readable stream.
|
||||
// TTY detection is intentionally absent: terminals and pipes receive the same
|
||||
// filtering semantics; callers may add styling later without changing them.
|
||||
type TextRenderer struct {
|
||||
w io.Writer
|
||||
verbose bool
|
||||
lastKey string
|
||||
atBOL bool
|
||||
}
|
||||
|
||||
func NewTextRenderer(w io.Writer, verbose bool) *TextRenderer {
|
||||
return &TextRenderer{w: w, verbose: verbose, atBOL: true}
|
||||
}
|
||||
|
||||
func (r *TextRenderer) Write(ev ProjectedEvent) error {
|
||||
switch ev.ResponseType {
|
||||
case string(sdk.ResponseTypeAnswer):
|
||||
return r.writeContentBlock(ev, "answer")
|
||||
case string(sdk.ResponseTypeThinking), string(sdk.ResponseTypeReflection):
|
||||
return r.writeContentBlock(ev, ev.ResponseType)
|
||||
case string(sdk.ResponseTypeReferences):
|
||||
return r.writeReferences(ev)
|
||||
default:
|
||||
return r.writeStructured(ev)
|
||||
}
|
||||
}
|
||||
|
||||
func (r *TextRenderer) Close() error {
|
||||
if !r.atBOL {
|
||||
return r.writeString("\n")
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func (r *TextRenderer) writeContentBlock(ev ProjectedEvent, label string) error {
|
||||
key := ev.ResponseType + "\x00" + ev.ID
|
||||
if key != r.lastKey {
|
||||
if err := r.ensureBOL(); err != nil {
|
||||
return err
|
||||
}
|
||||
if r.verbose {
|
||||
if err := r.writeString("[" + label + "]\n"); err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
r.lastKey = key
|
||||
}
|
||||
if ev.Content != "" {
|
||||
if err := r.writeString(ev.Content); err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
if ev.Done {
|
||||
r.lastKey = ""
|
||||
return r.ensureBOL()
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func (r *TextRenderer) writeReferences(ev ProjectedEvent) error {
|
||||
if err := r.ensureBOL(); err != nil {
|
||||
return err
|
||||
}
|
||||
if err := r.writeString("[references]\n"); err != nil {
|
||||
return err
|
||||
}
|
||||
for _, ref := range ev.KnowledgeReferences {
|
||||
line := "- chunk_id=" + ref.ChunkID
|
||||
if ref.KBID != "" {
|
||||
line += " kb_id=" + ref.KBID
|
||||
}
|
||||
if ref.ParentChunkID != "" {
|
||||
line += " parent_chunk_id=" + ref.ParentChunkID
|
||||
}
|
||||
if err := r.writeString(line + "\n"); err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
r.lastKey = ""
|
||||
return nil
|
||||
}
|
||||
|
||||
func (r *TextRenderer) writeStructured(ev ProjectedEvent) error {
|
||||
if err := r.ensureBOL(); err != nil {
|
||||
return err
|
||||
}
|
||||
header := "[" + ev.ResponseType
|
||||
if ev.ID != "" {
|
||||
header += " " + ev.ID
|
||||
}
|
||||
header += "]"
|
||||
if err := r.writeString(header); err != nil {
|
||||
return err
|
||||
}
|
||||
if ev.Content != "" {
|
||||
if err := r.writeString(" " + strings.ReplaceAll(ev.Content, "\n", " ")); err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
if len(ev.ToolCalls) > 0 {
|
||||
b, _ := json.Marshal(ev.ToolCalls)
|
||||
if err := r.writeString(" " + string(b)); err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
if len(ev.Data) > 0 {
|
||||
b, _ := json.Marshal(ev.Data)
|
||||
if err := r.writeString(" " + string(b)); err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
if err := r.writeString("\n"); err != nil {
|
||||
return err
|
||||
}
|
||||
r.lastKey = ""
|
||||
return nil
|
||||
}
|
||||
|
||||
func (r *TextRenderer) ensureBOL() error {
|
||||
if r.atBOL {
|
||||
return nil
|
||||
}
|
||||
return r.writeString("\n")
|
||||
}
|
||||
|
||||
func (r *TextRenderer) writeString(s string) error {
|
||||
if s == "" {
|
||||
return nil
|
||||
}
|
||||
if _, err := fmt.Fprint(r.w, s); err != nil {
|
||||
return err
|
||||
}
|
||||
r.atBOL = strings.HasSuffix(s, "\n")
|
||||
return nil
|
||||
}
|
||||
@@ -0,0 +1,137 @@
|
||||
package sse_test
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/sse"
|
||||
sdk "github.com/Tencent/WeKnora/client"
|
||||
)
|
||||
|
||||
func TestProjector_DefaultKeepsOnlyAnswerEvents(t *testing.T) {
|
||||
p := sse.NewProjector(false, false, "kb_fallback")
|
||||
input := []*sdk.StreamResponse{
|
||||
{ID: "think", ResponseType: sdk.ResponseTypeThinking, Content: "hidden"},
|
||||
{ID: "a", ResponseType: sdk.ResponseTypeAnswer, Content: "one", KnowledgeReferences: []*sdk.SearchResult{{ID: "piggyback", Content: "bulk"}}},
|
||||
{ID: "refs", ResponseType: sdk.ResponseTypeReferences, KnowledgeReferences: []*sdk.SearchResult{{ID: "c1", Content: "bulk"}}},
|
||||
{ID: "a", ResponseType: sdk.ResponseTypeAnswer, Content: "two", Done: true},
|
||||
{ResponseType: sdk.ResponseTypeComplete, Done: true},
|
||||
}
|
||||
var got []sse.ProjectedEvent
|
||||
for _, event := range input {
|
||||
if projected, ok := p.Chat(event); ok {
|
||||
got = append(got, projected)
|
||||
}
|
||||
}
|
||||
if !p.Done() || len(got) != 2 {
|
||||
t.Fatalf("done=%v events=%+v", p.Done(), got)
|
||||
}
|
||||
if got[0].Content != "one" || got[1].Content != "two" {
|
||||
t.Errorf("answer order changed: %+v", got)
|
||||
}
|
||||
if len(got[0].KnowledgeReferences) != 0 {
|
||||
t.Errorf("default answer leaked piggyback references: %+v", got[0])
|
||||
}
|
||||
}
|
||||
|
||||
func TestProjector_VerboseAndReferenceIncludeBothDetailClasses(t *testing.T) {
|
||||
p := sse.NewProjector(true, true, "kb_fallback")
|
||||
input := []*sdk.AgentStreamResponse{
|
||||
{ID: "t", ResponseType: sdk.AgentResponseTypeThinking, Content: "think"},
|
||||
{ID: "call", ResponseType: sdk.AgentResponseTypeToolCall, Content: "search"},
|
||||
{ID: "refs", ResponseType: sdk.AgentResponseTypeReferences, KnowledgeReferences: []*sdk.SearchResult{{ID: "c1", KnowledgeBaseID: "kb1", ParentChunkID: "p1", Content: "bulk"}}},
|
||||
{ID: "a", ResponseType: sdk.AgentResponseTypeAnswer, Content: "answer"},
|
||||
{ResponseType: sdk.AgentResponseTypeComplete, Done: true},
|
||||
}
|
||||
var got []sse.ProjectedEvent
|
||||
for _, event := range input {
|
||||
if projected, ok := p.Agent(event); ok {
|
||||
got = append(got, projected)
|
||||
}
|
||||
}
|
||||
want := []string{"thinking", "tool_call", "references", "answer", "complete"}
|
||||
if len(got) != len(want) {
|
||||
t.Fatalf("events=%+v", got)
|
||||
}
|
||||
for i := range want {
|
||||
if got[i].ResponseType != want[i] {
|
||||
t.Errorf("event[%d]=%q, want %q", i, got[i].ResponseType, want[i])
|
||||
}
|
||||
}
|
||||
refs := got[2].KnowledgeReferences
|
||||
if len(refs) != 1 || refs[0].KBID != "kb1" || refs[0].ChunkID != "c1" || refs[0].ParentChunkID != "p1" {
|
||||
t.Errorf("reference index=%+v", refs)
|
||||
}
|
||||
if input[2].KnowledgeReferences[0].Content != "bulk" {
|
||||
t.Error("projection mutated the raw SDK event")
|
||||
}
|
||||
}
|
||||
|
||||
func TestProjector_ReferenceOnlyAddsIndexesWithoutExecutionTrace(t *testing.T) {
|
||||
p := sse.NewProjector(false, true, "kb_fallback")
|
||||
input := []*sdk.AgentStreamResponse{
|
||||
{ID: "think", ResponseType: sdk.AgentResponseTypeThinking, Content: "hidden"},
|
||||
{ID: "refs", ResponseType: sdk.AgentResponseTypeReferences, KnowledgeReferences: []*sdk.SearchResult{{ID: "c1", KnowledgeBaseID: "kb1", Content: "bulk"}}},
|
||||
{ID: "answer", ResponseType: sdk.AgentResponseTypeAnswer, Content: "answer"},
|
||||
{ResponseType: sdk.AgentResponseTypeComplete, Done: true},
|
||||
}
|
||||
var got []sse.ProjectedEvent
|
||||
for _, event := range input {
|
||||
if projected, ok := p.Agent(event); ok {
|
||||
got = append(got, projected)
|
||||
}
|
||||
}
|
||||
if len(got) != 2 || got[0].ResponseType != "references" || got[1].ResponseType != "answer" {
|
||||
t.Fatalf("reference-only events=%+v", got)
|
||||
}
|
||||
if len(got[0].KnowledgeReferences) != 1 || got[0].KnowledgeReferences[0].ChunkID != "c1" {
|
||||
t.Errorf("reference indexes=%+v", got[0].KnowledgeReferences)
|
||||
}
|
||||
}
|
||||
|
||||
func TestProjector_VerboseDoesNotImplicitlyAddReferences(t *testing.T) {
|
||||
p := sse.NewProjector(true, false, "kb")
|
||||
input := []*sdk.AgentStreamResponse{
|
||||
{ResponseType: sdk.AgentResponseTypeThinking, Content: "thinking"},
|
||||
{ResponseType: sdk.AgentResponseTypeReferences, KnowledgeReferences: []*sdk.SearchResult{{ID: "c1"}}},
|
||||
{ResponseType: sdk.AgentResponseTypeAnswer, Content: "answer"},
|
||||
{ResponseType: sdk.AgentResponseTypeComplete, Done: true},
|
||||
}
|
||||
var got []sse.ProjectedEvent
|
||||
for _, event := range input {
|
||||
if projected, ok := p.Agent(event); ok {
|
||||
got = append(got, projected)
|
||||
}
|
||||
}
|
||||
for _, event := range got {
|
||||
if event.ResponseType == "references" || len(event.KnowledgeReferences) != 0 {
|
||||
t.Fatalf("verbose leaked references without reference=true: %+v", got)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestTextRenderer_StreamsSelectedEvents(t *testing.T) {
|
||||
var out bytes.Buffer
|
||||
r := sse.NewTextRenderer(&out, true)
|
||||
events := []sse.ProjectedEvent{
|
||||
{ID: "t", ResponseType: "thinking", Content: "THINK", Done: true},
|
||||
{ID: "call", ResponseType: "tool_call", Content: "SEARCH"},
|
||||
{ID: "a", ResponseType: "answer", Content: "ANSWER", Done: true},
|
||||
}
|
||||
for _, event := range events {
|
||||
if err := r.Write(event); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
}
|
||||
if err := r.Close(); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
got := out.String()
|
||||
thinking := strings.Index(got, "THINK")
|
||||
tool := strings.Index(got, "SEARCH")
|
||||
answer := strings.Index(got, "ANSWER")
|
||||
if !(thinking >= 0 && thinking < tool && tool < answer) {
|
||||
t.Errorf("event order changed: %q", got)
|
||||
}
|
||||
}
|
||||
@@ -17,8 +17,8 @@ one wastes turns or returns the wrong shape. Use the decision table.
|
||||
|
||||
| Your goal | Command | LLM synthesis? | Returns |
|
||||
|---|---|---|---|
|
||||
| Natural-language **answer** grounded in a KB | `chat "<q>" --kb <kb>` | yes | streaming answer + references |
|
||||
| Answer via a **custom agent** (its own KB scope, tools, web search) | `session ask --agent <id> "<q>"` | yes (+ tools) | streaming answer + tool events |
|
||||
| Natural-language **answer** grounded in a KB | `chat "<q>" --kb <kb>` | yes | bounded answer events; `--reference` adds citations; `--verbose` adds execution detail |
|
||||
| Answer via a **custom agent** (its own KB scope, tools, web search) | `session ask --agent <id> "<q>"` | yes (+ tools) | bounded answer events; `--reference` adds citations; `--verbose` adds execution detail |
|
||||
| **Raw context chunks** to reason over yourself (no answer) | `search chunks "<q>" --kb <kb>` | no | ranked chunk list |
|
||||
| Which **documents** match a keyword (title/filename) | `search docs "<q>" --kb <kb>` | no | document list |
|
||||
| Find a **knowledge base** by name | `search kb "<q>"` | no | KB list |
|
||||
@@ -33,9 +33,9 @@ one wastes turns or returns the wrong shape. Use the decision table.
|
||||
<id>` = invoke a *configured custom agent* (it may scope its own KBs, call
|
||||
tools, do web search). If the user set up an agent for this, prefer it
|
||||
(`weknora agent list` to find ids); otherwise `chat`.
|
||||
3. **One-shot vs multi-turn.** Both `chat` and `session ask` print an `init`
|
||||
event with a `session_id`. Pass `--session <id>` on the next call to continue
|
||||
the conversation. See `references/chat.md`.
|
||||
3. **One-shot vs multi-turn.** Both `chat` and `session ask` return a
|
||||
`data.session_id` in default JSON output. Pass `--session <id>` on the next
|
||||
call to continue the conversation. In NDJSON mode, read it from `init`.
|
||||
|
||||
## Safety / Gotchas
|
||||
|
||||
@@ -44,12 +44,14 @@ one wastes turns or returns the wrong shape. Use the decision table.
|
||||
If none resolves it's exit 1 (`local.kb_id_required`); a bad name is exit 1
|
||||
(`local.kb_not_found`). Resolve names with `weknora kb list` / `search kb`.
|
||||
(`search kb` / `search sessions` are tenant-wide and take no `--kb`.)
|
||||
- `chat` / `session ask` stream **NDJSON** by default. Parse line-by-line; keep
|
||||
the `init` event's `session_id` **and** `message_id`. Use `--format text` only
|
||||
for a human transcript.
|
||||
- `chat` / `session ask` return one buffered JSON envelope with answer
|
||||
events by default. Add `--reference` for indexed citations and `--verbose`
|
||||
for execution detail; use `--format ndjson` for raw events or `--format
|
||||
text` for the live human-readable projection.
|
||||
- A stalled stream is not stopped by Ctrl-C (that just drops your local
|
||||
connection; the server keeps generating + billing). Stop it server-side:
|
||||
`weknora session stop <session-id> --message <message-id>` (ids from `init`).
|
||||
`weknora session stop <session-id> --message <message-id>` (session_id from
|
||||
`data.session_id`, or from `init` under `--format ndjson`).
|
||||
Re-attach to a stream with `weknora session continue-stream <session-id>
|
||||
--message <message-id>`.
|
||||
- `search chunks --limit` defaults to **8** (tuned for an LLM context window);
|
||||
@@ -66,7 +68,7 @@ weknora search chunks "retry backoff policy" --kb engineering --limit 12
|
||||
# grounded answer (human transcript)
|
||||
weknora chat "How do we handle retries?" --kb engineering --format text
|
||||
|
||||
# continue the conversation (session id from the prior init event)
|
||||
# continue the conversation (session id from data.session_id above)
|
||||
weknora chat "And the max attempts?" --kb engineering --session sess_abc
|
||||
|
||||
# answer via a custom agent
|
||||
|
||||
@@ -1,8 +1,9 @@
|
||||
# `chat` and `session ask` — streaming RAG
|
||||
# `chat` and `session ask` — RAG answers and raw streams
|
||||
|
||||
Both stream an NDJSON event log (one JSON object per line) by default. They share
|
||||
the same event vocabulary; `chat` does plain KB RAG, `session ask` invokes a
|
||||
custom agent.
|
||||
Both return one buffered JSON envelope with answer events by default.
|
||||
`--reference` adds lookup-index references; `--verbose` adds execution events.
|
||||
They share the raw SSE vocabulary under `--format ndjson`; `chat` does plain KB
|
||||
RAG, `session ask` invokes a custom agent.
|
||||
|
||||
## Commands & flags
|
||||
|
||||
@@ -13,15 +14,20 @@ weknora session ask "<query>" --agent <agent-id> [--session <id>]
|
||||
|
||||
- `--kb` (chat) is required name-or-id. `--agent` (session ask) is required.
|
||||
- `--session <id>` continues an existing conversation; omit to start a new one.
|
||||
- `--format text` renders a human transcript instead of NDJSON; `--format json`
|
||||
/ `--format ndjson` both produce the NDJSON stream (identical here).
|
||||
- `--format json` returns one `{ok,data:{events:[...]}}` envelope; `--format
|
||||
text` streams the same projection as readable text; `--format ndjson` emits
|
||||
the raw event stream.
|
||||
- `--reference` adds bounded reference indexes to JSON/text.
|
||||
- `--verbose` adds thinking, reflection, tool, metadata, and lifecycle events.
|
||||
- Combine them when both provenance and execution detail are needed.
|
||||
|
||||
## Event stream
|
||||
## Event stream (`--format ndjson`)
|
||||
|
||||
The CLI emits an `init` line first, then passes SDK events through verbatim:
|
||||
Under `--format ndjson`, the CLI emits an `init` line first, then passes SDK
|
||||
events through verbatim:
|
||||
|
||||
```jsonc
|
||||
{"event":"init","session_id":"sess_abc","message_id":"msg_xyz","profile":"prod"}
|
||||
{"type":"init","session_id":"sess_abc","kb_id":"…","profile":"prod"} // session ask: agent_id instead of kb_id
|
||||
{"response_type":"thinking","content":"…"}
|
||||
{"response_type":"tool_call","tool_calls":[…]} // agent only
|
||||
{"response_type":"tool_result","content":"…"} // agent only
|
||||
@@ -32,9 +38,9 @@ The CLI emits an `init` line first, then passes SDK events through verbatim:
|
||||
|
||||
- Accumulate `response_type:"answer"` `content` pieces for the final answer.
|
||||
- `knowledge_references` carry the grounding chunks (source attribution).
|
||||
- **Keep `init.session_id` and `init.message_id`**: `session_id` continues the
|
||||
chat (`--session`); `message_id` is needed to `session stop` or
|
||||
`session continue-stream` that specific message.
|
||||
- **Keep `init.session_id`** to continue the chat (`--session`). The
|
||||
`assistant_message_id` needed for `session stop` / `session continue-stream`
|
||||
rides on the SDK's `agent_query` frame, not on `init` — scan for it.
|
||||
- On failure mid-stream you get `response_type:"error"`; a transport/HTTP error
|
||||
surfaces as the normal error envelope on stderr with a typed code.
|
||||
|
||||
|
||||
@@ -57,9 +57,11 @@ Default output is `--format json`: a single envelope.
|
||||
- `error.type` is a **stable typed code** (e.g. `local.kb_not_found`,
|
||||
`input.invalid_argument`, `input.confirmation_required`, `server.error`).
|
||||
Branch on it; `error.hint` usually tells you the next action.
|
||||
- `--format text` = human output. Streaming commands (`chat`, `session ask`,
|
||||
`session continue-stream`) emit **NDJSON event lines** by default — expect a
|
||||
stream, not one blob; use `--format text` for a rendered transcript.
|
||||
- `--format text` = a live human-readable projection. `chat` and `session ask`
|
||||
buffer a bounded answer-event projection into one JSON envelope by default;
|
||||
pass `--reference` for indexed citations, `--verbose` for execution detail,
|
||||
or `--format ndjson` for raw event lines. `session continue-stream` remains
|
||||
an NDJSON streaming command.
|
||||
- `--jq '<expr>'` filters the envelope (e.g. `weknora kb list --jq '.data[].id'`).
|
||||
- Exception: `weknora auth token` emits the **raw token** by default (it's a
|
||||
scripting helper); pass `--format json` for the `{token, mode, profile}` envelope.
|
||||
@@ -165,5 +167,5 @@ that to learn a command without scraping the human help table.
|
||||
| `weknora auth login` before any profile exists | `profile add <n> --host <url> --use` first (§1) |
|
||||
| Expecting `auth login --host/--name` flags | Gone — host comes from the profile; use global `--profile` |
|
||||
| Auto-adding `-y` to clear an exit-10 | Never; get user approval first (§5) |
|
||||
| `weknora chat "..."` prints "garbled" stream | NDJSON by default; use `--format text` for a transcript |
|
||||
| Need the raw `chat` event stream | pass `--format ndjson`; use `--format text` for a live projected transcript |
|
||||
| `search chunks "q"` → exit 1 `local.kb_id_required` | Pass `--kb <name-or-id>`, set `WEKNORA_KB_ID`, or `weknora link` the dir |
|
||||
|
||||
Reference in New Issue
Block a user