diff --git a/cli/AGENTS.md b/cli/AGENTS.md index 93a287ee..60a0c937 100644 --- a/cli/AGENTS.md +++ b/cli/AGENTS.md @@ -26,7 +26,7 @@ Key packages: - `internal/format/` — bare JSON emitter (`WriteJSON` / `WriteJSONFiltered`) - `internal/iostreams/` — global IO singleton + TTY detection + `SetForTest` swap - `internal/secrets/` — `Store` interface; `KeyringStore` primary, `FileStore` 0600 fallback, `MemStore` for tests -- `internal/prompt/` — `TTYPrompter` (huh-based, password no-echo) + `AgentPrompter` (non-TTY no-prompt sentinel) +- `internal/prompt/` — `TTYPrompter` (password no-echo) + `AgentPrompter` (non-TTY no-prompt sentinel) - `internal/sse/` — `Accumulator` for chat / agent invoke SSE streams - `internal/mcp/` — curated 10-tool stdio MCP server (wired by `cmd/mcp/serve.go`); see [MCP tool surface](#mcp-tool-surface) for the curation rationale and inventory - `client/` (parent module) — generated SDK @@ -195,21 +195,24 @@ Before specifying any CLI command, do this in order: 3. For each field, decide: hot-path flag / config-file only / hidden / never-expose. 4. Cross-check pagination signatures: an SDK `(ctx, id, page, pageSize)` shape demands `--limit` + `--all-pages` + `--page-size` on the CLI side. 5. ONLY THEN consult mainstream CLI conventions to choose flag names, positionals, mutex, and confirm semantics. +6. Decide which fields are "top use case" (flag) / "advanced" (`--config-file` or escape hatch via `weknora api`). Don't try to flag-cover every SDK field — mature CLIs that curate ship a tighter surface; CLIs that 1:1 mirror their API pay the UX cost. Rationale: earlier drafts produced three categories of schema errors — fields that didn't exist on the underlying SDK, wrong field counts in user-facing docs, and missing pagination flags — that all stemmed from "design from convention, not from SDK." The fix is canonical: the SDK schema is the ground truth; convention decides names and shapes around that ground truth. ## CRUD command flag canon -v0.5+ follows **Mode A: hard-required + immediate flag error** for CRUD commands, not Mode B: TTY-prompts-fill (used by `auth login` only). Mode A is the standard pattern for scripted / agent-friendly CLI usage. +CRUD commands follow the **hard-required-flags** pattern: every required input is a flag or positional, and a missing one yields an immediate `input.invalid_argument` exit. The contrast is **TTY-prompts-fill**, where missing input opens an interactive prompt; that pattern is reserved for `auth login` (the one command where a human must be at the terminal). + +Required-input idioms in this codebase: - Positional required: `cobra.ExactArgs(N)` or `cobra.MinimumNArgs(1)` - Flag required: `cmd.MarkFlagRequired("flag")` - Custom required (e.g., `agent edit` needs at-least-one-edit-flag): RunE-level validation that returns `input.invalid_argument` - Mutex: `cmd.MarkFlagsMutuallyExclusive("a", "b")` -Reasons for Mode A: +Reasons hard-required-flags is the v0.5+ default: -- Admin/debug commands are not `auth login` — there is no human-interactive prompt to lean on. +- Admin / debug commands have no natural human-interactive prompt to lean on. - Agent-friendly: MCP callers do not stall waiting for stdin prompts. - Consistent with every existing non-auth WeKnora command. diff --git a/cli/CHANGELOG.md b/cli/CHANGELOG.md index 5c1d79fe..15bd6976 100644 --- a/cli/CHANGELOG.md +++ b/cli/CHANGELOG.md @@ -16,9 +16,10 @@ CLI history before v0.3 is recorded in the project root #### Added - `weknora agent create --model ` / `agent edit ` / - `agent delete ` — hybrid surface (8 hot-path flags + `--config-file` - YAML/JSON tail + `--generate-skeleton` template emit). `--from ` - copies from an existing agent. + `agent delete ` — hybrid surface (hot-path flags for the common + fields + `--config-file` YAML/JSON for the long tail + + `--generate-skeleton` template emit). `--from ` copies + from an existing agent. - `weknora chunk list --doc ` / `chunk view ` / `chunk delete --doc ` — new subtree for RAG retrieval debug. Paginated with v0.4 `--limit` / `--page-size` / `--all-pages` canon. @@ -31,7 +32,7 @@ CLI history before v0.3 is recorded in the project root `--tag-id` / `--start-time` / `--end-time` (RFC3339) — matches the SDK's `KnowledgeListFilter` surface. Time flags reject malformed input with `input.invalid_argument`. -- MCP `doc_list` tool gains the same 5 filter fields (`keyword`, +- MCP `doc_list` tool gains the same 6 filter fields (`keyword`, `file_type`, `source`, `tag_id`, `start_time`, `end_time`) so agents have parity with the CLI. - `weknora session view --full` (with `--limit`, default 50, bounds @@ -47,29 +48,57 @@ CLI history before v0.3 is recorded in the project root distinct from filename), `DESC`, `SOURCE`, `CHANNEL`, `TAG`, `STORAGE` (human-readable bytes), `SUMMARY`, `ENABLED`, and `HASH` (12-char prefix). All omit-empty. +- `weknora doc upload` gains `--enable-multimodel` (tri-state: + unset/true/false), repeatable `--metadata key=value`, and + `--channel` flags. `--enable-multimodel` and `--channel` apply to + file / `--recursive` / `--from-url`; `--metadata` is file / + `--recursive` only (the URL-ingest request carries no metadata + field server-side, so passing it with `--from-url` is rejected + up-front as `input.invalid_argument`). URL mode additionally + accepts `--title`, `--file-type`, and `--tag-id`. Threads through + to the SDK's `CreateKnowledgeFromFile` / `CreateKnowledgeFromURL` + signatures (previously hardcoded to nil/"api" and dropped URL + extras). #### Fixed - MCP `search_chunks` tool: `limit` arg now correctly threads into `SearchParams.MatchCount`. Previously the server's default cap won, silently capping below the requested limit. -- `search sessions` human time format: now uses `fuzzyTime` like - `session list` instead of raw RFC3339. +- `search sessions` human time format: now renders a relative + duration ("2 hours ago") matching `session list`, instead of raw + RFC3339. +- `doc upload` (file path): re-uploading a file already ingested into + the KB now surfaces as `resource.already_exists` (exit 1) instead of + the misleading `network.error` ("check base URL reachability"). The + SDK returns its `ErrDuplicateFile` sentinel with no `HTTP error :` + prefix because the duplicate is detected via file-hash short-circuit, + not by HTTP status; the previous fall-through to `WrapHTTP` therefore + misclassified it. The `--from-url` branch already handled the + symmetric `ErrDuplicateURL` correctly. + +#### Breaking changes +- `weknora search docs` now applies the keyword filter server-side via + `ListKnowledgeWithFilter` (was: page through every doc and + substring-match client-side). Smaller wire payload on large KBs. + **The match is now case-sensitive** (server uses `LIKE %keyword%`), + whereas the previous client-side path lowered both sides. Callers + that relied on case-insensitive matching (e.g. `search docs Q3` + finding `q3 retro`) must lower-case the query themselves, or fall + back to `weknora api` with a custom filter. #### Changed - `cli/AGENTS.md` MCP curation rationale rewritten: curated read-only - is a deliberate product call gated on server-side token scope, not - MCP industry canon. -- `cli/AGENTS.md` adds §"Command surface design SOP" and - §"CRUD command flag canon" for v0.6+ contributors. -- `cli/go.mod`: adds `gopkg.in/yaml.v3` for `agent create --config-file`. -- `weknora search docs` now applies the keyword filter server-side via - `ListKnowledgeWithFilter` (was: page through every doc and substring- - match client-side). Smaller wire payload on large KBs. **Semantics - shift**: the match is now case-sensitive (server uses `LIKE %keyword%`), - whereas the previous client-side path lowered both sides. Callers that - relied on case-insensitive matching (e.g. `search docs Q3` finding - `q3 retro`) must lower-case the query, or fall back to `weknora api` - with a custom filter. + is a deliberate product call gated on the absence of server-side + per-token scope. When server-side scope ships, mutation tools can + land in the MCP surface. +- `cli/AGENTS.md` adds "Command surface design SOP" and "CRUD command + flag canon" sections for future contributors. The design-SOP + section includes a step reminding contributors to decide + flag-vs-escape-hatch per field rather than trying to flag-mirror + every SDK capability. +- `cli/README.md` now documents the `weknora api` raw HTTP passthrough + as the canonical escape hatch for deep KB config, per-request `chat` + / `agent invoke` overrides, and operations without a CLI verb. ### v0.4 — output contract hardening and mainstream alignment @@ -82,10 +111,10 @@ CLI history before v0.3 is recorded in the project root non-TTY callers that omit `-y` exit with code 10 and `input.confirmation_required` so an agent must surface the prompt to a human before retrying. -- Dropped the per-command AI footer that rendered when `CLAUDECODE` - or `CURSOR_AGENT` was set. The same machine-readable guidance now - lives in the standard `--help` (visible to all callers) and in - `mcp serve`'s tool descriptions. +- Dropped the per-command AI footer that rendered when AI-coding-agent + env detection fired. The same machine-readable guidance now lives in + the standard `--help` (visible to all callers) and in `mcp serve`'s + tool descriptions. #### Added - `weknora mcp serve` — curated read-only stdio MCP server exposing 9 @@ -152,8 +181,7 @@ CLI history before v0.3 is recorded in the project root passthrough (file or stdin); mutually exclusive with `--data`. - `unlink` — remove the cwd's `.weknora/project.yaml` so subsequent commands stop auto-resolving `--kb` from it. Walks up from cwd so a - user in a subdirectory can unlink without cd-ing to the project root - (mirrors `vercel unlink` / `netlify unlink`). + user in a subdirectory can unlink without cd-ing to the project root. - Completion smoke test guards against cobra bumps silently breaking bash / zsh / fish / powershell completion. diff --git a/cli/README.md b/cli/README.md index 3681c1f4..fca2d612 100644 --- a/cli/README.md +++ b/cli/README.md @@ -14,6 +14,7 @@ Available Commands: api Make a raw API request to the WeKnora server auth Manage authentication credentials and contexts chat Ask a streaming RAG question against a knowledge base + chunk Manage document chunks (RAG retrieval debug) completion Generate the autocompletion script for the specified shell context Manage CLI contexts (named connection targets) doc Manage documents in a knowledge base @@ -28,10 +29,9 @@ Available Commands: version Show CLI build metadata ``` -The command surface mirrors `gh` CLI's ` ` convention. The -wire contract for AI agents (Claude Code, Cursor, Aider, …) is documented -[below](#wire-contract). For contributing to the CLI source, see -[AGENTS.md](AGENTS.md). +The command surface follows a ` ` convention. The wire +contract for AI agents is documented [below](#wire-contract). For +contributing to the CLI source, see [AGENTS.md](AGENTS.md). --- @@ -78,6 +78,13 @@ weknora search chunks "what is reciprocal rank fusion?" # 7. Ask the LLM (streams to terminal) weknora chat "summarise the design doc" + +# 8. Manage custom agents (full hybrid surface: see `weknora agent --help`) +weknora agent list +weknora agent invoke ag_abc "what's our q4 retention plan?" + +# 9. Inspect a document's chunks for RAG retrieval debug +weknora chunk list --doc doc_xyz ``` --- @@ -179,9 +186,9 @@ The full code registry is in `cli/internal/cmdutil/errors.go` **Exit 10** is the wire-level signal for "destructive write needs explicit confirmation". Pass `-y/--yes` on `kb delete` / `kb empty` / `doc delete` / `session delete` / `context remove` (on the current -context) when running headless. **Never auto-add `-y` without the -user's explicit go-ahead** — exit 10 is the guard against unintended -writes. +context) / `agent delete` / `chunk delete` when running headless. +**Never auto-add `-y` without the user's explicit go-ahead** — exit 10 +is the guard against unintended writes. ### Other agent ergonomics @@ -189,8 +196,32 @@ writes. — streaming tokens to stdout makes JSON parsing impossible. - `--json` composes with the global `--context ` for single-shot context overrides without disk writes. -- `weknora mcp serve` exposes a curated readonly tool surface over - stdio MCP for Claude Desktop / Code / custom MCP clients. +- `weknora mcp serve` exposes a curated read-only tool surface over + stdio MCP for any MCP-compatible client. + +--- + +## Advanced operations not exposed as flags + +WeKnora CLI exposes top use cases as polished commands; deep +configuration goes through the raw HTTP passthrough. CLI flag coverage +targets common workflows, not 1:1 API parity. Examples of deep +operations that intentionally go through `weknora api`: + +- **Tuning a KB's nested config** — chunking strategy, summary model, + multimodal extraction defaults, FAQ thresholds, VLM model, storage + provider. Use `weknora api PUT /api/v1/knowledge-bases/ --input -` + with a JSON body matching the server's `UpdateKnowledgeBaseRequest`. +- **Per-request `chat` parameters** — multi-KB scope, summary model + override, image attachments, web search toggle. Use `weknora api POST + /api/v1/knowledge-chat/ --input -`. +- **Per-request `agent invoke` overrides** — same shape via + `weknora api POST /api/v1/agent-chat/ --input -`. +- **Operations without a CLI verb** — register / change-password / + OIDC flows, organization / sharing endpoints, tenant management. + +`weknora api --help` documents the raw passthrough. Run +`weknora doctor` first to verify auth and base URL. --- @@ -221,6 +252,20 @@ macOS / Windows × Go 1.26, path-filtered to changes under `cli/`. --- +## Contributing / Reporting issues + +- **Bugs and feature requests**: file an issue at + [github.com/Tencent/WeKnora/issues](https://github.com/Tencent/WeKnora/issues). +- **Security disclosures**: see the repository-level + [SECURITY.md](../SECURITY.md). Do not file public issues for + security findings. +- **Pull requests**: the developer guide for editing the CLI lives in + [AGENTS.md](AGENTS.md) (build / test / command-surface design SOP / + CRUD flag canon). Run `go test ./... -race -count=1` and `go vet ./...` + before submitting. + +--- + ## License MIT — see the repository [LICENSE](../LICENSE). diff --git a/cli/acceptance/contract/helpers_test.go b/cli/acceptance/contract/helpers_test.go index 5848cfc5..470e2daf 100644 --- a/cli/acceptance/contract/helpers_test.go +++ b/cli/acceptance/contract/helpers_test.go @@ -35,8 +35,6 @@ func TestMain(m *testing.M) { // update is the standard Go test golden-update flag. // // go test -update ./acceptance/contract/... -// -// Mirrors gh / kubectl / golang-migrate convention. var update = flag.Bool("update", false, "update golden files") // newTestFactory builds a Factory whose Client returns mockClient. diff --git a/cli/acceptance/contract/wire_test.go b/cli/acceptance/contract/wire_test.go index 54ae1ceb..eb23e829 100644 --- a/cli/acceptance/contract/wire_test.go +++ b/cli/acceptance/contract/wire_test.go @@ -157,10 +157,10 @@ var wireCases = []wireCase{ wantStderrSubstring: "auth.unauthenticated", }, - // 11-13. search chunks - verb-noun shape (gh search parity), positional query, --kb required. - // --kb accepts either kb_ (passed through) or a name (resolved via - // list); UUID-format detection happens client-side, mirroring gcloud - // --project's id-or-name auto-detection. + // 11-13. search chunks - verb-noun shape, positional query, --kb required. + // --kb accepts either a kb_ (passed through) or a name (resolved via + // list); UUID-format detection happens client-side so callers can use + // either form interchangeably. { name: "search.success", args: []string{"search", "chunks", "query", "--kb=11111111-1111-4111-8111-111111111111", "--limit=3", "--json"}, diff --git a/cli/acceptance/e2e/e2e_test.go b/cli/acceptance/e2e/e2e_test.go index cf92b965..8b93e906 100644 --- a/cli/acceptance/e2e/e2e_test.go +++ b/cli/acceptance/e2e/e2e_test.go @@ -4,8 +4,8 @@ // server to validate the RAG closing loop end-to-end. // // Build tag isolation: //go:build acceptance_e2e excludes this file from -// the default `go test ./...` (mirrors gh's acceptance/ build tag pattern; -// see https://github.com/cli/cli/tree/trunk/acceptance). To run: +// the default `go test ./...` so the e2e suite only runs when explicitly +// requested. To run: // // cd cli // WEKNORA_E2E_HOST=https://kb.example.com \ diff --git a/cli/cmd/agent/create.go b/cli/cmd/agent/create.go index c51f6a65..4f0e43f1 100644 --- a/cli/cmd/agent/create.go +++ b/cli/cmd/agent/create.go @@ -4,7 +4,6 @@ import ( "context" "fmt" "io" - "os" "path/filepath" "strings" @@ -58,11 +57,11 @@ type createFlagSet struct { kbsSet bool } -const agentCreateExample = ` weknora agent create "Support Bot" --model gpt-4 - weknora agent create "Code Reviewer" --model gpt-4 --system-prompt-file ./prompt.md --kb kb_eng --kb kb_arch - weknora agent create "From Template" --model gpt-4 --from ag_existing +const agentCreateExample = ` weknora agent create "Support Bot" --model + weknora agent create "Code Reviewer" --model --system-prompt-file ./prompt.md --kb kb_eng --kb kb_arch + weknora agent create "From Template" --model --from ag_existing weknora agent create --generate-skeleton > my-agent.yaml - weknora agent create "Tuned" --model gpt-4 --config-file ./my-agent.yaml` + weknora agent create "Tuned" --model --config-file ./my-agent.yaml` const agentCreateLong = `Create a new custom agent. @@ -114,17 +113,16 @@ func NewCmdCreate(f *cmdutil.Factory) *cobra.Command { opts.flags.kbSelectionModeSet = cmd.Flags().Changed("kb-selection-mode") opts.flags.kbsSet = cmd.Flags().Changed("kb") - // L-5 / §1.5.1: --temperature is bounded 0.0..2.0. Reject - // out-of-range early with a typed input.invalid_argument so - // users don't burn a roundtrip on a value the server would - // also reject. + // --temperature is bounded 0.0..2.0. Reject out-of-range + // early with a typed input.invalid_argument so users don't + // burn a roundtrip on a value the server would also reject. if opts.flags.temperatureSet && (opts.Temperature < 0.0 || opts.Temperature > 2.0) { return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, fmt.Sprintf("--temperature must be in 0.0..2.0, got %g", opts.Temperature)) } if systemPromptFile != "" { - r, err := openInput(systemPromptFile) + r, err := cmdutil.OpenInput(systemPromptFile) if err != nil { return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, fmt.Sprintf("--system-prompt-file: %v", err)) } @@ -219,7 +217,7 @@ func runCreate(ctx context.Context, opts *CreateOptions, jopts *cmdutil.JSONOpti base = *copied.Config } - // --kb on --from REPLACES the copied KB list (per spec); when --kb + // --kb on --from REPLACES the copied KB list; when --kb // is not set, KnowledgeBasesSet stays false inside applyCreateOverrides // and the copy's KB list passes through unchanged. cfg := applyCreateOverrides(&base, opts) @@ -278,18 +276,10 @@ func applyCreateOverrides(base *sdk.AgentConfig, opts *CreateOptions) *sdk.Agent return cfg } -// openInput returns a Reader for path; "-" means the global stdin. -func openInput(path string) (io.Reader, error) { - if path == "-" { - return iostreams.IO.In, nil - } - return os.Open(path) -} - // openConfigFile returns a Reader, the detected kind ("yaml"/"json"), or // an error. Format is inferred from file extension; "-" defaults to YAML. func openConfigFile(path string) (io.Reader, string, error) { - r, err := openInput(path) + r, err := cmdutil.OpenInput(path) if err != nil { return nil, "", err } diff --git a/cli/cmd/agent/create_test.go b/cli/cmd/agent/create_test.go index afaacde0..a5f72926 100644 --- a/cli/cmd/agent/create_test.go +++ b/cli/cmd/agent/create_test.go @@ -48,18 +48,18 @@ func (f *fakeCreateSvc) UpdateAgent(_ context.Context, id string, req *sdk.Updat func TestCreate_HappyPath_MinimalRequired(t *testing.T) { _, _ = iostreams.SetForTest(t) svc := &fakeCreateSvc{createResp: &sdk.Agent{ID: "ag_new", Name: "Test"}} - opts := &CreateOptions{Name: "Test", Model: "gpt-4"} + opts := &CreateOptions{Name: "Test", Model: "model-x"} err := runCreate(context.Background(), opts, &cmdutil.JSONOptions{}, svc) require.NoError(t, err) require.NotNil(t, svc.createReq) assert.Equal(t, "Test", svc.createReq.Name) require.NotNil(t, svc.createReq.Config) - assert.Equal(t, "gpt-4", svc.createReq.Config.ModelID) + assert.Equal(t, "model-x", svc.createReq.Config.ModelID) } func TestCreate_MissingName_FlagError(t *testing.T) { cmd := NewCmdCreate(nil) - cmd.SetArgs([]string{"--model", "gpt-4"}) + cmd.SetArgs([]string{"--model", "model-x"}) cmd.SilenceUsage = true cmd.SilenceErrors = true err := cmd.Execute() @@ -84,31 +84,31 @@ func TestCreate_ConfigFile_FlagsOverrideFile(t *testing.T) { svc := &fakeCreateSvc{createResp: &sdk.Agent{ID: "ag_new"}} opts := &CreateOptions{ Name: "Test", - Model: "gpt-4", // override file - ConfigFileBody: bytes.NewBufferString(`{"agent_mode":"smart-reasoning","model_id":"gpt-3.5","temperature":0.5}`), + Model: "model-x", // override file + ConfigFileBody: bytes.NewBufferString(`{"agent_mode":"smart-reasoning","model_id":"model-y","temperature":0.5}`), ConfigFileKind: "json", } require.NoError(t, runCreate(context.Background(), opts, &cmdutil.JSONOptions{}, svc)) require.NotNil(t, svc.createReq.Config) assert.Equal(t, "smart-reasoning", svc.createReq.Config.AgentMode, "file value preserved when no flag override") - assert.Equal(t, "gpt-4", svc.createReq.Config.ModelID, "flag overrides file") + assert.Equal(t, "model-x", svc.createReq.Config.ModelID, "flag overrides file") assert.InDelta(t, 0.5, svc.createReq.Config.Temperature, 0.001) } func TestCreate_From_CopiesThenUpdates(t *testing.T) { _, _ = iostreams.SetForTest(t) svc := &fakeCreateSvc{ - copyResp: &sdk.Agent{ID: "ag_clone", Name: "Source", Config: &sdk.AgentConfig{ModelID: "gpt-3.5"}}, + copyResp: &sdk.Agent{ID: "ag_clone", Name: "Source", Config: &sdk.AgentConfig{ModelID: "model-y"}}, updateResp: &sdk.Agent{ID: "ag_clone", Name: "Renamed"}, } - opts := &CreateOptions{Name: "Renamed", Model: "gpt-4", From: "ag_source"} + opts := &CreateOptions{Name: "Renamed", Model: "model-x", From: "ag_source"} require.NoError(t, runCreate(context.Background(), opts, &cmdutil.JSONOptions{}, svc)) assert.Equal(t, "ag_source", svc.copySrcID) require.True(t, svc.updateCalled, "must Update after Copy when overrides present") assert.Equal(t, "ag_clone", svc.updateID) assert.Equal(t, "Renamed", svc.updateReq.Name) require.NotNil(t, svc.updateReq.Config) - assert.Equal(t, "gpt-4", svc.updateReq.Config.ModelID) + assert.Equal(t, "model-x", svc.updateReq.Config.ModelID) } func TestCreate_GenerateSkeleton_NoAPICall(t *testing.T) { @@ -126,7 +126,7 @@ func TestCreate_RepeatedKB_ImpliesSelectedMode(t *testing.T) { svc := &fakeCreateSvc{createResp: &sdk.Agent{ID: "ag_new"}} opts := &CreateOptions{ Name: "Test", - Model: "gpt-4", + Model: "model-x", KBs: []string{"kb_a", "kb_b"}, flags: createFlagSet{kbsSet: true}, } @@ -140,7 +140,7 @@ func TestCreate_SystemPromptFile_ReaderRead(t *testing.T) { svc := &fakeCreateSvc{createResp: &sdk.Agent{ID: "ag_new"}} opts := &CreateOptions{ Name: "Test", - Model: "gpt-4", + Model: "model-x", SystemPromptReader: strings.NewReader("You are a helpful assistant.\n"), flags: createFlagSet{systemPromptSet: true}, } @@ -157,7 +157,7 @@ func TestCreate_From_PreservesSourceFieldsNotOverridden(t *testing.T) { _, _ = iostreams.SetForTest(t) svc := &fakeCreateSvc{ copyResp: &sdk.Agent{ID: "ag_clone", Config: &sdk.AgentConfig{ - ModelID: "gpt-3.5", + ModelID: "model-y", SystemPrompt: "Source prompt", AgentMode: "smart-reasoning", Temperature: 0.5, @@ -167,7 +167,7 @@ func TestCreate_From_PreservesSourceFieldsNotOverridden(t *testing.T) { } // Only --temperature overridden; other fields should round-trip. opts := &CreateOptions{ - Name: "Renamed", Model: "gpt-3.5", From: "ag_source", + Name: "Renamed", Model: "model-y", From: "ag_source", Temperature: 0.9, flags: createFlagSet{temperatureSet: true}, } @@ -181,17 +181,20 @@ func TestCreate_From_PreservesSourceFieldsNotOverridden(t *testing.T) { } func TestCreate_From_KBReplacesSourceList(t *testing.T) { - // --kb on --from REPLACES the copied agent's KB list (spec §2.1). + // --kb on --from REPLACES the copied agent's KB list (instead of + // merging with it). The override semantic matches a from-scratch + // `agent create --kb a --kb b`: whatever was on the source agent is + // discarded for KBs the caller explicitly listed. _, _ = iostreams.SetForTest(t) svc := &fakeCreateSvc{ copyResp: &sdk.Agent{ID: "ag_clone", Config: &sdk.AgentConfig{ - ModelID: "gpt-3.5", + ModelID: "model-y", KnowledgeBases: []string{"kb_src_a", "kb_src_b"}, }}, updateResp: &sdk.Agent{ID: "ag_clone"}, } opts := &CreateOptions{ - Name: "X", Model: "gpt-3.5", From: "ag_source", + Name: "X", Model: "model-y", From: "ag_source", KBs: []string{"kb_new"}, flags: createFlagSet{kbsSet: true}, } @@ -205,7 +208,7 @@ func TestCreate_Temperature_Bounds(t *testing.T) { for _, badT := range []float64{-0.1, 2.1, 100.0} { t.Run(fmt.Sprintf("t=%g", badT), func(t *testing.T) { cmd := NewCmdCreate(nil) - cmd.SetArgs([]string{"Test", "--model", "gpt-4", "--temperature", fmt.Sprintf("%f", badT)}) + cmd.SetArgs([]string{"Test", "--model", "model-x", "--temperature", fmt.Sprintf("%f", badT)}) cmd.SilenceUsage = true cmd.SilenceErrors = true err := cmd.Execute() @@ -218,7 +221,7 @@ func TestCreate_Temperature_Bounds(t *testing.T) { func TestCreate_CopyAgent_NotFound(t *testing.T) { _, _ = iostreams.SetForTest(t) svc := &fakeCreateSvc{copyErr: errBadHTTP404} - opts := &CreateOptions{Name: "X", Model: "gpt-4", From: "ag_missing"} + opts := &CreateOptions{Name: "X", Model: "model-x", From: "ag_missing"} err := runCreate(context.Background(), opts, &cmdutil.JSONOptions{}, svc) require.Error(t, err) assert.Contains(t, err.Error(), "resource.not_found") diff --git a/cli/cmd/agent/delete.go b/cli/cmd/agent/delete.go index 0343c745..e74e8e68 100644 --- a/cli/cmd/agent/delete.go +++ b/cli/cmd/agent/delete.go @@ -15,7 +15,6 @@ import ( // Result payload is a tiny {id, deleted} object — mirrors `kb delete`. var agentDeleteFields = []string{"id", "deleted"} -// DeleteOptions captures `agent delete` flag state. type DeleteOptions struct { AgentID string Yes bool // sourced from the global -y/--yes persistent flag diff --git a/cli/cmd/agent/edit.go b/cli/cmd/agent/edit.go index bb7c4a66..09e3e71d 100644 --- a/cli/cmd/agent/edit.go +++ b/cli/cmd/agent/edit.go @@ -117,15 +117,15 @@ func NewCmdEdit(f *cmdutil.Factory) *cobra.Command { opts.flags.kbSelectionModeSet = cmd.Flags().Changed("kb-selection-mode") opts.flags.configFileSet = cmd.Flags().Changed("config-file") - // L-5 / §1.5.1: --temperature is bounded 0.0..2.0. Reject - // out-of-range early with a typed input.invalid_argument. + // --temperature is bounded 0.0..2.0. Reject out-of-range + // early with a typed input.invalid_argument. if opts.flags.temperatureSet && (opts.Temperature < 0.0 || opts.Temperature > 2.0) { return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, fmt.Sprintf("--temperature must be in 0.0..2.0, got %g", opts.Temperature)) } if systemPromptFile != "" { - r, err := openInput(systemPromptFile) + r, err := cmdutil.OpenInput(systemPromptFile) if err != nil { return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, fmt.Sprintf("--system-prompt-file: %v", err)) } @@ -194,7 +194,7 @@ func runEdit(ctx context.Context, opts *EditOptions, jopts *cmdutil.JSONOptions, } } - // L-2 fetch-then-update so omitted fields round-trip unchanged through + // Fetch-then-update so omitted fields round-trip unchanged through // the full PUT body. current, err := svc.GetAgent(ctx, opts.AgentID) if err != nil { diff --git a/cli/cmd/agent/edit_test.go b/cli/cmd/agent/edit_test.go index f96a7274..a05d29d5 100644 --- a/cli/cmd/agent/edit_test.go +++ b/cli/cmd/agent/edit_test.go @@ -44,7 +44,7 @@ func TestEdit_FetchThenUpdate_PreservesUntouchedFields(t *testing.T) { svc := &fakeEditSvc{ getResp: &sdk.Agent{ ID: "ag_abc", Name: "Original", Description: "Keep me", - Config: &sdk.AgentConfig{ModelID: "gpt-4", Temperature: 0.7, KnowledgeBases: []string{"kb_a"}}, + Config: &sdk.AgentConfig{ModelID: "model-x", Temperature: 0.7, KnowledgeBases: []string{"kb_a"}}, }, updateResp: &sdk.Agent{ID: "ag_abc"}, } @@ -59,7 +59,7 @@ func TestEdit_FetchThenUpdate_PreservesUntouchedFields(t *testing.T) { assert.Equal(t, "Original", svc.updateReq.Name, "Name must round-trip unchanged") assert.Equal(t, "Updated", svc.updateReq.Description) require.NotNil(t, svc.updateReq.Config) - assert.Equal(t, "gpt-4", svc.updateReq.Config.ModelID, "ModelID must round-trip") + assert.Equal(t, "model-x", svc.updateReq.Config.ModelID, "ModelID must round-trip") assert.Equal(t, []string{"kb_a"}, svc.updateReq.Config.KnowledgeBases, "KBs must round-trip") assert.InDelta(t, 0.7, svc.updateReq.Config.Temperature, 0.001) } diff --git a/cli/cmd/agent/view.go b/cli/cmd/agent/view.go index 80f2344b..037c44da 100644 --- a/cli/cmd/agent/view.go +++ b/cli/cmd/agent/view.go @@ -10,9 +10,15 @@ import ( "github.com/Tencent/WeKnora/cli/internal/cmdutil" "github.com/Tencent/WeKnora/cli/internal/iostreams" + "github.com/Tencent/WeKnora/cli/internal/text" sdk "github.com/Tencent/WeKnora/client" ) +// promptPreviewWidth caps inline KV row prompt previews. Multi-line prompts +// collapse to one line via text.OneLine; the Templates section gets the +// full multi-line treatment instead. +const promptPreviewWidth = 80 + // agentViewFields enumerates fields surfaced for `--json=` field discovery // on `agent view`. Only top-level Agent keys are listed because the // `--json=foo,bar` field-projection filter matches flat top-level keys @@ -77,9 +83,9 @@ func runView(ctx context.Context, jopts *cmdutil.JSONOptions, svc ViewService, a } // renderAgent prints a single agent in human-readable form, grouped into -// 10 presentation sections (spec §2.9). Zero-value fields are omitted; -// a section header prints only when at least one of its fields is set. -// Group labels and order match the spec exactly so spec drift surfaces +// 10 presentation sections. Zero-value fields are omitted; a section +// header prints only when at least one of its fields is set. Group +// labels and order are pinned by snapshot tests so future drift surfaces // as test failure rather than silent divergence. func renderAgent(w io.Writer, a *sdk.Agent) { // Identity is always rendered — id/name/created_at/updated_at are @@ -186,10 +192,10 @@ func renderAgent(w io.Writer, a *sdk.Agent) { qr = append(qr, row{"Query understand model ID", c.QueryUnderstandModelID}) } if c.RewritePromptSystem != "" { - qr = append(qr, row{"Rewrite prompt (system)", truncate1Line(c.RewritePromptSystem)}) + qr = append(qr, row{"Rewrite prompt (system)", text.OneLine(promptPreviewWidth, c.RewritePromptSystem)}) } if c.RewritePromptUser != "" { - qr = append(qr, row{"Rewrite prompt (user)", truncate1Line(c.RewritePromptUser)}) + qr = append(qr, row{"Rewrite prompt (user)", text.OneLine(promptPreviewWidth, c.RewritePromptUser)}) } emit("Query rewrite", qr) @@ -251,7 +257,7 @@ func renderAgent(w io.Writer, a *sdk.Agent) { fb = append(fb, row{"Response", c.FallbackResponse}) } if c.FallbackPrompt != "" { - fb = append(fb, row{"Prompt", truncate1Line(c.FallbackPrompt)}) + fb = append(fb, row{"Prompt", text.OneLine(promptPreviewWidth, c.FallbackPrompt)}) } emit("Fallback", fb) @@ -271,18 +277,6 @@ func renderAgent(w io.Writer, a *sdk.Agent) { } } -// truncate1Line collapses newlines and clips long values for inline KV -// rows. Templates section gets full multi-line treatment instead. -func truncate1Line(s string) string { - s = strings.ReplaceAll(s, "\n", " ") - s = strings.ReplaceAll(s, "\r", " ") - const max = 80 - if len(s) > max { - return s[:max-3] + "..." - } - return s -} - // writeIndented prints s with the given prefix on every line. Trailing // newline always added so the next section starts on its own line. func writeIndented(w io.Writer, s, prefix string) { diff --git a/cli/cmd/agent/view_test.go b/cli/cmd/agent/view_test.go index 4266f165..e251baf7 100644 --- a/cli/cmd/agent/view_test.go +++ b/cli/cmd/agent/view_test.go @@ -82,7 +82,7 @@ func TestRenderAgent_RendersAllGroupsWithOmitEmpty(t *testing.T) { Config: &sdk.AgentConfig{ AgentMode: "smart-reasoning", SystemPrompt: "You help users.", - ModelID: "gpt-4", + ModelID: "model-x", Temperature: 0.7, KBSelectionMode: "selected", KnowledgeBases: []string{"kb_a"}, @@ -101,7 +101,7 @@ func TestRenderAgent_RendersAllGroupsWithOmitEmpty(t *testing.T) { } } // Set fields rendered: - for _, want := range []string{"smart-reasoning", "gpt-4", "You help users."} { + for _, want := range []string{"smart-reasoning", "model-x", "You help users."} { if !strings.Contains(body, want) { t.Errorf("missing value %q in:\n%s", want, body) } diff --git a/cli/cmd/auth/login.go b/cli/cmd/auth/login.go index b10b1ba3..336892fe 100644 --- a/cli/cmd/auth/login.go +++ b/cli/cmd/auth/login.go @@ -43,7 +43,7 @@ type LoginService interface { // apiKeyValidator probes /auth/me with the supplied API key so a bad key // fails fast at `auth login --with-token` time rather than on the next -// authenticated call. Mirrors gh CLI's pre-persist token verification. +// authenticated call. // // Returns the resolved user (used to populate context.User / TenantID at // rest, so later `auth list` reflects who owns the key). @@ -123,7 +123,7 @@ func runLogin(ctx context.Context, opts *LoginOptions, jopts *cmdutil.JSONOption } opts.APIKey = key // Validate against the server before persisting so a typo'd / - // expired / wrong-host key fails fast (gh CLI parity). The probe + // expired / wrong-host key fails fast at login time. The probe // is /auth/me - read-only, side-effect-free. user, err := defaultAPIKeyValidator(ctx, opts.Host, key) if err != nil { diff --git a/cli/cmd/chat/chat.go b/cli/cmd/chat/chat.go index 1c950ce5..2cee6dc9 100644 --- a/cli/cmd/chat/chat.go +++ b/cli/cmd/chat/chat.go @@ -63,9 +63,9 @@ type chatData struct { Answer string `json:"answer"` References []*sdk.SearchResult `json:"references"` // Thinking holds the reasoning / reflection text emitted by reasoning - // models (GPT-5, Claude extended thinking) via response_type=thinking - // frames. Omitted when empty (non-reasoning model or model didn't - // surface reasoning for this query). + // models via response_type=thinking frames. Omitted when empty + // (non-reasoning model or model didn't surface reasoning for this + // query). Thinking string `json:"thinking,omitempty"` SessionID string `json:"session_id"` AssistantMessageID string `json:"assistant_message_id,omitempty"` diff --git a/cli/cmd/chunk/delete.go b/cli/cmd/chunk/delete.go index a67f11f0..1f62ea54 100644 --- a/cli/cmd/chunk/delete.go +++ b/cli/cmd/chunk/delete.go @@ -16,7 +16,6 @@ import ( // `agent delete`. var chunkDeleteFields = []string{"id", "deleted"} -// DeleteOptions captures `chunk delete` flag state. type DeleteOptions struct { ChunkID string DocID string // required: SDK DeleteChunk takes both ids in the route. diff --git a/cli/cmd/chunk/list.go b/cli/cmd/chunk/list.go index 082042aa..b25704aa 100644 --- a/cli/cmd/chunk/list.go +++ b/cli/cmd/chunk/list.go @@ -3,7 +3,6 @@ package chunkcmd import ( "context" "fmt" - "strings" "text/tabwriter" "time" @@ -39,7 +38,6 @@ type ListService interface { ListKnowledgeChunks(ctx context.Context, knowledgeID string, page, pageSize int) ([]sdk.Chunk, int64, error) } -// ListOptions captures `chunk list` flag state. type ListOptions struct { // DocID scopes the listing to a single knowledge document (SDK // `knowledge_id`). The chunks SDK does not expose a KB-wide route. @@ -79,7 +77,7 @@ const chunkListExample = ` weknora chunk list --doc doc_abc // NewCmdList builds `weknora chunk list --doc `. func NewCmdList(f *cmdutil.Factory) *cobra.Command { - opts := &ListOptions{PageSize: defaultPageSize, Limit: defaultLimit} + opts := &ListOptions{} cmd := &cobra.Command{ Use: "list", Short: "List chunks of a document (admin/debug, not retrieval)", @@ -169,7 +167,7 @@ func runList(ctx context.Context, opts *ListOptions, jopts *cmdutil.JSONOptions, if c.IsEnabled { enabled = "yes" } - preview := text.Truncate(previewWidth, singleLine(c.Content)) + preview := text.OneLine(previewWidth, c.Content) if preview == "" { preview = "-" } @@ -182,8 +180,3 @@ func runList(ctx context.Context, opts *ListOptions, jopts *cmdutil.JSONOptions, } return tw.Flush() } - -// singleLine collapses newlines/carriage-returns/tabs to spaces so the -// chunk preview fits on one row of the human table. Without this a -// multi-line chunk would smear across rows and break tabwriter alignment. -var singleLine = strings.NewReplacer("\n", " ", "\r", " ", "\t", " ").Replace diff --git a/cli/cmd/chunk/view.go b/cli/cmd/chunk/view.go index c3fe8039..9b916e63 100644 --- a/cli/cmd/chunk/view.go +++ b/cli/cmd/chunk/view.go @@ -29,7 +29,6 @@ type ViewService interface { GetChunkByIDOnly(ctx context.Context, chunkID string) (*sdk.Chunk, error) } -// ViewOptions captures `chunk view` flag state. Chunk id is the sole input. type ViewOptions struct { ChunkID string } @@ -96,7 +95,7 @@ func runView(ctx context.Context, opts *ViewOptions, jopts *cmdutil.JSONOptions, return nil } -// renderChunk prints a single chunk in human-readable KV form per spec §1.5.2. +// renderChunk prints a single chunk in human-readable KV form. // Field order: id / seq_id / chunk_index / doc_id / kb_id / type / enabled / // status (omit-zero) / start_at (omit-zero) / end_at (omit-zero) / // tag_id (omit-empty) / image_info (omit-empty) / created_at / updated_at / diff --git a/cli/cmd/chunk/view_test.go b/cli/cmd/chunk/view_test.go index 1587268b..21d85fba 100644 --- a/cli/cmd/chunk/view_test.go +++ b/cli/cmd/chunk/view_test.go @@ -53,7 +53,8 @@ func TestView_HumanLabels_DocAndKB(t *testing.T) { }} require.NoError(t, runView(context.Background(), &ViewOptions{ChunkID: "c1"}, nil, svc)) body := out.String() - // Human KV must use friendlier DOC_ID / KB_ID labels (spec §1.5.2), not raw SDK names. + // Human KV uses friendlier DOC_ID / KB_ID labels (the SDK's + // knowledge_id / knowledge_base_id are kept only in --json output). assert.Contains(t, body, "doc_id") assert.Contains(t, body, "kb_id") assert.NotContains(t, body, "knowledge_id") diff --git a/cli/cmd/doc/upload.go b/cli/cmd/doc/upload.go index bf0b5ef4..297d8d02 100644 --- a/cli/cmd/doc/upload.go +++ b/cli/cmd/doc/upload.go @@ -93,15 +93,19 @@ The three input modes (positional file / --recursive directory walk / --from-url remote ingest) are mutually exclusive - pass exactly one. Use --recursive --glob to upload a directory tree (see Examples). -Server-side ingestion knobs apply to all modes: +Server-side ingestion knobs: --enable-multimodel Toggle multimodal extraction (image-in-PDF → text). Unset ⇒ server default; pass true or false to override. + Applies to file / --recursive / --from-url. --metadata key=value Attach arbitrary key/value metadata. Repeatable. Empty value allowed; duplicate keys ⇒ last-wins. Malformed values (no '=', empty key) ⇒ - input.invalid_argument. + input.invalid_argument. File and --recursive modes + only; rejected on --from-url because the URL-ingest + request type carries no metadata field. --channel Override the ingestion-channel tag (default "api"). + Applies to file / --recursive / --from-url. URL mode (--from-url) additionally accepts --title, --file-type, and --tag-id. Passing any of those without --from-url is rejected as input.invalid_argument.`, @@ -239,15 +243,28 @@ func validateUploadFlags(opts *UploadOptions, args []string) error { return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, "--recursive cannot be combined with --from-url") } + // The server's URL-ingest request type has no Metadata field; a + // --metadata pair would be silently dropped on the wire. Reject + // up-front so callers don't think they've set metadata when they + // haven't. + if len(opts.Metadata) > 0 { + return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, + "--metadata is not supported with --from-url (server URL-ingest has no metadata field)") + } return cmdutil.ValidateHTTPURL("--from-url", opts.FromURL) } if !hasPath { return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, "a file path is required (or pass --from-url)") } - // --title / --file-type / --tag-id are URL-mode only. Reject silently - // ignoring them in file mode to avoid the "set X, server did nothing" - // surprise. + return rejectURLOnlyFlags(opts) +} + +// rejectURLOnlyFlags errors on --title / --file-type / --tag-id when +// --from-url is NOT set. Shared between validateUploadFlags (file mode) +// and runUploadRecursive (directory walk) so a future URL-mode-only flag +// only needs to add one entry here instead of two parallel checks. +func rejectURLOnlyFlags(opts *UploadOptions) error { if opts.Title != "" { return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, "--title is only valid with --from-url") @@ -343,6 +360,13 @@ func runUpload(ctx context.Context, opts *UploadOptions, jopts *cmdutil.JSONOpti } k, err := svc.CreateKnowledgeFromFile(ctx, kbID, path, meta, opts.EnableMultimodel, opts.Name, effectiveChannel(opts)) if err != nil { + if errors.Is(err, sdk.ErrDuplicateFile) { + // SDK returns sentinel without an "HTTP error :" prefix + // (the duplicate is detected by file hash, not by status code), + // so WrapHTTP would misclassify it as network.error. + return cmdutil.Wrapf(cmdutil.CodeResourceAlreadyExists, err, + "file already uploaded to this knowledge base") + } return cmdutil.WrapHTTP(err, "upload %s", path) } return renderUploadSuccess(k, jopts, "Uploaded", opts.Name, path) diff --git a/cli/cmd/doc/upload_recursive.go b/cli/cmd/doc/upload_recursive.go index 18e0f120..c31721bf 100644 --- a/cli/cmd/doc/upload_recursive.go +++ b/cli/cmd/doc/upload_recursive.go @@ -32,26 +32,11 @@ func runUploadRecursive(ctx context.Context, opts *UploadOptions, jopts *cmdutil Hint: "drop --name or upload files one at a time", } } - // URL-mode-only flags are not meaningful for a directory walk; reject - // them so misuse fails fast (mirrors the file-mode path's check in - // validateUploadFlags - that path runs before --recursive dispatches). - if opts.Title != "" { - return &cmdutil.Error{ - Code: cmdutil.CodeInputInvalidArgument, - Message: "--title is only valid with --from-url", - } - } - if opts.FileType != "" { - return &cmdutil.Error{ - Code: cmdutil.CodeInputInvalidArgument, - Message: "--file-type is only valid with --from-url", - } - } - if opts.TagID != "" { - return &cmdutil.Error{ - Code: cmdutil.CodeInputInvalidArgument, - Message: "--tag-id is only valid with --from-url", - } + // URL-mode-only flags are not meaningful for a directory walk; + // rejectURLOnlyFlags is the single source of truth shared with + // file-mode upload. + if err := rejectURLOnlyFlags(opts); err != nil { + return err } // Parse --metadata up front so a malformed value aborts before the // first SDK call - otherwise a typo in `key=value` would only surface diff --git a/cli/cmd/doc/upload_test.go b/cli/cmd/doc/upload_test.go index a3922ffc..95078959 100644 --- a/cli/cmd/doc/upload_test.go +++ b/cli/cmd/doc/upload_test.go @@ -132,6 +132,25 @@ func TestUpload_HTTPError_409Conflict(t *testing.T) { assert.Equal(t, cmdutil.CodeResourceAlreadyExists, typed.Code) } +// TestUpload_DuplicateFileMaps_resource_already_exists pins the contract that +// the SDK's sentinel sdk.ErrDuplicateFile (returned with no "HTTP error :" +// prefix because the duplicate is detected by file-hash short-circuit, not by +// status code) is mapped to resource.already_exists. Prior regression: the +// file-upload path forwarded the sentinel to WrapHTTP, which classified the +// prefix-less message as network.error — symmetric with the --from-url branch +// which already handled ErrDuplicateURL. +func TestUpload_DuplicateFileMaps_resource_already_exists(t *testing.T) { + _, _ = iostreams.SetForTest(t) + path := writeTempFile(t, "dup.md") + svc := &fakeUploadSvc{err: sdk.ErrDuplicateFile} + err := runUpload(context.Background(), &UploadOptions{}, nil, svc, "kb_xxx", path) + require.Error(t, err) + + var typed *cmdutil.Error + require.ErrorAs(t, err, &typed) + assert.Equal(t, cmdutil.CodeResourceAlreadyExists, typed.Code) +} + func TestValidateUploadPath_NotFound(t *testing.T) { missing := filepath.Join(t.TempDir(), "does-not-exist.pdf") err := validateUploadPath(missing) @@ -238,6 +257,21 @@ func TestValidateUploadFlags_FromURL_WithRecursive_Rejected(t *testing.T) { assert.Equal(t, cmdutil.CodeInputInvalidArgument, typed.Code) } +// The server's URL-ingest request type has no Metadata field; the CLI must +// reject --metadata + --from-url upfront so callers don't think they've set +// metadata that the server then silently drops on the wire. +func TestValidateUploadFlags_FromURL_WithMetadata_Rejected(t *testing.T) { + err := validateUploadFlags(&UploadOptions{ + FromURL: "https://example.com/x.pdf", + Metadata: []string{"team=alpha"}, + }, nil) + require.Error(t, err) + var typed *cmdutil.Error + require.ErrorAs(t, err, &typed) + assert.Equal(t, cmdutil.CodeInputInvalidArgument, typed.Code) + assert.Contains(t, typed.Message, "--metadata is not supported with --from-url") +} + func TestValidateUploadFlags_FromURL_BadScheme(t *testing.T) { err := validateUploadFlags(&UploadOptions{FromURL: "file:///etc/passwd"}, nil) require.Error(t, err) @@ -300,8 +334,8 @@ func TestParseTriBool(t *testing.T) { {"false", false, false}, {"0", false, false}, {"no", false, false}, - {"", false, true}, // explicit empty rejected - {" ", false, true}, // whitespace rejected + {"", false, true}, // explicit empty rejected + {" ", false, true}, // whitespace rejected {"maybe", false, true}, } { t.Run(c.in, func(t *testing.T) { diff --git a/cli/cmd/mcp/mcp.go b/cli/cmd/mcp/mcp.go index 313b57a5..2e072aed 100644 --- a/cli/cmd/mcp/mcp.go +++ b/cli/cmd/mcp/mcp.go @@ -23,8 +23,8 @@ func NewCmd(f *cmdutil.Factory) *cobra.Command { cmd := &cobra.Command{ Use: "mcp", Short: "Run weknora as a Model Context Protocol server", - Long: `Exposes weknora's read surface as MCP tools so agentic IDE clients -(Claude Code, Cursor, Continue, Zed) can call them over JSON-RPC. + Long: `Exposes weknora's read surface as MCP tools so any +MCP-compatible client can call them over JSON-RPC. Initial tool surface is read-only and curated: kb_list / kb_view / doc_list / doc_view / doc_download / search_chunks / chat / agent_list / diff --git a/cli/cmd/mcp/serve.go b/cli/cmd/mcp/serve.go index 22844db5..f5b8ca89 100644 --- a/cli/cmd/mcp/serve.go +++ b/cli/cmd/mcp/serve.go @@ -22,8 +22,8 @@ configured, the process exits with auth.unauthenticated before any MCP handshake. This way an IDE-side agent sees a clear failure mode rather than a server that handshakes successfully then errors on every tool. -To register with your MCP client (Claude Desktop / Code / Cursor / etc.), -add an entry pointing at this binary under "mcpServers": +To register with your MCP client, add an entry pointing at this binary +under "mcpServers": { "mcpServers": { diff --git a/cli/cmd/root.go b/cli/cmd/root.go index 137351e5..056580aa 100644 --- a/cli/cmd/root.go +++ b/cli/cmd/root.go @@ -30,7 +30,7 @@ import ( func Execute() int { root := NewRootCmd(cmdutil.New()) if err := root.Execute(); err != nil { - // Errors go to stderr (matches gh/aws/stripe). Stdout stays + // Errors go to stderr. Stdout stays // empty (or holds partial success the command produced) so // downstream `--json | jq` pipelines never filter error shapes // out of the success stream. The typed exit code (3/4/5/6/7/10) diff --git a/cli/cmd/search/chunks.go b/cli/cmd/search/chunks.go index 7db58807..f90b4a8e 100644 --- a/cli/cmd/search/chunks.go +++ b/cli/cmd/search/chunks.go @@ -51,7 +51,7 @@ func NewCmdChunks(f *cmdutil.Factory) *cobra.Command { Short: "Hybrid (vector + keyword) chunk retrieval against a knowledge base", Example: ` weknora search chunks "what is RAG?" --kb engineering weknora search chunks "embedding model" --kb kb_abc --limit 20 - weknora search chunks "k8s" --kb engineering --no-keyword # vector-only`, + weknora search chunks "retry policy" --kb engineering --no-keyword # vector-only`, Long: `Hybrid (vector + keyword) retrieval against the knowledge base. Pass --no-vector or --no-keyword to disable one channel; you cannot disable both. --limit caps the returned slice client-side.`, diff --git a/cli/internal/cmdutil/agentconfig_test.go b/cli/internal/cmdutil/agentconfig_test.go index 1d167e17..73034cdc 100644 --- a/cli/internal/cmdutil/agentconfig_test.go +++ b/cli/internal/cmdutil/agentconfig_test.go @@ -13,7 +13,7 @@ import ( func TestLoadConfigFile_YAML(t *testing.T) { yaml := strings.NewReader(` agent_mode: smart-reasoning -model_id: gpt-4 +model_id: model-x temperature: 0.7 knowledge_bases: - kb_abc @@ -22,17 +22,17 @@ knowledge_bases: cfg, err := LoadAgentConfig(yaml, "yaml") require.NoError(t, err) assert.Equal(t, "smart-reasoning", cfg.AgentMode) - assert.Equal(t, "gpt-4", cfg.ModelID) + assert.Equal(t, "model-x", cfg.ModelID) assert.InDelta(t, 0.7, cfg.Temperature, 0.001) assert.Equal(t, []string{"kb_abc", "kb_def"}, cfg.KnowledgeBases) } func TestLoadConfigFile_JSON(t *testing.T) { - js := strings.NewReader(`{"agent_mode":"quick-answer","model_id":"gpt-3.5"}`) + js := strings.NewReader(`{"agent_mode":"quick-answer","model_id":"model-y"}`) cfg, err := LoadAgentConfig(js, "json") require.NoError(t, err) assert.Equal(t, "quick-answer", cfg.AgentMode) - assert.Equal(t, "gpt-3.5", cfg.ModelID) + assert.Equal(t, "model-y", cfg.ModelID) } func TestLoadConfigFile_UnknownKind(t *testing.T) { @@ -52,17 +52,17 @@ func TestLoadConfigFile_BadJSON(t *testing.T) { } func TestMergeAgentConfig_FlagsOverrideFile(t *testing.T) { - base := &sdk.AgentConfig{ModelID: "gpt-3.5"} - overrides := AgentConfigFlags{ModelIDSet: true, ModelID: "gpt-4"} + base := &sdk.AgentConfig{ModelID: "model-y"} + overrides := AgentConfigFlags{ModelIDSet: true, ModelID: "model-x"} merged := MergeAgentConfig(base, overrides) - assert.Equal(t, "gpt-4", merged.ModelID) + assert.Equal(t, "model-x", merged.ModelID) } func TestMergeAgentConfig_UnsetFlagsPreserveBase(t *testing.T) { - base := &sdk.AgentConfig{ModelID: "gpt-3.5", Temperature: 0.5} + base := &sdk.AgentConfig{ModelID: "model-y", Temperature: 0.5} overrides := AgentConfigFlags{} // nothing set merged := MergeAgentConfig(base, overrides) - assert.Equal(t, "gpt-3.5", merged.ModelID) + assert.Equal(t, "model-y", merged.ModelID) assert.InDelta(t, 0.5, merged.Temperature, 0.001) } @@ -70,7 +70,7 @@ func TestMergeAgentConfig_EveryFieldOverlay(t *testing.T) { base := &sdk.AgentConfig{ AgentMode: "quick-answer", SystemPrompt: "old", - ModelID: "gpt-3.5", + ModelID: "model-y", RerankModelID: "rerank-old", Temperature: 0.1, KBSelectionMode: "all", @@ -79,7 +79,7 @@ func TestMergeAgentConfig_EveryFieldOverlay(t *testing.T) { overrides := AgentConfigFlags{ AgentMode: "smart-reasoning", AgentModeSet: true, SystemPrompt: "new", SystemPromptSet: true, - ModelID: "gpt-4", ModelIDSet: true, + ModelID: "model-x", ModelIDSet: true, RerankModelID: "rerank-new", RerankModelIDSet: true, Temperature: 0.9, TemperatureSet: true, KBSelectionMode: "selected", KBSelectionModeSet: true, @@ -88,7 +88,7 @@ func TestMergeAgentConfig_EveryFieldOverlay(t *testing.T) { merged := MergeAgentConfig(base, overrides) assert.Equal(t, "smart-reasoning", merged.AgentMode) assert.Equal(t, "new", merged.SystemPrompt) - assert.Equal(t, "gpt-4", merged.ModelID) + assert.Equal(t, "model-x", merged.ModelID) assert.Equal(t, "rerank-new", merged.RerankModelID) assert.InDelta(t, 0.9, merged.Temperature, 0.001) assert.Equal(t, "selected", merged.KBSelectionMode) diff --git a/cli/internal/cmdutil/input.go b/cli/internal/cmdutil/input.go new file mode 100644 index 00000000..2f5a4b7d --- /dev/null +++ b/cli/internal/cmdutil/input.go @@ -0,0 +1,20 @@ +package cmdutil + +import ( + "io" + "os" + + "github.com/Tencent/WeKnora/cli/internal/iostreams" +) + +// OpenInput returns a reader for path. If path == "-", returns stdin +// (iostreams.IO.In). Otherwise opens the file. Caller is responsible +// for closing if needed — for typical "-input "/"--input -" CLI +// patterns the file is fully read before the command exits and OS +// reclaims the FD, so closing is cosmetic. +func OpenInput(path string) (io.Reader, error) { + if path == "-" { + return iostreams.IO.In, nil + } + return os.Open(path) +} diff --git a/cli/internal/cmdutil/jsonflags_test.go b/cli/internal/cmdutil/jsonflags_test.go index e1c58bca..8394fbc3 100644 --- a/cli/internal/cmdutil/jsonflags_test.go +++ b/cli/internal/cmdutil/jsonflags_test.go @@ -53,9 +53,8 @@ func TestAddJSONFlags_BareYieldsEnabledOptsWithNoFields(t *testing.T) { func TestAddJSONFlags_FieldsFlagParsing(t *testing.T) { // NoOptDefVal sentinel means the `=` form is required for value passing. - // Space form `--json id,name` parses as bare + positional, which is a - // documented divergence from gh CLI: weknora keeps bare `--json` as a - // shortcut for "full payload". + // Space form `--json id,name` parses as bare + positional; bare `--json` + // (no value) is reserved as a shortcut for the unfiltered payload. cases := []struct { args []string want []string diff --git a/cli/internal/format/bare.go b/cli/internal/format/bare.go index b4e57e16..53c038ab 100644 --- a/cli/internal/format/bare.go +++ b/cli/internal/format/bare.go @@ -21,7 +21,7 @@ func WriteJSON(w io.Writer, v any) error { // - len(fields) == 0 → no field filter // - jqExpr == "" → no jq filter // -// Field filter rules (mirrors gh CLI's `--json field,field` semantics): +// Field filter rules: // // - v marshals to a top-level array → each [*] object is restricted to // the named keys diff --git a/cli/internal/format/bare_test.go b/cli/internal/format/bare_test.go index 18b26afb..c88edbcb 100644 --- a/cli/internal/format/bare_test.go +++ b/cli/internal/format/bare_test.go @@ -105,7 +105,8 @@ func TestWriteJSONFiltered_JQOnly(t *testing.T) { if err := format.WriteJSONFiltered(buf, items, nil, ".[].id"); err != nil { t.Fatalf("err = %v", err) } - // gh CLI parity: string results render without JSON quotes. + // String / scalar results render without JSON quotes so scalar + // projections (e.g. `--jq '.[].id'`) pipe cleanly into shell tools. lines := strings.Split(strings.TrimRight(buf.String(), "\n"), "\n") if len(lines) != 2 || lines[0] != "1" || lines[1] != "2" { t.Errorf("jq output mismatch: %q", buf.String()) diff --git a/cli/internal/mcp/tools.go b/cli/internal/mcp/tools.go index 8a38a3f3..c6ff7655 100644 --- a/cli/internal/mcp/tools.go +++ b/cli/internal/mcp/tools.go @@ -451,7 +451,7 @@ func addAgentInvoke(server *mcpsdk.Server, svc agentInvokeService) { Channel: "api", } // Auto-create session if not supplied. Sessions are agent- - // agnostic at creation (Q3 - verified against server source). + // agnostic at creation (verified against server source). sessionID := in.SessionID if sessionID == "" { sess, err := svc.CreateSession(ctx, &sdk.CreateSessionRequest{Title: "weknora mcp agent_invoke"}) diff --git a/cli/internal/sse/accumulator.go b/cli/internal/sse/accumulator.go index 4067eb04..26546402 100644 --- a/cli/internal/sse/accumulator.go +++ b/cli/internal/sse/accumulator.go @@ -23,8 +23,8 @@ import ( // Demuxes by ResponseType so the answer string is not polluted by thinking // or reflection fragments - the model layer (internal/models/chat/ // remote_api.go) emits ResponseTypeThinking events whenever the upstream -// LLM produces reasoning_content (GPT-5 / Claude extended thinking), and -// without demux those would be silently concatenated into Result(). +// LLM produces reasoning_content frames, and without demux those would +// be silently concatenated into Result(). type Accumulator struct { answer strings.Builder thinking strings.Builder diff --git a/cli/internal/text/oneline.go b/cli/internal/text/oneline.go new file mode 100644 index 00000000..1e6ac6f4 --- /dev/null +++ b/cli/internal/text/oneline.go @@ -0,0 +1,13 @@ +package text + +import "strings" + +// OneLine collapses newlines/carriage-returns/tabs in s to single spaces, +// then truncates to maxDisplayWidth columns (UTF-8 safe via Truncate). +// Use for human-readable preview rows where multiline content would +// break tabular layout. +func OneLine(maxDisplayWidth int, s string) string { + return Truncate(maxDisplayWidth, lineReplacer.Replace(s)) +} + +var lineReplacer = strings.NewReplacer("\n", " ", "\r", " ", "\t", " ") diff --git a/cli/internal/text/oneline_test.go b/cli/internal/text/oneline_test.go new file mode 100644 index 00000000..9d4b0f52 --- /dev/null +++ b/cli/internal/text/oneline_test.go @@ -0,0 +1,29 @@ +package text_test + +import ( + "testing" + + "github.com/Tencent/WeKnora/cli/internal/text" +) + +func TestOneLine(t *testing.T) { + cases := []struct { + name string + max int + in, want string + }{ + {"empty", 10, "", ""}, + {"no-collapse", 10, "hello", "hello"}, + {"collapse-newline", 20, "hello\nworld", "hello world"}, + {"collapse-cr-tab", 20, "hello\r\tworld", "hello world"}, + {"truncate", 8, "hello world long", "hello w…"}, + {"truncate-after-collapse", 8, "hello\nworld\nlong", "hello w…"}, + } + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + if got := text.OneLine(c.max, c.in); got != c.want { + t.Errorf("OneLine(%d, %q) = %q, want %q", c.max, c.in, got, c.want) + } + }) + } +}