255 Commits

Author SHA1 Message Date
姚章浩 3619f44ac8 test(concurrency): 修复异步测试仓库与事件计数竞争 2026-10-28 10:48:56 +08:00
姚章浩 23387779c1 fix(index): 修复父子模式遗漏无父节点正文索引 2026-10-28 08:56:14 +08:00
wizardchen c64a48647c chore(release): prepare v0.7.1
Bump version to 0.7.1 across VERSION, frontend package manifests, and the
Helm chart appVersion. Add the 0.7.1 CHANGELOG entry and refresh all README
locales (badge, latest-updates, IM channel list with Yunzhijia).

Regenerate Swagger/OpenAPI docs, refresh the architecture diagram (IM Bots
9 channels), and extend docs/QA.md with entries for the Yunzhijia IM
integration, Volcengine rerank / Zhipu web search providers, and the Neo4j
conversation-memory removal.
2026-07-24 16:53:25 +08:00
wizardchen 84f65a809f fix(agent): ensure wiki summary slugs are preserved during citation compaction
This update addresses the issue where wiki summary-page slugs (summary/<knowledgeID>) were being mangled during the citation compaction process, leading to dead links. The changes include:

- Reordering the message encoding process to ensure resource references are aliased before source references, preventing the UUID from being replaced in the summary slug.
- Implementing a new function to selectively replace document IDs while preserving the integrity of summary slugs.
- Adding unit tests to verify that summary slugs remain intact and are not altered during compaction.

This fix enhances the reliability of cross-links in the wiki system and prevents potential dead links from being generated.
2026-07-24 15:57:08 +08:00
wizardchen 5d0326f987 fix(wiki): harden slug integrity across ingest and agent write paths
Weak LLMs routinely mangle high-entropy wiki slugs (especially UUID-based
summary/<id> slugs), producing dead cross-links and cross-item dedup
hallucinations. This tightens integrity end to end:

- Ingest dedup now groups each new item with only its own trigram
  candidates and validates merges against that per-item scope, rejecting
  cross-item mispairings; candidate top-K narrowed 20 -> 5.
- Editor path aliases out-link slugs behind low-entropy ref-N tokens and
  translates them back after generation, removing the chance to mangle.
- Agent write tool normalizes/validates slugs, blocks manual creation of
  system-owned summary pages, and auto-repairs dead [[slug]] links
  (rewrite-only, never strips) via bigram/display-text resolution.
- llmresource registry aliases summary/<uuid> slugs the same way as
  storage handles so they round-trip safely through chat.

Adds unit tests for slug validation, aliasing round-trip, dead-link
repair, and dedup rejection rules.
2026-07-24 15:57:08 +08:00
wizardchen d283fabc99 fix(doris): harden Stream Load HTTP with SSRF-safe client
Doris Stream Load previously used a plain http.Client, leaving FE→BE
redirects and stored FE URLs without outbound SSRF checks. Use the shared
SSRFSafeHTTPClient, validate URLs at send time, and only forward Basic
credentials to whitelisted BE hosts after FE 307 redirects.
2026-07-24 15:10:44 +08:00
wizardchen 50eb48c344 fix(org): disambiguate shared-space terms and tighten invite search
Search tenants for invite by workspace name only (a user may belong to
multiple workspaces, so username/email matching was ambiguous). Align
organization i18n to distinguish shared spaces from workspaces, fix the
duplicate zh-CN members key, and wrap invite-code generation response in
data so the frontend and Go SDK can read it.
2026-07-24 11:42:27 +08:00
wizardchen 075b16d6ca fix: prevent TDesign textarea autosize crash in org settings popup
Avoid resetting upgrade form after destroy-on-close unmounts the textarea,
blur focus before closing the modal, and skip async form updates when closed.
2026-07-24 11:06:23 +08:00
Jack Wang 43839f7830 fix(agent): honor suggested-questions limit parameter
Treat limit as the authoritative upper bound instead of clamping it down
to the agent's Starters.Count, so ?limit=N no longer always returns 6.

Fixes #2238
2026-07-24 10:46:53 +08:00
wizardchen e0b6a71503 fix(frontend): correct optimistic organization state after review and detail loads
Follow-up fixes for the organization state sync work:

- reviewOrganizationJoinRequest no longer increments member_count when
  approving a role-upgrade request (only genuine "join" approvals add a
  member); callers pass the request_type so upgrades are excluded.
- setCurrentOrganization now merges the detail payload onto the existing
  card instead of replacing it, so list-only aggregate badges
  (share_count / agent_share_count / pending_join_request_count) are not
  transiently blanked when a detail response omits them.
- OrganizationSettingsModal clears the previous organization context when
  reopening in edit mode for a different org, avoiding a stale frame
  before the detail request resolves.

Adds pure-helper unit tests for mergeById and reviewMemberCountDelta.
2026-07-24 10:45:12 +08:00
ttommybot 014cf4e545 fix: synchronize organization state after writes 2026-07-24 10:40:33 +08:00
wizardchen 8cb43473e6 fix(knowledge): restrict source file download to Editor and above
Downloading exposes the original source file, which is more sensitive than viewing parsed content or previews. Align backend route guards, handler checks, and frontend UI so tenant Viewers and org-shared read-only access cannot download.
2026-07-23 22:19:39 +08:00
wizardchen 697e0ae04e feat(frontend): polish organization space UI and share-to-space panels
Redesign share-to-space settings for knowledge bases and agents with member-style
search, add popup, and table list; simplify the org picker dropdown. Also refresh
organization settings join-request review with table layout and approval popup.
2026-07-23 21:03:20 +08:00
wizardchen 265556950b feat(frontend): polish shared space settings and join preview UI
Redesign organization settings with grouped navigation, table-based member
and shared resource views, and anchored popups for invites and permission
upgrades. Refresh the join-space confirmation flow and soften global input
focus styling to a thin brand border without the heavy outer glow.
2026-07-23 20:32:29 +08:00
wizardchen c28cd05c0c fix(models): align model debug upload limit with global MAX_FILE_SIZE
Use the deploy-time file size configuration for model debugger uploads
instead of a hardcoded 20 MB cap, and validate file size on the frontend
before sending the request.
2026-07-23 19:43:06 +08:00
wizardchen b2ae22c4eb feat(chat): show wiki tool results in the references drawer
Parse wiki search/read/edit/issue tool outputs into structured reference
cards so agent citations and the right-side drawer work consistently with
other retrieval tools.
2026-07-23 19:41:34 +08:00
wizardchen 6fb858105a feat(llm): add prompt-cache observability and wiki cache-friendly prompts
Normalize provider-specific cache counters into TokenUsage, propagate call
purpose and prefix fingerprints through context for logging and Langfuse,
and restructure wiki page-modify prompts with warmup/singleflight to improve
prefix cache hit rates during reduce batches.
2026-07-23 19:17:30 +08:00
wizardchen 6c794f64cf feat(runtime): add bulk purge for archived queue tasks and chat_attachment i18n
Operators can clear all finally-failed tasks in one queue from the runtime
drawer, with audit logging and scoped API access. Also localize the
chat_attachment queue label in the runtime queue details table.
2026-07-23 16:52:35 +08:00
ttommybot de7507cc96 docs: clarify workspace owner cardinality 2026-07-23 16:13:35 +08:00
ttommybot a287808597 fix: prevent API keys from assigning owner role 2026-07-23 16:04:42 +08:00
wizardchen 8ae82573ab fix(mcp): coordinate OAuth token refresh and authorization polling
Prevent concurrent refresh-token rotation across instances, distinguish
expired-but-refreshable tokens from active authorization, and bind OAuth
popup polling to a per-attempt ID so stale tokens cannot satisfy new consent.
2026-07-23 15:35:24 +08:00
lhy c74b0caa35 fix(task-inspector): handle lazy queue not found errors 2026-07-23 14:24:21 +08:00
wizardchen 0869f3e829 fix(im): harden Yunzhijia image download and prune dead validation
- Follow a single download redirect while re-validating the target stays
  within the allowed host suffix; never forward the bearer token across it.
  The shared http client disables auto-redirects for SSRF safety, so a 302
  from downloadfileOpen previously failed the download outright.
- Cap in-memory download size at 32 MiB via a limited read-closer that
  errors instead of silently truncating, avoiding OOM on large responses.
- Remove dead frontend host-suffix validation branch (normalize always
  fills the default) and drop the now-unused i18n keys
  yunzhijiaAllowedHostSuffixRequired / yunzhijiaRequiredCredentials.
- Add tests for redirect follow/reject and the size limit.
2026-07-23 12:41:19 +08:00
jacentsao 85c9b61ad0 feat(im): support Yunzhijia image messages 2026-07-23 12:25:51 +08:00
wizardchen 986a6f3699 fix(tasks): detach KB deletion queue cleanup from request ctx
Run the synchronous best-effort queue scrub in DeleteKnowledgeBase with
context.WithoutCancel and kbTaskCleanupTimeout so client disconnects
cannot truncate cancellation mid-scan, matching ProcessKBDelete cleanup
semantics.
2026-07-23 12:20:03 +08:00
zhangzherui 37de0afad0 fix(tasks): dequeue work for deleted knowledge bases 2026-07-23 12:17:14 +08:00
zhangzherui 7fde37eeeb fix(search): validate hybrid search query text 2026-07-23 12:05:57 +08:00
ttommybot 97bcca21c6 fix: refresh pending join request counts after review 2026-07-23 12:03:07 +08:00
wizardchen 146e341748 refactor(http): share SSRF-safe transport across model clients
Extract NewSSRFSafeTransport and NewSSRFSafeHTTPClientWithTransport so
embedding and rerank can reuse one connection pool without allocating a
throwaway transport per client. SSRF dial and redirect policies are
unchanged; each client still keeps its own timeout.
2026-07-23 12:00:05 +08:00
zhangzherui ccf02e1a2a fix(embedding): reuse SSRF-safe HTTP transport 2026-07-23 11:51:54 +08:00
wizardchen 8ca9c117bb feat(knowledge): enhance FAQ entry filtering and tagging
- Updated the listFAQEntries function to support multiple tag IDs for filtering.
- Modified the frontend components to accommodate the new tag_ids parameter.
- Enhanced the KbTagManageDrawer and FAQEntryManager components to reflect changes in tag handling.
- Improved API documentation to clarify the new tag filtering capabilities.

This commit enhances the flexibility of FAQ entry retrieval, allowing users to filter by multiple tags for more precise results.
2026-07-23 10:50:32 +08:00
wizardchen b6a3b347da feat(knowledge): enhance FAQ export functionality
- Updated the exportFAQEntries function to support exporting FAQ entries in both CSV and JSON formats.
- Modified the frontend to include options for selecting the export format.
- Enhanced localization files to reflect the new export options in English, Russian, and Chinese.
- Implemented new tests to validate the export functionality for both formats.

This commit improves the flexibility of FAQ exports, allowing users to choose their preferred format for better integration with other tools.
2026-07-23 10:50:32 +08:00
wizardchen 135033e6df feat(knowledge): enhance FAQ import result tracking and UI
- Added new fields for tracking added, merged, and partially failed entries during FAQ imports.
- Updated the import result statistics to include detailed counts for added and merged entries.
- Enhanced the UI to display progress hints and improved import result summaries.
- Implemented a new method for saving chunks in a single transaction to improve performance.

This commit improves the visibility and accuracy of FAQ import results, providing better user feedback and tracking capabilities.
2026-07-23 10:50:32 +08:00
wizardchen 5af8eae81d feat(knowledge): enhance activity logging for FAQ imports
- Added new actions for FAQ import lifecycle: `faq.import_started`, `faq.import_completed`, and `faq.import_failed`.
- Updated activity details to include success, failure, and skipped counts for FAQ imports.
- Enhanced UI to display additional activity information, including filtering options and clearer summaries.
- Implemented tests to validate the new FAQ import outcomes and activity details.

This commit improves the tracking and visibility of FAQ import activities within the knowledge base, ensuring better audit trails and user feedback.
2026-07-23 10:50:32 +08:00
wizardchen a3a0308b62 feat(knowledge): add scoped activity audit trail 2026-07-23 10:50:32 +08:00
wolfkill f195e0494c fix(wiki): support orphan count on sqlite 2026-07-23 10:44:08 +08:00
Changjin Li 8248752e62 修复共享知识库文档预览路径 2026-07-23 10:43:31 +08:00
huangbinghe 76f9640a4f fix(dev): nc 兼容BSD netcat (#2205)
* fix(dev): nc 兼容BSD netcat
2026-07-23 10:42:08 +08:00
wizardchen 4c3ae69b49 feat(wiki): prune empty folders after document retract
Automatically remove wiki folders that become empty when knowledge is
retracted, using the durable finalize lane so pruning waits until ingest
drains. Repository DeleteFolder now atomically checks emptiness to avoid
races with concurrent page or child-folder writes.
2026-07-22 19:27:22 +08:00
unknown ab0b1d65b5 fix: correct graph and multimodal processing traces 2026-07-22 17:38:28 +08:00
wizardchen b9b81a6c3c fix(knowledge): stop async delete from leaving visible/zombie rows (#2192)
Two backend fixes for the v0.7.0 regression where a deleted document keeps
showing in the list ('delete success' toast) and a follow-up reparse then
reports the file is missing:

1. List filtering: applyKnowledgeListFilter now hides rows in the transient
   'deleting' state from the default document list. The async delete pipeline
   marks a row 'deleting' before tearing down its resources, so without this
   the entry lingers as a normal doc until it is physically gone. Rows whose
   delete task exhausts retries are flipped to 'failed' by the dead-letter
   callback and stay visible so the failure remains actionable; an explicit
   parse_status=deleting filter can still surface in-flight rows.

2. Delete ordering: DeleteKnowledge / DeleteKnowledgeList now delete the DB
   row FIRST and defer physical file (+ extracted image) cleanup until after
   the row is gone. Previously file removal ran concurrently with the
   index/chunk/graph cleanup; when one of those failed the row was kept but
   the file could already be deleted, producing a 'file missing but row
   present' zombie that could neither be reparsed nor cleanly re-deleted.
   Orphaning a file after the row is gone is the tolerable failure mode.

Adds a repository regression test covering the default/explicit deleting
visibility rules.
2026-07-22 17:30:14 +08:00
wizardchen 0f2c6cee11 fix: normalize API key expiry timestamps to UTC (#2137)
Store authorization timestamps as timestamptz and normalize Unix expiry
inputs to UTC so tenant/platform API keys expire at the intended instant
even when the app process timezone differs from the PostgreSQL session.
2026-07-22 17:09:55 +08:00
wizardchen 59fed12643 fix(chat): show model reasoning inline in agent timeline
Keep thinking events in the compact tool timeline and render expanded
reasoning inline instead of hiding it or using a separate title block.
2026-07-22 16:43:58 +08:00
wizardchen 554d273cf5 fix(knowledge): copy embedded chunk images into exports namespace
Cloned images were unreachable via GET /knowledge-bases/:id/files:
copyOwnedObject used CopyFile, which writes to the knowledge-scoped upload
layout ({tenant}/{knowledgeID}/...), but the KB proxy only serves objects
under {tenant}/exports/ (ValidateKBScopedStoragePath). Read the source
bytes and re-save via SaveBytes instead, mirroring how images are
persisted during ingestion, so copies land in the servable exports
namespace and remain independent of the source object.
2026-07-22 15:27:11 +08:00
yuefanxiao 0f422f172d fix(cli): repair acceptance e2e test for current CLI wire contract 2026-07-22 14:34:50 +08:00
wangke.2002 2e540654f1 feat: 修复IM问答无法读取session的问题 2026-07-22 14:25:55 +08:00
wizardchen 1d37b90a17 fix(knowledge): rewrite parent text chunk image URLs via global pass
For document knowledge, extracted images live in independent image_ocr/
image_caption child chunks that carry image_info, while the parent text
chunk embeds the ![](url) reference with an empty image_info. Rewriting
content per-chunk therefore missed the parent text chunk, leaving it
pointing at soon-to-be-deleted source storage.

Move content URL rewriting to a final pass over all cloned chunks, run
once urlCache holds the complete old->new mapping. FAQ chunks are
self-contained, so they are rewritten inline from the same cache.
2026-07-22 14:22:58 +08:00
wizardchen ac321a3e81 fix(knowledge): rewrite chunk content image URLs on clone
When cloning knowledge chunks, image_info was deep-copied to new storage
objects but Content still embedded the source markdown image URLs. After
the source knowledge is deleted, those in-content references break while
image_info points at the new copies. Rewrite Content alongside image_info
so both stay consistent.
2026-07-22 12:06:31 +08:00
jacentsao 7e7083ce17 feat(im): default markdown format for yunzhijia replies
SendReply now sets param.formatType=markdown by default since WeKnora
replies are authored in Markdown. Callers can override via
reply.Extra["yunzhijia_format_type"] (empty string disables the param).
2026-07-22 11:01:49 +08:00
wizardchen be48324c84 fix(frontend): keep custom theme tokens in production builds
Raise theme.css selector specificity so TDesign bundled styles cannot
override WeKnora tokens after minification, and add vite preview proxy
so production-like local testing can reach the API backend.
2026-07-21 20:29:02 +08:00
wizardchen 0d545c8c6a feat(knowledge): implement AminusB function for multiset comparison of knowledge bases
- Added AminusB method to the knowledgeRepository, which returns IDs of knowledge in A that have no counterpart in B, comparing by file_hash as a multiset.
- This implementation addresses issues with handling duplicate entries and NULL file_hash values, ensuring accurate synchronization between knowledge bases.
- Updated the KnowledgeRepository interface to reflect the new functionality and improved documentation for clarity.
2026-07-21 17:44:51 +08:00
wizardchen 516ef01cf2 refactor(api-keys): update tenant_api_keys table structure and remove legacy migration files
- Modified tenant_api_keys table to allow nullable tenant_id and added scope_type with constraints.
- Removed legacy platform API keys migration files to streamline database management.
- Added new index for scope_type to improve query performance.
2026-07-21 17:21:35 +08:00
wizardchen 171fbd0dca feat(i18n): add drawer localization for audit log details
Enhance internationalization support by adding new localization entries for the audit log detail drawer in English, Korean, Russian, and Chinese. This includes sections for event summary, related IDs, request information, and method.
2026-07-21 17:21:35 +08:00
wizardchen 23db592c4a feat(api-keys): add platform-scoped API keys for control-plane automation
Introduce platform API keys with capability-based access to tenant management,
system settings, runtime queues, and audit logs, plus admin UI for key lifecycle
and system audit log viewing.
2026-07-21 17:21:35 +08:00
nullkey c695125dce fix(feishu): resilient large-wiki sync — retry, streaming resume, failure visibility
Large Feishu wikis stopped syncing after the first batch (Tencent/WeKnora#2136:
5000+ docs, only ~150 ingested; #1262: a child-list failure aborted the run).
Three compounding causes, fixed in layers:

1. Rate-limit / transient failures had no retry. Feishu's wiki/drive/export
   APIs are aggressively rate limited; a thousand-doc sync issues tens of
   thousands of calls, and a single 429/5xx burst failed whole swathes of docs.
   Add exponential backoff honouring Retry-After to doRequest (JSON) and
   downloadRawBytes (files): 429 up to 3x, 5xx once, transport errors back off.

2. The batch path fetched the entire tree into memory before ingesting, so a
   sync that hit the 2h task timeout lost all progress and restarted from
   scratch, and a transient per-document export failure advanced the cursor and
   skipped that doc permanently. Add an optional StreamingConnector interface,
   implemented for Feishu: FetchStream interleaves fetch -> ingest -> checkpoint,
   bounding memory to one item and persisting a per-node edit-time cursor at
   page boundaries. The service dispatches to it via type assertion; connectors
   without it fall back to FetchAll / FetchIncremental unchanged (non-breaking).
   A resumed/incremental run skips nodes already recorded at their current edit
   time (converges), a failed fetch does not advance the cursor (retried next
   run instead of dropped), and partial listing failures emit error items and
   carry prior edit times forward instead of aborting the sync.

3. Failures and skips were invisible. Unsupported node types (mindnote/slides/…)
   were skipped with no item, error or log ("13 docs synced only 3"). FetchAll
   now tallies discovered/fetched/failed/skipped per resource with a per-type
   skip breakdown and a progress line every 100 nodes. The backend already
   persisted per-item errors in SyncLog.result.errors but the frontend type
   omitted the field; declare `result` on SyncLog and render up to 50 failed
   documents in the sync-log drawer (#1262). i18n for zh-CN/en-US/ko-KR/ru-RU.
   result.errors is a jsonb column shipped in every list response, so it is
   capped at 100 samples server-side (recordSyncError); the exact failure total
   comes from the bounded items_failed counter, which the drawer uses for its
   count and "N more" line so a sync that fails thousands of docs stays bounded.
   Each sample is a structured, localisable SyncItemError instead of a raw
   "title: ...api error: status=500 body={json}" dump that repeated the title
   and leaked status/body/log_id. The connector (feishuFailure) classifies the
   error into a stable i18n code (+ the feishu code as a param); the service
   builds {title, code, params, message}; the drawer localises via vue-i18n to
   the viewer's language (zh/en/ko/ru), falling back to message. A custom
   UnmarshalJSON keeps old string-form logs readable. The banner is localised
   from items_failed too. Raw errors stay in the server logs. Follows the
   two-tier norm of Airbyte/Fivetran/Onyx: human, actionable, localised
   summaries in the UI; raw detail in logs. Transient errors say "will retry"
   (the cursor is retained); auth/permission errors point at the fix instead.

Tests: client_retry_test (backoff), tally_test (accounting), connector_stream /
datasource_stream (streaming dispatch + checkpoint), connector_convergence
(timeout + transient-failure resume converges to full coverage; proven to catch
#2136 via bug injection), datasource_result_cap (error-sample cap + structured
localisable SyncItemError, no raw body), connector_error_reason (error→i18n-code
classification), sync_item_error (legacy-string + structured back-compat) — all
in the normal suite. connector_realapi / connector_seed are an opt-in real-Feishu
harness gated by the feishu_integration build tag AND env vars, never run in CI.
2026-07-21 16:14:22 +08:00
wizardchen 74cdd7cdd0 fix(compose): let PDF render parallelism follow CPU-aware code default
Stop hardcoding DOCREADER_PDF_RENDER_PARALLELISM=4 in compose so low-core
containers use min(4,cpu). Clarify WEKNORA_LANGUAGE precedence and align
docreader JPEG quality docs with the 85 default.
2026-07-21 16:02:31 +08:00
Greenplumwine fa7ae075ee feat(compose): align env vars with code + fix helm GraphRAG bug (#2164)
* feat(compose): align env vars in docker-compose and .env.example with code

docker-compose.yml / docker-compose.dev.yml
- app.environment: remove deprecated vars Go app no longer reads
  (CRYPTO_MASTER_KEY, CRYPTO_SALT, TENANT_AES_KEY, ENABLE_GRAPH_RAG);
  add missing vars the code actually consumes (OSS/S3/TOS/COS completion,
  OpenSearch, Tencent VectorDB, Milvus credentials, Redis TLS/namespace,
  OIDC, audit/invitation/quota, LLM tuning, doc timeouts, etc.)
- docreader.environment: complete PDF tuning knobs, SSRF/LOG_LEVEL/gRPC
  params, GRPC_MTLS_REQUIRE_CLIENT_CERT; fix DOCREADER_PDF_JPEG_QUALITY
  default 90 -> 85 to match code (config.py)
- mcp.environment: add MCP_SERVER_AUTH_TOKEN (required by HTTP transport),
  WEKNORA_CHAT_TIMEOUT, WEKNORA_VERIFY_SSL, MCP_ALLOWED_UPLOAD_DIRS
- dev compose docreader.environment kept symmetric with prod

.env.example
- reorganize into A-J sections (deploy / data / retrieval / models /
  parsing / auth / agent / integrations / observability / security)
- remove the four deprecated vars, document why
- add missing vars, fix NEO4J_URI to bolt:// (matches compose + single-node),
  fix DORIS_COMPAT_MODE typo, complete docreader PDF tuning defaults

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(helm): inject NEO4J_ENABLE and drop deprecated TENANT_AES_KEY

helm graph bug fix
- NEO4J_ENABLE is the sole graph switch the Go app reads (since v0.1.6,
  ENABLE_GRAPH_RAG is no longer read). helm never injected NEO4J_ENABLE,
  so GraphRAG was silently broken: setting neo4j.enabled=true gave the
  app NEO4J_URI/USERNAME/PASSWORD but not the switch, and the UI rejected
  Node Extractor config with "请正确配置环境变量NEO4J_ENABLE".
- app.yaml: inject NEO4J_ENABLE=true inside the neo4j.enabled block;
  remove the dead ENABLE_GRAPH_RAG injection
- NOTES.txt: update GraphRAG instructions (just enable neo4j, no need
  to set the deprecated ENABLE_GRAPH_RAG)
- values.yaml: drop ENABLE_GRAPH_RAG, fix neo4j section comment

TENANT_AES_KEY cleanup (deprecated since v0.4.0, encryption now uses
SYSTEM_AES_KEY exclusively; Go app no longer reads it)
- secrets.yaml: stop generating/looking-up/writing TENANT_AES_KEY,
  fix stale comment about tenants.api_key rotation
- app.yaml: remove TENANT_AES_KEY secretKeyRef
- values.yaml: drop tenantAesKey, fix existingSecret key list + comments
- cloud-image/firstboot.sh: stop generating/writing/printing TENANT_AES
- cloud-image/README.md: drop TENANT_AES_KEY from credential list

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>
2026-07-21 15:55:52 +08:00
jacentsao 150c07368b feat(im): add Yunzhijia integration 2026-07-21 12:24:33 +08:00
Martín Alcalá Rubí 83da0903b6 fix(rerank): stop sending vLLM truncate_prompt_tokens by default
The generic OpenAI-compatible reranker hardcoded `truncate_prompt_tokens:
511` on every /rerank request. Providers that honor this vLLM-specific
field (e.g. SiliconFlow serving Qwen3-Reranker) keep only the last 511
tokens of the templated rerank prompt, cutting the instruction and query
off any document longer than ~511 tokens. Every relevance score then
collapses to near zero (~0.0067 instead of ~0.998), falls below the score
threshold, and knowledge-base search returns empty results. A direct curl
without the field returns the correct scores.

WeKnora already removed this exact hardcoded parameter from the embedding
path in #960; the rerank path was never fixed.

- Add `omitempty` to `truncate_prompt_tokens` and `additional_data` so
  empty optional fields are not sent.
- Make truncation opt-in via `extra_config.truncate_prompt_tokens`
  (validated > 0 at construction), preserving an escape hatch for
  self-hosted vLLM deployments with small-context rerankers.
- Add regression tests reproducing the collapsed-score symptom and the
  opt-in path.

Fixes #2143
2026-07-21 12:12:56 +08:00
myheart99@126.com e289595054 fix(types): use correct GORM tag separator in Message.KnowledgeReferences
Multiple GORM tag options must be separated by ';', not ','. The comma was
parsed as part of the type value, producing malformed DDL that causes
AutoMigrate(&Message{}) to fail on SQLite with a syntax error.
2026-07-21 12:06:48 +08:00
hbh112233abc fd660ca796 fix(embed): 兼容不支持 crypto.randomUUID 的浏览器以及http请求模式 2026-07-21 12:01:47 +08:00
wizardchen 25ef7b6c68 feat(session): gate IM/embed/API channel sessions behind admin
Restrict channel-managed sessions (API keys, IM, embed) to tenant admin
in the Web console for list/read paths, hide channel sidebar buckets from
non-admins, and add CountSessionsBySource for aggregate stats without
exposing session rows to viewers.
2026-07-20 20:31:54 +08:00
wizardchen b1b42abe23 fix(rerank): batch Volcengine rerank requests over API document limit
Split oversized candidate sets into concurrent batches instead of failing when retrieval exceeds the VikingDB rerank per-request cap, and align ko/ru locale hints with zh-CN.
2026-07-20 20:07:21 +08:00
KKtwo 3011f132e9 feat: support Volcengine rerank 2026-07-20 19:58:48 +08:00
jacentsao c387f09add fix(frontend): load complete TDesign styles 2026-07-20 19:52:30 +08:00
wizardchen d1cab68e3d fix(api-keys): allow scoped file serve and ingest batch routes
Let tenant-wide retrieve keys serve tenant-bounded /files paths while
denying KB-restricted keys, declare knowledge batch write routes for
ingest-capable keys, and short-circuit ownership checks for API-key
principals already authorized by the gate and KB allow-list.
2026-07-20 19:52:13 +08:00
wizardchen 23e606f570 fix(frontend): pin nginx base image by digest for old-host compatibility
The floating `nginx:stable-alpine` tag drifts with every stable release.
A newer Alpine base (3.24+) fails to start on old hosts such as CentOS 7
(kernel 3.10 + old libseccomp), which broke v0.7.0. Pin to nginx 1.30.3 /
Alpine 3.23.5 by digest, the same base as the working v0.6.3 image.
2026-07-20 19:41:17 +08:00
wizardchen 29bec6c613 feat(session): implement strict owner scope for API-key sessions
Add GetOwnedSession method to enforce strict ownership checks for session mutations, ensuring tenant admins can read but not modify API-key sessions. Update relevant handlers to utilize this method for operations that alter session data, maintaining security and integrity of API-key sessions.
2026-07-20 19:31:02 +08:00
wizardchen 76a4ffe525 feat(session): add admin API session bucket and stabilize sidebar filter
Let tenant admins list and open API-key sessions from the Web console while
keeping per-key isolation for everyone else. Pin the session source filter so
it no longer jumps when switching buckets, and resolve session origin on read
so deep links stay in sync with the active folder after refresh.
2026-07-20 19:31:02 +08:00
wizardchen eab91d2f7f feat(web-search): add Zhipu AI web search provider support
Integrate Zhipu's standalone Web Search API with configurable search
engine and content size options, plus settings UI, docs, and tests.
2026-07-20 12:15:35 +08:00
wizardchen 380e371c2e refactor: remove Neo4j-based conversation memory feature
Drop the memory pipeline, API fields, settings UI, and embed toggles so chat no longer depends on Neo4j graph storage for episodic recall.
2026-07-18 23:41:48 +08:00
zhangshuai 7807dee42a fix: stabilize top-k retrieval ordering 2026-07-17 18:42:45 +08:00
Donson 5293b8e7db fix(wiki): detach ingest cleanup from task cancellation
Use bounded detached contexts for wiki ingest tail cleanup so pending row
settlement, span closure, finalize enqueueing, and follow-up scheduling can
finish even after the asynq task context is cancelled.

Return settlement errors from pending row trimming and failed-op requeueing,
and only mark claims settled after rows are deleted, released, or
dead-lettered successfully. Requeue documents whose reduce updates were not
applied after context cancellation to avoid silently dropping wiki work.

Add unit coverage for detached cleanup contexts and settlement error handling.
2026-07-17 18:05:27 +08:00
wizardchen e294dff7f4 feat(chat): enhance ChatHeader with docked state and references panel support
Add a new 'is-docked' class to the ChatHeader component for improved styling when the references panel is visible. Introduce a 'hasReferencesPanel' prop to manage this state, enhancing the layout and responsiveness of the chat header on wider screens.
2026-07-17 17:55:04 +08:00
wizardchen 457285cffe style(chat): widen conversation content area from 800px to 960px
Improve readability on wide screens by expanding the main chat column and aligning related sub-component widths.
2026-07-17 17:55:04 +08:00
wizardchen 1649603af4 fix(tracing): merge Langfuse finish metadata and export auto root spans
Finish-time metadata was discarded and implicit root traces opened by
StartSpan/StartGeneration were never ended, leaving orphaned parents in
Langfuse. Also stop mutating the global OTel text-map propagator.
2026-07-17 16:58:40 +08:00
shenk-b 5ee96019e0 feat(tracing): migrate langfuse client to OTLP/OTel wire protocol
Migrate WeKnora's Langfuse tracing from the legacy /api/public/ingestion
batch API to the OpenTelemetry Go SDK emitting OTLP/HTTP to
/api/public/otel/v1/traces — the Langfuse v3+ standard ingestion protocol.

Why: Langfuse v3 deprecated the legacy ingestion API in favor of OTLP, and
OTel-only backends (e.g. the LiteFuse Doris fork) dropped it entirely, so the
legacy client was incompatible. Migrating to the OTel SDK also adds W3C
traceparent cross-service propagation: an upstream caller's trace id is
inherited so its run and the WeKnora call land under one trace in the UI.

What:
- Manager owns an OTel TracerProvider backed by an otlptracehttp exporter
  (Basic auth + the x-langfuse-ingestion-version gate header). Spans are
  buffered by BatchSpanProcessor and exported complete on End, so a long
  trace no longer fragments across flush batches.
- *Trace/*Span/*Generation wrap OTel spans; the public API (StartTrace/
  Span/Generation, handles, InjectTracing, asynq/gin middleware, Config,
  TokenUsage) is unchanged, so callers (agent/chat/handler/scheduler/asynqdl)
  need no edits.
- W3C traceparent: GinMiddleware extracts traceparent from incoming requests;
  AsynqMiddleware + InjectTracing propagate it across the asynq payload.
  types.TracingContext gains a LangfuseTraceparent field.
- logger.CloneContext preserves the active OTel span across context rebuilds
  so child spans (agent engine, summary generation) stitch to the HTTP trace
  instead of orphaning into separate traces.
- StartSpan/StartGeneration re-establish the parent from the *Trace handle
  when the ctx lost the active OTel span, covering background/derived contexts.

Compatibility: works with Langfuse v3+ (cloud / self-hosted / the bundled
docker-compose profile) and LiteFuse. Drops Langfuse v2 (legacy-only) support.
Uses the OTel Go SDK already (indirectly) in go.mod, promoting
otlptracehttp to direct; no third-party langfuse-go library.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-17 16:30:45 +08:00
wizardchen 1a2021b3f8 feat(chat): add session header actions and Markdown export
Give chat a left-aligned header for rename/pin/copy/clear/delete, share session mutations across sidebar and chat view, and support copying the full conversation as Markdown.
2026-07-17 16:16:35 +08:00
wizardchen e8dcbb07d0 docs: release v0.7.0 notes and update version artifacts
Publish scoped API keys, worker-pool governance, multi-instance storage,
and the rest of the v0.7.0 feature set across CHANGELOG, READMEs, QA,
Swagger, and version pins.
2026-07-17 14:42:56 +08:00
wizardchen df21abe13b fix(parser): remove workspace chat parser policy UI
Chat attachment parser rules belong on agents; drop the duplicate workspace settings section while preserving legacy tenant rules when engine config is updated without that field.
2026-07-17 13:42:02 +08:00
wizardchen bea58bbef7 fix(chat): emit retrieval references when citation output is disabled
Decouple the references SSE event from the per-agent citation output toggle
so the retrieval-results drawer still works, and align follow-up suggestion
card layout with the chat column.
2026-07-17 11:38:35 +08:00
qilifan 9afb8b7b68 feat(im,datasource): support Lark, Feishu's international edition
Lark and Feishu are the same product deployed on two isolated clouds
(open.larksuite.com and open.feishu.cn). WeKnora touches both from two
places — the IM bot and the Wiki data-source connector — and this brings
Lark to parity across both. Neither API surface differs, so rather than
duplicate either implementation, each is parametrized by a Region and
registered twice.

IM (internal/im/feishu):
  Every API call routes through a.api(), which prefixes the region's
  host, and the WebSocket client passes larkws.WithDomain — the SDK
  defaults to open.feishu.cn, so Lark long connections would otherwise
  fail to authenticate.

Data source (internal/datasource/connector/feishu):
  Lark was half-supported: the client honoured a base_url override and a
  LarkBaseURL constant existed, but the connector registered only as
  "feishu" and the UI never exposed base_url, so Lark wikis could not be
  configured at all. Lark is now its own connector type. base_url is kept
  as an explicit override so data sources that pointed a "feishu"
  connector at open.larksuite.com keep working.

Bugs found and fixed along the way:

- Wiki resource links were hardcoded to https://feishu.cn/wiki/{token} in
  four places, so a Lark wiki linked into the wrong cloud entirely.
- Bot identity is now platform-prefixed (feishu:cli_x vs lark:cli_x).
  BotIdentity carries a unique index, so without this a Lark channel
  would be rejected as a duplicate of an unrelated Feishu bot sharing an
  app_id.
- The card image cache is now keyed by app_id. image_keys are issued per
  app on one cloud; a Feishu key handed to a Lark app fails the card
  update with code=200570.
- The datasource doc claimed Lark "adapts automatically" — it could not,
  since the UI had no way to reach base_url.

Permissions are where the clouds genuinely diverge. Identical APIs do not
mean identical permission catalogues: aily:file:read, aily:file:write and
corehr:file:download exist on Feishu but not on Lark, so pasting Feishu's
scope JSON into Lark fails to import. That JSON is also over-broad (it
covers products WeKnora never calls) and simultaneously incomplete (it
omits the drive:*/docx:* scopes the connector needs). Lark therefore gets
its own list, derived from the 17 endpoints the code actually calls and
checked identifier-by-identifier against Lark's own API reference, plus a
full Feishu→Lark mapping table marking each scope verified, unverified,
or absent. Both features use tenant_access_token only — no user_access_
token exists anywhere in the repo — so the user dimension stays empty.

Known limitation: Region.ThinkingText makes Lark's initial card
placeholder English, but once streaming starts the think-block headers
come from the shared MarkdownThinkStyle and are Chinese on every platform
(Lark, Slack, Telegram, Mattermost alike). Fixing that means threading a
locale through FormatIMDisplayContent, which has no platform context — a
cross-platform change, not a Lark one. Documented as such.

The channel-creation 400 message is now derived from validIMPlatforms so
the list cannot drift as platforms are added.

Tests: region invariants and per-region URL construction on both sides,
the Feishu/Lark bot-identity split, platform-to-channel mapping, base_url
override precedence, an end-to-end SendReply against a fake Open Platform
(token fetch, reply, thread-unsupported fallback, hard-error surfacing),
and a ListResources drive asserting wiki links never leak the other
cloud's host.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-17 11:05:54 +08:00
wizardchen 3edd9c2c84 fix(chat): polish references drawer layout and web reference titles
Improve reference list readability by resolving URL-like titles to domains,
stripping markdown noise from snippets, and aligning suggestion chip hover
styles across chat and embed surfaces.
2026-07-17 11:04:16 +08:00
wizardchen eedd7d4641 feat(agent): enhance suggested questions API with tag scopes
Update the SuggestedQuestionsRequest to include TagScopes for better filtering of knowledge items based on their parent knowledge bases. Modify related API documentation and frontend interfaces to accommodate the new structure. Ensure backend services handle the new tag scope logic correctly, including tests for the updated functionality.
2026-07-17 10:19:43 +08:00
wizardchen c21c34b3c0 feat(agent): implement agent selection behavior for web search
Add a test to verify that selecting an agent defaults web search to off until the user enables it. Update the agent selection logic to ensure that the web search capability is controlled by user action rather than agent configuration. Modify comments in the Input-field component to reflect this change in behavior.
2026-07-17 10:19:43 +08:00
wizardchen 53a66a6456 feat(chat): enhance references drawer behavior and citation handling
Implement improvements to the chat references drawer, including a new event for handling panel entry to ensure smooth scrolling to highlighted citations. Update the logic for retrieving references from agent events, allowing for better integration of citation data. Additionally, enhance tests to cover new functionality and ensure correct behavior of the references drawer during interactions.
2026-07-17 10:19:43 +08:00
wizardchen e938a76be4 feat(chat): enhance follow-up suggestions rendering logic
Implement a mechanism to ensure follow-up suggestions are only displayed after the answer is fully rendered. Introduce an event for rendering completion and update related components to handle this new logic. Update tests to verify the correct behavior of follow-up suggestions based on rendering state.
2026-07-17 10:19:43 +08:00
wizardchen b862c2e45d feat(agent): add per-agent citation output toggle
Move citation protocol injection to the system layer so custom prompts no
longer own citation syntax. Agents can disable inline citations while source
aliases still encode and decode tool arguments correctly.
2026-07-17 10:19:43 +08:00
wizardchen 014164ae44 feat(llm): introduce request-local source reference aliases
Replace raw chunk/document/KB IDs in LLM context with short cN/dN/bN/wN
aliases, decode tool arguments on the way in, and expand compact <ref/>
citations to the public <kb>/<web> format before user-facing output.
2026-07-17 10:19:43 +08:00
wizardchen 79e8f3d894 fix(agent): use attach icon for attachment upload nav item
Align the capability extension sidebar icon with chat attachment upload
after the section was renamed from image-only to attachment upload.
2026-07-16 19:26:08 +08:00
wizardchen 48969b49f7 fix(agent): show disabled and unavailable MCP services in editor selector
Preserve selected MCP IDs in the agent editor when services are disabled or
missing, display them as disabled options with clear labels, and tighten
setting-row layout so long multi-select tags do not overflow.
2026-07-16 19:26:08 +08:00
wizardchen 88a0201afe style(chat): simplify suggestion copy and align hover with chat UI
Shorten follow-up and refresh labels across locales, and replace flashy
suggestion card hovers with the same border, neutral background, and
shadow treatment used elsewhere in the chat page.
2026-07-16 19:15:18 +08:00
wizardchen a1d8f55cbd fix(chat): improve streaming wait indicators across chat and embed
Keep the agent timeline placeholder visible between tool rounds when
nothing is pending, remove redundant thinking dot loaders, and replace
embed bouncing dots with a lightweight native spinner.
2026-07-16 19:15:18 +08:00
wizardchen a270d40cd5 fix(chat): replace detached typing dots with native loading placeholders
Remove redundant bounce-dot indicators from agent/RAG timelines and non-agent
answers; use existing pending step cards before activity and a compact spinner
for global wait states so streaming feedback stays aligned with the timeline.
2026-07-16 19:15:18 +08:00
wizardchen 7ddac0385f feat(attachments): enforce combined limit for images and attachments
Implement a maximum limit of 5 for the total number of images and attachments that can be uploaded in a chat session. Introduce a warning message for users when the limit is exceeded. Additionally, add functionality to clear pending uploads when switching sessions to prevent errors related to stale document IDs. Update localization files to include new warning messages in English, Korean, Russian, and Chinese.
2026-07-16 17:41:27 +08:00
wizardchen 85d10d99e3 feat(attachments): implement normalization and limits for temporary attachment IDs
Add functionality to normalize temporary attachment IDs, ensuring deduplication and enforcing a maximum limit of 5 attachments per message. Update related handlers and tests to support this new behavior, enhancing the robustness of attachment management in chat sessions.
2026-07-16 17:41:27 +08:00
wizardchen 9ae17be43c fix(chat): persist attachment content and fix fallback multi-turn context
Persist resolved temporary-attachment content onto the stored user message
so later turns can replay it in history. Close the retrieval progress spinner
on early pipeline exits, and reshape model-fallback messages with a proper
system role plus trailing user question.
2026-07-16 17:41:27 +08:00
wizardchen 92ceb3bd7d refactor(chat): enhance follow-up handling for previous image/document context
Update the classification logic for follow-up questions to include reasoning about previously described images or documents. Ensure that follow-up queries referencing earlier attachments are correctly identified and processed without triggering unnecessary knowledge base searches. This change improves the model's ability to maintain context and respond accurately to user inquiries related to past interactions.
2026-07-16 17:41:27 +08:00
wizardchen ceb4d1a310 feat(chat): add session-scoped temporary attachments with async parsing
Let users upload documents in chat without ingesting them into a knowledge base: files are parsed in the background, referenced by ID on send, and expire after a configurable TTL.
2026-07-16 17:41:27 +08:00
wizardchen 7b2c9e73bf fix(agent): ground follow-up suggestions and preserve KB scope on click
Tighten model prompt so retrieval questions stay topic-bound and self-contained,
reserve knowledge slots in hybrid mode, and carry suggestion KB IDs into the next send.
2026-07-15 19:16:53 +08:00
wizardchen fbc9db85d1 fix(chat): enforce retrieved image output in answers
When retrieved context or tool results contain Markdown images, dynamically
append output requirements to system prompts and final-answer instructions.
Also normalize fullwidth image parentheses in the frontend renderer so
localized model output still renders correctly.
2026-07-15 18:10:31 +08:00
wizardchen 951f95903b fix(chat): use Markdown for LLM image context and normalize legacy XML
Chat and agent tool context now emits answer-ready Markdown images instead
of internal <image> XML so copied content renders safely. The frontend also
normalizes legacy XML blocks in persisted conversations during streaming.
2026-07-15 18:10:31 +08:00
wizardchen a729bc1271 feat(agent): enrich follow-up suggestion generation context
Improve follow-up question quality by feeding the model structured context
(evidence, capabilities, complete turns) instead of raw RAG content, and
rank knowledge candidates by current-topic relevance.
2026-07-15 17:05:24 +08:00
wizardchen 0f4500b98f fix(tests): update resource alias syntax from 'res:' to 'res://' in tests and registry
Refactor tests and registry to use the new 'res://' syntax for resource aliases, ensuring consistency across the codebase. This change addresses alias handling in various test cases, including stream processing and registry encoding, to prevent data loss and improve resource reference management.
2026-07-15 17:02:43 +08:00
wizardchen 38c594aec3 feat(chat): implement orphan alias detection and logging in chat completion and streaming
Add functionality to detect unresolvable resource aliases emitted by the model during chat completion and streaming. Introduce logging for these orphan aliases to aid in debugging and improve the handling of resource references. Update the stream processing to ensure held aliases are flushed upon cancellation, preventing data loss. Include tests to verify the correct reporting of orphan aliases.
2026-07-15 17:02:43 +08:00
wizardchen 6d14cc3536 feat(resource): add stable resource registry with LLM-context alias compaction
Introduce resource://<handle> as the stable application identity for stored
objects, decoupling API responses, persisted rich text, and LLM prompts from
physical storage paths. Adds a resource catalog service (register/resolve/bind,
revocable expiring access grants), a request-local alias registry that compacts
resource references while in the LLM context and restores them (including across
streaming chunks), plus router, IM, chat-pipeline, and multimodal integration.

Includes schema migrations (resources, resource_bindings, resource_access_grants)
for sqlite, and hardens URL/output security handling.
2026-07-15 17:02:43 +08:00
wizardchen 9733bd28bf feat(storage): add storage backend management API and UI enhancements
Implement a comprehensive API for managing storage backends, including endpoints for listing, creating, updating, and deleting storage instances. Enhance the UI to support multi-instance configurations, allowing users to manage multiple storage types effectively. Update localization files for new storage backend features and improve error handling for connectivity tests. This update also includes detailed documentation for the storage backend API.
2026-07-15 14:54:39 +08:00
wizardchen a8dea5f9a3 feat(storage): improve storage connectivity error handling and multi-instance support
Enhance error messaging for storage connectivity issues by sanitizing raw errors to prevent leaking sensitive information. Introduce a new utility function for consistent error handling across storage backend operations. Additionally, implement logic to support multi-instance storage backends, allowing for more flexible workspace configurations and improved reporting of active storage providers.
2026-07-15 14:54:39 +08:00
wizardchen 6349fff002 feat(security): enhance image source protection for storage backends
Update the image source protection logic to include support for storage backend images. Introduce new regex patterns for identifying storage URLs and refactor the image tag building process to ensure proper handling of both provider and storage backend images. Add corresponding tests to validate the new functionality.
2026-07-15 14:54:39 +08:00
wizardchen f8b3e5f148 feat(storage): add multi-instance storage backends per workspace
Introduce tenant-scoped storage backend registry so workspaces can register
multiple storage instances and bind each knowledge base to a specific backend,
with migration from legacy tenant-level storage config and new settings UI.
2026-07-15 14:54:39 +08:00
wizardchen 139ec1e6b8 fix(storage): align default provider fallback with STORAGE_ALLOW_LIST
Extract storage allowlist into internal/storageallowlist so KB creation
uses FirstAllowed when tenant default_provider is empty or disallowed.
Share pickUsableStorageProvider via editorResources for consistent UI
selection, and add regression tests for OBS status and allow-list defaults.
2026-07-15 11:05:00 +08:00
wizardchen 97490ef7ed feat(api-keys): enhance manage_kbs capability for KB lifecycle management
Update the manage_kbs capability to cover the full lifecycle of knowledge bases, including create, copy, duplicate, update, and delete operations. Adjust related API routes and tests to ensure proper access control and policy requirements for knowledge base management.
2026-07-15 10:56:06 +08:00
ShadowSmallBaby b3bb60f03c fix: 修复/api/v1/tenants/kv/storage-engine-config接口不返回华为云obs配置导致创建知识库弹窗存储引擎华为云OBS未正确显示不可用标识
fix: 修复租户default_provider为空时降级至local,而local未被允许时导致创建知识库报错: Storage provider is not allowed by STORAGE_ALLOW_LIST
2026-07-15 10:54:14 +08:00
wizardchen e3b7ad98c2 feat(api-keys): let manage_kbs cover full KB lifecycle routes
Align create/copy/duplicate with update/delete under manage_kbs or
full-access, and update capability docs and UI hints accordingly.
2026-07-15 10:41:19 +08:00
Binks Riverton be88a56245 fix(knowledge): reload doc list after tag rename in manage drawer 2026-07-15 10:12:31 +08:00
wizardchen bdd459b071 fix(frontend): open chat reference links in new tabs
Prevent in-chat navigation from replacing the active conversation by
opening knowledge-base and citation links in a new tab with
noopener/noreferrer, and apply the same policy to sanitized markdown links.
2026-07-14 18:13:53 +08:00
wizardchen ace84bc757 fix(knowledge): recover tasks safely after server restart
Stop failing distributed-mode knowledge rows on startup; let housekeeping
decide using span activity and Asynq queue state. In Lite mode, resume
wiki work from durable task_pending_ops and surface SERVER_RESTART errors
in the processing timeline with i18n support.
2026-07-14 17:55:26 +08:00
wizardchen 28ebcf2525 feat(chat): polish follow-up suggestion loading and answer toolbar timing
Move follow-up loading into the answer toolbar so the card only appears when suggestions are ready, and delay toolbar actions until the typewriter finishes revealing the answer.
2026-07-14 17:49:03 +08:00
wizardchen 01f1011511 feat(system): add cursor pagination for runtime queue tasks
Replace offset-based page numbers with opaque Redis-backed cursors so
scheduled/retry tasks sort by next run time and live lists stay stable
when queue state changes between requests.
2026-07-14 16:53:07 +08:00
wizardchen f583d77fa0 feat(knowledge): enhance error handling in knowledge spans
Refactor the error handling logic in the GetKnowledgeSpans function to utilize a new helper function, knowledgeSpansLastError, which consolidates the logic for determining the last error from span failures and knowledge row failures. This improves clarity and maintainability of the code. Additionally, update test cases to cover new scenarios for last error handling.
2026-07-14 16:49:56 +08:00
wizardchen fc03e4862d fix(knowledge): align processing timeline status with knowledge row
Latest attempt tabs and header now trust parse_status over a closed root span, surface recovery failures via last_error, and keep attempt hover styles from washing out the active tab.
2026-07-14 16:49:56 +08:00
wizardchen 41975abcc5 refactor(terminology): rename user-facing tenant labels to workspace
Align product copy, API docs, Swagger descriptions, and i18n strings
with workspace terminology while keeping internal tenant identifiers
and headers unchanged for API compatibility.
2026-07-14 16:14:43 +08:00
wizardchen e1572b71b9 feat(models): let system admins edit builtin model config
Allow platform system administrators to update builtin model parameters
and credentials from the management UI while keeping secrets masked in API
responses. UI edits clear YAML ownership so startup reconciliation no
longer overwrites runtime overrides.
2026-07-14 15:56:02 +08:00
wizardchen f409bd756b feat(tests): enhance image multimodal service tests and runtime task handling
Added new tests for the ImageMultimodalService to verify the handling of orphan tasks and the finalization of pending counters. Improved runtime task inspection with better error handling and task cancellation logic, ensuring robust management of orphan tasks in the system.
2026-07-14 15:38:06 +08:00
wizardchen 4ae48d6acf feat(system): expand runtime queue task inspection and safe actions
Replace failed-only task views with state-aware runtime task listing,
operator-safe cancel/run-now/delete actions, orphan detection, and
multimodal queue cleanup for deleted knowledge rows.
2026-07-14 15:38:06 +08:00
wizardchen 1eae475a1f feat(i18n): enhance localization for task management and queue descriptions
Added new translations and improved existing ones for English, Korean, Russian, and Chinese. Introduced short weight labels, refined failed task notices, and updated queue names and descriptions for better clarity and consistency across languages.
2026-07-14 13:11:06 +08:00
wizardchen 6171962e56 feat(system): add failed-task inspection and manual retry for runtime queues
Give system admins visibility into asynq tasks that exhausted retries, with safe retry/delete actions and operator-facing UI in Runtime Queues.
2026-07-14 13:11:06 +08:00
darcy f7ec759cc6 fix(knowledge): propagate chunking strategy to parent-child splitter configs
buildParentChildConfigs only copied ChunkSize/ChunkOverlap/Separators into
the parent and child SplitterConfigs, dropping base.Strategy. Since an empty
Strategy resolves to the legacy tier (resolveChainWithProfile treats "" as
legacy for backwards compatibility), parent-child chunking always ran the
legacy recursive splitter regardless of the configured strategy: no heading
alignment and no ContextHeader breadcrumbs in child embeddings, silently.

The flat path (buildSplitterConfigFromChunking) already propagates Strategy;
parent-child predates the strategy system (b3334990, 2026-03) and was not
updated when the 3-tier strategy landed (ae6fde23, 2026-05). SplitParentChild's
docstring ("Child splitting honours childCfg.Strategy") and mergeBreadcrumbs
both assume the strategy reaches the parent-child path.

Copy base.Strategy into both configs and add a regression test.
2026-07-14 11:56:29 +08:00
Binks Riverton 3b587c401d fix(frontend): add cancelled, finalizing, draft statuses to parse-status dropdown
The '全部状态' (All Statuses) filter dropdown on the knowledge base documents page was missing the 'cancelled', 'finalizing', and 'draft' status options, even though documents can reach these states (e.g. cancelled via the '停止解析' button). Added all three status options and their i18n translations for zh-CN, en-US, ru-RU, and ko-KR.
2026-07-14 11:38:30 +08:00
wizardchen abeb4a0126 style(system): polish admin password reset trigger and dialog layout
Improve the password reset entry button and dialog styling for clearer
visual hierarchy, consistent spacing, and better mobile responsiveness.
2026-07-14 11:30:15 +08:00
wizardchen 087fcc9fe7 feat(agent): add question suggestions with after-answer follow-ups
Enable agents to configure starter prompts and async follow-up questions after completed answers, with durable caching, analytics events, and chat/embed UI integration.
2026-07-14 11:17:25 +08:00
wizardchen a6c85dad28 feat(middleware): enhance logger to sanitize new and old password fields
Updated the logger to include regex patterns for sanitizing "new_password" and "old_password" fields in JSON logs. Added a corresponding test case to verify the sanitization functionality.
2026-07-13 20:11:00 +08:00
wizardchen 8ec65941a5 feat(system): add admin password reset with session revocation
Let system administrators reset another user's local password from the settings UI, revoke all active sessions, and record the action in the audit log.
2026-07-13 20:11:00 +08:00
wizardchen 8554c422dc feat(frontend): reorganize system settings into tabbed sections
Group global settings by product area (access, tenant, runtime, security),
add overview summary badges and inline save feedback, surface high-risk
keys, and collapse config-priority docs into a disclosure panel.
2026-07-13 19:42:18 +08:00
wizardchen 87ba3fc2de refactor(auth): unify OIDC provisioning under shared default_tenant_mode policy
Drop the standalone OIDC_AUTH_DEFAULT_TENANT_MODE / oidc_auth.default_tenant_mode
knob so OIDC auto-provisioning and local password registration share the single
auth.default_tenant_mode policy (resolved by the callback handler). Repair
tenantless sessions by falling back to the first active membership on the login
happy path and stale-preference paths, allow tenantless PUT /auth/me/preferences,
clear the tenant snapshot on /auth/me responses without a tenant, and default the
frontend canCreateTenant capability to fail-closed until /auth/me confirms it.
2026-07-13 19:14:49 +08:00
wizardchen ecf2c1fb9b feat(auth): support tenantless provisioning and gated self-service workspace creation
Allow deployments to register users without auto-creating a personal tenant, expose creation policy via /auth/me, and guide tenantless accounts through a workspace onboarding flow.
2026-07-13 18:13:51 +08:00
wizardchen 50b8c0a72e fix(security): harden agent share listing and align full-access API key routes
Enforce tenant ownership in ListSharesByAgent so full-access API keys cannot enumerate cross-tenant shares, and allow full-access keys to create KBs and manage share routes consistently with other tenant-wide operations.
2026-07-13 17:09:58 +08:00
wizardchen 1dfa23d728 docs(model): add Requesty to API and wiki provider lists
Sync hand-written provider tables with the merged Requesty provider support.
2026-07-13 17:08:36 +08:00
Thibault Jaigu 35b92f73aa feat(provider): add Requesty as an OpenAI-compatible model provider
Requesty is an OpenAI-compatible LLM gateway that uses the same provider/model
naming convention as OpenRouter, so this mirrors the existing OpenRouter provider.

- internal/models/provider/requesty.go: RequestyProvider mirroring openrouter.go
  (base URL https://router.requesty.ai/v1, REQUESTY_API_KEY, RequiresAuth)
- provider.go: ProviderRequesty const + AllProviders() entry + DetectProvider case
- internal/types/model.go + client/model.go: ModelSourceRequesty
- provider_test.go: TestRequestyProviderValidation + DetectProvider case
- frontend model editor + i18n (en/zh/ko/ru) + docs/BUILTIN_MODELS.md provider list
- docs/swagger.{json,yaml} + docs.go: requesty enum value (hand-edited to match; these
  are normally swag-generated)

Verified: go build/vet/test pass; live call to https://router.requesty.ai/v1 succeeds.
Signed-off-by: Thibault Jaigu <thibault.jaigu@gmail.com>
2026-07-13 17:03:23 +08:00
wizardchen eacc278b9a fix(wiki): strip internal chunk aliases from page content
Wiki ingest prompts previously encouraged inline [cNNN] citations that
leak internal chunk metadata into reader-facing Markdown. Strip legacy
aliases on read/write paths and update the modify prompt to keep prose
clean while source links remain in ChunkRefs.
2026-07-13 15:59:09 +08:00
wizardchen 07ba01ec93 feat(worker): replace aggregate asynq concurrency with per-pool governance
Split the monolithic upstream worker budget into explicit core, post-process,
enrichment, maintenance, and shared elastic pools, expose live cluster capacity
on the runtime dashboard, and retire the legacy asynq.concurrency setting.
2026-07-13 15:51:06 +08:00
wizardchen 5eefa70e6f Enhance knowledge base configuration by normalizing and validating custom instruction fields. Implemented length checks for prompt instructions and added tests for validation logic. Updated GraphSettings to retain custom instructions when extraction is disabled. 2026-07-13 12:16:19 +08:00
wizardchen c1cddb4d4d Add instruction fields to knowledge base configuration 2026-07-13 12:16:19 +08:00
wizardchen def92bb74f fix(router): restrict KB-scoped file proxy to exports/ paths
Borrowers with shared-KB read access could previously request any
owner-tenant storage path via /knowledge-bases/:id/files. Limit the
proxy to exports/ embedded images; raw knowledge uploads continue to
use /knowledge/:id/download.
2026-07-13 12:13:58 +08:00
wizardchen 800cea0826 fix(files): serve shared KB images via KB-scoped file proxy
Org-shared and agent-visible knowledge bases store images under the owner
tenant's storage path, which the tenant-scoped /files route rejects for
borrowing tenants. Add GET /api/v1/knowledge-bases/:id/files gated by
RequireKBAccess and route frontend image hydration through it when kbId
is known.
2026-07-13 12:13:58 +08:00
wizardchen abcecc870a fix(router): allow scoped API keys to poll FAQ import progress
Register the FAQ import progress route through apiKeyRoute with retrieve
or ingest capability so scoped keys that start imports can poll task
status without hitting APIKeyGate fail-closed 403.
2026-07-13 11:07:07 +08:00
wizardchen c8793b001d fix(spans): make fitSpanName rune-aware and normalize lookups
Follow-up to the knowledge span name column expansion: truncate span
names by rune count to match PostgreSQL VARCHAR(255), apply the same
normalization in LookupSpanByName, and add regression tests for mid-length
wiki slugs and CJK truncation boundaries.
2026-07-13 10:38:50 +08:00
wizardchen 26f8afa3db fix(spans): expand knowledge span name column and truncate long wiki names
Wiki ingest builds postprocess.wiki.page[<slug>] subspan names that can exceed
varchar(64); widen the column to 255 and hash-suffix truncation so long slugs
still persist distinctly.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-13 10:35:44 +08:00
wizardchen 083e9738f6 fix(docreader): detect legacy doc payloads 2026-07-11 12:21:56 +08:00
wizardchen ac8c5c5540 chore(deps): resolve open Dependabot security alerts across Go, npm, and pip.
Bump vulnerable runtime and transitive dependencies in docreader, frontend, and the Go module graph to address current GitHub security advisories.
2026-07-11 12:15:39 +08:00
wizardchen b9cccc7bee feat(system): expose model concurrency stats on runtime queues dashboard
Surface per-model active/waiting/limit from the background task limiter so admins can distinguish task scheduling from model-service throttling, with full i18n coverage.
2026-07-11 07:17:28 +08:00
wizardchen 80556fbaa7 refactor(RuntimeQueues): enhance UI layout and styling for better readability
Updated the RuntimeQueues component to improve the layout and styling of the task queue display. Changes include a new grid layout for pool items, updated class names for better semantic structure, and adjustments to font sizes and spacing for improved readability. Additionally, added a note section with enhanced styling for clarity.
2026-07-10 23:54:24 +08:00
wizardchen d496d0fc73 feat(task-queue): split upstream workers into isolated core/enrichment/maintenance pools
Route summary/sync/maintenance tasks to dedicated queues and servers so parsing, enrichment, and batch work no longer share one concurrency budget, while extending the runtime dashboard and settings validation to reflect the new topology.
2026-07-10 23:51:29 +08:00
wizardchen fe47ac1f96 feat(system): add runtime task queue observability dashboard for system admins
Expose live asynq queue depths and worker-pool concurrency via a new SystemAdmin API and settings UI, so operators can monitor parsing/wiki backlog without Redis CLI access.
2026-07-10 23:51:29 +08:00
养乐多 30f7630ac4 fix(im/feishu): reply via reply-message API so replies land in the original thread
Previously the Feishu adapter sent replies with the "send message" API
(POST /im/v1/messages) without a root_id. In topic-enabled groups this
spawned a new topic for every reply instead of attaching to the thread
the user @-mentioned the bot from, fragmenting the conversation.

Switch SendReply (text) and sendCardByCardID (streaming card) to the
"reply message" API (POST /im/v1/messages/:message_id/reply), using
incoming.MessageID as the path parameter. Feishu automatically replies
in thread form when the replied-to message is itself a thread message,
so no reply_in_thread flag or session-mode plumbing is needed.

Add sendWithFallback to retry via the plain send-message API on
fallback-eligible error codes (230019 topic gone, 230054 unsupported
message type, 230071 group does not support reply-in-thread), and to
skip straight to the fallback when incoming.MessageID is empty. This
keeps replies deliverable even when the reply API cannot be used.

Also add a debug log in convertEvent (longconn.go) that prints every
raw received event (msg_type/chat_id/msg_id/root_id/parent_id/thread_id/
content) to aid diagnosing intermittent event-delivery issues.

No interface signature changes; other platform adapters untouched.

Co-Authored-By: Claude <noreply@anthropic.com>
2026-07-10 22:51:57 +08:00
wizardchen b4b63a0c1f feat(tenant): optional legacy auto-create API key on tenant creation
Add a tenant.auto_create_api_key setting (env
WEKNORA_TENANT_AUTO_CREATE_API_KEY, default false) that restores the
pre-break-change behaviour of minting a full_access API key when a
tenant is created and returning its plaintext token in the create
response (data.api_key).

- system_setting: register tenant.auto_create_api_key bool spec
- handler: gate auto key creation behind the setting; embed the token
  via tenantWithAPIKey without re-adding a persisted api_key column;
  key-creation failures log a warning and do not fail tenant creation
- client: add optional Tenant.APIKey field populated only on create
- docs/env: document the switch (.env.example, docker-compose,
  tenant.md, regenerated swagger)
2026-07-10 15:50:15 +08:00
wizardchen 38aacc3113 chore(env): update WEKNORA_MODEL_MAX_CONCURRENCY to 32 in configuration files
Increase the default value of WEKNORA_MODEL_MAX_CONCURRENCY from 8 to 32 in .env.example, docker-compose.yml, and related application code. This change enhances the concurrency limit for background tasks, ensuring better performance and resource management across the system.
2026-07-10 14:51:01 +08:00
wizardchen 37dcdc7f74 chore(env): update .env.example and docker-compose.yml to include WEKNORA_MODEL_MAX_CONCURRENCY
Add WEKNORA_MODEL_MAX_CONCURRENCY to the example environment file and docker-compose configuration, setting a default value of 8. This change supports the new model concurrency feature for background tasks, ensuring proper configuration across environments.
2026-07-09 20:40:51 +08:00
wizardchen 4404ea74e3 feat(models): implement model.max_concurrency for background tasks
Add a new `max_concurrency` setting to the model configuration, allowing for fine-tuned control over the maximum number of concurrent background tasks (ingestion/enrichment) per model. This update includes localization support across multiple languages and integrates the setting into the system's concurrency governor, enabling immediate application of changes without requiring a service restart.
2026-07-09 20:40:51 +08:00
wizardchen 20256287ec feat(models): add max concurrency setting for background tasks
Introduce a new `max_concurrency` parameter to the model configuration, allowing control over the maximum number of concurrent background tasks (ingestion/enrichment) per model. This feature is applicable to chat, embedding, and VLM models, with a value of 0 or undefined falling back to the global default. Update UI components and localization files to support this new setting, ensuring a seamless user experience.
2026-07-09 20:40:51 +08:00
wizardchen 200c344065 feat(models): cap background embedding concurrency per model
Extend the per-model background concurrency governor to embedding, the
highest-volume background model call (document ingestion vectorises every
chunk, so a batch upload can burst the whole worker pool against one provider).

The wrapper sits innermost (below debug/langfuse) because BatchEmbedWithPool
fans a batch out into per-sub-batch BatchEmbed calls via the pooler, and the
pooler invokes BatchEmbed on whichever Embedder is threaded down as `model`;
sitting innermost routes those per-sub-batch provider round-trips through Gate
so the semaphore bounds real concurrent calls rather than one coarse per-doc
unit. Only background (asynq) calls are throttled; interactive query embedding
is never gated.
2026-07-09 20:40:51 +08:00
wizardchen 98ad41cda4 fix(models): harden background concurrency governor
Follow-up hardening on the per-model background concurrency governor:

- limiter: heartbeat now refreshes the ZSET key's PEXPIRE alongside the
  lease score, so a semaphore that stays saturated with no slot turnover
  can't let the whole key expire (which would drop every lease and admit
  over the limit); reuse one poll timer instead of allocating time.After
  each iteration under contention.
- governor: extract the process-wide governor + Gate helper into the
  limiter package so chat and vlm share one limiter/limit without
  importing each other; add an in-process localLimiter for Lite mode.
- vlm: gate background multimodal (VLM) calls through the same governor;
  previously only chat was throttled.
- chat: ChatStream releases its slot when the consumer abandons the
  stream and cancels ctx (select on ctx.Done, drain inner), fixing a
  slot/goroutine leak.
- container/sync_task: install the local governor in Lite mode and tag
  SyncTaskExecutor runs as background; honour model.max_concurrency=0 as
  an explicit disable instead of falling back to the default.
- tests: cover the governor gating, local limiter, and stream release.
2026-07-09 20:40:51 +08:00
wizardchen 63198c5d9f feat(models): cap background LLM concurrency per model
Background ingestion/enrichment stages (summary, question, graph,
multimodal) all target the same chat model, and asynq queue weights are
scheduling priority rather than throttling. A large upload could therefore
burst up to the entire worker pool of concurrent chat calls against a
single provider, unbounded across replicas, with no model-side rate limit.

Govern concurrency at the chat-client layer (the one place that sees every
task type), keyed by model ID:

- internal/models/limiter: Redis ZSET + Lua distributed semaphore with a
  lease heartbeat, expired-lease reclaim for crashed holders, and fail-open
  on any backend error or context cancellation.
- chat: concurrencyChat decorator (outermost in NewChat) acquires a
  per-model slot only for background tasks; interactive chat is never gated.
- router/task: asynq middleware tags every worker execution as background.
- container: wire the Redis limiter with WEKNORA_MODEL_MAX_CONCURRENCY
  (model.max_concurrency), default 8; enabled only when Redis is present.

Tested with miniredis: concurrency cap, expired-lease reclaim, per-key
isolation, and all fail-open paths (nil client, backend down, cancelled ctx).
2026-07-09 20:40:51 +08:00
wizardchen 76a8092483 refactor(task_queue): enhance claim handling and test coverage
- Renamed TestTaskPendingOps_ClaimBatch_NewSiblingRowNotDoubleClaimed to TestTaskPendingOps_ClaimBatch_LateSiblingBlockedByFreshClaim for clarity on behavior.
- Added new test TestTaskPendingOps_ClaimBatch_LateSiblingClaimableAfterStale to verify claim behavior when a holder crashes.
- Updated ClaimBatch logic to ensure that fresh claims block late siblings entirely, maintaining serialization of same-document operations.
- Improved comments in task_queue.go to clarify the handling of concurrent claims and the implications of the claimed_at field.
- Added crash safety mechanism in ProcessWikiIngest to release claims on abnormal exits, ensuring timely re-claims of pending operations.
2026-07-09 17:41:07 +08:00
wizardchen 60f7f35e40 fix(wiki): recover stranded claims and prevent finalize double-run
- claim/peekPendingList now surface DB errors so a transient load
  failure retries via asynq instead of acking as a false "no pending
  ops" success that strands the queue.
- no_pending_ops now arms a coalesced stale-claim recheck (TaskID
  keyed, delayed past wikiClaimStaleAfter) so rows held by a crashed
  batch's fresh claim are reclaimed automatically instead of sitting
  unclaimable and never re-triggered.
- ProcessWikiFinalize fails CLOSED on a SetNX error (returns an error
  to retry) instead of running unlocked, avoiding two finalize runs
  double-rebuilding the index page.
2026-07-09 17:41:07 +08:00
wizardchen c8a4fd5ba3 fix(wiki): prevent silent work loss and cross-batch doc races
Two correctness fixes on the Phase 3 concurrent claim-based ingest path:

- Slug-lock timeout / reduce failure no longer silently drops work. When a
  per-slug lock can't be acquired within wikiSlugLockWait, or reduce returns
  an error, the page's read-modify-write never lands. Previously the owning
  document was still counted as successful and its pending row was deleted at
  trim time, permanently losing the contribution (finalize only rebuilds the
  index / cross-links, it does not re-run reduce). Such documents are now
  folded into failedOps: their rows stay queued, their finalizing slot is
  held, and requeueFailedOps' fail_count budget retries them (dead-lettering
  a permanently hot/broken slug).

- ClaimBatch now claims by dedup_key affinity so a document is never split
  across concurrent batches. limit counts distinct dedup_keys (documents),
  and ALL eligible rows sharing a key are claimed together. On Postgres the
  per-key anchor row is locked with FOR UPDATE SKIP LOCKED, handing
  concurrent claimers disjoint key sets. This restores in-document ordering
  (e.g. ingest-then-retract collapses correctly) that the per-batch dedup
  could not guarantee once the exclusive per-KB lock was removed, preventing
  a stale ingest from resurrecting a retracted document.

Adds repository tests for same-key affinity and in-flight sibling rows.
2026-07-09 17:41:07 +08:00
wizardchen 70e2e85fa6 feat(wiki): dedicated worker pool with concurrent claim-based batching
Isolate the wiki generation pipeline from the document parse pipeline so
the two can no longer starve each other during concurrent uploads.

- Dedicated asynq worker pool for QueueWiki (NewWikiAsynqServer) with its
  own concurrency budget (WEKNORA_WIKI_ASYNQ_CONCURRENCY / asynq.wiki_
  concurrency, default 16), split from the parse pool (NewParseAsynqServer).
  Both run the same mux over disjoint queue sets. Replaces the old
  weighted-lottery approach where wiki sat on the low queue (weight 1).
- Task queue: add ClaimBatch (SELECT ... FOR UPDATE SKIP LOCKED + claimed_at)
  and ReleaseByIDs so multiple concurrent consumers pull disjoint rows
  without an external per-KB lock; PeekBatch retained for Lite mode.
- New TypeWikiFinalize debounced KB-global finalize task (index rebuild /
  dead-link cleanup / cross-linking), registered on both Redis and Lite paths.
- Two-level wiki ingest concurrency: IngestMaxInflight caps concurrent
  batches per KB; Map/Reduce fan-out sized within a batch. New config knob
  + system setting + swagger docs.
2026-07-09 17:41:07 +08:00
wizardchen 7642117b70 fix(im): harden DingTalk file download with SSRF checks and pictureDownloadCode fallback
Validate temporary download URLs against allowed DingTalk CDN hosts before fetching,
and accept pictureDownloadCode when downloadCode is absent so image messages ingest reliably.
2026-07-09 15:38:13 +08:00
nullkey a6ff0036b5 fix(im): ingest DingTalk file/image messages into knowledge base (#1771)
The DingTalk adapter only ever classified incoming messages as text and
did not implement FileDownloader, so files sent to the bot were never
saved to the channel's configured knowledge base — unlike WeCom, which
worked. Users saw the file received and read, but never stored.

Parse file/picture msgtypes in both the webhook and stream paths (set
MessageTypeFile/Image, FileName, FileKey=downloadCode, robot_code), and
implement DownloadFile: exchange the downloadCode for a temporary URL via
robot/messageFiles/download, then fetch it. robotCode comes from the
callback (webhook) or the app client ID (stream). Pictures get a
MsgID-derived name, mirroring the WeCom adapter.
2026-07-09 15:28:57 +08:00
wizardchen b6d3420a5d fix: harden document pipeline concurrency and diagnostics
- docreader: serialize all pdfium access behind a global lock. pypdfium2
  is process-global and not thread-safe, so concurrent PDF uploads could
  corrupt its shared state and deadlock the whole process (requests stuck
  in "Parsing document" forever). Non-PDF parsers still run concurrently.
- logger: strip ANSI color escapes from file logs so on-disk logs stay
  plain text while stdout keeps terminal colors.
- storage: log baseDir/resolvedPath on file-open failure and when the
  multimodal service resolves a file service, so a LOCAL_STORAGE_BASE_DIR
  mismatch between writer and reader is immediately visible.
- docker: set TZ (default Asia/Shanghai) for the docreader container.
2026-07-09 13:26:40 +08:00
wizardchen d287c70358 feat(frontend): add inline session title rename in sidebar
Allow users to rename chat sessions from the sidebar menu with inline editing, API persistence, and i18n feedback.
2026-07-09 00:10:11 +08:00
wizardchen 6ac1703198 Simplify KB duplicate API and improve naming/docs coverage.
Drop client-supplied target_id, generate IDs server-side, localize duplicate
names from request language, document the endpoint, and expand handler/client tests.
2026-07-08 20:55:54 +08:00
wizardchen 58b79876ae Add knowledge base duplicate flow 2026-07-08 20:55:54 +08:00
wizardchen e93f8d3c21 feat(knowledge-list): show Wiki badge on knowledge base cards
Help users spot Wiki-enabled knowledge bases in the list with a Lucide book icon beside the card title.
2026-07-08 20:12:14 +08:00
wizardchen 0ffdf945b3 fix(knowledge-base): improve doc filter bar responsive layout 2026-07-08 15:45:46 +08:00
wizardchen ca9da8399e feat(dev): support remote infrastructure via .env.local 2026-07-08 15:42:23 +08:00
wizardchen a1b49e2664 fix(faq): guard against division by zero in import timing logs
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-08 15:27:51 +08:00
wizardchen d9bb7aa8f2 fix(search): harden tag scope resolution after #1907
Default missing KB metadata to document tag relation lookup, propagate tag resolution failures instead of returning empty results, and reject ambiguous bare tag_ids when multiple knowledge bases are in scope.
2026-07-08 10:55:42 +08:00
wizardchen 0db71bf2f8 fix(agent): polish selector capability status chips 2026-07-08 10:55:02 +08:00
wizardchen d01526b758 fix(chat): close references drawer on session switch 2026-07-08 00:39:35 +08:00
wizardchen 15b81d1581 fix(agent): gate web search controls by provider readiness 2026-07-08 00:26:34 +08:00
wizardchen 3209ed77fd feat(quick-qa): add references drawer and polish retrieval source UI
Add a side panel for web and knowledge-base citations with citation-badge
highlighting, refine collapsed RAG pipeline summary layout, and emit
knowledge_base_id from agent knowledge_search results.
2026-07-08 00:26:34 +08:00
wizardchen 45eab4a95f fix(quick-qa): distinguish web and knowledge base retrieval in pipeline UI
Emit search_source metadata from RAG progress events so quick-answer steps,
summaries, and IM labels no longer mislabel web-only results as knowledge base search.
2026-07-08 00:26:34 +08:00
wizardchen 77cf6a5789 fix(web-search): polish Keenable provider integration after #1946
Expose optional API key in settings UI, map longer API snippets into Content
for RAG, align maxResults fallback with other providers, sync Swagger enum,
and add follow-up unit tests.
2026-07-07 17:14:39 +08:00
Ilya Bogin 8cf9f1c882 feat: add Keenable as a configurable web search provider
Add Keenable Search alongside the existing DuckDuckGo / Bing / Google /
Tavily / Ollama / Baidu / SearXNG providers.

- internal/infrastructure/web_search/keenable.go: KeenableProvider
  implementing the WebSearchProvider interface, following the Tavily
  provider pattern. Keyless by default: with no API key it calls the
  public endpoint (/v1/search/public, rate-limited); a key switches to
  /v1/search and lifts the cap. Base URL is hardcoded (SSRF-safe), proxy
  is honored.
- Registered "keenable" in the container registry.
- Added the keenable provider type + type metadata (RequiresAPIKey=false)
  and service validation (no required key, like DuckDuckGo).
- Provider-specific empty-results diagnostic (keyless rate-limit hint).
- Frontend: extend the provider union type with 'keenable'.
- Unit tests: keyless vs keyed endpoint, attribution header, maxResults
  trim, result mapping, error status, name.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-07 16:58:26 +08:00
wizardchen f7b427009d fix(frontend): keep HMAC secret visible for copy after save
API principal HMAC secrets are write-only from the server, so users could
not copy a newly generated or rotated key before the input was cleared.
Retain the plaintext in-session after save, simplify secret field controls,
and add copy guidance across locales.
2026-07-07 16:39:51 +08:00
wizardchen 974231190c Add API key member and space capabilities 2026-07-07 12:00:13 +08:00
wizardchen d60614475e test(api-keys): add unit tests for tenant API key validation
Introduce unit tests for the tenant API key validation logic, ensuring that scoped keys require capabilities, while full-access keys are validated without them. The tests cover various scenarios, reinforcing the expected behavior of the API key validation function.
2026-07-07 12:00:13 +08:00
wizardchen 2c6f082062 Refine scoped API key capabilities 2026-07-07 12:00:13 +08:00
wizardchen b5cc7d2a28 feat(api-keys): implement throttled last_used_at updates for API key authentication
Enhance the tenant API key service by introducing asynchronous throttling for the last_used_at updates during API key authentication. This change reduces database write frequency under high request rates, improving performance. Additionally, update tests to validate the throttling behavior, ensuring that last_used_at is only updated once per key within the defined interval. This implementation aligns with the goal of optimizing API key management and maintaining system efficiency.
2026-07-07 12:00:13 +08:00
wizardchen 97c36f634a refactor(api-keys): remove API key reset endpoint and update documentation
Eliminate the POST /tenants/{id}/api-key endpoint for resetting tenant API keys, transitioning to a more granular API key management approach. Update related documentation and API specifications to reflect the new structure, including changes to the tenant API key management paths. Adjust frontend code and internationalization files to remove references to the deprecated API key reset functionality, enhancing clarity and consistency across the application.
2026-07-07 12:00:13 +08:00
wizardchen 1d1e1e3d25 refactor(api-keys): update role handling and enhance API key restrictions
Change the default role for tenant API keys from 'admin' to 'owner' to align with the new authorization model. Update related tests to reflect this change, ensuring that API keys with the owner role are correctly denied access to management paths and system-admin routes. Introduce new tests to validate that API keys are properly restricted from accessing sensitive endpoints, reinforcing the security measures in place.
2026-07-07 12:00:13 +08:00
wizardchen a6759d61b5 feat(api-keys): implement DenyAPIKeyPrincipal middleware and related tests
Add DenyAPIKeyPrincipal middleware to explicitly block API-key principals from accessing certain routes, ensuring security for endpoints outside the /api/v1 group. Introduce tests to validate that API keys are correctly denied access while allowing JWT sessions to pass through. This enhances the overall authorization model by reinforcing the default-deny approach for API keys.
2026-07-07 12:00:13 +08:00
wizardchen d2ffc1b973 refactor(api-keys): simplify authorization to a single-role gate
Redesign tenant API key authorization around one dimension (role) plus a
central default-deny gate, replacing the previous role + KB-scoped flag model.

- Add APIKeyGate as the single authority for API-key authorization: routes
  declare one policy (MinRole) via apiKeyGroup/apiKeyRoute helpers; undeclared
  routes are denied by default. JWT principals short-circuit the gate and the
  JWT-centric RBAC guards short-circuit for API-key principals.
- Roles: viewer/contributor/admin are knowledge-base data-plane only (KB scope
  is a pure downstream data filter); owner is a full-access tenant tier that
  unlocks tenant-level infrastructure routes and is required for every method.
- Drop the KBScoped policy flag and the KB-restricted-vs-tenant branching.
- Security hardening: never disclose HMAC secret (return presence only), abort
  writes on API-key encryption failure, deny KB-restricted keys on /files, and
  backfill legacy key hashes at startup instead of O(N) plaintext scans.
- Frontend: two-level create dialog (access type -> permission level), rename
  role labels to reflect actual scope, sync en/zh/ko/ru locales.
- Fix startup self-check false-positive on trailing-slash routes and normalize
  gin paths before comparison; add regression tests.
2026-07-07 12:00:13 +08:00
wizardchen fedb6c3f7e test(api-keys): add tests for tenant API key management path rejection
Introduce tests to validate that tenant API keys are correctly restricted from accessing management paths. Implemented new test cases for both allowed and forbidden paths, ensuring proper enforcement of API key scopes. Additionally, refactored existing tests to utilize the new rejection logic.
2026-07-07 12:00:13 +08:00
wizardchen 9a76a24ce6 refactor(api-keys): use role field and route-level API key guards
Replace scopes JSON with a viewer/contributor/admin role column, move
unsafe-method authorization from path-prefix middleware to declarative
APIKey* guards on routes, and close remaining KB-scope gaps in handlers.
2026-07-07 12:00:13 +08:00
wizardchen 3ace6e657f fix(frontend): polish API key create dialog UX and align i18n
Map API key permissions to tenant roles in the UI, widen the create dialog,
and sync integrations.api locale strings across en-US, ko-KR, and ru-RU.
2026-07-07 12:00:13 +08:00
wizardchen c65ffa3d9c fix(api-keys): enforce scope from request context after attach
Use c.Request.Context() in authenticateAPIKeyRequest so scoped keys are
actually restricted, update dto tests for removed tenant.api_key, and add
a regression test for the attach-context contract.
2026-07-07 12:00:13 +08:00
wizardchen 94d18ea15a fix(api-keys): close KB scope gaps in handlers and CloneContext
Enforce per-key knowledge base restrictions on batch/search read paths,
centralize scope checks in shared KB access validators, and propagate
TenantAPIKeyScope through logger.CloneContext so async QA cannot bypass it.
2026-07-07 12:00:13 +08:00
wizardchen 3f516d7f31 fix(api-keys): harden scoped key auth after code review
Revoke existing keys on reset, unify scope enforcement, default empty
scopes to read-only, map API key scopes to tenant roles, and remove dead
key-generation helpers left over from the tenant api_key column removal.
2026-07-07 12:00:13 +08:00
wizardchen 505bc7ddec feat: add scoped tenant api keys 2026-07-07 12:00:13 +08:00
langcaiye 1708d6895a fix(search): apply tag filters to knowledge search 2026-07-06 23:30:33 +08:00
cao_j b16cb0bb56 fix(agent): treat end_turn as natural stop 2026-07-06 23:16:18 +08:00
养乐多 baada32cb6 fix(im/feishu): actually close WebSocket long connection when channel is stopped
Deleting or disabling a Feishu channel left its WebSocket long connection
alive: the Lark SDK's Start blocks on a bare select{} and never observes
ctx, and v3.6.1 exposed no public Close(), so the wsCancel() cleanup was a
no-op. The socket stayed open, the SDK kept auto-reconnecting, and Feishu
kept pushing messages — causing cross-environment message duplication when
the same bot was bound elsewhere.

Fix in three layers:

1. Connection teardown
   - Upgrade oapi-sdk-go v3.6.1 -> v3.9.7 (adds Client.Close()).
   - Add LongConnClient.Close() wrapping wsClient.Close(); factory's cleanup
     now calls Close() first, then wsCancel() as a belt-and-braces fallback.

2. Multi-instance coordination
   - wsLeaderRetryLoop: after acquiring leadership, re-check the DB before
     starting; abort if the channel was deleted/disabled while waiting.
   - wsLeaderRenewLoop: on each renewal, re-check the DB; step down if the
     channel was deleted/disabled on another instance (HTTP request may have
     been served elsewhere), so the leader doesn't keep the connection open
     until process restart.

3. Robustness
   - DB checks distinguish gorm.ErrRecordNotFound (channel truly gone ->
     stop/abort) from transient DB errors (skip this round, retry next tick)
     so a DB hiccup can't cause a spurious stop or permanent leader-abort.
   - startChannelInternal now stops any existing channelState for the same
     ID before overwriting, making it idempotent against concurrent start
     paths and preventing adapter/long-connection leaks.

No interface changes; webhook and long-poll modes unaffected.

Co-Authored-By: Claude <noreply@anthropic.com>
2026-07-06 23:10:45 +08:00
wizardchen 4f2dca0b63 fix(redis): harden TLS tests and surface TLS config at startup
Isolate Redis TLS unit tests from parent-process env vars and log
REDIS_USE_TLS settings at boot so misconfiguration is easier to spot.
2026-07-06 23:04:52 +08:00
qilifan d5b8d2f886 feat(redis): support TLS for Redis connections (#1930)
[Feature]: Support TLS for Redis connections
2026-07-06 23:02:02 +08:00
nullkey d3c03b2f34 feat(cli)!: v0.10 reliability, agent-UX, and command-surface hardening
A hardening + finalization pass over the agent-first CLI: correctness fixes,
richer machine-readable signals, flag/naming consistency, and a symmetric
config surface. Pre-1.0, so it includes breaking renames.

Correctness:
- agent update: resolve/validate --model/--rerank-model (was storing a bogus
  name verbatim, corrupting config.model_id).
- doctor: honor WEKNORA_HOST / WEKNORA_API_KEY (headless path no longer reports
  "no host configured").
- session ask / MCP session_ask: text answer was empty on non-TTY — the agent
  stream sets Done=true on an intermediate agent_query frame before the answer,
  and AgentAccumulator treated the first Done as terminal. Terminate on the
  `complete` event (new sdk.AgentResponseTypeComplete), not a per-frame Done.
- batch exit codes: any per-item failure collapses to operation.failed (exit 1),
  including `doc upload --recursive` partial failures — a permanent per-file
  failure (e.g. a duplicate) no longer surfaces as a retryable exit 7 an agent
  would loop on; per-item typed errors stay in the envelope.

Agent-first signals & discovery:
- error.exit_code in the envelope (type + exit_code disambiguate the
  input.invalid_argument exit-2-vs-5 split in one JSON read).
- meta.hint on empty content search and on draft doc create; doc wait fails fast
  on a never-parsing draft instead of hanging to --timeout.
- retrieval-readiness is visible in the natural flow: kb status / kb check emit
  retrieval_ready, and kb create hints the fix when no embedding model is bound
  — an unconfigured KB no longer looks silently healthy.
- schema contract completeness: every leaf declares output + >=1 example
  (drift-guarded); output strings match the meta actually emitted; chunk list
  and search docs now emit meta.total_count (both previously dropped it).
- schema tolerates a quoted multi-word command label; zero-state auth — and
  `link` with no profile — point at profile setup / the headless WEKNORA_KB_ID
  path instead of looping on `auth login`.
- id-addressed reads tolerate a redundant --kb (doc view/wait, chunk list/view
  accept and ignore it, declared in schema) so a carried-over --kb doesn't
  exit 2; streaming commands warn that --jq does not apply to an NDJSON stream.
- keep JSON-always as the default; --jq hints spell out the .data path.

Consistency & gating:
- doc create: drop the deprecated --name alias (--title only; pre-1.0 break).
- chunk list --limit aligned to 1..10000; model list --limit/-L with
  has_more/total_count; api write-gates -X PUT/PATCH (exit 10); skills install
  expands a leading ~.
- docs corrected: search docs / doc list --keyword help is case-insensitive
  (server does LOWER LIKE); AGENTS.md risk-action list (no phantom kb.init; add
  model.update / kb.config.set) and batch example (failed item carries `error`);
  session resume --message id comes from `message list`, not the stream.
- auth/profile ergonomics: env credentials are now first-class — `auth token`
  prints the active WEKNORA_API_KEY / WEKNORA_TOKEN, and auth login/logout/refresh
  give an env-aware message instead of looping on "run auth login". `auth logout`
  clears credentials but keeps the profile registered (host preserved for
  re-login); deleting a profile is `profile remove`'s job (clean logout/remove
  separation, matching gh / lark).

Config surface (symmetric read/write, in-place model edits):
- kb config now returns a secret-free KBModelConfigView (was {}); `kb config`
  reads, new `kb config set` writes; `kb init` removed (misnomer).
- kb create --chat-model: retrieval-ready in one step.
- model update: edit a model in place (id preserved, references survive) —
  rotate --api-key-stdin, change base-url / display-name / etc.
- session continue-stream renamed to session resume.

Docs: AGENTS.md is the single wire-contract source; CHANGELOG slimmed; stale
kb-init / continue-stream references removed; skill wire-vocab guard extended.
AGENTS.md / weknora-shared SKILL document retrieval_ready (a KB needs an
embedding model to be searchable), that --jq does not apply to NDJSON
streams, and the env-credential-first auth path; the KB quickstart example
now creates a retrieval-ready KB.
2026-07-06 22:53:01 +08:00
nullkey 040a734766 docs: CLI operational contract, quickstart, and changelog
AGENTS.md wire contract for AI agents, README install + 5-minute quickstart,
CHANGELOG, and the root README CLI section.
2026-07-06 22:53:01 +08:00
nullkey 6f8b825f5f feat(cli): agent-first WeKnora CLI
The `weknora` command-line client for the WeKnora RAG server. Full command
surface: kb / doc / chunk / session / message / agent / model / search / chat /
auth / profile / link / api / mcp / skills / config / doctor / schema /
exit-codes.

Agent-first wire contract: JSON envelope by default, typed error codes mapped to
stable exit codes, error.retry_argv / retryable / partial-failure status,
global --dry-run preview, the exit-10 confirmation protocol for writes, and
control/ANSI/Bidi input hygiene. Stateless env-credential auth
(WEKNORA_API_KEY / WEKNORA_TOKEN + WEKNORA_HOST) for headless/CI/agent use.
A curated read-only MCP tool surface (`mcp serve`) and embedded Agent Skills
(`skills install`). Extensive unit + contract-golden tests and CI.
2026-07-06 22:53:01 +08:00
nullkey 445a4330fa fix(server): case-insensitive doc keyword search + not-found classification
Make document keyword search case-insensitive (LOWER(...) LIKE LOWER(?)) in the
list filter and SearchKnowledge / SearchKnowledgeInScopes paths so a query and
its differently-cased variant return the same results.

Classify not-found consistently as HTTP 404 (not 500) so clients read a
permanent resource.not_found instead of a retryable 5xx: map the document /
chunk not-found sentinels in the KB-access middleware (typed ErrChunkNotFound
via errors.Is), and return 404 for a missing message on the continue-stream and
message-delete endpoints.
2026-07-06 22:53:01 +08:00
nullkey 8f36ea2229 feat(sdk): typed errors, enums, and KB model config for the CLI
Adds the client-library surface the agent-first CLI builds on:
- named server error-code constants + typed *APIError from non-2xx responses,
- MessageSearchMode / AgentMode / KBSelectionMode and model type/source
  enumerators so the CLI validates flags against the server vocabulary,
- SetKBModelConfig for binding embedding/chat models to a knowledge base.
2026-07-06 22:53:01 +08:00
wizardchen eba9fe7e78 fix(frontend): unify document action menu styles and reset move state on close
Restore onVisibleChange in card menu close handler so moveMenuMode resets correctly, and align list view popup chrome with card view via shared card-more styles.
2026-07-06 22:52:32 +08:00
Binks Riverton cb46db23f5 refactor(frontend): extract shared document action menu and card view component
- Add DocumentActionMenu.vue: shared component for document context menu
  items (edit, view-trace, rebuild, cancel-parse, move, batch-manage,
  delete) with consistent visibility conditions
- Add DocumentCardView.vue: standalone card/grid view component extracted
  from KnowledgeBase.vue inline template, including hover popover, tag
  chips, move sub-flow, and status display
- Update DocumentListView.vue: use shared DocumentActionMenu, add
  canMutateKnowledge gating for move/batch-manage, add view-trace and
  batch-manage menu items, add move sub-flow support (targets/confirm)
- Update KnowledgeBase.vue: use DocumentCardView component, add
  handleCardAction bridge, remove unused helpers and imports

Both card and list views now render identical operation menus from a
single source of truth.
2026-07-06 22:45:51 +08:00
wizardchen 1b0502e562 fix(feishu): upload card markdown images 2026-07-06 14:52:29 +08:00
wizardchen 699d6bd235 fix(frontend): harden settings localStorage load after #1925
Validate parsed WeKnora_settings is a plain object, deep-clone defaults
on reset, and reuse safeSetItem for reconcile write-back. Extracts load
logic into settingsStorage with unit tests for corrupt and non-object JSON.
2026-07-06 10:46:34 +08:00
Binks Riverton 85f5cd760b fix(frontend): prevent white screen from corrupted localStorage
- Wrap JSON.parse in loadAndReconcileSettings() with try/catch, fall
  back to defaultSettings and remove corrupted WeKnora_settings on
  parse failure instead of crashing the app
- Add try/catch around localStorage.setItem write-back for quota
  exceeded protection
- Register app.config.errorHandler to catch unhandled Vue errors and
  prevent silent component tree crashes
2026-07-06 10:43:43 +08:00
wizardchen 18d7a6b3d3 Fix manual knowledge editor publish flow 2026-07-03 18:38:34 +08:00
wizardchen 1109e85a57 fix(cli): align stream error handling after output-mode merge
Follow up on #1740/#1741 by typing terminal SSE errors in the SDK,
classifying them as server.error in the CLI/MCP, marking Projector done
on error frames, attaching session_id to MCP stream failures, and
migrating the e2e chat step to the bounded JSON envelope.
2026-07-03 00:30:34 +08:00
coconut-yc 9437e1ac3c feat(cli)!: add agent-first chat and session ask output modes 2026-07-03 00:21:48 +08:00
coconut-yc 238297e2c5 fix(client): harden chat and agent SSE reliability 2026-07-03 00:13:41 +08:00
wizardchen 1661827d6e fix(security): harden model client redirects 2026-07-02 19:15:46 +08:00
wizardchen 663d13eb58 fix(security): harden outbound requests and file previews 2026-07-02 19:15:46 +08:00
wizardchen 7099a7e181 fix(security): redact IM list credentials and harden MinerU SSRF
Stop returning bot credentials from Viewer-accessible IM channel list
endpoints and validate self-hosted MinerU URLs at config save and fetch time.
2026-07-02 17:58:20 +08:00
Krypt0n123 929697618f fix(nginx):embed iframe x-frame-options 2026-07-02 17:17:24 +08:00
wizardchen 235e86b876 fix(security): harden refresh token validation and add auth tests
Reject refresh attempts when the DB token type is not refresh_token,
and add service-layer tests for bearer refresh rejection, logout
revocation, and expired-token logout handling.
2026-07-02 17:08:17 +08:00
wizardchen 26cc335420 fix(security): apply MCP upload sandbox when transport is set via CLI
Record the active transport at run_stdio/run_sse/run_http startup so
create_knowledge_from_file path checks apply even when MCP_TRANSPORT
is not set in the environment.
2026-07-02 17:08:17 +08:00
wizardchen 040504447e fix(security): block refresh tokens as bearer and sandbox MCP uploads
Reject refresh JWTs in ValidateToken, revoke all user sessions on logout,
and restrict create_knowledge_from_file to allowed directories on network MCP transports.
2026-07-02 17:08:17 +08:00
wizardchen cd65665894 fix(security): close remaining GHSA gaps from security triage
Block scheme-prefixed loopback storage checks, validate Notion attachment
URLs, sanitize wiki markdown HTML, and require MCP_SERVER_AUTH_TOKEN for
network MCP transports.
2026-07-02 15:03:53 +08:00
wizardchen f23c674bad fix(security): close six open GHSA findings from security triage
Harden share-link listing, password rotation, OIDC callback binding,
org invite search, knowledge batch mutations, and connector redirects.
2026-07-02 15:03:53 +08:00
wizardchen fc64751f4e fix(security): close init config and parser-check redaction gaps
Strip model base URLs from viewer-accessible initialization config
responses and merge redacted parser secrets before engine check overrides
so admin test flows keep working after masked GET responses.
2026-07-02 14:41:42 +08:00
wizardchen 1a264e09c1 fix(security): harden secret redaction follow-ups for PR #1884
Restore PreserveIfRedacted merge on tenant KV PUT so Admin settings saves
no longer overwrite stored secrets with placeholder values. Redact cross-
tenant tenant listings, tighten Viewer MCP/model responses, and align init
config frontend types with credentials metadata.
2026-07-02 14:41:42 +08:00
wizardchen 512d2e5c25 fix(security): redact secrets in login and tenant KV update responses
Apply the same tenant/integration secret policy to auth login, OIDC
callback, switch-tenant, and invite-register payloads, and return masked
config objects from Admin-only tenant KV PUT handlers.
2026-07-02 14:41:42 +08:00
wizardchen 0b73080bb8 fix(security): redact integration secrets from viewer-accessible endpoints
Prevent low-privileged tenant members from reading raw API keys and
infrastructure credentials via tenant profile, KV config, model/MCP/web
search listings, and KB initialization config responses.
2026-07-02 14:41:42 +08:00
wizardchen 8325dac738 fix(security): harden web_fetch and datasource connector SSRF paths
Use SSRF-safe HTTP clients in chat pipeline web_fetch and Feishu/Yuque/Notion
connectors, validating tenant-supplied base_url values before outbound requests.
2026-07-02 12:27:48 +08:00
wizardchen 1d322c525a fix(security): block SSRF via redirects in knowledge URL import
Use the SSRF-safe HTTP client for file_url downloads and add redirect-aware
guards to the docreader Playwright path, closing GHSA-44fp, GHSA-rv6v, and
GHSA-c7m6.
2026-07-02 12:27:48 +08:00
wizardchen a17a2250ed fix(security): enforce KB access on wiki reads and related IDOR paths
Gate wiki GET routes and initialization config reads with KBAccessRead,
and bind async task progress endpoints to the caller tenant via task ID
parsing. Closes cross-tenant read paths reported in GHSA-ph8f-4qwx-89rr
and related initialization/progress leaks.
2026-07-02 12:06:22 +08:00
wizardchen ab790bcbd9 fix(security): close SQL validator bypass in agent database tools
Harden validateNode with default-deny semantics and PG17 SQL/JSON node
recursion so dangerous functions cannot hide inside JSON_SCALAR/JSON_VALUE.
Also recurse into FROM subqueries for DuckDB data_analysis and block
read_text/read_blob and related file-access functions.
2026-07-02 11:42:11 +08:00
wizardchen 0060c0d397 Fix MCP code import placeholder 2026-07-01 21:08:54 +08:00
wizardchen 2203c4bb14 feat(im): include per-service MCP OAuth URLs in IM auth notices
IM channels cannot complete in-conversation OAuth prompts, so when an
MCP service needs authorization the reply now includes clickable
authorization URLs (when APP_EXTERNAL_URL and OAuth manager are
available) instead of only directing users to the admin console.
2026-07-01 17:53:54 +08:00
wizardchen c694fcf6cd test: address PR review follow-ups for OAuth and logger cleanup
Restore logger config via t.Cleanup after t.Setenv so Yuque token tests
do not leak global state, add unit tests for MCP OAuth non-interactive
context helpers and IM auth notice formatting, and fix EmbedChatCore
indentation.
2026-07-01 17:31:42 +08:00
wizardchen 8d40959f88 fix lint and test failures 2026-07-01 17:31:42 +08:00
wizardchen 4c962a9403 feat(agent): add configurable MCP OAuth wait timeout per agent
Allow agents to set how long in-conversation OAuth prompts wait before
auto-skipping, with UI in the agent editor and bounded gate behavior.
2026-07-01 14:37:37 +08:00
lawrence fdfc7297de fix(vlm): allow configurable temperature for VLM models
Some VLM models (e.g. certain vision models) only accept temperature=1.
Previously temperature was hardcoded to 0.1. Now reads from model's
ExtraConfig["temperature"] with fallback to default 0.1.

Usage: set ExtraConfig.temperature=1 in the VLM model configuration.
2026-07-01 12:20:09 +08:00
Krypt0n123 9682ad67a6 fix: update dev script checks and Air docs 2026-07-01 11:52:42 +08:00
wizardchen ee1014f87c feat(frontend): add API integration playground 2026-07-01 11:14:51 +08:00
wizardchen a24567a951 fix(docker): default DB_HOST to postgres in .env.example
Docker Compose runs the app against the postgres service hostname;
localhost breaks first-time setup when copying .env.example as-is.
2026-06-30 21:06:30 +08:00
wizardchen 2d9b21feb6 fix(frontend): polish Chrome and Claw integration landing pages
Remove redundant hero icons from the Chrome extension and Claw Skill
landing headers, and keep Claw CTA hover states on the lobster accent
instead of the default brand green.
2026-06-30 20:42:51 +08:00
wizardchen f8accb2610 fix(frontend): hide API integration tab for non-owner tenants
Gate the integrations API tab and sidebar preview behind owner role,
matching Settings and the /api-principal-config backend guard, so users
without permission no longer see a 403 error when opening the tab.
2026-06-30 20:42:51 +08:00
wizardchen 47a7fe8c83 feat(migrations): add principal model migration for MCP OAuth and tenant API config
Implement migration 000064 to introduce principal columns in MCP OAuth tokens, widen user_id in sessions, and add tenant API principal configuration. Remove previous migrations related to API principal config and user_id widening.
2026-06-30 20:01:05 +08:00
wizardchen f373c8a96f fix(frontend): update API integration icon to secured 2026-06-30 20:01:05 +08:00
wizardchen 146b41193d feat(frontend): embed OAuth wiring and API integration UI polish
Wire embed visitor ID through chat and MCP OAuth flows, add embed i18n,
redesign API integration settings (signed-token docs, layout), and rename
the integrations tab to API Integration with a server icon.
2026-06-30 20:01:05 +08:00
wizardchen 5074344c16 feat(embed): scope OAuth and sessions per visitor principal
Add embed visitor principals (X-Embed-Visitor), widen sessions.user_id,
embed MCP OAuth/approval routes, OAuth callback context detachment, and
CloneContext principal preservation for async QA streams.
2026-06-30 20:01:05 +08:00
wizardchen 168b1d4cfe docs: clarify API principal isolation scope and direct_header risks
Document MCP OAuth-only principal boundaries and spoofing risks for
direct_header mode in API docs and the integrations settings UI.
2026-06-30 20:01:05 +08:00
wizardchen 97bca74a31 fix: harden API principal config after review
Add require_direct_header toggle, external user ID validation, JWT TTL
limits, SaveToken error handling, ru-RU i18n, API docs, and Go SDK methods.
2026-06-30 20:01:05 +08:00
wizardchen cb99736d72 feat: scope API MCP OAuth by principal 2026-06-30 20:01:05 +08:00
1150 changed files with 106898 additions and 21687 deletions
+610 -631
View File
File diff suppressed because it is too large Load Diff
+14
View File
@@ -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
+6
View File
@@ -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
View File
@@ -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
+34 -27
View File
@@ -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
View File
@@ -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
View File
@@ -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
View File
@@ -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 확장 프로그램
+1 -1
View File
@@ -1 +1 @@
0.6.3
0.7.1
+7 -3
View File
@@ -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.
+55
View File
@@ -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
View File
@@ -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.
+2 -2
View File
@@ -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
}
+81 -53
View File
@@ -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
View File
@@ -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
View File
@@ -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
View File
@@ -1 +1 @@
{"ok":true,"data":[],"meta":{}}
{"ok":true,"data":[],"meta":{"count":0,"total_count":0}}
+2 -2
View File
@@ -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
View File
@@ -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
+38 -1
View File
@@ -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)")
}
+2 -1
View File
@@ -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
View File
@@ -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)
}
+42 -6
View File
@@ -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
View File
@@ -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)
}
+29
View File
@@ -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)})
+64
View File
@@ -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
View File
@@ -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 {
+72
View File
@@ -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
View File
@@ -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")
}
}
+1 -1
View File
@@ -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
View File
@@ -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
View File
@@ -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")
+16 -5
View File
@@ -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) {
+12
View File
@@ -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
View File
@@ -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)
+3 -2
View File
@@ -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
View File
@@ -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
View File
@@ -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
View File
@@ -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)
}
}
+6 -3
View File
@@ -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 {
+1 -1
View File
@@ -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
View File
@@ -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)
}
+27 -1
View File
@@ -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")
+1
View File
@@ -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)"},
+25
View File
@@ -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
}
+275
View File
@@ -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)"
}
+120
View File
@@ -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
View File
@@ -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
}
+13 -2
View File
@@ -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"))
+7 -5
View File
@@ -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
}
+2 -2
View File
@@ -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)
+2
View File
@@ -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))
+5
View File
@@ -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
}
+3 -3
View File
@@ -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
+5 -2
View File
@@ -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
View File
@@ -3,9 +3,7 @@ package doc
import (
"context"
"fmt"
"slices"
"sort"
"strings"
"text/tabwriter"
"time"
@@ -48,10 +46,6 @@ type ListOptions struct {
EndTime string // raw RFC3339; parsed into filter.EndTime
}
// rfc3339Example is the canonical RFC3339 hint surfaced when --start-time /
// --end-time fail to parse. Picked to match Go's reference time docs.
const rfc3339Example = "2006-01-02T15:04:05Z"
// docListStatusValues mirrors internal/types/knowledge.go ParseStatus*
// constants - these are the values the server accepts on the
// ?parse_status= query. Kept in sync manually since the SDK doesn't
@@ -88,6 +82,14 @@ backend storage order is not guaranteed and varies between deployments.`,
return err
}
fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
// Validate static input (--page-size / --limit / --status) before
// resolving the KB or building the client so a bad value returns
// input.invalid_argument (exit 5) instead of an auth error (exit 3)
// when the profile is unconfigured — an agent must see the real,
// fixable problem.
if err := validateListOpts(opts); err != nil {
return err
}
kbID, err := f.ResolveKB(c)
if err != nil {
return err
@@ -101,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).
+39
View File
@@ -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) {
+96
View File
@@ -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
}
+84
View File
@@ -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"])
}
+153
View File
@@ -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
}
+137
View File
@@ -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)
}
+6 -2
View File
@@ -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
}
+9 -8
View File
@@ -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,
+7 -4
View File
@@ -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)
}
+1
View File
@@ -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)"},
+9
View File
@@ -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.
+27
View File
@@ -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)
}
}
+28 -3
View File
@@ -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 {
+52
View File
@@ -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)
}
})
}
+41 -6
View File
@@ -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) {
+84
View File
@@ -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()
}
+99
View File
@@ -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
View File
@@ -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)
+4 -1
View File
@@ -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)
}
+110
View File
@@ -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)
+166
View File
@@ -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)
+138
View File
@@ -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`")
}
+70
View File
@@ -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
View File
@@ -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
}
+3 -3
View File
@@ -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")
}
+54 -4
View File
@@ -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) {
+2 -1
View File
@@ -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
}
+3 -3
View File
@@ -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
View File
@@ -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)
+1 -2
View File
@@ -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)
+6 -6
View File
@@ -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
View File
@@ -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
View File
@@ -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)
}
+37
View File
@@ -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
View File
@@ -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"
+8 -4
View File
@@ -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
View File
@@ -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)
+22 -5
View File
@@ -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) {
+15
View File
@@ -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)
}
+9
View File
@@ -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
View File
@@ -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
}
+3
View File
@@ -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
}
+3
View File
@@ -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",
+117
View File
@@ -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
}
+99
View File
@@ -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