feat(cli): doc/kb resource expansion — upload flags + list filters + view fields

Closes deep-tuning gaps in v0.4-shipped doc / kb / session commands.
Each command had multiple SDK fields the CLI silently hardcoded or
omitted; this commit threads them through.

doc upload:
- --enable-multimodel (tri-state via NoOptDefVal): toggle multimodal
  extraction (PDF/DOCX image-to-text) per upload. Empty explicit
  value (e.g. --enable-multimodel="" from uninterpolated shell var)
  rejected as input.invalid_argument rather than silently coerced.
- --metadata key=value (repeatable): attach arbitrary metadata
- --channel <name> (default api, override for browser / wechat ingests)
- URL mode gains --title / --file-type / --tag-id; URL-only flags
  rejected with input.invalid_argument when used without --from-url

doc list filter flags:
- --keyword (server-side LIKE — case-sensitive per PG)
- --file-type / --source / --tag-id
- --start-time / --end-time (RFC3339)

search docs switches from client-side substring to server-side Keyword
via ListKnowledgeWithFilter — smaller wire payload, but case-sensitivity
shifts (documented in CHANGELOG + help text + Long).

MCP doc_list schema gains the same 6 filter fields (parity with CLI).

session view --full + --limit: loads chat history via LoadMessages SDK
method.

kb view human KV expanded: type / pinned / temporary / processing
state + count / summary model / created timestamp. All omit-empty.

doc view human KV expanded: title (when distinct from filename) /
description / source / channel / summary_status / enable_status /
tag_id / storage (human bytes) / file_hash (12-char prefix).
This commit is contained in:
nullkey
2026-05-16 02:38:48 +08:00
committed by lyingbug
parent 7bccd72ba3
commit f89d54362d
17 changed files with 1280 additions and 79 deletions
+95 -10
View File
@@ -12,30 +12,59 @@ import (
sdk "github.com/Tencent/WeKnora/client"
)
const (
defaultFullLimit = 50
maxFullLimit = 1000
)
// sessionViewFields enumerates the fields surfaced for `--json` discovery on
// `session view`. Mirrors sdk.Session json tags.
// `session view`. Mirrors sdk.Session json tags; adds the synthesized
// `messages` projection surfaced by `--full`.
var sessionViewFields = []string{
"id", "tenant_id", "title", "description", "created_at", "updated_at",
"messages",
}
type ViewOptions struct{}
type ViewOptions struct {
// Full instructs runView to fetch chat history via LoadMessages and
// render it after the session metadata.
Full bool
// Limit caps the number of messages loaded when Full is true.
// Must be 1..maxFullLimit.
Limit int
// LimitSet records whether the caller explicitly set --limit, so we
// can reject `--limit` without `--full` (vs. silently ignoring the
// default).
LimitSet bool
}
// ViewService is the narrow SDK surface this command depends on.
// ViewService is the narrow SDK surface this command depends on. LoadMessages
// is only invoked under --full but lives on the same interface so the runView
// dependency surface stays minimal.
type ViewService interface {
GetSession(ctx context.Context, id string) (*sdk.Session, error)
LoadMessages(ctx context.Context, sessionID string, limit int, beforeTime *time.Time) ([]sdk.Message, error)
}
// NewCmdView builds `weknora session view <id>`. Renders session metadata
// only (title/description/timestamps). Full chat-history retrieval is a
// separate concern (the SDK has LoadMessages / GetMessagesBefore for it);
// surfacing it as `session view --full` is queued for v0.6.
// only by default. With `--full`, also loads the chat history via
// `LoadMessages` and renders messages (or projects them into the JSON
// payload under `messages`).
func NewCmdView(f *cmdutil.Factory) *cobra.Command {
opts := &ViewOptions{}
opts := &ViewOptions{Limit: defaultFullLimit}
cmd := &cobra.Command{
Use: "view <id>",
Short: "Show a chat session by ID",
Args: cobra.ExactArgs(1),
Long: `Show a chat session.
By default renders the session metadata (id, title, description, timestamps).
Pass --full to also load the chat history (LoadMessages SDK call). Use
--limit to cap the number of messages loaded (1..1000, default 50).
--limit without --full is rejected as input.invalid_argument.`,
Args: cobra.ExactArgs(1),
RunE: func(c *cobra.Command, args []string) error {
opts.LimitSet = c.Flags().Changed("limit")
jopts, err := cmdutil.CheckJSONFlags(c)
if err != nil {
return err
@@ -47,18 +76,58 @@ func NewCmdView(f *cmdutil.Factory) *cobra.Command {
return runView(c.Context(), opts, jopts, cli, args[0])
},
}
cmd.Flags().BoolVar(&opts.Full, "full", false, "Also load chat history via LoadMessages")
cmd.Flags().IntVar(&opts.Limit, "limit", defaultFullLimit, "Max messages to load when --full is set (1..1000)")
cmdutil.AddJSONFlags(cmd, sessionViewFields)
return cmd
}
func runView(ctx context.Context, opts *ViewOptions, jopts *cmdutil.JSONOptions, svc ViewService, id string) error {
if !opts.Full && opts.LimitSet {
return &cmdutil.Error{
Code: cmdutil.CodeInputInvalidArgument,
Message: "--limit requires --full",
}
}
if opts.Full {
if opts.Limit < 1 || opts.Limit > maxFullLimit {
return &cmdutil.Error{
Code: cmdutil.CodeInputInvalidArgument,
Message: fmt.Sprintf("--limit must be in 1..%d, got %d", maxFullLimit, opts.Limit),
}
}
}
s, err := svc.GetSession(ctx, id)
if err != nil {
return cmdutil.WrapHTTP(err, "get session %q", id)
}
if jopts.Enabled() {
return jopts.Emit(iostreams.IO.Out, s)
var msgs []sdk.Message
if opts.Full {
msgs, err = svc.LoadMessages(ctx, id, opts.Limit, nil)
if err != nil {
return cmdutil.WrapHTTP(err, "load messages for session %q", id)
}
if msgs == nil {
msgs = []sdk.Message{}
}
}
if jopts.Enabled() {
if !opts.Full {
return jopts.Emit(iostreams.IO.Out, s)
}
// Project session + messages into a single bare object. Use the
// SDK json tags via an embedded *Session so existing keys stay
// stable.
payload := struct {
*sdk.Session
Messages []sdk.Message `json:"messages"`
}{Session: s, Messages: msgs}
return jopts.Emit(iostreams.IO.Out, payload)
}
w := iostreams.IO.Out
fmt.Fprintf(w, "ID: %s\n", s.ID)
if s.Title != "" {
@@ -77,6 +146,22 @@ func runView(ctx context.Context, opts *ViewOptions, jopts *cmdutil.JSONOptions,
} else if s.UpdatedAt != "" {
fmt.Fprintf(w, "UPDATED: %s\n", s.UpdatedAt)
}
if opts.Full {
fmt.Fprintln(w)
fmt.Fprintf(w, "Messages (%d):\n", len(msgs))
for _, m := range msgs {
fmt.Fprintln(w)
ts := ""
if !m.CreatedAt.IsZero() {
ts = " " + m.CreatedAt.Format("2006-01-02 15:04:05")
}
fmt.Fprintf(w, "[%s]%s\n", m.Role, ts)
if m.Content != "" {
fmt.Fprintln(w, m.Content)
}
}
}
return nil
}
+104 -4
View File
@@ -5,6 +5,7 @@ import (
"errors"
"strings"
"testing"
"time"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
@@ -14,11 +15,18 @@ import (
sdk "github.com/Tencent/WeKnora/client"
)
// fakeViewService scripts a GetSession response.
// fakeViewService scripts a GetSession + LoadMessages response.
type fakeViewService struct {
s *sdk.Session
err error
gotID string
s *sdk.Session
err error
gotID string
msgs []sdk.Message
msgsErr error
loadCall struct {
sessionID string
limit int
called bool
}
}
func (f *fakeViewService) GetSession(_ context.Context, id string) (*sdk.Session, error) {
@@ -26,6 +34,13 @@ func (f *fakeViewService) GetSession(_ context.Context, id string) (*sdk.Session
return f.s, f.err
}
func (f *fakeViewService) LoadMessages(_ context.Context, sessionID string, limit int, _ *time.Time) ([]sdk.Message, error) {
f.loadCall.called = true
f.loadCall.sessionID = sessionID
f.loadCall.limit = limit
return f.msgs, f.msgsErr
}
func TestView_Human(t *testing.T) {
out, _ := iostreams.SetForTest(t)
svc := &fakeViewService{s: &sdk.Session{
@@ -74,3 +89,88 @@ func TestView_OmitsEmptyDescription(t *testing.T) {
}
}
}
// --- --full / --limit tests ---
func TestView_Full_LoadsMessages(t *testing.T) {
out, _ := iostreams.SetForTest(t)
svc := &fakeViewService{
s: &sdk.Session{ID: "s_abc", Title: "Chat"},
msgs: []sdk.Message{
{ID: "m1", Role: "user", Content: "What is RAG?", CreatedAt: time.Date(2026, 5, 15, 14, 32, 0, 0, time.UTC)},
{ID: "m2", Role: "assistant", Content: "RAG stands for retrieval-augmented generation.", CreatedAt: time.Date(2026, 5, 15, 14, 32, 5, 0, time.UTC)},
},
}
require.NoError(t, runView(context.Background(), &ViewOptions{Full: true, Limit: 50}, nil, svc, "s_abc"))
got := out.String()
assert.True(t, svc.loadCall.called, "expected LoadMessages to be called")
assert.Equal(t, "s_abc", svc.loadCall.sessionID)
assert.Equal(t, 50, svc.loadCall.limit)
for _, want := range []string{"Messages (2)", "[user]", "[assistant]", "What is RAG?", "retrieval-augmented generation"} {
assert.Contains(t, got, want)
}
}
func TestView_Full_NoMessages(t *testing.T) {
out, _ := iostreams.SetForTest(t)
svc := &fakeViewService{
s: &sdk.Session{ID: "s_empty", Title: "Empty"},
msgs: []sdk.Message{},
}
require.NoError(t, runView(context.Background(), &ViewOptions{Full: true, Limit: 50}, nil, svc, "s_empty"))
got := out.String()
assert.Contains(t, got, "Messages (0)")
}
func TestView_Full_LimitInvalid_Zero(t *testing.T) {
_, _ = iostreams.SetForTest(t)
svc := &fakeViewService{s: &sdk.Session{ID: "s"}}
err := runView(context.Background(), &ViewOptions{Full: true, Limit: 0}, nil, svc, "s")
require.Error(t, err)
assert.Contains(t, err.Error(), "input.invalid_argument")
}
func TestView_Full_LimitInvalid_TooLarge(t *testing.T) {
_, _ = iostreams.SetForTest(t)
svc := &fakeViewService{s: &sdk.Session{ID: "s"}}
err := runView(context.Background(), &ViewOptions{Full: true, Limit: 1001}, nil, svc, "s")
require.Error(t, err)
assert.Contains(t, err.Error(), "input.invalid_argument")
}
// --limit without --full is rejected with input.invalid_argument — same
// pattern as `--title` requires `--from-url` in `doc upload`.
func TestView_LimitWithoutFull(t *testing.T) {
_, _ = iostreams.SetForTest(t)
svc := &fakeViewService{s: &sdk.Session{ID: "s"}}
err := runView(context.Background(), &ViewOptions{Full: false, Limit: 100, LimitSet: true}, nil, svc, "s")
require.Error(t, err)
assert.Contains(t, err.Error(), "input.invalid_argument")
assert.Contains(t, err.Error(), "--limit")
assert.Contains(t, err.Error(), "--full")
}
func TestView_Full_JSON_HasMessages(t *testing.T) {
out, _ := iostreams.SetForTest(t)
svc := &fakeViewService{
s: &sdk.Session{ID: "s_abc", Title: "T"},
msgs: []sdk.Message{
{ID: "m1", Role: "user", Content: "hi"},
},
}
require.NoError(t, runView(context.Background(), &ViewOptions{Full: true, Limit: 50}, &cmdutil.JSONOptions{}, svc, "s_abc"))
body := out.String()
assert.Contains(t, body, `"messages":`)
assert.Contains(t, body, `"id":"m1"`)
assert.Contains(t, body, `"role":"user"`)
}
// Without --full, the LoadMessages SDK call must not fire and the JSON
// payload must not contain a `messages` key.
func TestView_NoFull_DoesNotCallLoadMessages(t *testing.T) {
out, _ := iostreams.SetForTest(t)
svc := &fakeViewService{s: &sdk.Session{ID: "s_abc"}}
require.NoError(t, runView(context.Background(), &ViewOptions{}, &cmdutil.JSONOptions{}, svc, "s_abc"))
assert.False(t, svc.loadCall.called, "LoadMessages must not be called without --full")
assert.NotContains(t, out.String(), `"messages":`)
}