* fix(agent): search bound knowledge bases before answering, and pass suggested-question origins
A user picked the suggested question "为什么在比较图形时需要谨慎处理?"
and the agent answered in round 1 with no tool call, claiming it had
searched the knowledge base and found nothing, then explained misleading
statistical charts. The question had been generated from "Corners Don't
Look Like That: Regarding Screenspace Ambient Occlusion" in a bound base,
where "comparing graphs" means SSAO falloff curves.
Two things let that happen: the grounding prompt said "Stable general
explanations need no lookup", and nothing told the agent where the
question came from - the base in question had no profile, only two
recent titles in the directory, and the click sent the text alone.
Prompt
- With knowledge tools available, search bound bases before answering a
question about a topic, even one that reads like general knowledge;
directory profiles and recent titles cannot prove a base lacks it.
- The general-explanation exemption applies only without bound bases.
- Say you searched or found nothing only when a search tool ran.
Question origin
- Suggested questions from FAQ/document chunks also return knowledge_id.
- Picking one on the home or chat page sends question_origin
{knowledge_base_id, knowledge_id} with that question only.
- The service keeps the origin only when its base is inside the turn's
resolved scope and the document belongs to that base; it never
changes the scope (unlike knowledge_base_ids, which narrows it).
- The engine renders it in runtime_context as <question_origin> with the
base and document handles and a note to search it before answering.
* fix(agent): keep question origins across file/tag scopes and bind them to the send
Review follow-up for the suggested-question origin.
- Scope check: the origin was kept only when its base was in the resolved
KB list, which is empty for file-only and tag-only scopes even though
their bases are searched. It is now checked against SearchTargets after
they are built; the document is kept only when a target for that base
covers it (unfiltered base, or a document scope listing it).
resolveQuestionOriginInfo re-checks SearchTargets, looks up the name of
a base that is not in kbInfos, and the renderer omits an unknown name.
- Frontend: the origin travelled through module-level "pending" state, so
a send that returned early (agent not ready, upload in progress,
steering) left it behind and a second pick overwrote it. It now rides
with the one send: triggerSend(text, options) -> createSession ->
send-msg -> sendMsg / changeFirstQuery.
- RetrieveKBOnlyWhenMentioned: suggestions are still generated from the
agent's bases, but picking one retrieved nothing. The origin now
selects its base, as an @mention would, when the agent may read it.
- API sync: question_origin in docs/api/chat.md and swagger;
QuestionOrigin on the Go SDK's KnowledgeQARequest/AgentQARequest and
knowledge_id on SuggestedQuestion.
|
||
|---|---|---|
| .. | ||
| README.md | ||
| README_EN.md | ||
| agent.go | ||
| agent_manage.go | ||
| agent_manage_test.go | ||
| auth.go | ||
| chunk.go | ||
| client.go | ||
| env_var.go | ||
| evaluation.go | ||
| example.go | ||
| faq.go | ||
| go.mod | ||
| go.sum | ||
| initialization.go | ||
| knowledge.go | ||
| knowledgebase.go | ||
| knowledgebase_duplicate_test.go | ||
| log.go | ||
| log_test.go | ||
| mcp_endpoint.go | ||
| mcp_service.go | ||
| memory.go | ||
| message.go | ||
| message_suggestion.go | ||
| model.go | ||
| organization.go | ||
| resource_urls.go | ||
| resource_urls_test.go | ||
| session.go | ||
| skill.go | ||
| stream_errors.go | ||
| stream_errors_test.go | ||
| streaming_test.go | ||
| system.go | ||
| tag.go | ||
| tenant.go | ||
| web_search.go | ||
README_EN.md
WeKnora HTTP Client
This package provides a client library for interacting with WeKnora services, supporting all HTTP-based interface calls, making it easier for other modules to integrate with WeKnora services without having to write HTTP request code directly.
Main Features
The client includes the following main functional modules:
- Session Management: Create, retrieve, update, and delete sessions
- Knowledge Base Management: Create, retrieve, update, and delete knowledge bases
- Knowledge Management: Add, retrieve, and delete knowledge content
- Workspace Management: CRUD operations for workspaces
- Knowledge Q&A: Supports regular Q&A and streaming Q&A
- Chunk Management: Query, update, and delete knowledge chunks
- Message Management: Retrieve and delete session messages
- Model Management: Create, retrieve, update, and delete models
- Evaluation Function: Start evaluation tasks and get evaluation results
- Sandbox skills: Install a skill onto a sandbox config (zip upload, or ClawHub / SkillHub / GitHub source) and configure the environment variables it needs
- Long-term memory: The caller's cross-session memories (settings, items, confirm/reject, topics, document affinity, export, consolidate)
- Auth: Login, refresh tokens, and switch the active workspace (
SwitchTenantrecords the last-active-tenant preference)
Usage
Creating Client Instance
import (
"context"
"github.com/Tencent/WeKnora/client"
"time"
)
// Create client instance
apiClient := client.NewClient(
"http://api.example.com",
client.WithToken("your-auth-token"),
client.WithTimeout(30*time.Second),
)
Workspace Configuration
You can set a default workspace with WithTenantID; the client will automatically send the X-Tenant-ID header:
tenantID := uint64(10000)
apiClient := client.NewClient(
"http://api.example.com",
client.WithToken("your-auth-token"),
client.WithTenantID(tenantID),
)
If a single request needs a different workspace, set TenantID in the request context. The value can be a uint64, *uint64, or a numeric string, and it will take precedence over the client default:
ctx := context.WithValue(context.Background(), "TenantID", uint64(10000))
// Pass ctx into any client method to switch to workspace 10000 for that request
Example: Create Knowledge Base and Upload File
// Create knowledge base
kb := &client.KnowledgeBase{
Name: "Test Knowledge Base",
Description: "This is a test knowledge base",
ChunkingConfig: client.ChunkingConfig{
ChunkSize: 500,
ChunkOverlap: 50,
Separators: []string{"\n\n", "\n", ". ", "? ", "! "},
},
ImageProcessingConfig: client.ImageProcessingConfig{
ModelID: "image_model_id",
},
EmbeddingModelID: "embedding_model_id",
SummaryModelID: "summary_model_id",
}
kb, err := apiClient.CreateKnowledgeBase(context.Background(), kb)
if err != nil {
// Handle error
}
// Upload knowledge file with metadata
metadata := map[string]string{
"source": "local",
"type": "document",
}
knowledge, err := apiClient.CreateKnowledgeFromFile(context.Background(), kb.ID, "path/to/file.pdf", metadata)
if err != nil {
// Handle error
}
// Download original files from one knowledge base as a ZIP (max 200 IDs, 512 MiB)
err = apiClient.DownloadKnowledgeFiles(context.Background(), kb.ID, []string{knowledge.ID}, "knowledge-files.zip")
if err != nil {
// Handle error
}
Example: Create Session and Chat
// Create session
sessionRequest := &client.CreateSessionRequest{
KnowledgeBaseID: knowledgeBaseID,
SessionStrategy: &client.SessionStrategy{
MaxRounds: 10,
EnableRewrite: true,
FallbackStrategy: "fixed_answer",
FallbackResponse: "Sorry, I cannot answer this question",
EmbeddingTopK: 5,
KeywordThreshold: 0.5,
VectorThreshold: 0.7,
RerankModelID: "rerank_model_id",
RerankTopK: 3,
RerankThreshold: 0.8,
SummaryModelID: "summary_model_id",
},
}
session, err := apiClient.CreateSession(context.Background(), sessionRequest)
if err != nil {
// Handle error
}
// Regular Q&A
answer, err := apiClient.KnowledgeQA(context.Background(), session.ID, &client.KnowledgeQARequest{
Query: "What is artificial intelligence?",
})
if err != nil {
// Handle error
}
// Streaming Q&A
err = apiClient.KnowledgeQAStream(context.Background(), session.ID, "What is machine learning?", func(response *client.StreamResponse) error {
// Handle each response chunk
fmt.Print(response.Content)
return nil
})
if err != nil {
// Handle error
}
Example: Managing Models
// Create model
modelRequest := &client.CreateModelRequest{
Name: "Test Model",
Type: client.ModelTypeChat,
Source: client.ModelSourceInternal,
Description: "This is a test model",
Parameters: client.ModelParameters{
"temperature": 0.7,
"top_p": 0.9,
},
IsDefault: true,
}
model, err := apiClient.CreateModel(context.Background(), modelRequest)
if err != nil {
// Handle error
}
// List all models
models, err := apiClient.ListModels(context.Background())
if err != nil {
// Handle error
}
Example: Managing Knowledge Chunks
// List knowledge chunks
chunks, total, err := apiClient.ListKnowledgeChunks(context.Background(), knowledgeID, 1, 10)
if err != nil {
// Handle error
}
// Update chunk
updateRequest := &client.UpdateChunkRequest{
Content: "Updated chunk content",
IsEnabled: true,
}
updatedChunk, err := apiClient.UpdateChunk(context.Background(), knowledgeID, chunkID, updateRequest)
if err != nil {
// Handle error
}
Example: Getting Session Messages
// Get recent messages
messages, err := apiClient.GetRecentMessages(context.Background(), sessionID, 10)
if err != nil {
// Handle error
}
// Get messages before a specific time
beforeTime := time.Now().Add(-24 * time.Hour)
olderMessages, err := apiClient.GetMessagesBefore(context.Background(), sessionID, beforeTime, 10)
if err != nil {
// Handle error
}
Example: Install a sandbox skill from a registry
source must be explicit: @owner/slug for ClawHub, a full https://clawhub.ai/skills-sh/owner/repo/slug (or skills-sh:owner/repo/slug) for federated skills.sh listings, or a full GitHub / SkillHub URL. Bare owner/slug is rejected.
skillID, err := apiClient.InstallSandboxSkillFromSource(
context.Background(), sandboxConfigID, "@owner/slug")
if err != nil {
// Handle error
}
_ = skillID // follow /sandbox-configs/{id}/skills/{skillID}/install-events
Example: Stop a stuck install
After a process restart the row may sit at installing with nothing running, which hides retry and uninstall. Stop rewrites the row immediately (and cancels the in-process goroutine if one is still alive). Then retry or uninstall as usual.
skill, err := apiClient.StopSandboxSkill(context.Background(), sandboxConfigID, skillID)
if err != nil {
// Handle error
}
_ = skill
Example: Retry a failed install
Installs usually fail for reasons the bundle cannot fix — an unreachable sandbox, a package index that timed out. The server still holds the archive, so the retry needs nothing from you.
skillID, err := apiClient.ReinstallSandboxSkill(context.Background(), sandboxConfigID, skillID)
if err != nil {
// Handle error
}
Example: Browse files of an installed skill
files, err := apiClient.ListSandboxSkillFiles(context.Background(), sandboxConfigID, skillID)
if err != nil {
// Handle error
}
content, err := apiClient.GetSandboxSkillFile(context.Background(), sandboxConfigID, skillID, "SKILL.md")
if err != nil {
// Handle error
}
_ = files
_ = content
Example: Configure a skill's environment variables
A skill declares the environment variables it needs when it is installed. Values live in two layers: a workspace value an admin sets for everybody, and a per-identity value that overrides it for the caller alone. No endpoint reads a stored value back; they only report whether one is set.
An API key and a web login are different identities: a personal value entered through the web UI does not apply to runs driven by an API key. Prefer workspace values for integrations.
// Workspace-wide, applies to everybody; requires Admin or above
skill, err := apiClient.SetSandboxSkillEnvValues(
context.Background(), sandboxConfigID, skillID,
map[string]string{"TAVILY_API_KEY": "tvly-xxxxx"})
if err != nil {
// Handle error
}
// Applies to the calling identity alone
err = apiClient.SetMySkillEnvVar(
context.Background(), skillID, "TAVILY_API_KEY", "tvly-yyyyy")
if err != nil {
// Handle error
}
// See what is still unset. Clearing a value is a delete, not a write of ""
groups, err := apiClient.ListMyEnvVars(context.Background())
if err != nil {
// Handle error
}
_ = skill
_ = groups
Complete Example
Please refer to the ExampleUsage function in the example.go file, which demonstrates the complete usage flow of the client.