Compare commits
255 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
| 3619f44ac8 | |||
| 23387779c1 | |||
| c64a48647c | |||
| 84f65a809f | |||
| 5d0326f987 | |||
| d283fabc99 | |||
| 50eb48c344 | |||
| 075b16d6ca | |||
| 43839f7830 | |||
| e0b6a71503 | |||
| 014cf4e545 | |||
| 8cb43473e6 | |||
| 697e0ae04e | |||
| 265556950b | |||
| c28cd05c0c | |||
| b2ae22c4eb | |||
| 6fb858105a | |||
| 6c794f64cf | |||
| de7507cc96 | |||
| a287808597 | |||
| 8ae82573ab | |||
| c74b0caa35 | |||
| 0869f3e829 | |||
| 85c9b61ad0 | |||
| 986a6f3699 | |||
| 37de0afad0 | |||
| 7fde37eeeb | |||
| 97bcca21c6 | |||
| 146e341748 | |||
| ccf02e1a2a | |||
| 8ca9c117bb | |||
| b6a3b347da | |||
| 135033e6df | |||
| 5af8eae81d | |||
| a3a0308b62 | |||
| f195e0494c | |||
| 8248752e62 | |||
| 76f9640a4f | |||
| 4c3ae69b49 | |||
| ab0b1d65b5 | |||
| b9b81a6c3c | |||
| 0f2c6cee11 | |||
| 59fed12643 | |||
| 554d273cf5 | |||
| 0f422f172d | |||
| 2e540654f1 | |||
| 1d37b90a17 | |||
| ac321a3e81 | |||
| 7e7083ce17 | |||
| be48324c84 | |||
| 0d545c8c6a | |||
| 516ef01cf2 | |||
| 171fbd0dca | |||
| 23db592c4a | |||
| c695125dce | |||
| 74cdd7cdd0 | |||
| fa7ae075ee | |||
| 150c07368b | |||
| 83da0903b6 | |||
| e289595054 | |||
| fd660ca796 | |||
| 25ef7b6c68 | |||
| b1b42abe23 | |||
| 3011f132e9 | |||
| c387f09add | |||
| d1cab68e3d | |||
| 23e606f570 | |||
| 29bec6c613 | |||
| 76a4ffe525 | |||
| eab91d2f7f | |||
| 380e371c2e | |||
| 7807dee42a | |||
| 5293b8e7db | |||
| e294dff7f4 | |||
| 457285cffe | |||
| 1649603af4 | |||
| 5ee96019e0 | |||
| 1a2021b3f8 | |||
| e8dcbb07d0 | |||
| df21abe13b | |||
| bea58bbef7 | |||
| 9afb8b7b68 | |||
| 3edd9c2c84 | |||
| eedd7d4641 | |||
| c21c34b3c0 | |||
| 53a66a6456 | |||
| e938a76be4 | |||
| b862c2e45d | |||
| 014164ae44 | |||
| 79e8f3d894 | |||
| 48969b49f7 | |||
| 88a0201afe | |||
| a1d8f55cbd | |||
| a270d40cd5 | |||
| 7ddac0385f | |||
| 85d10d99e3 | |||
| 9ae17be43c | |||
| 92ceb3bd7d | |||
| ceb4d1a310 | |||
| 7b2c9e73bf | |||
| fbc9db85d1 | |||
| 951f95903b | |||
| a729bc1271 | |||
| 0f4500b98f | |||
| 38c594aec3 | |||
| 6d14cc3536 | |||
| 9733bd28bf | |||
| a8dea5f9a3 | |||
| 6349fff002 | |||
| f8b3e5f148 | |||
| 139ec1e6b8 | |||
| 97490ef7ed | |||
| b3bb60f03c | |||
| e3b7ad98c2 | |||
| be88a56245 | |||
| bdd459b071 | |||
| ace84bc757 | |||
| 28ebcf2525 | |||
| 01f1011511 | |||
| f583d77fa0 | |||
| fc03e4862d | |||
| 41975abcc5 | |||
| e1572b71b9 | |||
| f409bd756b | |||
| 4ae48d6acf | |||
| 1eae475a1f | |||
| 6171962e56 | |||
| f7ec759cc6 | |||
| 3b587c401d | |||
| abeb4a0126 | |||
| 087fcc9fe7 | |||
| a6c85dad28 | |||
| 8ec65941a5 | |||
| 8554c422dc | |||
| 87ba3fc2de | |||
| ecf2c1fb9b | |||
| 50b8c0a72e | |||
| 1dfa23d728 | |||
| 35b92f73aa | |||
| eacc278b9a | |||
| 07ba01ec93 | |||
| 5eefa70e6f | |||
| c1cddb4d4d | |||
| def92bb74f | |||
| 800cea0826 | |||
| abcecc870a | |||
| c8793b001d | |||
| 26f8afa3db | |||
| 083e9738f6 | |||
| ac8c5c5540 | |||
| b9cccc7bee | |||
| 80556fbaa7 | |||
| d496d0fc73 | |||
| fe47ac1f96 | |||
| 30f7630ac4 | |||
| b4b63a0c1f | |||
| 38aacc3113 | |||
| 37dcdc7f74 | |||
| 4404ea74e3 | |||
| 20256287ec | |||
| 200c344065 | |||
| 98ad41cda4 | |||
| 63198c5d9f | |||
| 76a8092483 | |||
| 60f7f35e40 | |||
| c8a4fd5ba3 | |||
| 70e2e85fa6 | |||
| 7642117b70 | |||
| a6ff0036b5 | |||
| b6d3420a5d | |||
| d287c70358 | |||
| 6ac1703198 | |||
| 58b79876ae | |||
| e93f8d3c21 | |||
| 0ffdf945b3 | |||
| ca9da8399e | |||
| a1b49e2664 | |||
| d9bb7aa8f2 | |||
| 0db71bf2f8 | |||
| d01526b758 | |||
| 15b81d1581 | |||
| 3209ed77fd | |||
| 45eab4a95f | |||
| 77cf6a5789 | |||
| 8cf9f1c882 | |||
| f7b427009d | |||
| 974231190c | |||
| d60614475e | |||
| 2c6f082062 | |||
| b5cc7d2a28 | |||
| 97c36f634a | |||
| 1d1e1e3d25 | |||
| a6759d61b5 | |||
| d2ffc1b973 | |||
| fedb6c3f7e | |||
| 9a76a24ce6 | |||
| 3ace6e657f | |||
| c65ffa3d9c | |||
| 94d18ea15a | |||
| 3f516d7f31 | |||
| 505bc7ddec | |||
| 1708d6895a | |||
| b16cb0bb56 | |||
| baada32cb6 | |||
| 4f2dca0b63 | |||
| d5b8d2f886 | |||
| d3c03b2f34 | |||
| 040a734766 | |||
| 6f8b825f5f | |||
| 445a4330fa | |||
| 8f36ea2229 | |||
| eba9fe7e78 | |||
| cb46db23f5 | |||
| 1b0502e562 | |||
| 699d6bd235 | |||
| 85f5cd760b | |||
| 18d7a6b3d3 | |||
| 1109e85a57 | |||
| 9437e1ac3c | |||
| 238297e2c5 | |||
| 1661827d6e | |||
| 663d13eb58 | |||
| 7099a7e181 | |||
| 929697618f | |||
| 235e86b876 | |||
| 26cc335420 | |||
| 040504447e | |||
| cd65665894 | |||
| f23c674bad | |||
| fc64751f4e | |||
| 1a264e09c1 | |||
| 512d2e5c25 | |||
| 0b73080bb8 | |||
| 8325dac738 | |||
| 1d322c525a | |||
| a17a2250ed | |||
| ab790bcbd9 | |||
| 0060c0d397 | |||
| 2203c4bb14 | |||
| c694fcf6cd | |||
| 8d40959f88 | |||
| 4c962a9403 | |||
| fdfc7297de | |||
| 9682ad67a6 | |||
| ee1014f87c | |||
| a24567a951 | |||
| 2d9b21feb6 | |||
| f8accb2610 | |||
| 47a7fe8c83 | |||
| f373c8a96f | |||
| 146b41193d | |||
| 5074344c16 | |||
| 168b1d4cfe | |||
| 97bca74a31 | |||
| cb99736d72 |
+610
-631
File diff suppressed because it is too large
Load Diff
@@ -56,6 +56,20 @@ DISABLE_REGISTRATION=false
|
||||
# === 性能 ===
|
||||
CONCURRENCY_POOL_SIZE=3
|
||||
|
||||
# 聊天附件解析产物保留时长(小时),默认 24 小时
|
||||
# WEKNORA_CHAT_ATTACHMENT_TTL_HOURS=24
|
||||
|
||||
# 单轮问答等待附件解析完成的最长时间(秒),超时后未完成的附件会被跳过。
|
||||
# 大文件 / 扫描件解析较慢时可调大,默认 60 秒。智能体里的「附件解析等待超时」> 0 时优先于此全局值。
|
||||
# WEKNORA_CHAT_ATTACHMENT_WAIT_TIMEOUT_SEC=60
|
||||
|
||||
# 附件 VLM OCR 调优(扫描件 / 图片型文档)。解析慢的瓶颈是逐页 VLM OCR,而非文档解析器。
|
||||
# OCR_CONCURRENCY 为并行 OCR 的页数(默认 8,与页数上限一致,让扫描件一波跑完;调大会加重 VLM 负载,
|
||||
# 所有智能体共享 VLM 后端,故保持全局);OCR_MAX_PAGES 为扫描件送入 VLM 的最大页数(默认 8),
|
||||
# 智能体里的「扫描件 OCR 最大页数」> 0 时优先于此全局值。
|
||||
# WEKNORA_CHAT_ATTACHMENT_OCR_CONCURRENCY=8
|
||||
# WEKNORA_CHAT_ATTACHMENT_OCR_MAX_PAGES=8
|
||||
|
||||
# Docreader 地址
|
||||
DOCREADER_ADDR=127.0.0.1:50051
|
||||
|
||||
|
||||
@@ -47,6 +47,12 @@ jobs:
|
||||
run: go test -race -coverprofile=coverage.out ./...
|
||||
- name: go vet
|
||||
run: go vet ./...
|
||||
- name: Check skill wire vocabulary
|
||||
if: runner.os == 'Linux'
|
||||
run: scripts/check-skill-wire-vocab.sh
|
||||
- name: Check for committed credentials in docs
|
||||
if: runner.os == 'Linux'
|
||||
run: scripts/check-secret-tokens.sh
|
||||
- name: coverage report
|
||||
if: matrix.os == 'ubuntu-latest'
|
||||
run: go tool cover -func=coverage.out
|
||||
|
||||
+105
@@ -2,6 +2,111 @@
|
||||
|
||||
All notable changes to this project will be documented in this file.
|
||||
|
||||
## [0.7.1] - 2026-07-24
|
||||
|
||||
### New Features
|
||||
|
||||
- **NEW**: **Yunzhijia (云之家) IM Integration** — a new instant-messaging platform integration for Yunzhijia, including WebSocket message handling, request signing, image-message ingestion with SSRF-checked downloads, and markdown-formatted replies by default. Add the channel under **Settings → IM Integration** and fill in the credentials.
|
||||
- **NEW**: **Volcengine Rerank Provider** — Volcengine is now a first-class rerank provider, with request batching that transparently splits payloads exceeding the API's per-request document limit. vLLM rerankers no longer send `truncate_prompt_tokens` by default for broader compatibility.
|
||||
- **NEW**: **Zhipu AI Web Search Provider** — Zhipu AI added as a configurable web search provider alongside the existing options.
|
||||
- **NEW**: **Platform-Scoped API Keys** — control-plane automation now has dedicated platform API keys with capability-based access to tenant management, system settings, runtime queues, and audit logs, plus an admin UI for key lifecycle and system-wide audit-log viewing (migration `000071_platform_api_keys`).
|
||||
- **NEW**: **Knowledge Base Activity Audit Trail** — a scoped, per-KB activity audit trail records knowledge operations (including FAQ imports) with a dedicated activity settings view and localized audit-log detail drawer (migration `000073_kb_activity_scope`).
|
||||
- **NEW**: **FAQ Management Enhancements** — richer FAQ workflows: entry filtering and tagging, export support, and import result tracking with clearer UI feedback and activity logging.
|
||||
- **NEW**: **Langfuse OTLP/OTel Tracing** — Langfuse tracing migrated from the legacy ingestion batch API to the OpenTelemetry Go SDK emitting OTLP/HTTP (`/api/public/otel/v1/traces`), the Langfuse v3+ standard. Adds W3C `traceparent` cross-service propagation so upstream trace IDs are inherited, and merges finish metadata with auto-exported root spans.
|
||||
- **NEW**: **Chat Header Actions & Markdown Export** — a new chat header with docked state and references-panel support, session header actions, and one-click Markdown export of a conversation. Wiki tool results now surface in the references drawer, and model reasoning renders inline in the agent timeline.
|
||||
- **NEW**: **Prompt-Cache Observability** — prompt-cache hit/usage observability with cache-friendly wiki prompts to improve LLM cost and latency.
|
||||
- **NEW**: **Session Channel Governance** — IM / embed / API-key channel sessions are gated behind admin scope, with a dedicated admin API session bucket, strict owner scoping for API-key sessions, and a stabilized sidebar source filter. Archived queue tasks can now be bulk-purged.
|
||||
|
||||
### Improvements
|
||||
|
||||
- **IMPROVED**: **Removed Neo4j conversation memory** — the Neo4j-based episodic memory pipeline, its API fields, settings UI, and embed toggles were dropped, so chat no longer depends on Neo4j graph storage. This simplifies deployment and reduces the required infrastructure footprint.
|
||||
- **IMPROVED**: **Shared SSRF-safe HTTP transport** — model clients, embedders, the Doris Stream Load client, and datasource connectors now reuse a single SSRF-safe HTTP transport, consolidating outbound-request protection.
|
||||
- **IMPROVED**: **Resilient Feishu large-wiki sync** — Feishu wiki synchronization now retries, resumes streaming, and surfaces failure reasons for large spaces.
|
||||
- **IMPROVED**: **Organization & shared-space UI** — polished organization space UI, share-to-space panels, shared-space settings, and join-preview UI, with disambiguated shared-space terminology and tightened invite search.
|
||||
- **IMPROVED**: **Compose & config alignment** — docker-compose env vars aligned with code defaults (including a Helm GraphRAG fix, #2164), PDF render parallelism follows the CPU-aware code default, and BSD `netcat` compatibility in the dev script (#2205).
|
||||
- **IMPROVED**: **Chat layout** — conversation content area widened from 800px to 960px.
|
||||
|
||||
### Bug Fixes
|
||||
|
||||
- **FIXED**: Wiki summary slugs are preserved during citation compaction, and slug integrity is hardened across ingest and agent write paths (with sqlite alias support).
|
||||
- **FIXED**: IM Q&A could not read its session (#session lookup); DingTalk/IM session reads now resolve correctly.
|
||||
- **FIXED**: API keys can no longer be assigned the owner role; scoped keys can access file-serve and ingest-batch routes as intended.
|
||||
- **FIXED**: MCP OAuth token refresh and authorization polling are now coordinated to avoid races (migration `000074_mcp_oauth_refresh_lease`).
|
||||
- **FIXED**: API-key expiry timestamps normalized to UTC (#2137, migration `000072_auth_timestamp_tz`).
|
||||
- **FIXED**: Async knowledge deletion no longer leaves visible/zombie rows (#2192); KB deletion queue cleanup is detached from the request context and dequeues work for deleted knowledge bases.
|
||||
- **FIXED**: Source file download restricted to Editor role and above; shared knowledge base document preview path corrected.
|
||||
- **FIXED**: Hybrid search query text is validated; top-k retrieval ordering stabilized.
|
||||
- **FIXED**: Embedded chunk images copied into the exports namespace; parent/clone chunk image URLs rewritten via a global pass.
|
||||
- **FIXED**: Optimistic organization state corrected after review and detail loads; state synchronized after writes and pending join-request counts refreshed after review.
|
||||
- **FIXED**: Suggested-questions limit parameter honored; model debug upload limit aligned with the global `MAX_FILE_SIZE`.
|
||||
- **FIXED**: Frontend robustness — custom theme tokens kept in production builds, complete TDesign styles loaded, TDesign textarea autosize crash prevented in the org settings popup, and `crypto.randomUUID` fallback for older browsers / HTTP mode.
|
||||
- **FIXED**: nginx base image pinned by digest for old-host compatibility; graph and multimodal processing traces corrected; task-inspector lazy-queue "not found" errors handled.
|
||||
|
||||
### Infrastructure & Build
|
||||
|
||||
- **BUILD**: Migrations `000071_platform_api_keys`, `000072_auth_timestamp_tz`, `000073_kb_activity_scope`, `000074_mcp_oauth_refresh_lease`.
|
||||
- **BUILD**: `tenant_api_keys` table structure updated and legacy migration files removed; Langfuse tracing client replaced by an OTel exporter.
|
||||
- **BUILD**: Swagger / API docs regenerated for platform API keys, activity audit trail, web-search providers, and the removed memory feature.
|
||||
|
||||
## [0.7.0] - 2026-07-17
|
||||
|
||||
### New Features
|
||||
|
||||
- **NEW**: **Scoped Tenant API Keys & Principal Model** — the headline of this release. WeKnora now issues fine-grained, capability-scoped API keys that are first-class principals separate from human users (migrations `000064_principal_model`, `000065_tenant_api_keys`). Each key carries an explicit role plus capability grants (`manage_kbs` covering the full KB lifecycle, `manage_storage_backends`, member/space capabilities, etc.), can be restricted to specific knowledge bases, and updates its `last_used_at` under a throttle. Route-level guards (`DenyAPIKeyPrincipal`, `api_key_gate`) close IDOR/scope gaps, and a new **API Integration Playground** in the web UI lets owners mint, scope, and test keys interactively. MCP OAuth and embed sessions are now scoped per principal so external integrations stay isolated.
|
||||
- **NEW**: **Runtime Task Queue Observability & Worker-Pool Governance** — a system-admin **Runtime Queues** dashboard exposes live queue depth, per-model concurrency stats, failed-task inspection, manual retry, and cursor-paginated task listings. The ingestion pipeline moves from a single aggregate worker pool to guaranteed per-stage pools (core / post-process / enrichment / maintenance) plus a shared elastic pool, with per-model background concurrency governors (`model.max_concurrency`) wrapping chat, embedding, rerank, and VLM calls. Wiki generation runs in its own independently governed pool. See [`docs/worker-pool-governance.md`](./docs/worker-pool-governance.md).
|
||||
- **NEW**: **Multi-Instance Storage Backends** — each workspace can register multiple object/file storage instances (`local` / `minio` / `cos` / `tos` / `s3` / `oss` / `ks3` / `obs`) and bind different knowledge bases to different instances, with a workspace-level default (migration `000068_storage_backends`). Ships a full CRUD + connectivity-test API and settings UI, credential masking on read, and hardened image-source protection for storage backends. See [`docs/api/storage-backend.md`](./docs/api/storage-backend.md).
|
||||
- **NEW**: **Session-Scoped Temporary Attachments** — attach images and documents to a chat session for one-off Q&A with asynchronous parsing (migration `000070_temporary_documents`). Enforces a combined image + attachment limit, normalizes temporary attachment IDs, persists attachment content across turns, and adds a chat attachment preview drawer.
|
||||
- **NEW**: **Question & Follow-up Suggestions** — knowledge-grounded suggested questions plus after-answer follow-ups (migration `000067_question_suggestions`), with tag-scope aware generation, KB-scope preservation on click, and a dedicated follow-up rendering component.
|
||||
- **NEW**: **Stable Resource Registry & LLM-Context Alias Compaction** — a request-local resource registry (migration `000069_resource_registry`) assigns stable `res://` aliases to retrieved sources so LLM context stays compact and citations remain consistent; includes orphan-alias detection/logging and Markdown-based image context normalization.
|
||||
- **NEW**: **@Skill / @MCP Mentions with Scoped Agent Runtime** — mention skills and MCP services inline in chat to scope the agent runtime for a single turn, with hardened `@mention` scope resolution and consolidated per-turn scoping across knowledge tools.
|
||||
- **NEW**: **Mid-Conversation MCP OAuth** — MCP services can prompt for and resume OAuth authorization mid-chat, driven by `AuthType` with auto-detection on test, an OAuth skip endpoint, and in-chat OAuth interaction cards aligned with the agent tool timeline.
|
||||
- **NEW**: **QQBot & Lark (Feishu International) IM Integration** — new QQBot instant-messaging platform integration and support for Feishu's international edition (Lark), including region-aware routing and reply-in-thread via the Feishu reply-message API.
|
||||
- **NEW**: **`weknora` CLI v0.10** (BREAKING) — an agent-first CLI refresh: new `model`, `message`, `config`, and `skills` command groups; `doc reparse` / `doc update`; `kb config` / `kb config set`; `session resume` (renamed from `continue`) and `session tool-approval`; agent-first chat and `session ask` output modes; typed SDK errors/enums and KB model config; hardened SSE reliability; schema and exit-code contracts.
|
||||
- **NEW**: **Redis TLS Support** — TLS connections to Redis with config surfaced at startup and hardened TLS tests (#1930).
|
||||
- **NEW**: **New Providers** — Requesty added as an OpenAI-compatible model provider; Keenable added as a configurable web search provider.
|
||||
- **NEW**: **Tenantless Provisioning & Gated Self-Service Workspaces** — OIDC/login provisioning can create users without a tenant, with gated self-service workspace creation and a workspace onboarding flow, unified under a shared `default_tenant_mode` policy.
|
||||
- **NEW**: **Admin Password Reset & System Settings Tabs** — system admins can reset user passwords with session revocation and edit builtin model configs; system settings reorganized into tabbed sections. Password fields are sanitized in logs.
|
||||
- **NEW**: **Knowledge Base Duplicate Flow** — clone a knowledge base (config + structure) via a dedicated API and UI; custom instruction fields added to KB configuration with length validation.
|
||||
- **NEW**: **Per-Agent Citation Output Toggle** — agents can enable/disable citation output; retrieval references are still emitted to the references drawer even when in-answer citations are disabled.
|
||||
- **NEW**: **Chat References Drawer & UX Polish** — a dedicated references drawer with web/KB source distinction, inline session-title rename in the sidebar, chat reference links opening in new tabs, and native streaming loading placeholders.
|
||||
|
||||
### Improvements
|
||||
|
||||
- **IMPROVED**: **Security hardening (broad triage)** — closed numerous open GHSA findings and security-triage gaps: SSRF protection across web_fetch, datasource connectors, knowledge URL import (including redirect chains), MinerU, embedders, and model clients; secret redaction in login, tenant KV, integration-list, and initialization/parser-check responses; SQL-validator bypass closed in agent database tools; refresh-token validation hardened (blocked as bearer); MCP upload sandbox enforced across transports; wiki/IDOR KB-access enforcement; nginx iframe `X-Frame-Options`.
|
||||
- **IMPROVED**: **Wiki ingestion** — dedicated worker pool with concurrent claim-based batching; recovers stranded claims, prevents finalize double-run and cross-batch document races, and strips internal chunk aliases from page content.
|
||||
- **IMPROVED**: **Knowledge processing** — safe task recovery after server restart, chunking strategy propagated to parent-child splitter configs, richer error handling in knowledge spans, rune-aware span-name fitting with expanded name column, and processing-timeline status aligned with the knowledge row.
|
||||
- **IMPROVED**: **Terminology** — user-facing "tenant" labels renamed to "workspace" across the UI and i18n.
|
||||
- **IMPROVED**: **Chat streaming** — unified streaming wait indicators across chat and embed, follow-up suggestion loading and answer-toolbar timing polished, references drawer closed on session switch, and enforced retrieved-image output in answers.
|
||||
- **IMPROVED**: **Frontend resilience** — hardened settings `localStorage` load to prevent white-screen from corrupted state; shared document action menu and card-view components extracted; Wiki badge on KB cards; responsive doc filter bar.
|
||||
- **IMPROVED**: **Infrastructure config** — infrastructure host/port configurable via env vars in docker-compose; remote infrastructure supported via `.env.local`; `WEKNORA_MODEL_MAX_CONCURRENCY` defaulted to 32.
|
||||
- **IMPROVED**: **docreader** — SSRF utility and safe HTTP client added; legacy doc-payload detection; parser routing tests.
|
||||
|
||||
### Bug Fixes
|
||||
|
||||
- **FIXED**: Chat now emits retrieval references even when citation output is disabled.
|
||||
- **FIXED**: `/api/v1/tenants/kv/storage-engine-config` returned no Huawei OBS config, causing the KB-creation dialog to omit the OBS unavailable marker.
|
||||
- **FIXED**: Empty tenant `default_provider` fell back to `local` even when `local` was not in `STORAGE_ALLOW_LIST`, breaking KB creation.
|
||||
- **FIXED**: DingTalk file/image messages now ingest into the knowledge base with SSRF-checked downloads and `pictureDownloadCode` fallback (#1771).
|
||||
- **FIXED**: Feishu WebSocket long connection now actually closes when the channel is stopped; replies land in the original thread.
|
||||
- **FIXED**: Tag filters correctly applied to knowledge search; tag-scope resolution hardened (#1907).
|
||||
- **FIXED**: Scoped API keys can poll FAQ import progress; KB-scoped file proxy restricted to `exports/` paths while still serving shared KB images.
|
||||
- **FIXED**: Web-search controls gated by provider readiness; agent selector capability status chips polished.
|
||||
- **FIXED**: Manual knowledge editor publish flow; doc list reloads after tag rename in the manage drawer.
|
||||
- **FIXED**: Division-by-zero guard in FAQ import timing logs; VLM temperature made configurable.
|
||||
|
||||
### Infrastructure & Build
|
||||
|
||||
- **BUILD**: Migrations `000064_principal_model`, `000065_tenant_api_keys`, `000066_expand_knowledge_span_name`, `000067_question_suggestions`, `000068_storage_backends`, `000069_resource_registry`, `000070_temporary_documents`.
|
||||
- **BUILD**: Per-pool task-queue governance (core / post-process / enrichment / maintenance / shared / wiki); model concurrency limiter/governor package.
|
||||
- **BUILD**: Go client extended for scoped API keys, storage backends, message suggestions, KB duplicate, and streaming error types; resolved open Dependabot alerts across Go, npm, and pip.
|
||||
- **BUILD**: Swagger / API docs regenerated; `docs/api/storage-backend.md` added.
|
||||
|
||||
### Documentation
|
||||
|
||||
- **DOC**: `docs/worker-pool-governance.md` added; `docs/api/storage-backend.md` added.
|
||||
- **DOC**: `docs/QA.md`, wiki docs, and per-feature guides extended for scoped API keys, storage backends, runtime queues, temporary attachments, and MCP OAuth.
|
||||
- **DOC**: Architecture diagram updated for scoped API keys, multi-instance storage, and worker-pool governance.
|
||||
|
||||
## [0.6.3] - 2026-06-26
|
||||
|
||||
### New Features
|
||||
|
||||
@@ -28,7 +28,7 @@
|
||||
<img src="https://img.shields.io/badge/License-MIT-ffffff?labelColor=d4eaf7&color=2e6cc4" alt="License">
|
||||
</a>
|
||||
<a href="./CHANGELOG.md">
|
||||
<img alt="Version" src="https://img.shields.io/badge/version-0.6.3-2e6cc4?labelColor=d4eaf7">
|
||||
<img alt="Version" src="https://img.shields.io/badge/version-0.7.1-2e6cc4?labelColor=d4eaf7">
|
||||
</a>
|
||||
</p>
|
||||
|
||||
@@ -50,19 +50,21 @@
|
||||
|
||||
[**WeKnora**](https://weknora.weixin.qq.com) is an open-source, LLM-powered knowledge framework built for enterprise-grade document understanding, semantic retrieval, and autonomous reasoning.
|
||||
|
||||
It is organized around three core capabilities: **RAG-based Quick Q&A** for everyday lookups, a **ReAct Agent** that autonomously orchestrates retrieval, MCP tools and web search to handle complex multi-step tasks, and a brand-new **Wiki Mode** in which agents distill raw documents into a self-maintaining, interlinked markdown knowledge base with an interactive knowledge graph. Combined with multi-source ingestion (Feishu / Notion / Yuque / RSS, and growing), **website embed widgets** for publishing agents to external sites, 20+ LLM provider integrations, full Langfuse observability, **enterprise-ready multi-tenant RBAC** (4-tier role matrix + per-resource ownership + per-tenant audit log), and a fully self-hostable modular architecture, WeKnora turns scattered documents into a queryable, reasoning-capable, continuously evolving knowledge asset.
|
||||
It is organized around three core capabilities: **RAG-based Quick Q&A** for everyday lookups, a **ReAct Agent** that autonomously orchestrates retrieval, MCP tools and web search to handle complex multi-step tasks, and a brand-new **Wiki Mode** in which agents distill raw documents into a self-maintaining, interlinked markdown knowledge base with an interactive knowledge graph. Combined with multi-source ingestion (Feishu / Notion / Yuque / RSS, and growing), **website embed widgets** for publishing agents to external sites, **scoped API keys with a principal model** for programmatic integrations, **multi-instance storage backends** per workspace for flexible data placement, 20+ LLM provider integrations, full Langfuse observability plus a **runtime task-queue dashboard with worker-pool governance**, **enterprise-ready multi-workspace RBAC** (4-tier role matrix + per-resource ownership + per-workspace audit log), and a fully self-hostable modular architecture, WeKnora turns scattered documents into a queryable, reasoning-capable, continuously evolving knowledge asset.
|
||||
|
||||
The framework supports auto-syncing knowledge from Feishu, Notion, and Yuque (more data sources coming soon), handles 10+ document formats including PDF, Word, images, and Excel, and can serve Q&A directly through IM channels like WeCom, Feishu, Slack, and Telegram. It is compatible with major LLM providers including OpenAI, DeepSeek, Qwen (Alibaba Cloud), Zhipu, Hunyuan, Gemini, MiniMax, NVIDIA, and Ollama. Its fully modular design allows swapping LLMs, vector databases, and storage backends, with support for local and private cloud deployment ensuring complete data sovereignty. WeKnora also integrates with **Langfuse** for comprehensive observability into agent reasoning, token usage, and pipeline tracing.
|
||||
|
||||
|
||||
## ✨ Latest Updates
|
||||
|
||||
- **v0.7.1** — New **Yunzhijia (云之家) IM integration** (WebSocket + image messages + markdown replies); **Volcengine rerank** provider (with request batching) and **Zhipu AI web search** provider; **platform-scoped API keys** for control-plane automation (tenant management, system settings, runtime queues, audit logs); **per-KB activity audit trail**; FAQ management enhancements (filtering, tagging, export, import tracking); **Langfuse OTLP/OTel tracing** migration with W3C traceparent propagation; chat header actions with one-click **Markdown export** and wiki tool results in the references drawer; prompt-cache observability; session channel governance (admin-scoped IM/embed/API sessions); resilient Feishu large-wiki sync; and removal of the legacy Neo4j conversation-memory dependency. Plus broad slug-integrity, SSRF-transport, and state-sync hardening. See [`CHANGELOG.md`](./CHANGELOG.md).
|
||||
- **v0.7.0** — Fine-grained **scoped API keys & principal model** (capability-level grants + per-KB restriction + API integration playground); **runtime task-queue observability dashboard & worker-pool governance** (per-stage pools + per-model concurrency governors + failed-task inspection/retry); **multi-instance storage backends** (multiple storage instances per workspace, per-KB binding, default instance); **session-scoped temporary attachments** (async image/doc parsing + combined limits); question & follow-up suggestions; stable resource registry with LLM-context alias compaction; `@Skill / @MCP` mentions with scoped agent runtime; mid-conversation MCP OAuth; QQBot & Lark (Feishu International) IM integration; Redis TLS; Requesty model provider + Keenable web search; tenantless provisioning & gated self-service workspaces; admin password reset; knowledge base duplicate flow; `weknora` CLI v0.10. Plus broad security hardening (SSRF, secret redaction, SQL validation, IDOR). See [`CHANGELOG.md`](./CHANGELOG.md).
|
||||
- **v0.6.3** — Website embed widget & Integrations Center (secure-mode token exchange + rate limits); chat experience overhaul (citation popovers, RAG pipeline progress, streaming markdown); document multi-tag & batch reparse; Wiki folders & hierarchy navigation; RSS data source; MCP OAuth2; EPUB / MHTML parsing; agent model-readiness checks; model test debugger; session source filter; workspace deletion UI. See [`CHANGELOG.md`](./CHANGELOG.md).
|
||||
- **v0.6.2** — Per-upload process configuration with upload-confirm dialog; document reparse with `process_config`; `weknora` CLI v0.9 (bundled Agent Skills, `session stop`, auth/profile harmonization); KB marquee multi-select; HNSW index for 1024-dim pgvector embeddings; chat resources store refactor; Langfuse-only tracing (Jaeger removed). See [`CHANGELOG.md`](./CHANGELOG.md).
|
||||
- **v0.6.1** — Document parsing trace timeline (Langfuse-style span tree with stage-by-stage progress + stop-parse); OpenSearch vector store driver; declarative built-in models via YAML; system admin & consolidated platform settings + audit log; new-user onboarding guide; settings UI redesign; `weknora` CLI v0.7 / v0.8 (agent-first wire contract, NDJSON, `--dry-run`); OpenDataLoader + PaddleOCR-VL parsers; MCP server multi-transport (stdio / SSE / HTTP); per-model thinking-mode config; Tencent LKEAP rerank + native Gemini embeddings + MiniMax-M3. See [`CHANGELOG.md`](./CHANGELOG.md).
|
||||
- **v0.6.0** — Tenant RBAC (4-tier role matrix `Owner` / `Admin` / `Contributor` / `Viewer` + per-KB ownership + per-tenant audit log), tenant member management & multi-workspace UX, self-service workspaces; `weknora` CLI v0.4 GA with `mcp serve`; KB retrieval fan-out across vector stores; AES-256-GCM credential encryption + docreader gRPC TLS + Token; Zhipu embedder + Huawei OBS; server-side user preferences; Go 1.26.0. See [`docs/RBAC说明.md`](./docs/RBAC说明.md) and [`CHANGELOG.md`](./CHANGELOG.md).
|
||||
- **v0.6.0** — Workspace RBAC (4-tier role matrix `Owner` / `Admin` / `Contributor` / `Viewer` + per-KB ownership + per-workspace audit log), workspace member management & multi-workspace UX, self-service workspaces; `weknora` CLI v0.4 GA with `mcp serve`; KB retrieval fan-out across vector stores; AES-256-GCM credential encryption + docreader gRPC TLS + Token; Zhipu embedder + Huawei OBS; server-side user preferences; Go 1.26.0. See [`docs/RBAC说明.md`](./docs/RBAC说明.md) and [`CHANGELOG.md`](./CHANGELOG.md).
|
||||
- **v0.5.2** — Wiki ingest scales to 40k-document KBs (task queue + DLQ); MCP human-in-the-loop tool approval; Anthropic / Apache Doris / Tencent VectorDB / KS3 / SearXNG backends; adaptive 3-tier chunking with live preview; global ⌘K command palette; Yuque connector + WeChat Mini Program; `weknora` CLI preview.
|
||||
- **v0.5.1** — Knowledge-base batch management; tenant-wide IM channels overview; session search + user-scoped pinning; unified Model / Web Search / MCP settings cards; per-agent LLM timeout; desktop tenant switching.
|
||||
- **v0.5.1** — Knowledge-base batch management; workspace-wide IM channels overview; session search + user-scoped pinning; unified Model / Web Search / MCP settings cards; per-agent LLM timeout; desktop workspace switching.
|
||||
- **v0.5.0** — Wiki Mode GA — agents auto-generate structured, interlinked Markdown wiki pages with a knowledge graph; wiki browser + visual graph in the UI.
|
||||
- **v0.4.0** — WeKnora Cloud (hosted LLM + parsing); Chrome Extension; ClawHub Skill; WeChat IM; attachment processing; Azure OpenAI / Alibaba OSS; Notion connector; Baidu + Ollama web search; VectorStore management.
|
||||
- **v0.3.6** — ASR (audio); Feishu data-source auto-sync; OIDC; IM quote-reply context + thread-based sessions; document summarization; Tavily search; parallel tool calling; agent @mention scope restriction.
|
||||
@@ -108,11 +110,12 @@ Fully modular pipeline from document parsing, vectorization, and retrieval to LL
|
||||
| Intelligent Reasoning | ReACT progressive multi-step reasoning, autonomously orchestrating knowledge retrieval, MCP tools, and web search |
|
||||
| Quick Q&A | RAG-based Q&A over knowledge bases for fast and accurate answers |
|
||||
| Wiki Mode | Agent-driven auto-generation of structured, interlinked markdown Wiki pages from raw documents |
|
||||
| Tool Calling | Built-in tools, MCP tools (incl. OAuth2 remote services), web search |
|
||||
| Conversation Strategy | Online Prompt editing, retrieval threshold tuning, multi-turn context awareness |
|
||||
| Suggested Questions | Auto-generated question suggestions based on knowledge base content |
|
||||
| Citations & RAG Progress | Inline citation popovers, shared markdown rendering, and stage-by-stage RAG pipeline progress in chat |
|
||||
| Session Management | Filter and group sidebar sessions by source (Web / IM / Embed) |
|
||||
| Tool Calling | Built-in tools, MCP tools (incl. OAuth2 remote services, mid-conversation OAuth), web search; `@Skill / @MCP` mentions to scope the agent runtime per turn |
|
||||
| Conversation Strategy | Online Prompt editing, retrieval threshold tuning, multi-turn context awareness, per-agent citation output toggle |
|
||||
| Suggested Questions | Auto-generated question suggestions and after-answer follow-ups based on knowledge base content |
|
||||
| Temporary Attachments | Session-scoped image / document uploads with async parsing for one-off Q&A, with a combined image + attachment limit |
|
||||
| Citations & RAG Progress | Inline citation popovers and a references drawer (web / KB source distinction), shared markdown rendering, and stage-by-stage RAG pipeline progress in chat |
|
||||
| Session Management | Filter and group sidebar sessions by source (Web / IM / Embed), with inline session-title rename |
|
||||
|
||||
**Knowledge Management**
|
||||
|
||||
@@ -131,13 +134,14 @@ Fully modular pipeline from document parsing, vectorization, and retrieval to LL
|
||||
|
||||
| Capability | Details |
|
||||
|------------|---------|
|
||||
| LLMs | OpenAI / Azure OpenAI / Anthropic (Claude) / DeepSeek / Qwen (Alibaba Cloud) / Zhipu / Hunyuan / Doubao (Volcengine) / Gemini / MiniMax / NVIDIA / Novita AI / SiliconFlow / OpenRouter / Ollama |
|
||||
| LLMs | OpenAI / Azure OpenAI / Anthropic (Claude) / DeepSeek / Qwen (Alibaba Cloud) / Zhipu / Hunyuan / Doubao (Volcengine) / Gemini / MiniMax / NVIDIA / Novita AI / SiliconFlow / OpenRouter / Requesty / Ollama |
|
||||
| Embeddings | Ollama / BGE / GTE / Zhipu / OpenAI-compatible APIs |
|
||||
| Vector DBs | PostgreSQL (pgvector) / Elasticsearch / OpenSearch / Milvus / Weaviate / Qdrant / Apache Doris / Tencent VectorDB |
|
||||
| Object Storage | Local / MinIO / AWS S3 / Volcengine TOS / Alibaba Cloud OSS / Kingsoft Cloud KS3 / Huawei Cloud OBS |
|
||||
| IM Channels | WeCom / Feishu / Slack / Telegram / DingTalk / Mattermost / WeChat |
|
||||
| Object Storage | Local / MinIO / AWS S3 / Volcengine TOS / Alibaba Cloud OSS / Kingsoft Cloud KS3 / Huawei Cloud OBS; **multiple storage instances per workspace** with per-KB binding and a default instance |
|
||||
| IM Channels | WeCom / Feishu / Lark (Feishu International) / QQBot / Slack / Telegram / DingTalk / Mattermost / WeChat / Yunzhijia |
|
||||
| Website Embed | Publish agents via embed widget with domain allowlists, rate limits, and secure-mode token exchange |
|
||||
| Web Search | DuckDuckGo / Bing / Google / Tavily / Baidu / Ollama / SearXNG |
|
||||
| Web Search | DuckDuckGo / Bing / Google / Tavily / Baidu / Ollama / SearXNG / Keenable / Zhipu AI |
|
||||
| API Integration | Scoped API keys (capability-level grants + per-KB restriction + throttled last-used tracking) with an API integration playground; MCP OAuth and embed sessions isolated per principal |
|
||||
|
||||
**Platform**
|
||||
|
||||
@@ -145,11 +149,11 @@ Fully modular pipeline from document parsing, vectorization, and retrieval to LL
|
||||
|------------|---------|
|
||||
| Deployment | Local / Docker / Kubernetes (Helm) with private and offline support |
|
||||
| UI | Web UI / RESTful API / CLI (`weknora`) / Chrome Extension / Website Embed Widget / WeChat Mini Program |
|
||||
| Access Control | Tenant RBAC with 4-tier role matrix (Owner / Admin / Contributor / Viewer), per-KB resource ownership, per-tenant audit log, invite-only workspaces, self-service tenant creation, cross-tenant superuser |
|
||||
| Security | AES-256-GCM at-rest encryption for API keys and MCP / data-source credentials with graceful key rotation; gRPC TLS + Token between app and docreader; SSRF-safe HTTP client; sandbox isolation for agent skills |
|
||||
| Observability | Integrated Langfuse (sole tracing backend) for ReAct loops, token tracking, tool calls, and pipeline tracing; built-in Langfuse-style document parsing trace timeline with stage-by-stage progress |
|
||||
| Task Management | MQ async tasks, automatic database migration on version upgrade |
|
||||
| Model Management | Centralized config, declarative built-in models via YAML, per-knowledge-base model selection, per-model thinking-mode and embedding-dimension overrides, interactive model test debugger, multi-tenant built-in model sharing, WeKnora Cloud hosted models and parsing |
|
||||
| Access Control | Workspace RBAC with 4-tier role matrix (Owner / Admin / Contributor / Viewer), per-KB resource ownership, per-workspace audit log, invite-only workspaces, tenantless provisioning & gated self-service workspace creation, admin password reset (session revocation), cross-workspace superuser, scoped API keys |
|
||||
| Security | AES-256-GCM at-rest encryption for API keys and MCP / data-source credentials with graceful key rotation; gRPC TLS + Token between app and docreader; Redis TLS; SSRF-safe HTTP client (data sources, URL import, redirect chains); secret redaction in responses; sandbox isolation for agent skills |
|
||||
| Observability | Integrated Langfuse (sole tracing backend) for ReAct loops, token tracking, tool calls, and pipeline tracing; built-in Langfuse-style document parsing trace timeline with stage-by-stage progress; system-admin runtime task-queue dashboard (queue depth, per-model concurrency, failed-task inspection & manual retry) |
|
||||
| Task Management | MQ async tasks with per-stage worker-pool governance (core / post-process / enrichment / maintenance + elastic shared pool, plus an independent Wiki pool) and per-model background concurrency governors; automatic database migration on version upgrade |
|
||||
| Model Management | Centralized config, declarative built-in models via YAML, per-knowledge-base model selection, per-model thinking-mode and embedding-dimension overrides, interactive model test debugger, multi-workspace built-in model sharing, WeKnora Cloud hosted models and parsing |
|
||||
|
||||
## 🧩 Chrome Extension
|
||||
|
||||
@@ -171,23 +175,26 @@ The [WeKnora Mini Program](./miniprogram/README.md) provides a lightweight mobil
|
||||
|
||||
## ⌨️ Command-Line Interface
|
||||
|
||||
`weknora` is the official CLI for driving the API from a terminal or AI agent.
|
||||
The command surface mirrors `gh` CLI's `<noun> <verb>` convention; output is
|
||||
human-readable by default and switches to a stable JSON envelope with `--json`.
|
||||
v0.9 ships bundled Agent Skills (`weknora-rag-search`, `weknora-shared`), adds
|
||||
`session stop`, and harmonizes auth/profile workflows (see [`cli/CHANGELOG.md`](./cli/CHANGELOG.md)).
|
||||
`weknora` is the official CLI for driving the API from a terminal or an AI
|
||||
agent. It is **agent-first**: every command emits a stable JSON envelope by
|
||||
default (with typed error codes mapped to exit codes), and `--format text`
|
||||
renders for humans. It also serves a curated MCP tool surface
|
||||
(`weknora mcp serve`) and ships bundled Agent Skills.
|
||||
|
||||
```bash
|
||||
weknora auth login --host https://kb.example.com
|
||||
weknora profile add prod --host https://kb.example.com --use
|
||||
weknora auth login
|
||||
weknora kb list
|
||||
weknora link --kb my-knowledge-base # bind the current directory
|
||||
weknora doc upload notes.md
|
||||
weknora chat "summarise the design doc"
|
||||
```
|
||||
|
||||
See [`cli/README.md`](./cli/README.md) for install + 5-minute quickstart
|
||||
and [`cli/AGENTS.md`](./cli/AGENTS.md) for the operational contract that
|
||||
AI agents (Claude Code, Cursor, Aider, …) can rely on.
|
||||
For headless / CI use, set `WEKNORA_API_KEY` + `WEKNORA_HOST` and skip
|
||||
`auth login` entirely — no credentials written to disk.
|
||||
|
||||
See [`cli/README.md`](./cli/README.md) for install + 5-minute quickstart and
|
||||
[`cli/AGENTS.md`](./cli/AGENTS.md) for the operational contract AI agents rely on.
|
||||
|
||||
## 🚀 Getting Started
|
||||
|
||||
|
||||
+22
-18
@@ -28,7 +28,7 @@
|
||||
<img src="https://img.shields.io/badge/License-MIT-ffffff?labelColor=d4eaf7&color=2e6cc4" alt="License">
|
||||
</a>
|
||||
<a href="./CHANGELOG.md">
|
||||
<img alt="版本" src="https://img.shields.io/badge/version-0.6.3-2e6cc4?labelColor=d4eaf7">
|
||||
<img alt="版本" src="https://img.shields.io/badge/version-0.7.1-2e6cc4?labelColor=d4eaf7">
|
||||
</a>
|
||||
</p>
|
||||
|
||||
@@ -50,18 +50,20 @@
|
||||
|
||||
**[WeKnora(维娜拉)](https://weknora.weixin.qq.com)** 是一款开源的、基于大语言模型(LLM)的知识管理框架,专为企业级文档理解、语义检索与智能推理场景打造。
|
||||
|
||||
框架围绕三大核心能力构建:**RAG 快速问答**适合日常知识查询,**ReAct Agent 智能推理**自主编排知识检索、MCP 工具与网络搜索完成复杂多步任务,全新的 **Wiki 模式**则让 Agent 从原始文档中自治生成相互链接的 Markdown 知识库与可视化知识图谱。结合多源数据接入(飞书 / Notion / 语雀 / RSS,更多持续接入中)、**网站嵌入 Widget** 将智能体发布到外部站点、二十余家主流模型厂商集成、Langfuse 全链路可观测性、**企业级多租户 RBAC(四级角色矩阵 + 资源归属 + 租户审计日志)**,以及完全可私有化部署的模块化架构,WeKnora 帮助团队把分散文档沉淀为可查询、可推理、可持续演进的专属知识资产。
|
||||
框架围绕三大核心能力构建:**RAG 快速问答**适合日常知识查询,**ReAct Agent 智能推理**自主编排知识检索、MCP 工具与网络搜索完成复杂多步任务,全新的 **Wiki 模式**则让 Agent 从原始文档中自治生成相互链接的 Markdown 知识库与可视化知识图谱。结合多源数据接入(飞书 / Notion / 语雀 / RSS,更多持续接入中)、**网站嵌入 Widget** 将智能体发布到外部站点、**权限范围 API Key 与 Principal 模型**面向程序化集成、**每空间多实例存储后端**灵活编排数据落地、二十余家主流模型厂商集成、Langfuse 全链路可观测性与**运行时任务队列面板 + Worker 池治理**、**企业级多空间 RBAC(四级角色矩阵 + 资源归属 + 空间审计日志)**,以及完全可私有化部署的模块化架构,WeKnora 帮助团队把分散文档沉淀为可查询、可推理、可持续演进的专属知识资产。
|
||||
|
||||
框架支持从飞书、Notion 及语雀等外部平台自动同步知识(更多数据源持续接入中),覆盖 PDF、Word、图片、Excel 等十余种文档格式,并可通过企业微信、飞书、Slack、Telegram 等 IM 频道直接提供问答服务。模型层面兼容 OpenAI、DeepSeek、Qwen(阿里云)、智谱、混元、Gemini、MiniMax、NVIDIA、Ollama 等主流厂商。全流程模块化设计,大模型、向量数据库、存储等组件均可灵活替换,支持本地与私有云部署,数据完全自主可控。WeKnora 还无缝集成了 **Langfuse**,为 Agent 运行、Token 使用及任务流水线提供了全面的可观测性追踪。
|
||||
|
||||
## ✨ 最新更新
|
||||
|
||||
- **v0.7.1** —— 新增**云之家 IM 集成**(WebSocket + 图片消息 + Markdown 回复);**火山引擎 Rerank** 供应商(自动分批请求)与**智谱 AI 网络搜索**供应商;**平台级 API Key**,用于控制面自动化(租户管理、系统设置、运行时队列、审计日志);**按知识库的活动审计追踪**;FAQ 管理增强(筛选、打标签、导出、导入结果追踪);**Langfuse OTLP/OTel 追踪**迁移,支持 W3C traceparent 跨服务传播;对话头部操作栏,支持一键 **Markdown 导出**,并在引用抽屉中展示 Wiki 工具结果;Prompt 缓存可观测性;会话渠道治理(IM/嵌入/API 会话按管理员范围隔离);飞书大型 Wiki 同步韧性增强;移除旧版 Neo4j 会话记忆依赖。另有大范围的 slug 完整性、SSRF 传输与状态同步加固。详见 [`CHANGELOG.md`](./CHANGELOG.md)。
|
||||
- **v0.7.0** —— 细粒度**权限范围 API Key 与 Principal 模型**(能力级授权 + 按 KB 限制 + API 集成调试台);**运行时任务队列可观测面板与 Worker 池治理**(分阶段独立池 + 按模型并发治理 + 失败任务排查/重试);**多实例存储后端**(每空间多存储实例、按 KB 绑定、默认实例);**会话级临时附件**(图片/文档异步解析 + 合并限额);推荐问题与追问;稳定资源注册表与 LLM 上下文别名压缩;`@Skill / @MCP` 提及范围化 Agent 运行时;会话内 MCP OAuth 授权;QQBot 与 Lark(飞书国际版)IM 集成;Redis TLS;Requesty 模型厂商 + Keenable 网络搜索;无租户预置与受控自助创建工作区;管理员密码重置;知识库复制流程;`weknora` CLI v0.10。同时完成大范围安全加固(SSRF、密钥脱敏、SQL 校验、越权)。详见 [`CHANGELOG.md`](./CHANGELOG.md)。
|
||||
- **v0.6.3** —— 网站嵌入 Widget 与发布集成中心(安全模式 Token 交换 + 限流);对话体验全面革新(引用浮层、RAG 流水线进度、流式 Markdown);文档多标签与批量重新解析;Wiki 文件夹与层级导航;RSS 数据源;MCP OAuth2;EPUB / MHTML 解析;Agent 模型就绪校验;模型调试器;会话来源筛选;工作区删除 UI。详见 [`CHANGELOG.md`](./CHANGELOG.md)。
|
||||
- **v0.6.2** —— 按批次解析配置(`process_config`)+ 上传确认对话框;文档重新解析(reparse)支持覆盖配置;`weknora` CLI v0.9(内置 Agent Skills、`session stop`、auth/profile 统一);知识库框选多选;pgvector 1024 维 HNSW 索引;对话资源 Store 重构;仅保留 Langfuse 追踪(移除 Jaeger)。详见 [`CHANGELOG.md`](./CHANGELOG.md)。
|
||||
- **v0.6.1** —— 文档解析追踪时间线(Langfuse 风格 Span 树,逐阶段进度展示 + 解析中止);OpenSearch 向量库驱动;YAML 声明式内置模型配置;系统管理员与统一平台设置 + 审计日志;新用户引导;设置页 UI 重构;`weknora` CLI v0.7 / v0.8(Agent 优先线协议、NDJSON、`--dry-run`);OpenDataLoader 与 PaddleOCR-VL 解析引擎;MCP Server 多传输(stdio / SSE / HTTP);按模型的思考模式配置;腾讯云 LKEAP 重排 + 原生 Gemini Embedding + MiniMax-M3。详见 [`CHANGELOG.md`](./CHANGELOG.md)。
|
||||
- **v0.6.0** —— 租户 RBAC(四级角色矩阵 `Owner` / `Admin` / `Contributor` / `Viewer` + 按 KB 归属 + 每租户审计日志)、租户成员管理与多工作区 UX、自助创建工作区;`weknora` CLI v0.4 正式版 + `mcp serve`;KB 检索跨向量库扇出;MCP / 数据源凭据 AES-256-GCM 加密 + docreader gRPC TLS + Token;新增智谱 Embedding 与华为云 OBS;服务端用户偏好;Go 1.26.0。详见 [`docs/RBAC说明.md`](./docs/RBAC说明.md) 与 [`CHANGELOG.md`](./CHANGELOG.md)。
|
||||
- **v0.6.0** —— 空间 RBAC(四级角色矩阵 `Owner` / `Admin` / `Contributor` / `Viewer` + 按 KB 归属 + 每空间审计日志)、空间成员管理与多工作区 UX、自助创建工作区;`weknora` CLI v0.4 正式版 + `mcp serve`;KB 检索跨向量库扇出;MCP / 数据源凭据 AES-256-GCM 加密 + docreader gRPC TLS + Token;新增智谱 Embedding 与华为云 OBS;服务端用户偏好;Go 1.26.0。详见 [`docs/RBAC说明.md`](./docs/RBAC说明.md) 与 [`CHANGELOG.md`](./CHANGELOG.md)。
|
||||
- **v0.5.2** —— Wiki 入库支撑万级文档知识库(任务队列 + 死信队列);MCP 工具人机审批;Anthropic / Apache Doris / 腾讯云 VectorDB / 金山云 KS3 / SearXNG 后端;自适应三层分块 + 实时调试面板;全局 ⌘K 命令面板;语雀连接器 + 微信小程序;`weknora` CLI 早期版本。
|
||||
- **v0.5.1** —— 知识库批量管理;租户级 IM 频道总览;会话搜索 + 用户级置顶;模型 / 网页搜索 / MCP 统一卡片化设置;按 Agent LLM 调用超时;桌面端租户切换。
|
||||
- **v0.5.1** —— 知识库批量管理;空间级 IM 频道总览;会话搜索 + 用户级置顶;模型 / 网页搜索 / MCP 统一卡片化设置;按 Agent LLM 调用超时;桌面端空间切换。
|
||||
- **v0.5.0** —— Wiki 模式正式版 —— Agent 从原始文档自治生成结构化、相互链接的 Markdown Wiki 页面及知识图谱;Wiki 浏览器 + 可视化图谱。
|
||||
- **v0.4.0** —— WeKnora Cloud(托管模型 + 解析);Chrome 插件;ClawHub Skill;微信 IM;附件处理;Azure OpenAI / 阿里云 OSS;Notion 连接器;百度 + Ollama 网页搜索;VectorStore 管理。
|
||||
- **v0.3.6** —— ASR 语音;飞书数据源自动同步;OIDC;IM 引用回复 + 线程会话;文档自动摘要;Tavily 搜索;并行工具调用;Agent @提及范围限制。
|
||||
@@ -107,11 +109,12 @@
|
||||
| 智能推理 | ReACT 渐进式多步推理,自主编排知识检索、MCP 工具与网络搜索 |
|
||||
| 快速问答 | 基于知识库的 RAG 问答,快速准确地回答问题 |
|
||||
| Wiki 模式 | Agent 驱动从原始文档中自动生成并维护结构化、相互链接的 Markdown Wiki 知识页面 |
|
||||
| 工具调用 | 内置工具、MCP 工具(含 OAuth2 远程服务)、网络搜索 |
|
||||
| 对话策略 | 在线 Prompt 编辑、检索阈值调节、多轮上下文感知 |
|
||||
| 推荐问题 | 基于知识库内容自动生成推荐问题 |
|
||||
| 引用与 RAG 进度 | 对话内引用浮层、统一 Markdown 渲染、RAG 流水线分阶段进度展示 |
|
||||
| 会话管理 | 侧边栏按来源(Web / IM / 嵌入)筛选与分组会话 |
|
||||
| 工具调用 | 内置工具、MCP 工具(含 OAuth2 远程服务、会话内 OAuth 授权)、网络搜索;支持 `@Skill / @MCP` 提及以按轮次范围化 Agent 运行时 |
|
||||
| 对话策略 | 在线 Prompt 编辑、检索阈值调节、多轮上下文感知、按 Agent 引用输出开关 |
|
||||
| 推荐问题 | 基于知识库内容自动生成推荐问题与答后追问 |
|
||||
| 临时附件 | 会话级临时上传图片 / 文档,异步解析后用于一次性问答,支持图片与附件合并限额 |
|
||||
| 引用与 RAG 进度 | 对话内引用浮层与引用抽屉(区分网络 / 知识库来源)、统一 Markdown 渲染、RAG 流水线分阶段进度展示 |
|
||||
| 会话管理 | 侧边栏按来源(Web / IM / 嵌入)筛选与分组会话,支持会话标题内联重命名 |
|
||||
|
||||
**知识管理**
|
||||
|
||||
@@ -130,13 +133,14 @@
|
||||
|
||||
| 能力 | 详情 |
|
||||
|------|------|
|
||||
| 模型厂商 | OpenAI / Azure OpenAI / Anthropic(Claude)/ DeepSeek / Qwen(阿里云)/ 智谱 / 混元 / 豆包(火山引擎)/ Gemini / MiniMax / NVIDIA / Novita AI / SiliconFlow / OpenRouter / Ollama |
|
||||
| 模型厂商 | OpenAI / Azure OpenAI / Anthropic(Claude)/ DeepSeek / Qwen(阿里云)/ 智谱 / 混元 / 豆包(火山引擎)/ Gemini / MiniMax / NVIDIA / Novita AI / SiliconFlow / OpenRouter / Requesty / Ollama |
|
||||
| 向量数据库 | PostgreSQL (pgvector) / Elasticsearch / OpenSearch / Milvus / Weaviate / Qdrant / Apache Doris / 腾讯云 VectorDB |
|
||||
| Embedding | Ollama / BGE / GTE / 智谱 / OpenAI 兼容接口 |
|
||||
| 对象存储 | 本地 / 腾讯云COS / 火山引擎 TOS / MinIO / AWS S3 / 阿里云 OSS / 金山云 KS3 / 华为云 OBS |
|
||||
| IM 集成 | 企业微信 / 飞书 / Slack / Telegram / 钉钉 / Mattermost / 微信 |
|
||||
| 对象存储 | 本地 / 腾讯云COS / 火山引擎 TOS / MinIO / AWS S3 / 阿里云 OSS / 金山云 KS3 / 华为云 OBS;支持**每空间多实例存储后端**,不同知识库可绑定不同实例并设置默认实例 |
|
||||
| IM 集成 | 企业微信 / 飞书 / Lark(飞书国际版)/ QQBot / Slack / Telegram / 钉钉 / Mattermost / 微信 / 云之家 |
|
||||
| 网站嵌入 | 通过嵌入 Widget 发布智能体,支持域名白名单、限流与安全模式 Token 交换 |
|
||||
| 网络搜索 | DuckDuckGo / Bing / Google / Tavily / Baidu / Ollama / SearXNG |
|
||||
| 网络搜索 | DuckDuckGo / Bing / Google / Tavily / Baidu / Ollama / SearXNG / Keenable / 智谱 AI |
|
||||
| API 集成 | 权限范围 API Key(能力级授权 + 按 KB 限制 + 节流的 last_used 追踪)与 API 集成调试台;MCP OAuth 与嵌入会话按 Principal 隔离 |
|
||||
|
||||
|
||||
**平台能力**
|
||||
@@ -145,11 +149,11 @@
|
||||
|------|------|
|
||||
| 部署 | 本地 / Docker / Kubernetes (Helm),支持私有化离线部署 |
|
||||
| 界面 | Web UI / RESTful API / 命令行(`weknora`)/ Chrome Extension / 网站嵌入 Widget / 微信小程序 |
|
||||
| 权限控制 | 租户 RBAC 四级角色矩阵(Owner / Admin / Contributor / Viewer),按知识库的资源归属,每租户审计日志,invite-only 准入,自助创建工作区,跨租户超级管理员 |
|
||||
| 安全 | API Key 与 MCP / 数据源凭据 AES-256-GCM 静态加密、支持平滑密钥轮换;app ↔ docreader gRPC TLS + Token;防 SSRF HTTP 客户端;Agent 技能沙箱隔离 |
|
||||
| 可观测性 | 集成 Langfuse(唯一追踪后端)以追踪 ReAct 循环、Token 消耗、工具调用和任务流水线;内置 Langfuse 风格的文档解析追踪时间线,逐阶段展示解析进度 |
|
||||
| 任务管理 | MQ 异步任务,版本升级自动数据库迁移 |
|
||||
| 模型管理 | 集中配置,YAML 声明式内置模型配置,知识库级别模型选择,按模型思考模式与 Embedding 维度覆盖,交互式模型调试器,多租户共享内置模型,WeKnora Cloud 托管模型与文档解析 |
|
||||
| 权限控制 | 空间 RBAC 四级角色矩阵(Owner / Admin / Contributor / Viewer),按知识库的资源归属,每空间审计日志,invite-only 准入,无租户预置与受控自助创建工作区,管理员密码重置(会话吊销),跨空间超级管理员,权限范围 API Key |
|
||||
| 安全 | API Key 与 MCP / 数据源凭据 AES-256-GCM 静态加密、支持平滑密钥轮换;app ↔ docreader gRPC TLS + Token;Redis TLS;防 SSRF HTTP 客户端(覆盖数据源、URL 导入、重定向链等);密钥响应脱敏;Agent 技能沙箱隔离 |
|
||||
| 可观测性 | 集成 Langfuse(唯一追踪后端)以追踪 ReAct 循环、Token 消耗、工具调用和任务流水线;内置 Langfuse 风格的文档解析追踪时间线,逐阶段展示解析进度;系统管理员运行时任务队列面板(队列深度、按模型并发、失败任务排查与手动重试) |
|
||||
| 任务管理 | MQ 异步任务,分阶段独立 Worker 池治理(core / 后处理 / enrichment / maintenance + 弹性共享池,Wiki 独立池)与按模型后台并发治理;版本升级自动数据库迁移 |
|
||||
| 模型管理 | 集中配置,YAML 声明式内置模型配置,知识库级别模型选择,按模型思考模式与 Embedding 维度覆盖,交互式模型调试器,多空间共享内置模型,WeKnora Cloud 托管模型与文档解析 |
|
||||
|
||||
## 🧩 Chrome 插件
|
||||
|
||||
|
||||
+17
-13
@@ -28,7 +28,7 @@
|
||||
<img src="https://img.shields.io/badge/License-MIT-ffffff?labelColor=d4eaf7&color=2e6cc4" alt="License">
|
||||
</a>
|
||||
<a href="./CHANGELOG.md">
|
||||
<img alt="バージョン" src="https://img.shields.io/badge/version-0.6.3-2e6cc4?labelColor=d4eaf7">
|
||||
<img alt="バージョン" src="https://img.shields.io/badge/version-0.7.1-2e6cc4?labelColor=d4eaf7">
|
||||
</a>
|
||||
</p>
|
||||
|
||||
@@ -50,12 +50,14 @@
|
||||
|
||||
[**WeKnora(ウィーノラ)**](https://weknora.weixin.qq.com) は、大規模言語モデル(LLM)をベースとしたオープンソースのナレッジフレームワークで、エンタープライズ級の文書理解、セマンティック検索、自律推論シナリオ向けに設計されています。
|
||||
|
||||
本フレームワークは **3 つのコア能力** を中心に構築されています:日常的な検索に最適な **RAG ベースのクイック Q&A**、ナレッジ検索・MCP ツール・Web 検索を自律的にオーケストレーションし複雑なマルチステップタスクを処理する **ReAct Agent 推論**、そして Agent が生のドキュメントから相互リンクされた Markdown ナレッジベースとインタラクティブなナレッジグラフを自律生成・維持する全く新しい **Wiki モード**。さらに、多様なデータソース連携(Feishu / Notion / Yuque / RSS、随時拡充中)、**ウェブサイト埋め込み Widget** による外部サイトへのエージェント公開、20 以上の LLM プロバイダー統合、Langfuse による全体可観測性、**エンタープライズ向けマルチテナント RBAC(4 階層ロールマトリクス + リソース所有権 + テナント監査ログ)**、完全セルフホスト可能なモジュラーアーキテクチャと組み合わせることで、WeKnora は散在する文書を「検索可能・推論可能・継続的に進化する」専用ナレッジ資産へと昇華させます。
|
||||
本フレームワークは **3 つのコア能力** を中心に構築されています:日常的な検索に最適な **RAG ベースのクイック Q&A**、ナレッジ検索・MCP ツール・Web 検索を自律的にオーケストレーションし複雑なマルチステップタスクを処理する **ReAct Agent 推論**、そして Agent が生のドキュメントから相互リンクされた Markdown ナレッジベースとインタラクティブなナレッジグラフを自律生成・維持する全く新しい **Wiki モード**。さらに、多様なデータソース連携(Feishu / Notion / Yuque / RSS、随時拡充中)、**ウェブサイト埋め込み Widget** による外部サイトへのエージェント公開、プログラム連携向けの**スコープ付き API キーと Principal モデル**、ワークスペースごとの**マルチインスタンスストレージバックエンド**、20 以上の LLM プロバイダー統合、Langfuse による全体可観測性と**ランタイムタスクキューダッシュボード + Worker プール統治**、**エンタープライズ向けマルチテナント RBAC(4 階層ロールマトリクス + リソース所有権 + テナント監査ログ)**、完全セルフホスト可能なモジュラーアーキテクチャと組み合わせることで、WeKnora は散在する文書を「検索可能・推論可能・継続的に進化する」専用ナレッジ資産へと昇華させます。
|
||||
|
||||
Feishu、Notion、Yuqueなどの外部プラットフォームからのナレッジ自動同期(他のデータソースも順次対応中)に対応し、PDF、Word、画像、Excelなど10以上の文書フォーマットをサポート。WeChat Work、Feishu、Slack、TelegramなどのIMチャネルから直接Q&Aサービスを提供できます。モデル層ではOpenAI、DeepSeek、Qwen(Alibaba Cloud)、Zhipu、Hunyuan、Gemini、MiniMax、NVIDIA、Ollamaなど主要プロバイダーに対応。全プロセスをモジュラー設計し、大規模モデル、ベクトルデータベース、ストレージなどのコンポーネントを柔軟に差し替え可能。ローカルおよびプライベートクラウドデプロイに対応し、データは完全に自己管理可能です。さらにWeKnoraは **Langfuse** とシームレスに統合され、Agentの推論、トークン消費、パイプラインに対する包括的な可観測性(オブザーバビリティ)を提供します。
|
||||
|
||||
## ✨ 最新アップデート
|
||||
|
||||
- **v0.7.1** — 新しい**Yunzhijia(云之家)IM 連携**(WebSocket + 画像メッセージ + Markdown 返信);**Volcengine Rerank** プロバイダー(リクエストの自動分割)と **Zhipu AI Web 検索**プロバイダー;コントロールプレーン自動化向けの**プラットフォームスコープ API キー**(テナント管理、システム設定、ランタイムキュー、監査ログ);**KB 単位のアクティビティ監査証跡**;FAQ 管理の強化(フィルタリング、タグ付け、エクスポート、インポート結果追跡);**Langfuse OTLP/OTel トレーシング**への移行と W3C traceparent 伝播;チャットヘッダーアクションによるワンクリック **Markdown エクスポート**、参照ドロワーへの Wiki ツール結果表示;プロンプトキャッシュ可観測性;セッションチャネルガバナンス(IM/埋め込み/API セッションを管理者スコープで分離);Feishu 大規模 Wiki 同期の堅牢化;レガシー Neo4j 会話メモリ依存の削除。加えて広範な slug 整合性・SSRF トランスポート・状態同期の強化。詳細は [`CHANGELOG.md`](./CHANGELOG.md)。
|
||||
- **v0.7.0** — きめ細かい**スコープ付き API キーと Principal モデル**(能力単位の付与 + KB 単位の制限 + API 連携プレイグラウンド);**ランタイムタスクキュー可観測ダッシュボードと Worker プール統治**(ステージ別プール + モデル別並行度ガバナー + 失敗タスクの調査/再試行);**マルチインスタンスストレージバックエンド**(ワークスペースごとに複数のストレージインスタンス、KB 単位のバインド、デフォルトインスタンス);**セッションスコープの一時添付**(画像/ドキュメントの非同期解析 + 合算上限);推奨質問とフォローアップ;安定リソースレジストリと LLM コンテキストのエイリアス圧縮;`@Skill / @MCP` メンションによるスコープ化 Agent ランタイム;会話中の MCP OAuth;QQBot と Lark(Feishu 国際版)IM 連携;Redis TLS;Requesty モデルプロバイダー + Keenable Web 検索;テナントレスプロビジョニングと制御されたセルフサービスワークスペース;管理者パスワードリセット;ナレッジベース複製フロー;`weknora` CLI v0.10。加えて大規模なセキュリティ強化(SSRF、シークレットのマスキング、SQL 検証、IDOR)。詳細は [`CHANGELOG.md`](./CHANGELOG.md)。
|
||||
- **v0.6.3** — ウェブサイト埋め込み Widget と統合センター(セキュアモード Token 交換 + レート制限);チャット体験の全面刷新(引用ポップオーバー、RAG パイプライン進捗、ストリーミング Markdown);ドキュメント複数タグと一括 reparse;Wiki フォルダーと階層ナビゲーション;RSS データソース;MCP OAuth2;EPUB / MHTML 解析;Agent モデル準備状態チェック;モデルデバッガー;セッションソースフィルター;ワークスペース削除 UI。詳細は [`CHANGELOG.md`](./CHANGELOG.md)。
|
||||
- **v0.6.2** — アップロード単位の解析設定(`process_config`)+ アップロード確認ダイアログ;reparse 時の設定上書き;`weknora` CLI v0.9(同梱 Agent Skills、`session stop`、auth/profile 統合);KB マーキー複数選択;pgvector 1024 次元 HNSW インデックス;チャットリソース Store 刷新;Langfuse のみのトレーシング(Jaeger 削除)。詳細は [`CHANGELOG.md`](./CHANGELOG.md)。
|
||||
- **v0.6.1** — ドキュメント解析トレースタイムライン(Langfuse 風の Span ツリー、ステージごとの進捗表示 + 解析中止);OpenSearch ベクター DB ドライバー;YAML 宣言型ビルトインモデル設定;システム管理者と統合プラットフォーム設定 + 監査ログ;新規ユーザーオンボーディングガイド;設定 UI 刷新;`weknora` CLI v0.7 / v0.8(Agent ファースト ワイヤープロトコル、NDJSON、`--dry-run`);OpenDataLoader と PaddleOCR-VL 解析エンジン;MCP サーバーのマルチトランスポート(stdio / SSE / HTTP);モデル単位の思考モード設定;Tencent LKEAP リランク + ネイティブ Gemini Embedding + MiniMax-M3。詳細は [`CHANGELOG.md`](./CHANGELOG.md) を参照。
|
||||
@@ -108,11 +110,12 @@ Feishu、Notion、Yuqueなどの外部プラットフォームからのナレッ
|
||||
| インテリジェント推論 | ReACT プログレッシブ・マルチステップ推論、ナレッジ検索・MCP ツール・Web 検索を自律的にオーケストレーション |
|
||||
| クイック Q&A | ナレッジベースベースの RAG Q&A、迅速かつ正確な回答 |
|
||||
| Wiki モード | Agent主導で生のドキュメントから構造化された相互リンク済みMarkdown Wikiページを自動生成・保守 |
|
||||
| ツール呼び出し | 組み込みツール、MCP ツール(OAuth2 リモートサービス含む)、Web 検索 |
|
||||
| 対話戦略 | オンライン Prompt 編集、検索閾値チューニング、マルチターン文脈認識 |
|
||||
| 推奨質問 | ナレッジベースの内容に基づく質問の自動生成 |
|
||||
| 引用と RAG 進捗 | インライン引用ポップオーバー、統一 Markdown レンダリング、RAG パイプラインの段階別進捗表示 |
|
||||
| セッション管理 | サイドバーでソース別(Web / IM / 埋め込み)にセッションをフィルター・グループ化 |
|
||||
| ツール呼び出し | 組み込みツール、MCP ツール(OAuth2 リモートサービス・会話中 OAuth 含む)、Web 検索;`@Skill / @MCP` メンションでターン単位に Agent ランタイムを範囲化 |
|
||||
| 対話戦略 | オンライン Prompt 編集、検索閾値チューニング、マルチターン文脈認識、Agent 単位の引用出力トグル |
|
||||
| 推奨質問 | ナレッジベースの内容に基づく質問の自動生成と回答後のフォローアップ |
|
||||
| 一時添付 | セッションスコープで画像 / ドキュメントをアップロードし、非同期解析して一回限りの Q&A に使用(画像 + 添付の合算上限) |
|
||||
| 引用と RAG 進捗 | インライン引用ポップオーバーと引用ドロワー(Web / KB ソースの区別)、統一 Markdown レンダリング、RAG パイプラインの段階別進捗表示 |
|
||||
| セッション管理 | サイドバーでソース別(Web / IM / 埋め込み)にセッションをフィルター・グループ化、セッションタイトルのインラインリネーム対応 |
|
||||
|
||||
**ナレッジ管理**
|
||||
|
||||
@@ -131,13 +134,14 @@ Feishu、Notion、Yuqueなどの外部プラットフォームからのナレッ
|
||||
|
||||
| 機能 | 詳細 |
|
||||
|------|------|
|
||||
| 大規模モデル | OpenAI / Azure OpenAI / Anthropic (Claude) / DeepSeek / Qwen (Alibaba Cloud) / Zhipu / Hunyuan / Doubao (Volcengine) / Gemini / MiniMax / NVIDIA / Novita AI / SiliconFlow / OpenRouter / Ollama |
|
||||
| 大規模モデル | OpenAI / Azure OpenAI / Anthropic (Claude) / DeepSeek / Qwen (Alibaba Cloud) / Zhipu / Hunyuan / Doubao (Volcengine) / Gemini / MiniMax / NVIDIA / Novita AI / SiliconFlow / OpenRouter / Requesty / Ollama |
|
||||
| Embedding | Ollama / BGE / GTE / OpenAI 互換 API |
|
||||
| ベクトル DB | PostgreSQL (pgvector) / Elasticsearch / OpenSearch / Milvus / Weaviate / Qdrant / Apache Doris / Tencent VectorDB |
|
||||
| オブジェクトストレージ | ローカル / MinIO / AWS S3 / 火山引擎 TOS / Alibaba Cloud OSS / 金山雲 KS3 |
|
||||
| IM 統合 | WeChat Work / Feishu / Slack / Telegram / DingTalk / Mattermost / WeChat |
|
||||
| オブジェクトストレージ | ローカル / MinIO / AWS S3 / 火山引擎 TOS / Alibaba Cloud OSS / 金山雲 KS3 / 華為雲 OBS;**ワークスペースごとに複数のストレージインスタンス**、KB 単位のバインドとデフォルトインスタンス |
|
||||
| IM 統合 | WeChat Work / Feishu / Lark(Feishu 国際版)/ QQBot / Slack / Telegram / DingTalk / Mattermost / WeChat / Yunzhijia |
|
||||
| ウェブ埋め込み | 埋め込み Widget でエージェントを公開、ドメイン許可リスト・レート制限・セキュアモード Token 交換 |
|
||||
| Web 検索 | DuckDuckGo / Bing / Google / Tavily / Baidu / Ollama / SearXNG |
|
||||
| Web 検索 | DuckDuckGo / Bing / Google / Tavily / Baidu / Ollama / SearXNG / Keenable / Zhipu AI |
|
||||
| API 連携 | スコープ付き API キー(能力単位の付与 + KB 単位の制限 + 節流付き last_used 追跡)と API 連携プレイグラウンド;MCP OAuth と埋め込みセッションを Principal 単位で分離 |
|
||||
|
||||
**プラットフォーム**
|
||||
|
||||
@@ -145,8 +149,8 @@ Feishu、Notion、Yuqueなどの外部プラットフォームからのナレッ
|
||||
|------|------|
|
||||
| デプロイ | ローカル / Docker / Kubernetes (Helm)、プライベート化・オフラインデプロイ対応 |
|
||||
| UI | Web UI / RESTful API / CLI (`weknora`) / Chrome Extension / ウェブ埋め込み Widget / WeChat ミニプログラム |
|
||||
| 可観測性 | Langfuse(唯一のトレーシングバックエンド)で ReAct ループ・トークン消費・ツール呼び出し・パイプライン追跡;Langfuse 風のドキュメント解析トレースタイムラインを内蔵し、ステージごとの進捗を表示 |
|
||||
| タスク管理 | MQ 非同期タスク、バージョンアップ時の DB 自動マイグレーション |
|
||||
| 可観測性 | Langfuse(唯一のトレーシングバックエンド)で ReAct ループ・トークン消費・ツール呼び出し・パイプライン追跡;Langfuse 風のドキュメント解析トレースタイムラインを内蔵し、ステージごとの進捗を表示;システム管理者向けランタイムタスクキューダッシュボード(キュー深度・モデル別並行度・失敗タスクの調査と手動再試行) |
|
||||
| タスク管理 | MQ 非同期タスク、ステージ別 Worker プール統治(core / 後処理 / enrichment / maintenance + 弾性共有プール、Wiki は独立プール)とモデル別バックグラウンド並行度ガバナー;バージョンアップ時の DB 自動マイグレーション |
|
||||
| モデル管理 | 集中設定、YAML 宣言型ビルトインモデル設定、ナレッジベース単位のモデル選択、モデル単位の思考モード・Embedding 次元上書き、インタラクティブモデルデバッガー、マルチテナント組み込みモデル共有、WeKnora Cloud ホスティングモデルとドキュメント解析 |
|
||||
|
||||
## 🧩 Chrome 拡張機能
|
||||
|
||||
+17
-13
@@ -28,7 +28,7 @@
|
||||
<img src="https://img.shields.io/badge/License-MIT-ffffff?labelColor=d4eaf7&color=2e6cc4" alt="License">
|
||||
</a>
|
||||
<a href="./CHANGELOG.md">
|
||||
<img alt="버전" src="https://img.shields.io/badge/version-0.6.3-2e6cc4?labelColor=d4eaf7">
|
||||
<img alt="버전" src="https://img.shields.io/badge/version-0.7.1-2e6cc4?labelColor=d4eaf7">
|
||||
</a>
|
||||
</p>
|
||||
|
||||
@@ -50,12 +50,14 @@
|
||||
|
||||
[**WeKnora**](https://weknora.weixin.qq.com)는 엔터프라이즈급 문서 이해, 시맨틱 검색, 자율 추론 시나리오를 위해 설계된 오픈소스 LLM 기반 지식 프레임워크입니다.
|
||||
|
||||
본 프레임워크는 **세 가지 핵심 역량**을 중심으로 구성됩니다. 일상 검색에 최적화된 **RAG 기반 빠른 Q&A**, 지식 검색·MCP 도구·웹 검색을 자율적으로 오케스트레이션하여 복잡한 다단계 작업을 처리하는 **ReAct Agent 추론**, 그리고 Agent가 원본 문서에서 상호 연결된 마크다운 지식베이스와 인터랙티브 지식 그래프를 스스로 생성·유지하는 완전히 새로운 **Wiki 모드**입니다. 다양한 데이터 소스 연동(Feishu / Notion / Yuque / RSS, 지속 확장 중), **웹사이트 임베드 Widget**으로 외부 사이트에 에이전트 게시, 20개 이상의 LLM 프로바이더 통합, Langfuse 기반 풀스택 관측 가능성, **엔터프라이즈 멀티 테넌트 RBAC(4단계 역할 매트릭스 + 리소스 소유권 + 테넌트 감사 로그)**, 완전 셀프호스팅이 가능한 모듈형 아키텍처를 결합하여, WeKnora는 흩어진 문서를 검색·추론 가능하며 지속적으로 진화하는 전용 지식 자산으로 탈바꿈시킵니다.
|
||||
본 프레임워크는 **세 가지 핵심 역량**을 중심으로 구성됩니다. 일상 검색에 최적화된 **RAG 기반 빠른 Q&A**, 지식 검색·MCP 도구·웹 검색을 자율적으로 오케스트레이션하여 복잡한 다단계 작업을 처리하는 **ReAct Agent 추론**, 그리고 Agent가 원본 문서에서 상호 연결된 마크다운 지식베이스와 인터랙티브 지식 그래프를 스스로 생성·유지하는 완전히 새로운 **Wiki 모드**입니다. 다양한 데이터 소스 연동(Feishu / Notion / Yuque / RSS, 지속 확장 중), **웹사이트 임베드 Widget**으로 외부 사이트에 에이전트 게시, 프로그램 연동을 위한 **범위 지정 API 키 및 Principal 모델**, 워크스페이스별 **다중 인스턴스 스토리지 백엔드**, 20개 이상의 LLM 프로바이더 통합, Langfuse 기반 풀스택 관측 가능성과 **런타임 작업 큐 대시보드 + Worker 풀 거버넌스**, **엔터프라이즈 멀티 테넌트 RBAC(4단계 역할 매트릭스 + 리소스 소유권 + 테넌트 감사 로그)**, 완전 셀프호스팅이 가능한 모듈형 아키텍처를 결합하여, WeKnora는 흩어진 문서를 검색·추론 가능하며 지속적으로 진화하는 전용 지식 자산으로 탈바꿈시킵니다.
|
||||
|
||||
Feishu, Notion, Yuque 등 외부 플랫폼에서 지식 자동 동기화를 지원하며(추가 데이터 소스 개발 중), PDF, Word, 이미지, Excel 등 10가지 이상의 문서 포맷을 처리합니다. WeChat Work, Feishu, Slack, Telegram 등의 IM 채널을 통해 Q&A 서비스를 직접 제공할 수 있습니다. 모델 레이어에서 OpenAI, DeepSeek, Qwen(Alibaba Cloud), Zhipu, Hunyuan, Gemini, MiniMax, NVIDIA, Ollama 등 주요 프로바이더를 지원합니다. 전체 프로세스가 모듈화 설계되어 LLM, 벡터 DB, 스토리지 등 구성 요소를 유연하게 교체 가능하며, 로컬 및 프라이빗 클라우드 배포를 지원하여 데이터 완전 자체 관리가 가능합니다. 또한 WeKnora는 **Langfuse**와 원활하게 통합되어 Agent 추론, 토큰 사용량 및 파이프라인에 대한 포괄적인 관측 가능성(Observability)을 제공합니다.
|
||||
|
||||
## ✨ 최신 업데이트
|
||||
|
||||
- **v0.7.1** — 새로운 **Yunzhijia(云之家) IM 통합**(WebSocket + 이미지 메시지 + Markdown 응답); **Volcengine Rerank** 제공자(요청 자동 분할)와 **Zhipu AI 웹 검색** 제공자; 컨트롤 플레인 자동화를 위한 **플랫폼 범위 API 키**(테넌트 관리, 시스템 설정, 런타임 큐, 감사 로그); **KB 단위 활동 감사 추적**; FAQ 관리 강화(필터링, 태깅, 내보내기, 가져오기 결과 추적); **Langfuse OTLP/OTel 트레이싱** 마이그레이션 및 W3C traceparent 전파; 채팅 헤더 액션을 통한 원클릭 **Markdown 내보내기** 및 참조 드로어의 Wiki 도구 결과 표시; 프롬프트 캐시 가시성; 세션 채널 거버넌스(IM/임베드/API 세션을 관리자 범위로 분리); Feishu 대규모 Wiki 동기화 견고화; 레거시 Neo4j 대화 메모리 의존성 제거. 또한 광범위한 slug 무결성, SSRF 전송, 상태 동기화 강화. 자세한 내용은 [`CHANGELOG.md`](./CHANGELOG.md).
|
||||
- **v0.7.0** — 세분화된 **범위 지정 API 키 및 Principal 모델**(능력 단위 권한 + KB 단위 제한 + API 통합 플레이그라운드); **런타임 작업 큐 가시성 대시보드 및 Worker 풀 거버넌스**(단계별 풀 + 모델별 동시성 거버너 + 실패 작업 조사/재시도); **다중 인스턴스 스토리지 백엔드**(워크스페이스당 여러 스토리지 인스턴스, KB 단위 바인딩, 기본 인스턴스); **세션 범위 임시 첨부**(이미지/문서 비동기 파싱 + 통합 한도); 추천 질문 및 후속 질문; 안정적인 리소스 레지스트리 및 LLM 컨텍스트 별칭 압축; `@Skill / @MCP` 멘션 기반 범위 지정 Agent 런타임; 대화 중 MCP OAuth; QQBot 및 Lark(Feishu 국제판) IM 통합; Redis TLS; Requesty 모델 제공자 + Keenable 웹 검색; 테넌트리스 프로비저닝 및 제어된 셀프서비스 워크스페이스; 관리자 비밀번호 재설정; 지식 베이스 복제 플로우; `weknora` CLI v0.10. 또한 대규모 보안 강화(SSRF, 비밀 마스킹, SQL 검증, IDOR). 자세한 내용은 [`CHANGELOG.md`](./CHANGELOG.md).
|
||||
- **v0.6.3** — 웹사이트 임베드 Widget 및 통합 센터(보안 모드 Token 교환 + 속도 제한); 채팅 경험 전면 개편(인용 팝오버, RAG 파이프라인 진행, 스트리밍 Markdown); 문서 다중 태그 및 일괄 reparse; Wiki 폴더 및 계층 탐색; RSS 데이터 소스; MCP OAuth2; EPUB / MHTML 파싱; Agent 모델 준비 상태 검사; 모델 디버거; 세션 소스 필터; 워크스페이스 삭제 UI. 자세한 내용은 [`CHANGELOG.md`](./CHANGELOG.md).
|
||||
- **v0.6.2** — 업로드 단위 파싱 설정(`process_config`) + 업로드 확인 대화상자; reparse 시 설정 덮어쓰기; `weknora` CLI v0.9(번들 Agent Skills, `session stop`, auth/profile 통합); KB 마키 선택 다중 선택; pgvector 1024차원 HNSW 인덱스; 채팅 리소스 Store 리팩터; Langfuse 단일 추적(Jaeger 제거). 자세한 내용은 [`CHANGELOG.md`](./CHANGELOG.md).
|
||||
- **v0.6.1** — 문서 파싱 추적 타임라인(Langfuse 스타일 Span 트리, 단계별 진행 표시 + 파싱 중단); OpenSearch 벡터 저장소 드라이버; YAML 선언형 내장 모델 구성; 시스템 관리자와 통합 플랫폼 설정 + 감사 로그; 신규 사용자 온보딩 가이드; 설정 UI 리디자인; `weknora` CLI v0.7 / v0.8(Agent 우선 와이어 프로토콜, NDJSON, `--dry-run`); OpenDataLoader 및 PaddleOCR-VL 파싱 엔진; MCP 서버 멀티 트랜스포트(stdio / SSE / HTTP); 모델별 사고 모드 설정; Tencent LKEAP 리랭크 + 네이티브 Gemini 임베딩 + MiniMax-M3. 자세한 내용은 [`CHANGELOG.md`](./CHANGELOG.md) 참고.
|
||||
@@ -117,11 +119,12 @@ Feishu, Notion, Yuque 등 외부 플랫폼에서 지식 자동 동기화를 지
|
||||
| 지능형 추론 | ReACT 점진적 멀티스텝 추론, 지식 검색·MCP 도구·웹 검색을 자율 오케스트레이션 |
|
||||
| 빠른 Q&A | 지식베이스 기반 RAG Q&A, 빠르고 정확한 답변 |
|
||||
| Wiki 모드 | Agent가 주도하여 원본 문서에서 구조화된 마크다운 Wiki 페이지를 자동 생성 및 유지 관리 |
|
||||
| 도구 호출 | 내장 도구, MCP 도구(OAuth2 원격 서비스 포함), 웹 검색 |
|
||||
| 대화 전략 | 온라인 프롬프트 편집, 검색 임계값 조정, 멀티턴 문맥 인식 |
|
||||
| 추천 질문 | 지식베이스 콘텐츠 기반 질문 자동 생성 |
|
||||
| 인용 및 RAG 진행 | 인라인 인용 팝오버, 통합 Markdown 렌더링, RAG 파이프라인 단계별 진행 표시 |
|
||||
| 세션 관리 | 사이드바에서 소스별(Web / IM / 임베드) 세션 필터 및 그룹화 |
|
||||
| 도구 호출 | 내장 도구, MCP 도구(OAuth2 원격 서비스·대화 중 OAuth 포함), 웹 검색; `@Skill / @MCP` 멘션으로 턴 단위 Agent 런타임 범위 지정 |
|
||||
| 대화 전략 | 온라인 프롬프트 편집, 검색 임계값 조정, 멀티턴 문맥 인식, Agent별 인용 출력 토글 |
|
||||
| 추천 질문 | 지식베이스 콘텐츠 기반 질문 자동 생성 및 답변 후 후속 질문 |
|
||||
| 임시 첨부 | 세션 범위로 이미지 / 문서를 업로드하고 비동기 파싱하여 일회성 Q&A에 사용(이미지 + 첨부 통합 한도) |
|
||||
| 인용 및 RAG 진행 | 인라인 인용 팝오버 및 인용 드로어(웹 / KB 소스 구분), 통합 Markdown 렌더링, RAG 파이프라인 단계별 진행 표시 |
|
||||
| 세션 관리 | 사이드바에서 소스별(Web / IM / 임베드) 세션 필터 및 그룹화, 세션 제목 인라인 이름 변경 지원 |
|
||||
|
||||
**지식 관리**
|
||||
|
||||
@@ -140,13 +143,14 @@ Feishu, Notion, Yuque 등 외부 플랫폼에서 지식 자동 동기화를 지
|
||||
|
||||
| 기능 | 상세 |
|
||||
|------|------|
|
||||
| LLM | OpenAI / Azure OpenAI / Anthropic (Claude) / DeepSeek / Qwen (Alibaba Cloud) / Zhipu / Hunyuan / Doubao (Volcengine) / Gemini / MiniMax / NVIDIA / Novita AI / SiliconFlow / OpenRouter / Ollama |
|
||||
| LLM | OpenAI / Azure OpenAI / Anthropic (Claude) / DeepSeek / Qwen (Alibaba Cloud) / Zhipu / Hunyuan / Doubao (Volcengine) / Gemini / MiniMax / NVIDIA / Novita AI / SiliconFlow / OpenRouter / Requesty / Ollama |
|
||||
| Embedding | Ollama / BGE / GTE / OpenAI 호환 API |
|
||||
| 벡터 DB | PostgreSQL (pgvector) / Elasticsearch / OpenSearch / Milvus / Weaviate / Qdrant / Apache Doris / Tencent VectorDB |
|
||||
| 오브젝트 스토리지 | 로컬 / MinIO / AWS S3 / Volcengine TOS / Alibaba Cloud OSS / Kingsoft Cloud KS3 |
|
||||
| IM 통합 | WeChat Work / Feishu / Slack / Telegram / DingTalk / Mattermost / WeChat |
|
||||
| 오브젝트 스토리지 | 로컬 / MinIO / AWS S3 / Volcengine TOS / Alibaba Cloud OSS / Kingsoft Cloud KS3 / Huawei Cloud OBS; **워크스페이스당 여러 스토리지 인스턴스**, KB 단위 바인딩 및 기본 인스턴스 |
|
||||
| IM 통합 | WeChat Work / Feishu / Lark(Feishu 국제판) / QQBot / Slack / Telegram / DingTalk / Mattermost / WeChat / Yunzhijia |
|
||||
| 웹사이트 임베드 | 임베드 Widget으로 에이전트 게시, 도메인 허용 목록·속도 제한·보안 모드 Token 교환 |
|
||||
| 웹 검색 | DuckDuckGo / Bing / Google / Tavily / Baidu / Ollama / SearXNG |
|
||||
| 웹 검색 | DuckDuckGo / Bing / Google / Tavily / Baidu / Ollama / SearXNG / Keenable / Zhipu AI |
|
||||
| API 통합 | 범위 지정 API 키(능력 단위 권한 + KB 단위 제한 + 스로틀링된 last_used 추적)와 API 통합 플레이그라운드; MCP OAuth 및 임베드 세션을 Principal 단위로 격리 |
|
||||
|
||||
**플랫폼**
|
||||
|
||||
@@ -154,8 +158,8 @@ Feishu, Notion, Yuque 등 외부 플랫폼에서 지식 자동 동기화를 지
|
||||
|------|------|
|
||||
| 배포 | 로컬 / Docker / Kubernetes (Helm), 프라이빗/오프라인 배포 지원 |
|
||||
| UI | Web UI / RESTful API / CLI (`weknora`) / Chrome Extension / 웹사이트 임베드 Widget / WeChat 미니 프로그램 |
|
||||
| 관측 가능성 | Langfuse(단일 추적 백엔드)로 ReAct 루프·토큰 소비·도구 호출·파이프라인 추적; Langfuse 스타일의 문서 파싱 추적 타임라인 내장으로 단계별 진행 표시 |
|
||||
| 작업 관리 | MQ 비동기 작업, 버전 업그레이드 시 자동 DB 마이그레이션 |
|
||||
| 관측 가능성 | Langfuse(단일 추적 백엔드)로 ReAct 루프·토큰 소비·도구 호출·파이프라인 추적; Langfuse 스타일의 문서 파싱 추적 타임라인 내장으로 단계별 진행 표시; 시스템 관리자용 런타임 작업 큐 대시보드(큐 깊이·모델별 동시성·실패 작업 조사 및 수동 재시도) |
|
||||
| 작업 관리 | MQ 비동기 작업, 단계별 Worker 풀 거버넌스(core / 후처리 / enrichment / maintenance + 탄력적 공유 풀, Wiki 독립 풀)와 모델별 백그라운드 동시성 거버너; 버전 업그레이드 시 자동 DB 마이그레이션 |
|
||||
| 모델 관리 | 중앙 설정, YAML 선언형 내장 모델 구성, 지식베이스별 모델 선택, 모델별 사고 모드·Embedding 차원 덮어쓰기, 대화형 모델 디버거, 멀티테넌트 내장 모델 공유, WeKnora Cloud 호스팅 모델 및 문서 파싱 |
|
||||
|
||||
## 🧩 Chrome 확장 프로그램
|
||||
|
||||
+7
-3
@@ -56,7 +56,7 @@ Errors emit an error envelope on stderr (`--format json`) or prose
|
||||
"type": "auth.unauthenticated",
|
||||
"message": "fetch current user: HTTP error 401",
|
||||
"hint": "run `weknora auth login`",
|
||||
"retry_command": "weknora auth login",
|
||||
"retry_command": "weknora auth login --host https://kb.example.com",
|
||||
"retry_after_seconds": 0,
|
||||
"risk": {"level": "destructive", "action": "noun.verb"},
|
||||
"detail": {}
|
||||
@@ -413,6 +413,10 @@ Agents parse the first colon to extract the typed code. The exit code class (see
|
||||
| `local.unimplemented` | 1 | no | (planned in a future release) |
|
||||
| `local.upload_file_not_found` | 1 | no | verify the path is correct and readable |
|
||||
| `local.user_aborted` | 1 | no (user said no) | no action taken; pass `-y/--yes` to skip the confirmation prompt |
|
||||
| `internal.error` | 1 | no | catch-all for an untyped error that reached the top (a bug or unmapped dependency error); a recurring one is a classification gap worth reporting |
|
||||
| `mcp.readonly_mode` | 1 | no | MCP tool surface is read-only; mutations not exposed in this mode |
|
||||
| `mcp.schema_unknown_command` | 1 | no | (no canonical hint) |
|
||||
| `mcp.tool_not_allowed` | 1 | no | MCP tool not in the curated allowlist |
|
||||
|
||||
<!-- ERROR_REFERENCE_END -->
|
||||
|
||||
@@ -535,7 +539,7 @@ The three surfaces do not auto-sync: each is wired separately so agents that onl
|
||||
|
||||
## MCP Tool Surface
|
||||
|
||||
WeKnora's MCP server exposes a curated 10-tool surface where most tools are read-only but `chat` and `session_ask` create conversation/message records. Many MCP servers in the wild ship write / mutation operations on by default and rely on credential-scope or sandbox restrictions for safety. WeKnora opts for curation instead: the server side doesn't yet enforce per-token scope, so an agent holding a user's token has full write access. Until server-side scope ships, the CLI keeps mutation tools out of the MCP surface as a belt-and-braces second line of defense. When server scope arrives this stance can loosen.
|
||||
WeKnora's MCP server exposes a curated read-only tool surface. Many MCP servers in the wild ship write / mutation operations on by default and rely on credential-scope or sandbox restrictions for safety. WeKnora opts for curation instead: the server side doesn't yet enforce per-token scope, so an agent holding a user's token has full write access. Until server-side scope ships, the CLI keeps mutation tools out of the MCP surface as a belt-and-braces second line of defense. When server scope arrives this stance can loosen.
|
||||
|
||||
The curated 10 tools (`cli/internal/mcp/tools.go`):
|
||||
|
||||
@@ -550,7 +554,7 @@ The curated 10 tools (`cli/internal/mcp/tools.go`):
|
||||
| `search_chunks` | hybrid (vector + keyword) retrieval |
|
||||
| `chat` | stream a RAG answer; auto-creates a session if absent |
|
||||
| `agent_list` | list custom agents |
|
||||
| `session_ask` | run a query through a custom agent (`session ask --agent`) |
|
||||
| `agent_invoke` | run a query through a custom agent |
|
||||
|
||||
Adding a tool is a deliberate API expansion — the AI-agent-callable surface is the reason this CLI ships an MCP server, not its CLI command list, so the registration list in `registerTools` is maintained by hand.
|
||||
|
||||
|
||||
@@ -10,6 +10,61 @@ of the WeKnora server / frontend release cadence.
|
||||
CLI history before v0.3 is recorded in the project root
|
||||
[CHANGELOG.md](../CHANGELOG.md) under the release that introduced the CLI.
|
||||
|
||||
## [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.
|
||||
- `session continue-stream` renamed to `session resume`.
|
||||
- `kb init` renamed to `kb config set`.
|
||||
- Error envelope: `retry_command` (a shell string) replaced by `retry_argv`
|
||||
(a directly-executable argv array — no shell-splitting or quoting).
|
||||
|
||||
### 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.
|
||||
- `error.exit_code` embeds the process exit code in the JSON error envelope,
|
||||
disambiguating the two `input.invalid_argument` cases (parse error → 2,
|
||||
typed-value error → 5).
|
||||
- `kb status` / `kb check` / `kb create` report `retrieval_ready` (whether an
|
||||
embedding model is bound); `kb create` hints the fix when it is false.
|
||||
- `model create` / `model update` / `model delete` (`update` rotates key /
|
||||
base-url in place, preserving the id).
|
||||
- Stateless env-credential auth: `WEKNORA_API_KEY` / `WEKNORA_TOKEN` +
|
||||
`WEKNORA_HOST`, a zero-disk path for headless / agent use. `auth logout` now
|
||||
keeps the profile registered (use `profile remove` to delete it entirely).
|
||||
- `meta.total_count` on paginated list / search output (full result size before
|
||||
client-side `--limit` truncation).
|
||||
|
||||
### 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
|
||||
up to 4 MiB are accepted.
|
||||
- Terminal `response_type=error, done=true` frames now end SDK stream calls
|
||||
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 `knowledge_base_id`, `parent_chunk_id`, and `sub_chunk_id` fields
|
||||
now survive SDK unmarshal.
|
||||
- E2E chat step parses the bounded JSON envelope; MCP stream errors include
|
||||
`session_id` in `error.detail`; terminal SSE errors classify as
|
||||
`server.error` instead of `network.error` or `local.sse_stream_aborted`.
|
||||
|
||||
## [0.9.0] - 2026-06-10
|
||||
|
||||
### v0.9 — auth/profile model harmonization + flag cleanup
|
||||
|
||||
+85
-31
@@ -17,15 +17,21 @@ Available Commands:
|
||||
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
|
||||
profile Manage CLI profiles (named connection targets)
|
||||
config Inspect the CLI's resolved configuration
|
||||
doc Manage documents in a knowledge base
|
||||
doctor Run 4 self-checks: base URL, auth, server version, credential storage
|
||||
exit-codes Exit code matrix and the agent action for each
|
||||
help Help about any command
|
||||
kb Manage knowledge bases
|
||||
link Bind the current directory to a knowledge base
|
||||
mcp Run weknora as a Model Context Protocol server
|
||||
message Inspect and manage messages inside chat sessions
|
||||
model Manage models (list / view / create / update / delete)
|
||||
profile Manage CLI profiles (named connection targets)
|
||||
schema Machine-readable contract for a command (or the whole surface)
|
||||
search Search across chunks, knowledge bases, documents, or sessions
|
||||
session Manage chat sessions
|
||||
skills List and install the bundled Agent Skills
|
||||
unlink Remove the directory's knowledge-base binding
|
||||
version Show CLI build metadata
|
||||
```
|
||||
@@ -50,8 +56,9 @@ sudo mv weknora /usr/local/bin/ # or anywhere on $PATH
|
||||
|
||||
### Pre-built binaries
|
||||
|
||||
Pre-built binaries for Linux / macOS / Windows are produced by CI on each
|
||||
release. Grab the latest from the [Releases page](https://github.com/Tencent/WeKnora/releases).
|
||||
Building from source is the supported install method today. Pre-built binaries,
|
||||
`go install`, and a Homebrew formula are planned to accompany a tagged release;
|
||||
until then, use the from-source build above.
|
||||
|
||||
---
|
||||
|
||||
@@ -76,6 +83,7 @@ weknora link --kb my-knowledge-base
|
||||
# 5. Upload a document, then block until parsing finishes
|
||||
weknora doc upload notes.md
|
||||
weknora doc wait doc_abc # exit 0 completed, 1 failed, 124 --timeout, 130 ^C
|
||||
weknora doc reparse doc_abc # re-trigger parsing if it failed, then wait again
|
||||
|
||||
# 6. Search
|
||||
weknora search chunks "what is reciprocal rank fusion?"
|
||||
@@ -84,13 +92,22 @@ weknora search chunks "what is reciprocal rank fusion?"
|
||||
weknora chat "summarise the design doc"
|
||||
|
||||
# 8. Manage custom agents and run them (see `weknora agent --help` / `weknora session --help`)
|
||||
weknora model list # discover a model id for --model
|
||||
weknora agent list
|
||||
weknora session ask --agent ag_abc "what's our q4 retention plan?"
|
||||
|
||||
# 9. Inspect a document's chunks for RAG retrieval debug
|
||||
weknora chunk list --doc doc_xyz
|
||||
|
||||
# 10. Health & verification verbs
|
||||
# 10. Inspect messages in a session / search across sessions
|
||||
weknora message list --session sess_abc
|
||||
weknora message search "retry policy" # cross-session Q&A retrieval
|
||||
|
||||
# 11. Resolve a pending tool approval (agent run blocked on approval event)
|
||||
weknora session tool-approval resolve pend_xxx -y # approve (after user go-ahead)
|
||||
weknora session resume sess_abc --message msg_xyz # resume the blocked stream
|
||||
|
||||
# 12. Health & verification verbs
|
||||
weknora kb status kb_abc # fast snapshot: reachable / counts / processing flag (1 HTTP)
|
||||
weknora kb check kb_abc # deep verify: also aggregates failed_count via doc list (1+N HTTP)
|
||||
weknora agent status ag_abc # fast: reachable / model_id
|
||||
@@ -101,10 +118,17 @@ weknora agent check ag_abc # deep: probes every KB in the agent's scope
|
||||
|
||||
### Agent quick start
|
||||
|
||||
For AI agents (Claude Code, Cursor, Gemini CLI, etc.) integrating WeKnora:
|
||||
For AI agents (any MCP-capable host) integrating WeKnora:
|
||||
|
||||
1. Install: `brew install weknora` or `go install github.com/Tencent/WeKnora/cli@latest`
|
||||
2. Register a profile, then authenticate it (background; extract login URL for the user):
|
||||
1. Install: build from source (see [Install](#install))
|
||||
2. Authenticate. In a sandbox / CI, the **stateless** path needs no `auth login`
|
||||
and writes nothing to disk — just set two env vars:
|
||||
```bash
|
||||
export WEKNORA_API_KEY="sk-…" # or WEKNORA_TOKEN for a bearer JWT
|
||||
export WEKNORA_HOST="https://kb.example.com"
|
||||
weknora kb list # already authenticated
|
||||
```
|
||||
Or, for a persisted local profile:
|
||||
```bash
|
||||
weknora profile add prod --host <server-url> --use
|
||||
weknora auth login
|
||||
@@ -127,17 +151,19 @@ under [`skills/`](skills/) that teach an agent to drive WeKnora without trial an
|
||||
- [`weknora-rag-search`](skills/weknora-rag-search/SKILL.md) — when to use `chat`
|
||||
vs `session ask` vs `search chunks`, plus retrieval gotchas.
|
||||
|
||||
MVP install: symlink them into your agent's skills directory (from a source checkout):
|
||||
Install them with the CLI (the skills are embedded in the binary, no checkout
|
||||
needed):
|
||||
|
||||
```bash
|
||||
ln -s "$PWD/skills/weknora-shared" ~/.claude/skills/weknora-shared
|
||||
ln -s "$PWD/skills/weknora-rag-search" ~/.claude/skills/weknora-rag-search
|
||||
weknora skills install # writes to ~/.claude/skills
|
||||
weknora skills install --dir <agent-skills-dir> --force # other agents / overwrite
|
||||
weknora skills list --format json # what would be installed
|
||||
```
|
||||
|
||||
Each skill's frontmatter records the CLI version it was `tested_against`; a CI
|
||||
parity test (`internal/skillparity`) fails if a skill ever references a command,
|
||||
flag, or MCP tool the CLI no longer has. (A `weknora skills install` command is
|
||||
planned; for now, symlink or copy.)
|
||||
Existing files are left untouched without `--force`; `--dry-run` previews the
|
||||
file list. Each skill's frontmatter records the CLI version it was
|
||||
`tested_against`; a CI parity test (`internal/skillparity`) fails if a skill
|
||||
ever references a command, flag, or MCP tool the CLI no longer has.
|
||||
|
||||
---
|
||||
|
||||
@@ -177,7 +203,9 @@ weknora auth logout --all
|
||||
|
||||
Designed to be AI-agent-first. Stable across minor releases; breaking
|
||||
changes announced in the changelog and the corresponding
|
||||
`weknora --version` bump.
|
||||
`weknora --version` bump. This section is the human overview; the complete,
|
||||
authoritative contract (envelope field stability, error taxonomy, streaming,
|
||||
confirmation and dry-run protocols) lives in **[AGENTS.md](AGENTS.md)**.
|
||||
|
||||
### Streams
|
||||
|
||||
@@ -188,15 +216,17 @@ changes announced in the changelog and the corresponding
|
||||
|
||||
### JSON output
|
||||
|
||||
Every command supports `--format json`, emitting bare JSON for the
|
||||
resource it produces — an array for `list` / `search`, a single object
|
||||
for `view` and write outcomes:
|
||||
Every command supports `--format json`, wrapping the resource in the
|
||||
symmetric envelope `{ok, data, meta?}` — `data` is an array for `list` /
|
||||
`search`, a single object for `view` and write outcomes. `--jq` runs
|
||||
against the whole envelope, so reach into list items with `.data[]`:
|
||||
|
||||
```bash
|
||||
weknora kb list --format json # [{ "id": "kb_x", "name": "Eng" }, …]
|
||||
weknora kb view kb_x --format json # { "id": "kb_x", "name": "Eng", … }
|
||||
weknora kb list --format json --jq '.[] | {id, name}' # project to listed fields
|
||||
weknora kb list --format json --jq '.[].id' # jq over the bare data
|
||||
weknora kb list --format json # {"ok":true,"data":[{"id":"kb_x",…}],"meta":{"count":1,…}}
|
||||
weknora kb view kb_x --format json # {"ok":true,"data":{"id":"kb_x","name":"Eng",…}}
|
||||
weknora kb list --format json --jq '.data[] | {id, name}' # project listed fields out of each item
|
||||
weknora kb list --format json --jq '.data[].id' # ids only
|
||||
weknora kb list --format json --jq '.meta.count' # number returned
|
||||
```
|
||||
|
||||
`--format ndjson` is also accepted for streaming list commands; each
|
||||
@@ -221,10 +251,10 @@ auth.unauthenticated: fetch current user: HTTP error 401: ...
|
||||
hint: run `weknora auth login`
|
||||
```
|
||||
|
||||
The full code registry is in `cli/internal/cmdutil/errors.go`
|
||||
(`AllCodes()`). Code namespaces: `auth.*` / `resource.*` / `input.*` /
|
||||
`server.*` / `network.*` / `local.*` / `mcp.*` / `operation.*` (CLI-level
|
||||
wait/poll outcomes: `operation.timeout`, `operation.failed`, `operation.cancelled`).
|
||||
Under `--format json` the same failure is the typed error envelope on stderr
|
||||
(`{ok:false, error:{type, exit_code, hint?, retry_argv?, …}}`) — see
|
||||
[AGENTS.md §1.4](AGENTS.md) for the field-by-field contract and the full code
|
||||
taxonomy.
|
||||
|
||||
### Exit codes
|
||||
|
||||
@@ -240,7 +270,9 @@ wait/poll outcomes: `operation.timeout`, `operation.failed`, `operation.cancelle
|
||||
| `7` | `server.*` / `network.*` | transient — retry with backoff |
|
||||
| `10` | **`input.confirmation_required`** (high-risk write) | ask the human, retry with `-y` only after explicit approval |
|
||||
| `124` | `operation.timeout` (e.g. `doc wait --timeout` reached) | raise `--timeout` or check the underlying job |
|
||||
| `130` | `operation.cancelled` (SIGINT / SIGTERM) | stop, do not retry |
|
||||
| `130` | cancelled by signal — typed `operation.cancelled` errors exit 1; `main.go` promotes the process exit to 130 when the root context was signal-cancelled (SIGINT / SIGTERM) | stop, do not retry |
|
||||
|
||||
Run `weknora exit-codes` for the machine-readable matrix (JSON); `weknora help exit-codes` for the human-readable table.
|
||||
|
||||
**Exit 10** is the wire-level signal for "destructive write needs
|
||||
explicit confirmation". Pass `-y/--yes` on `kb delete` /
|
||||
@@ -252,12 +284,19 @@ 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
|
||||
stdio MCP for any MCP-compatible client.
|
||||
- `weknora schema` enumerates every command with its `used_for`, and
|
||||
`weknora schema <cmd path>` (e.g. `weknora schema doc update`) prints that
|
||||
command's full contract — `used_for`, `required_flags`, `examples`,
|
||||
`output`, `warnings`, `risk`, and local `flags` — as the standard envelope,
|
||||
so an agent can discover the surface without scraping `--help` prose.
|
||||
|
||||
---
|
||||
|
||||
@@ -329,7 +368,7 @@ weknora api /api/v1/knowledge-bases --dry-run
|
||||
|
||||
## Resuming streams
|
||||
|
||||
The `weknora session continue-stream` command resumes an SSE event stream for an existing assistant message. Useful for network-blip recovery or polling long-running agent invocations:
|
||||
The `weknora session resume` command resumes an SSE event stream for an existing assistant message. Useful for network-blip recovery or polling long-running agent invocations:
|
||||
|
||||
```bash
|
||||
# Original streaming call captures session_id + message_id from init event:
|
||||
@@ -339,11 +378,26 @@ weknora session ask "..." --agent ag_xxxx --format ndjson | tee /tmp/stream.ndjs
|
||||
# [network blip]
|
||||
|
||||
# Resume the same stream:
|
||||
weknora session continue-stream sess_abc --message msg_xyz
|
||||
weknora session resume sess_abc --message msg_xyz
|
||||
# Server REPLAYS all stored events from the start, then tails new ones.
|
||||
# Agent must dedupe (by message_id or event hash) to avoid double-processing.
|
||||
```
|
||||
|
||||
### Tool-approval unlock chain
|
||||
|
||||
An agent run may pause the stream on a tool-approval event until a human approves or rejects the pending tool call. The unlock sequence:
|
||||
|
||||
```bash
|
||||
# 1. Stream pauses with a tool-approval event carrying a pending_id.
|
||||
# 2. Surface the pending tool call to the user; get explicit go-ahead.
|
||||
weknora session tool-approval resolve pend_xxx -y # approve
|
||||
# weknora session tool-approval resolve pend_xxx --reject --reason "..." -y # reject
|
||||
# 3. Resume the stream — server replays + tails from where the run was blocked.
|
||||
weknora session resume sess_abc --message msg_xyz
|
||||
```
|
||||
|
||||
Pass `--modified-args '{"key":"value"}'` to replace tool arguments on approve (must be a non-empty JSON object). Never auto-pass `-y` — the approval is the exit-10 human-in-the-loop gate.
|
||||
|
||||
Server-side buffer TTL: 1 hour for redis mode; process lifetime for memory mode (default). After TTL, expect `local.sse_stream_aborted` typed error.
|
||||
|
||||
See `cli/AGENTS.md` "Stream recovery" section for the full agent contract.
|
||||
|
||||
@@ -185,8 +185,6 @@ func identToErrorCode(name string) (cmdutil.ErrorCode, bool) {
|
||||
return cmdutil.CodeLocalKeychainDenied, true
|
||||
case "CodeLocalFileIO":
|
||||
return cmdutil.CodeLocalFileIO, true
|
||||
case "CodeLocalUnimplemented":
|
||||
return cmdutil.CodeLocalUnimplemented, true
|
||||
case "CodeLocalProfileNotFound":
|
||||
return cmdutil.CodeLocalProfileNotFound, true
|
||||
case "CodeKBIDRequired":
|
||||
@@ -209,6 +207,8 @@ func identToErrorCode(name string) (cmdutil.ErrorCode, bool) {
|
||||
return cmdutil.CodeOperationFailed, true
|
||||
case "CodeOperationCancelled":
|
||||
return cmdutil.CodeOperationCancelled, true
|
||||
case "CodeInternalError":
|
||||
return cmdutil.CodeInternalError, true
|
||||
}
|
||||
return "", false
|
||||
}
|
||||
|
||||
@@ -40,71 +40,115 @@ func TestRAGFullLoop(t *testing.T) {
|
||||
|
||||
bin := buildBinary(t)
|
||||
xdg := t.TempDir()
|
||||
writeProfileYAML(t, xdg, host, token)
|
||||
|
||||
// Inject host + token as WEKNORA_HOST / WEKNORA_TOKEN env vars. The
|
||||
// CLI's env-credential path (buildClientFromEnv) takes precedence
|
||||
// over profile config, so this bypasses the secrets-store dance
|
||||
// entirely — no keychain access, no file:// ref plumbing. This is
|
||||
// the most robust path for CI and local e2e alike.
|
||||
env := append(os.Environ(),
|
||||
"XDG_CONFIG_HOME="+xdg,
|
||||
"XDG_CACHE_HOME="+filepath.Join(xdg, "cache"),
|
||||
"WEKNORA_HOST="+host,
|
||||
"WEKNORA_TOKEN="+token,
|
||||
// SDK debug off - explicit so the CI run isn't noisy.
|
||||
"WEKNORA_LOG_LEVEL=error",
|
||||
)
|
||||
|
||||
// 1. kb create → bare KnowledgeBase object
|
||||
// 1. kb create → KnowledgeBase object (envelope-wrapped: {ok, data})
|
||||
// The CLI now requires explicit model binding so uploaded docs are
|
||||
// immediately searchable. Use the server's builtin model IDs (they
|
||||
// exist on every deployment that configures builtin_models.yaml).
|
||||
embeddingModel := envOr("WEKNORA_E2E_EMBEDDING_MODEL", "Qwen/Qwen3-Embedding-8B")
|
||||
chatModel := envOr("WEKNORA_E2E_CHAT_MODEL", "deepseek-ai/DeepSeek-V3.2")
|
||||
kbName := prefix + fmt.Sprintf("%d", time.Now().UnixNano())
|
||||
var created struct {
|
||||
ID string `json:"id"`
|
||||
Name string `json:"name"`
|
||||
OK bool `json:"ok"`
|
||||
Data struct {
|
||||
ID string `json:"id"`
|
||||
Name string `json:"name"`
|
||||
} `json:"data"`
|
||||
}
|
||||
runJSONInto(t, bin, env, &created, "kb", "create", kbName, "--format", "json")
|
||||
if created.ID == "" {
|
||||
runJSONInto(t, bin, env, &created, "kb", "create", kbName,
|
||||
"--embedding-model", embeddingModel,
|
||||
"--chat-model", chatModel,
|
||||
"--format", "json")
|
||||
if created.Data.ID == "" {
|
||||
t.Fatalf("kb create returned no id")
|
||||
}
|
||||
t.Logf("created KB: %s (%s)", created.ID, kbName)
|
||||
t.Logf("created KB: %s (%s)", created.Data.ID, kbName)
|
||||
|
||||
t.Cleanup(func() {
|
||||
// Best-effort cleanup; a 404 means the KB was already gone.
|
||||
out, err := run(bin, env, "kb", "delete", created.ID, "-y", "--format", "json")
|
||||
out, err := run(bin, env, "kb", "delete", created.Data.ID, "-y", "--format", "json")
|
||||
if err != nil {
|
||||
t.Logf("cleanup kb delete: %v\n%s", err, out)
|
||||
}
|
||||
})
|
||||
|
||||
// 2. doc upload → bare Knowledge object
|
||||
// 2. doc upload → Knowledge object (envelope-wrapped: {ok, data})
|
||||
docPath := writeSampleDoc(t)
|
||||
var uploaded struct {
|
||||
ID string `json:"id"`
|
||||
OK bool `json:"ok"`
|
||||
Data struct {
|
||||
ID string `json:"id"`
|
||||
} `json:"data"`
|
||||
}
|
||||
runJSONInto(t, bin, env, &uploaded, "doc", "upload", docPath, "--kb", created.ID, "--format", "json")
|
||||
if uploaded.ID == "" {
|
||||
runJSONInto(t, bin, env, &uploaded, "doc", "upload", docPath, "--kb", created.Data.ID, "--format", "json")
|
||||
if uploaded.Data.ID == "" {
|
||||
t.Fatalf("doc upload returned no id")
|
||||
}
|
||||
t.Logf("uploaded doc: %s", uploaded.ID)
|
||||
t.Logf("uploaded doc: %s", uploaded.Data.ID)
|
||||
|
||||
// 3. poll until indexing finishes (status changes from "pending" / "processing" to "ready" / similar)
|
||||
waitDocReady(t, bin, env, created.ID, uploaded.ID, 90*time.Second)
|
||||
waitDocReady(t, bin, env, created.Data.ID, uploaded.Data.ID, 90*time.Second)
|
||||
|
||||
// 4. search chunks → bare []SearchResult
|
||||
var results []map[string]any
|
||||
runJSONInto(t, bin, env, &results, "search", "chunks", "sample", "--kb", created.ID, "--limit", "5", "--format", "json")
|
||||
// 4. search chunks → SearchResult list (envelope-wrapped: {ok, data})
|
||||
var searchResp struct {
|
||||
OK bool `json:"ok"`
|
||||
Data []map[string]any `json:"data"`
|
||||
}
|
||||
runJSONInto(t, bin, env, &searchResp, "search", "chunks", "sample", "--kb", created.Data.ID, "--limit", "5", "--format", "json")
|
||||
results := searchResp.Data
|
||||
if len(results) == 0 {
|
||||
t.Fatalf("search returned no results")
|
||||
}
|
||||
t.Logf("search returned %d results", len(results))
|
||||
|
||||
// 5. chat --format json → bare {answer, references, ...} object
|
||||
var chat struct {
|
||||
Answer string `json:"answer"`
|
||||
References []map[string]any `json:"references"`
|
||||
// 5. chat --format json → bounded answer-event envelope (--reference for citations)
|
||||
var chatEnv struct {
|
||||
OK bool `json:"ok"`
|
||||
Data struct {
|
||||
Events []struct {
|
||||
ResponseType string `json:"response_type"`
|
||||
Content string `json:"content"`
|
||||
KnowledgeReferences []struct {
|
||||
ChunkID string `json:"chunk_id"`
|
||||
} `json:"knowledge_references"`
|
||||
} `json:"events"`
|
||||
SessionID string `json:"session_id"`
|
||||
} `json:"data"`
|
||||
}
|
||||
runJSONInto(t, bin, env, &chat, "chat", "summarize the document briefly", "--kb", created.ID, "--format", "json")
|
||||
if strings.TrimSpace(chat.Answer) == "" {
|
||||
runJSONInto(t, bin, env, &chatEnv, "chat", "summarize the document briefly", "--kb", created.Data.ID, "--format", "json", "--reference")
|
||||
if !chatEnv.OK {
|
||||
t.Fatal("chat ok=false")
|
||||
}
|
||||
var answer strings.Builder
|
||||
refCount := 0
|
||||
for _, ev := range chatEnv.Data.Events {
|
||||
if ev.ResponseType == "answer" {
|
||||
answer.WriteString(ev.Content)
|
||||
}
|
||||
refCount += len(ev.KnowledgeReferences)
|
||||
}
|
||||
if strings.TrimSpace(answer.String()) == "" {
|
||||
t.Fatalf("chat returned empty answer")
|
||||
}
|
||||
t.Logf("chat answer (%d chars), %d references", len(chat.Answer), len(chat.References))
|
||||
if len(chat.References) == 0 {
|
||||
t.Logf("chat answer (%d chars), %d reference indexes", len(answer.String()), refCount)
|
||||
if refCount == 0 {
|
||||
// Soft warning - some servers may not surface references for every
|
||||
// question, but the demo flow is supposed to.
|
||||
t.Logf("warning: chat returned 0 references (server may have a different config)")
|
||||
t.Logf("warning: chat returned 0 reference indexes (server may have a different config)")
|
||||
}
|
||||
}
|
||||
|
||||
@@ -142,27 +186,6 @@ func buildBinary(t *testing.T) string {
|
||||
return out
|
||||
}
|
||||
|
||||
// writeProfileYAML drops a minimal config.yaml into XDG_CONFIG_HOME so the
|
||||
// CLI finds a profile without needing `weknora profile add` (which prompts
|
||||
// in interactive scenarios). Tests using `auth login` belong to a different
|
||||
// suite; here we go straight to authenticated calls.
|
||||
func writeProfileYAML(t *testing.T, xdg, host, token string) {
|
||||
t.Helper()
|
||||
dir := filepath.Join(xdg, "weknora")
|
||||
if err := os.MkdirAll(dir, 0o700); err != nil {
|
||||
t.Fatalf("mkdir xdg: %v", err)
|
||||
}
|
||||
yaml := fmt.Sprintf(`current_profile: e2e
|
||||
profiles:
|
||||
- name: e2e
|
||||
host: %s
|
||||
token: %s
|
||||
`, host, token)
|
||||
if err := os.WriteFile(filepath.Join(dir, "config.yaml"), []byte(yaml), 0o600); err != nil {
|
||||
t.Fatalf("write config: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
// writeSampleDoc emits a small bilingual doc that gives the embedder enough
|
||||
// signal for retrieval but stays tiny so indexing finishes within the poll
|
||||
// window.
|
||||
@@ -196,13 +219,18 @@ func waitDocReady(t *testing.T, bin string, env []string, kbID, docID string, ti
|
||||
t.Helper()
|
||||
deadline := time.Now().Add(timeout)
|
||||
tick := 2 * time.Second
|
||||
type docItem struct {
|
||||
ID string `json:"id"`
|
||||
ParseStatus string `json:"parse_status"`
|
||||
}
|
||||
for time.Now().Before(deadline) {
|
||||
var docs []struct {
|
||||
ID string `json:"id"`
|
||||
ParseStatus string `json:"parse_status"`
|
||||
// doc list is envelope-wrapped: {ok, data: [...]} (bare array)
|
||||
var resp struct {
|
||||
OK bool `json:"ok"`
|
||||
Data []docItem `json:"data"`
|
||||
}
|
||||
runJSONInto(t, bin, env, &docs, "doc", "list", "--kb", kbID, "--page-size", "100", "--format", "json")
|
||||
for _, d := range docs {
|
||||
runJSONInto(t, bin, env, &resp, "doc", "list", "--kb", kbID, "--page-size", "100", "--format", "json")
|
||||
for _, d := range resp.Data {
|
||||
if d.ID != docID {
|
||||
continue
|
||||
}
|
||||
@@ -210,7 +238,7 @@ func waitDocReady(t *testing.T, bin string, env []string, kbID, docID string, ti
|
||||
switch {
|
||||
case low == "failed", low == "error":
|
||||
t.Fatalf("doc %s indexing failed: status=%q", docID, d.ParseStatus)
|
||||
case low == "pending", low == "processing", low == "":
|
||||
case low == "pending", low == "processing", low == "finalizing", low == "":
|
||||
// keep waiting
|
||||
default:
|
||||
t.Logf("doc %s ready (status=%q)", docID, d.ParseStatus)
|
||||
|
||||
+1
-1
@@ -1 +1 @@
|
||||
{"ok":true,"data":{"profile":"","user_id":"usr_abc","email":"user@example.com","tenant_id":42,"tenant_name":"Acme"}}
|
||||
{"ok":true,"data":{"profile":"","auth_source":"profile + keyring","user_id":"usr_abc","email":"user@example.com","tenant_id":42,"tenant_name":"Acme"}}
|
||||
|
||||
+1
-1
@@ -1 +1 @@
|
||||
{"ok":true,"data":[{"id":"kb1","name":"Onboarding Docs","type":"","is_temporary":false,"is_pinned":false,"description":"","tenant_id":42,"chunking_config":{"chunk_size":0,"chunk_overlap":0,"separators":null},"image_processing_config":{"model_id":""},"faq_config":null,"embedding_model_id":"text-embedding-3","summary_model_id":"","vlm_config":{"enabled":false,"model_id":""},"storage_provider_config":null,"storage_config":{"secret_id":"","secret_key":"","region":"","bucket_name":"","app_id":"","path_prefix":"","provider":""},"extract_config":null,"created_at":"2025-01-01T12:00:00Z","updated_at":"2025-01-01T12:00:00Z","knowledge_count":5,"chunk_count":128,"is_processing":false,"processing_count":0},{"id":"kb2","name":"API Reference","type":"","is_temporary":false,"is_pinned":false,"description":"","tenant_id":42,"chunking_config":{"chunk_size":0,"chunk_overlap":0,"separators":null},"image_processing_config":{"model_id":""},"faq_config":null,"embedding_model_id":"text-embedding-3","summary_model_id":"","vlm_config":{"enabled":false,"model_id":""},"storage_provider_config":null,"storage_config":{"secret_id":"","secret_key":"","region":"","bucket_name":"","app_id":"","path_prefix":"","provider":""},"extract_config":null,"created_at":"2025-01-01T12:00:00Z","updated_at":"2025-01-01T12:00:00Z","knowledge_count":12,"chunk_count":340,"is_processing":false,"processing_count":0}],"meta":{"count":2}}
|
||||
{"ok":true,"data":[{"id":"kb1","name":"Onboarding Docs","type":"","is_temporary":false,"is_pinned":false,"description":"","tenant_id":42,"chunking_config":{"chunk_size":0,"chunk_overlap":0,"separators":null},"image_processing_config":{"model_id":""},"faq_config":null,"embedding_model_id":"text-embedding-3","summary_model_id":"","vlm_config":{"enabled":false,"model_id":""},"storage_provider_config":null,"storage_config":{"secret_id":"","secret_key":"","region":"","bucket_name":"","app_id":"","path_prefix":"","provider":""},"extract_config":null,"created_at":"2025-01-01T12:00:00Z","updated_at":"2025-01-01T12:00:00Z","knowledge_count":5,"chunk_count":128,"is_processing":false,"processing_count":0},{"id":"kb2","name":"API Reference","type":"","is_temporary":false,"is_pinned":false,"description":"","tenant_id":42,"chunking_config":{"chunk_size":0,"chunk_overlap":0,"separators":null},"image_processing_config":{"model_id":""},"faq_config":null,"embedding_model_id":"text-embedding-3","summary_model_id":"","vlm_config":{"enabled":false,"model_id":""},"storage_provider_config":null,"storage_config":{"secret_id":"","secret_key":"","region":"","bucket_name":"","app_id":"","path_prefix":"","provider":""},"extract_config":null,"created_at":"2025-01-01T12:00:00Z","updated_at":"2025-01-01T12:00:00Z","knowledge_count":12,"chunk_count":340,"is_processing":false,"processing_count":0}],"meta":{"count":2,"total_count":2}}
|
||||
|
||||
+1
-1
@@ -1 +1 @@
|
||||
{"ok":true,"data":[],"meta":{}}
|
||||
{"ok":true,"data":[],"meta":{"count":0,"total_count":0}}
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
// Package agentcmd holds the `weknora agent` command tree:
|
||||
// list / view / create / edit / delete / status / check. The directory is
|
||||
// list / view / create / update / delete / status / check. The directory is
|
||||
// named `agent/` to match the cobra subcommand; the Go package is `agentcmd`
|
||||
// to avoid colliding with cobra's *cobra.Command identifier.
|
||||
//
|
||||
@@ -22,7 +22,7 @@ func NewCmd(f *cmdutil.Factory) *cobra.Command {
|
||||
Use: "agent",
|
||||
Short: "Manage custom agents (CRUD + status/check)",
|
||||
Long: `Custom Agents bundle a system prompt, model, tool allow-list, and KB
|
||||
scope into an addressable resource. Create, edit, list, view, check,
|
||||
scope into an addressable resource. Create, update, list, view, check,
|
||||
or delete agents. To invoke an agent, use: weknora session ask --agent <id>`,
|
||||
}
|
||||
cmd.AddCommand(NewCmdList(f))
|
||||
|
||||
+72
-8
@@ -66,7 +66,8 @@ const agentCreateExample = ` weknora agent create "Support Bot" --model <model-
|
||||
|
||||
const agentCreateLong = `Create a new custom agent.
|
||||
|
||||
--model is required (an agent without a model cannot invoke). The 7
|
||||
--model is required (an agent without a model cannot invoke); discover a
|
||||
valid model id with 'weknora model list'. The 7
|
||||
optional hot-path flags cover the most frequently set AgentConfig fields;
|
||||
for the remaining 27 use --config-file with a YAML or JSON document
|
||||
matching the AgentConfig schema (run --generate-skeleton to get a
|
||||
@@ -122,6 +123,12 @@ func NewCmdCreate(f *cmdutil.Factory) *cobra.Command {
|
||||
fmt.Sprintf("--temperature must be in 0.0..2.0, got %g", opts.Temperature))
|
||||
}
|
||||
|
||||
// Reject an unknown --agent-mode / --kb-selection-mode up front
|
||||
// (typed exit 5) rather than letting the server fail the create.
|
||||
if err := validateAgentModeFlags(&opts.AgentMode, &opts.KBSelectionMode); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
if systemPromptFile != "" {
|
||||
r, err := cmdutil.OpenInput(systemPromptFile)
|
||||
if err != nil {
|
||||
@@ -159,6 +166,31 @@ func NewCmdCreate(f *cmdutil.Factory) *cobra.Command {
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
// Resolve --model / --rerank-model (id or name) and validate they
|
||||
// exist, matching the id-or-name policy of `kb config set`. A bogus name
|
||||
// fails fast here instead of creating an agent whose model never
|
||||
// resolves at run time.
|
||||
if opts.Model, err = cmdutil.ResolveModelRef(cmd.Context(), cli, opts.Model, "KnowledgeQA"); err != nil {
|
||||
return err
|
||||
}
|
||||
if opts.RerankModel, err = cmdutil.ResolveModelRef(cmd.Context(), cli, opts.RerankModel, "Rerank"); err != nil {
|
||||
return err
|
||||
}
|
||||
// Resolve --attach-kb values (id or name) to canonical ids,
|
||||
// matching the --kb flag's id-or-name policy. Without this a raw
|
||||
// name is stored verbatim as a kb_id, silently creating an agent
|
||||
// whose KB reference never resolves at run time.
|
||||
if len(opts.KBs) > 0 {
|
||||
resolved := make([]string, 0, len(opts.KBs))
|
||||
for _, raw := range opts.KBs {
|
||||
id, rerr := cmdutil.ResolveKBFlag(cmd.Context(), cli, raw)
|
||||
if rerr != nil {
|
||||
return rerr
|
||||
}
|
||||
resolved = append(resolved, id)
|
||||
}
|
||||
opts.KBs = resolved
|
||||
}
|
||||
return runCreate(cmd.Context(), opts, fopts, cli)
|
||||
},
|
||||
}
|
||||
@@ -166,17 +198,17 @@ func NewCmdCreate(f *cmdutil.Factory) *cobra.Command {
|
||||
// Required (enforced in PreRunE rather than cmd.MarkFlagRequired so
|
||||
// --generate-skeleton can bypass it — cobra's MarkFlagRequired runs
|
||||
// before PreRunE and would otherwise block the skeleton path).
|
||||
cmd.Flags().StringVar(&opts.Model, "model", "", "LLM model id (required, except with --generate-skeleton)")
|
||||
cmd.Flags().StringVar(&opts.Model, "model", "", "LLM model id or name (required, except with --generate-skeleton)")
|
||||
|
||||
// Hot-path (8 flag names, 7 distinct config fields)
|
||||
cmd.Flags().StringVar(&opts.Description, "description", "", "Agent description")
|
||||
cmd.Flags().StringVar(&opts.SystemPrompt, "system-prompt", "", "System prompt text (mutex with --system-prompt-file)")
|
||||
cmd.Flags().StringVar(&systemPromptFile, "system-prompt-file", "", "Read system prompt from FILE, or '-' for stdin")
|
||||
cmd.MarkFlagsMutuallyExclusive("system-prompt", "system-prompt-file")
|
||||
cmd.Flags().StringVar(&opts.AgentMode, "agent-mode", "", "Agent operating mode: quick-answer | smart-reasoning")
|
||||
cmd.Flags().StringSliceVar(&opts.KBs, "attach-kb", nil, "Attach a knowledge base id (repeatable); aligns with 'agent edit --add-kb'")
|
||||
cmd.Flags().StringVar(&opts.KBSelectionMode, "kb-selection-mode", "", "KB selection mode: all | selected | none")
|
||||
cmd.Flags().StringVar(&opts.RerankModel, "rerank-model", "", "Rerank model id")
|
||||
cmd.Flags().StringVar(&opts.AgentMode, "agent-mode", "", "Agent operating mode: "+strings.Join(agentModeValues, " | "))
|
||||
cmd.Flags().StringSliceVar(&opts.KBs, "attach-kb", nil, "Attach a knowledge base id (repeatable); aligns with 'agent update --add-kb'")
|
||||
cmd.Flags().StringVar(&opts.KBSelectionMode, "kb-selection-mode", "", "KB selection mode: "+strings.Join(kbSelectionModeValues, " | "))
|
||||
cmd.Flags().StringVar(&opts.RerankModel, "rerank-model", "", "Rerank model id or name")
|
||||
cmd.Flags().Float64Var(&opts.Temperature, "temperature", 0.0, "Generation temperature (0.0..2.0)")
|
||||
|
||||
// Power-user / utility
|
||||
@@ -187,9 +219,14 @@ func NewCmdCreate(f *cmdutil.Factory) *cobra.Command {
|
||||
cmdutil.AddFormatFlag(cmd, agentViewFields...)
|
||||
cmdutil.AddDryRunFlag(cmd, &opts.DryRun)
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "Create a new custom agent. --model is required; --attach-kb takes KB ids (repeatable, not names). Emits the created Agent object.",
|
||||
UsedFor: "Create a new custom agent. --model is required and accepts a model id or name; --attach-kb (repeatable) accepts KB ids or names. Emits the created Agent object.",
|
||||
RequiredFlags: []string{"<name> (positional)", "--model"},
|
||||
Output: "envelope.data is the created Agent object with id, name, config",
|
||||
Examples: []string{
|
||||
`weknora agent create "Support Bot" --model gpt-4o`,
|
||||
`weknora agent create "Support Bot" --model gpt-4o --attach-kb kb_eng --system-prompt "You are a support assistant."`,
|
||||
`weknora agent create --generate-skeleton # print a blank config to fill in (no --model needed)`,
|
||||
},
|
||||
Output: "envelope.data is the created Agent object with id, name, config",
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
@@ -270,6 +307,33 @@ func runCreate(ctx context.Context, opts *CreateOptions, fopts *cmdutil.FormatOp
|
||||
return emitAgent(fopts, created)
|
||||
}
|
||||
|
||||
// agentModeValues / kbSelectionModeValues are the closed server enums for the
|
||||
// --agent-mode / --kb-selection-mode flags, sourced from the SDK enumerators so
|
||||
// the CLI can't drift from the server vocabulary.
|
||||
var (
|
||||
agentModeValues = cmdutil.EnumStrings(sdk.AllAgentModes())
|
||||
kbSelectionModeValues = cmdutil.EnumStrings(sdk.AllKBSelectionModes())
|
||||
)
|
||||
|
||||
// validateAgentModeFlags validates and canonicalises --agent-mode and
|
||||
// --kb-selection-mode in place against the SDK enums. An empty value passes
|
||||
// through (flag unset → no override). Rejecting a typo here gives a fast,
|
||||
// typed input.invalid_argument instead of a confusing server-side failure.
|
||||
// Shared by `agent create` and `agent update`.
|
||||
func validateAgentModeFlags(agentMode, kbSelectionMode *string) error {
|
||||
v, err := cmdutil.ValidateEnum("agent-mode", *agentMode, agentModeValues)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
*agentMode = v
|
||||
v, err = cmdutil.ValidateEnum("kb-selection-mode", *kbSelectionMode, kbSelectionModeValues)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
*kbSelectionMode = v
|
||||
return nil
|
||||
}
|
||||
|
||||
// applyCreateOverrides merges hot-path flag overrides into the base config,
|
||||
// then applies the "--attach-kb implies --kb-selection-mode=selected" fallback.
|
||||
// Shared by the --from path (base=copied agent's config) and the plain
|
||||
|
||||
@@ -218,6 +218,44 @@ func TestCreate_Temperature_Bounds(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// TestCreate_AgentModeValidation: an unknown --agent-mode / --kb-selection-mode
|
||||
// is rejected up front (PreRunE) with a typed input.invalid_argument (exit 5),
|
||||
// while a valid value passes the gate. The closed set is sourced from the SDK
|
||||
// enumerators, so this also guards against CLI/SDK drift.
|
||||
func TestCreate_AgentModeValidation(t *testing.T) {
|
||||
cases := []struct {
|
||||
name string
|
||||
args []string
|
||||
wantErr string // substring; "" means the mode gate must pass
|
||||
}{
|
||||
{"bad agent-mode", []string{"--agent-mode", "bogus"}, "agent-mode"},
|
||||
{"bad kb-selection-mode", []string{"--kb-selection-mode", "every"}, "kb-selection-mode"},
|
||||
{"valid agent-mode", []string{"--agent-mode", "smart-reasoning", "--dry-run"}, ""},
|
||||
{"valid kb-selection-mode", []string{"--kb-selection-mode", "selected", "--dry-run"}, ""},
|
||||
}
|
||||
for _, tc := range cases {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
cmd := NewCmdCreate(nil)
|
||||
cmd.SetArgs(append([]string{"Test", "--model", "model-x"}, tc.args...))
|
||||
cmd.SilenceUsage, cmd.SilenceErrors = true, true
|
||||
err := cmd.Execute()
|
||||
if tc.wantErr == "" {
|
||||
// Valid mode + --dry-run: must clear the mode gate. (--dry-run
|
||||
// short-circuits before any client call, so nil factory is fine.)
|
||||
require.NoError(t, err)
|
||||
return
|
||||
}
|
||||
require.Error(t, err)
|
||||
var ce *cmdutil.Error
|
||||
require.ErrorAs(t, err, &ce)
|
||||
assert.Equal(t, cmdutil.CodeInputInvalidArgument, ce.Code)
|
||||
assert.Equal(t, 5, cmdutil.ExitCode(err))
|
||||
assert.Contains(t, err.Error(), tc.wantErr)
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestCreate_CopyAgent_NotFound(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
svc := &fakeCreateSvc{copyErr: errBadHTTP404}
|
||||
@@ -251,4 +289,3 @@ func TestCreate_AttachKBFlagExists(t *testing.T) {
|
||||
old := cmd.Flags().Lookup("kb")
|
||||
assert.Nil(t, old, "old --kb flag must not exist on 'agent create' (renamed to --attach-kb)")
|
||||
}
|
||||
|
||||
|
||||
@@ -93,6 +93,7 @@ func NewCmdDelete(f *cmdutil.Factory) *cobra.Command {
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "permanently delete a custom agent",
|
||||
RequiredFlags: []string{"<agent-id> (positional)"},
|
||||
Output: "envelope.data is {id, deleted:true}",
|
||||
Examples: []string{
|
||||
"weknora agent delete ag_abc -y",
|
||||
"weknora agent delete ag_abc -y --format json",
|
||||
@@ -106,7 +107,7 @@ func NewCmdDelete(f *cmdutil.Factory) *cobra.Command {
|
||||
}
|
||||
|
||||
func runDelete(ctx context.Context, opts *DeleteOptions, fopts *cmdutil.FormatOptions, svc DeleteService, p prompt.Prompter) error {
|
||||
if err := cmdutil.ConfirmDestructive(p, opts.Yes, fopts.WantsJSON(), "delete", "agent", opts.AgentID, "agent.delete", "weknora agent delete "+opts.AgentID+" -y"); err != nil {
|
||||
if err := cmdutil.ConfirmDestructive(p, opts.Yes, fopts.WantsJSON(), "delete", "agent", opts.AgentID, "agent.delete", []string{"weknora", "agent", "delete", opts.AgentID, "-y"}); err != nil {
|
||||
return err
|
||||
}
|
||||
if err := svc.DeleteAgent(ctx, opts.AgentID); err != nil {
|
||||
|
||||
+67
-58
@@ -8,7 +8,6 @@ import (
|
||||
"strings"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
"github.com/spf13/pflag"
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
||||
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
||||
@@ -22,6 +21,10 @@ import (
|
||||
type EditService interface {
|
||||
GetAgent(ctx context.Context, id string) (*sdk.Agent, error)
|
||||
UpdateAgent(ctx context.Context, id string, req *sdk.UpdateAgentRequest) (*sdk.Agent, error)
|
||||
// ListModels backs --model / --rerank-model id-or-name resolution so a
|
||||
// bogus name fails fast instead of clobbering config.model_id with an
|
||||
// unresolvable string (which never resolves at run time).
|
||||
ListModels(ctx context.Context) ([]sdk.Model, error)
|
||||
}
|
||||
|
||||
// EditOptions captures the surgical flag state. Both string fields and
|
||||
@@ -64,7 +67,7 @@ type editFlagSet struct {
|
||||
configFileSet bool
|
||||
}
|
||||
|
||||
const agentEditLong = `Edit a custom agent's fields surgically.
|
||||
const agentEditLong = `Update a custom agent's fields surgically.
|
||||
|
||||
At least one update flag is required; flags you omit preserve the current
|
||||
server-side value via fetch-then-update. Pass --description "" to clear
|
||||
@@ -89,20 +92,20 @@ with input.confirmation_required. Surface the prompt to the user and only
|
||||
retry with -y after explicit approval. Other failure codes: resource.not_found
|
||||
(agent id or KB id), auth.forbidden, input.invalid_argument (no flags, bad file).`
|
||||
|
||||
const agentEditExample = ` weknora agent edit ag_abc --name "Renamed" -y
|
||||
weknora agent edit ag_abc --description "" -y # clear description
|
||||
weknora agent edit ag_abc --add-kb kb_new --remove-kb kb_old -y
|
||||
weknora agent edit ag_abc --system-prompt-file ./prompt.md -y
|
||||
weknora agent edit ag_abc --config-file ./tuned.yaml --temperature 0.9 -y`
|
||||
const agentEditExample = ` weknora agent update ag_abc --name "Renamed" -y
|
||||
weknora agent update ag_abc --description "" -y # clear description
|
||||
weknora agent update ag_abc --add-kb kb_new --remove-kb kb_old -y
|
||||
weknora agent update ag_abc --system-prompt-file ./prompt.md -y
|
||||
weknora agent update ag_abc --config-file ./tuned.yaml --temperature 0.9 -y`
|
||||
|
||||
// NewCmdEdit builds `weknora agent edit <agent-id>`.
|
||||
// NewCmdEdit builds `weknora agent update <agent-id>`.
|
||||
func NewCmdEdit(f *cmdutil.Factory) *cobra.Command {
|
||||
opts := &EditOptions{}
|
||||
var systemPromptFile, configFile string
|
||||
|
||||
cmd := &cobra.Command{
|
||||
Use: "edit <agent-id>",
|
||||
Short: "Edit a custom agent's configuration",
|
||||
Use: "update <agent-id>",
|
||||
Short: "Update a custom agent's configuration",
|
||||
Long: agentEditLong,
|
||||
Example: agentEditExample,
|
||||
Args: cobra.ExactArgs(1),
|
||||
@@ -127,6 +130,12 @@ func NewCmdEdit(f *cmdutil.Factory) *cobra.Command {
|
||||
fmt.Sprintf("--temperature must be in 0.0..2.0, got %g", opts.Temperature))
|
||||
}
|
||||
|
||||
// Reject an unknown --agent-mode / --kb-selection-mode up front
|
||||
// (typed exit 5) rather than letting the server fail the update.
|
||||
if err := validateAgentModeFlags(&opts.AgentMode, &opts.KBSelectionMode); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
if systemPromptFile != "" {
|
||||
r, err := cmdutil.OpenInput(systemPromptFile)
|
||||
if err != nil {
|
||||
@@ -156,7 +165,7 @@ func NewCmdEdit(f *cmdutil.Factory) *cobra.Command {
|
||||
if !editHasAnyFlag(opts) {
|
||||
return &cmdutil.Error{
|
||||
Code: cmdutil.CodeInputInvalidArgument,
|
||||
Message: "agent edit requires at least one flag",
|
||||
Message: "agent update requires at least one flag",
|
||||
Hint: "pass at least one update flag (e.g., --name, --add-kb, --description) or --config-file",
|
||||
}
|
||||
}
|
||||
@@ -200,7 +209,7 @@ func NewCmdEdit(f *cmdutil.Factory) *cobra.Command {
|
||||
}
|
||||
}
|
||||
if handled, err := cmdutil.HandleDryRun(cmd, true, cmdutil.DryRunPlan{
|
||||
Action: "agent.edit",
|
||||
Action: "agent.update",
|
||||
Args: planArgs,
|
||||
}); handled {
|
||||
return err
|
||||
@@ -208,14 +217,32 @@ func NewCmdEdit(f *cmdutil.Factory) *cobra.Command {
|
||||
}
|
||||
yes, _ := cmd.Flags().GetBool("yes")
|
||||
// Build the retry command from the flags the user actually passed.
|
||||
retryCmd := buildAgentEditRetryCmd(cmd, opts.AgentID)
|
||||
if err := cmdutil.ConfirmDestructive(f.Prompter(), yes, fopts.WantsJSON(), "edit", "agent", opts.AgentID, "agent.edit", retryCmd); err != nil {
|
||||
// --add-kb/--remove-kb/--system-prompt-file/--config-file are excluded
|
||||
// (multi-value / file-based — a precise single argv is impractical).
|
||||
retryCmd := cmdutil.BuildRetryArgv(cmd, []string{"weknora", "agent", "update", opts.AgentID},
|
||||
"name", "description", "model", "system-prompt", "agent-mode",
|
||||
"rerank-model", "temperature", "kb-selection-mode", "format")
|
||||
if err := cmdutil.ConfirmWrite(f.Prompter(), yes, fopts.WantsJSON(), "update", "agent", opts.AgentID, "agent.update", retryCmd); err != nil {
|
||||
return err
|
||||
}
|
||||
cli, err := f.Client()
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
// Resolve --add-kb values (id or name) to canonical ids, matching
|
||||
// the --kb id-or-name policy and agent create --attach-kb. Avoids
|
||||
// silently attaching an unresolvable name as a kb_id.
|
||||
if len(opts.AddKBs) > 0 {
|
||||
resolved := make([]string, 0, len(opts.AddKBs))
|
||||
for _, raw := range opts.AddKBs {
|
||||
id, rerr := cmdutil.ResolveKBFlag(cmd.Context(), cli, raw)
|
||||
if rerr != nil {
|
||||
return rerr
|
||||
}
|
||||
resolved = append(resolved, id)
|
||||
}
|
||||
opts.AddKBs = resolved
|
||||
}
|
||||
return runEdit(cmd.Context(), opts, fopts, cli)
|
||||
},
|
||||
}
|
||||
@@ -227,68 +254,36 @@ func NewCmdEdit(f *cmdutil.Factory) *cobra.Command {
|
||||
cmd.Flags().StringVar(&opts.SystemPrompt, "system-prompt", "", "System prompt text (mutex with --system-prompt-file)")
|
||||
cmd.Flags().StringVar(&systemPromptFile, "system-prompt-file", "", "Read system prompt from FILE, or '-' for stdin")
|
||||
cmd.MarkFlagsMutuallyExclusive("system-prompt", "system-prompt-file")
|
||||
cmd.Flags().StringVar(&opts.AgentMode, "agent-mode", "", "Agent operating mode: quick-answer | smart-reasoning")
|
||||
cmd.Flags().StringVar(&opts.AgentMode, "agent-mode", "", "Agent operating mode: "+strings.Join(agentModeValues, " | "))
|
||||
cmd.Flags().StringVar(&opts.RerankModel, "rerank-model", "", "Rerank model id")
|
||||
cmd.Flags().Float64Var(&opts.Temperature, "temperature", 0.0, "Generation temperature (0.0..2.0)")
|
||||
cmd.Flags().StringSliceVar(&opts.AddKBs, "add-kb", nil, "Attach knowledge base id (repeatable, idempotent)")
|
||||
cmd.Flags().StringSliceVar(&opts.RemoveKBs, "remove-kb", nil, "Detach knowledge base id (repeatable, idempotent)")
|
||||
cmd.Flags().StringVar(&opts.KBSelectionMode, "kb-selection-mode", "", "KB selection mode: all | selected | none")
|
||||
cmd.Flags().StringVar(&opts.KBSelectionMode, "kb-selection-mode", "", "KB selection mode: "+strings.Join(kbSelectionModeValues, " | "))
|
||||
|
||||
// Full-replace
|
||||
cmd.Flags().StringVar(&configFile, "config-file", "", "Full AgentConfig YAML or JSON (REPLACES current config baseline; surgical flags then apply on top)")
|
||||
|
||||
cmdutil.AddFormatFlag(cmd, agentViewFields...)
|
||||
cmdutil.AddDryRunFlag(cmd, &opts.DryRun)
|
||||
cmdutil.SetRisk(cmd, "agent.edit")
|
||||
cmdutil.SetWriteRisk(cmd, "agent.update")
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "surgically edit a custom agent's configuration",
|
||||
RequiredFlags: []string{"<agent-id> (positional)", "at least one edit flag (--name, --add-kb, etc.)"},
|
||||
UsedFor: "surgically update a custom agent's configuration",
|
||||
RequiredFlags: []string{"<agent-id> (positional)", "at least one update flag (--name, --add-kb, etc.)"},
|
||||
Examples: []string{
|
||||
"weknora agent edit ag_abc --name \"Renamed\"",
|
||||
"weknora agent edit ag_abc --add-kb kb_new --remove-kb kb_old",
|
||||
"weknora agent edit ag_abc --config-file ./tuned.yaml",
|
||||
"weknora agent update ag_abc --name \"Renamed\"",
|
||||
"weknora agent update ag_abc --add-kb kb_new --remove-kb kb_old",
|
||||
"weknora agent update ag_abc --config-file ./tuned.yaml",
|
||||
},
|
||||
Output: "envelope.data is the updated Agent object (id, name, config) after the update is applied",
|
||||
Warnings: []string{
|
||||
"Requires explicit user approval (exit 10 / input.confirmation_required); never auto-add -y.",
|
||||
"agent edit overwrites config; fetch-then-update protects unmentioned fields, but bad input still saved.",
|
||||
"agent update overwrites config; fetch-then-update protects unmentioned fields, but bad input still saved.",
|
||||
},
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
|
||||
// buildAgentEditRetryCmd constructs a directly-executable retry argv from the
|
||||
// flags the user actually set so agents can surface a precise re-run command.
|
||||
func buildAgentEditRetryCmd(cmd *cobra.Command, id string) string {
|
||||
var parts []string
|
||||
parts = append(parts, "weknora", "agent", "edit", id)
|
||||
cmd.Flags().Visit(func(f *pflag.Flag) {
|
||||
switch f.Name {
|
||||
case "name":
|
||||
parts = append(parts, "--name", f.Value.String())
|
||||
case "description":
|
||||
parts = append(parts, "--description", f.Value.String())
|
||||
case "model":
|
||||
parts = append(parts, "--model", f.Value.String())
|
||||
case "system-prompt":
|
||||
parts = append(parts, "--system-prompt", f.Value.String())
|
||||
case "agent-mode":
|
||||
parts = append(parts, "--agent-mode", f.Value.String())
|
||||
case "rerank-model":
|
||||
parts = append(parts, "--rerank-model", f.Value.String())
|
||||
case "temperature":
|
||||
parts = append(parts, "--temperature", f.Value.String())
|
||||
case "kb-selection-mode":
|
||||
parts = append(parts, "--kb-selection-mode", f.Value.String())
|
||||
case "format":
|
||||
parts = append(parts, "--format", f.Value.String())
|
||||
// --add-kb, --remove-kb, --system-prompt-file, --config-file are excluded
|
||||
// because they are multi-value or file-based; a precise argv is impractical.
|
||||
// The user must reconstruct those manually.
|
||||
}
|
||||
})
|
||||
parts = append(parts, "-y")
|
||||
return strings.Join(parts, " ")
|
||||
}
|
||||
|
||||
// editHasAnyFlag reports whether opts carries at least one surgical update
|
||||
// signal. Required-flag validation lives in runEdit (not PreRunE) so unit
|
||||
@@ -304,7 +299,7 @@ func runEdit(ctx context.Context, opts *EditOptions, fopts *cmdutil.FormatOption
|
||||
if !editHasAnyFlag(opts) {
|
||||
return &cmdutil.Error{
|
||||
Code: cmdutil.CodeInputInvalidArgument,
|
||||
Message: "agent edit requires at least one flag",
|
||||
Message: "agent update requires at least one flag",
|
||||
Hint: "pass at least one update flag (e.g., --name, --add-kb, --description) or --config-file",
|
||||
}
|
||||
}
|
||||
@@ -338,6 +333,20 @@ func runEdit(ctx context.Context, opts *EditOptions, fopts *cmdutil.FormatOption
|
||||
opts.SystemPrompt = strings.TrimSpace(string(body))
|
||||
}
|
||||
|
||||
// Resolve --model / --rerank-model (id or name) and validate they exist,
|
||||
// mirroring agent create. Without this a bogus name is stored verbatim as
|
||||
// config.model_id and the agent silently never resolves at run time.
|
||||
if opts.flags.modelSet {
|
||||
if opts.Model, err = cmdutil.ResolveModelRef(ctx, svc, opts.Model, "KnowledgeQA"); err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
if opts.flags.rerankModelSet {
|
||||
if opts.RerankModel, err = cmdutil.ResolveModelRef(ctx, svc, opts.RerankModel, "Rerank"); err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
|
||||
// Compute KB list from current + add/remove with a stderr warning when
|
||||
// the same id appears in both flags (net no-op, still idempotent).
|
||||
kbs := computeKBList(base.KnowledgeBases, opts.AddKBs, opts.RemoveKBs)
|
||||
@@ -373,7 +382,7 @@ func runEdit(ctx context.Context, opts *EditOptions, fopts *cmdutil.FormatOption
|
||||
|
||||
updated, err := svc.UpdateAgent(ctx, opts.AgentID, req)
|
||||
if err != nil {
|
||||
return cmdutil.WrapHTTP(err, "edit agent %s", opts.AgentID)
|
||||
return cmdutil.WrapHTTP(err, "update agent %s", opts.AgentID)
|
||||
}
|
||||
return emitAgent(fopts, updated)
|
||||
}
|
||||
|
||||
@@ -28,6 +28,8 @@ type fakeEditSvc struct {
|
||||
updateResp *sdk.Agent
|
||||
updateErr error
|
||||
updateCalls int
|
||||
models []sdk.Model
|
||||
modelsErr error
|
||||
}
|
||||
|
||||
func (f *fakeEditSvc) GetAgent(_ context.Context, _ string) (*sdk.Agent, error) {
|
||||
@@ -41,6 +43,40 @@ func (f *fakeEditSvc) UpdateAgent(_ context.Context, id string, req *sdk.UpdateA
|
||||
return f.updateResp, f.updateErr
|
||||
}
|
||||
|
||||
func (f *fakeEditSvc) ListModels(_ context.Context) ([]sdk.Model, error) {
|
||||
return f.models, f.modelsErr
|
||||
}
|
||||
|
||||
func TestEdit_ModelName_ResolvedToID(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
svc := &fakeEditSvc{
|
||||
getResp: &sdk.Agent{ID: "ag_abc", Name: "A", Config: &sdk.AgentConfig{ModelID: "old-id"}},
|
||||
updateResp: &sdk.Agent{ID: "ag_abc"},
|
||||
models: []sdk.Model{{ID: "m-real", Name: "good-llm", Type: "KnowledgeQA"}},
|
||||
}
|
||||
opts := &EditOptions{AgentID: "ag_abc", Model: "good-llm", flags: editFlagSet{modelSet: true}}
|
||||
require.NoError(t, runEdit(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc))
|
||||
require.NotNil(t, svc.updateReq)
|
||||
require.NotNil(t, svc.updateReq.Config)
|
||||
assert.Equal(t, "m-real", svc.updateReq.Config.ModelID, "--model name must resolve to the model id")
|
||||
}
|
||||
|
||||
func TestEdit_BogusModelName_RejectedNoWrite(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
svc := &fakeEditSvc{
|
||||
getResp: &sdk.Agent{ID: "ag_abc", Name: "A", Config: &sdk.AgentConfig{ModelID: "old-id"}},
|
||||
updateResp: &sdk.Agent{ID: "ag_abc"},
|
||||
models: []sdk.Model{{ID: "m-real", Name: "good-llm", Type: "KnowledgeQA"}},
|
||||
}
|
||||
opts := &EditOptions{AgentID: "ag_abc", Model: "totally-bogus-model-xyz", flags: editFlagSet{modelSet: true}}
|
||||
err := runEdit(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc)
|
||||
require.Error(t, err, "a --model name matching no model must fail")
|
||||
var e *cmdutil.Error
|
||||
require.ErrorAs(t, err, &e)
|
||||
assert.Equal(t, cmdutil.CodeResourceNotFound, e.Code)
|
||||
assert.Equal(t, 0, svc.updateCalls, "must not write an agent with an unresolvable model")
|
||||
}
|
||||
|
||||
func TestEdit_FetchThenUpdate_PreservesUntouchedFields(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
svc := &fakeEditSvc{
|
||||
@@ -250,7 +286,7 @@ func TestEdit_SystemPromptFile(t *testing.T) {
|
||||
assert.Equal(t, "new prompt", svc.updateReq.Config.SystemPrompt)
|
||||
}
|
||||
|
||||
// withRootHarnessAgent wraps `weknora agent edit ...` under a synthetic root
|
||||
// withRootHarnessAgent wraps `weknora agent update ...` under a synthetic root
|
||||
// cmd that registers the global persistent flags (mirrors addGlobalFlags in
|
||||
// cmd/root.go).
|
||||
func withRootHarnessAgent(edit *cobra.Command, args ...string) *cobra.Command {
|
||||
@@ -262,7 +298,7 @@ func withRootHarnessAgent(edit *cobra.Command, args ...string) *cobra.Command {
|
||||
ag := &cobra.Command{Use: "agent"}
|
||||
ag.AddCommand(edit)
|
||||
root.AddCommand(ag)
|
||||
root.SetArgs(append([]string{"agent", "edit"}, args...))
|
||||
root.SetArgs(append([]string{"agent", "update"}, args...))
|
||||
root.SetContext(context.Background())
|
||||
root.SilenceErrors = true
|
||||
root.SilenceUsage = true
|
||||
@@ -270,7 +306,7 @@ func withRootHarnessAgent(edit *cobra.Command, args ...string) *cobra.Command {
|
||||
}
|
||||
|
||||
// TestAgentEdit_RequiresConfirmation asserts that without -y (non-TTY / JSON
|
||||
// mode), agent edit returns input.confirmation_required (exit 10).
|
||||
// mode), agent update returns input.confirmation_required (exit 10).
|
||||
func TestAgentEdit_RequiresConfirmation(t *testing.T) {
|
||||
iostreams.SetForTest(t) // non-TTY
|
||||
f := &cmdutil.Factory{
|
||||
@@ -284,7 +320,7 @@ func TestAgentEdit_RequiresConfirmation(t *testing.T) {
|
||||
require.ErrorAs(t, err, &ce)
|
||||
assert.Equal(t, cmdutil.CodeInputConfirmationRequired, ce.Code)
|
||||
assert.Equal(t, 10, cmdutil.ExitCode(err), "exit code 10 per destructive-write protocol")
|
||||
// retry command must include -y and the agent id
|
||||
assert.Contains(t, ce.RetryCommand, "-y")
|
||||
assert.Contains(t, ce.RetryCommand, "ag_abc")
|
||||
// retry argv must include -y and the agent id
|
||||
assert.Contains(t, ce.RetryArgv, "-y")
|
||||
assert.Contains(t, ce.RetryArgv, "ag_abc")
|
||||
}
|
||||
|
||||
+31
-9
@@ -51,6 +51,11 @@ func NewCmdList(f *cmdutil.Factory) *cobra.Command {
|
||||
return err
|
||||
}
|
||||
fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
|
||||
// Validate static input before building the client so a bad --limit
|
||||
// returns input.invalid_argument (exit 5), not an auth error (exit 3).
|
||||
if err := validateListOpts(opts); err != nil {
|
||||
return err
|
||||
}
|
||||
cli, err := f.Client()
|
||||
if err != nil {
|
||||
return err
|
||||
@@ -58,19 +63,22 @@ func NewCmdList(f *cmdutil.Factory) *cobra.Command {
|
||||
return runList(c.Context(), opts, fopts, cli)
|
||||
},
|
||||
}
|
||||
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)")
|
||||
cmdutil.AddFormatFlag(cmd, agentListFields...)
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "List custom agents visible to the active tenant. The SDK returns all agents in one call (no server-side pagination); meta.count reflects the full tenant set, --limit caps client-side.",
|
||||
Examples: []string{"weknora agent list --format json", "weknora agent list --limit 10 --format json"},
|
||||
Output: "envelope.data is an array of Agent objects with id, name, is_builtin; meta.count is the total returned",
|
||||
Output: "envelope.data is an array of Agent objects with id, name, is_builtin; meta.total_count is the full tenant set and meta.has_more=true means --limit truncated it (raise --limit to get the rest)",
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
|
||||
func runList(ctx context.Context, opts *ListOptions, fopts *cmdutil.FormatOptions, svc ListService) error {
|
||||
// validateListOpts checks --limit. Called from RunE before the client is built
|
||||
// (so a bad value surfaces as exit 5, not an auth error) and at runList's top
|
||||
// for direct callers; idempotent and nil-safe.
|
||||
func validateListOpts(opts *ListOptions) error {
|
||||
if opts == nil {
|
||||
opts = &ListOptions{}
|
||||
return nil
|
||||
}
|
||||
if opts.Limit < 1 || opts.Limit > 10000 {
|
||||
return &cmdutil.Error{
|
||||
@@ -78,6 +86,16 @@ func runList(ctx context.Context, opts *ListOptions, fopts *cmdutil.FormatOption
|
||||
Message: fmt.Sprintf("--limit must be in 1..10000, got %d", opts.Limit),
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func runList(ctx context.Context, opts *ListOptions, fopts *cmdutil.FormatOptions, svc ListService) error {
|
||||
if opts == nil {
|
||||
opts = &ListOptions{}
|
||||
}
|
||||
if err := validateListOpts(opts); err != nil {
|
||||
return err
|
||||
}
|
||||
items, err := svc.ListAgents(ctx)
|
||||
if err != nil {
|
||||
return cmdutil.WrapHTTP(err, "list agents")
|
||||
@@ -90,16 +108,20 @@ func runList(ctx context.Context, opts *ListOptions, fopts *cmdutil.FormatOption
|
||||
sort.Slice(items, func(i, j int) bool {
|
||||
return items[i].UpdatedAt.After(items[j].UpdatedAt)
|
||||
})
|
||||
// --limit applies after sort so the cap returns the top-N most-recent.
|
||||
// The agent list SDK is unpaginated, so client-side truncation does not
|
||||
// imply server-side has_more — there is no cursor to continue with.
|
||||
// has_more is omitted; callers needing all agents should raise --limit.
|
||||
// The agent list SDK is unpaginated — it returns every agent in one
|
||||
// call — so the CLI holds the true total and can tell the caller
|
||||
// whether the client-side --limit dropped any. total_count is the full
|
||||
// count; has_more flags that --limit truncated it (raise --limit to get
|
||||
// the rest — there is no server cursor to continue with).
|
||||
total := len(items)
|
||||
truncated := false
|
||||
if opts.Limit > 0 && len(items) > opts.Limit {
|
||||
items = items[:opts.Limit]
|
||||
truncated = true
|
||||
}
|
||||
|
||||
if fopts.WantsJSON() {
|
||||
meta := &output.Meta{Count: len(items)}
|
||||
meta := &output.Meta{Count: output.IntPtr(len(items)), HasMore: truncated, TotalCount: output.IntPtr(total)}
|
||||
return fopts.Emit(iostreams.IO.Out, items, meta)
|
||||
}
|
||||
|
||||
|
||||
@@ -145,6 +145,35 @@ func TestList_Limit_CapsResults(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// TestList_Truncation_SignalsHasMoreAndTotal pins that --limit truncation
|
||||
// tells the agent it did not get everything (has_more + total_count).
|
||||
// Regression: agent list silently dropped agents past --limit with no signal.
|
||||
func TestList_Truncation_SignalsHasMoreAndTotal(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
if err := runList(context.Background(), &ListOptions{Limit: 5}, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, &fakeListSvc{items: makeAgents(20)}); err != nil {
|
||||
t.Fatalf("runList: %v", err)
|
||||
}
|
||||
if !strings.Contains(out.String(), `"has_more":true`) {
|
||||
t.Errorf("truncated list must set has_more:true; got:\n%s", out.String())
|
||||
}
|
||||
if !strings.Contains(out.String(), `"total_count":20`) {
|
||||
t.Errorf("truncated list must report total_count:20; got:\n%s", out.String())
|
||||
}
|
||||
}
|
||||
|
||||
func TestList_NoTruncation_OmitsHasMore(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
if err := runList(context.Background(), &ListOptions{Limit: 30}, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, &fakeListSvc{items: makeAgents(3)}); err != nil {
|
||||
t.Fatalf("runList: %v", err)
|
||||
}
|
||||
if strings.Contains(out.String(), `"has_more"`) {
|
||||
t.Errorf("non-truncated list must omit has_more; got:\n%s", out.String())
|
||||
}
|
||||
if !strings.Contains(out.String(), `"total_count":3`) {
|
||||
t.Errorf("list must report total_count:3; got:\n%s", out.String())
|
||||
}
|
||||
}
|
||||
|
||||
func TestList_Limit_Zero_Rejected(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
err := runList(context.Background(), &ListOptions{Limit: 0}, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, &fakeListSvc{items: makeAgents(7)})
|
||||
|
||||
@@ -43,3 +43,67 @@ func TestEveryLeafCommandHasAgentHelp(t *testing.T) {
|
||||
missing, len(missing))
|
||||
}
|
||||
}
|
||||
|
||||
// renderAgentHelp runs a leaf's help under WEKNORA_AGENT_HELP=1 and decodes the
|
||||
// machine blob (used_for / output / examples) an agent would read.
|
||||
func renderAgentHelp(t *testing.T, c *cobra.Command) struct {
|
||||
UsedFor string `json:"used_for"`
|
||||
Output string `json:"output"`
|
||||
Examples []string `json:"examples"`
|
||||
} {
|
||||
t.Helper()
|
||||
var buf bytes.Buffer
|
||||
c.SetOut(&buf)
|
||||
c.Help()
|
||||
var ah struct {
|
||||
UsedFor string `json:"used_for"`
|
||||
Output string `json:"output"`
|
||||
Examples []string `json:"examples"`
|
||||
}
|
||||
if err := json.Unmarshal(buf.Bytes(), &ah); err != nil {
|
||||
t.Fatalf("%s: agent-help is not JSON: %v", c.CommandPath(), err)
|
||||
}
|
||||
return ah
|
||||
}
|
||||
|
||||
// TestEveryLeafCommandDeclaresOutput enforces that every leaf command tells an
|
||||
// agent what its stdout carries. Even side-effect commands describe their
|
||||
// envelope (e.g. deletes emit {id, deleted:true}); an empty Output is a contract
|
||||
// gap, not a valid state. Sibling drift guard to the agent-help test above.
|
||||
func TestEveryLeafCommandDeclaresOutput(t *testing.T) {
|
||||
t.Setenv("WEKNORA_AGENT_HELP", "1")
|
||||
root := NewRootCmd(cmdutil.New())
|
||||
|
||||
var missing []string
|
||||
eachLeafCommand(root, func(c *cobra.Command) {
|
||||
if renderAgentHelp(t, c).Output == "" {
|
||||
missing = append(missing, c.CommandPath())
|
||||
}
|
||||
})
|
||||
|
||||
sort.Strings(missing)
|
||||
if len(missing) > 0 {
|
||||
t.Errorf("leaf commands missing agent-help Output (declare AgentHelp.Output):\n %v\n(%d commands)",
|
||||
missing, len(missing))
|
||||
}
|
||||
}
|
||||
|
||||
// TestEveryLeafCommandHasExample enforces that every leaf ships at least one
|
||||
// runnable example — agents learn invocation shape from examples, not prose.
|
||||
func TestEveryLeafCommandHasExample(t *testing.T) {
|
||||
t.Setenv("WEKNORA_AGENT_HELP", "1")
|
||||
root := NewRootCmd(cmdutil.New())
|
||||
|
||||
var missing []string
|
||||
eachLeafCommand(root, func(c *cobra.Command) {
|
||||
if len(renderAgentHelp(t, c).Examples) == 0 {
|
||||
missing = append(missing, c.CommandPath())
|
||||
}
|
||||
})
|
||||
|
||||
sort.Strings(missing)
|
||||
if len(missing) > 0 {
|
||||
t.Errorf("leaf commands missing agent-help Examples (declare AgentHelp.Examples):\n %v\n(%d commands)",
|
||||
missing, len(missing))
|
||||
}
|
||||
}
|
||||
|
||||
+199
-108
@@ -1,12 +1,15 @@
|
||||
// Package api implements the `weknora api` raw HTTP passthrough command.
|
||||
//
|
||||
// Shape: one positional (path) + `-X/--method` flag, default GET (auto-
|
||||
// promoted to POST when a body is supplied via --input). Default raw
|
||||
// response body to stdout; --format json emits a {status, headers, body}
|
||||
// object. Reuses sdk.Client.Raw which already applies tenant + auth headers.
|
||||
// promoted to POST when a body is supplied via -d/--input). Text mode writes
|
||||
// the raw response body to stdout; --format json places the parsed server
|
||||
// response directly under envelope.data (no {status, headers, body} wrapper),
|
||||
// so `--jq '.data...'` projects at the server's own depth. Reuses
|
||||
// sdk.Client.Raw which already applies tenant + auth headers.
|
||||
package api
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"context"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
@@ -31,7 +34,9 @@ var apiFields = []string{"<response-shape-varies>"}
|
||||
|
||||
type Options struct {
|
||||
Method string
|
||||
Input string // --input: file path, "-" for stdin
|
||||
Input string // --input: file path, "-" for stdin
|
||||
Data string // -d/--data: inline JSON body (mutually exclusive with --input)
|
||||
Fields []string // -F/--field: key=value pairs assembled into a JSON object body (mutually exclusive with -d/--input)
|
||||
Yes bool
|
||||
DryRun bool
|
||||
StdinReader io.Reader // overridden by tests; defaults to iostreams.IO.In
|
||||
@@ -51,19 +56,23 @@ func NewCmd(f *cmdutil.Factory) *cobra.Command {
|
||||
cmd := &cobra.Command{
|
||||
Use: "api <path>",
|
||||
Short: "Make a raw API request to the WeKnora server",
|
||||
Long: `Raw HTTP API access. Body via --input <file> or --input - (stdin).
|
||||
Long: `Raw HTTP API access. JSON body via -d/--data (inline) or --input <file>/- (stdin).
|
||||
|
||||
The default method is GET; passing --input auto-promotes it to POST. Use
|
||||
-X/--method to override (any non-empty method is accepted: DELETE / PUT /
|
||||
PATCH / HEAD / OPTIONS / TRACE / custom).
|
||||
The default method is GET; supplying a body (-d or --input) auto-promotes it
|
||||
to POST. Use -X/--method to override (any non-empty method is accepted:
|
||||
DELETE / PUT / PATCH / HEAD / OPTIONS / TRACE / custom).
|
||||
|
||||
Auth, tenant, and request-id headers are applied automatically from the
|
||||
active profile. The response body is written to stdout by default; use
|
||||
--format json to emit a {status, headers, body} envelope.
|
||||
active profile. In text mode (default) the raw server response body is written
|
||||
to stdout. In --format json the parsed server response is placed directly
|
||||
under envelope.data — drill in with --jq '.data...' at the server's own depth
|
||||
(e.g. '.data.data[]' for a list endpoint). Only -X DELETE is confirmation-gated.
|
||||
|
||||
Examples:
|
||||
weknora api /api/v1/knowledge-bases # GET
|
||||
echo '{"name":"foo"}' | weknora api /api/v1/knowledge-bases --input - # POST (auto)
|
||||
weknora api /api/v1/knowledge-bases # GET
|
||||
weknora api /api/v1/knowledge-bases -d '{"name":"foo"}' # POST (auto)
|
||||
weknora api /api/v1/knowledge-bases -F name=foo -F enabled=true # POST, typed body
|
||||
echo '{"name":"foo"}' | weknora api /api/v1/knowledge-bases --input - # POST via stdin
|
||||
weknora api /api/v1/knowledge-bases/kb_xxx -X DELETE`,
|
||||
Args: cobra.ExactArgs(1),
|
||||
RunE: func(c *cobra.Command, args []string) error {
|
||||
@@ -86,14 +95,14 @@ Examples:
|
||||
"--dry-run requires explicit -X POST/PUT/PATCH/DELETE; default GET is read-only with no side effect to preview"))
|
||||
}
|
||||
var body any
|
||||
if opts.Input != "" {
|
||||
contents, err := readInput(opts)
|
||||
if hasBody(opts) {
|
||||
contents, err := resolveBody(opts)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
// Best-effort JSON decode so the plan body surfaces a
|
||||
// structured object (agents grep meta.plan.body for shape);
|
||||
// fall back to raw string when the payload isn't JSON.
|
||||
// Surface the parsed body in the plan so agents can grep
|
||||
// meta.plan.body for shape; resolveBody has already validated
|
||||
// it as JSON.
|
||||
var parsed any
|
||||
if json.Unmarshal(contents, &parsed) == nil {
|
||||
body = parsed
|
||||
@@ -112,9 +121,19 @@ Examples:
|
||||
}
|
||||
method := resolveMethod(opts)
|
||||
// Escape-hatch DELETE through `weknora api` is just as destructive
|
||||
// as `weknora kb delete` - exit-10 protocol must apply (cli/README.md).
|
||||
if method == http.MethodDelete {
|
||||
if err := cmdutil.ConfirmDestructive(f.Prompter(), opts.Yes, fopts.WantsJSON(), "delete", "endpoint", args[0], "api.delete", "weknora api -X DELETE "+args[0]+" -y"); err != nil {
|
||||
// as `weknora kb delete` - exit-10 destructive protocol must apply
|
||||
// (cli/README.md). PUT/PATCH mutate server state like a typed
|
||||
// `kb/agent/doc update`, so they get the same exit-10 WRITE gate;
|
||||
// without it the raw escape hatch bypassed the "an agent cannot
|
||||
// silently mutate" guarantee. POST stays ungated to match typed
|
||||
// `create` (also ungated). GET/HEAD are reads.
|
||||
switch method {
|
||||
case http.MethodDelete:
|
||||
if err := cmdutil.ConfirmDestructive(f.Prompter(), opts.Yes, fopts.WantsJSON(), "delete", "endpoint", args[0], "api.delete", []string{"weknora", "api", "-X", "DELETE", args[0], "-y"}); err != nil {
|
||||
return err
|
||||
}
|
||||
case http.MethodPut, http.MethodPatch:
|
||||
if err := cmdutil.ConfirmWrite(f.Prompter(), opts.Yes, fopts.WantsJSON(), "write", "endpoint", args[0], "api."+strings.ToLower(method), apiRetryArgv(opts, method, args[0])); err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
@@ -126,8 +145,10 @@ Examples:
|
||||
return runAPI(c.Context(), opts, fopts, cli, method, args[0], paginate)
|
||||
},
|
||||
}
|
||||
cmd.Flags().StringVarP(&opts.Method, "method", "X", "", "HTTP method (default: GET, or POST when --input is supplied). Any non-empty method is accepted.")
|
||||
cmd.Flags().StringVar(&opts.Input, "input", "", "Read request body from file (use `-` for stdin)")
|
||||
cmd.Flags().StringVarP(&opts.Method, "method", "X", "", "HTTP method (default: GET, or POST when a body is supplied via -d/--input). Any non-empty method is accepted.")
|
||||
cmd.Flags().StringVarP(&opts.Data, "data", "d", "", "Inline JSON request body (e.g. -d '{\"name\":\"x\"}'). Mutually exclusive with --input.")
|
||||
cmd.Flags().StringVar(&opts.Input, "input", "", "Read JSON request body from file (use `-` for stdin). Mutually exclusive with -d/--data.")
|
||||
cmd.Flags().StringArrayVarP(&opts.Fields, "field", "F", nil, "Add a key=value to a JSON object body (repeatable; e.g. -F name=foo -F enabled=true). true/false/null and numbers are typed; everything else is a string. Flat keys only. Mutually exclusive with -d/--input.")
|
||||
cmd.Flags().Bool("paginate", false, "Follow offset-based pagination (?page=N&page_size=M), merging all pages into a single {data, total} JSON response.")
|
||||
cmdutil.AddFormatFlag(cmd, apiFields...)
|
||||
cmdutil.AddDryRunFlag(cmd, &opts.DryRun)
|
||||
@@ -136,12 +157,15 @@ Examples:
|
||||
RequiredFlags: []string{"path (positional)"},
|
||||
Examples: []string{
|
||||
"weknora api /api/v1/knowledge-bases",
|
||||
"weknora api /api/v1/knowledge-bases -d '{\"name\":\"foo\"}'",
|
||||
"weknora api -X POST /api/v1/knowledge-bases -F name=\"Eng Docs\" -F enabled=true",
|
||||
"weknora api -X DELETE /api/v1/knowledge-bases/kb_x -y",
|
||||
"echo '{\"name\":\"foo\"}' | weknora api -X POST /api/v1/knowledge-bases --input -",
|
||||
"echo '{\"name\":\"foo\"}' | weknora api /api/v1/knowledge-bases --input -",
|
||||
},
|
||||
Output: "raw server response body or envelope on error",
|
||||
Output: "text mode (default): the raw server response body on stdout. json mode: the parsed server response is placed directly under envelope.data — project with --jq '.data...' at the server's own depth (e.g. '.data.data[]' for a list endpoint, '.data.data.id' for a created object). With --paginate, envelope.data is the merged {data, total}.",
|
||||
Warnings: []string{
|
||||
"Only -X DELETE is confirmation-gated (exit 10 / input.confirmation_required unless -y); -X GET/POST/PUT/PATCH and other methods are unguarded — you own the safety of writes made through this escape hatch.",
|
||||
"-X DELETE is destructive-gated and -X PUT/PATCH are write-gated (exit 10 / input.confirmation_required unless -y), matching typed delete/update. -X POST (create-shaped) and GET are unguarded — you own the safety of creates made through this escape hatch.",
|
||||
"Raw passthrough: the typed error envelope does NOT fully apply. The server's own response goes under envelope.data at its native depth; a non-2xx HTTP status surfaces via the exit code, not a typed error.type/retry_argv. Do not rely on error.type/retryable for `api` the way you do for typed subcommands.",
|
||||
"Raw HTTP passthrough; agents should prefer typed subcommands (kb/doc/session/...) when available.",
|
||||
},
|
||||
})
|
||||
@@ -151,37 +175,153 @@ Examples:
|
||||
// readInput reads opts.Input and returns its contents. "-" reads from
|
||||
// opts.StdinReader (or iostreams.IO.In as the production default) for
|
||||
// piped JSON payloads.
|
||||
//
|
||||
// The body is sent as a JSON document (the SDK marshals it as json.RawMessage),
|
||||
// so a non-JSON / malformed payload is validated and rejected here as
|
||||
// input.invalid_argument (exit 5). Without this, the failure surfaced from the
|
||||
// SDK's marshal step as a confusing network.error (exit 7, "retryable") —
|
||||
// looping an agent on a body that can never be sent.
|
||||
func readInput(opts *Options) ([]byte, error) {
|
||||
var b []byte
|
||||
if opts.Input == "-" {
|
||||
r := opts.StdinReader
|
||||
if r == nil {
|
||||
r = iostreams.IO.In
|
||||
}
|
||||
b, err := io.ReadAll(r)
|
||||
var err error
|
||||
b, err = io.ReadAll(r)
|
||||
if err != nil {
|
||||
return nil, cmdutil.Wrapf(cmdutil.CodeLocalFileIO, err, "read request body from stdin")
|
||||
}
|
||||
return b, nil
|
||||
} else {
|
||||
var err error
|
||||
b, err = os.ReadFile(opts.Input)
|
||||
if err != nil {
|
||||
return nil, cmdutil.Wrapf(cmdutil.CodeLocalFileIO, err, "read input file %s", opts.Input)
|
||||
}
|
||||
}
|
||||
b, err := os.ReadFile(opts.Input)
|
||||
if err != nil {
|
||||
return nil, cmdutil.Wrapf(cmdutil.CodeLocalFileIO, err, "read input file %s", opts.Input)
|
||||
if len(bytes.TrimSpace(b)) > 0 && !json.Valid(b) {
|
||||
return nil, cmdutil.NewError(cmdutil.CodeInputInvalidArgument,
|
||||
"--input must be valid JSON (the request body is sent as a JSON document)")
|
||||
}
|
||||
return b, nil
|
||||
}
|
||||
|
||||
// resolveBody returns the request body bytes from -d/--data (inline) or
|
||||
// --input (file/stdin), or nil when neither is set. Inline --data is
|
||||
// validated as JSON here; --input is validated inside readInput. The two
|
||||
// flags are mutually exclusive — checked here (rather than cobra's
|
||||
// MarkFlagsMutuallyExclusive, whose violation surfaces as an unclassified
|
||||
// internal.error / exit 1) so the conflict reports input.invalid_argument.
|
||||
func resolveBody(opts *Options) ([]byte, error) {
|
||||
set := 0
|
||||
if opts.Data != "" {
|
||||
set++
|
||||
}
|
||||
if opts.Input != "" {
|
||||
set++
|
||||
}
|
||||
if len(opts.Fields) > 0 {
|
||||
set++
|
||||
}
|
||||
if set > 1 {
|
||||
return nil, cmdutil.NewError(cmdutil.CodeInputInvalidArgument,
|
||||
"-d/--data, --input, and -F/--field are mutually exclusive; supply the body one way")
|
||||
}
|
||||
if len(opts.Fields) > 0 {
|
||||
return buildFieldBody(opts.Fields)
|
||||
}
|
||||
if opts.Data != "" {
|
||||
if !json.Valid([]byte(opts.Data)) {
|
||||
return nil, cmdutil.NewError(cmdutil.CodeInputInvalidArgument,
|
||||
"-d/--data must be valid JSON (the request body is sent as a JSON document)")
|
||||
}
|
||||
return []byte(opts.Data), nil
|
||||
}
|
||||
if opts.Input != "" {
|
||||
return readInput(opts)
|
||||
}
|
||||
return nil, nil
|
||||
}
|
||||
|
||||
// hasBody reports whether a request body was supplied via -d or --input.
|
||||
func hasBody(opts *Options) bool {
|
||||
return opts.Data != "" || opts.Input != "" || len(opts.Fields) > 0
|
||||
}
|
||||
|
||||
// inferFieldValue maps a -F value string to a typed JSON scalar: literal
|
||||
// true/false/null and integer/float literals become typed JSON; everything
|
||||
// else stays a string. A value that looks numeric but must stay a string
|
||||
// (e.g. a zero-padded id "007") can't be forced here — use -d/--data or
|
||||
// --input for full control.
|
||||
func inferFieldValue(v string) any {
|
||||
switch v {
|
||||
case "true":
|
||||
return true
|
||||
case "false":
|
||||
return false
|
||||
case "null":
|
||||
return nil
|
||||
}
|
||||
if i, err := strconv.ParseInt(v, 10, 64); err == nil {
|
||||
return i
|
||||
}
|
||||
if f, err := strconv.ParseFloat(v, 64); err == nil {
|
||||
return f
|
||||
}
|
||||
return v
|
||||
}
|
||||
|
||||
// buildFieldBody assembles -F/--field key=value pairs into a JSON object with
|
||||
// type inference. Flat keys only. Returns input.invalid_argument (exit 5) for
|
||||
// a malformed pair or an unsupported @file value.
|
||||
func buildFieldBody(fields []string) ([]byte, error) {
|
||||
obj := make(map[string]any, len(fields))
|
||||
for _, f := range fields {
|
||||
k, v, ok := strings.Cut(f, "=")
|
||||
if !ok || k == "" {
|
||||
return nil, cmdutil.NewError(cmdutil.CodeInputInvalidArgument,
|
||||
fmt.Sprintf("-F/--field must be key=value, got %q", f))
|
||||
}
|
||||
if strings.HasPrefix(v, "@") {
|
||||
return nil, cmdutil.NewError(cmdutil.CodeInputInvalidArgument,
|
||||
fmt.Sprintf("-F %q: @file values are not supported; read a file body with --input", f))
|
||||
}
|
||||
obj[k] = inferFieldValue(v)
|
||||
}
|
||||
return json.Marshal(obj)
|
||||
}
|
||||
|
||||
// resolveMethod implements the auto-method behavior: explicit -X wins;
|
||||
// otherwise body presence promotes GET → POST.
|
||||
// otherwise body presence (-d/--data or --input) promotes GET → POST.
|
||||
func resolveMethod(opts *Options) string {
|
||||
if opts.Method != "" {
|
||||
return strings.ToUpper(opts.Method)
|
||||
}
|
||||
if opts.Input != "" {
|
||||
if hasBody(opts) {
|
||||
return "POST"
|
||||
}
|
||||
return "GET"
|
||||
}
|
||||
|
||||
// apiRetryArgv reconstructs a directly-executable `weknora api` argv (with -y)
|
||||
// for the write-confirmation gate, preserving the method, path and body flags
|
||||
// the caller passed so an agent can re-run the exact mutation after approval.
|
||||
func apiRetryArgv(opts *Options, method, path string) []string {
|
||||
argv := []string{"weknora", "api", "-X", method, path}
|
||||
switch {
|
||||
case opts.Data != "":
|
||||
argv = append(argv, "-d", opts.Data)
|
||||
case opts.Input != "":
|
||||
argv = append(argv, "--input", opts.Input)
|
||||
default:
|
||||
for _, f := range opts.Fields {
|
||||
argv = append(argv, "-F", f)
|
||||
}
|
||||
}
|
||||
return append(argv, "-y")
|
||||
}
|
||||
|
||||
// runAPI is the testable core: validate inputs, dispatch via Service.Raw,
|
||||
// classify status, and emit either the raw body or a JSON object. The
|
||||
// caller is responsible for resolving the method (defaults / auto-POST)
|
||||
@@ -207,13 +347,15 @@ func runAPISingle(ctx context.Context, opts *Options, fopts *cmdutil.FormatOptio
|
||||
return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, fmt.Sprintf("path must start with /: %s", path))
|
||||
}
|
||||
|
||||
// Resolve request body from --input (file path or `-` for stdin).
|
||||
// Resolve request body from -d/--data (inline) or --input (file / `-`).
|
||||
// Empty input is treated as no body rather than an empty JSON document
|
||||
// (which fails to marshal).
|
||||
contents, err := resolveBody(opts)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
var body any
|
||||
if opts.Input != "" {
|
||||
contents, err := readInput(opts)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if len(bytes.TrimSpace(contents)) > 0 {
|
||||
body = json.RawMessage(contents)
|
||||
}
|
||||
|
||||
@@ -241,38 +383,31 @@ func runAPISingle(ctx context.Context, opts *Options, fopts *cmdutil.FormatOptio
|
||||
return ce
|
||||
}
|
||||
|
||||
return emitRawBody(respBody, fopts)
|
||||
}
|
||||
|
||||
// emitRawBody writes a server response body under the active format. JSON mode
|
||||
// places the parsed body directly under envelope.data — no {status, headers,
|
||||
// body} wrapper — so `--jq '.data...'` projects at the server's own shape
|
||||
// (e.g. `.data.data[]` for a list endpoint) rather than a triple-nested
|
||||
// `.data.body.data[]`; non-JSON decodes best-effort to a raw string. Text mode
|
||||
// writes the body verbatim with a trailing newline. Shared by the single and
|
||||
// paginated-fallback paths so both project identically.
|
||||
func emitRawBody(body []byte, fopts *cmdutil.FormatOptions) error {
|
||||
out := iostreams.IO.Out
|
||||
if fopts.WantsJSON() {
|
||||
// Best-effort decode: if response body is valid JSON, surface the
|
||||
// parsed structure under .body so JSON consumers can drill
|
||||
// in; otherwise fall back to the raw string.
|
||||
var bodyAny any
|
||||
if len(respBody) > 0 {
|
||||
if err := json.Unmarshal(respBody, &bodyAny); err != nil {
|
||||
bodyAny = string(respBody)
|
||||
if len(body) > 0 {
|
||||
if err := json.Unmarshal(body, &bodyAny); err != nil {
|
||||
bodyAny = string(body)
|
||||
}
|
||||
}
|
||||
hdrs := make(map[string]string, len(resp.Header))
|
||||
for k, v := range resp.Header {
|
||||
if len(v) > 0 {
|
||||
hdrs[k] = v[0]
|
||||
}
|
||||
}
|
||||
// Route through fopts.Emit so the payload lives under .data in the
|
||||
// success envelope. --jq applies to the full envelope, so users
|
||||
// project with ".data.status", ".data.body", etc.
|
||||
payload := map[string]any{
|
||||
"status": resp.StatusCode,
|
||||
"headers": hdrs,
|
||||
"body": bodyAny,
|
||||
}
|
||||
return fopts.Emit(out, payload, nil)
|
||||
return fopts.Emit(out, bodyAny, nil)
|
||||
}
|
||||
|
||||
if _, err := out.Write(respBody); err != nil {
|
||||
if _, err := out.Write(body); err != nil {
|
||||
return cmdutil.Wrapf(cmdutil.CodeLocalFileIO, err, "write response body")
|
||||
}
|
||||
if len(respBody) > 0 && respBody[len(respBody)-1] != '\n' {
|
||||
if len(body) > 0 && body[len(body)-1] != '\n' {
|
||||
_, _ = out.Write([]byte{'\n'})
|
||||
}
|
||||
return nil
|
||||
@@ -320,7 +455,7 @@ func runAPIPaginated(ctx context.Context, opts *Options, fopts *cmdutil.FormatOp
|
||||
if err := json.Unmarshal(body, &pageResp); err != nil {
|
||||
// Non-JSON response on first page — fall back through the envelope.
|
||||
if page == 1 {
|
||||
return passThroughFallback(body, resp, fopts)
|
||||
return emitRawBody(body, fopts)
|
||||
}
|
||||
return cmdutil.NewError(cmdutil.CodeInputInvalidArgument,
|
||||
fmt.Sprintf("--paginate: page %d response not in expected shape: %v", page, err))
|
||||
@@ -329,7 +464,7 @@ func runAPIPaginated(ctx context.Context, opts *Options, fopts *cmdutil.FormatOp
|
||||
// Heuristic: if the first page lacks pagination metadata, treat the
|
||||
// response as non-paginated and fall back through the envelope.
|
||||
if page == 1 && pageResp.Total == 0 && pageResp.PageSize == 0 {
|
||||
return passThroughFallback(body, resp, fopts)
|
||||
return emitRawBody(body, fopts)
|
||||
}
|
||||
|
||||
allData = append(allData, pageResp.Data...)
|
||||
@@ -349,50 +484,6 @@ func runAPIPaginated(ctx context.Context, opts *Options, fopts *cmdutil.FormatOp
|
||||
return fopts.Emit(iostreams.IO.Out, merged, nil)
|
||||
}
|
||||
|
||||
// passThroughFallback handles the case where --paginate detects a
|
||||
// non-paginated first-page response. When JSON output is requested, it routes
|
||||
// the body through fopts.Emit in the same {status, headers, body} envelope
|
||||
// shape that runAPISingle produces — keeping the wire contract consistent
|
||||
// regardless of whether --paginate was passed. For human-readable mode it
|
||||
// writes the raw body verbatim (same as the original passThroughRaw behavior).
|
||||
func passThroughFallback(body []byte, resp *http.Response, fopts *cmdutil.FormatOptions) error {
|
||||
out := iostreams.IO.Out
|
||||
if fopts.WantsJSON() {
|
||||
var bodyAny any
|
||||
if len(body) > 0 {
|
||||
if err := json.Unmarshal(body, &bodyAny); err != nil {
|
||||
bodyAny = string(body) // best-effort string fallback
|
||||
}
|
||||
}
|
||||
hdrs := collectHeaders(resp)
|
||||
return fopts.Emit(out, map[string]any{
|
||||
"status": resp.StatusCode,
|
||||
"headers": hdrs,
|
||||
"body": bodyAny,
|
||||
}, nil)
|
||||
}
|
||||
// Human-readable: raw passthrough, same as before.
|
||||
if _, err := out.Write(body); err != nil {
|
||||
return cmdutil.Wrapf(cmdutil.CodeLocalFileIO, err, "write response body")
|
||||
}
|
||||
if len(body) > 0 && body[len(body)-1] != '\n' {
|
||||
_, _ = out.Write([]byte{'\n'})
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// collectHeaders extracts the first value of each response header into a flat
|
||||
// map, matching the shape that runAPISingle emits in its JSON envelope.
|
||||
func collectHeaders(resp *http.Response) map[string]string {
|
||||
hdrs := make(map[string]string, len(resp.Header))
|
||||
for k, v := range resp.Header {
|
||||
if len(v) > 0 {
|
||||
hdrs[k] = v[0]
|
||||
}
|
||||
}
|
||||
return hdrs
|
||||
}
|
||||
|
||||
// extractPageSize parses the page_size query parameter from path, returning 0
|
||||
// if absent or unparseable.
|
||||
func extractPageSize(path string) int {
|
||||
|
||||
@@ -125,3 +125,75 @@ func TestApi_DryRunWithPost_EmitsPlan(t *testing.T) {
|
||||
require.True(t, ok, "plan.body must be a JSON object when --input is valid JSON, got %T", env.Meta.Plan["body"])
|
||||
assert.Equal(t, "foo", body["name"])
|
||||
}
|
||||
|
||||
// TestApi_FieldBody_TypedDryRun: -F/--field builds a typed JSON object body —
|
||||
// true/false/null and numbers are typed, everything else stays a string — and
|
||||
// the resolved body is surfaced in the dry-run plan for agent inspection.
|
||||
func TestApi_FieldBody_TypedDryRun(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
root := withRootHarness(NewCmd(apiDryRunFactory(t)),
|
||||
"/api/v1/x", "-X", "POST",
|
||||
"-F", "name=Hello", "-F", "enabled=true", "-F", "count=3",
|
||||
"-F", "ratio=1.5", "-F", "empty=null",
|
||||
"--dry-run", "--format", "json")
|
||||
require.NoError(t, root.Execute(), "-F + --dry-run must succeed without SDK")
|
||||
|
||||
var env struct {
|
||||
Meta struct {
|
||||
Plan map[string]any `json:"plan"`
|
||||
} `json:"meta"`
|
||||
}
|
||||
require.NoError(t, json.Unmarshal(out.Bytes(), &env), "envelope: %q", out.String())
|
||||
body, ok := env.Meta.Plan["body"].(map[string]any)
|
||||
require.True(t, ok, "plan.body must be a JSON object, got %T", env.Meta.Plan["body"])
|
||||
assert.Equal(t, "Hello", body["name"], "non-numeric stays string")
|
||||
assert.Equal(t, true, body["enabled"], "true -> JSON bool")
|
||||
assert.Equal(t, float64(3), body["count"], "integer -> JSON number")
|
||||
assert.Equal(t, 1.5, body["ratio"], "float -> JSON number")
|
||||
assert.Nil(t, body["empty"], "null -> JSON null")
|
||||
}
|
||||
|
||||
// TestApi_FieldBody_AutoPromotesPost: -F on its own (no -X) auto-promotes
|
||||
// GET -> POST, matching -d/--input body behavior.
|
||||
func TestApi_FieldBody_AutoPromotesPost(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
root := withRootHarness(NewCmd(apiDryRunFactory(t)),
|
||||
"/api/v1/x", "-F", "a=b", "--dry-run", "--format", "json")
|
||||
require.NoError(t, root.Execute())
|
||||
var env struct {
|
||||
Meta struct {
|
||||
Plan map[string]any `json:"plan"`
|
||||
} `json:"meta"`
|
||||
}
|
||||
require.NoError(t, json.Unmarshal(out.Bytes(), &env))
|
||||
assert.Equal(t, "POST", env.Meta.Plan["method"], "-F must auto-promote GET -> POST")
|
||||
}
|
||||
|
||||
// TestApi_FieldBody_ConflictsWithData: -F and -d are mutually exclusive — the
|
||||
// conflict is reported as input.invalid_argument (exit 5), consistent with the
|
||||
// existing -d/--input conflict.
|
||||
func TestApi_FieldBody_ConflictsWithData(t *testing.T) {
|
||||
iostreams.SetForTest(t)
|
||||
root := withRootHarness(NewCmd(apiDryRunFactory(t)),
|
||||
"/api/v1/x", "-X", "POST", "-F", "a=b", "-d", "{}", "--dry-run", "--format", "json")
|
||||
err := root.Execute()
|
||||
require.Error(t, err, "-F + -d must conflict")
|
||||
var ce *cmdutil.Error
|
||||
require.ErrorAs(t, err, &ce)
|
||||
assert.Equal(t, cmdutil.CodeInputInvalidArgument, ce.Code)
|
||||
assert.Equal(t, 5, cmdutil.ExitCode(err))
|
||||
}
|
||||
|
||||
// TestApi_FieldBody_Malformed: a -F value without '=' (or empty key) is a typed
|
||||
// input error, not a panic or a silently-dropped field.
|
||||
func TestApi_FieldBody_Malformed(t *testing.T) {
|
||||
iostreams.SetForTest(t)
|
||||
root := withRootHarness(NewCmd(apiDryRunFactory(t)),
|
||||
"/api/v1/x", "-X", "POST", "-F", "nope", "--dry-run", "--format", "json")
|
||||
err := root.Execute()
|
||||
require.Error(t, err)
|
||||
var ce *cmdutil.Error
|
||||
require.ErrorAs(t, err, &ce)
|
||||
assert.Equal(t, cmdutil.CodeInputInvalidArgument, ce.Code)
|
||||
assert.Contains(t, err.Error(), "key=value")
|
||||
}
|
||||
|
||||
+138
-26
@@ -78,14 +78,12 @@ func TestAPI_GetSuccess_JSON(t *testing.T) {
|
||||
if err := runAPI(context.Background(), &Options{}, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, cli, "GET", "/api/v1/foo", false); err != nil {
|
||||
t.Fatalf("runAPI: %v", err)
|
||||
}
|
||||
// v0.7 envelope: {ok:true, data:{status, headers, body}}
|
||||
// The server response is passed through directly under envelope.data — no
|
||||
// {status, headers, body} wrapper — so consumers project at the server's
|
||||
// own depth (e.g. .data.value here).
|
||||
var env struct {
|
||||
OK bool `json:"ok"`
|
||||
Data struct {
|
||||
Status int `json:"status"`
|
||||
Headers map[string]string `json:"headers"`
|
||||
Body map[string]any `json:"body"`
|
||||
} `json:"data"`
|
||||
OK bool `json:"ok"`
|
||||
Data map[string]any `json:"data"`
|
||||
}
|
||||
if err := json.Unmarshal(out.Bytes(), &env); err != nil {
|
||||
t.Fatalf("decode envelope JSON: %v\n%s", err, out.String())
|
||||
@@ -93,15 +91,55 @@ func TestAPI_GetSuccess_JSON(t *testing.T) {
|
||||
if !env.OK {
|
||||
t.Errorf("envelope ok: want true, got false")
|
||||
}
|
||||
got := env.Data
|
||||
if got.Status != 200 {
|
||||
t.Errorf("status: want 200, got %d", got.Status)
|
||||
if v, ok := env.Data["value"]; !ok || v.(float64) != 42 {
|
||||
t.Errorf("data.value: want 42 directly under .data (no .body nesting), got %v", env.Data)
|
||||
}
|
||||
if got.Headers["Content-Type"] != "application/json" {
|
||||
t.Errorf("Content-Type header missing: %v", got.Headers)
|
||||
}
|
||||
|
||||
// TestAPI_InlineDataBody verifies -d/--data sends an inline JSON body and
|
||||
// auto-promotes the method to POST.
|
||||
func TestAPI_InlineDataBody(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
var seenBody []byte
|
||||
var seenMethod string
|
||||
cli, stop := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
seenMethod = r.Method
|
||||
seenBody, _ = io.ReadAll(r.Body)
|
||||
_, _ = w.Write([]byte(`{"id":"new"}`))
|
||||
})
|
||||
defer stop()
|
||||
|
||||
opts := &Options{Data: `{"name":"foo"}`}
|
||||
if err := runAPI(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, cli, resolveMethod(opts), "/api/v1/things", false); err != nil {
|
||||
t.Fatalf("runAPI: %v", err)
|
||||
}
|
||||
if v, ok := got.Body["value"]; !ok || v.(float64) != 42 {
|
||||
t.Errorf("body.value: want 42, got %v", got.Body)
|
||||
if seenMethod != http.MethodPost {
|
||||
t.Errorf("inline -d should auto-promote to POST, got %s", seenMethod)
|
||||
}
|
||||
if string(seenBody) != `{"name":"foo"}` {
|
||||
t.Errorf("server received body %q, want the inline --data JSON", seenBody)
|
||||
}
|
||||
}
|
||||
|
||||
// TestAPI_InlineDataMalformed_RejectedAsInput pins that a malformed -d body is
|
||||
// rejected as input.invalid_argument before any request.
|
||||
func TestAPI_InlineDataMalformed_RejectedAsInput(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
called := false
|
||||
cli, stop := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
called = true
|
||||
_, _ = w.Write([]byte(`{}`))
|
||||
})
|
||||
defer stop()
|
||||
|
||||
opts := &Options{Data: `{bad`}
|
||||
err := runAPI(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, cli, "POST", "/api/v1/things", false)
|
||||
var typed *cmdutil.Error
|
||||
if !errors.As(err, &typed) || typed.Code != cmdutil.CodeInputInvalidArgument {
|
||||
t.Errorf("want input.invalid_argument for malformed -d, got %v", err)
|
||||
}
|
||||
if called {
|
||||
t.Error("server must not be called with a malformed inline body")
|
||||
}
|
||||
}
|
||||
|
||||
@@ -130,6 +168,33 @@ func TestAPI_PostWithStdinInput(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// TestAPI_MalformedInputJSON_RejectedAsInput pins that a non-JSON --input body
|
||||
// is rejected with input.invalid_argument (exit 5) at the boundary, not the
|
||||
// confusing network.error (exit 7, "retryable") the SDK's marshal step
|
||||
// produced. The server must never be called.
|
||||
func TestAPI_MalformedInputJSON_RejectedAsInput(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
called := false
|
||||
cli, stop := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
called = true
|
||||
_, _ = w.Write([]byte(`{}`))
|
||||
})
|
||||
defer stop()
|
||||
|
||||
opts := &Options{Input: "-", StdinReader: strings.NewReader(`{bad json`)}
|
||||
err := runAPI(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, cli, "POST", "/api/v1/things", false)
|
||||
if err == nil {
|
||||
t.Fatal("expected an error for malformed --input JSON")
|
||||
}
|
||||
var typed *cmdutil.Error
|
||||
if !errors.As(err, &typed) || typed.Code != cmdutil.CodeInputInvalidArgument {
|
||||
t.Errorf("want input.invalid_argument, got %v", err)
|
||||
}
|
||||
if called {
|
||||
t.Error("server must not be called with a malformed body")
|
||||
}
|
||||
}
|
||||
|
||||
// TestAPI_InputFile verifies --input <file> reads the request body from disk.
|
||||
func TestAPI_InputFile(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
@@ -418,14 +483,12 @@ func TestAPI_PaginateNoMetadataPassesThrough(t *testing.T) {
|
||||
if called != 1 {
|
||||
t.Errorf("called %d times, want 1 (non-paginated response)", called)
|
||||
}
|
||||
// H3a: fallback must produce an envelope, not raw passthrough.
|
||||
// The non-paginated fallback must emit the SAME flat shape as a single
|
||||
// call: the server response directly under .data (no {status,headers,body}
|
||||
// wrapper), so --paginate and single-call project identically.
|
||||
var env struct {
|
||||
OK bool `json:"ok"`
|
||||
Data struct {
|
||||
Status int `json:"status"`
|
||||
Headers map[string]string `json:"headers"`
|
||||
Body map[string]any `json:"body"`
|
||||
} `json:"data"`
|
||||
OK bool `json:"ok"`
|
||||
Data map[string]any `json:"data"`
|
||||
}
|
||||
if err := json.Unmarshal(out.Bytes(), &env); err != nil {
|
||||
t.Fatalf("non-paginated fallback must emit envelope JSON, unmarshal failed: %v\n%s", err, out.String())
|
||||
@@ -433,11 +496,8 @@ func TestAPI_PaginateNoMetadataPassesThrough(t *testing.T) {
|
||||
if !env.OK {
|
||||
t.Errorf("envelope ok: want true, got false")
|
||||
}
|
||||
if env.Data.Status != 200 {
|
||||
t.Errorf("envelope data.status: want 200, got %d", env.Data.Status)
|
||||
}
|
||||
if v, ok := env.Data.Body["hello"]; !ok || v.(string) != "world" {
|
||||
t.Errorf("envelope data.body: want {hello:world}, got %v", env.Data.Body)
|
||||
if v, ok := env.Data["hello"]; !ok || v.(string) != "world" {
|
||||
t.Errorf("fallback must pass the body through flat under .data (.data.hello), got %v", env.Data)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -491,3 +551,55 @@ func TestAPI_PaginateServerCapsPageSize(t *testing.T) {
|
||||
t.Errorf("got %d records, want 5 (server-capped page_size should not cause truncation)", len(got.Data))
|
||||
}
|
||||
}
|
||||
|
||||
// TestAPI_PUT_RequiresConfirmation pins the exit-10 write gate on the
|
||||
// escape-hatch PUT path: `weknora api -X PUT /...` mutates server state the
|
||||
// same way a typed `kb update` does, so it must require -y (exit 10) rather
|
||||
// than silently writing. Regression: only DELETE was gated, letting an agent
|
||||
// bypass the write-confirmation protocol via raw PUT/PATCH.
|
||||
func TestAPI_PUT_RequiresConfirmation(t *testing.T) {
|
||||
for _, method := range []string{"PUT", "PATCH"} {
|
||||
t.Run(method, func(t *testing.T) {
|
||||
iostreams.SetForTest(t) // non-TTY
|
||||
f := &cmdutil.Factory{
|
||||
Client: func() (*sdk.Client, error) { return nil, nil },
|
||||
Prompter: func() prompt.Prompter { return prompt.AgentPrompter{} },
|
||||
}
|
||||
root := withRootHarness(NewCmd(f), "/api/v1/knowledge-bases/kb_xxx", "-X", method, "-F", "name=x")
|
||||
err := root.Execute()
|
||||
if err == nil {
|
||||
t.Fatalf("expected confirmation_required for %s without -y", method)
|
||||
}
|
||||
var ce *cmdutil.Error
|
||||
if !asTypedError(err, &ce) || ce.Code != cmdutil.CodeInputConfirmationRequired {
|
||||
t.Errorf("want input.confirmation_required, got %v", err)
|
||||
}
|
||||
if got := cmdutil.ExitCode(err); got != 10 {
|
||||
t.Errorf("exit code = %d, want 10", got)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// TestAPI_POST_NotGated: POST is create-shaped and, like typed `kb create`,
|
||||
// intentionally ungated — it must reach the SDK without a confirmation gate.
|
||||
func TestAPI_POST_NotGated(t *testing.T) {
|
||||
iostreams.SetForTest(t)
|
||||
called := false
|
||||
cli, stop := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
called = true
|
||||
w.WriteHeader(http.StatusOK)
|
||||
})
|
||||
defer stop()
|
||||
f := &cmdutil.Factory{
|
||||
Client: func() (*sdk.Client, error) { return cli, nil },
|
||||
Prompter: func() prompt.Prompter { return prompt.AgentPrompter{} },
|
||||
}
|
||||
root := withRootHarness(NewCmd(f), "/api/v1/knowledge-bases", "-X", "POST", "-F", "name=x")
|
||||
if err := root.Execute(); err != nil {
|
||||
t.Fatalf("execute: %v", err)
|
||||
}
|
||||
if !called {
|
||||
t.Error("POST handler not called - POST must not be gated")
|
||||
}
|
||||
}
|
||||
|
||||
@@ -74,7 +74,7 @@ func runList(fopts *cmdutil.FormatOptions, f *cmdutil.Factory) error {
|
||||
sort.Slice(entries, func(i, j int) bool { return entries[i].Name < entries[j].Name })
|
||||
|
||||
if fopts.WantsJSON() {
|
||||
meta := &output.Meta{Count: len(entries)}
|
||||
meta := &output.Meta{Count: output.IntPtr(len(entries))}
|
||||
return fopts.Emit(iostreams.IO.Out, entries, meta)
|
||||
}
|
||||
if len(entries) == 0 {
|
||||
|
||||
+17
-10
@@ -20,7 +20,7 @@ import (
|
||||
// keyring; agents who need to verify the credential should re-run
|
||||
// `auth status`.
|
||||
var authLoginFields = []string{
|
||||
"profile", "host", "mode", "user", "tenant_id",
|
||||
"profile", "host", "mode", "email", "tenant_id",
|
||||
}
|
||||
|
||||
// LoginOptions is the configuration captured from flags + prompts. Host and
|
||||
@@ -104,7 +104,7 @@ Credentials are persisted to the OS keyring when available; otherwise to a
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "authenticate the active profile; --with-token reads an API key from stdin (non-interactive)",
|
||||
Examples: []string{`echo "$WEKNORA_API_KEY" | weknora auth login --with-token`},
|
||||
Output: "envelope.data is {profile, host, mode, user, tenant_id} on success",
|
||||
Output: "envelope.data is {profile, host, mode, email, tenant_id} on success (email matches `auth status`)",
|
||||
Warnings: []string{
|
||||
"a profile must exist and be active first (`weknora profile add <n> --host <url> --use`)",
|
||||
"password login is interactive-only (no flags) — agents must use --with-token with the key piped to stdin",
|
||||
@@ -128,8 +128,12 @@ func resolveActiveProfile(f *cmdutil.Factory) (name, host string, err error) {
|
||||
}
|
||||
active := cfg.CurrentProfile
|
||||
if active == "" {
|
||||
return "", "", cmdutil.NewError(cmdutil.CodeAuthUnauthenticated,
|
||||
"no active profile; run `weknora profile add <name> --host <h> --use` first")
|
||||
msg := "no active profile; run `weknora profile add <name> --host <h> --use` first"
|
||||
if envActive, kind := cmdutil.EnvCredential(); envActive {
|
||||
msg = "no active profile to log in — you are already authenticated this session via " + kind +
|
||||
"; `auth login` only persists a named profile, so run `weknora profile add <name> --host <h> --use` first if you want one"
|
||||
}
|
||||
return "", "", cmdutil.NewError(cmdutil.CodeAuthUnauthenticated, msg)
|
||||
}
|
||||
prof, ok := cfg.Profiles[active]
|
||||
if !ok {
|
||||
@@ -171,7 +175,7 @@ func runLogin(ctx context.Context, opts *LoginOptions, fopts *cmdutil.FormatOpti
|
||||
}
|
||||
// Reject shell-metacharacter / path-like names up-front so opts.Profile
|
||||
// stays safe to interpolate into the keyring namespace, config.yaml
|
||||
// keys, and (later) envelope.error.retry_command. Matches `profile add`.
|
||||
// keys, and envelope.error.retry_argv. Matches `profile add`.
|
||||
if err := cmdutil.ValidateProfileName(opts.Profile); err != nil {
|
||||
return err
|
||||
}
|
||||
@@ -310,10 +314,13 @@ func applyUser(prof *config.Profile, user *sdk.AuthUser) {
|
||||
// loginResult is the typed payload emitted by `--format json`. mode is derived from
|
||||
// whether the server returned a user (password flow) vs API-key flow.
|
||||
type loginResult struct {
|
||||
Profile string `json:"profile"`
|
||||
Host string `json:"host"`
|
||||
Mode string `json:"mode"` // ModeBearer or ModeAPIKey
|
||||
User string `json:"user,omitempty"`
|
||||
Profile string `json:"profile"`
|
||||
Host string `json:"host"`
|
||||
Mode string `json:"mode"` // ModeBearer or ModeAPIKey
|
||||
// Email is the authenticated principal's email. Named "email" (not
|
||||
// "user") so the identity field matches `auth status`, which also
|
||||
// exposes it as `email` — one key for one concept across both commands.
|
||||
Email string `json:"email,omitempty"`
|
||||
TenantID uint64 `json:"tenant_id,omitempty"`
|
||||
}
|
||||
|
||||
@@ -344,7 +351,7 @@ func saveProfileRef(opts *LoginOptions, fopts *cmdutil.FormatOptions, f *cmdutil
|
||||
// user != nil would mislabel it as bearer.
|
||||
result := loginResult{Profile: opts.Profile, Host: opts.Host, Mode: mode}
|
||||
if user != nil {
|
||||
result.User = user.Email
|
||||
result.Email = user.Email
|
||||
result.TenantID = user.TenantID
|
||||
}
|
||||
return fopts.Emit(iostreams.IO.Out, result, nil)
|
||||
|
||||
+21
-11
@@ -61,6 +61,10 @@ accepted until it expires.`,
|
||||
return cfgErr
|
||||
}
|
||||
if len(cfg.Profiles) == 0 {
|
||||
if active, kind := cmdutil.EnvCredential(); active {
|
||||
return cmdutil.NewError(cmdutil.CodeAuthUnauthenticated,
|
||||
"authenticated via "+kind+" (stateless env credential) — nothing is stored to log out; unset "+kind+" to drop it")
|
||||
}
|
||||
return cmdutil.NewError(cmdutil.CodeAuthUnauthenticated, "no profiles configured; nothing to log out")
|
||||
}
|
||||
if _, err := pickLogoutTargets(opts, cfg); err != nil {
|
||||
@@ -86,12 +90,13 @@ accepted until it expires.`,
|
||||
cmdutil.AddDryRunFlag(cmd, &opts.DryRun)
|
||||
cmdutil.SetRisk(cmd, "auth.logout")
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "clear stored credentials for the active profile (or all) and remove the profile from config",
|
||||
UsedFor: "clear stored credentials for the active profile (or --all); the profile itself stays registered (host preserved) so `auth login` can re-auth it — use `profile remove` to delete the profile entirely",
|
||||
Examples: []string{
|
||||
"weknora auth logout",
|
||||
"weknora --profile staging auth logout",
|
||||
"weknora auth logout --all",
|
||||
},
|
||||
Output: "envelope.data is {removed: [profile names cleared]}",
|
||||
Warnings: []string{
|
||||
"Requires explicit user approval (exit 10 / input.confirmation_required); never auto-add -y.",
|
||||
"auth logout clears local credentials for this profile; server-side session continues until expiry.",
|
||||
@@ -106,6 +111,10 @@ func runLogout(opts *LogoutOptions, fopts *cmdutil.FormatOptions, f *cmdutil.Fac
|
||||
return err
|
||||
}
|
||||
if len(cfg.Profiles) == 0 {
|
||||
if active, kind := cmdutil.EnvCredential(); active {
|
||||
return cmdutil.NewError(cmdutil.CodeAuthUnauthenticated,
|
||||
"authenticated via "+kind+" (stateless env credential) — nothing is stored to log out; unset "+kind+" to drop it")
|
||||
}
|
||||
return cmdutil.NewError(cmdutil.CodeAuthUnauthenticated, "no profiles configured; nothing to log out")
|
||||
}
|
||||
|
||||
@@ -116,9 +125,9 @@ func runLogout(opts *LogoutOptions, fopts *cmdutil.FormatOptions, f *cmdutil.Fac
|
||||
|
||||
// Destructive-write protocol: confirm before clearing credentials.
|
||||
scope := fmt.Sprintf("%d profile(s) [%s]", len(targets), strings.Join(targets, ", "))
|
||||
retryCmd := "weknora auth logout -y"
|
||||
retryCmd := []string{"weknora", "auth", "logout", "-y"}
|
||||
if opts.All {
|
||||
retryCmd = "weknora auth logout --all -y"
|
||||
retryCmd = []string{"weknora", "auth", "logout", "--all", "-y"}
|
||||
}
|
||||
if err := cmdutil.ConfirmDestructive(f.Prompter(), opts.Yes, fopts.WantsJSON(), "delete", "auth credentials", scope, "auth.logout", retryCmd); err != nil {
|
||||
return err
|
||||
@@ -130,14 +139,15 @@ func runLogout(opts *LogoutOptions, fopts *cmdutil.FormatOptions, f *cmdutil.Fac
|
||||
}
|
||||
for _, name := range targets {
|
||||
clearProfileSecrets(store, cfg.Profiles[name], name)
|
||||
delete(cfg.Profiles, name)
|
||||
}
|
||||
// If we removed the active profile, pick a remaining one (deterministic by
|
||||
// map order would be flaky - leave CurrentProfile empty so the next
|
||||
// invocation surfaces a clear "no current profile" error rather than
|
||||
// silently switching).
|
||||
if _, stillExists := cfg.Profiles[cfg.CurrentProfile]; !stillExists {
|
||||
cfg.CurrentProfile = ""
|
||||
// Keep the profile registered (its host stays) — only clear the
|
||||
// credential refs so it reads as logged-out and can be re-authed with
|
||||
// `auth login`. Deleting the profile entirely is `profile remove`'s job;
|
||||
// that clean logout(who)/remove(what) split matches gh / lark.
|
||||
p := cfg.Profiles[name]
|
||||
p.APIKeyRef = ""
|
||||
p.TokenRef = ""
|
||||
p.RefreshRef = ""
|
||||
cfg.Profiles[name] = p
|
||||
}
|
||||
if err := config.Save(cfg); err != nil {
|
||||
return cmdutil.Wrapf(cmdutil.CodeLocalFileIO, err, "save config")
|
||||
|
||||
@@ -48,8 +48,12 @@ func TestLogout_CurrentProfile(t *testing.T) {
|
||||
}
|
||||
require.NoError(t, runLogout(&LogoutOptions{Yes: true}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, newLogoutFactory(t, cfg, store)))
|
||||
|
||||
assert.Empty(t, cfg.CurrentProfile, "current_profile should clear when removed")
|
||||
assert.NotContains(t, cfg.Profiles, "prod")
|
||||
assert.Equal(t, "prod", cfg.CurrentProfile, "active profile stays selected — logout clears creds, not the profile")
|
||||
require.Contains(t, cfg.Profiles, "prod", "profile stays registered after logout")
|
||||
assert.Empty(t, cfg.Profiles["prod"].APIKeyRef, "credential ref cleared")
|
||||
assert.Empty(t, cfg.Profiles["prod"].TokenRef, "credential ref cleared")
|
||||
assert.Empty(t, cfg.Profiles["prod"].RefreshRef, "credential ref cleared")
|
||||
assert.Equal(t, "https://prod", cfg.Profiles["prod"].Host, "host preserved for re-login")
|
||||
assert.Contains(t, cfg.Profiles, "staging", "non-target profile untouched")
|
||||
|
||||
// Secrets gone for the removed profile, kept for the survivor.
|
||||
@@ -81,7 +85,8 @@ func TestLogout_ActiveProfileViaOverride(t *testing.T) {
|
||||
}
|
||||
require.NoError(t, runLogout(&LogoutOptions{Yes: true}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, newLogoutFactory(t, cfg, store)))
|
||||
|
||||
assert.NotContains(t, cfg.Profiles, "staging", "active profile (staging) is the target")
|
||||
require.Contains(t, cfg.Profiles, "staging", "target profile stays registered (creds cleared, not removed)")
|
||||
assert.Empty(t, cfg.Profiles["staging"].APIKeyRef, "target's credential ref cleared")
|
||||
assert.Contains(t, cfg.Profiles, "prod", "non-target profile untouched")
|
||||
}
|
||||
|
||||
@@ -98,8 +103,14 @@ func TestLogout_All(t *testing.T) {
|
||||
}
|
||||
require.NoError(t, runLogout(&LogoutOptions{All: true, Yes: true}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, newLogoutFactory(t, cfg, store)))
|
||||
|
||||
assert.Empty(t, cfg.Profiles)
|
||||
assert.Empty(t, cfg.CurrentProfile)
|
||||
// --all clears every profile's credentials but keeps the profiles registered.
|
||||
require.NotEmpty(t, cfg.Profiles, "profiles stay registered after logout --all")
|
||||
for name, p := range cfg.Profiles {
|
||||
assert.Empty(t, p.APIKeyRef, "%s api-key ref cleared", name)
|
||||
assert.Empty(t, p.TokenRef, "%s token ref cleared", name)
|
||||
assert.Empty(t, p.RefreshRef, "%s refresh ref cleared", name)
|
||||
}
|
||||
assert.Equal(t, "prod", cfg.CurrentProfile, "active selection is preserved; logout clears creds, not the profile")
|
||||
}
|
||||
|
||||
func TestLogout_NoProfiles(t *testing.T) {
|
||||
|
||||
@@ -62,6 +62,10 @@ refresh semantic. Rotate the key in the server UI instead.`,
|
||||
}
|
||||
name := cfg.CurrentProfile
|
||||
if name == "" {
|
||||
if active, kind := cmdutil.EnvCredential(); active {
|
||||
return cmdutil.NewError(cmdutil.CodeInputInvalidArgument,
|
||||
"authenticated via "+kind+" (stateless env credential): there is no stored JWT to refresh — env credentials are supplied fresh each call, so no refresh is needed")
|
||||
}
|
||||
return cmdutil.NewError(cmdutil.CodeAuthUnauthenticated,
|
||||
"no active profile configured; run `weknora auth login` to set one up")
|
||||
}
|
||||
@@ -99,6 +103,10 @@ refresh semantic. Rotate the key in the server UI instead.`,
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "Renew the JWT access token for the active profile (override with the global --profile) using the stored refresh token. API-key profiles are rejected.",
|
||||
Output: "envelope.data has profile name that was refreshed",
|
||||
Examples: []string{
|
||||
"weknora auth refresh",
|
||||
"weknora --profile staging auth refresh",
|
||||
},
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
@@ -117,6 +125,10 @@ func runRefresh(ctx context.Context, opts *RefreshOptions, fopts *cmdutil.Format
|
||||
}
|
||||
name := cfg.CurrentProfile
|
||||
if name == "" {
|
||||
if active, kind := cmdutil.EnvCredential(); active {
|
||||
return cmdutil.NewError(cmdutil.CodeInputInvalidArgument,
|
||||
"authenticated via "+kind+" (stateless env credential): there is no stored JWT to refresh — env credentials are supplied fresh each call, so no refresh is needed")
|
||||
}
|
||||
return cmdutil.NewError(cmdutil.CodeAuthUnauthenticated,
|
||||
"no active profile configured; run `weknora auth login` to set one up")
|
||||
}
|
||||
|
||||
+26
-9
@@ -3,6 +3,8 @@ package auth
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"os"
|
||||
"strings"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
|
||||
@@ -14,7 +16,7 @@ import (
|
||||
// authStatusFields enumerates the fields surfaced for `--format json` discovery
|
||||
// on `auth status`. Single-resource shape: filter applies to data itself.
|
||||
var authStatusFields = []string{
|
||||
"profile", "user_id", "username", "email", "is_active",
|
||||
"profile", "host", "auth_source", "user_id", "username", "email", "is_active",
|
||||
"can_access_all_tenants", "tenant_id", "tenant_name",
|
||||
}
|
||||
|
||||
@@ -29,6 +31,8 @@ type StatusService interface {
|
||||
// account) without a second round-trip.
|
||||
type statusResult struct {
|
||||
Profile string `json:"profile"`
|
||||
Host string `json:"host,omitempty"`
|
||||
AuthSource string `json:"auth_source,omitempty"`
|
||||
UserID string `json:"user_id,omitempty"`
|
||||
Username string `json:"username,omitempty"`
|
||||
Email string `json:"email,omitempty"`
|
||||
@@ -68,7 +72,7 @@ usually only surfaces a hard auth failure.`,
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "show the active profile, the authenticated principal, and token state",
|
||||
Examples: []string{"weknora auth status", "weknora auth status --jq .data.tenant_id"},
|
||||
Output: "envelope.data is {profile, host, user, tenant, ...}; exit 3 if unauthenticated",
|
||||
Output: "envelope.data is {profile, host, auth_source, user_id, username, email, tenant_id, tenant_name, ...}; auth_source is 'profile + keyring' or a stateless env credential; exit 3 if unauthenticated",
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
@@ -89,8 +93,24 @@ func runStatus(ctx context.Context, fopts *cmdutil.FormatOptions, f *cmdutil.Fac
|
||||
return err
|
||||
}
|
||||
|
||||
// Effective host + auth source. Stateless env credentials
|
||||
// (WEKNORA_TOKEN/WEKNORA_API_KEY) override the profile + keyring for the
|
||||
// client, so report the host they authenticate against (WEKNORA_HOST) and
|
||||
// that they are in effect — not the bypassed config profile's host.
|
||||
host := ""
|
||||
if c, ok := cfg.Profiles[cfg.CurrentProfile]; ok {
|
||||
host = c.Host
|
||||
}
|
||||
authSource := "profile + keyring"
|
||||
if active, kind := cmdutil.EnvCredential(); active {
|
||||
authSource = kind + " env (stateless)"
|
||||
if h := strings.TrimSpace(os.Getenv("WEKNORA_HOST")); h != "" {
|
||||
host = h
|
||||
}
|
||||
}
|
||||
|
||||
if fopts.WantsJSON() {
|
||||
result := statusResult{Profile: cfg.CurrentProfile}
|
||||
result := statusResult{Profile: cfg.CurrentProfile, Host: host, AuthSource: authSource}
|
||||
if user != nil {
|
||||
result.UserID = user.ID
|
||||
result.Username = user.Username
|
||||
@@ -105,12 +125,9 @@ func runStatus(ctx context.Context, fopts *cmdutil.FormatOptions, f *cmdutil.Fac
|
||||
return fopts.Emit(iostreams.IO.Out, result, nil)
|
||||
}
|
||||
|
||||
host := ""
|
||||
if c, ok := cfg.Profiles[cfg.CurrentProfile]; ok {
|
||||
host = c.Host
|
||||
}
|
||||
fmt.Fprintf(iostreams.IO.Out, "profile: %s\n", cfg.CurrentProfile)
|
||||
fmt.Fprintf(iostreams.IO.Out, "host: %s\n", host)
|
||||
fmt.Fprintf(iostreams.IO.Out, "profile: %s\n", cfg.CurrentProfile)
|
||||
fmt.Fprintf(iostreams.IO.Out, "auth_source: %s\n", authSource)
|
||||
fmt.Fprintf(iostreams.IO.Out, "host: %s\n", host)
|
||||
if user != nil {
|
||||
fmt.Fprintf(iostreams.IO.Out, "user: %s (%s)\n", user.Email, user.ID)
|
||||
fmt.Fprintf(iostreams.IO.Out, "tenant: %d", user.TenantID)
|
||||
|
||||
@@ -54,8 +54,9 @@ func TestRunStatus_TextOutput(t *testing.T) {
|
||||
}
|
||||
require.NoError(t, runStatus(context.Background(), &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, f, svc))
|
||||
got := out.String()
|
||||
assert.Contains(t, got, "profile: prod")
|
||||
assert.Contains(t, got, "host: https://kb.example.com")
|
||||
assert.Contains(t, got, "profile: prod")
|
||||
assert.Contains(t, got, "auth_source: profile + keyring")
|
||||
assert.Contains(t, got, "host: https://kb.example.com")
|
||||
assert.Contains(t, got, "alice@example.com")
|
||||
assert.Contains(t, got, "Acme")
|
||||
}
|
||||
|
||||
+26
-5
@@ -2,6 +2,7 @@ package auth
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"os"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
|
||||
@@ -57,9 +58,9 @@ to see which mode each profile uses, and construct the matching HTTP header:
|
||||
}
|
||||
// `auth token` is a scalar scripting helper (WEKNORA_TOKEN=$(...)),
|
||||
// so it defaults to the raw token — overriding the global json
|
||||
// default (gh auth token does the same; cf. doc download streaming
|
||||
// raw bytes). Explicit --format json / WEKNORA_FORMAT=json still
|
||||
// emit the {token,mode,profile} envelope.
|
||||
// default, the same way `doc download` streams raw bytes. Explicit
|
||||
// --format json / WEKNORA_FORMAT=json still emit the
|
||||
// {token,mode,profile} envelope.
|
||||
fopts.FromEnv()
|
||||
if fopts.Mode == "" {
|
||||
// --jq implies JSON (it filters the envelope); without it,
|
||||
@@ -83,13 +84,23 @@ to see which mode each profile uses, and construct the matching HTTP header:
|
||||
},
|
||||
Output: "raw token on stdout (no envelope, no trailing newline) by default; --format json emits {token, mode, profile}",
|
||||
Warnings: []string{
|
||||
"default output is the bare token, NOT the JSON envelope — it is a scripting helper (cf. `gh auth token`)",
|
||||
"default output is the bare token, NOT the JSON envelope — it is a scripting helper for shell capture",
|
||||
},
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
|
||||
func runToken(f *cmdutil.Factory, fopts *cmdutil.FormatOptions) error {
|
||||
// Env credentials are the active credential on the headless path — `auth
|
||||
// token` must surface them (they ARE the token / api key) instead of
|
||||
// erroring on the absence of a stored profile.
|
||||
if active, kind := cmdutil.EnvCredential(); active {
|
||||
mode := ModeBearer
|
||||
if kind == "WEKNORA_API_KEY" {
|
||||
mode = ModeAPIKey
|
||||
}
|
||||
return emitToken(fopts, os.Getenv(kind), mode, "(env)")
|
||||
}
|
||||
cfg, err := f.Config()
|
||||
if err != nil {
|
||||
return err
|
||||
@@ -140,8 +151,18 @@ func runToken(f *cmdutil.Factory, fopts *cmdutil.FormatOptions) error {
|
||||
fmt.Sprintf("profile %q credential is empty in keyring; run `weknora auth login`", profileName))
|
||||
}
|
||||
|
||||
return emitToken(fopts, token, mode, profileName)
|
||||
}
|
||||
|
||||
// emitToken renders a resolved credential: the {token, mode, profile} envelope
|
||||
// under --format json, else the raw token on stdout (no trailing newline, for
|
||||
// clean $(weknora auth token) capture) with a TTY-only leak hint on stderr.
|
||||
func emitToken(fopts *cmdutil.FormatOptions, token, mode, profile string) error {
|
||||
if token == "" {
|
||||
return cmdutil.NewError(cmdutil.CodeAuthUnauthenticated, "active credential is empty")
|
||||
}
|
||||
if fopts.WantsJSON() {
|
||||
return fopts.Emit(iostreams.IO.Out, tokenResult{Token: token, Mode: mode, Profile: profileName}, nil)
|
||||
return fopts.Emit(iostreams.IO.Out, tokenResult{Token: token, Mode: mode, Profile: profile}, nil)
|
||||
}
|
||||
|
||||
// No trailing newline - clean $(weknora auth token) substitution.
|
||||
|
||||
+138
-74
@@ -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.",
|
||||
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, ...)",
|
||||
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{"<text> (positional)", "--kb"},
|
||||
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,23 +210,22 @@ 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 {
|
||||
if cmdutil.IsCancelled(ctx, err) {
|
||||
return cmdutil.Wrapf(cmdutil.CodeOperationCancelled, err, "chat cancelled")
|
||||
}
|
||||
return cmdutil.WrapHTTP(err, "knowledge qa stream")
|
||||
return cmdutil.WrapStream(err, "knowledge qa stream")
|
||||
}
|
||||
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,12 +260,12 @@ 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
|
||||
// classifier so 401 / 404 / 5xx still surface their specific codes.
|
||||
return cmdutil.WrapHTTP(streamErr, "knowledge qa stream")
|
||||
return cmdutil.WrapStream(streamErr, "knowledge qa stream")
|
||||
}
|
||||
|
||||
// SDK returned nil but we never saw a Done event - server closed the
|
||||
@@ -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.WrapStream(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.
|
||||
|
||||
+221
-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{
|
||||
@@ -329,6 +318,29 @@ func TestChat_SDKError_MidStream_AbortsAsSSE(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
func TestChat_TerminalSSEError_ClassifiesAsServerError(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
svc := &fakeChatService{
|
||||
streamEvents: []*sdk.StreamResponse{
|
||||
{ResponseType: sdk.ResponseTypeAnswer, Content: "partial"},
|
||||
{ResponseType: sdk.ResponseTypeError, Content: "boom", Done: true},
|
||||
},
|
||||
streamErr: sdk.NewSSEStreamError("boom"),
|
||||
}
|
||||
opts := &Options{Query: "q", KBID: "kb"}
|
||||
err := runChat(context.Background(), opts, textOpts(), svc)
|
||||
if err == nil {
|
||||
t.Fatal("expected error, got nil")
|
||||
}
|
||||
var typed *cmdutil.Error
|
||||
if !errors.As(err, &typed) {
|
||||
t.Fatalf("expected *cmdutil.Error, got %T", err)
|
||||
}
|
||||
if typed.Code != cmdutil.CodeServerError {
|
||||
t.Errorf("code: got %q want %q", typed.Code, cmdutil.CodeServerError)
|
||||
}
|
||||
}
|
||||
|
||||
func TestChat_ContextCancelled(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
ctx, cancel := context.WithCancel(context.Background())
|
||||
@@ -430,8 +442,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 +459,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 +484,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 +515,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)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -3,7 +3,6 @@ package chunkcmd
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"strings"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
|
||||
@@ -101,7 +100,9 @@ func NewCmdDelete(f *cmdutil.Factory) *cobra.Command {
|
||||
opts.ChunkID = args[0]
|
||||
return runDelete(c.Context(), opts, fopts, cli, f.Prompter())
|
||||
}
|
||||
if err := cmdutil.ConfirmDestructiveBatch(f.Prompter(), opts.Yes, fopts.WantsJSON(), "delete", "chunk", len(args), "chunk.delete", "weknora chunk delete "+strings.Join(args, " ")+" --doc "+opts.DocID+" -y"); err != nil {
|
||||
batchRetry := append([]string{"weknora", "chunk", "delete"}, args...)
|
||||
batchRetry = append(batchRetry, "--doc", opts.DocID, "-y")
|
||||
if err := cmdutil.ConfirmDestructiveBatch(f.Prompter(), opts.Yes, fopts.WantsJSON(), "delete", "chunk", len(args), "chunk.delete", batchRetry); err != nil {
|
||||
return err
|
||||
}
|
||||
outcomes, runErr := cmdutil.RunBatch(c.Context(), args, func(ctx context.Context, id string) error {
|
||||
@@ -123,6 +124,7 @@ func NewCmdDelete(f *cmdutil.Factory) *cobra.Command {
|
||||
}
|
||||
cmd.Flags().StringVar(&opts.DocID, "doc", "", "Parent document id (SDK knowledge_id) the chunks live under")
|
||||
_ = cmd.MarkFlagRequired("doc")
|
||||
cmdutil.AddIgnoredKBFlag(cmd)
|
||||
cmdutil.AddFormatFlag(cmd, chunkDeleteFields...)
|
||||
cmdutil.AddDryRunFlag(cmd, &opts.DryRun)
|
||||
cmdutil.SetRisk(cmd, "chunk.delete")
|
||||
@@ -134,6 +136,7 @@ func NewCmdDelete(f *cmdutil.Factory) *cobra.Command {
|
||||
"weknora chunk delete c1 c2 c3 --doc doc_xyz -y",
|
||||
"weknora chunk delete chunk_abc --doc doc_xyz -y --format json",
|
||||
},
|
||||
Output: "envelope.data shape depends on the form: a single chunk id -> {id, deleted:true}; multiple ids -> batch envelope (top-level status success|partial|error, ok=(failures==0), data per-item [{id, ok, error?}], meta.successes/failures — read data[].ok per id).",
|
||||
Warnings: []string{
|
||||
"Requires explicit user approval (exit 10 / input.confirmation_required); never auto-add -y.",
|
||||
"chunk delete is irreversible; loses the chunk + breaks RAG retrieval coherence for downstream queries.",
|
||||
@@ -143,7 +146,7 @@ func NewCmdDelete(f *cmdutil.Factory) *cobra.Command {
|
||||
}
|
||||
|
||||
func runDelete(ctx context.Context, opts *DeleteOptions, fopts *cmdutil.FormatOptions, svc DeleteService, p prompt.Prompter) error {
|
||||
if err := cmdutil.ConfirmDestructive(p, opts.Yes, fopts.WantsJSON(), "delete", "chunk", opts.ChunkID, "chunk.delete", "weknora chunk delete "+opts.ChunkID+" --doc "+opts.DocID+" -y"); err != nil {
|
||||
if err := cmdutil.ConfirmDestructive(p, opts.Yes, fopts.WantsJSON(), "delete", "chunk", opts.ChunkID, "chunk.delete", []string{"weknora", "chunk", "delete", opts.ChunkID, "--doc", opts.DocID, "-y"}); err != nil {
|
||||
return err
|
||||
}
|
||||
if err := svc.DeleteChunk(ctx, opts.DocID, opts.ChunkID); err != nil {
|
||||
|
||||
@@ -178,7 +178,7 @@ func TestMultiDelete_NonTTY_NoYes_RequiresConfirmation(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
svc := &fakeMultiChunkDeleteSvc{}
|
||||
fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatText}
|
||||
err := cmdutil.ConfirmDestructiveBatch(&testutil.ConfirmPrompter{}, false, fopts.WantsJSON(), "delete", "chunk", 2, "chunk.delete", "")
|
||||
err := cmdutil.ConfirmDestructiveBatch(&testutil.ConfirmPrompter{}, false, fopts.WantsJSON(), "delete", "chunk", 2, "chunk.delete", nil)
|
||||
require.Error(t, err)
|
||||
var typed *cmdutil.Error
|
||||
require.ErrorAs(t, err, &typed)
|
||||
|
||||
+29
-9
@@ -19,7 +19,7 @@ const (
|
||||
defaultPageSize = 50
|
||||
maxPageSize = 1000
|
||||
defaultLimit = 50
|
||||
maxLimit = 1000
|
||||
maxLimit = 10000
|
||||
previewWidth = 80
|
||||
)
|
||||
|
||||
@@ -45,7 +45,7 @@ type ListOptions struct {
|
||||
DocID string
|
||||
// PageSize is the server batch size (1..1000, default 50).
|
||||
PageSize int
|
||||
// Limit caps the client-side accumulated slice (1..1000, default 50).
|
||||
// Limit caps the client-side accumulated slice (1..10000, default 50).
|
||||
// Default 50 chosen as domain-tuned for chunk enumeration (RAG debug).
|
||||
Limit int
|
||||
// AllPages walks server pages internally until total exhausted or
|
||||
@@ -65,7 +65,7 @@ For relevance-ranked retrieval (the RAG runtime surface), use
|
||||
vector + keyword scoring across all chunks of a knowledge base.
|
||||
|
||||
Typed exit codes:
|
||||
input.invalid_argument --limit / --page-size out of 1..1000 range (exit 5)
|
||||
input.invalid_argument --limit out of 1..10000 or --page-size out of 1..1000 (exit 5)
|
||||
resource.not_found no document with the given id (exit 4)
|
||||
|
||||
AI agents: prefer 'search chunks' for retrieval tasks. Use 'chunk list'
|
||||
@@ -91,6 +91,12 @@ func NewCmdList(f *cmdutil.Factory) *cobra.Command {
|
||||
return err
|
||||
}
|
||||
fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
|
||||
// Validate static input before building the client so a bad
|
||||
// --limit/--page-size returns input.invalid_argument (exit 5), not
|
||||
// an auth error (exit 3).
|
||||
if err := validateListOpts(opts); err != nil {
|
||||
return err
|
||||
}
|
||||
cli, err := f.Client()
|
||||
if err != nil {
|
||||
return err
|
||||
@@ -100,20 +106,24 @@ func NewCmdList(f *cmdutil.Factory) *cobra.Command {
|
||||
}
|
||||
cmd.Flags().StringVar(&opts.DocID, "doc", "", "Document id (SDK knowledge_id) to enumerate chunks for")
|
||||
_ = cmd.MarkFlagRequired("doc")
|
||||
cmd.Flags().IntVarP(&opts.Limit, "limit", "L", defaultLimit, "Maximum results to return (1..1000)")
|
||||
cmd.Flags().IntVarP(&opts.Limit, "limit", "L", defaultLimit, "Maximum results to return — client-side cap; meta.has_more/total_count report truncation (1..10000)")
|
||||
cmd.Flags().IntVar(&opts.PageSize, "page-size", defaultPageSize, "Items per server batch (1..1000)")
|
||||
cmd.Flags().BoolVar(&opts.AllPages, "all-pages", false, "Walk all server pages until exhausted (or --limit hit)")
|
||||
cmdutil.AddFormatFlag(cmd, chunkListFields...)
|
||||
cmdutil.AddIgnoredKBFlag(cmd)
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "List chunks of a specific document in stored order (admin/debug). Results come with meta.count; use --limit (1..1000) and --all-pages to paginate. Prefer 'search chunks' for RAG retrieval.",
|
||||
UsedFor: "List chunks of a specific document in stored order (admin/debug). Results come with meta.count; use --limit (1..10000) and --all-pages to paginate. Prefer 'search chunks' for RAG retrieval.",
|
||||
RequiredFlags: []string{"--doc"},
|
||||
Examples: []string{"weknora chunk list --doc doc_abc --format json", "weknora chunk list --doc doc_abc --all-pages --format json"},
|
||||
Output: "envelope.data is an array of Chunk objects with id, chunk_index, content, is_enabled; meta.count is the total returned",
|
||||
Output: "envelope.data is an array of Chunk objects with id, chunk_index, content, is_enabled; meta.count is the returned count, meta.total_count the document's full chunk count, meta.has_more true when --limit truncated",
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
|
||||
func runList(ctx context.Context, opts *ListOptions, fopts *cmdutil.FormatOptions, svc ListService) error {
|
||||
// validateListOpts checks --limit / --page-size. Called from RunE before the
|
||||
// client is built (so a bad value surfaces as exit 5, not an auth error) and at
|
||||
// runList's top for direct callers; idempotent.
|
||||
func validateListOpts(opts *ListOptions) error {
|
||||
if opts.Limit < 1 || opts.Limit > maxLimit {
|
||||
return &cmdutil.Error{
|
||||
Code: cmdutil.CodeInputInvalidArgument,
|
||||
@@ -126,8 +136,16 @@ func runList(ctx context.Context, opts *ListOptions, fopts *cmdutil.FormatOption
|
||||
Message: fmt.Sprintf("--page-size must be in 1..%d, got %d", maxPageSize, opts.PageSize),
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func runList(ctx context.Context, opts *ListOptions, fopts *cmdutil.FormatOptions, svc ListService) error {
|
||||
if err := validateListOpts(opts); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
var items []sdk.Chunk
|
||||
var serverTotal int64
|
||||
truncated := false
|
||||
if opts.AllPages {
|
||||
accum := make([]sdk.Chunk, 0)
|
||||
@@ -136,6 +154,7 @@ func runList(ctx context.Context, opts *ListOptions, fopts *cmdutil.FormatOption
|
||||
if err != nil {
|
||||
return cmdutil.WrapHTTP(err, "list chunks for doc %s", opts.DocID)
|
||||
}
|
||||
serverTotal = total
|
||||
accum = append(accum, chunks...)
|
||||
if len(accum) >= opts.Limit {
|
||||
accum = accum[:opts.Limit]
|
||||
@@ -148,10 +167,11 @@ func runList(ctx context.Context, opts *ListOptions, fopts *cmdutil.FormatOption
|
||||
}
|
||||
items = accum
|
||||
} else {
|
||||
chunks, _, err := svc.ListKnowledgeChunks(ctx, opts.DocID, 1, opts.PageSize)
|
||||
chunks, total, err := svc.ListKnowledgeChunks(ctx, opts.DocID, 1, opts.PageSize)
|
||||
if err != nil {
|
||||
return cmdutil.WrapHTTP(err, "list chunks for doc %s", opts.DocID)
|
||||
}
|
||||
serverTotal = total
|
||||
items = chunks
|
||||
}
|
||||
if items == nil {
|
||||
@@ -163,7 +183,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)), TotalCount: output.IntPtr(int(serverTotal)), HasMore: truncated}
|
||||
return fopts.Emit(iostreams.IO.Out, items, meta)
|
||||
}
|
||||
|
||||
|
||||
@@ -128,9 +128,35 @@ func TestList_AllPages_LimitTruncatesAccumulated(t *testing.T) {
|
||||
assert.Equal(t, []string{"c1", "c2", "c3"}, []string{got[0].ID, got[1].ID, got[2].ID})
|
||||
}
|
||||
|
||||
// TestList_JSON_EmitsTotalCount pins that chunk list surfaces the document's
|
||||
// full chunk count as meta.total_count (like doc/session/kb/model list), not
|
||||
// just the returned count — an agent must be able to tell truncation from
|
||||
// completeness.
|
||||
func TestList_JSON_EmitsTotalCount(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &fakeListSvc{
|
||||
pages: [][]sdk.Chunk{{{ID: "c1"}, {ID: "c2"}}},
|
||||
totals: []int64{7},
|
||||
errs: []error{nil},
|
||||
}
|
||||
opts := &ListOptions{DocID: "d1", Limit: 50, PageSize: 50}
|
||||
require.NoError(t, runList(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc))
|
||||
var env struct {
|
||||
Meta struct {
|
||||
Count *int `json:"count"`
|
||||
TotalCount *int `json:"total_count"`
|
||||
} `json:"meta"`
|
||||
}
|
||||
require.NoError(t, json.Unmarshal(out.Bytes(), &env))
|
||||
require.NotNil(t, env.Meta.TotalCount, "chunk list must emit meta.total_count")
|
||||
assert.Equal(t, 7, *env.Meta.TotalCount)
|
||||
require.NotNil(t, env.Meta.Count)
|
||||
assert.Equal(t, 2, *env.Meta.Count)
|
||||
}
|
||||
|
||||
func TestList_LimitInvalid(t *testing.T) {
|
||||
svc := &fakeListSvc{}
|
||||
for _, lim := range []int{0, -1, 1001} {
|
||||
for _, lim := range []int{0, -1, 10001} {
|
||||
err := runList(context.Background(), &ListOptions{DocID: "d", Limit: lim, PageSize: 50}, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc)
|
||||
require.Error(t, err, "expect error for --limit %d", lim)
|
||||
assert.Contains(t, err.Error(), "input.invalid_argument")
|
||||
|
||||
@@ -81,6 +81,7 @@ func NewCmdView(f *cmdutil.Factory) *cobra.Command {
|
||||
},
|
||||
}
|
||||
cmdutil.AddFormatFlag(cmd, chunkViewFields...)
|
||||
cmdutil.AddIgnoredKBFlag(cmd)
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "fetch one chunk's fields and content by id (scope-less; no --doc needed)",
|
||||
RequiredFlags: []string{"<chunk-id> (positional)"},
|
||||
|
||||
@@ -0,0 +1,25 @@
|
||||
// Package configcmd holds the `weknora config` command tree.
|
||||
//
|
||||
// Currently a single read-only `view` subcommand that prints the resolved
|
||||
// CLI configuration and its resolution chain. No mutation, no network.
|
||||
//
|
||||
// Package name `configcmd` (not `config`) avoids colliding with the
|
||||
// internal/config package and matches the cmd-subpackage naming pattern.
|
||||
// The cobra Use: string is "config" — what users type.
|
||||
package configcmd
|
||||
|
||||
import (
|
||||
"github.com/spf13/cobra"
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
||||
)
|
||||
|
||||
// NewCmd builds the `weknora config` parent command.
|
||||
func NewCmd(f *cmdutil.Factory) *cobra.Command {
|
||||
cmd := &cobra.Command{
|
||||
Use: "config",
|
||||
Short: "Inspect the CLI's resolved configuration",
|
||||
}
|
||||
cmd.AddCommand(NewCmdView(f))
|
||||
return cmd
|
||||
}
|
||||
@@ -0,0 +1,275 @@
|
||||
package configcmd
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"os"
|
||||
"strings"
|
||||
"text/tabwriter"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
||||
"github.com/Tencent/WeKnora/cli/internal/config"
|
||||
"github.com/Tencent/WeKnora/cli/internal/format"
|
||||
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
||||
"github.com/Tencent/WeKnora/cli/internal/projectlink"
|
||||
"github.com/Tencent/WeKnora/cli/internal/secrets"
|
||||
"github.com/Tencent/WeKnora/cli/internal/xdg"
|
||||
)
|
||||
|
||||
// viewFields enumerates the fields surfaced for `--format json` discovery on
|
||||
// `config view`. Flat shape — each entry is a top-level key of envelope.data.
|
||||
var viewFields = []string{
|
||||
"active_profile", "profile_source", "auth_source", "host",
|
||||
"kb_id", "kb_source",
|
||||
"log_level", "log_level_source",
|
||||
"format_default",
|
||||
"config_file", "cache_dir", "secrets", "project_link",
|
||||
}
|
||||
|
||||
// viewData is the flat JSON payload describing the resolved config and where
|
||||
// each value came from. Sources are stable human strings (e.g. "--profile
|
||||
// flag") so an agent can explain the resolution without re-deriving it.
|
||||
type viewData struct {
|
||||
ActiveProfile string `json:"active_profile"`
|
||||
ProfileSource string `json:"profile_source"`
|
||||
AuthSource string `json:"auth_source"`
|
||||
Host string `json:"host"`
|
||||
KBID string `json:"kb_id"`
|
||||
KBSource string `json:"kb_source"`
|
||||
LogLevel string `json:"log_level"`
|
||||
LogLevelSource string `json:"log_level_source"`
|
||||
FormatDefault string `json:"format_default"`
|
||||
ConfigFile string `json:"config_file"`
|
||||
CacheDir string `json:"cache_dir"`
|
||||
Secrets string `json:"secrets"`
|
||||
ProjectLink string `json:"project_link"`
|
||||
}
|
||||
|
||||
// NewCmdView builds `weknora config view`. Read-only inspection of the
|
||||
// resolved config and resolution chain. Never builds the SDK client and
|
||||
// never issues a network request: KB resolution uses ResolveKBLocal, secrets
|
||||
// storage is detected from the store type, and everything else is read from
|
||||
// config.yaml / env / flags.
|
||||
func NewCmdView(f *cmdutil.Factory) *cobra.Command {
|
||||
cmd := &cobra.Command{
|
||||
Use: "view",
|
||||
Short: "Show the resolved configuration and where each value came from",
|
||||
Long: `Print the configuration currently in effect and its resolution chain:
|
||||
the active profile (and its source), the profile host, the resolved knowledge
|
||||
base (and source), log level, default output format, and the on-disk paths for
|
||||
config / cache / secrets / project link.
|
||||
|
||||
Read-only: no values are mutated and no network request is issued. Succeeds
|
||||
even when no profile or KB is configured (sources report "(none)" /
|
||||
"(unresolved)").`,
|
||||
Args: cobra.NoArgs,
|
||||
RunE: func(c *cobra.Command, _ []string) error {
|
||||
fopts, err := cmdutil.CheckFormatFlag(c)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
|
||||
return runView(c, f, fopts)
|
||||
},
|
||||
}
|
||||
cmdutil.AddFormatFlag(cmd, viewFields...)
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "inspect the resolved CLI config and resolution chain (active profile, host, kb, log level, default format, file paths) without mutating or hitting the network",
|
||||
Examples: []string{
|
||||
"weknora config view",
|
||||
"weknora config view --format json",
|
||||
"weknora config view --jq '.data.active_profile'",
|
||||
},
|
||||
Output: "envelope.data is {active_profile, profile_source, auth_source, host, kb_id, kb_source, log_level, log_level_source, format_default, config_file, cache_dir, secrets, project_link}. auth_source reports whether the active credential is the profile+keyring or a stateless WEKNORA_TOKEN/WEKNORA_API_KEY env override.",
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
|
||||
func runView(cmd *cobra.Command, f *cmdutil.Factory, fopts *cmdutil.FormatOptions) error {
|
||||
d := resolveView(cmd, f)
|
||||
|
||||
if fopts.WantsJSON() {
|
||||
return fopts.Emit(iostreams.IO.Out, d, nil)
|
||||
}
|
||||
|
||||
tw := tabwriter.NewWriter(iostreams.IO.Out, 0, 0, 2, ' ', 0)
|
||||
row := func(k, v string) { fmt.Fprintf(tw, "%s\t%s\n", k, format.DashIfEmpty(v)) }
|
||||
row("active_profile", d.ActiveProfile)
|
||||
row("profile_source", d.ProfileSource)
|
||||
row("auth_source", d.AuthSource)
|
||||
row("host", d.Host)
|
||||
row("kb_id", d.KBID)
|
||||
row("kb_source", d.KBSource)
|
||||
row("log_level", d.LogLevel)
|
||||
row("log_level_source", d.LogLevelSource)
|
||||
row("format_default", d.FormatDefault)
|
||||
row("config_file", d.ConfigFile)
|
||||
row("cache_dir", d.CacheDir)
|
||||
row("secrets", d.Secrets)
|
||||
row("project_link", d.ProjectLink)
|
||||
return tw.Flush()
|
||||
}
|
||||
|
||||
// resolveView assembles the resolved-config snapshot. Pure read: reads
|
||||
// config.yaml (no network), env vars, flags, and the local project link.
|
||||
func resolveView(cmd *cobra.Command, f *cmdutil.Factory) viewData {
|
||||
d := viewData{}
|
||||
|
||||
// Profile + its source.
|
||||
d.ActiveProfile, d.ProfileSource = resolveProfile(f)
|
||||
|
||||
// Host: looked up from the active profile in config (best-effort; empty
|
||||
// when unset, no profile, or config unreadable).
|
||||
if d.ActiveProfile != "" && f.Config != nil {
|
||||
if cfg, err := f.Config(); err == nil && cfg != nil {
|
||||
if prof, ok := cfg.Profiles[d.ActiveProfile]; ok {
|
||||
d.Host = prof.Host
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Auth source: stateless env credentials (WEKNORA_TOKEN/WEKNORA_API_KEY)
|
||||
// override the profile + keyring for the actual client, so report that —
|
||||
// otherwise host/profile above would silently describe a profile the env
|
||||
// credential bypassed. WEKNORA_HOST (when set) is the host that env cred
|
||||
// authenticates against.
|
||||
if active, kind := cmdutil.EnvCredential(); active {
|
||||
d.AuthSource = kind + " env (stateless; bypasses profile + keyring)"
|
||||
if h := strings.TrimSpace(os.Getenv("WEKNORA_HOST")); h != "" {
|
||||
d.Host = h
|
||||
}
|
||||
} else if d.ActiveProfile != "" {
|
||||
d.AuthSource = "profile + keyring"
|
||||
} else {
|
||||
d.AuthSource = "(none)"
|
||||
}
|
||||
|
||||
// KB id + source (never network — ResolveKBLocal).
|
||||
d.KBID, d.KBSource = resolveKB(cmd, f)
|
||||
|
||||
// Log level + source.
|
||||
d.LogLevel, d.LogLevelSource = resolveLogLevel(cmd)
|
||||
|
||||
// Default output format (configured default, not the per-invocation flag).
|
||||
d.FormatDefault = resolveFormatDefault()
|
||||
|
||||
// Paths.
|
||||
if p, err := config.Path(); err == nil {
|
||||
d.ConfigFile = p
|
||||
}
|
||||
if p, err := xdg.Path("XDG_CACHE_HOME", ".cache"); err == nil {
|
||||
d.CacheDir = p
|
||||
}
|
||||
d.Secrets = resolveSecrets(f)
|
||||
d.ProjectLink = resolveProjectLink()
|
||||
|
||||
return d
|
||||
}
|
||||
|
||||
// resolveProfile mirrors Factory.ActiveProfile's precedence but also reports
|
||||
// which level supplied the value, so `config view` can explain the choice.
|
||||
func resolveProfile(f *cmdutil.Factory) (name, source string) {
|
||||
if f.ProfileOverride != "" {
|
||||
return f.ProfileOverride, "--profile flag"
|
||||
}
|
||||
if v := os.Getenv("WEKNORA_PROFILE"); v != "" {
|
||||
return v, "WEKNORA_PROFILE env"
|
||||
}
|
||||
if f.Config != nil {
|
||||
if cfg, err := f.Config(); err == nil && cfg != nil && cfg.CurrentProfile != "" {
|
||||
return cfg.CurrentProfile, "config current_profile"
|
||||
}
|
||||
}
|
||||
return "", "(none)"
|
||||
}
|
||||
|
||||
// resolveKB reports the locally-resolved KB id and its source. ResolveKBLocal
|
||||
// never hits the SDK; a CodeKBIDRequired error means nothing is in scope, which
|
||||
// config view reports as "(unresolved)" rather than failing.
|
||||
func resolveKB(cmd *cobra.Command, f *cmdutil.Factory) (id, source string) {
|
||||
id, err := f.ResolveKBLocal(cmd)
|
||||
if err != nil {
|
||||
return "", "(unresolved)"
|
||||
}
|
||||
// Re-derive which level supplied it (ResolveKBLocal returns only the value).
|
||||
if v, _ := cmd.Flags().GetString("kb"); v != "" {
|
||||
return id, "--kb flag"
|
||||
}
|
||||
if v := os.Getenv("WEKNORA_KB_ID"); v != "" {
|
||||
return id, "WEKNORA_KB_ID env"
|
||||
}
|
||||
if cwd, werr := os.Getwd(); werr == nil {
|
||||
if path, found, derr := projectlink.Discover(cwd); derr == nil && found {
|
||||
return id, "project link " + path
|
||||
}
|
||||
}
|
||||
return id, "(unresolved)"
|
||||
}
|
||||
|
||||
// resolveLogLevel reports the effective level and its source, matching
|
||||
// ResolveLogLevel's precedence (flag > env > default).
|
||||
func resolveLogLevel(cmd *cobra.Command) (level, source string) {
|
||||
level, _ = cmdutil.ResolveLogLevel(cmd, iostreams.IO.Err)
|
||||
if cmd != nil {
|
||||
if fl := cmd.Flags().Lookup("log-level"); fl != nil && fl.Changed && cmdutil.IsValidLogLevel(fl.Value.String()) {
|
||||
return level, "--log-level flag"
|
||||
}
|
||||
}
|
||||
if v := os.Getenv("WEKNORA_LOG_LEVEL"); v != "" && cmdutil.IsValidLogLevel(v) {
|
||||
return level, "WEKNORA_LOG_LEVEL env"
|
||||
}
|
||||
return level, "default"
|
||||
}
|
||||
|
||||
// resolveFormatDefault reports the configured default output format: the
|
||||
// config.yaml defaults.format value, else WEKNORA_FORMAT, else the hard
|
||||
// default. This is the *default* used when --format is unset — not the
|
||||
// per-invocation --format flag value.
|
||||
func resolveFormatDefault() string {
|
||||
cfg, err := config.Load()
|
||||
if err == nil && cfg != nil && cfg.Defaults.Format != "" {
|
||||
return cfg.Defaults.Format
|
||||
}
|
||||
if v := os.Getenv("WEKNORA_FORMAT"); v == "text" || v == "json" || v == "ndjson" {
|
||||
return v
|
||||
}
|
||||
return string(cmdutil.DefaultFormatMode)
|
||||
}
|
||||
|
||||
// resolveSecrets reports where credentials are stored: "file <path-root>" when
|
||||
// the keyring is unavailable and the layer fell back to a 0600 FileStore,
|
||||
// otherwise "keyring". Detection mirrors doctor's credential_storage check
|
||||
// (type-assert on the best-effort store). On construction failure, reports the
|
||||
// file fallback root so the user knows where to look.
|
||||
func resolveSecrets(f *cmdutil.Factory) string {
|
||||
var store secrets.Store
|
||||
var err error
|
||||
if f.Secrets != nil {
|
||||
store, err = f.Secrets()
|
||||
} else {
|
||||
store, err = secrets.NewBestEffortStore()
|
||||
}
|
||||
if err == nil && store != nil {
|
||||
if _, isFile := store.(*secrets.FileStore); !isFile {
|
||||
return "keyring"
|
||||
}
|
||||
}
|
||||
if p, perr := xdg.Path("XDG_CONFIG_HOME", ".config", "secrets"); perr == nil {
|
||||
return "file " + p
|
||||
}
|
||||
return "file"
|
||||
}
|
||||
|
||||
// resolveProjectLink reports the discovered .weknora/project.yaml path or
|
||||
// "(none)". Walks up from cwd like ResolveKBLocal does.
|
||||
func resolveProjectLink() string {
|
||||
cwd, err := os.Getwd()
|
||||
if err != nil {
|
||||
return "(none)"
|
||||
}
|
||||
if path, found, derr := projectlink.Discover(cwd); derr == nil && found {
|
||||
return path
|
||||
}
|
||||
return "(none)"
|
||||
}
|
||||
@@ -0,0 +1,120 @@
|
||||
package configcmd
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"testing"
|
||||
|
||||
"github.com/stretchr/testify/assert"
|
||||
"github.com/stretchr/testify/require"
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
||||
"github.com/Tencent/WeKnora/cli/internal/config"
|
||||
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
||||
sdk "github.com/Tencent/WeKnora/client"
|
||||
)
|
||||
|
||||
type viewEnvelope struct {
|
||||
OK bool `json:"ok"`
|
||||
Data struct {
|
||||
ActiveProfile string `json:"active_profile"`
|
||||
ProfileSource string `json:"profile_source"`
|
||||
AuthSource string `json:"auth_source"`
|
||||
Host string `json:"host"`
|
||||
KBID string `json:"kb_id"`
|
||||
KBSource string `json:"kb_source"`
|
||||
FormatDefault string `json:"format_default"`
|
||||
ConfigFile string `json:"config_file"`
|
||||
} `json:"data"`
|
||||
}
|
||||
|
||||
func runViewJSON(t *testing.T, f *cmdutil.Factory) viewEnvelope {
|
||||
t.Helper()
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
// --format is a root-level persistent flag, so drive runView directly with
|
||||
// a JSON FormatOptions rather than through standalone leaf flag parsing.
|
||||
cmd := NewCmdView(f)
|
||||
require.NoError(t, runView(cmd, f, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}))
|
||||
var env viewEnvelope
|
||||
require.NoError(t, json.Unmarshal(out.Bytes(), &env), "envelope: %q", out.String())
|
||||
return env
|
||||
}
|
||||
|
||||
// TestConfigView_ConfigProfileSource: with a current_profile set in config and
|
||||
// no flag/env override, config view reports the profile, its source, and the
|
||||
// host — and resolves the KB to "(unresolved)" (no --kb/env/link) without error.
|
||||
func TestConfigView_ConfigProfileSource(t *testing.T) {
|
||||
t.Setenv("XDG_CONFIG_HOME", t.TempDir())
|
||||
cfg := &config.Config{
|
||||
CurrentProfile: "prod",
|
||||
Profiles: map[string]config.Profile{"prod": {Host: "https://kb.example.com"}},
|
||||
}
|
||||
require.NoError(t, config.Save(cfg))
|
||||
|
||||
env := runViewJSON(t, networkFreeFactory(t))
|
||||
assert.True(t, env.OK)
|
||||
assert.Equal(t, "prod", env.Data.ActiveProfile)
|
||||
assert.Equal(t, "config current_profile", env.Data.ProfileSource)
|
||||
assert.Equal(t, "https://kb.example.com", env.Data.Host)
|
||||
assert.Equal(t, "(unresolved)", env.Data.KBSource, "no --kb/env/link must report unresolved, not error")
|
||||
assert.Equal(t, "json", env.Data.FormatDefault)
|
||||
assert.NotEmpty(t, env.Data.ConfigFile)
|
||||
}
|
||||
|
||||
// TestConfigView_ProfileOverrideSource: the --profile override (set on the
|
||||
// Factory by root's PersistentPreRunE) wins over config and is reported as
|
||||
// such, so an agent can see why a non-default profile is active.
|
||||
func TestConfigView_ProfileOverrideSource(t *testing.T) {
|
||||
t.Setenv("XDG_CONFIG_HOME", t.TempDir())
|
||||
cfg := &config.Config{
|
||||
CurrentProfile: "prod",
|
||||
Profiles: map[string]config.Profile{"prod": {Host: "https://kb.example.com"}},
|
||||
}
|
||||
require.NoError(t, config.Save(cfg))
|
||||
|
||||
f := networkFreeFactory(t)
|
||||
f.ProfileOverride = "other"
|
||||
env := runViewJSON(t, f)
|
||||
assert.Equal(t, "other", env.Data.ActiveProfile)
|
||||
assert.Equal(t, "--profile flag", env.Data.ProfileSource)
|
||||
}
|
||||
|
||||
// TestConfigView_NoProfile: config view succeeds with an empty config —
|
||||
// active_profile "" / source "(none)" — never erroring on a fresh install.
|
||||
func TestConfigView_NoProfile(t *testing.T) {
|
||||
t.Setenv("XDG_CONFIG_HOME", t.TempDir())
|
||||
env := runViewJSON(t, networkFreeFactory(t))
|
||||
assert.True(t, env.OK)
|
||||
assert.Equal(t, "", env.Data.ActiveProfile)
|
||||
assert.Equal(t, "(none)", env.Data.ProfileSource)
|
||||
}
|
||||
|
||||
// networkFreeFactory builds a Factory whose Client closure fails the test if
|
||||
// invoked — config view must resolve everything locally (ResolveKBLocal,
|
||||
// ActiveProfile) and never build the SDK client.
|
||||
func networkFreeFactory(t *testing.T) *cmdutil.Factory {
|
||||
t.Helper()
|
||||
f := cmdutil.New()
|
||||
f.Client = func() (*sdk.Client, error) {
|
||||
t.Fatal("config view must not build the SDK client / hit the network")
|
||||
return nil, nil
|
||||
}
|
||||
return f
|
||||
}
|
||||
|
||||
// TestConfigView_EnvCredentialSurfaced: when WEKNORA_API_KEY + WEKNORA_HOST are
|
||||
// set, config view reports the env override (auth_source + the env host), not
|
||||
// the bypassed config profile's host.
|
||||
func TestConfigView_EnvCredentialSurfaced(t *testing.T) {
|
||||
t.Setenv("XDG_CONFIG_HOME", t.TempDir())
|
||||
cfg := &config.Config{
|
||||
CurrentProfile: "prod",
|
||||
Profiles: map[string]config.Profile{"prod": {Host: "https://configured.example.com"}},
|
||||
}
|
||||
require.NoError(t, config.Save(cfg))
|
||||
t.Setenv("WEKNORA_API_KEY", "sk-test")
|
||||
t.Setenv("WEKNORA_HOST", "https://env-override.example.com")
|
||||
|
||||
env := runViewJSON(t, networkFreeFactory(t))
|
||||
assert.Contains(t, env.Data.AuthSource, "WEKNORA_API_KEY env")
|
||||
assert.Equal(t, "https://env-override.example.com", env.Data.Host, "host must be the env override, not the profile host")
|
||||
}
|
||||
+30
-14
@@ -12,6 +12,7 @@ import (
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
||||
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
||||
"github.com/Tencent/WeKnora/cli/internal/output"
|
||||
sdk "github.com/Tencent/WeKnora/client"
|
||||
)
|
||||
|
||||
@@ -26,7 +27,7 @@ var docCreateFields = []string{
|
||||
// CreateOptions holds CLI flag values for `doc create`.
|
||||
type CreateOptions struct {
|
||||
Text string // --text (required): document text content (Markdown)
|
||||
Name string // --name: document title
|
||||
Title string // --title: document title (matches `doc update --title`)
|
||||
TagID string // --tag-id: associate with a tag
|
||||
Channel string // --channel: ingestion-channel tag (default "api")
|
||||
DryRun bool
|
||||
@@ -54,12 +55,12 @@ don't require a file upload or remote URL. KB resolution follows the standard
|
||||
4-level chain: --kb flag > WEKNORA_KB_ID env > .weknora/project.yaml > error.
|
||||
|
||||
--text <content> Document text in Markdown format (required).
|
||||
--name <title> Display title stored with the entry.
|
||||
--title <title> Display title stored with the entry (matches doc update --title).
|
||||
--tag-id <id> Associate the new entry with a tag.
|
||||
--channel <name> Override the ingestion-channel tag (default "api").`,
|
||||
Example: ` weknora doc create --text "# Meeting Notes\n\nAction items: ..."
|
||||
weknora doc create --text "$(cat notes.md)" --name "Sprint Notes" --kb my-kb
|
||||
weknora doc create --text "API usage guide" --name "API Guide" --tag-id tag_abc`,
|
||||
weknora doc create --text "$(cat notes.md)" --title "Sprint Notes" --kb my-kb
|
||||
weknora doc create --text "API usage guide" --title "API Guide" --tag-id tag_abc`,
|
||||
Args: cobra.NoArgs,
|
||||
RunE: func(c *cobra.Command, _ []string) error {
|
||||
fopts, err := cmdutil.CheckFormatFlag(c)
|
||||
@@ -78,9 +79,9 @@ don't require a file upload or remote URL. KB resolution follows the standard
|
||||
if handled, err := cmdutil.HandleDryRun(c, true, cmdutil.DryRunPlan{
|
||||
Action: "doc.create",
|
||||
Args: map[string]any{
|
||||
"text": opts.Text,
|
||||
"name": opts.Name,
|
||||
"kb": kbID,
|
||||
"text": opts.Text,
|
||||
"title": opts.Title,
|
||||
"kb": kbID,
|
||||
},
|
||||
}); handled {
|
||||
return err
|
||||
@@ -100,7 +101,7 @@ don't require a file upload or remote URL. KB resolution follows the standard
|
||||
}
|
||||
cmdutil.AddKBFlag(cmd)
|
||||
cmd.Flags().StringVar(&opts.Text, "text", "", "Document text content in Markdown format (required)")
|
||||
cmd.Flags().StringVar(&opts.Name, "name", "", "Document title")
|
||||
cmd.Flags().StringVar(&opts.Title, "title", "", "Document title")
|
||||
cmd.Flags().StringVar(&opts.TagID, "tag-id", "", "Tag id to associate with the new entry")
|
||||
cmd.Flags().StringVar(&opts.Channel, "channel", "", "Ingestion-channel tag recorded server-side (default \"api\")")
|
||||
_ = cmd.MarkFlagRequired("text")
|
||||
@@ -108,8 +109,12 @@ don't require a file upload or remote URL. KB resolution follows the standard
|
||||
cmdutil.AddDryRunFlag(cmd, &opts.DryRun)
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "Create a knowledge entry from inline Markdown text. KB resolved via --kb flag, WEKNORA_KB_ID env, or project link. Emits the created Knowledge object with its id.",
|
||||
RequiredFlags: []string{"--text"},
|
||||
Output: "envelope.data is the created Knowledge object with id, knowledge_base_id, title, parse_status",
|
||||
RequiredFlags: []string{"--text", "--kb (or WEKNORA_KB_ID / project link)"},
|
||||
Examples: []string{
|
||||
`weknora doc create --kb kb_eng --text "# Runbook\n\nRestart steps: ..."`,
|
||||
`weknora doc create --kb kb_eng --text "$(cat notes.md)" --title "Sprint Notes"`,
|
||||
},
|
||||
Output: "envelope.data is the created Knowledge object with id, knowledge_base_id, title, parse_status",
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
@@ -123,7 +128,7 @@ func runCreate(ctx context.Context, opts *CreateOptions, fopts *cmdutil.FormatOp
|
||||
return cmdutil.NewFlagError(fmt.Errorf("--text is required"))
|
||||
}
|
||||
req := &sdk.CreateManualKnowledgeRequest{
|
||||
Title: opts.Name,
|
||||
Title: opts.Title,
|
||||
Content: opts.Text,
|
||||
TagID: opts.TagID,
|
||||
Channel: cmp.Or(opts.Channel, uploadChannel),
|
||||
@@ -132,10 +137,18 @@ func runCreate(ctx context.Context, opts *CreateOptions, fopts *cmdutil.FormatOp
|
||||
if err != nil {
|
||||
return cmdutil.WrapHTTP(err, "create document")
|
||||
}
|
||||
if fopts.WantsJSON() {
|
||||
return fopts.Emit(iostreams.IO.Out, k, nil)
|
||||
// Inline-created docs land in parse_status=draft and are NOT auto-queued
|
||||
// for parsing (unlike `doc upload`), so they aren't searchable until
|
||||
// reparsed. Surface the next step so an agent doesn't `doc wait` into a
|
||||
// timeout or `search` into empty results.
|
||||
var meta *output.Meta
|
||||
if k.ParseStatus == "draft" {
|
||||
meta = &output.Meta{Hint: "document created in parse_status=draft (not yet indexed) — run `weknora doc reparse " + k.ID + "` to parse & make it searchable"}
|
||||
}
|
||||
displayed := opts.Name
|
||||
if fopts.WantsJSON() {
|
||||
return fopts.Emit(iostreams.IO.Out, k, meta)
|
||||
}
|
||||
displayed := opts.Title
|
||||
if displayed == "" {
|
||||
displayed = k.Title
|
||||
}
|
||||
@@ -143,5 +156,8 @@ func runCreate(ctx context.Context, opts *CreateOptions, fopts *cmdutil.FormatOp
|
||||
displayed = k.ID
|
||||
}
|
||||
fmt.Fprintf(iostreams.IO.Out, "✓ Created %q (id: %s)\n", displayed, k.ID)
|
||||
if meta != nil {
|
||||
fmt.Fprintf(iostreams.IO.Out, " ⚠ %s\n", meta.Hint)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
@@ -35,10 +35,21 @@ func (f *fakeCreateSvc) CreateManualKnowledge(
|
||||
return f.resp, f.err
|
||||
}
|
||||
|
||||
// TestCreate_TitleSetsRequestTitle: --title is the sole title flag and flows
|
||||
// straight into the create request.
|
||||
func TestCreate_TitleSetsRequestTitle(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
svc := &fakeCreateSvc{resp: &sdk.Knowledge{ID: "d1"}}
|
||||
require.NoError(t, runCreate(context.Background(),
|
||||
&CreateOptions{Text: "x", Title: "FromTitle"},
|
||||
&cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc, "kb1"))
|
||||
assert.Equal(t, "FromTitle", svc.got.req.Title)
|
||||
}
|
||||
|
||||
func TestCreate_Success_Text(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &fakeCreateSvc{resp: &sdk.Knowledge{ID: "doc_manual_1", Title: "Sprint Notes"}}
|
||||
opts := &CreateOptions{Text: "# Sprint Notes\n\nAction items: ...", Name: "Sprint Notes"}
|
||||
opts := &CreateOptions{Text: "# Sprint Notes\n\nAction items: ...", Title: "Sprint Notes"}
|
||||
require.NoError(t, runCreate(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc, "kb_xxx"))
|
||||
|
||||
assert.Equal(t, "kb_xxx", svc.got.kbID)
|
||||
@@ -92,7 +103,7 @@ func TestCreate_Channel_DefaultIsAPI(t *testing.T) {
|
||||
func TestCreate_JSON_Envelope(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &fakeCreateSvc{resp: &sdk.Knowledge{ID: "doc_manual_json", Title: "My Note"}}
|
||||
opts := &CreateOptions{Text: "# My Note", Name: "My Note"}
|
||||
opts := &CreateOptions{Text: "# My Note", Title: "My Note"}
|
||||
fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}
|
||||
require.NoError(t, runCreate(context.Background(), opts, fopts, svc, "kb_xxx"))
|
||||
|
||||
|
||||
@@ -3,7 +3,6 @@ package doc
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"strings"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
|
||||
@@ -95,7 +94,7 @@ without the user's explicit go-ahead.`,
|
||||
if opts.KB == "" {
|
||||
return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, "--all requires --kb=<id>").
|
||||
WithHint("specify --kb=<uuid-or-name> to scope the delete-all operation").
|
||||
WithRetryCommand("weknora doc delete --all --kb=<kb-id> -y")
|
||||
WithRetryArgv([]string{"weknora", "doc", "delete", "--all", "--kb=<kb-id>", "-y"})
|
||||
}
|
||||
if len(args) > 0 {
|
||||
return cmdutil.NewFlagError(fmt.Errorf("--all is exclusive with positional doc ids"))
|
||||
@@ -138,7 +137,9 @@ without the user's explicit go-ahead.`,
|
||||
if len(args) == 1 {
|
||||
return runDelete(c.Context(), opts, fopts, cli, f.Prompter(), args[0])
|
||||
}
|
||||
if err := cmdutil.ConfirmDestructiveBatch(f.Prompter(), opts.Yes, fopts.WantsJSON(), "delete", "document", len(args), "doc.delete", "weknora doc delete "+strings.Join(args, " ")+" -y"); err != nil {
|
||||
batchRetry := append([]string{"weknora", "doc", "delete"}, args...)
|
||||
batchRetry = append(batchRetry, "-y")
|
||||
if err := cmdutil.ConfirmDestructiveBatch(f.Prompter(), opts.Yes, fopts.WantsJSON(), "delete", "document", len(args), "doc.delete", batchRetry); err != nil {
|
||||
return err
|
||||
}
|
||||
outcomes, runErr := cmdutil.RunBatch(c.Context(), args, func(ctx context.Context, id string) error {
|
||||
@@ -171,6 +172,7 @@ without the user's explicit go-ahead.`,
|
||||
"weknora doc delete doc_a doc_b doc_c -y",
|
||||
"weknora doc delete --all --kb=kb_x -y --format json",
|
||||
},
|
||||
Output: "envelope.data shape depends on the form: a single doc id -> {id, deleted:true}; multiple doc ids -> batch envelope (top-level status success|partial|error, ok=(failures==0), data per-item [{id, ok, error?}], meta.successes/failures — read data[].ok per id, ok:true overall does not survive a partial failure / exit 1); --all --kb -> {kb_id, deleted_count}.",
|
||||
Warnings: []string{
|
||||
"Requires explicit user approval (exit 10 / input.confirmation_required); never auto-add -y.",
|
||||
"doc delete is irreversible; loses the document + its chunks + embeddings.",
|
||||
@@ -181,7 +183,7 @@ without the user's explicit go-ahead.`,
|
||||
}
|
||||
|
||||
func runDelete(ctx context.Context, opts *DeleteOptions, fopts *cmdutil.FormatOptions, svc DeleteService, p prompt.Prompter, id string) error {
|
||||
if err := cmdutil.ConfirmDestructive(p, opts.Yes, fopts.WantsJSON(), "delete", "document", id, "doc.delete", "weknora doc delete "+id+" -y"); err != nil {
|
||||
if err := cmdutil.ConfirmDestructive(p, opts.Yes, fopts.WantsJSON(), "delete", "document", id, "doc.delete", []string{"weknora", "doc", "delete", id, "-y"}); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
@@ -201,7 +203,7 @@ func runDelete(ctx context.Context, opts *DeleteOptions, fopts *cmdutil.FormatOp
|
||||
// CodeInputConfirmationRequired (exit 10) with risk metadata so agents can
|
||||
// surface the risk to the user before re-invoking with -y.
|
||||
func runDeleteAll(ctx context.Context, opts *DeleteOptions, fopts *cmdutil.FormatOptions, svc AllService, p prompt.Prompter) error {
|
||||
if err := cmdutil.ConfirmDestructive(p, opts.Yes, fopts.WantsJSON(), "delete", "all docs in KB", opts.KB, "doc.delete_all", fmt.Sprintf("weknora doc delete --all --kb=%s -y", opts.KB)); err != nil {
|
||||
if err := cmdutil.ConfirmDestructive(p, opts.Yes, fopts.WantsJSON(), "delete", "all docs in KB", opts.KB, "doc.delete_all", []string{"weknora", "doc", "delete", "--all", "--kb=" + opts.KB, "-y"}); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
|
||||
@@ -262,7 +262,7 @@ func TestRunMultiDelete_ConfirmBatch_NonTTY_RequiresConfirmation(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t) // non-TTY
|
||||
svc := &fakeDeleteSvc{}
|
||||
fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}
|
||||
err := cmdutil.ConfirmDestructiveBatch(&testutil.ConfirmPrompter{Answer: false}, false, fopts.WantsJSON(), "delete", "document", 2, "doc.delete", "")
|
||||
err := cmdutil.ConfirmDestructiveBatch(&testutil.ConfirmPrompter{Answer: false}, false, fopts.WantsJSON(), "delete", "document", 2, "doc.delete", nil)
|
||||
require.Error(t, err)
|
||||
var typed *cmdutil.Error
|
||||
require.ErrorAs(t, err, &typed)
|
||||
@@ -274,7 +274,7 @@ func TestRunMultiDelete_ConfirmBatch_TTY_UserAborts(t *testing.T) {
|
||||
_, errBuf := iostreams.SetForTestWithTTY(t)
|
||||
svc := &fakeDeleteSvc{}
|
||||
fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatText}
|
||||
err := cmdutil.ConfirmDestructiveBatch(&testutil.ConfirmPrompter{Answer: false}, false, fopts.WantsJSON(), "delete", "document", 3, "doc.delete", "")
|
||||
err := cmdutil.ConfirmDestructiveBatch(&testutil.ConfirmPrompter{Answer: false}, false, fopts.WantsJSON(), "delete", "document", 3, "doc.delete", nil)
|
||||
require.Error(t, err)
|
||||
var typed *cmdutil.Error
|
||||
require.ErrorAs(t, err, &typed)
|
||||
|
||||
@@ -26,6 +26,8 @@ func NewCmd(f *cmdutil.Factory) *cobra.Command {
|
||||
cmd.AddCommand(NewCmdDownload(f))
|
||||
cmd.AddCommand(NewCmdFetch(f))
|
||||
cmd.AddCommand(NewCmdList(f))
|
||||
cmd.AddCommand(NewCmdReparse(f))
|
||||
cmd.AddCommand(NewCmdUpdate(f))
|
||||
cmd.AddCommand(NewCmdUpload(f))
|
||||
cmd.AddCommand(NewCmdView(f))
|
||||
cmd.AddCommand(NewCmdWait(f))
|
||||
|
||||
@@ -79,11 +79,16 @@ stdout.`,
|
||||
}
|
||||
cmd.Flags().StringVarP(&opts.Output, "output", "O", "", `Output path; "-" for stdout. Defaults to the server-suggested filename.`)
|
||||
cmd.Flags().BoolVar(&opts.Clobber, "clobber", false, "Overwrite the output file if it already exists")
|
||||
cmdutil.AddIgnoredKBFlag(cmd)
|
||||
cmdutil.AddFormatFlag(cmd, downloadFields...)
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "Download a document's bytes by id. Writes a file (or stdout with --output -).",
|
||||
RequiredFlags: []string{"<doc-id> (positional)"},
|
||||
Output: "with --format json (file output): envelope.data has path, bytes, filename; suppressed with --output - (raw bytes to stdout)",
|
||||
Examples: []string{
|
||||
"weknora doc download doc_abc --output ./manual.pdf",
|
||||
"weknora doc download doc_abc --output - > manual.pdf",
|
||||
},
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
// Package doc — dryrun_validation_test.go asserts that --dry-run on
|
||||
// doc subcommands rejects identically to the live path (industry standard:
|
||||
// gh / kubectl / lark all validate before previewing). Before the surrounding
|
||||
// fix, validation lived in runX() and was reached only after HandleDryRun
|
||||
// doc subcommands rejects identically to the live path (validation must run
|
||||
// before previewing). Before the surrounding fix, validation lived in runX()
|
||||
// and was reached only after HandleDryRun
|
||||
// short-circuited, so --dry-run silently emitted plan envelopes for inputs
|
||||
// the live path would reject — agents got false-positive previews.
|
||||
package doc
|
||||
|
||||
@@ -136,8 +136,11 @@ Server-side ingestion knobs:
|
||||
cmdutil.AddDryRunFlag(cmd, &opts.DryRun)
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "Ingest a remote URL into the resolved knowledge base. KB resolved via --kb flag, WEKNORA_KB_ID env, or project link. Emits the created Knowledge object with its id.",
|
||||
RequiredFlags: []string{"<url> (positional)"},
|
||||
Output: "envelope.data is the created Knowledge object with id, knowledge_base_id, source, parse_status",
|
||||
RequiredFlags: []string{"<url> (positional)", "--kb (or WEKNORA_KB_ID / project link)"},
|
||||
Examples: []string{
|
||||
`weknora doc fetch https://example.com/whitepaper.pdf --kb kb_eng`,
|
||||
},
|
||||
Output: "envelope.data is the created Knowledge object with id, knowledge_base_id, source, parse_status",
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
|
||||
+45
-38
@@ -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,10 +103,10 @@ 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)")
|
||||
cmd.Flags().StringVar(&opts.Keyword, "keyword", "", "Server-side substring match against title / file_name (case-insensitive)")
|
||||
cmd.Flags().StringVar(&opts.FileType, "file-type", "", `Filter by file extension (e.g. "pdf", "md")`)
|
||||
cmd.Flags().StringVar(&opts.Source, "source", "", `Filter by ingestion source (e.g. "api", "web")`)
|
||||
cmd.Flags().StringVar(&opts.TagID, "tag-id", "", "Filter by tag association")
|
||||
@@ -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 returned count; meta.total_count is the server-side total before client-side --limit truncation; meta.has_more=true when --limit truncated",
|
||||
})
|
||||
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).
|
||||
|
||||
@@ -431,6 +431,45 @@ func TestList_EndTime_InvalidFormat_Rejected(t *testing.T) {
|
||||
assert.Contains(t, typed.Message, "--end-time")
|
||||
}
|
||||
|
||||
// TestList_JSON_TotalCount_SinglePage asserts that meta.total_count is populated
|
||||
// from the server total when doing a single-page fetch.
|
||||
func TestList_JSON_TotalCount_SinglePage(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &fakeListSvc{
|
||||
items: []sdk.Knowledge{{ID: "doc1", FileName: "a.pdf"}},
|
||||
total: 99,
|
||||
}
|
||||
opts := &ListOptions{PageSize: 20, Limit: 30}
|
||||
require.NoError(t, runList(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc, "kb_xxx"))
|
||||
body := out.String()
|
||||
assert.Contains(t, body, `"total_count":99`, "single-page fetch must surface server total in meta.total_count")
|
||||
}
|
||||
|
||||
// TestList_JSON_TotalCount_AllPages asserts meta.total_count is populated
|
||||
// from the server total when walking all pages.
|
||||
func TestList_JSON_TotalCount_AllPages(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &pagedDocSvc{all: makeDocs(45)}
|
||||
opts := &ListOptions{PageSize: 20, Limit: 10000, AllPages: true}
|
||||
require.NoError(t, runList(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc, "kb_xxx"))
|
||||
body := out.String()
|
||||
assert.Contains(t, body, `"total_count":45`, "--all-pages fetch must surface server total in meta.total_count")
|
||||
}
|
||||
|
||||
// TestList_JSON_TotalCount_Zero_Present asserts that when server returns total=0
|
||||
// on an empty list, meta.total_count (and meta.count) still serialize as 0. The
|
||||
// *int + omitempty pattern omits only nil, so the agent contract stays stable:
|
||||
// an empty result reports 0, not a missing key.
|
||||
func TestList_JSON_TotalCount_Zero_Present(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &fakeListSvc{items: nil, total: 0}
|
||||
opts := &ListOptions{PageSize: 20, Limit: 30}
|
||||
require.NoError(t, runList(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc, "kb_xxx"))
|
||||
body := out.String()
|
||||
assert.Contains(t, body, `"total_count":0`, "zero server total must serialize as 0 on empty list")
|
||||
assert.Contains(t, body, `"count":0`, "empty list must report count:0, not omit it")
|
||||
}
|
||||
|
||||
// TestList_AllFiltersCombined drives every new filter flag at once to confirm
|
||||
// they all land on the same filter struct (AND combine on the server).
|
||||
func TestList_AllFiltersCombined(t *testing.T) {
|
||||
|
||||
@@ -0,0 +1,96 @@
|
||||
package doc
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
|
||||
"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"
|
||||
)
|
||||
|
||||
// docReparseFields enumerates the fields surfaced for `--format json` discovery
|
||||
// on `doc reparse`. The result is the Knowledge object; the caller mainly wants
|
||||
// the id and the reset parse_status.
|
||||
var docReparseFields = []string{"id", "parse_status", "file_name", "title"}
|
||||
|
||||
// ReparseOptions captures `doc reparse` flag state.
|
||||
type ReparseOptions struct {
|
||||
DryRun bool
|
||||
}
|
||||
|
||||
// ReparseService is the narrow SDK surface this command depends on.
|
||||
type ReparseService interface {
|
||||
ReparseKnowledge(ctx context.Context, id string) (*sdk.Knowledge, error)
|
||||
}
|
||||
|
||||
// NewCmdReparse builds `weknora doc reparse <doc-id>`.
|
||||
func NewCmdReparse(f *cmdutil.Factory) *cobra.Command {
|
||||
opts := &ReparseOptions{}
|
||||
cmd := &cobra.Command{
|
||||
Use: "reparse <doc-id>",
|
||||
Short: "Re-run parsing on a document",
|
||||
Long: `Re-trigger server-side parsing of a document — the recovery path when a
|
||||
document's parse_status is failed, or after its source changed. The document
|
||||
keeps its id; parsing restarts asynchronously, so follow with
|
||||
'weknora doc wait <doc-id>' to block until it reaches a terminal status.`,
|
||||
Args: cobra.ExactArgs(1),
|
||||
RunE: func(c *cobra.Command, args []string) error {
|
||||
fopts, err := cmdutil.CheckFormatFlag(c)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
|
||||
if handled, err := cmdutil.HandleDryRun(c, opts.DryRun, cmdutil.DryRunPlan{
|
||||
Action: "doc.reparse",
|
||||
Args: map[string]any{"doc": args[0]},
|
||||
}); handled {
|
||||
return err
|
||||
}
|
||||
cli, err := f.Client()
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
return runReparse(c.Context(), opts, fopts, cli, args[0])
|
||||
},
|
||||
}
|
||||
cmdutil.AddIgnoredKBFlag(cmd)
|
||||
cmdutil.AddFormatFlag(cmd, docReparseFields...)
|
||||
cmdutil.AddDryRunFlag(cmd, &opts.DryRun)
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "re-run parsing on a document (recovery after parse_status=failed, or a changed source)",
|
||||
RequiredFlags: []string{"<doc-id> (positional)"},
|
||||
Examples: []string{
|
||||
"weknora doc reparse doc_abc",
|
||||
"weknora doc reparse doc_abc --format json",
|
||||
},
|
||||
Output: "envelope.data is the Knowledge object with parse_status reset to the re-processing state; poll `weknora doc wait <doc-id>` for completion",
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
|
||||
func runReparse(ctx context.Context, opts *ReparseOptions, fopts *cmdutil.FormatOptions, svc ReparseService, id string) error {
|
||||
k, err := svc.ReparseKnowledge(ctx, id)
|
||||
if err != nil {
|
||||
return cmdutil.WrapHTTP(err, "reparse document %s", id)
|
||||
}
|
||||
if fopts.WantsJSON() {
|
||||
return fopts.Emit(iostreams.IO.Out, k, nil)
|
||||
}
|
||||
// fileName → title, with no id fallback (empty means "skip the suffix").
|
||||
name := text.KnowledgeDisplayName(k.FileName, k.Title, "")
|
||||
w := iostreams.IO.Out
|
||||
fmt.Fprintf(w, "✓ reparse triggered for %s", id)
|
||||
if name != "" {
|
||||
fmt.Fprintf(w, " (%s)", name)
|
||||
}
|
||||
fmt.Fprintln(w)
|
||||
if k.ParseStatus != "" {
|
||||
fmt.Fprintf(w, " parse_status: %s\n", k.ParseStatus)
|
||||
}
|
||||
fmt.Fprintf(w, " next: weknora doc wait %s\n", id)
|
||||
return nil
|
||||
}
|
||||
@@ -0,0 +1,84 @@
|
||||
package doc
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"testing"
|
||||
|
||||
"github.com/stretchr/testify/assert"
|
||||
"github.com/stretchr/testify/require"
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
||||
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
||||
sdk "github.com/Tencent/WeKnora/client"
|
||||
)
|
||||
|
||||
type fakeReparseSvc struct {
|
||||
k *sdk.Knowledge
|
||||
err error
|
||||
called bool
|
||||
}
|
||||
|
||||
func (f *fakeReparseSvc) ReparseKnowledge(_ context.Context, id string) (*sdk.Knowledge, error) {
|
||||
f.called = true
|
||||
if f.err != nil {
|
||||
return nil, f.err
|
||||
}
|
||||
k := *f.k
|
||||
k.ID = id
|
||||
return &k, nil
|
||||
}
|
||||
|
||||
func TestDocReparse_Text(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &fakeReparseSvc{k: &sdk.Knowledge{FileName: "runbook.md", ParseStatus: "processing"}}
|
||||
require.NoError(t, runReparse(context.Background(), &ReparseOptions{}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc, "doc_abc"))
|
||||
assert.True(t, svc.called)
|
||||
got := out.String()
|
||||
assert.Contains(t, got, "doc_abc")
|
||||
assert.Contains(t, got, "runbook.md")
|
||||
assert.Contains(t, got, "processing")
|
||||
assert.Contains(t, got, "doc wait doc_abc")
|
||||
}
|
||||
|
||||
func TestDocReparse_JSON(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &fakeReparseSvc{k: &sdk.Knowledge{ParseStatus: "processing"}}
|
||||
require.NoError(t, runReparse(context.Background(), &ReparseOptions{}, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc, "doc_abc"))
|
||||
var env struct {
|
||||
OK bool `json:"ok"`
|
||||
Data sdk.Knowledge `json:"data"`
|
||||
}
|
||||
require.NoError(t, json.Unmarshal(out.Bytes(), &env), "got %q", out.String())
|
||||
assert.True(t, env.OK)
|
||||
assert.Equal(t, "doc_abc", env.Data.ID)
|
||||
assert.Equal(t, "processing", env.Data.ParseStatus)
|
||||
}
|
||||
|
||||
func TestDocReparse_NotFound(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
svc := &fakeReparseSvc{err: errors.New("HTTP error 404: not found")}
|
||||
err := runReparse(context.Background(), &ReparseOptions{}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc, "missing")
|
||||
require.Error(t, err)
|
||||
assert.True(t, cmdutil.IsNotFound(err))
|
||||
}
|
||||
|
||||
// TestDocReparse_DryRun_NoServerCall: --dry-run must emit a doc.reparse plan
|
||||
// (exit 0) without reaching the server, honoring the mutation-preview contract.
|
||||
func TestDocReparse_DryRun_NoServerCall(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
root := withRootHarnessDoc(NewCmdReparse(docDryRunFactory(t)), "doc_x", "--dry-run", "--format", "json")
|
||||
require.NoError(t, root.Execute(), "dry-run must succeed without a client")
|
||||
var env struct {
|
||||
OK bool `json:"ok"`
|
||||
Meta struct {
|
||||
DryRun bool `json:"dry_run"`
|
||||
Plan map[string]any `json:"plan"`
|
||||
} `json:"meta"`
|
||||
}
|
||||
require.NoError(t, json.Unmarshal(out.Bytes(), &env), "got %q", out.String())
|
||||
assert.True(t, env.OK)
|
||||
assert.True(t, env.Meta.DryRun)
|
||||
assert.Equal(t, "doc.reparse", env.Meta.Plan["action"])
|
||||
}
|
||||
@@ -0,0 +1,153 @@
|
||||
package doc
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
||||
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
||||
sdk "github.com/Tencent/WeKnora/client"
|
||||
)
|
||||
|
||||
// docUpdateFields enumerates the fields surfaced for `--format json` discovery
|
||||
// on `doc update`. The result is the updated Knowledge object.
|
||||
var docUpdateFields = []string{"id", "title", "description", "file_name", "parse_status"}
|
||||
|
||||
// UpdateOptions captures `doc update` flag state. Title/Description are *string
|
||||
// so an unset flag is distinguishable from "set to empty" — only fields the
|
||||
// user passed are changed; the rest are preserved via fetch-then-update.
|
||||
type UpdateOptions struct {
|
||||
Title *string
|
||||
Description *string
|
||||
Yes bool // sourced from global -y/--yes persistent flag
|
||||
DryRun bool
|
||||
}
|
||||
|
||||
// UpdateService is the narrow SDK surface this command depends on. The server's
|
||||
// UpdateKnowledge endpoint persists only title and description (other fields on
|
||||
// the PUT body are ignored), so this command edits just those two; GetKnowledge
|
||||
// supplies the fetch half of the fetch-then-update flow.
|
||||
type UpdateService interface {
|
||||
GetKnowledge(ctx context.Context, id string) (*sdk.Knowledge, error)
|
||||
UpdateKnowledge(ctx context.Context, k *sdk.Knowledge) error
|
||||
}
|
||||
|
||||
// NewCmdUpdate builds `weknora doc update <doc-id>`. At least one of
|
||||
// --title / --description must be provided.
|
||||
func NewCmdUpdate(f *cmdutil.Factory) *cobra.Command {
|
||||
opts := &UpdateOptions{}
|
||||
var title, desc string
|
||||
cmd := &cobra.Command{
|
||||
Use: "update <doc-id>",
|
||||
Short: "Update a document's title or description",
|
||||
Long: `Update a document's title and/or description. At least one of --title /
|
||||
--description must be supplied; the document's content, file, and parse state are
|
||||
untouched (only the title and description are editable — re-upload to change the
|
||||
content).
|
||||
|
||||
AI agents: this is a high-risk write. Without -y/--yes the CLI exits 10
|
||||
with input.confirmation_required. Never auto-pass -y; surface the prompt
|
||||
to the user first.`,
|
||||
Args: cobra.ExactArgs(1),
|
||||
RunE: func(c *cobra.Command, args []string) error {
|
||||
fopts, err := cmdutil.CheckFormatFlag(c)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
|
||||
opts.Yes, _ = c.Flags().GetBool("yes")
|
||||
if c.Flag("title").Changed {
|
||||
opts.Title = &title
|
||||
}
|
||||
if c.Flag("description").Changed {
|
||||
opts.Description = &desc
|
||||
}
|
||||
id := args[0]
|
||||
// Validate "at least one mutation flag" before the dry-run gate so
|
||||
// --dry-run rejects identically to the live path.
|
||||
if opts.Title == nil && opts.Description == nil {
|
||||
return errNoUpdateFlag()
|
||||
}
|
||||
planArgs := map[string]any{"doc": id}
|
||||
if opts.Title != nil {
|
||||
planArgs["title"] = *opts.Title
|
||||
}
|
||||
if opts.Description != nil {
|
||||
planArgs["description"] = *opts.Description
|
||||
}
|
||||
if handled, err := cmdutil.HandleDryRun(c, opts.DryRun, cmdutil.DryRunPlan{
|
||||
Action: "doc.update",
|
||||
Args: planArgs,
|
||||
}); handled {
|
||||
return err
|
||||
}
|
||||
cli, err := f.Client()
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
// Build a retry command from the flags the user actually passed so
|
||||
// agents can re-invoke with -y after explicit human approval.
|
||||
retryCmd := cmdutil.BuildRetryArgv(c, []string{"weknora", "doc", "update", id}, "title", "description", "format")
|
||||
if err := cmdutil.ConfirmWrite(f.Prompter(), opts.Yes, fopts.WantsJSON(), "update", "document", id, "doc.update", retryCmd); err != nil {
|
||||
return err
|
||||
}
|
||||
return runUpdate(c.Context(), opts, fopts, cli, id)
|
||||
},
|
||||
}
|
||||
cmd.Flags().StringVar(&title, "title", "", "New title (omit to leave unchanged)")
|
||||
cmd.Flags().StringVar(&desc, "description", "", "New description (omit to leave unchanged)")
|
||||
cmdutil.AddIgnoredKBFlag(cmd)
|
||||
cmdutil.AddFormatFlag(cmd, docUpdateFields...)
|
||||
cmdutil.AddDryRunFlag(cmd, &opts.DryRun)
|
||||
cmdutil.SetWriteRisk(cmd, "doc.update")
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "update a document's title or description (content is not editable — re-upload for that)",
|
||||
RequiredFlags: []string{"<doc-id> (positional)", "--title or --description (at least one)"},
|
||||
Examples: []string{
|
||||
`weknora doc update doc_abc --title "Q3 Runbook" -y`,
|
||||
`weknora doc update doc_abc --description "archived" --format json -y`,
|
||||
},
|
||||
Output: "envelope.data is the Knowledge object with the new title/description",
|
||||
Warnings: []string{
|
||||
"Requires explicit user approval (exit 10 / input.confirmation_required); never auto-add -y.",
|
||||
},
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
|
||||
func errNoUpdateFlag() error {
|
||||
return &cmdutil.Error{
|
||||
Code: cmdutil.CodeInputMissingFlag,
|
||||
Message: "doc update requires at least one of --title or --description",
|
||||
Hint: "pass --title <title> and/or --description <desc>",
|
||||
}
|
||||
}
|
||||
|
||||
func runUpdate(ctx context.Context, opts *UpdateOptions, fopts *cmdutil.FormatOptions, svc UpdateService, id string) error {
|
||||
if opts.Title == nil && opts.Description == nil {
|
||||
return errNoUpdateFlag()
|
||||
}
|
||||
// Fetch-then-update: load the current record, overlay only the fields the
|
||||
// user set, and PUT the whole object. TOCTOU note: a concurrent writer could
|
||||
// change the record between the Get and Put (same window as kb update).
|
||||
current, err := svc.GetKnowledge(ctx, id)
|
||||
if err != nil {
|
||||
return cmdutil.WrapHTTP(err, "fetch document %s", id)
|
||||
}
|
||||
if opts.Title != nil {
|
||||
current.Title = *opts.Title
|
||||
}
|
||||
if opts.Description != nil {
|
||||
current.Description = *opts.Description
|
||||
}
|
||||
if err := svc.UpdateKnowledge(ctx, current); err != nil {
|
||||
return cmdutil.WrapHTTP(err, "update document %s", id)
|
||||
}
|
||||
if fopts.WantsJSON() {
|
||||
return fopts.Emit(iostreams.IO.Out, current, nil)
|
||||
}
|
||||
fmt.Fprintf(iostreams.IO.Out, "✓ Updated document %s\n", id)
|
||||
return nil
|
||||
}
|
||||
@@ -0,0 +1,137 @@
|
||||
package doc
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"testing"
|
||||
|
||||
"github.com/stretchr/testify/assert"
|
||||
"github.com/stretchr/testify/require"
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
||||
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
||||
"github.com/Tencent/WeKnora/cli/internal/prompt"
|
||||
sdk "github.com/Tencent/WeKnora/client"
|
||||
)
|
||||
|
||||
type fakeUpdateSvc struct {
|
||||
current *sdk.Knowledge
|
||||
getErr error
|
||||
updateErr error
|
||||
got *sdk.Knowledge // captured object passed to UpdateKnowledge
|
||||
}
|
||||
|
||||
func (f *fakeUpdateSvc) GetKnowledge(_ context.Context, id string) (*sdk.Knowledge, error) {
|
||||
if f.getErr != nil {
|
||||
return nil, f.getErr
|
||||
}
|
||||
c := *f.current
|
||||
c.ID = id
|
||||
return &c, nil
|
||||
}
|
||||
|
||||
func (f *fakeUpdateSvc) UpdateKnowledge(_ context.Context, k *sdk.Knowledge) error {
|
||||
f.got = k
|
||||
return f.updateErr
|
||||
}
|
||||
|
||||
func strptr(s string) *string { return &s }
|
||||
|
||||
func TestDocUpdate_Title_FetchThenUpdate(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &fakeUpdateSvc{current: &sdk.Knowledge{Title: "Old", Description: "keep", FileName: "f.md"}}
|
||||
require.NoError(t, runUpdate(context.Background(),
|
||||
&UpdateOptions{Title: strptr("New")}, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc, "doc_abc"))
|
||||
// Only title changed; description preserved from the fetched record.
|
||||
require.NotNil(t, svc.got)
|
||||
assert.Equal(t, "New", svc.got.Title)
|
||||
assert.Equal(t, "keep", svc.got.Description)
|
||||
var env struct {
|
||||
OK bool `json:"ok"`
|
||||
Data sdk.Knowledge `json:"data"`
|
||||
}
|
||||
require.NoError(t, json.Unmarshal(out.Bytes(), &env), "got %q", out.String())
|
||||
assert.True(t, env.OK)
|
||||
assert.Equal(t, "doc_abc", env.Data.ID)
|
||||
assert.Equal(t, "New", env.Data.Title)
|
||||
}
|
||||
|
||||
func TestDocUpdate_DescriptionOnly_PreservesTitle(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
svc := &fakeUpdateSvc{current: &sdk.Knowledge{Title: "Keep", Description: "old"}}
|
||||
require.NoError(t, runUpdate(context.Background(),
|
||||
&UpdateOptions{Description: strptr("fresh")}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc, "doc_abc"))
|
||||
assert.Equal(t, "Keep", svc.got.Title)
|
||||
assert.Equal(t, "fresh", svc.got.Description)
|
||||
}
|
||||
|
||||
func TestDocUpdate_NoFlags_MissingFlag(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
svc := &fakeUpdateSvc{current: &sdk.Knowledge{}}
|
||||
err := runUpdate(context.Background(), &UpdateOptions{}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc, "doc_abc")
|
||||
var typed *cmdutil.Error
|
||||
require.True(t, errors.As(err, &typed))
|
||||
assert.Equal(t, cmdutil.CodeInputMissingFlag, typed.Code)
|
||||
assert.Nil(t, svc.got, "must not call UpdateKnowledge when no flag is set")
|
||||
}
|
||||
|
||||
func TestDocUpdate_NotFound(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
svc := &fakeUpdateSvc{getErr: errors.New("HTTP error 404: not found")}
|
||||
err := runUpdate(context.Background(),
|
||||
&UpdateOptions{Title: strptr("x")}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc, "missing")
|
||||
require.Error(t, err)
|
||||
assert.True(t, cmdutil.IsNotFound(err))
|
||||
}
|
||||
|
||||
// TestDocUpdate_DryRun_NoServerCall: --dry-run emits a doc.update plan (exit 0)
|
||||
// without reaching the server.
|
||||
func TestDocUpdate_DryRun_NoServerCall(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
root := withRootHarnessDoc(NewCmdUpdate(docDryRunFactory(t)), "doc_x", "--title", "T", "--dry-run", "--format", "json")
|
||||
require.NoError(t, root.Execute(), "dry-run must succeed without a client")
|
||||
var env struct {
|
||||
OK bool `json:"ok"`
|
||||
Meta struct {
|
||||
DryRun bool `json:"dry_run"`
|
||||
Plan map[string]any `json:"plan"`
|
||||
} `json:"meta"`
|
||||
}
|
||||
require.NoError(t, json.Unmarshal(out.Bytes(), &env), "got %q", out.String())
|
||||
assert.True(t, env.Meta.DryRun)
|
||||
assert.Equal(t, "doc.update", env.Meta.Plan["action"])
|
||||
}
|
||||
|
||||
// TestDocUpdate_RequiresConfirmation asserts that without -y (non-TTY / JSON
|
||||
// mode), doc update returns input.confirmation_required (exit 10) — parity with
|
||||
// kb/agent update gating (AGENTS.md §3.1: all three updates are confirmation-gated).
|
||||
func TestDocUpdate_RequiresConfirmation(t *testing.T) {
|
||||
iostreams.SetForTest(t) // non-TTY
|
||||
f := &cmdutil.Factory{
|
||||
Client: func() (*sdk.Client, error) { return nil, nil },
|
||||
Prompter: func() prompt.Prompter { return prompt.AgentPrompter{} },
|
||||
}
|
||||
root := withRootHarnessDoc(NewCmdUpdate(f), "doc_abc", "--title", "New", "--format", "json")
|
||||
err := root.Execute()
|
||||
require.Error(t, err)
|
||||
var ce *cmdutil.Error
|
||||
require.ErrorAs(t, err, &ce)
|
||||
assert.Equal(t, cmdutil.CodeInputConfirmationRequired, ce.Code)
|
||||
assert.Equal(t, 10, cmdutil.ExitCode(err))
|
||||
// retry argv must include -y and the target id
|
||||
assert.Contains(t, ce.RetryArgv, "-y")
|
||||
assert.Contains(t, ce.RetryArgv, "doc_abc")
|
||||
}
|
||||
|
||||
// TestDocUpdate_DryRun_RejectsNoFlag: --dry-run rejects the no-mutation-flag
|
||||
// invocation identically to the live path (validation before the dry-run gate).
|
||||
func TestDocUpdate_DryRun_RejectsNoFlag(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
root := withRootHarnessDoc(NewCmdUpdate(docDryRunFactory(t)), "doc_x", "--dry-run", "--format", "json")
|
||||
err := root.Execute()
|
||||
require.Error(t, err, "dry-run must reject identically to live path")
|
||||
var typed *cmdutil.Error
|
||||
require.True(t, errors.As(err, &typed))
|
||||
assert.Equal(t, cmdutil.CodeInputMissingFlag, typed.Code)
|
||||
}
|
||||
@@ -191,8 +191,12 @@ Server-side ingestion knobs:
|
||||
cmdutil.AddDryRunFlag(cmd, &opts.DryRun)
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "Upload a local file to the resolved knowledge base. KB resolved via --kb flag, WEKNORA_KB_ID env, or project link. Emits the created Knowledge object with its id.",
|
||||
RequiredFlags: []string{"<file> (positional)"},
|
||||
Output: "envelope.data is the created Knowledge object with id, knowledge_base_id, file_name, parse_status",
|
||||
RequiredFlags: []string{"<file> (positional)", "--kb (or WEKNORA_KB_ID / project link)"},
|
||||
Examples: []string{
|
||||
`weknora doc upload report.pdf --kb kb_eng`,
|
||||
`weknora doc upload report.pdf --kb kb_eng --jq .data.id # then: doc wait <id>`,
|
||||
},
|
||||
Output: "envelope.data is the created Knowledge object with id, knowledge_base_id, file_name, parse_status",
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
|
||||
@@ -81,16 +81,11 @@ func runUploadRecursive(ctx context.Context, opts *UploadOptions, fopts *cmdutil
|
||||
// uploaded captures per-path server results for successful uploads.
|
||||
// Populated by the RunBatch closure; read by the resultFn below.
|
||||
uploaded := make(map[string]uploadedFile, len(matches))
|
||||
var firstFailCode cmdutil.ErrorCode
|
||||
channel := cmp.Or(opts.Channel, uploadChannel)
|
||||
|
||||
outcomes, runErr := cmdutil.RunBatch(ctx, matches, func(ctx context.Context, p string) error {
|
||||
k, err := svc.CreateKnowledgeFromFile(ctx, kbID, p, meta, opts.EnableMultimodel, "", channel, nil)
|
||||
if err != nil {
|
||||
code := cmdutil.ClassifyHTTPError(err)
|
||||
if firstFailCode == "" {
|
||||
firstFailCode = code
|
||||
}
|
||||
// Per-file progress lines are human progress signal; suppress
|
||||
// under --format json so they don't precede the JSON object on stdout.
|
||||
if !fopts.WantsJSON() {
|
||||
@@ -133,9 +128,15 @@ func runUploadRecursive(ctx context.Context, opts *UploadOptions, fopts *cmdutil
|
||||
// carries per-file detail; without Silent the root error handler would
|
||||
// print to stderr in addition. ExitCode still walks Code so the typed
|
||||
// exit-code-by-class contract holds.
|
||||
code := firstFailCode
|
||||
if code == "" {
|
||||
code = cmdutil.ClassifyContextErr(ctx.Err())
|
||||
// Any per-file failure collapses to operation.failed (exit 1) — the
|
||||
// per-file batch envelope carries each file's typed error, which is the
|
||||
// authoritative signal (matches doc/session/chunk batch delete). A
|
||||
// cancelled / timed-out batch keeps its context class (124 / 130) so a
|
||||
// permanent partial failure (e.g. a duplicate) is never misreported as a
|
||||
// retryable 5xx that an agent would loop on.
|
||||
code := cmdutil.CodeOperationFailed
|
||||
if ctxErr := ctx.Err(); ctxErr != nil {
|
||||
code = cmdutil.ClassifyContextErr(ctxErr)
|
||||
}
|
||||
return &cmdutil.Error{
|
||||
Code: code,
|
||||
|
||||
@@ -109,9 +109,12 @@ func TestUploadRecursive_PartialFailure_Exits1(t *testing.T) {
|
||||
|
||||
var typed *cmdutil.Error
|
||||
require.ErrorAs(t, err, &typed)
|
||||
// CodeServerError preserves the 500 classification of the underlying
|
||||
// SDK error - the recursive wrapper just aggregates.
|
||||
assert.Equal(t, cmdutil.CodeServerError, typed.Code)
|
||||
// Any per-file failure aggregates to operation.failed (exit 1), matching the
|
||||
// batch-delete contract — a partial failure (even a permanent one like a
|
||||
// duplicate, which classifies as server.error per-file) must not surface as
|
||||
// a retryable exit 7 an agent would loop on. Per-file codes live in the
|
||||
// batch envelope.
|
||||
assert.Equal(t, cmdutil.CodeOperationFailed, typed.Code)
|
||||
|
||||
got := out.String()
|
||||
assert.Contains(t, got, "OK") // ok.pdf still succeeded
|
||||
@@ -267,5 +270,5 @@ func TestUploadRecursive_JSON_BatchEnvelope(t *testing.T) {
|
||||
var typed *cmdutil.Error
|
||||
require.ErrorAs(t, err, &typed)
|
||||
assert.True(t, typed.Silent, "JSON-path partial failure must be Silent")
|
||||
assert.Equal(t, cmdutil.CodeServerError, typed.Code)
|
||||
assert.Equal(t, cmdutil.CodeOperationFailed, typed.Code)
|
||||
}
|
||||
|
||||
@@ -52,6 +52,7 @@ func NewCmdView(f *cmdutil.Factory) *cobra.Command {
|
||||
},
|
||||
}
|
||||
cmdutil.AddFormatFlag(cmd, docViewFields...)
|
||||
cmdutil.AddIgnoredKBFlag(cmd)
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "fetch one document's metadata by id",
|
||||
RequiredFlags: []string{"<doc-id> (positional)"},
|
||||
|
||||
@@ -94,6 +94,7 @@ For fail-fast semantics, use shell composition:
|
||||
cmd.Flags().DurationVar(&opts.Timeout, "timeout", 10*time.Minute, "Max wait time before exiting 124")
|
||||
cmd.Flags().DurationVar(&opts.Interval, "interval", 2*time.Second, "Initial poll interval; exponential backoff capped at 15s + jitter")
|
||||
cmdutil.AddFormatFlag(cmd)
|
||||
cmdutil.AddIgnoredKBFlag(cmd)
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "block until one or more documents reach a terminal parse state (completed or failed), or --timeout elapses",
|
||||
RequiredFlags: []string{"<doc-id>... (one or more positionals)"},
|
||||
@@ -234,6 +235,14 @@ func waitForDocs(ctx context.Context, ids []string, svc WaitService, opts WaitOp
|
||||
case "failed":
|
||||
addFailed(FailedDoc{ID: id, Message: doc.ErrorMessage})
|
||||
return
|
||||
case "draft":
|
||||
// draft = created but NOT queued for parsing (inline
|
||||
// `doc create` leaves docs here; file `doc upload`
|
||||
// auto-enqueues). It never progresses on its own, so
|
||||
// waiting would hang to the --timeout (124). Fail fast with
|
||||
// the exact unblock command instead of silently polling.
|
||||
addFailed(FailedDoc{ID: id, Message: "parse_status=draft: not queued for parsing — run `weknora doc reparse " + id + "` to index it"})
|
||||
return
|
||||
}
|
||||
|
||||
// Not yet terminal — sleep with jitter, then exp-backoff.
|
||||
|
||||
@@ -311,3 +311,30 @@ func TestDocWait_FailureError_IsSilent(t *testing.T) {
|
||||
t.Errorf("exit code = %d, want 1", cmdutil.ExitCode(err))
|
||||
}
|
||||
}
|
||||
|
||||
// TestWaitForDocs_DraftFailsFast pins that a document stuck in parse_status
|
||||
// "draft" (inline `doc create` leaves docs here; it never auto-progresses) is
|
||||
// failed fast with a reparse hint instead of polling until the --timeout.
|
||||
// Regression: `doc create` + `doc wait` used to hang to a 124 timeout.
|
||||
func TestWaitForDocs_DraftFailsFast(t *testing.T) {
|
||||
svc := newFakeKBSvc(map[string][]string{
|
||||
"doc_draft": {"draft", "draft", "draft"},
|
||||
})
|
||||
start := time.Now()
|
||||
res, _ := waitForDocs(context.Background(), []string{"doc_draft"}, svc, WaitOptions{
|
||||
Timeout: 5 * time.Second,
|
||||
Interval: 1 * time.Millisecond,
|
||||
})
|
||||
if len(res.Timeout) != 0 {
|
||||
t.Errorf("draft must NOT time out; got timeout=%v", res.Timeout)
|
||||
}
|
||||
if len(res.Failed) != 1 || res.Failed[0].ID != "doc_draft" {
|
||||
t.Fatalf("draft doc must be failed-fast; got failed=%v", res.Failed)
|
||||
}
|
||||
if !strings.Contains(res.Failed[0].Message, "reparse") {
|
||||
t.Errorf("draft failure message must point to reparse; got %q", res.Failed[0].Message)
|
||||
}
|
||||
if elapsed := time.Since(start); elapsed > time.Second {
|
||||
t.Errorf("draft must fail fast (well under timeout); took %v", elapsed)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -24,6 +24,7 @@ import (
|
||||
"fmt"
|
||||
"net/http"
|
||||
"os"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
@@ -31,6 +32,7 @@ import (
|
||||
"github.com/Tencent/WeKnora/cli/internal/build"
|
||||
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
||||
"github.com/Tencent/WeKnora/cli/internal/compat"
|
||||
"github.com/Tencent/WeKnora/cli/internal/config"
|
||||
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
||||
"github.com/Tencent/WeKnora/cli/internal/secrets"
|
||||
sdk "github.com/Tencent/WeKnora/client"
|
||||
@@ -132,7 +134,7 @@ func NewCmd(f *cmdutil.Factory) *cobra.Command {
|
||||
"weknora doctor --offline",
|
||||
"weknora doctor --no-cache --format json",
|
||||
},
|
||||
Output: "envelope.data is {summary:{all_passed,passed,failed,skipped}, checks:[{name,status,detail}]}",
|
||||
Output: "envelope.data is {summary:{all_passed,passed,warned,failed,skipped}, checks:[{name,status,details,hint?}]}",
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
@@ -396,15 +398,38 @@ func buildServices(f *cmdutil.Factory) (Services, error) {
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return &realServices{f: f, host: resolveDoctorHost(cfg)}, nil
|
||||
}
|
||||
|
||||
// resolveDoctorHost picks the host base_url_reachable probes. Tiers 2 and 3
|
||||
// mirror the client builder (buildClientFromEnv) so doctor probes the host the
|
||||
// real commands actually connect to; tier 1 is a doctor-local test/dev knob:
|
||||
//
|
||||
// 1. WEKNORA_BASE_URL — doctor-only probe override (used by tests); NOT read
|
||||
// by the client builder, so setting it points doctor at a host no real
|
||||
// command uses. Kept for test/dev harnesses; leave unset in normal use.
|
||||
// 2. WEKNORA_HOST — when stateless env credentials (WEKNORA_TOKEN /
|
||||
// WEKNORA_API_KEY) are in effect, i.e. the headless agent path. Without
|
||||
// this, `WEKNORA_API_KEY=… WEKNORA_HOST=… weknora doctor` falsely reported
|
||||
// "no host configured" and exited 1 while every other command worked.
|
||||
// 3. active profile host — the configured default.
|
||||
func resolveDoctorHost(cfg *config.Config) string {
|
||||
host := ""
|
||||
if ctx, ok := cfg.Profiles[cfg.CurrentProfile]; ok {
|
||||
host = ctx.Host
|
||||
}
|
||||
// WEKNORA_BASE_URL still wins as a test/dev override; production reads host.
|
||||
// Env credentials authenticate via WEKNORA_HOST, bypassing the profile.
|
||||
// Honor it only when such creds are actually set, matching the client
|
||||
// builder (a bare WEKNORA_HOST without creds is ignored there too).
|
||||
if envActive, _ := cmdutil.EnvCredential(); envActive {
|
||||
if v := strings.TrimSpace(os.Getenv("WEKNORA_HOST")); v != "" {
|
||||
host = v
|
||||
}
|
||||
}
|
||||
if v := os.Getenv("WEKNORA_BASE_URL"); v != "" {
|
||||
host = v
|
||||
}
|
||||
return &realServices{f: f, host: host}, nil
|
||||
return host
|
||||
}
|
||||
|
||||
type realServices struct {
|
||||
|
||||
@@ -10,6 +10,7 @@ import (
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
||||
"github.com/Tencent/WeKnora/cli/internal/compat"
|
||||
"github.com/Tencent/WeKnora/cli/internal/config"
|
||||
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
||||
"github.com/Tencent/WeKnora/cli/internal/secrets"
|
||||
sdk "github.com/Tencent/WeKnora/client"
|
||||
@@ -507,3 +508,54 @@ func TestDoctor_RunE_WarnReturnsNil(t *testing.T) {
|
||||
t.Fatalf("setup error: expected Warned>=1, got %+v", r.Summary)
|
||||
}
|
||||
}
|
||||
|
||||
// TestResolveDoctorHost_EnvCredentials - doctor's base_url probe must honor
|
||||
// WEKNORA_HOST when stateless env credentials are in effect (the headless
|
||||
// agent path), mirroring buildClientFromEnv. Regression: doctor previously
|
||||
// read only the active profile host, so `WEKNORA_API_KEY=... WEKNORA_HOST=...
|
||||
// weknora doctor` reported "no host configured" and exited 1 while every
|
||||
// other command worked.
|
||||
func TestResolveDoctorHost_EnvCredentials(t *testing.T) {
|
||||
cfg := &config.Config{
|
||||
CurrentProfile: "prod",
|
||||
Profiles: map[string]config.Profile{"prod": {Host: "https://profile-host"}},
|
||||
}
|
||||
|
||||
t.Run("env creds + WEKNORA_HOST wins over profile", func(t *testing.T) {
|
||||
t.Setenv("WEKNORA_TOKEN", "")
|
||||
t.Setenv("WEKNORA_API_KEY", "sk-test")
|
||||
t.Setenv("WEKNORA_HOST", "https://env-host:8080")
|
||||
t.Setenv("WEKNORA_BASE_URL", "")
|
||||
if got := resolveDoctorHost(cfg); got != "https://env-host:8080" {
|
||||
t.Errorf("want env host, got %q", got)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("env creds without WEKNORA_HOST falls back to profile", func(t *testing.T) {
|
||||
t.Setenv("WEKNORA_API_KEY", "sk-test")
|
||||
t.Setenv("WEKNORA_HOST", "")
|
||||
t.Setenv("WEKNORA_BASE_URL", "")
|
||||
if got := resolveDoctorHost(cfg); got != "https://profile-host" {
|
||||
t.Errorf("want profile host, got %q", got)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("no env creds ignores WEKNORA_HOST (matches client builder)", func(t *testing.T) {
|
||||
t.Setenv("WEKNORA_TOKEN", "")
|
||||
t.Setenv("WEKNORA_API_KEY", "")
|
||||
t.Setenv("WEKNORA_HOST", "https://should-be-ignored")
|
||||
t.Setenv("WEKNORA_BASE_URL", "")
|
||||
if got := resolveDoctorHost(cfg); got != "https://profile-host" {
|
||||
t.Errorf("want profile host, got %q", got)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("WEKNORA_BASE_URL test override always wins", func(t *testing.T) {
|
||||
t.Setenv("WEKNORA_API_KEY", "sk-test")
|
||||
t.Setenv("WEKNORA_HOST", "https://env-host")
|
||||
t.Setenv("WEKNORA_BASE_URL", "https://base-url-override")
|
||||
if got := resolveDoctorHost(cfg); got != "https://base-url-override" {
|
||||
t.Errorf("want base-url override, got %q", got)
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
@@ -20,12 +20,17 @@ import (
|
||||
// decision rather than silently inheriting "no preview".
|
||||
var dryRunExpectation = map[string]bool{
|
||||
// --- mutations: MUST have --dry-run ---
|
||||
"kb create": true, "kb edit": true, "kb delete": true, "kb pin": true, "kb unpin": true,
|
||||
"kb create": true, "kb update": true, "kb delete": true, "kb pin": true, "kb unpin": true,
|
||||
"kb config set": true, // binds models to a KB (state change)
|
||||
"model create": true, "model update": true, "model delete": true,
|
||||
"doc create": true, "doc upload": true, "doc fetch": true, "doc delete": true,
|
||||
"chunk delete": true,
|
||||
"session delete": true, "session stop": true,
|
||||
"agent create": true, "agent edit": true, "agent delete": true,
|
||||
"doc reparse": true, // re-triggers server-side parsing (a state change)
|
||||
"doc update": true, // edits title/description server-side
|
||||
"chunk delete": true, "message delete": true,
|
||||
"session delete": true, "session stop": true, "session tool-approval resolve": true,
|
||||
"agent create": true, "agent update": true, "agent delete": true,
|
||||
"profile add": true, "profile use": true, "profile remove": true,
|
||||
"skills install": true, // writes skill files to a local dir (state change)
|
||||
"auth logout": true, "auth refresh": true,
|
||||
"link": true, "unlink": true,
|
||||
"api": true, // passthrough: dry-run previews write methods, rejected on GET
|
||||
@@ -33,24 +38,54 @@ var dryRunExpectation = map[string]bool{
|
||||
// --- exempt: no state change to preview ---
|
||||
// reads
|
||||
"kb list": false, "kb view": false, "kb status": false, "kb check": false,
|
||||
"kb config": false, // read-only inspection of a KB's model config
|
||||
"doc list": false, "doc view": false, "doc download": false,
|
||||
"doc wait": false, // polling read, no mutation
|
||||
"chunk list": false, "chunk view": false,
|
||||
"message list": false, "message search": false,
|
||||
"session list": false, "session view": false,
|
||||
"agent list": false, "agent view": false, "agent status": false, "agent check": false,
|
||||
"model list": false, "model view": false,
|
||||
"search chunks": false, "search docs": false, "search kb": false, "search sessions": false,
|
||||
"auth list": false, "auth status": false, "auth token": false,
|
||||
"profile list": false,
|
||||
"doctor": false, "version": false,
|
||||
"skills list": false, // read-only: lists the embedded skills
|
||||
// read-only inspection of the resolved config; no mutation, no network.
|
||||
"config view": false,
|
||||
"doctor": false, "version": false,
|
||||
// generate / stream ops — the session-creation side effect is incidental,
|
||||
// not a CRUD write; a no-SDK-call preview would be meaningless.
|
||||
"chat": false, "session ask": false, "session continue-stream": false,
|
||||
"chat": false, "session ask": false, "session resume": false,
|
||||
// auth login VALIDATES credentials against the server and stores them; its
|
||||
// whole purpose is the server round-trip, which a side-effect-free dry-run
|
||||
// cannot exercise — so previewing it would be misleading. Exempt by design.
|
||||
"auth login": false,
|
||||
// long-running stdio server, not a one-shot command.
|
||||
"mcp serve": false,
|
||||
// offline help topic: prints the static exit-code matrix.
|
||||
"exit-codes": false,
|
||||
// offline introspection: prints command contracts from the in-binary tree.
|
||||
"schema": false,
|
||||
}
|
||||
|
||||
// TestIdAddressedCommandsTolerateKB pins that the id-addressed read/wait
|
||||
// commands accept a (redundant, ignored) --kb flag, so an agent flowing from
|
||||
// `doc upload --kb X` into `doc wait <id> --kb X` doesn't hit exit 2.
|
||||
func TestIdAddressedCommandsTolerateKB(t *testing.T) {
|
||||
root := NewRootCmd(cmdutil.New())
|
||||
for _, path := range [][]string{
|
||||
{"doc", "view"}, {"doc", "wait"}, {"doc", "download"},
|
||||
{"doc", "reparse"}, {"doc", "update"},
|
||||
{"chunk", "list"}, {"chunk", "view"}, {"chunk", "delete"},
|
||||
} {
|
||||
c, _, err := root.Find(path)
|
||||
if err != nil {
|
||||
t.Fatalf("find %v: %v", path, err)
|
||||
}
|
||||
if c.Flags().Lookup("kb") == nil {
|
||||
t.Errorf("`%s` must accept a --kb flag (ignored) so a carried-over --kb doesn't error", strings.Join(path, " "))
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestDryRunCoverageMatchesExpectation(t *testing.T) {
|
||||
|
||||
@@ -0,0 +1,84 @@
|
||||
package cmd
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"strings"
|
||||
"text/tabwriter"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
||||
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
||||
"github.com/Tencent/WeKnora/cli/internal/output"
|
||||
)
|
||||
|
||||
type exitCodeRow struct {
|
||||
Code int `json:"code"`
|
||||
Meaning string `json:"meaning"`
|
||||
ErrorTypes string `json:"error_types,omitempty"`
|
||||
AgentAction string `json:"agent_action"`
|
||||
}
|
||||
|
||||
func exitCodeRows() []exitCodeRow {
|
||||
return []exitCodeRow{
|
||||
{0, "success", "", "continue"},
|
||||
{1, "typed local.* / operation.failed / unclassified", "local.*, operation.failed, operation.cancelled, server.session_create_failed, internal.error", "read stderr, decide retry/abort"},
|
||||
{2, "flag / argument validation error (cobra parse: unknown flag, arg count, missing required flag)", "input.invalid_argument (same type as exit 5; distinguish by exit code)", "re-check weknora <cmd> --help"},
|
||||
{3, "authentication / authorization", "auth.*", "re-auth (weknora auth login), then retry"},
|
||||
{4, "resource not found", "resource.not_found", "verify the resource id"},
|
||||
{5, "invalid input value (typed validation, not a parse error)", "input.* (other than confirmation_required)", "adjust args, retry"},
|
||||
{6, "rate limited", "server.rate_limited", "back off, retry"},
|
||||
{7, "server / network error", "server.* (excl. rate_limited→6, session_create_failed→1), network.*", "transient — retry with backoff"},
|
||||
{10, "confirmation required (high-risk write)", "input.confirmation_required", "ask the human; retry with -y only after explicit approval"},
|
||||
{124, "operation timeout", "operation.timeout", "raise --timeout or check the underlying job"},
|
||||
{130, "cancelled by signal (SIGINT/SIGTERM)", "", "stop, do not retry"},
|
||||
}
|
||||
}
|
||||
|
||||
// newCmdExitCodes builds the `weknora exit-codes` help-topic command.
|
||||
// `weknora help exit-codes` renders Long for humans; running it directly
|
||||
// emits the machine-readable matrix (json by default, per the agent-first
|
||||
// output contract). Listed in the command tree (not hidden) so humans have a
|
||||
// discoverable path to it via `weknora help`, not only the README.
|
||||
func newCmdExitCodes() *cobra.Command {
|
||||
cmd := &cobra.Command{
|
||||
Use: "exit-codes",
|
||||
Short: "Exit code matrix and the agent action for each",
|
||||
Args: cobra.NoArgs,
|
||||
RunE: func(c *cobra.Command, _ []string) error {
|
||||
fopts, err := cmdutil.CheckFormatFlag(c)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
|
||||
rows := exitCodeRows()
|
||||
if fopts.WantsJSON() {
|
||||
return fopts.Emit(iostreams.IO.Out, rows, &output.Meta{Count: output.IntPtr(len(rows))})
|
||||
}
|
||||
tw := tabwriter.NewWriter(iostreams.IO.Out, 0, 0, 2, ' ', 0)
|
||||
fmt.Fprintln(tw, "CODE\tMEANING\tERROR TYPES\tAGENT ACTION")
|
||||
for _, r := range rows {
|
||||
fmt.Fprintf(tw, "%d\t%s\t%s\t%s\n", r.Code, r.Meaning, r.ErrorTypes, r.AgentAction)
|
||||
}
|
||||
return tw.Flush()
|
||||
},
|
||||
}
|
||||
cmdutil.AddFormatFlag(cmd, "code", "meaning", "error_types", "agent_action")
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "Machine-readable exit code matrix: what each code means and what to do next.",
|
||||
Examples: []string{"weknora exit-codes", "weknora help exit-codes"},
|
||||
Output: "envelope.data is an array of {code, meaning, error_types, agent_action}",
|
||||
})
|
||||
cmd.Long = "Exit codes and the agent action for each:\n\n" + exitCodesLongTable()
|
||||
return cmd
|
||||
}
|
||||
|
||||
func exitCodesLongTable() string {
|
||||
var sb strings.Builder
|
||||
tw := tabwriter.NewWriter(&sb, 0, 0, 2, ' ', 0)
|
||||
for _, r := range exitCodeRows() {
|
||||
fmt.Fprintf(tw, " %d\t%s\t%s\n", r.Code, r.Meaning, r.AgentAction)
|
||||
}
|
||||
tw.Flush()
|
||||
return sb.String()
|
||||
}
|
||||
@@ -0,0 +1,99 @@
|
||||
package cmd
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/stretchr/testify/assert"
|
||||
"github.com/stretchr/testify/require"
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
||||
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
||||
)
|
||||
|
||||
func TestExitCodesRows_CoversDocumentedMatrix(t *testing.T) {
|
||||
rows := exitCodeRows()
|
||||
codes := make([]int, 0, len(rows))
|
||||
for _, r := range rows {
|
||||
require.NotEmpty(t, r.Meaning)
|
||||
require.NotEmpty(t, r.AgentAction)
|
||||
codes = append(codes, r.Code)
|
||||
}
|
||||
assert.Equal(t, []int{0, 1, 2, 3, 4, 5, 6, 7, 10, 124, 130}, codes)
|
||||
}
|
||||
|
||||
// TestExitCodesRows_MatrixSnapshot guards key rows against silent drift.
|
||||
func TestExitCodesRows_MatrixSnapshot(t *testing.T) {
|
||||
byCode := map[int]exitCodeRow{}
|
||||
for _, r := range exitCodeRows() {
|
||||
byCode[r.Code] = r
|
||||
}
|
||||
|
||||
// exit 130 — produced by main.go signal guard, not ExitCode(); no typed code routes here
|
||||
r130 := byCode[130]
|
||||
assert.Equal(t, "cancelled by signal (SIGINT/SIGTERM)", r130.Meaning)
|
||||
assert.Equal(t, "", r130.ErrorTypes, "exit 130 must have empty ErrorTypes (omitempty)")
|
||||
assert.Equal(t, "stop, do not retry", r130.AgentAction)
|
||||
|
||||
// exit 1 — fallback bucket; operation.cancelled typed errors land here
|
||||
r1 := byCode[1]
|
||||
assert.Contains(t, r1.ErrorTypes, "operation.cancelled")
|
||||
assert.Contains(t, r1.ErrorTypes, "server.session_create_failed")
|
||||
assert.Contains(t, r1.ErrorTypes, "local.*")
|
||||
|
||||
// exit 7 — server transient, excluding the two special-cased server codes
|
||||
r7 := byCode[7]
|
||||
assert.Contains(t, r7.ErrorTypes, "network.*")
|
||||
assert.Contains(t, r7.ErrorTypes, "rate_limited→6")
|
||||
assert.Contains(t, r7.ErrorTypes, "session_create_failed→1")
|
||||
}
|
||||
|
||||
func TestExitCodes_JSONOutput(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
root := NewRootCmd(cmdutil.New())
|
||||
root.SetArgs([]string{"exit-codes", "--format", "json"})
|
||||
root.SetOut(&bytes.Buffer{}) // discard cobra's writer; real output goes to iostreams.IO.Out
|
||||
root.SetErr(&bytes.Buffer{})
|
||||
require.NoError(t, root.Execute())
|
||||
|
||||
got := out.String()
|
||||
// Must contain the envelope key for code 10
|
||||
assert.Contains(t, got, `"code":10`, "JSON output must include code 10")
|
||||
// Must contain the count
|
||||
assert.Contains(t, got, `"count":11`, "JSON output must include count:11")
|
||||
// Must contain exit 130 (signal-guard exit)
|
||||
assert.Contains(t, got, `"code":130`, "JSON output must include code 130")
|
||||
}
|
||||
|
||||
func TestExitCodes_TextOutput(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
root := NewRootCmd(cmdutil.New())
|
||||
root.SetArgs([]string{"exit-codes", "--format", "text"})
|
||||
root.SetOut(&bytes.Buffer{}) // discard cobra's writer; real output goes to iostreams.IO.Out
|
||||
root.SetErr(&bytes.Buffer{})
|
||||
require.NoError(t, root.Execute())
|
||||
|
||||
got := out.String()
|
||||
lines := strings.Split(strings.TrimRight(got, "\n"), "\n")
|
||||
// Header line + 11 data rows = 12 lines
|
||||
require.Len(t, lines, 12, "text output must have header + 11 data rows; got:\n%s", got)
|
||||
// Header must contain column names
|
||||
assert.Contains(t, lines[0], "CODE")
|
||||
assert.Contains(t, lines[0], "MEANING")
|
||||
assert.Contains(t, lines[0], "AGENT ACTION")
|
||||
// First data row (exit 0) must mention "success"
|
||||
assert.Contains(t, lines[1], "success", "first data row must describe exit 0 success")
|
||||
}
|
||||
|
||||
func TestExitCodes_HelpOutput(t *testing.T) {
|
||||
var out bytes.Buffer
|
||||
root := NewRootCmd(cmdutil.New())
|
||||
root.SetArgs([]string{"help", "exit-codes"})
|
||||
root.SetOut(&out)
|
||||
root.SetErr(&bytes.Buffer{})
|
||||
require.NoError(t, root.Execute())
|
||||
|
||||
got := out.String()
|
||||
assert.Contains(t, got, "Exit codes and the agent action for each", "help output must contain the Long description header")
|
||||
}
|
||||
+15
-9
@@ -17,13 +17,17 @@ import (
|
||||
// aggregated by paging the doc list. Verb split with `kb status`:
|
||||
// status reads existing state cheaply, check actively verifies.
|
||||
type CheckResult struct {
|
||||
ID string `json:"id"`
|
||||
Reachable bool `json:"reachable"`
|
||||
KnowledgeCount int64 `json:"knowledge_count,omitempty"`
|
||||
ChunkCount int64 `json:"chunk_count,omitempty"`
|
||||
IsProcessing bool `json:"is_processing,omitempty"`
|
||||
ProcessingCount int64 `json:"processing_count,omitempty"`
|
||||
FailedCount int64 `json:"failed_count"` // always populated (no omitempty)
|
||||
ID string `json:"id"`
|
||||
Reachable bool `json:"reachable"`
|
||||
// RetrievalReady is false when no embedding model is bound — the KB can never
|
||||
// index/retrieve regardless of failed_count. Always emitted (no omitempty) so
|
||||
// an unconfigured KB is not reported as silently healthy.
|
||||
RetrievalReady bool `json:"retrieval_ready"`
|
||||
KnowledgeCount int64 `json:"knowledge_count,omitempty"`
|
||||
ChunkCount int64 `json:"chunk_count,omitempty"`
|
||||
IsProcessing bool `json:"is_processing,omitempty"`
|
||||
ProcessingCount int64 `json:"processing_count,omitempty"`
|
||||
FailedCount int64 `json:"failed_count"` // always populated (no omitempty)
|
||||
}
|
||||
|
||||
// CheckService is the narrow SDK surface needed for kb check.
|
||||
@@ -33,7 +37,7 @@ type CheckService interface {
|
||||
}
|
||||
|
||||
var kbCheckFields = []string{
|
||||
"id", "reachable", "knowledge_count", "chunk_count",
|
||||
"id", "reachable", "retrieval_ready", "knowledge_count", "chunk_count",
|
||||
"is_processing", "processing_count", "failed_count",
|
||||
}
|
||||
|
||||
@@ -76,7 +80,7 @@ verification including failed-doc aggregation.`,
|
||||
UsedFor: "verify a knowledge base end-to-end: status plus failed-doc aggregation",
|
||||
RequiredFlags: []string{"<kb-id> (positional)"},
|
||||
Examples: []string{"weknora kb check kb_abc"},
|
||||
Output: "envelope.data is {id, reachable, failed_count, ...}; deeper than `kb status`",
|
||||
Output: "envelope.data is {id, reachable, retrieval_ready, failed_count, ...}; retrieval_ready=false means no embedding model is bound (run `kb config set`); deeper than `kb status`",
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
@@ -92,6 +96,7 @@ func runCheck(ctx context.Context, svc CheckService, id string) (*CheckResult, e
|
||||
res := &CheckResult{
|
||||
ID: kb.ID,
|
||||
Reachable: true,
|
||||
RetrievalReady: kb.EmbeddingModelID != "",
|
||||
KnowledgeCount: kb.KnowledgeCount,
|
||||
ChunkCount: kb.ChunkCount,
|
||||
IsProcessing: kb.IsProcessing,
|
||||
@@ -144,6 +149,7 @@ func writeCheckText(w io.Writer, res *CheckResult) error {
|
||||
if !res.Reachable {
|
||||
return nil
|
||||
}
|
||||
fmt.Fprintf(w, "Retrieval: %v%s\n", res.RetrievalReady, retrievalHint(res.RetrievalReady))
|
||||
fmt.Fprintf(w, "Knowledge: %d\n", res.KnowledgeCount)
|
||||
fmt.Fprintf(w, "Chunks: %d\n", res.ChunkCount)
|
||||
fmt.Fprintf(w, "Processing: %v (%d active)\n", res.IsProcessing, res.ProcessingCount)
|
||||
|
||||
@@ -39,7 +39,7 @@ func (f *fakeCheckSvc) ListKnowledgeWithFilter(_ context.Context, _ string, page
|
||||
|
||||
func TestRunCheck_AggregatesFailed(t *testing.T) {
|
||||
svc := &fakeCheckSvc{
|
||||
kb: &sdk.KnowledgeBase{ID: "kb_x", KnowledgeCount: 5, ChunkCount: 20},
|
||||
kb: &sdk.KnowledgeBase{ID: "kb_x", KnowledgeCount: 5, ChunkCount: 20, EmbeddingModelID: "emb_1"},
|
||||
failedDocs: []sdk.Knowledge{
|
||||
{ID: "d1", ParseStatus: "failed"},
|
||||
{ID: "d2", ParseStatus: "failed"},
|
||||
@@ -55,6 +55,9 @@ func TestRunCheck_AggregatesFailed(t *testing.T) {
|
||||
if !res.Reachable {
|
||||
t.Error("Reachable=false, want true")
|
||||
}
|
||||
if !res.RetrievalReady {
|
||||
t.Error("RetrievalReady=false, want true when an embedding model is bound")
|
||||
}
|
||||
if res.KnowledgeCount != 5 || res.ChunkCount != 20 {
|
||||
t.Errorf("got %+v", res)
|
||||
}
|
||||
|
||||
@@ -0,0 +1,110 @@
|
||||
package kb
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
||||
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
||||
sdk "github.com/Tencent/WeKnora/client"
|
||||
)
|
||||
|
||||
// kbConfigFields enumerates the fields surfaced for `--format json` discovery on
|
||||
// `kb config`. Mirrors client.KBModelConfigView (secret-free — no api keys).
|
||||
var kbConfigFields = []string{
|
||||
"retrieval_ready", "embedding", "llm", "rerank", "multimodal",
|
||||
}
|
||||
|
||||
// ConfigService is the narrow SDK surface this command depends on.
|
||||
type ConfigService interface {
|
||||
GetInitializationConfig(ctx context.Context, kbID string) (*sdk.KBModelConfigView, error)
|
||||
}
|
||||
|
||||
// NewCmdConfig builds `weknora kb config <kb-id>` — read-only inspection of a
|
||||
// knowledge base's model configuration. Write it with `weknora kb config set`.
|
||||
func NewCmdConfig(f *cmdutil.Factory) *cobra.Command {
|
||||
cmd := &cobra.Command{
|
||||
Use: "config <kb-id>",
|
||||
Short: "Show a knowledge base's model configuration (set it with `config set`)",
|
||||
Long: `Show the model configuration bound to a knowledge base: embedding, llm
|
||||
(chat), rerank, and multimodal model names + source. retrieval_ready is false
|
||||
until an embedding model is bound — configure it with 'weknora kb config set'.
|
||||
Provider API keys are never shown.`,
|
||||
Args: cobra.ExactArgs(1),
|
||||
RunE: func(c *cobra.Command, args []string) error {
|
||||
fopts, err := cmdutil.CheckFormatFlag(c)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
|
||||
cli, err := f.Client()
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
return runConfig(c.Context(), fopts, cli, args[0])
|
||||
},
|
||||
}
|
||||
// `kb config` reads (this command's RunE); `kb config set` writes. Same
|
||||
// read/write pairing as mainstream config surfaces.
|
||||
cmd.AddCommand(newKBModelWriteCmd(f, "set <kb-id>", []string{"weknora", "kb", "config", "set"}))
|
||||
cmdutil.AddFormatFlag(cmd, kbConfigFields...)
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "show a KB's model config (embedding/llm/rerank/multimodal by name, secret-free). retrieval_ready=false => run `weknora kb config set`. Write config with `weknora kb config set`.",
|
||||
RequiredFlags: []string{"<kb-id> (positional)"},
|
||||
Examples: []string{"weknora kb config kb_abc --jq .data.embedding_model_id"},
|
||||
Output: "envelope.data is {retrieval_ready, embedding{configured,model_name,source,dimension}, llm{...}, rerank{enabled,model_name}, multimodal{enabled}} — secret-free (no provider api keys)",
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
|
||||
func runConfig(ctx context.Context, fopts *cmdutil.FormatOptions, svc ConfigService, kbID string) error {
|
||||
cfg, err := svc.GetInitializationConfig(ctx, kbID)
|
||||
if err != nil {
|
||||
return cmdutil.WrapHTTP(err, "get config for knowledge base %q", kbID)
|
||||
}
|
||||
if cfg == nil {
|
||||
cfg = &sdk.KBModelConfigView{}
|
||||
}
|
||||
if fopts.WantsJSON() {
|
||||
return fopts.Emit(iostreams.IO.Out, cfg, nil)
|
||||
}
|
||||
w := iostreams.IO.Out
|
||||
fmt.Fprintf(w, "%-13s %v\n", "RETRIEVAL:", readyLabel(cfg.RetrievalReady))
|
||||
fmt.Fprintf(w, "%-13s %s\n", "EMBEDDING:", slotLabel(cfg.Embedding))
|
||||
fmt.Fprintf(w, "%-13s %s\n", "CHAT (LLM):", slotLabel(cfg.LLM))
|
||||
fmt.Fprintf(w, "%-13s %s\n", "RERANK:", rerankLabel(cfg.Rerank))
|
||||
fmt.Fprintf(w, "%-13s %v\n", "MULTIMODAL:", cfg.Multimodal.Enabled)
|
||||
if !cfg.RetrievalReady {
|
||||
fmt.Fprintln(w, "\n(not retrieval-ready — no embedding model; run `weknora kb config set <kb-id> --chat-model <id> --embedding-model <id>`)")
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func readyLabel(ready bool) string {
|
||||
if ready {
|
||||
return "ready"
|
||||
}
|
||||
return "NOT ready (no embedding model)"
|
||||
}
|
||||
|
||||
func slotLabel(s sdk.ModelSlotView) string {
|
||||
if !s.Configured {
|
||||
return "(unset)"
|
||||
}
|
||||
if s.Source != "" {
|
||||
return fmt.Sprintf("%s (%s)", s.ModelName, s.Source)
|
||||
}
|
||||
return s.ModelName
|
||||
}
|
||||
|
||||
func rerankLabel(r sdk.RerankSlotView) string {
|
||||
if !r.Enabled {
|
||||
return "(disabled)"
|
||||
}
|
||||
return r.ModelName
|
||||
}
|
||||
|
||||
// compile-time check: the production SDK client implements ConfigService.
|
||||
var _ ConfigService = (*sdk.Client)(nil)
|
||||
@@ -0,0 +1,166 @@
|
||||
package kb
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"strings"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
||||
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
||||
sdk "github.com/Tencent/WeKnora/client"
|
||||
)
|
||||
|
||||
type ConfigSetOptions struct {
|
||||
ChatModel string
|
||||
EmbeddingModel string
|
||||
Yes bool
|
||||
DryRun bool
|
||||
}
|
||||
|
||||
// ConfigSetService is the narrow SDK surface this command depends on. SetKBModelConfig
|
||||
// points the KB at already-registered models; GetInitializationConfig re-reads
|
||||
// the server's resulting state so the success envelope reflects what stuck.
|
||||
type ConfigSetService interface {
|
||||
SetKBModelConfig(ctx context.Context, kbID string, cfg *sdk.KBModelConfig) error
|
||||
GetInitializationConfig(ctx context.Context, kbID string) (*sdk.KBModelConfigView, error)
|
||||
}
|
||||
|
||||
// newKBModelWriteCmd builds the `kb config set` model-binding write command.
|
||||
// head is the argv prefix used for the risk action and retry_argv (weknora kb
|
||||
// config set).
|
||||
func newKBModelWriteCmd(f *cmdutil.Factory, use string, head []string) *cobra.Command {
|
||||
opts := &ConfigSetOptions{}
|
||||
action := strings.Join(head[1:], ".") // e.g. "kb.config.set"
|
||||
cmd := &cobra.Command{
|
||||
Use: use,
|
||||
Short: "Bind embedding + chat models to a knowledge base (make it usable)",
|
||||
Long: `Bind already-registered models to a knowledge base so it can embed, retrieve,
|
||||
and generate. Both --chat-model (LLM, used for generation/summary) and
|
||||
--embedding-model (used for retrieval) are required; register models first with
|
||||
'weknora model create' and discover ids with 'weknora model list'.
|
||||
|
||||
High-risk write: changing a KB's embedding model affects how its content is
|
||||
indexed and searched (the server refuses to CHANGE it once the KB has
|
||||
documents; setting it on an unconfigured KB is allowed). Without -y/--yes in a
|
||||
non-TTY / JSON context it exits 10 (input.confirmation_required) without
|
||||
applying the change.`,
|
||||
Args: cobra.ExactArgs(1),
|
||||
RunE: func(c *cobra.Command, args []string) error {
|
||||
fopts, err := cmdutil.CheckFormatFlag(c)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
|
||||
opts.Yes, _ = c.Flags().GetBool("yes")
|
||||
kbID := args[0]
|
||||
// Validate required flags before the dry-run gate so --dry-run rejects
|
||||
// identically to the live path.
|
||||
if err := validateConfigSetFlags(opts); err != nil {
|
||||
return err
|
||||
}
|
||||
if handled, err := cmdutil.HandleDryRun(c, opts.DryRun, cmdutil.DryRunPlan{
|
||||
Action: action,
|
||||
Args: map[string]any{"kb": kbID, "chat_model": opts.ChatModel, "embedding_model": opts.EmbeddingModel},
|
||||
}); handled {
|
||||
return err
|
||||
}
|
||||
cli, err := f.Client()
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if err := cmdutil.ConfirmDestructive(f.Prompter(), opts.Yes, fopts.WantsJSON(),
|
||||
"configure", "knowledge base", kbID, action,
|
||||
cmdutil.BuildRetryArgv(c, append(append([]string{}, head...), kbID), "chat-model", "embedding-model", "format")); err != nil {
|
||||
return err
|
||||
}
|
||||
// Resolve name-or-id for the model flags (a UUID passes through; a
|
||||
// name is looked up among models of the expected type). Network read
|
||||
// on the live path only — the dry-run above shows the raw refs.
|
||||
if opts.ChatModel, err = cmdutil.ResolveModelRef(c.Context(), cli, opts.ChatModel, "KnowledgeQA"); err != nil {
|
||||
return err
|
||||
}
|
||||
if opts.EmbeddingModel, err = cmdutil.ResolveModelRef(c.Context(), cli, opts.EmbeddingModel, "Embedding"); err != nil {
|
||||
return err
|
||||
}
|
||||
return runConfigSet(c.Context(), opts, fopts, cli, kbID)
|
||||
},
|
||||
}
|
||||
cmd.Flags().StringVar(&opts.ChatModel, "chat-model", "", "Chat / LLM model id or name for generation & summary (required) — see `weknora model list`")
|
||||
cmd.Flags().StringVar(&opts.EmbeddingModel, "embedding-model", "", "Embedding model id or name for retrieval (required) — see `weknora model list`")
|
||||
cmdutil.AddFormatFlag(cmd, kbConfigFields...)
|
||||
cmdutil.AddDryRunFlag(cmd, &opts.DryRun)
|
||||
cmdutil.SetRisk(cmd, action)
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "bind models to a KB so it becomes retrieval-ready. --chat-model and --embedding-model are required and accept a model id or name; discover them with `weknora model list`. Read the result back with `weknora kb config`.",
|
||||
RequiredFlags: []string{"<kb-id> (positional)", "--chat-model", "--embedding-model"},
|
||||
Examples: []string{
|
||||
"weknora kb config set kb_abc --chat-model model_llm --embedding-model model_emb -y",
|
||||
},
|
||||
Output: "envelope.data is the resulting secret-free config view {retrieval_ready, embedding, llm, rerank, multimodal}",
|
||||
Warnings: []string{
|
||||
"Requires explicit user approval (exit 10 / input.confirmation_required); never auto-add -y.",
|
||||
"The server refuses to CHANGE the embedding model of a KB that already has documents (setting it on an unconfigured KB is fine).",
|
||||
},
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
|
||||
func validateConfigSetFlags(opts *ConfigSetOptions) error {
|
||||
var missing []string
|
||||
if strings.TrimSpace(opts.ChatModel) == "" {
|
||||
missing = append(missing, "--chat-model")
|
||||
}
|
||||
if strings.TrimSpace(opts.EmbeddingModel) == "" {
|
||||
missing = append(missing, "--embedding-model")
|
||||
}
|
||||
if len(missing) == 0 {
|
||||
return nil
|
||||
}
|
||||
return &cmdutil.Error{
|
||||
Code: cmdutil.CodeInputMissingFlag,
|
||||
Message: "kb config set requires " + strings.Join(missing, " and "),
|
||||
Hint: "discover model ids with `weknora model list` (or register one with `weknora model create`), then pass --chat-model <id> --embedding-model <id>",
|
||||
}
|
||||
}
|
||||
|
||||
func runConfigSet(ctx context.Context, opts *ConfigSetOptions, fopts *cmdutil.FormatOptions, svc ConfigSetService, kbID string) error {
|
||||
if err := validateConfigSetFlags(opts); err != nil {
|
||||
return err
|
||||
}
|
||||
cfg := &sdk.KBModelConfig{
|
||||
LLMModelID: opts.ChatModel,
|
||||
EmbeddingModelID: opts.EmbeddingModel,
|
||||
}
|
||||
if err := svc.SetKBModelConfig(ctx, kbID, cfg); err != nil {
|
||||
return cmdutil.WrapHTTP(err, "configure knowledge base %q", kbID)
|
||||
}
|
||||
// Re-read the server's resulting state (secret-free view) so the envelope
|
||||
// reflects what stuck — the same shape `kb config` returns.
|
||||
result, err := svc.GetInitializationConfig(ctx, kbID)
|
||||
if err != nil || result == nil {
|
||||
// The write succeeded; surface what we applied if the read-back failed.
|
||||
result = &sdk.KBModelConfigView{
|
||||
RetrievalReady: opts.EmbeddingModel != "",
|
||||
Embedding: sdk.ModelSlotView{Configured: opts.EmbeddingModel != "", ModelName: opts.EmbeddingModel},
|
||||
LLM: sdk.ModelSlotView{Configured: opts.ChatModel != "", ModelName: opts.ChatModel},
|
||||
}
|
||||
}
|
||||
if fopts.WantsJSON() {
|
||||
return fopts.Emit(iostreams.IO.Out, result, nil)
|
||||
}
|
||||
fmt.Fprintf(iostreams.IO.Out, "✓ Configured knowledge base %s (chat: %s, embedding: %s)\n",
|
||||
kbID, orUnset(result.LLM.ModelName), orUnset(result.Embedding.ModelName))
|
||||
return nil
|
||||
}
|
||||
|
||||
func orUnset(s string) string {
|
||||
if s == "" {
|
||||
return "(unset)"
|
||||
}
|
||||
return s
|
||||
}
|
||||
|
||||
// compile-time check: the production SDK client implements ConfigSetService.
|
||||
var _ ConfigSetService = (*sdk.Client)(nil)
|
||||
@@ -0,0 +1,138 @@
|
||||
package kb
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"testing"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
"github.com/stretchr/testify/assert"
|
||||
"github.com/stretchr/testify/require"
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
||||
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
||||
"github.com/Tencent/WeKnora/cli/internal/prompt"
|
||||
sdk "github.com/Tencent/WeKnora/client"
|
||||
)
|
||||
|
||||
type fakeInitSvc struct {
|
||||
gotKB string
|
||||
gotCfg *sdk.KBModelConfig
|
||||
result *sdk.KBModelConfigView
|
||||
setErr error
|
||||
}
|
||||
|
||||
func (f *fakeInitSvc) SetKBModelConfig(_ context.Context, kbID string, cfg *sdk.KBModelConfig) error {
|
||||
f.gotKB = kbID
|
||||
f.gotCfg = cfg
|
||||
return f.setErr
|
||||
}
|
||||
|
||||
func (f *fakeInitSvc) GetInitializationConfig(_ context.Context, _ string) (*sdk.KBModelConfigView, error) {
|
||||
if f.result != nil {
|
||||
return f.result, nil
|
||||
}
|
||||
if f.gotCfg == nil {
|
||||
return &sdk.KBModelConfigView{}, nil
|
||||
}
|
||||
return &sdk.KBModelConfigView{
|
||||
RetrievalReady: f.gotCfg.EmbeddingModelID != "",
|
||||
Embedding: sdk.ModelSlotView{Configured: f.gotCfg.EmbeddingModelID != "", ModelName: f.gotCfg.EmbeddingModelID},
|
||||
LLM: sdk.ModelSlotView{Configured: f.gotCfg.LLMModelID != "", ModelName: f.gotCfg.LLMModelID},
|
||||
}, nil
|
||||
}
|
||||
|
||||
func TestKBConfigSet_AppliesAndEmitsResult(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &fakeInitSvc{}
|
||||
opts := &ConfigSetOptions{ChatModel: "model_llm", EmbeddingModel: "model_emb"}
|
||||
require.NoError(t, runConfigSet(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc, "kb_abc"))
|
||||
|
||||
assert.Equal(t, "kb_abc", svc.gotKB)
|
||||
require.NotNil(t, svc.gotCfg)
|
||||
assert.Equal(t, "model_llm", svc.gotCfg.LLMModelID)
|
||||
assert.Equal(t, "model_emb", svc.gotCfg.EmbeddingModelID)
|
||||
|
||||
var env struct {
|
||||
OK bool `json:"ok"`
|
||||
Data sdk.KBModelConfigView `json:"data"`
|
||||
}
|
||||
require.NoError(t, json.Unmarshal(out.Bytes(), &env))
|
||||
assert.True(t, env.OK)
|
||||
assert.Equal(t, "model_emb", env.Data.Embedding.ModelName)
|
||||
assert.Equal(t, "model_llm", env.Data.LLM.ModelName)
|
||||
assert.True(t, env.Data.RetrievalReady)
|
||||
}
|
||||
|
||||
func TestKBConfigSet_RequiresBothModels(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
svc := &fakeInitSvc{}
|
||||
// Missing both.
|
||||
err := runConfigSet(context.Background(), &ConfigSetOptions{}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc, "kb_abc")
|
||||
var ce *cmdutil.Error
|
||||
require.ErrorAs(t, err, &ce)
|
||||
assert.Equal(t, cmdutil.CodeInputMissingFlag, ce.Code)
|
||||
assert.Equal(t, "", svc.gotKB, "must not call SetKBModelConfig when flags are missing")
|
||||
|
||||
// Missing just embedding.
|
||||
err = runConfigSet(context.Background(), &ConfigSetOptions{ChatModel: "m"}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc, "kb_abc")
|
||||
require.ErrorAs(t, err, &ce)
|
||||
assert.Contains(t, ce.Message, "--embedding-model")
|
||||
}
|
||||
|
||||
func TestKBConfigSet_WriteSucceedsReadbackFails(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc2 := &readbackErrSvc{fakeInitSvc: &fakeInitSvc{}}
|
||||
opts := &ConfigSetOptions{ChatModel: "model_llm", EmbeddingModel: "model_emb"}
|
||||
require.NoError(t, runConfigSet(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc2, "kb_abc"))
|
||||
var env struct {
|
||||
Data sdk.KBModelConfigView `json:"data"`
|
||||
}
|
||||
require.NoError(t, json.Unmarshal(out.Bytes(), &env))
|
||||
assert.Equal(t, "model_emb", env.Data.Embedding.ModelName, "falls back to applied config when read-back fails")
|
||||
}
|
||||
|
||||
type readbackErrSvc struct{ *fakeInitSvc }
|
||||
|
||||
func (s *readbackErrSvc) GetInitializationConfig(_ context.Context, _ string) (*sdk.KBModelConfigView, error) {
|
||||
return nil, errors.New("read-back boom")
|
||||
}
|
||||
|
||||
// withRootKB wraps a kb subcommand under a synthetic root with global flags,
|
||||
// keyed off the sub's own name (unlike withRootHarnessKB which is hardcoded to
|
||||
// `update`).
|
||||
func withRootKB(sub *cobra.Command, args ...string) *cobra.Command {
|
||||
root := &cobra.Command{Use: "weknora"}
|
||||
pf := root.PersistentFlags()
|
||||
pf.BoolP("yes", "y", false, "")
|
||||
pf.String("format", "", "")
|
||||
pf.StringP("jq", "q", "", "")
|
||||
kb := &cobra.Command{Use: "kb"}
|
||||
kb.AddCommand(sub)
|
||||
root.AddCommand(kb)
|
||||
root.SetArgs(append([]string{"kb", sub.Name()}, args...))
|
||||
root.SetContext(context.Background())
|
||||
root.SilenceErrors = true
|
||||
root.SilenceUsage = true
|
||||
return root
|
||||
}
|
||||
|
||||
func TestKBConfigSet_RequiresConfirmation(t *testing.T) {
|
||||
iostreams.SetForTest(t)
|
||||
f := &cmdutil.Factory{
|
||||
Client: func() (*sdk.Client, error) { return nil, nil },
|
||||
Prompter: func() prompt.Prompter { return prompt.AgentPrompter{} },
|
||||
}
|
||||
// Drive `kb config set` (the config parent routes to its `set` subcommand).
|
||||
root := withRootKB(NewCmdConfig(f), "set", "kb_abc", "--chat-model", "model_llm", "--embedding-model", "model_emb", "--format", "json")
|
||||
err := root.Execute()
|
||||
require.Error(t, err)
|
||||
var ce *cmdutil.Error
|
||||
require.ErrorAs(t, err, &ce)
|
||||
assert.Equal(t, cmdutil.CodeInputConfirmationRequired, ce.Code)
|
||||
assert.Equal(t, 10, cmdutil.ExitCode(err))
|
||||
assert.Contains(t, ce.RetryArgv, "-y")
|
||||
assert.Contains(t, ce.RetryArgv, "model_emb")
|
||||
assert.Contains(t, ce.RetryArgv, "set", "retry_argv should target `kb config set`")
|
||||
}
|
||||
@@ -0,0 +1,70 @@
|
||||
package kb
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"testing"
|
||||
|
||||
"github.com/stretchr/testify/assert"
|
||||
"github.com/stretchr/testify/require"
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
||||
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
||||
sdk "github.com/Tencent/WeKnora/client"
|
||||
)
|
||||
|
||||
type fakeConfigSvc struct {
|
||||
cfg *sdk.KBModelConfigView
|
||||
err error
|
||||
}
|
||||
|
||||
func (f *fakeConfigSvc) GetInitializationConfig(_ context.Context, _ string) (*sdk.KBModelConfigView, error) {
|
||||
return f.cfg, f.err
|
||||
}
|
||||
|
||||
func TestKBConfig_EmitsConfig(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &fakeConfigSvc{cfg: &sdk.KBModelConfigView{
|
||||
RetrievalReady: true,
|
||||
Embedding: sdk.ModelSlotView{Configured: true, ModelName: "model_emb", Source: "remote"},
|
||||
LLM: sdk.ModelSlotView{Configured: true, ModelName: "model_chat"},
|
||||
}}
|
||||
require.NoError(t, runConfig(context.Background(), &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc, "kb_abc"))
|
||||
var env struct {
|
||||
OK bool `json:"ok"`
|
||||
Data sdk.KBModelConfigView `json:"data"`
|
||||
}
|
||||
require.NoError(t, json.Unmarshal(out.Bytes(), &env))
|
||||
assert.True(t, env.OK)
|
||||
assert.Equal(t, "model_emb", env.Data.Embedding.ModelName)
|
||||
assert.Equal(t, "model_chat", env.Data.LLM.ModelName)
|
||||
assert.True(t, env.Data.RetrievalReady)
|
||||
}
|
||||
|
||||
// TestKBConfig_SecretFree: the view type has no apiKey/baseUrl field, so the
|
||||
// JSON output can never carry provider credentials — the CLI never echoes the
|
||||
// keys the server returns for the web config form.
|
||||
func TestKBConfig_SecretFree(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &fakeConfigSvc{cfg: &sdk.KBModelConfigView{
|
||||
Embedding: sdk.ModelSlotView{Configured: true, ModelName: "e", Source: "remote"},
|
||||
}}
|
||||
require.NoError(t, runConfig(context.Background(), &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc, "kb_abc"))
|
||||
assert.NotContains(t, out.String(), "apiKey")
|
||||
assert.NotContains(t, out.String(), "api_key")
|
||||
assert.NotContains(t, out.String(), "baseUrl")
|
||||
}
|
||||
|
||||
// TestKBConfig_NilConfig: a nil server config (KB not yet initialized) emits
|
||||
// retrieval_ready:false, not a crash.
|
||||
func TestKBConfig_NilConfig(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &fakeConfigSvc{cfg: nil}
|
||||
require.NoError(t, runConfig(context.Background(), &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc, "kb_abc"))
|
||||
var env struct {
|
||||
Data sdk.KBModelConfigView `json:"data"`
|
||||
}
|
||||
require.NoError(t, json.Unmarshal(out.Bytes(), &env))
|
||||
assert.False(t, env.Data.RetrievalReady)
|
||||
assert.Empty(t, env.Data.Embedding.ModelName)
|
||||
}
|
||||
+52
-20
@@ -3,13 +3,13 @@ package kb
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"slices"
|
||||
"strings"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
||||
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
||||
"github.com/Tencent/WeKnora/cli/internal/output"
|
||||
sdk "github.com/Tencent/WeKnora/client"
|
||||
)
|
||||
|
||||
@@ -30,13 +30,14 @@ type CreateOptions struct {
|
||||
Name string
|
||||
Description string
|
||||
EmbeddingModel string
|
||||
ChatModel string
|
||||
StorageProvider string
|
||||
DryRun bool
|
||||
}
|
||||
|
||||
// storageProviderValues mirrors the server enum in
|
||||
// internal/types/knowledgebase.go:StorageProviderConfig.Provider.
|
||||
var storageProviderValues = []string{"local", "minio", "cos", "tos", "s3", "oss", "ks3"}
|
||||
var storageProviderValues = []string{"local", "minio", "cos", "tos", "s3", "oss", "ks3", "obs"}
|
||||
|
||||
// CreateService is the narrow SDK surface this command depends on.
|
||||
// *sdk.Client satisfies it via duck typing.
|
||||
@@ -60,16 +61,16 @@ func NewCmdCreate(f *cmdutil.Factory) *cobra.Command {
|
||||
fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
|
||||
opts.Name = args[0]
|
||||
// Validate --storage-provider enum before the dry-run gate so
|
||||
// --dry-run rejects identically to the live path. Same typed
|
||||
// FlagError as runCreate (kept there for direct-call callers).
|
||||
if opts.StorageProvider != "" {
|
||||
v := strings.ToLower(strings.TrimSpace(opts.StorageProvider))
|
||||
if !slices.Contains(storageProviderValues, v) {
|
||||
return cmdutil.NewFlagError(fmt.Errorf(
|
||||
"invalid --storage-provider %q: must be %s",
|
||||
opts.StorageProvider, strings.Join(storageProviderValues, " | ")))
|
||||
}
|
||||
// --dry-run rejects identically to the live path. ValidateEnum
|
||||
// returns input.invalid_argument (exit 5) and normalizes to the
|
||||
// canonical lowercase form — consistent with every other enum flag
|
||||
// (model --type, agent --agent-mode, message search --mode).
|
||||
// runCreate re-validates for direct-call callers.
|
||||
canonSP, err := cmdutil.ValidateEnum("storage-provider", opts.StorageProvider, storageProviderValues)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
opts.StorageProvider = canonSP
|
||||
if handled, err := cmdutil.HandleDryRun(c, opts.DryRun, cmdutil.DryRunPlan{
|
||||
Action: "kb.create",
|
||||
Args: map[string]any{
|
||||
@@ -83,11 +84,25 @@ func NewCmdCreate(f *cmdutil.Factory) *cobra.Command {
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
// --embedding-model accepts a model id or name (a UUID passes
|
||||
// through; a name resolves among Embedding models). Configuring a
|
||||
// KB's models fully is `weknora kb config set`; this just pre-sets the
|
||||
// embedding model at creation.
|
||||
if opts.EmbeddingModel, err = cmdutil.ResolveModelRef(c.Context(), cli, opts.EmbeddingModel, "Embedding"); err != nil {
|
||||
return err
|
||||
}
|
||||
// --chat-model (id or name) pre-sets the KB's LLM at creation, so a
|
||||
// KB can be born retrieval-ready in one step. Full model config
|
||||
// (rerank / multimodal) is still `weknora kb config set`.
|
||||
if opts.ChatModel, err = cmdutil.ResolveModelRef(c.Context(), cli, opts.ChatModel, "KnowledgeQA"); err != nil {
|
||||
return err
|
||||
}
|
||||
return runCreate(c.Context(), opts, fopts, cli)
|
||||
},
|
||||
}
|
||||
cmd.Flags().StringVar(&opts.Description, "description", "", "Knowledge base description (optional)")
|
||||
cmd.Flags().StringVar(&opts.EmbeddingModel, "embedding-model", "", "Embedding model ID (optional; server picks default when unset)")
|
||||
cmd.Flags().StringVar(&opts.EmbeddingModel, "embedding-model", "", "Embedding model id or name (optional; makes the KB retrieval-ready at creation)")
|
||||
cmd.Flags().StringVar(&opts.ChatModel, "chat-model", "", "Chat/LLM model id or name (optional; pre-set the KB's answer model at creation)")
|
||||
cmd.Flags().StringVar(&opts.StorageProvider, "storage-provider", "",
|
||||
"Storage provider for documents in this KB: "+strings.Join(storageProviderValues, " | ")+" (optional; server default when unset)")
|
||||
cmdutil.AddFormatFlag(cmd, kbCreateFields...)
|
||||
@@ -95,7 +110,12 @@ func NewCmdCreate(f *cmdutil.Factory) *cobra.Command {
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "Create a new knowledge base with the given name. Emits the created KB object with its id.",
|
||||
RequiredFlags: []string{"<name> (positional)"},
|
||||
Output: "envelope.data is the created KnowledgeBase object with id, name, type, embedding_model_id",
|
||||
Examples: []string{
|
||||
`weknora kb create "Eng Docs"`,
|
||||
`weknora kb create "Eng Docs" --embedding-model text-embedding-3-small --chat-model gpt-4o-mini # retrieval-ready in one step`,
|
||||
`weknora kb create "Eng Docs" --jq .data.id # capture id to chain into doc upload --kb`,
|
||||
},
|
||||
Output: "envelope.data is the created KnowledgeBase object with id, name, type, embedding_model_id, summary_model_id",
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
@@ -114,14 +134,15 @@ func runCreate(ctx context.Context, opts *CreateOptions, fopts *cmdutil.FormatOp
|
||||
if opts.EmbeddingModel != "" {
|
||||
req.EmbeddingModelID = opts.EmbeddingModel
|
||||
}
|
||||
if opts.ChatModel != "" {
|
||||
req.SummaryModelID = opts.ChatModel
|
||||
}
|
||||
if opts.StorageProvider != "" {
|
||||
v := strings.ToLower(strings.TrimSpace(opts.StorageProvider))
|
||||
if !slices.Contains(storageProviderValues, v) {
|
||||
return cmdutil.NewFlagError(fmt.Errorf(
|
||||
"invalid --storage-provider %q: must be %s",
|
||||
opts.StorageProvider, strings.Join(storageProviderValues, " | ")))
|
||||
canonSP, err := cmdutil.ValidateEnum("storage-provider", opts.StorageProvider, storageProviderValues)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
req.StorageProviderConfig = &sdk.StorageProviderConfig{Provider: v}
|
||||
req.StorageProviderConfig = &sdk.StorageProviderConfig{Provider: canonSP}
|
||||
}
|
||||
|
||||
created, err := svc.CreateKnowledgeBase(ctx, req)
|
||||
@@ -129,9 +150,20 @@ func runCreate(ctx context.Context, opts *CreateOptions, fopts *cmdutil.FormatOp
|
||||
return cmdutil.WrapHTTP(err, "create knowledge base")
|
||||
}
|
||||
|
||||
// A KB with no embedding model can hold documents but never index/retrieve
|
||||
// them — surface the next step at the point of creation instead of leaving
|
||||
// the agent to discover a silent-draft KB via a later empty search.
|
||||
var meta *output.Meta
|
||||
if created.EmbeddingModelID == "" {
|
||||
meta = &output.Meta{Hint: "retrieval_ready=false: no embedding model bound. Uploaded docs will not be searchable until you run `weknora kb config set " + created.ID + " --embedding-model <id> --chat-model <id>` (create the KB with --embedding-model/--chat-model to skip this step)."}
|
||||
}
|
||||
|
||||
if fopts.WantsJSON() {
|
||||
return fopts.Emit(iostreams.IO.Out, created, nil)
|
||||
return fopts.Emit(iostreams.IO.Out, created, meta)
|
||||
}
|
||||
fmt.Fprintf(iostreams.IO.Out, "✓ Created knowledge base %q (id: %s)\n", created.Name, created.ID)
|
||||
if meta != nil {
|
||||
fmt.Fprintf(iostreams.IO.Out, "⚠ %s\n", meta.Hint)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
@@ -93,7 +93,7 @@ func TestKBCreate_DryRun_RejectsInvalidStorageProvider(t *testing.T) {
|
||||
err := root.Execute()
|
||||
require.Error(t, err, "dry-run must reject invalid --storage-provider")
|
||||
|
||||
// runCreate emits a FlagError (exit 2) for this — make sure dry-run preserves
|
||||
// that exact mapping.
|
||||
assert.Equal(t, 2, cmdutil.ExitCode(err), "FlagError must map to exit 2")
|
||||
// The enum check returns input.invalid_argument (exit 5) — make sure the
|
||||
// dry-run path preserves that exact mapping (same as the live path).
|
||||
assert.Equal(t, 5, cmdutil.ExitCode(err), "invalid --storage-provider must map to exit 5")
|
||||
}
|
||||
|
||||
@@ -66,6 +66,50 @@ func TestCreate_Success_OmitsEmbeddingModelWhenEmpty(t *testing.T) {
|
||||
assert.Equal(t, "", svc.got.EmbeddingModelID, "embedding-model unset ⇒ empty in request")
|
||||
}
|
||||
|
||||
// A KB created without an embedding model can never retrieve; the create result
|
||||
// must hand the agent the fix (kb config set) instead of a silent unusable KB.
|
||||
func TestCreate_HintsWhenNoEmbeddingModel(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &fakeCreateSvc{resp: &sdk.KnowledgeBase{ID: "kb_x", Name: "n"}}
|
||||
require.NoError(t, runCreate(context.Background(), &CreateOptions{Name: "n"}, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc))
|
||||
var env struct {
|
||||
Meta struct {
|
||||
Hint string `json:"hint"`
|
||||
} `json:"meta"`
|
||||
}
|
||||
require.NoError(t, json.Unmarshal(out.Bytes(), &env))
|
||||
assert.Contains(t, env.Meta.Hint, "kb config set", "unconfigured KB must hint the retrieval-readiness fix")
|
||||
}
|
||||
|
||||
// A retrieval-ready KB (embedding model bound) carries no such hint — no noise.
|
||||
func TestCreate_NoHintWhenEmbeddingModelBound(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &fakeCreateSvc{resp: &sdk.KnowledgeBase{ID: "kb_x", Name: "n", EmbeddingModelID: "emb_1"}}
|
||||
require.NoError(t, runCreate(context.Background(), &CreateOptions{Name: "n", EmbeddingModel: "emb_1"}, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc))
|
||||
var env struct {
|
||||
Meta *struct {
|
||||
Hint string `json:"hint"`
|
||||
} `json:"meta"`
|
||||
}
|
||||
require.NoError(t, json.Unmarshal(out.Bytes(), &env))
|
||||
if env.Meta != nil {
|
||||
assert.Empty(t, env.Meta.Hint, "retrieval-ready KB must not emit a readiness hint")
|
||||
}
|
||||
}
|
||||
|
||||
// TestCreate_ChatModelSetsSummaryModelID: --chat-model rides the create request
|
||||
// as summary_model_id, so a KB can be born retrieval-ready in one step.
|
||||
func TestCreate_ChatModelSetsSummaryModelID(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
svc := &fakeCreateSvc{resp: &sdk.KnowledgeBase{ID: "kb_x", Name: "n"}}
|
||||
opts := &CreateOptions{Name: "n", EmbeddingModel: "emb_x", ChatModel: "chat_x"}
|
||||
require.NoError(t, runCreate(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc))
|
||||
|
||||
require.NotNil(t, svc.got)
|
||||
assert.Equal(t, "emb_x", svc.got.EmbeddingModelID)
|
||||
assert.Equal(t, "chat_x", svc.got.SummaryModelID, "--chat-model must set summary_model_id on the create request")
|
||||
}
|
||||
|
||||
func TestCreate_NameRequired(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
svc := &fakeCreateSvc{}
|
||||
@@ -138,16 +182,22 @@ func TestCreate_StorageProvider_InjectsRequest(t *testing.T) {
|
||||
assert.Equal(t, "local", svc.got.StorageProviderConfig.Provider, "value should be lowercased + trimmed before send")
|
||||
}
|
||||
|
||||
func TestCreate_StorageProvider_InvalidValueReturnsFlagError(t *testing.T) {
|
||||
func TestCreate_StorageProvider_InvalidValueReturnsInputError(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
svc := &fakeCreateSvc{}
|
||||
opts := &CreateOptions{Name: "n", StorageProvider: "azure"}
|
||||
err := runCreate(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc)
|
||||
require.Error(t, err)
|
||||
|
||||
assert.Equal(t, 2, cmdutil.ExitCode(err), "invalid --storage-provider must exit 2 (flag validation)")
|
||||
assert.Contains(t, err.Error(), "invalid --storage-provider")
|
||||
assert.Nil(t, svc.got, "SDK must not be called when flag validation fails")
|
||||
// A bad enum *value* (cobra accepted the string; the app rejected it) is an
|
||||
// app-level input error → exit 5, consistent with every other enum flag
|
||||
// (model --type, agent --agent-mode, message search --mode).
|
||||
var typed *cmdutil.Error
|
||||
require.ErrorAs(t, err, &typed)
|
||||
assert.Equal(t, cmdutil.CodeInputInvalidArgument, typed.Code)
|
||||
assert.Equal(t, 5, cmdutil.ExitCode(err), "invalid --storage-provider must exit 5 (app-level input validation)")
|
||||
assert.Contains(t, err.Error(), "--storage-provider")
|
||||
assert.Nil(t, svc.got, "SDK must not be called when input validation fails")
|
||||
}
|
||||
|
||||
func TestCreate_StorageProvider_OmittedWhenEmpty(t *testing.T) {
|
||||
|
||||
@@ -81,6 +81,7 @@ exactly to guard against unintended deletes.`,
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "permanently delete a knowledge base and all its contents",
|
||||
RequiredFlags: []string{"<kb-id> (positional)"},
|
||||
Output: "envelope.data is {id, deleted:true}",
|
||||
Examples: []string{
|
||||
"weknora kb delete kb_abc -y",
|
||||
"weknora kb delete kb_abc -y --format json",
|
||||
@@ -94,7 +95,7 @@ exactly to guard against unintended deletes.`,
|
||||
}
|
||||
|
||||
func runDelete(ctx context.Context, opts *DeleteOptions, fopts *cmdutil.FormatOptions, svc DeleteService, p prompt.Prompter, id string) error {
|
||||
if err := cmdutil.ConfirmDestructive(p, opts.Yes, fopts.WantsJSON(), "delete", "knowledge base", id, "kb.delete", "weknora kb delete "+id+" -y"); err != nil {
|
||||
if err := cmdutil.ConfirmDestructive(p, opts.Yes, fopts.WantsJSON(), "delete", "knowledge base", id, "kb.delete", []string{"weknora", "kb", "delete", id, "-y"}); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
|
||||
@@ -167,8 +167,8 @@ func TestDelete_JSONOut_WithYes_Proceeds(t *testing.T) {
|
||||
|
||||
func TestKbDelete_NoYes_JSONMode_AttachesRiskAndRetry(t *testing.T) {
|
||||
// Non-TTY + JSON mode without -y must return CodeInputConfirmationRequired
|
||||
// with risk.action == "kb.delete" and retry_command == "weknora kb delete kb_x -y".
|
||||
// Regression test for H1: ConfirmDestructive must attach risk + retry_command.
|
||||
// with risk.action == "kb.delete" and retry_argv == [weknora kb delete kb_x -y].
|
||||
// Regression test for H1: ConfirmDestructive must attach risk + retry_argv.
|
||||
iostreams.SetForTest(t)
|
||||
svc := &fakeDeleteSvc{}
|
||||
p := &testutil.ConfirmPrompter{}
|
||||
@@ -185,5 +185,5 @@ func TestKbDelete_NoYes_JSONMode_AttachesRiskAndRetry(t *testing.T) {
|
||||
require.NotNil(t, ce.Risk, "expected risk metadata on confirmation_required error")
|
||||
assert.Equal(t, "kb.delete", ce.Risk.Action, "expected risk.action == kb.delete")
|
||||
assert.Equal(t, "destructive", ce.Risk.Level, "expected risk.level == destructive")
|
||||
assert.Equal(t, "weknora kb delete kb_x -y", ce.RetryCommand, "expected retry_command")
|
||||
assert.Equal(t, []string{"weknora", "kb", "delete", "kb_x", "-y"}, ce.RetryArgv, "expected retry_argv")
|
||||
}
|
||||
|
||||
+18
-39
@@ -3,10 +3,8 @@ package kb
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"strings"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
"github.com/spf13/pflag"
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
||||
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
||||
@@ -14,7 +12,7 @@ import (
|
||||
)
|
||||
|
||||
// kbEditFields enumerates the fields surfaced for `--format json` discovery on
|
||||
// `kb edit`. The result is the updated KnowledgeBase; mirrors the kb
|
||||
// `kb update`. The result is the updated KnowledgeBase; mirrors the kb
|
||||
// top-level json tags.
|
||||
var kbEditFields = []string{
|
||||
"id", "name", "type", "description",
|
||||
@@ -47,14 +45,14 @@ type EditService interface {
|
||||
UpdateKnowledgeBase(ctx context.Context, id string, req *sdk.UpdateKnowledgeBaseRequest) (*sdk.KnowledgeBase, error)
|
||||
}
|
||||
|
||||
// NewCmdEdit builds `weknora kb edit <id>`. At least one of --name /
|
||||
// NewCmdEdit builds `weknora kb update <id>`. At least one of --name /
|
||||
// --description must be provided.
|
||||
func NewCmdEdit(f *cmdutil.Factory) *cobra.Command {
|
||||
opts := &EditOptions{}
|
||||
var name, desc string
|
||||
cmd := &cobra.Command{
|
||||
Use: "edit <kb-id>",
|
||||
Short: "Edit a knowledge base's name or description",
|
||||
Use: "update <kb-id>",
|
||||
Short: "Update a knowledge base's name or description",
|
||||
Long: `Update a knowledge base's name and/or description. At least one of
|
||||
--name / --description must be supplied; fields you omit are preserved
|
||||
server-side.
|
||||
@@ -78,14 +76,13 @@ to the user first.`,
|
||||
}
|
||||
id := args[0]
|
||||
// Validate pure-local "at least one mutation flag" before the
|
||||
// dry-run gate so --dry-run rejects identically to the live path
|
||||
// (industry standard: gh / kubectl / lark all validate before
|
||||
// preview). Same typed Error as runEdit so live behavior is
|
||||
// unchanged, just earlier.
|
||||
// dry-run gate so --dry-run rejects identically to the live path.
|
||||
// Same typed Error as runEdit so live behavior is unchanged, just
|
||||
// earlier.
|
||||
if opts.Name == nil && opts.Description == nil {
|
||||
return &cmdutil.Error{
|
||||
Code: cmdutil.CodeInputMissingFlag,
|
||||
Message: "kb edit requires at least one of --name or --description",
|
||||
Message: "kb update requires at least one of --name or --description",
|
||||
Hint: "pass --name <name> and/or --description <desc>",
|
||||
}
|
||||
}
|
||||
@@ -97,7 +94,7 @@ to the user first.`,
|
||||
planArgs["description"] = *opts.Description
|
||||
}
|
||||
if handled, err := cmdutil.HandleDryRun(c, opts.DryRun, cmdutil.DryRunPlan{
|
||||
Action: "kb.edit",
|
||||
Action: "kb.update",
|
||||
Args: planArgs,
|
||||
}); handled {
|
||||
return err
|
||||
@@ -108,8 +105,8 @@ to the user first.`,
|
||||
}
|
||||
// Build a retry command from the flags the user actually passed so
|
||||
// agents can re-invoke with -y after explicit human approval.
|
||||
retryCmd := buildKBEditRetryCmd(c, id)
|
||||
if err := cmdutil.ConfirmDestructive(f.Prompter(), opts.Yes, fopts.WantsJSON(), "edit", "knowledge base", id, "kb.edit", retryCmd); err != nil {
|
||||
retryCmd := cmdutil.BuildRetryArgv(c, []string{"weknora", "kb", "update", id}, "name", "description", "format")
|
||||
if err := cmdutil.ConfirmWrite(f.Prompter(), opts.Yes, fopts.WantsJSON(), "update", "knowledge base", id, "kb.update", retryCmd); err != nil {
|
||||
return err
|
||||
}
|
||||
return runEdit(c.Context(), opts, fopts, cli, id)
|
||||
@@ -119,46 +116,28 @@ to the user first.`,
|
||||
cmd.Flags().StringVar(&desc, "description", "", "New description (omit to leave unchanged)")
|
||||
cmdutil.AddFormatFlag(cmd, kbEditFields...)
|
||||
cmdutil.AddDryRunFlag(cmd, &opts.DryRun)
|
||||
cmdutil.SetRisk(cmd, "kb.edit")
|
||||
cmdutil.SetWriteRisk(cmd, "kb.update")
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "update a knowledge base's name or description",
|
||||
RequiredFlags: []string{"<kb-id> (positional)", "--name or --description (at least one)"},
|
||||
Output: "envelope.data is the updated KnowledgeBase object (id, name, description)",
|
||||
Examples: []string{
|
||||
"weknora kb edit kb_abc --name \"New Name\" -y",
|
||||
"weknora kb edit kb_abc --description \"Updated desc\" --format json -y",
|
||||
"weknora kb update kb_abc --name \"New Name\" -y",
|
||||
"weknora kb update kb_abc --description \"Updated desc\" --format json -y",
|
||||
},
|
||||
Warnings: []string{
|
||||
"Requires explicit user approval (exit 10 / input.confirmation_required); never auto-add -y.",
|
||||
"kb edit overwrites fields; SDK uses fetch-then-update to avoid clobbering, but malformed input can still corrupt config.",
|
||||
"kb update overwrites fields; SDK uses fetch-then-update to avoid clobbering, but malformed input can still corrupt config.",
|
||||
},
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
|
||||
// buildKBEditRetryCmd constructs a directly-executable retry argv from the
|
||||
// flags the user actually set so agents can surface a precise re-run command.
|
||||
func buildKBEditRetryCmd(c *cobra.Command, id string) string {
|
||||
var parts []string
|
||||
parts = append(parts, "weknora", "kb", "edit", id)
|
||||
c.Flags().Visit(func(f *pflag.Flag) {
|
||||
switch f.Name {
|
||||
case "name":
|
||||
parts = append(parts, "--name", f.Value.String())
|
||||
case "description":
|
||||
parts = append(parts, "--description", f.Value.String())
|
||||
case "format":
|
||||
parts = append(parts, "--format", f.Value.String())
|
||||
}
|
||||
})
|
||||
parts = append(parts, "-y")
|
||||
return strings.Join(parts, " ")
|
||||
}
|
||||
|
||||
func runEdit(ctx context.Context, opts *EditOptions, fopts *cmdutil.FormatOptions, svc EditService, id string) error {
|
||||
if opts.Name == nil && opts.Description == nil {
|
||||
return &cmdutil.Error{
|
||||
Code: cmdutil.CodeInputMissingFlag,
|
||||
Message: "kb edit requires at least one of --name or --description",
|
||||
Message: "kb update requires at least one of --name or --description",
|
||||
Hint: "pass --name <name> and/or --description <desc>",
|
||||
}
|
||||
}
|
||||
@@ -183,7 +162,7 @@ func runEdit(ctx context.Context, opts *EditOptions, fopts *cmdutil.FormatOption
|
||||
|
||||
updated, err := svc.UpdateKnowledgeBase(ctx, id, req)
|
||||
if err != nil {
|
||||
return cmdutil.WrapHTTP(err, "edit knowledge base %s", id)
|
||||
return cmdutil.WrapHTTP(err, "update knowledge base %s", id)
|
||||
}
|
||||
if fopts.WantsJSON() {
|
||||
return fopts.Emit(iostreams.IO.Out, updated, nil)
|
||||
|
||||
@@ -15,8 +15,7 @@ import (
|
||||
// "no mutation flag supplied" invocation the live path rejects. Before the
|
||||
// fix the validation lived in runEdit() (the live-only callee) and was
|
||||
// reached only after HandleDryRun early-exited, so --dry-run silently
|
||||
// emitted a no-op plan envelope. Industry standard (gh / kubectl / lark)
|
||||
// validates before previewing.
|
||||
// emitted a no-op plan envelope. Validation must run before previewing.
|
||||
func TestKBEdit_DryRun_RejectsNoMutationFlag(t *testing.T) {
|
||||
iostreams.SetForTest(t)
|
||||
f := kbDryRunFactory(t)
|
||||
|
||||
@@ -119,7 +119,7 @@ func TestEdit_NotFound(t *testing.T) {
|
||||
|
||||
func stringPtr(s string) *string { return &s }
|
||||
|
||||
// withRootHarnessKB wraps `weknora kb edit ...` under a synthetic root cmd
|
||||
// withRootHarnessKB wraps `weknora kb update ...` under a synthetic root cmd
|
||||
// that registers the global persistent flags (mirrors addGlobalFlags in
|
||||
// cmd/root.go). Required because NewCmdEdit reads --yes and --format from the
|
||||
// persistent flag set.
|
||||
@@ -132,7 +132,7 @@ func withRootHarnessKB(edit *cobra.Command, args ...string) *cobra.Command {
|
||||
kb := &cobra.Command{Use: "kb"}
|
||||
kb.AddCommand(edit)
|
||||
root.AddCommand(kb)
|
||||
root.SetArgs(append([]string{"kb", "edit"}, args...))
|
||||
root.SetArgs(append([]string{"kb", "update"}, args...))
|
||||
root.SetContext(context.Background())
|
||||
root.SilenceErrors = true
|
||||
root.SilenceUsage = true
|
||||
@@ -140,7 +140,7 @@ func withRootHarnessKB(edit *cobra.Command, args ...string) *cobra.Command {
|
||||
}
|
||||
|
||||
// TestKBEdit_RequiresConfirmation asserts that without -y (non-TTY / JSON
|
||||
// mode), kb edit returns input.confirmation_required (exit 10).
|
||||
// mode), kb update returns input.confirmation_required (exit 10).
|
||||
func TestKBEdit_RequiresConfirmation(t *testing.T) {
|
||||
iostreams.SetForTest(t) // non-TTY
|
||||
svc := &fakeEditSvc{
|
||||
@@ -159,7 +159,7 @@ func TestKBEdit_RequiresConfirmation(t *testing.T) {
|
||||
require.ErrorAs(t, err, &ce)
|
||||
assert.Equal(t, cmdutil.CodeInputConfirmationRequired, ce.Code)
|
||||
assert.Equal(t, 10, cmdutil.ExitCode(err))
|
||||
// retry command must include -y
|
||||
assert.Contains(t, ce.RetryCommand, "-y")
|
||||
assert.Contains(t, ce.RetryCommand, "kb_abc")
|
||||
// retry argv must include -y
|
||||
assert.Contains(t, ce.RetryArgv, "-y")
|
||||
assert.Contains(t, ce.RetryArgv, "kb_abc")
|
||||
}
|
||||
|
||||
+3
-2
@@ -1,6 +1,6 @@
|
||||
// Package kb holds the `weknora kb` command tree: list / view / create /
|
||||
// edit / delete / pin / unpin. Verb set follows common CRUD vocabulary
|
||||
// (list/view/create/edit/delete) plus pin/unpin. Bulk content deletion
|
||||
// update / delete / pin / unpin. Verb set follows common CRUD vocabulary
|
||||
// (list/view/create/update/delete) plus pin/unpin. Bulk content deletion
|
||||
// is exposed via `weknora doc delete --all --kb=<id>`.
|
||||
package kb
|
||||
|
||||
@@ -25,5 +25,6 @@ func NewCmd(f *cmdutil.Factory) *cobra.Command {
|
||||
cmd.AddCommand(NewCmdUnpin(f))
|
||||
cmd.AddCommand(NewCmdStatus(f))
|
||||
cmd.AddCommand(NewCmdCheck(f))
|
||||
cmd.AddCommand(NewCmdConfig(f)) // `config` also hosts the `config set` write subcommand
|
||||
return cmd
|
||||
}
|
||||
|
||||
+29
-9
@@ -57,6 +57,12 @@ func NewCmdList(f *cmdutil.Factory) *cobra.Command {
|
||||
return err
|
||||
}
|
||||
fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
|
||||
// Validate static input before building the client so a bad --limit
|
||||
// returns input.invalid_argument (exit 5) rather than an auth error
|
||||
// (exit 3) when no profile is configured.
|
||||
if err := validateListOpts(opts); err != nil {
|
||||
return err
|
||||
}
|
||||
cli, err := f.Client()
|
||||
if err != nil {
|
||||
return err
|
||||
@@ -65,23 +71,33 @@ func NewCmdList(f *cmdutil.Factory) *cobra.Command {
|
||||
},
|
||||
}
|
||||
cmd.Flags().BoolVar(&opts.Pinned, "pinned", false, "Only show pinned knowledge bases")
|
||||
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)")
|
||||
cmdutil.AddFormatFlag(cmd, kbListFields...)
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "List knowledge bases in the current tenant. --format json emits the v0.7 envelope {ok, data:[...], meta:{count}, profile}.",
|
||||
UsedFor: "List knowledge bases in the current tenant. --format json emits the standard envelope {ok, data:[...], meta:{count}, profile}.",
|
||||
Examples: []string{"weknora kb list --format json"},
|
||||
Output: "envelope.data is an array of KnowledgeBase objects with id, name, is_pinned, type, embedding_model_id",
|
||||
Output: "envelope.data is an array of KnowledgeBase objects with id, name, is_pinned, type, embedding_model_id; meta.total_count is the full tenant set and meta.has_more=true means --limit truncated it (raise --limit to get the rest)",
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
|
||||
func runList(ctx context.Context, opts *ListOptions, fopts *cmdutil.FormatOptions, svc ListService) error {
|
||||
// validateListOpts checks --limit. Called from RunE before the client is built
|
||||
// (so a bad value surfaces as exit 5, not an auth error) and at runList's top
|
||||
// for direct callers; idempotent.
|
||||
func validateListOpts(opts *ListOptions) error {
|
||||
if opts.Limit < 1 || opts.Limit > 10000 {
|
||||
return &cmdutil.Error{
|
||||
Code: cmdutil.CodeInputInvalidArgument,
|
||||
Message: fmt.Sprintf("--limit must be in 1..10000, got %d", opts.Limit),
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func runList(ctx context.Context, opts *ListOptions, fopts *cmdutil.FormatOptions, svc ListService) error {
|
||||
if err := validateListOpts(opts); err != nil {
|
||||
return err
|
||||
}
|
||||
items, err := svc.ListKnowledgeBases(ctx)
|
||||
if err != nil {
|
||||
return cmdutil.WrapHTTP(err, "list knowledge bases")
|
||||
@@ -104,16 +120,20 @@ func runList(ctx context.Context, opts *ListOptions, fopts *cmdutil.FormatOption
|
||||
sort.Slice(items, func(i, j int) bool {
|
||||
return items[i].UpdatedAt.After(items[j].UpdatedAt)
|
||||
})
|
||||
// --limit applies after sort so the cap returns the top-N most-recent.
|
||||
// The KB list SDK is unpaginated, so client-side truncation does not
|
||||
// imply server-side has_more — there is no cursor to continue with.
|
||||
// has_more is omitted; callers needing all KBs should raise --limit.
|
||||
// The KB list SDK is unpaginated — it returns every KB in one call —
|
||||
// so the CLI holds the true total and can tell the caller whether the
|
||||
// client-side --limit dropped any. total_count is the full count;
|
||||
// has_more flags that --limit truncated it (raise --limit to get the
|
||||
// rest — there is no server cursor to continue with).
|
||||
total := len(items)
|
||||
truncated := false
|
||||
if opts.Limit > 0 && len(items) > opts.Limit {
|
||||
items = items[:opts.Limit]
|
||||
truncated = true
|
||||
}
|
||||
|
||||
if fopts.WantsJSON() {
|
||||
meta := &output.Meta{Count: len(items)}
|
||||
meta := &output.Meta{Count: output.IntPtr(len(items)), HasMore: truncated, TotalCount: output.IntPtr(total)}
|
||||
return fopts.Emit(iostreams.IO.Out, items, meta)
|
||||
}
|
||||
|
||||
|
||||
@@ -172,6 +172,43 @@ func TestList_Limit_CapsResults(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// TestList_Truncation_SignalsHasMoreAndTotal pins that a client-side --limit
|
||||
// truncation tells the agent it did NOT get everything: has_more=true and
|
||||
// total_count=full set. Regression: kb list silently dropped items past
|
||||
// --limit with no completeness signal, so an agent listing to find a KB by
|
||||
// name could miss KBs beyond position 30 and never know.
|
||||
func TestList_Truncation_SignalsHasMoreAndTotal(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &fakeListSvc{items: makeKBs(20)}
|
||||
fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}
|
||||
if err := runList(context.Background(), &ListOptions{Limit: 5}, fopts, svc); err != nil {
|
||||
t.Fatalf("runList: %v", err)
|
||||
}
|
||||
if !strings.Contains(out.String(), `"has_more":true`) {
|
||||
t.Errorf("truncated list must set has_more:true; got:\n%s", out.String())
|
||||
}
|
||||
if !strings.Contains(out.String(), `"total_count":20`) {
|
||||
t.Errorf("truncated list must report total_count:20; got:\n%s", out.String())
|
||||
}
|
||||
}
|
||||
|
||||
// TestList_NoTruncation_OmitsHasMore pins that when --limit does NOT truncate,
|
||||
// has_more is absent (omitempty) so the agent reads "complete".
|
||||
func TestList_NoTruncation_OmitsHasMore(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &fakeListSvc{items: makeKBs(3)}
|
||||
fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}
|
||||
if err := runList(context.Background(), &ListOptions{Limit: 30}, fopts, svc); err != nil {
|
||||
t.Fatalf("runList: %v", err)
|
||||
}
|
||||
if strings.Contains(out.String(), `"has_more"`) {
|
||||
t.Errorf("non-truncated list must omit has_more; got:\n%s", out.String())
|
||||
}
|
||||
if !strings.Contains(out.String(), `"total_count":3`) {
|
||||
t.Errorf("list must report total_count:3; got:\n%s", out.String())
|
||||
}
|
||||
}
|
||||
|
||||
func TestList_Limit_Zero_Rejected(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
svc := &fakeListSvc{items: makeKBs(7)}
|
||||
|
||||
+23
-6
@@ -21,10 +21,13 @@ type PinOptions struct {
|
||||
}
|
||||
|
||||
// PinService is the narrow SDK surface this command depends on. The CLI
|
||||
// reads current state before toggling so `pin`/`unpin` are idempotent -
|
||||
// the server endpoint is only a non-idempotent toggle.
|
||||
// reads current state before toggling so `pin`/`unpin` are idempotent — the
|
||||
// server endpoint is only a toggle. Pin state is read from the LIST endpoint:
|
||||
// the single-KB GET does not carry per-user pin state (pin is a per-user
|
||||
// list-ordering preference, surfaced where the user sees it — in `kb list`),
|
||||
// so the list is the canonical source.
|
||||
type PinService interface {
|
||||
GetKnowledgeBase(ctx context.Context, id string) (*sdk.KnowledgeBase, error)
|
||||
ListKnowledgeBases(ctx context.Context) ([]sdk.KnowledgeBase, error)
|
||||
TogglePinKnowledgeBase(ctx context.Context, id string) (*sdk.KnowledgeBase, error)
|
||||
}
|
||||
|
||||
@@ -73,7 +76,7 @@ func newPinCmd(f *cmdutil.Factory, use string, want bool, short string) *cobra.C
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: use + " a knowledge base (idempotent: a no-op if it is already in the target state)",
|
||||
RequiredFlags: []string{"<kb-id> (positional)"},
|
||||
Examples: []string{"weknora " + use + " kb_abc"},
|
||||
Examples: []string{"weknora kb " + use + " kb_abc"},
|
||||
Output: "envelope.data is the KnowledgeBase with is_pinned reflecting the new state",
|
||||
})
|
||||
return cmd
|
||||
@@ -84,9 +87,23 @@ func runPin(ctx context.Context, opts *PinOptions, fopts *cmdutil.FormatOptions,
|
||||
if !want {
|
||||
verb = "unpin"
|
||||
}
|
||||
current, err := svc.GetKnowledgeBase(ctx, id)
|
||||
// Read the current pin state from the list (the canonical per-user pin
|
||||
// source); the single-KB GET doesn't carry it. This makes pin/unpin
|
||||
// idempotent: we toggle only when the state actually needs to change.
|
||||
kbs, err := svc.ListKnowledgeBases(ctx)
|
||||
if err != nil {
|
||||
return cmdutil.WrapHTTP(err, "get knowledge base %s", id)
|
||||
return cmdutil.WrapHTTP(err, "list knowledge bases")
|
||||
}
|
||||
var current *sdk.KnowledgeBase
|
||||
for i := range kbs {
|
||||
if kbs[i].ID == id {
|
||||
current = &kbs[i]
|
||||
break
|
||||
}
|
||||
}
|
||||
if current == nil {
|
||||
return cmdutil.NewError(cmdutil.CodeResourceNotFound,
|
||||
fmt.Sprintf("knowledge base not found: %s", id))
|
||||
}
|
||||
if current.IsPinned == want {
|
||||
state := "pinned"
|
||||
|
||||
@@ -15,7 +15,9 @@ import (
|
||||
sdk "github.com/Tencent/WeKnora/client"
|
||||
)
|
||||
|
||||
// fakePinSvc satisfies PinService: GetKnowledgeBase + TogglePinKnowledgeBase.
|
||||
// fakePinSvc satisfies PinService: ListKnowledgeBases + TogglePinKnowledgeBase.
|
||||
// The fake's `current` is returned as the single KB in the list (the list is
|
||||
// the canonical pin-state source).
|
||||
type fakePinSvc struct {
|
||||
current sdk.KnowledgeBase
|
||||
getErr error
|
||||
@@ -23,13 +25,15 @@ type fakePinSvc struct {
|
||||
toggleCalled bool
|
||||
}
|
||||
|
||||
func (f *fakePinSvc) GetKnowledgeBase(_ context.Context, id string) (*sdk.KnowledgeBase, error) {
|
||||
func (f *fakePinSvc) ListKnowledgeBases(_ context.Context) ([]sdk.KnowledgeBase, error) {
|
||||
if f.getErr != nil {
|
||||
return nil, f.getErr
|
||||
}
|
||||
c := f.current
|
||||
c.ID = id
|
||||
return &c, nil
|
||||
if c.ID == "" {
|
||||
c.ID = "kb_abc" // tests address this id
|
||||
}
|
||||
return []sdk.KnowledgeBase{c}, nil
|
||||
}
|
||||
|
||||
func (f *fakePinSvc) TogglePinKnowledgeBase(_ context.Context, id string) (*sdk.KnowledgeBase, error) {
|
||||
|
||||
+22
-8
@@ -16,12 +16,16 @@ import (
|
||||
// Shallow read only: 1 HTTP call, no failed-doc aggregation.
|
||||
// For deep verification including failed_count, use `kb check <id>`.
|
||||
type StatusResult struct {
|
||||
ID string `json:"id"`
|
||||
Reachable bool `json:"reachable"`
|
||||
KnowledgeCount int64 `json:"knowledge_count,omitempty"`
|
||||
ChunkCount int64 `json:"chunk_count,omitempty"`
|
||||
IsProcessing bool `json:"is_processing,omitempty"`
|
||||
ProcessingCount int64 `json:"processing_count,omitempty"`
|
||||
ID string `json:"id"`
|
||||
Reachable bool `json:"reachable"`
|
||||
// RetrievalReady is false when the KB has no embedding model bound — it can
|
||||
// never index or retrieve until `kb config set` runs. Always emitted (no
|
||||
// omitempty) so a not-ready KB is visible, not silently green.
|
||||
RetrievalReady bool `json:"retrieval_ready"`
|
||||
KnowledgeCount int64 `json:"knowledge_count,omitempty"`
|
||||
ChunkCount int64 `json:"chunk_count,omitempty"`
|
||||
IsProcessing bool `json:"is_processing,omitempty"`
|
||||
ProcessingCount int64 `json:"processing_count,omitempty"`
|
||||
}
|
||||
|
||||
// StatusService is the narrow SDK surface needed for kb status.
|
||||
@@ -30,7 +34,7 @@ type StatusService interface {
|
||||
}
|
||||
|
||||
var kbStatusFields = []string{
|
||||
"id", "reachable", "knowledge_count", "chunk_count",
|
||||
"id", "reachable", "retrieval_ready", "knowledge_count", "chunk_count",
|
||||
"is_processing", "processing_count",
|
||||
}
|
||||
|
||||
@@ -73,7 +77,7 @@ For full metadata (config / pinned / tenant), use 'weknora kb view <id>'.`,
|
||||
UsedFor: "shallow health probe of a knowledge base (one HTTP call): reachability, no failed-doc aggregation",
|
||||
RequiredFlags: []string{"<kb-id> (positional)"},
|
||||
Examples: []string{"weknora kb status kb_abc"},
|
||||
Output: "envelope.data is {id, reachable, ...}; use `kb check` for deep failed-doc aggregation",
|
||||
Output: "envelope.data is {id, reachable, retrieval_ready, ...}; retrieval_ready=false means no embedding model is bound (run `kb config set`), so the KB cannot index/retrieve; use `kb check` for deep failed-doc aggregation",
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
@@ -89,6 +93,7 @@ func runStatus(ctx context.Context, svc StatusService, id string) (*StatusResult
|
||||
return &StatusResult{
|
||||
ID: kb.ID,
|
||||
Reachable: true,
|
||||
RetrievalReady: kb.EmbeddingModelID != "",
|
||||
KnowledgeCount: kb.KnowledgeCount,
|
||||
ChunkCount: kb.ChunkCount,
|
||||
IsProcessing: kb.IsProcessing,
|
||||
@@ -115,11 +120,20 @@ func writeStatusText(w io.Writer, res *StatusResult) error {
|
||||
if !res.Reachable {
|
||||
return nil
|
||||
}
|
||||
fmt.Fprintf(w, "Retrieval: %v%s\n", res.RetrievalReady, retrievalHint(res.RetrievalReady))
|
||||
fmt.Fprintf(w, "Knowledge: %d\n", res.KnowledgeCount)
|
||||
fmt.Fprintf(w, "Chunks: %d\n", res.ChunkCount)
|
||||
fmt.Fprintf(w, "Processing: %v (%d active)\n", res.IsProcessing, res.ProcessingCount)
|
||||
return nil
|
||||
}
|
||||
|
||||
// retrievalHint annotates a not-ready KB in text output with the fix.
|
||||
func retrievalHint(ready bool) string {
|
||||
if ready {
|
||||
return ""
|
||||
}
|
||||
return " ← no embedding model bound; run `weknora kb config set <id>`"
|
||||
}
|
||||
|
||||
// compile-time check: SDK client satisfies StatusService.
|
||||
var _ StatusService = (*sdk.Client)(nil)
|
||||
|
||||
@@ -26,11 +26,12 @@ func (f *fakeStatusSvc) GetKnowledgeBase(_ context.Context, id string) (*sdk.Kno
|
||||
|
||||
func TestRunStatus_ShallowFields(t *testing.T) {
|
||||
svc := &fakeStatusSvc{kb: &sdk.KnowledgeBase{
|
||||
ID: "kb_x",
|
||||
KnowledgeCount: 42,
|
||||
ChunkCount: 100,
|
||||
IsProcessing: true,
|
||||
ProcessingCount: 3,
|
||||
ID: "kb_x",
|
||||
KnowledgeCount: 42,
|
||||
ChunkCount: 100,
|
||||
IsProcessing: true,
|
||||
ProcessingCount: 3,
|
||||
EmbeddingModelID: "emb_1",
|
||||
}}
|
||||
res, err := runStatus(context.Background(), svc, "kb_x")
|
||||
if err != nil {
|
||||
@@ -42,6 +43,22 @@ func TestRunStatus_ShallowFields(t *testing.T) {
|
||||
if res.KnowledgeCount != 42 || res.ChunkCount != 100 || res.ProcessingCount != 3 || !res.IsProcessing {
|
||||
t.Errorf("got %+v", res)
|
||||
}
|
||||
if !res.RetrievalReady {
|
||||
t.Error("RetrievalReady=false, want true when an embedding model is bound")
|
||||
}
|
||||
}
|
||||
|
||||
// A KB with no embedding model can never retrieve — the health probe must say
|
||||
// so (retrieval_ready=false), not report a silent all-green status.
|
||||
func TestRunStatus_RetrievalNotReadyWithoutEmbeddingModel(t *testing.T) {
|
||||
svc := &fakeStatusSvc{kb: &sdk.KnowledgeBase{ID: "kb_x", KnowledgeCount: 1}}
|
||||
res, err := runStatus(context.Background(), svc, "kb_x")
|
||||
if err != nil {
|
||||
t.Fatalf("runStatus: %v", err)
|
||||
}
|
||||
if res.RetrievalReady {
|
||||
t.Error("RetrievalReady=true, want false when no embedding model is bound")
|
||||
}
|
||||
}
|
||||
|
||||
func TestRunStatus_Unreachable(t *testing.T) {
|
||||
|
||||
@@ -27,8 +27,11 @@ var kbViewFields = []string{
|
||||
type ViewOptions struct{}
|
||||
|
||||
// ViewService is the narrow SDK surface this command depends on.
|
||||
// ListKnowledgeBases is used only to enrich is_pinned (the single-KB GET
|
||||
// doesn't carry per-user pin state — pin is a per-user list concept).
|
||||
type ViewService interface {
|
||||
GetKnowledgeBase(ctx context.Context, id string) (*sdk.KnowledgeBase, error)
|
||||
ListKnowledgeBases(ctx context.Context) ([]sdk.KnowledgeBase, error)
|
||||
}
|
||||
|
||||
// NewCmdView builds `weknora kb view <id>`.
|
||||
@@ -70,6 +73,18 @@ func runView(ctx context.Context, opts *ViewOptions, fopts *cmdutil.FormatOption
|
||||
if err != nil {
|
||||
return cmdutil.WrapHTTP(err, "get knowledge base %q", id)
|
||||
}
|
||||
// The single-KB GET doesn't stamp per-user pin state, so is_pinned would
|
||||
// always read false here. Enrich it from the list (the canonical pin
|
||||
// source) so the field is accurate. Best-effort: a list error leaves the
|
||||
// (unstamped) value rather than failing the view.
|
||||
if kbs, lerr := svc.ListKnowledgeBases(ctx); lerr == nil {
|
||||
for i := range kbs {
|
||||
if kbs[i].ID == id {
|
||||
kb.IsPinned = kbs[i].IsPinned
|
||||
break
|
||||
}
|
||||
}
|
||||
}
|
||||
if fopts.WantsJSON() {
|
||||
return fopts.Emit(iostreams.IO.Out, kb, nil)
|
||||
}
|
||||
|
||||
@@ -22,6 +22,15 @@ func (f *fakeGetSvc) GetKnowledgeBase(ctx context.Context, id string) (*sdk.Know
|
||||
return f.kb, f.err
|
||||
}
|
||||
|
||||
// ListKnowledgeBases backs is_pinned enrichment in runView. Returns the same
|
||||
// KB so the enrichment finds it; nil/empty is fine (enrichment is best-effort).
|
||||
func (f *fakeGetSvc) ListKnowledgeBases(ctx context.Context) ([]sdk.KnowledgeBase, error) {
|
||||
if f.kb == nil {
|
||||
return nil, nil
|
||||
}
|
||||
return []sdk.KnowledgeBase{*f.kb}, nil
|
||||
}
|
||||
|
||||
func TestGet_OK_Text(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &fakeGetSvc{kb: &sdk.KnowledgeBase{
|
||||
|
||||
+34
-12
@@ -40,29 +40,42 @@ type linkResult struct {
|
||||
func NewCmd(f *cmdutil.Factory) *cobra.Command {
|
||||
opts := &Options{}
|
||||
cmd := &cobra.Command{
|
||||
Use: "link",
|
||||
Use: "link [kb]",
|
||||
Short: "Bind the current directory to a knowledge base",
|
||||
Long: `Writes .weknora/project.yaml in the current working directory pointing
|
||||
at the supplied knowledge base. Subsequent commands run from this directory
|
||||
(or any subdirectory) automatically resolve --kb from the link unless
|
||||
overridden by the --kb flag or WEKNORA_KB_ID env var.
|
||||
|
||||
Pass --kb <id-or-name> for non-interactive use (scripts, CI). Run on a TTY
|
||||
without --kb to be prompted from the list of available KBs. Always overwrites
|
||||
any existing link - re-run to switch.
|
||||
Pass the knowledge base as a positional argument (weknora link <id-or-name>) or
|
||||
via --kb — the two are equivalent — for non-interactive use (scripts, CI). Run
|
||||
on a TTY without either to be prompted from the list of available KBs. Always
|
||||
overwrites any existing link - re-run to switch.
|
||||
|
||||
AI agents: link writes to the user's working directory. Only run it when the
|
||||
user explicitly asked to bind this directory; don't run it as a side effect.`,
|
||||
Example: ` weknora link --kb a32a63ff-fb36-4874-bcaa-30f48570a694 # explicit UUID
|
||||
weknora link --kb engineering # name → id
|
||||
Example: ` weknora link a32a63ff-fb36-4874-bcaa-30f48570a694 # positional UUID
|
||||
weknora link engineering # positional name → id
|
||||
weknora link --kb engineering # --kb form (equivalent)
|
||||
weknora link # interactive (TTY)`,
|
||||
Args: cobra.NoArgs,
|
||||
RunE: func(c *cobra.Command, _ []string) error {
|
||||
// The knowledge base may be given as a positional arg (matching every
|
||||
// other <id> command) or via --kb; the two are equivalent.
|
||||
Args: cobra.MaximumNArgs(1),
|
||||
RunE: func(c *cobra.Command, args []string) error {
|
||||
fopts, err := cmdutil.CheckFormatFlag(c)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
|
||||
// Accept the KB as a positional (consistent with `kb view <id>`,
|
||||
// `doc view <id>`, …) in addition to --kb. Reject supplying both.
|
||||
if len(args) == 1 {
|
||||
if opts.KB != "" && opts.KB != args[0] {
|
||||
return cmdutil.NewError(cmdutil.CodeInputInvalidArgument,
|
||||
"specify the knowledge base once: as a positional argument or --kb, not both")
|
||||
}
|
||||
opts.KB = args[0]
|
||||
}
|
||||
// Pure-local validation runs before the dry-run gate so --dry-run
|
||||
// rejects identically to the live path. resolveProfile only reads
|
||||
// config; the non-TTY-without-`--kb` check is a flag-shape error.
|
||||
@@ -88,9 +101,10 @@ user explicitly asked to bind this directory; don't run it as a side effect.`,
|
||||
cmdutil.AddFormatFlag(cmd, linkFields...)
|
||||
cmdutil.AddDryRunFlag(cmd, &opts.DryRun)
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "Bind the current directory to a knowledge base by writing .weknora/project.yaml. Requires --kb (non-interactive); only run when the user explicitly asks to link this directory.",
|
||||
RequiredFlags: []string{"--kb (required when no TTY)"},
|
||||
Output: "envelope.data has kb_id, kb_name, project_link_path",
|
||||
UsedFor: "Bind the current directory to a knowledge base by writing .weknora/project.yaml. Give the KB as a positional arg or --kb (non-interactive); only run when the user explicitly asks to link this directory.",
|
||||
RequiredFlags: []string{"<kb> positional or --kb (required when no TTY)"},
|
||||
Examples: []string{"weknora link engineering", "weknora link --kb a32a63ff-fb36-4874-bcaa-30f48570a694"},
|
||||
Output: "envelope.data has profile, kb_id, kb_name, project_link_path",
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
@@ -149,7 +163,15 @@ func resolveProfile(f *cmdutil.Factory) (string, error) {
|
||||
return "", err
|
||||
}
|
||||
if cfg.CurrentProfile == "" {
|
||||
return "", cmdutil.NewError(cmdutil.CodeAuthUnauthenticated, "no active profile; run `weknora auth login` first")
|
||||
// `link` binds a directory to a profile+KB, so it needs a configured
|
||||
// profile — env credentials (WEKNORA_API_KEY) alone have no profile to
|
||||
// record. Point at profile setup (not `auth login`, which loops with no
|
||||
// profile) and name the headless alternative so an env-cred agent isn't
|
||||
// stranded on a misleading hint.
|
||||
return "", cmdutil.NewError(cmdutil.CodeAuthUnauthenticated,
|
||||
"`link` records an active profile, but none is configured").
|
||||
WithHint("register one with `weknora profile add <name> --host <url> --use`; for a headless (WEKNORA_API_KEY) workflow, skip `link` and pass --kb per command or set WEKNORA_KB_ID").
|
||||
WithRetryArgv([]string{"weknora", "profile", "add", "--help"})
|
||||
}
|
||||
return cfg.CurrentProfile, nil
|
||||
}
|
||||
|
||||
@@ -79,6 +79,9 @@ is present anywhere in the parent chain.`,
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "Remove the .weknora/project.yaml KB binding from the current directory tree. No flags required; walks up from cwd to find the link.",
|
||||
Output: "envelope.data has project_link_path of the removed file",
|
||||
Examples: []string{
|
||||
"weknora unlink",
|
||||
},
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
|
||||
@@ -49,6 +49,9 @@ Consult your MCP client's documentation for the exact config-file location.`,
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "run weknora as a long-lived MCP (Model Context Protocol) server over stdio for an IDE/host agent",
|
||||
Output: "no stdout payload (JSON-RPC 2.0 protocol traffic); logs go to stderr",
|
||||
Examples: []string{
|
||||
"weknora mcp serve",
|
||||
},
|
||||
Warnings: []string{
|
||||
"this is a long-running stdio server, not a one-shot command — register it in your MCP client (command: weknora, args: [mcp, serve])",
|
||||
"exits with auth.unauthenticated at startup if no profile is configured",
|
||||
|
||||
@@ -0,0 +1,117 @@
|
||||
package messagecmd
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
||||
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
||||
"github.com/Tencent/WeKnora/cli/internal/prompt"
|
||||
)
|
||||
|
||||
var messageDeleteFields = []string{"id", "deleted"}
|
||||
|
||||
// DeleteOptions holds the parsed flag/arg values for `message delete`.
|
||||
type DeleteOptions struct {
|
||||
SessionID string
|
||||
MessageID string
|
||||
Yes bool
|
||||
DryRun bool
|
||||
}
|
||||
|
||||
// DeleteService is the narrow SDK surface this command depends on.
|
||||
type DeleteService interface {
|
||||
DeleteMessage(ctx context.Context, sessionID, messageID string) error
|
||||
}
|
||||
|
||||
// deleteResult is the typed payload emitted on success in JSON mode.
|
||||
type deleteResult struct {
|
||||
ID string `json:"id"`
|
||||
Deleted bool `json:"deleted"`
|
||||
}
|
||||
|
||||
const messageDeleteLong = `Permanently delete one message from a session.
|
||||
|
||||
Requires both the message id (positional) and the parent session id
|
||||
(--session) because the server route encodes both:
|
||||
DELETE /messages/{session_id}/{id}.
|
||||
|
||||
Deleting an assistant message breaks the turn chain for follow-up
|
||||
references (session ask). Prefer deleting whole sessions
|
||||
(weknora session delete) unless you specifically need to redact one turn.
|
||||
|
||||
Typed exit codes:
|
||||
resource.not_found no message with the given id under that session (exit 4)
|
||||
auth.forbidden caller lacks delete permission on the message (exit 3)
|
||||
input.confirmation_required destructive op without -y on a TTY (exit 10)
|
||||
|
||||
AI agents: this is a high-risk write. Without -y/--yes the CLI exits 10
|
||||
and writes input.confirmation_required to stderr. NEVER auto-pass -y
|
||||
without the user's explicit go-ahead — the exit-10 protocol exists
|
||||
exactly to guard against unintended deletes.`
|
||||
|
||||
// NewCmdDelete builds `weknora message delete <message-id> --session <session-id>`.
|
||||
func NewCmdDelete(f *cmdutil.Factory) *cobra.Command {
|
||||
opts := &DeleteOptions{}
|
||||
cmd := &cobra.Command{
|
||||
Use: "delete <message-id> --session <session-id>",
|
||||
Short: "Delete one message from a session (high-risk write)",
|
||||
Long: messageDeleteLong,
|
||||
Example: ` weknora message delete msg_abc --session sess_xyz # interactive confirm
|
||||
weknora message delete msg_abc --session sess_xyz -y # no prompt
|
||||
weknora message delete msg_abc --session sess_xyz -y --format json # agent / JSON form`,
|
||||
Args: cobra.ExactArgs(1),
|
||||
RunE: func(c *cobra.Command, args []string) error {
|
||||
fopts, err := cmdutil.CheckFormatFlag(c)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
|
||||
opts.MessageID = args[0]
|
||||
opts.Yes, _ = c.Flags().GetBool("yes")
|
||||
if handled, err := cmdutil.HandleDryRun(c, opts.DryRun, cmdutil.DryRunPlan{
|
||||
Action: "message.delete",
|
||||
Args: map[string]any{"message_id": opts.MessageID, "session": opts.SessionID},
|
||||
}); handled {
|
||||
return err
|
||||
}
|
||||
cli, err := f.Client()
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
return runDelete(c.Context(), opts, fopts, cli, f.Prompter())
|
||||
},
|
||||
}
|
||||
cmd.Flags().StringVar(&opts.SessionID, "session", "", "Parent session id the message lives in")
|
||||
_ = cmd.MarkFlagRequired("session")
|
||||
cmdutil.AddFormatFlag(cmd, messageDeleteFields...)
|
||||
cmdutil.AddDryRunFlag(cmd, &opts.DryRun)
|
||||
cmdutil.SetRisk(cmd, "message.delete")
|
||||
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
|
||||
UsedFor: "permanently delete one message from a session",
|
||||
RequiredFlags: []string{"<message-id> (positional)", "--session <session-id>"},
|
||||
Examples: []string{"weknora message delete msg_abc --session sess_xyz -y"},
|
||||
Output: "envelope.data is {id, deleted:true}",
|
||||
Warnings: []string{
|
||||
"Requires explicit user approval (exit 10 / input.confirmation_required); never auto-add -y.",
|
||||
"message delete is irreversible; breaks the turn chain for follow-up references to that conversation turn.",
|
||||
},
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
|
||||
func runDelete(ctx context.Context, opts *DeleteOptions, fopts *cmdutil.FormatOptions, svc DeleteService, p prompt.Prompter) error {
|
||||
if err := cmdutil.ConfirmDestructive(p, opts.Yes, fopts.WantsJSON(), "delete", "message", opts.MessageID, "message.delete", []string{"weknora", "message", "delete", opts.MessageID, "--session", opts.SessionID, "-y"}); err != nil {
|
||||
return err
|
||||
}
|
||||
if err := svc.DeleteMessage(ctx, opts.SessionID, opts.MessageID); err != nil {
|
||||
return cmdutil.WrapHTTP(err, "delete message %s", opts.MessageID)
|
||||
}
|
||||
if fopts.WantsJSON() {
|
||||
return fopts.Emit(iostreams.IO.Out, deleteResult{ID: opts.MessageID, Deleted: true}, nil)
|
||||
}
|
||||
fmt.Fprintf(iostreams.IO.Out, "✓ Deleted message %s\n", opts.MessageID)
|
||||
return nil
|
||||
}
|
||||
@@ -0,0 +1,99 @@
|
||||
package messagecmd
|
||||
|
||||
import (
|
||||
"context"
|
||||
"errors"
|
||||
"testing"
|
||||
|
||||
"github.com/stretchr/testify/assert"
|
||||
"github.com/stretchr/testify/require"
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
||||
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
||||
"github.com/Tencent/WeKnora/cli/internal/testutil"
|
||||
)
|
||||
|
||||
type fakeDeleteSvc struct {
|
||||
err error
|
||||
gotSessID string
|
||||
gotMsgID string
|
||||
}
|
||||
|
||||
func (s *fakeDeleteSvc) DeleteMessage(_ context.Context, sessionID, messageID string) error {
|
||||
s.gotSessID, s.gotMsgID = sessionID, messageID
|
||||
return s.err
|
||||
}
|
||||
|
||||
// TestRunDelete_YesSkipsPromptAndDeletes verifies that -y bypasses the confirm
|
||||
// prompt, calls the service with the correct IDs, and emits {"deleted":true}
|
||||
// JSON.
|
||||
func TestRunDelete_YesSkipsPromptAndDeletes(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &fakeDeleteSvc{}
|
||||
opts := &DeleteOptions{SessionID: "s1", MessageID: "m1", Yes: true}
|
||||
require.NoError(t, runDelete(context.Background(), opts, jsonOpts(), svc, &testutil.ConfirmPrompter{}))
|
||||
assert.Equal(t, "s1", svc.gotSessID)
|
||||
assert.Equal(t, "m1", svc.gotMsgID)
|
||||
assert.Contains(t, out.String(), `"deleted":true`)
|
||||
}
|
||||
|
||||
// TestRunDelete_NoYesInJSONModeIsConfirmationRequired verifies that without -y
|
||||
// on a non-TTY (JSON mode), the CLI returns exit 10 /
|
||||
// input.confirmation_required and does NOT call the service.
|
||||
func TestRunDelete_NoYesInJSONModeIsConfirmationRequired(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
svc := &fakeDeleteSvc{}
|
||||
opts := &DeleteOptions{SessionID: "s1", MessageID: "m1", Yes: false}
|
||||
err := runDelete(context.Background(), opts, jsonOpts(), svc, &testutil.ConfirmPrompter{})
|
||||
require.Error(t, err)
|
||||
var typed *cmdutil.Error
|
||||
require.ErrorAs(t, err, &typed)
|
||||
assert.Equal(t, cmdutil.CodeInputConfirmationRequired, typed.Code)
|
||||
assert.Equal(t, 10, cmdutil.ExitCode(err), "exit 10 per destructive-write protocol")
|
||||
assert.Empty(t, svc.gotMsgID, "SDK must not be called without confirmation")
|
||||
}
|
||||
|
||||
// TestRunDelete_TTY_ConfirmYes_Deletes verifies the interactive TTY path where
|
||||
// the user answers yes: service is called, text output contains success line.
|
||||
func TestRunDelete_TTY_ConfirmYes_Deletes(t *testing.T) {
|
||||
out, _ := iostreams.SetForTestWithTTY(t)
|
||||
svc := &fakeDeleteSvc{}
|
||||
p := &testutil.ConfirmPrompter{Answer: true}
|
||||
opts := &DeleteOptions{SessionID: "s1", MessageID: "m1"}
|
||||
fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatText}
|
||||
require.NoError(t, runDelete(context.Background(), opts, fopts, svc, p))
|
||||
assert.True(t, p.Asked)
|
||||
assert.Equal(t, "m1", svc.gotMsgID)
|
||||
assert.Equal(t, "s1", svc.gotSessID)
|
||||
assert.Contains(t, out.String(), "Deleted message m1")
|
||||
}
|
||||
|
||||
// TestRunDelete_TTY_ConfirmNo_Aborts verifies the interactive TTY path where
|
||||
// the user declines: service is NOT called, error has CodeUserAborted.
|
||||
func TestRunDelete_TTY_ConfirmNo_Aborts(t *testing.T) {
|
||||
_, errBuf := iostreams.SetForTestWithTTY(t)
|
||||
svc := &fakeDeleteSvc{}
|
||||
p := &testutil.ConfirmPrompter{Answer: false}
|
||||
opts := &DeleteOptions{SessionID: "s1", MessageID: "m1"}
|
||||
fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatText}
|
||||
err := runDelete(context.Background(), opts, fopts, svc, p)
|
||||
require.Error(t, err)
|
||||
var typed *cmdutil.Error
|
||||
require.ErrorAs(t, err, &typed)
|
||||
assert.Equal(t, cmdutil.CodeUserAborted, typed.Code)
|
||||
assert.Empty(t, svc.gotMsgID, "answer=no must not call DeleteMessage")
|
||||
assert.Contains(t, errBuf.String(), "Aborted")
|
||||
}
|
||||
|
||||
// TestRunDelete_ServiceError_Propagates verifies that an SDK-level error is
|
||||
// wrapped and returned (service called but returns HTTP error).
|
||||
func TestRunDelete_ServiceError_Propagates(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
svc := &fakeDeleteSvc{err: errors.New("HTTP error 404: not found")}
|
||||
opts := &DeleteOptions{SessionID: "s1", MessageID: "missing", Yes: true}
|
||||
err := runDelete(context.Background(), opts, jsonOpts(), svc, &testutil.ConfirmPrompter{})
|
||||
require.Error(t, err)
|
||||
var typed *cmdutil.Error
|
||||
require.ErrorAs(t, err, &typed)
|
||||
assert.Equal(t, cmdutil.CodeResourceNotFound, typed.Code)
|
||||
}
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user