feat(cli): agent-first WeKnora CLI

The `weknora` command-line client for the WeKnora RAG server. Full command
surface: kb / doc / chunk / session / message / agent / model / search / chat /
auth / profile / link / api / mcp / skills / config / doctor / schema /
exit-codes.

Agent-first wire contract: JSON envelope by default, typed error codes mapped to
stable exit codes, error.retry_argv / retryable / partial-failure status,
global --dry-run preview, the exit-10 confirmation protocol for writes, and
control/ANSI/Bidi input hygiene. Stateless env-credential auth
(WEKNORA_API_KEY / WEKNORA_TOKEN + WEKNORA_HOST) for headless/CI/agent use.
A curated read-only MCP tool surface (`mcp serve`) and embedded Agent Skills
(`skills install`). Extensive unit + contract-golden tests and CI.
This commit is contained in:
nullkey
2026-06-26 20:40:59 +08:00
committed by lyingbug
parent 445a4330fa
commit 6f8b825f5f
151 changed files with 7305 additions and 733 deletions
+44 -37
View File
@@ -3,9 +3,7 @@ package doc
import (
"context"
"fmt"
"slices"
"sort"
"strings"
"text/tabwriter"
"time"
@@ -48,10 +46,6 @@ type ListOptions struct {
EndTime string // raw RFC3339; parsed into filter.EndTime
}
// rfc3339Example is the canonical RFC3339 hint surfaced when --start-time /
// --end-time fail to parse. Picked to match Go's reference time docs.
const rfc3339Example = "2006-01-02T15:04:05Z"
// docListStatusValues mirrors internal/types/knowledge.go ParseStatus*
// constants - these are the values the server accepts on the
// ?parse_status= query. Kept in sync manually since the SDK doesn't
@@ -88,6 +82,14 @@ backend storage order is not guaranteed and varies between deployments.`,
return err
}
fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
// Validate static input (--page-size / --limit / --status) before
// resolving the KB or building the client so a bad value returns
// input.invalid_argument (exit 5) instead of an auth error (exit 3)
// when the profile is unconfigured — an agent must see the real,
// fixable problem.
if err := validateListOpts(opts); err != nil {
return err
}
kbID, err := f.ResolveKB(c)
if err != nil {
return err
@@ -101,7 +103,7 @@ backend storage order is not guaranteed and varies between deployments.`,
}
cmdutil.AddKBFlag(cmd)
cmd.Flags().IntVar(&opts.PageSize, "page-size", 50, "Items per server batch (1..1000)")
cmd.Flags().IntVarP(&opts.Limit, "limit", "L", 30, "Maximum results to return (1..10000)")
cmd.Flags().IntVarP(&opts.Limit, "limit", "L", 30, "Maximum results to return — client-side cap; meta.has_more/total_count report the full size (1..10000)")
cmd.Flags().BoolVar(&opts.AllPages, "all-pages", false, "Walk all server pages until exhausted (or --limit hit)")
cmd.Flags().StringVar(&opts.Status, "status", "", "Filter by parse status: pending | processing | completed | failed")
cmd.Flags().StringVar(&opts.Keyword, "keyword", "", "Server-side substring match against title / file_name (case-sensitive)")
@@ -114,12 +116,15 @@ backend storage order is not guaranteed and varies between deployments.`,
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
UsedFor: "List documents in the resolved knowledge base. Results come with meta.count; use --limit to cap, --all-pages to walk every server page, --status/--keyword to filter server-side.",
Examples: []string{"weknora doc list --format json", "weknora doc list --all-pages --limit 200 --format json"},
Output: "envelope.data is an array of Knowledge objects with id, title, file_name, parse_status; meta.count is the total returned",
Output: "envelope.data is an array of Knowledge objects with id, title, file_name, parse_status; meta.count is the total returned; meta.total_count is the server-side total before client-side --limit truncation",
})
return cmd
}
func runList(ctx context.Context, opts *ListOptions, fopts *cmdutil.FormatOptions, svc ListService, kbID string) error {
// validateListOpts checks --page-size / --limit / --status. Called from RunE
// before the KB/client are resolved (so bad input surfaces as exit 5, not an
// auth error) and again at the top of runList for direct callers; idempotent.
func validateListOpts(opts *ListOptions) error {
if opts.PageSize < 1 || opts.PageSize > 1000 {
return &cmdutil.Error{
Code: cmdutil.CodeInputInvalidArgument,
@@ -132,12 +137,19 @@ func runList(ctx context.Context, opts *ListOptions, fopts *cmdutil.FormatOption
Message: fmt.Sprintf("--limit must be in 1..10000, got %d", opts.Limit),
}
}
if opts.Status != "" && !validDocListStatus(opts.Status) {
return &cmdutil.Error{
Code: cmdutil.CodeInputInvalidArgument,
Message: fmt.Sprintf("--status must be one of: %s - got %q",
strings.Join(docListStatusValues, " | "), opts.Status),
}
// Validate + normalize --status via the shared enum helper (same exit-5
// path and case-insensitive normalization as every other enum flag).
status, err := cmdutil.ValidateEnum("status", opts.Status, docListStatusValues)
if err != nil {
return err
}
opts.Status = status
return nil
}
func runList(ctx context.Context, opts *ListOptions, fopts *cmdutil.FormatOptions, svc ListService, kbID string) error {
if err := validateListOpts(opts); err != nil {
return err
}
filter := sdk.KnowledgeListFilter{
ParseStatus: opts.Status,
@@ -146,26 +158,25 @@ func runList(ctx context.Context, opts *ListOptions, fopts *cmdutil.FormatOption
Source: opts.Source,
TagID: opts.TagID,
}
if opts.StartTime != "" {
t, err := time.Parse(time.RFC3339, opts.StartTime)
if err != nil {
return cmdutil.NewError(cmdutil.CodeInputInvalidArgument,
fmt.Sprintf("--start-time must be RFC3339 (e.g. %s), got %q", rfc3339Example, opts.StartTime))
}
filter.StartTime = t
start, err := cmdutil.ParseTimeFlag("--start-time", opts.StartTime)
if err != nil {
return err
}
if opts.EndTime != "" {
t, err := time.Parse(time.RFC3339, opts.EndTime)
if err != nil {
return cmdutil.NewError(cmdutil.CodeInputInvalidArgument,
fmt.Sprintf("--end-time must be RFC3339 (e.g. %s), got %q", rfc3339Example, opts.EndTime))
}
filter.EndTime = t
if start != nil {
filter.StartTime = *start
}
end, err := cmdutil.ParseTimeFlag("--end-time", opts.EndTime)
if err != nil {
return err
}
if end != nil {
filter.EndTime = *end
}
// Pagination is always 1-indexed internally. --all-pages walks; the
// non-walking path returns the first page only.
var items []sdk.Knowledge
var serverTotal int64
if opts.AllPages {
accum := make([]sdk.Knowledge, 0)
for page := 1; ; page++ {
@@ -173,6 +184,7 @@ func runList(ctx context.Context, opts *ListOptions, fopts *cmdutil.FormatOption
if err != nil {
return cmdutil.WrapHTTP(err, "list documents")
}
serverTotal = total
accum = append(accum, chunk...)
if opts.Limit > 0 && len(accum) >= opts.Limit {
accum = accum[:opts.Limit]
@@ -184,10 +196,11 @@ func runList(ctx context.Context, opts *ListOptions, fopts *cmdutil.FormatOption
}
items = accum
} else {
chunk, _, err := svc.ListKnowledgeWithFilter(ctx, kbID, 1, opts.PageSize, filter)
chunk, total, err := svc.ListKnowledgeWithFilter(ctx, kbID, 1, opts.PageSize, filter)
if err != nil {
return cmdutil.WrapHTTP(err, "list documents")
}
serverTotal = total
items = chunk
}
if items == nil {
@@ -208,7 +221,7 @@ func runList(ctx context.Context, opts *ListOptions, fopts *cmdutil.FormatOption
}
if fopts.WantsJSON() {
meta := &output.Meta{Count: len(items), HasMore: truncated}
meta := &output.Meta{Count: output.IntPtr(len(items)), HasMore: truncated, TotalCount: output.IntPtr(int(serverTotal))}
return fopts.Emit(iostreams.IO.Out, items, meta)
}
@@ -228,12 +241,6 @@ func runList(ctx context.Context, opts *ListOptions, fopts *cmdutil.FormatOption
return tw.Flush()
}
// validDocListStatus reports whether s matches one of the server-accepted
// parse_status enum values surfaced via --status.
func validDocListStatus(s string) bool {
return slices.Contains(docListStatusValues, s)
}
// formatSize renders a byte count as a short human string (KB / MB).
// Kept tiny on purpose - go-humanize would pull a transitive dep just for one
// column. A "-" placeholder hides zero-size entries (URL / text).