docs: 迁移有效文档至 website-docs 并清理旧文档 (#3580)

* docs: consolidate maintained documentation in website-docs

* docs: remove migrated legacy documentation and update remaining references
main
lyingbug 2026-09-22 23:25:40 +08:00 committed by GitHub
parent fbf9f54b6a
commit 63ef76dd80
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
142 changed files with 800 additions and 22083 deletions

View File

@ -358,7 +358,7 @@ OLLAMA_BASE_URL=http://host.docker.internal:11434
# ========== D2. 内置模型声明式配置(可选)==========
# 启用 config/builtin_models.yaml(见 config/builtin_models.yaml.example)后,YAML 中的
# ${NAME} 占位符会在应用启动期从这里读取真实值。变量名由 YAML 自定,下面给出常见命名参考。
# 详见 docs/BUILTIN_MODELS.md。
# 详见 website-docs/03-features/06-models.md。
#
# 内置对话模型
# LLM_MODEL_NAME=
@ -665,7 +665,7 @@ WEKNORA_SANDBOX_DOCKER_ENABLED=false
# #####################################################################
# ========== I1. Langfuse 接入(追踪 chat/embedding/rerank/VLM/ASR 模型调用,统计 token 消耗)==========
# 详细说明:docs/Langfuse集成.md
# 详细说明:website-docs/03-features/16-observability.md
#
# 方案 A:接入 Langfuse Cloud(最简单)
# 1) 登录 https://cloud.langfuse.com 生成 API Key
@ -777,7 +777,7 @@ LANGFUSE_HOST=http://langfuse-web:3000
CONCURRENCY_POOL_SIZE=5
# ========== J3. BrowserSkill 本机浏览器(可选) ==========
# 用户通过 Chrome 扩展连接;部署与限制见 docs/browser-skill-integration.md。
# 用户通过 Chrome 扩展连接;部署与限制见 website-docs/05-clients/09-local-browser.md。
# Docker app 镜像已内置 bsk 和配套扩展,默认从用户当前页面自动生成连接地址,无需配置 PUBLIC_URL。
# 原生部署还需构建产物并配置下面两个文件路径;显式设置 BROWSERSKILL_BINARY= 可关闭此功能。
# 后端所在系统/架构的官方 bsk 可执行文件绝对路径(Docker 已预设,不必重复配置)。

View File

@ -50,7 +50,7 @@ DISABLE_REGISTRATION=false
# === Langfuse 可观测性(可选) ===
# 追踪 chat / embedding / rerank / VLM / ASR 的 prompt、响应与 token 消耗。
# 同时填了 PUBLIC_KEY 和 SECRET_KEY 就会自动启用,详见 docs/Langfuse集成.md。
# 同时填了 PUBLIC_KEY 和 SECRET_KEY 就会自动启用,详见 website-docs/03-features/16-observability.md。
# LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxx
# LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxx
# LANGFUSE_HOST=https://cloud.langfuse.com

View File

@ -1,7 +1,7 @@
blank_issues_enabled: false
contact_links:
- name: WeKnora Documentation
url: https://github.com/Tencent/WeKnora/blob/main/docs/QA.md
url: https://github.com/Tencent/WeKnora/blob/main/website-docs/01-getting-started/05-troubleshooting.md
about: Check WeKnora FAQ
- name: Discussions
url: https://github.com/Tencent/WeKnora/discussions

View File

@ -35,7 +35,7 @@ exact command and failure here.
- [ ] Full-repository checks were run, or any unrelated/environment-dependent failures are documented above
- [ ] Self-reviewed the code
- [ ] Added/updated tests covering the change
- [ ] Updated related documentation (README, `docs/`, Swagger annotations, etc.)
- [ ] Updated related documentation (README, `website-docs/`, Swagger annotations, etc.)
- [ ] Breaking changes are clearly called out in the description above
## Screenshots / Recordings

View File

@ -14,7 +14,7 @@ All notable changes to this project will be documented in this file.
### New Features
- **NEW**: **Skill Sandbox Runtime (Docker / E2B / Cube)** — the headline of this release. Agent skills now run in a **session-persistent sandbox**: one sandbox per chat session, with `shell_exec`, file read/write/edit, attachment staging, and generated-file collection all landing in the same workspace. Three backends share one `RemoteSandboxClient` protocol: **Docker** (single-host / self-hosted, talking to the Engine API rather than `docker run --rm`), **E2B** (cloud or any E2B-compatible control plane, including self-hosted), and **CubeSandbox**. Per-workspace configs cover image, CPU/memory, TTL, DNS, templates and snapshots (migrations `000082_tenant_sandbox_config`, `000083_session_sandbox_config`). Admins can set a **network policy** per config (default-deny egress, allow/deny lists, Cube L7 rules, E2B host rules) (#2995). The old **Local host-process backend is removed**. The Docker backend is **opt-in** (`WEKNORA_SANDBOX_DOCKER_ENABLED` or System Settings → Network Security) because a mounted `docker.sock` is host root (#2936). See [`docs/sandbox-docker-backend.md`](./docs/sandbox-docker-backend.md) and [`docs/sandbox-protocol.md`](./docs/sandbox-protocol.md).
- **NEW**: **Skill Sandbox Runtime (Docker / E2B / Cube)** — the headline of this release. Agent skills now run in a **session-persistent sandbox**: one sandbox per chat session, with `shell_exec`, file read/write/edit, attachment staging, and generated-file collection all landing in the same workspace. Three backends share one `RemoteSandboxClient` protocol: **Docker** (single-host / self-hosted, talking to the Engine API rather than `docker run --rm`), **E2B** (cloud or any E2B-compatible control plane, including self-hosted), and **CubeSandbox**. Per-workspace configs cover image, CPU/memory, TTL, DNS, templates and snapshots (migrations `000082_tenant_sandbox_config`, `000083_session_sandbox_config`). Admins can set a **network policy** per config (default-deny egress, allow/deny lists, Cube L7 rules, E2B host rules) (#2995). The old **Local host-process backend is removed**. The Docker backend is **opt-in** (`WEKNORA_SANDBOX_DOCKER_ENABLED` or System Settings → Network Security) because a mounted `docker.sock` is host root (#2936). See [`docs/sandbox-docker-backend.md`](./website-docs/06-development/04-sandbox-deployment.md) and [`docs/sandbox-protocol.md`](./website-docs/06-development/04-sandbox-deployment.md).
- **NEW**: **Tenant Skill Catalog** — skills are first-class workspace resources, not files dropped next to the process (migrations `000086_tenant_skills`, `000087_skill_install_transcript`, `000088_skill_snapshot_planned_name`, `000090_skill_catalog`). Install from **ClawHub**, **SkillHub / skills.sh**, **GitHub/GitLab URLs**, or a zip upload; each install is a snapshot on the chosen sandbox config, with live circular progress, install transcripts, stop/reinstall, and uninstall that keeps catalog archives. Browse and edit installed skill files from Settings; agents get `write_skill_file` / `edit_skill_file` plus `shell_exec` that no longer requires a skill to be installed. Personal and workspace **skill env vars** inject at execution without ever being read back (migration `000089_env_vars`). `@mention` no longer silently shrinks the skill whitelist.
- **NEW**: **Cross-Session Long-Term Memory** — a new memory product (migration `000084_memory`), independent of the Neo4j conversation-memory that 0.7.1 removed. Workspaces opt in; each user can further turn it off. Memories are typed (`profile` / `preference` / `fact` / `task` / `interest`), written either explicitly or by a background extractor, and **inferred items stay pending until the user confirms**. Resident profile/preference blocks ride in every turn; situational facts are recalled lexically and (optionally) semantically; `search_memory` looks up on demand. Document affinity conditions retrieval toward sources the user keeps citing. Settings, items, topics, document affinity, confirm/reject, export and forced consolidation are exposed as `/api/v1/memory/*` (full-access API keys only; the subject is always the caller).
- **NEW**: **In-Process anydoc Parser** — Office documents (doc/docx/ppt/pptx and the types anydoc converts) can be parsed **inside the Go app** via `third_party/anydoc-go`, without a round-trip to docreader. When the binding is linked, anydoc is preferred for every type it converts; PPT/PPTX still default to MarkItDown when no engine rule is set. The app image links anydoc by default.
@ -88,7 +88,7 @@ All notable changes to this project will be documented in this file.
- **NEW**: **Knowledge Base Folder Tree** — folder uploads no longer smuggle their relative directory into `file_name`. The path now lives in a dedicated `folder_path` column with a backfill for existing rows (migration `000079_knowledge_folder_path`), so the document list renders a real sidebar folder tree that can be browsed like a file manager, folders can be renamed in place, and documents can be re-filed into another folder. Individually uploaded documents get a visible home at the tree root instead of disappearing. Adds `GET /knowledge-bases/{id}/knowledge/folders` and `PUT /knowledge-bases/{id}/knowledge/folders`, plus a folder picker popup on each row.
- **NEW**: **Editable Chunks, Revision History & Custom Metadata** — retrieval chunks are now editable directly from the UI, with every superseded version snapshotted for diff and one-click revert, and the index rebuilt automatically after an edit (migration `000078_chunk_editing_and_custom_metadata` adds `chunks.source_content` / `content_revision` / `index_status` / `last_editor_id` / `context_header`, the `chunk_revisions` table, and `knowledges.custom_metadata`). Generated questions can be added, edited, deleted, and regenerated per chunk, and survive content edits. Adds `PUT /chunks/{knowledge_id}/{id}`, `GET /chunks/{knowledge_id}/{id}/revisions`, `POST /chunks/{knowledge_id}/{id}/revert`, and the generated-question endpoints. Chunk details moved into header popups for a tighter layout.
- **NEW**: **Wiki Page Revision History, Diff & Manual Editing** — every wiki page version is preserved before being overwritten (migration `000075_wiki_page_revisions`, plus `wiki_pages.last_edit_source` / `last_editor_id` recording whether the current version came from the pipeline, an agent, a user, or a revert). A revision drawer lists the full history with line-level diffs and one-click rollback, and pages can be edited by hand in the browser. The Wiki reader layout, source-document reference handling, and sidebar UX were reworked to match the session-list experience.
- **NEW**: **Directly Loadable File URLs (`resource_urls=public`)** — chat answers, references, knowledge search, and embed responses can return ready-to-load http(s) URLs for files and images instead of internal `resource://` handles, so third-party apps no longer need a second authenticated call to the `/files` proxy. Opt in per request with `?resource_urls=public` or per deployment with `RESOURCE_URL_MODE=public`. A new `internal/storageurl` package centralizes the rewriting, reusing a live access grant per resource to keep read endpoints from writing on every request. Anonymous embed channels and KB-restricted API keys always stay on `handle`. See [`docs/api/README.md`](./docs/api/README.md).
- **NEW**: **Directly Loadable File URLs (`resource_urls=public`)** — chat answers, references, knowledge search, and embed responses can return ready-to-load http(s) URLs for files and images instead of internal `resource://` handles, so third-party apps no longer need a second authenticated call to the `/files` proxy. Opt in per request with `?resource_urls=public` or per deployment with `RESOURCE_URL_MODE=public`. A new `internal/storageurl` package centralizes the rewriting, reusing a live access grant per resource to keep read endpoints from writing on every request. Anonymous embed channels and KB-restricted API keys always stay on `handle`. See [`docs/api/README.md`](./website-docs/04-api/01-api-overview.md).
- **NEW**: **Feishu Drive Data Source** — a new Feishu Cloud Drive connector joins the existing Feishu wiki connector (#2466). New-format Feishu cloud documents (docx) are now synchronized through the blocks API with per-block-type drill-down (#2087), configurable via the new `E9` docx parsing-mode section in `.env.example`.
- **NEW**: **Batch Document Tagging** — select documents in the knowledge base list and apply tags in bulk through a dedicated dialog that pre-selects the tags already common to the selection.
- **NEW**: **MCP Server 1.1.x** — the WeKnora MCP server migrated from the removed low-level `Server` decorator API to the high-level `MCPServer` API (mcp 2.x), restoring HTTP (`stateless_http`) and SSE (`/sse/messages/`) transport compatibility, and now publishes as the official PyPI package **`tencent-weknora-mcp`** via Trusted Publishing. Two new tools bring the total to 29: `create_knowledge_from_text` (create a knowledge entry from Markdown text) and `list_shared_knowledge_bases` (shared KBs are also folded into name resolution and tool hints).
@ -196,8 +196,8 @@ All notable changes to this project will be documented in this file.
### 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**: **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`](./website-docs/02-architecture/05-async-tasks.md#capacity-planning).
- **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`](./website-docs/04-api/02-api-infra.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.
@ -254,7 +254,7 @@ All notable changes to this project will be documented in this file.
### New Features
- **NEW**: **Website Embed Widget & Channels** — the headline of this release. Publish custom agents to external websites via embed channels with domain allowlists, per-minute / per-day rate limiting, and secure-mode token exchange (`em_…` publish token → short-lived `ems_…` session token). Ships `weknora-widget.js`, a standalone embed chat UI, visitor session management, and a unified **Integrations Center** for IM + embed channel editors with agent rebind and live preview. See [`docs/embed-secure-mode.md`](./docs/embed-secure-mode.md) and [`docs/embed-subdomain.md`](./docs/embed-subdomain.md).
- **NEW**: **Website Embed Widget & Channels** — the headline of this release. Publish custom agents to external websites via embed channels with domain allowlists, per-minute / per-day rate limiting, and secure-mode token exchange (`em_…` publish token → short-lived `ems_…` session token). Ships `weknora-widget.js`, a standalone embed chat UI, visitor session management, and a unified **Integrations Center** for IM + embed channel editors with agent rebind and live preview. See [`docs/embed-secure-mode.md`](./website-docs/03-features/13-embed-channel.md) and [`docs/embed-subdomain.md`](./website-docs/03-features/13-embed-channel.md#embed-subdomain).
- **NEW**: **Chat Experience Overhaul** — unified markdown rendering pipeline with citation popovers, chunk caching, shared resource chips, and `@` mention browsing of recent files; RAG pipeline progress events surfaced in a dedicated timeline component; agent stream display refactor with tool-result rendering, thinking blocks, shimmer streaming tail, and typewriter effect; large tool outputs trimmed via agent-side persistence.
- **NEW**: **Document Multi-Tag** — documents can carry multiple tags (`knowledge_tag_ids` many-to-many via migration `000063_knowledge_multi_tags`); tag manage drawer, redesigned tag chips / edit dialog, and unified document tag filter in the KB list.
- **NEW**: **Batch Document Reparse** — `POST /knowledge/batch-reparse` re-queues parsing for multiple documents with optional `process_config`; async task UI refreshes after enqueue.
@ -462,7 +462,7 @@ All notable changes to this project will be documented in this file.
- **Per-KB resource ownership**: `chunk → knowledge → kb → creator_id`; same chain applies to FAQ entries, generated questions, KB tags and wiki pages. `custom_agents.creator_id` + `custom_agents.runnable_by_viewer` (default true) control agent ownership and viewer-callability.
- **Two guard families**: role guards (`Viewer()` / `Contributor()` / `Admin()` / `Owner()`) for tenant-level infra (models, vector stores, IM channels, …) and ownership guards (`OwnedKBOrAdmin()`, `OwnedAgentOrAdmin()`, `OwnedChunkKBOrAdmin()`, …) for resource writes. KB-access guard wired at the route layer for chunk / knowledge / knowledgebase routes (no per-handler helpers).
- **Tenant members**: invite / remove / role-change endpoints; new `/leave` endpoint; per-tenant audit log with daily retention sweep (default 90 days, `audit_logs.created_at` indexed); `tenant_members` table now drives membership (lifted from per-user to per-tenant in Plan 3); cross-tenant share managed by source-tenant Admin+.
- **Configurable**: `tenant.enable_rbac` (default `true`); `false` enters an "audit-only" grace window. New env knobs `WEKNORA_TENANT_ENABLE_RBAC`, `WEKNORA_TENANT_MAX_PER_USER`. RBAC state logged at startup. See [`docs/RBAC说明.md`](./docs/RBAC说明.md).
- **Configurable**: `tenant.enable_rbac` (default `true`); `false` enters an "audit-only" grace window. New env knobs `WEKNORA_TENANT_ENABLE_RBAC`, `WEKNORA_TENANT_MAX_PER_USER`. RBAC state logged at startup. See [`docs/RBAC说明.md`](./website-docs/03-features/01-tenant-auth.md).
- **NEW**: **Tenant Member Management & Multi-Workspace UX** — invite-only gate, member listing UI with role chips, tenant identity surfaces reworked; tenant switcher in the user menu; tenant switch always redirects to KB list and clears tenant-scoped client state; last-active workspace persisted across logins; pending invitations dialog with polling + global invitation bell; rich workspace-aware notifications on login / tenant switch (raw-message handling, styled chips, survives page reload); QuickNav entry for members; "leave workspace" surfaced in i18n.
- **NEW**: **Self-Service Workspaces** — any user can create their own tenant (capped per user via env knob); creation dialog with i18n; tenant name + description editable inline; cross-tenant superuser mirrored as Admin role chip in the UI.
- **NEW**: **`weknora` CLI v0.3 / v0.4 (GA)** — graduates from preview to GA with comprehensive verb-noun subtree coverage:

View File

@ -71,7 +71,7 @@ The framework supports auto-syncing knowledge from Feishu, GitLab, Tencent IMA,
- **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** — 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.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 [`website-docs/03-features/01-tenant-auth.md`](./website-docs/03-features/01-tenant-auth.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; 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.
@ -303,11 +303,11 @@ WeKnora serves as the core technology framework for the [WeChat Dialog Open Plat
**Official website and product documentation**: [`website-docs/`](./website-docs/README.md) contains the product homepage and the complete documentation set organized as Getting Started → Architecture → Features → API → Clients → Development. With Node.js 24, run `cd website-docs && npm run setup && npm run build && npm run preview` to preview both together. The unified static output serves the homepage at `/` and documentation at `/docs/`; see the directory's README for Nginx and Docker deployment.
Troubleshooting FAQ: [Troubleshooting FAQ](./docs/QA.md)
Troubleshooting FAQ: [Troubleshooting FAQ](./website-docs/01-getting-started/05-troubleshooting.md)
Detailed API documentation is available at: [API Docs](./docs/api/README.md)
Detailed API documentation is available at: [API Docs](./website-docs/04-api/01-api-overview.md)
Product plans and upcoming features: [Roadmap](./docs/ROADMAP.md)
Product capabilities: [Introduction](./website-docs/01-getting-started/01-introduction.md)
## 🧭 Developer Guide
@ -332,7 +332,7 @@ make dev-frontend
- ✅ No need to rebuild Docker images
- ✅ Support IDE breakpoint debugging
**Detailed Documentation:** [Development Environment Quick Start](./docs/开发指南.md)
**Detailed Documentation:** [Development Environment Quick Start](./website-docs/06-development/01-dev-guide.md)
## 🤝 Contributing

View File

@ -70,7 +70,7 @@ https://github.com/user-attachments/assets/2819598d-3140-4623-814a-8162a22b653c
- **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。详见 [`website-docs/03-features/01-tenant-auth.md`](./website-docs/03-features/01-tenant-auth.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.0** —— Wiki 模式正式版 —— Agent 从原始文档自治生成结构化、相互链接的 Markdown Wiki 页面及知识图谱;Wiki 浏览器 + 可视化图谱。
@ -266,7 +266,7 @@ docker compose up -d # 用新镜像重建容器
WeKnora 支持将文档转化为知识图谱,展示文档中不同段落之间的关联关系。开启知识图谱功能后,系统会分析并构建文档内部的语义关联网络,不仅帮助用户理解文档内容,还为索引和检索提供结构化支撑,提升检索结果的相关性和广度。
具体配置请参考 [知识图谱配置说明](./docs/KnowledgeGraph.md) 进行相关配置。
具体配置请参考 [知识图谱配置说明](./website-docs/03-features/09-knowledge-graph.md) 进行相关配置。
## 配套MCP服务器
@ -285,11 +285,11 @@ WeKnora 作为[微信对话开放平台](https://chatbot.weixin.qq.com)的核心
**官方产品文档**:[`website-docs/`](./website-docs/README.md) —— 按「入门 → 架构 → 功能 → API → 客户端 → 开发」六个板块组织的完整文档,覆盖约 360 个 API 端点、约 150 个环境变量与 9 大扩展点。本目录同时是一个 VitePress 站点,`cd website-docs && npm install && npm run dev` 即可本地预览,也可用目录内的 `Dockerfile` 独立部署。
常见问题排查:[常见问题排查](./docs/QA.md)
常见问题排查:[常见问题排查](./website-docs/01-getting-started/05-troubleshooting.md)
详细接口说明请参考:[API 文档](./docs/api/README.md)
详细接口说明请参考:[API 文档](./website-docs/04-api/01-api-overview.md)
产品规划与计划:[路线图 (Roadmap)](./docs/ROADMAP.md)
产品能力:[产品介绍](./website-docs/01-getting-started/01-introduction.md)
## 🧭 开发指南
@ -315,7 +315,7 @@ make dev-frontend
- ✅ 无需重新构建 Docker 镜像
- ✅ 支持 IDE 断点调试
**详细文档:** [开发环境快速入门](./docs/开发指南.md)
**详细文档:** [开发环境快速入门](./website-docs/06-development/01-dev-guide.md)
## 🤝 贡献指南

View File

@ -66,7 +66,7 @@ Feishu、GitLab、Tencent IMA、Notion、Yuqueなどの外部プラットフォ
- **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) を参照。
- **v0.6.0** — テナント RBAC(4 階層ロールマトリクス `Owner` / `Admin` / `Contributor` / `Viewer` + KB 単位の所有 + テナントごとの監査ログ)、テナントメンバー管理とマルチワークスペース UX、セルフサービスでのワークスペース作成;`weknora` CLI v0.4 GA + `mcp serve`;KB 検索の複数ベクター DB ファンアウト;MCP / データソース資格情報の AES-256-GCM 暗号化 + docreader gRPC TLS + Token;Zhipu Embedder と華為雲 OBS の追加;サーバーサイドユーザー設定;Go 1.26.0。詳細は [`docs/RBAC说明.md`](./docs/RBAC说明.md) と [`CHANGELOG.md`](./CHANGELOG.md) を参照。
- **v0.6.0** — テナント RBAC(4 階層ロールマトリクス `Owner` / `Admin` / `Contributor` / `Viewer` + KB 単位の所有 + テナントごとの監査ログ)、テナントメンバー管理とマルチワークスペース UX、セルフサービスでのワークスペース作成;`weknora` CLI v0.4 GA + `mcp serve`;KB 検索の複数ベクター DB ファンアウト;MCP / データソース資格情報の AES-256-GCM 暗号化 + docreader gRPC TLS + Token;Zhipu Embedder と華為雲 OBS の追加;サーバーサイドユーザー設定;Go 1.26.0。詳細は [`website-docs/03-features/01-tenant-auth.md`](./website-docs/03-features/01-tenant-auth.md) と [`CHANGELOG.md`](./CHANGELOG.md) を参照。
- **v0.5.2** — Wiki インジェストが万件規模 KB に対応(タスクキュー + DLQ);MCP 工具人機審批;Anthropic / Apache Doris / Tencent VectorDB / 金山雲 KS3 / SearXNG バックエンド;適応型 3 段階チャンキング + ライブプレビュー;グローバル ⌘K コマンドパレット;Yuque コネクタ + WeChat ミニプログラム;`weknora` CLI プレビュー版。
- **v0.5.1** — KB 一括管理;テナント全体の IM チャネル概観;セッション検索 + ユーザー単位ピン留め;モデル / Web 検索 / MCP 統一カード設定;Agent ごとの LLM タイムアウト;デスクトップ版テナント切替。
- **v0.5.0** — Wiki モード GA — Agent が原文書から構造化・相互リンクされた Markdown Wiki ページとナレッジグラフを自動生成、Wiki ブラウザと可視化グラフを UI に搭載。
@ -255,7 +255,7 @@ docker compose up -d # 新しいイメージでコンテナを再作成
WeKnoraは文書をナレッジグラフに変換し、文書内の異なる段落間の関連関係を表示することをサポートします。ナレッジグラフ機能を有効にすると、システムは文書内部の意味関連ネットワークを分析・構築し、ユーザーが文書内容を理解するのを助けるだけでなく、インデックスと検索に構造化サポートを提供し、検索結果の関連性と幅を向上させます。
詳細な設定については、[ナレッジグラフ設定ガイド](./docs/KnowledgeGraph.md)をご参照ください。
詳細な設定については、[ナレッジグラフ設定ガイド](./website-docs/03-features/09-knowledge-graph.md)をご参照ください。
## 対応するMCPサーバー
@ -275,11 +275,11 @@ WeKnoraは[WeChat対話オープンプラットフォーム](https://chatbot.wei
**公式製品ドキュメント**:[`website-docs/`](./website-docs/README.md) — 「入門 → アーキテクチャ → 機能 → API → クライアント → 開発」の 6 セクションで構成された完全なドキュメントセット。約 360 の API エンドポイント、約 150 の環境変数、9 つの拡張ポイントを網羅しています。このディレクトリは VitePress サイトでもあり、`cd website-docs && npm install && npm run dev` でローカルプレビュー、同ディレクトリの `Dockerfile` で単独デプロイも可能です。
よくある問題の解決:[よくある問題](./docs/QA.md)
よくある問題の解決:[よくある問題](./website-docs/01-getting-started/05-troubleshooting.md)
詳細なAPIドキュメントは:[APIドキュメント](./docs/api/README.md)を参照してください
詳細なAPIドキュメントは:[APIドキュメント](./website-docs/04-api/01-api-overview.md)を参照してください
製品計画と今後の機能:[Roadmap](./docs/ROADMAP.md)
製品の機能:[製品紹介](./website-docs/01-getting-started/01-introduction.md)
## 🧭 開発ガイド
@ -304,7 +304,7 @@ make dev-frontend
- ✅ Dockerイメージを再構築する必要がない
- ✅ IDEブレークポイントデバッグをサポート
**詳細ドキュメント:** [開発環境クイックスタート](./docs/开发指南.md)
**詳細ドキュメント:** [開発環境クイックスタート](./website-docs/06-development/01-dev-guide.md)
## 🤝 貢献ガイド

View File

@ -66,7 +66,7 @@ Feishu, GitLab, Tencent IMA, Notion, Yuque 등 외부 플랫폼에서 지식 자
- **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) 참고.
- **v0.6.0** — 테넌트 RBAC(4단계 역할 매트릭스 `Owner` / `Admin` / `Contributor` / `Viewer` + KB 단위 소유 + 테넌트별 감사 로그), 테넌트 멤버 관리와 멀티 워크스페이스 UX, 셀프 서비스 워크스페이스 생성; `weknora` CLI v0.4 GA + `mcp serve`; 여러 벡터 저장소에 걸친 KB 검색 팬아웃; MCP / 데이터 소스 자격 증명 AES-256-GCM 암호화 + docreader gRPC TLS + Token; Zhipu 임베더와 화웨이 클라우드 OBS 추가; 서버 사이드 사용자 환경설정; Go 1.26.0. 자세한 내용은 [`docs/RBAC说明.md`](./docs/RBAC说明.md)과 [`CHANGELOG.md`](./CHANGELOG.md) 참고.
- **v0.6.0** — 테넌트 RBAC(4단계 역할 매트릭스 `Owner` / `Admin` / `Contributor` / `Viewer` + KB 단위 소유 + 테넌트별 감사 로그), 테넌트 멤버 관리와 멀티 워크스페이스 UX, 셀프 서비스 워크스페이스 생성; `weknora` CLI v0.4 GA + `mcp serve`; 여러 벡터 저장소에 걸친 KB 검색 팬아웃; MCP / 데이터 소스 자격 증명 AES-256-GCM 암호화 + docreader gRPC TLS + Token; Zhipu 임베더와 화웨이 클라우드 OBS 추가; 서버 사이드 사용자 환경설정; Go 1.26.0. 자세한 내용은 [`website-docs/03-features/01-tenant-auth.md`](./website-docs/03-features/01-tenant-auth.md)과 [`CHANGELOG.md`](./CHANGELOG.md) 참고.
- **v0.5.2** — Wiki 인제스트가 만 건 규모 KB 지원(작업 큐 + DLQ); MCP 휴먼인더루프 도구 승인; Anthropic / Apache Doris / Tencent VectorDB / Kingsoft Cloud KS3 / SearXNG 백엔드; 적응형 3단계 청킹 + 라이브 미리보기; 글로벌 ⌘K 명령 팔레트; Yuque 커넥터 + WeChat 미니프로그램; `weknora` CLI 프리뷰.
- **v0.5.1** — 지식베이스 일괄 관리; 테넌트 전체 IM 채널 개요; 세션 검색 + 사용자 단위 핀; 모델 / 웹 검색 / MCP 통일 카드 설정; Agent별 LLM 타임아웃; 데스크탑 테넌트 전환.
- **v0.5.0** — Wiki 모드 GA — Agent가 원본 문서에서 구조화·상호 연결된 Markdown Wiki 페이지와 지식 그래프 자동 생성, Wiki 브라우저 및 시각화 그래프를 UI에 탑재.
@ -265,7 +265,7 @@ docker compose up -d # 새 이미지로 컨테이너 재생성
WeKnora는 문서를 지식 그래프로 변환해 문서 내 서로 다른 섹션 간 관계를 시각화할 수 있습니다. 지식 그래프 기능을 활성화하면 문서 내부의 시맨틱 연관 네트워크를 분석/구성하여 문서 이해를 돕고, 인덱싱과 검색에 구조화된 지원을 제공해 검색 결과의 관련성과 폭을 향상시킵니다.
자세한 설정은 [지식 그래프 설정 가이드](./docs/KnowledgeGraph.md)를 참고하세요.
자세한 설정은 [지식 그래프 설정 가이드](./website-docs/03-features/09-knowledge-graph.md)를 참고하세요.
## MCP 서버
@ -284,11 +284,11 @@ WeKnora는 [WeChat 대화 오픈 플랫폼](https://chatbot.weixin.qq.com)의
**공식 제품 문서**: [`website-docs/`](./website-docs/README.md) — 「입문 → 아키텍처 → 기능 → API → 클라이언트 → 개발」 6개 섹션으로 구성된 완전한 문서 세트로, 약 360개 API 엔드포인트, 약 150개 환경 변수, 9개 확장 지점을 다룹니다. 이 디렉터리는 VitePress 사이트이기도 하여 `cd website-docs && npm install && npm run dev`로 로컬 미리보기가 가능하며, 디렉터리 내 `Dockerfile`로 단독 배포할 수도 있습니다.
문제 해결 FAQ: [문제 해결 FAQ](./docs/QA.md)
문제 해결 FAQ: [문제 해결 FAQ](./website-docs/01-getting-started/05-troubleshooting.md)
상세 API 문서: [API Docs](./docs/api/README.md)
상세 API 문서: [API Docs](./website-docs/04-api/01-api-overview.md)
제품 계획 및 예정 기능: [Roadmap](./docs/ROADMAP.md)
제품 기능: [제품 소개](./website-docs/01-getting-started/01-introduction.md)
## 🧭 개발자 가이드
@ -313,7 +313,7 @@ make dev-frontend
- ✅ Docker 이미지 재빌드 불필요
- ✅ IDE 브레이크포인트 디버깅 지원
**상세 문서:** [개발 환경 빠른 시작](./docs/开发指南.md)
**상세 문서:** [개발 환경 빠른 시작](./website-docs/06-development/01-dev-guide.md)
## 🤝 기여하기

View File

@ -122,7 +122,7 @@ services:
# OpenSearch k-NN (Phase 3 driver). Single-node dev profile with the
# security plugin disabled → plain HTTP on :9200, no auth/TLS. The image
# bundles the opensearch-knn plugin. For production use a secured,
# multi-node cluster. See docs/dev/opensearch-integration-test.md.
# multi-node cluster. See website-docs/03-features/05-retrieval-engines.md.
opensearch:
image: opensearchproject/opensearch:3.3.2
container_name: WeKnora-opensearch-dev

View File

@ -54,7 +54,7 @@ services:
# - /var/run/docker.sock:/var/run/docker.sock
# Optional: declarative built-in models. Copy config/builtin_models.yaml.example
# to config/builtin_models.yaml, edit it for your deployment, then
# uncomment the line below. See docs/BUILTIN_MODELS.md.
# uncomment the line below. See website-docs/03-features/06-models.md.
# - ./config/builtin_models.yaml:/app/config/builtin_models.yaml:ro
# Optional: model catalog overlay (extra vendors / model overrides).
# Copy config/models.json.example to config/models.json, then
@ -148,7 +148,7 @@ services:
# - DB_PATH=${DB_PATH:-}
# ========== Langfuse (optional observability) ==========
# Enabled automatically when LANGFUSE_PUBLIC_KEY + LANGFUSE_SECRET_KEY are set.
# See docs/Langfuse集成.md for the full list of tuning knobs.
# See website-docs/03-features/16-observability.md for the full list of tuning knobs.
- LANGFUSE_ENABLED=${LANGFUSE_ENABLED:-}
- LANGFUSE_HOST=${LANGFUSE_HOST:-https://cloud.langfuse.com}
- LANGFUSE_PUBLIC_KEY=${LANGFUSE_PUBLIC_KEY:-}
@ -338,7 +338,7 @@ services:
- WEKNORA_AGENT_TOOL_APPROVAL_TIMEOUT=${WEKNORA_AGENT_TOOL_APPROVAL_TIMEOUT:-}
# MCP 工具人工审批失败时是否放行(true 放行 / 默认 fail-close 拒绝)
- WEKNORA_AGENT_TOOL_APPROVAL_FAIL_OPEN=${WEKNORA_AGENT_TOOL_APPROVAL_FAIL_OPEN:-}
# Tenant / RBAC(详见 docs/RBAC说明.md 与 .env.example 注释)
# Tenant / RBAC(详见 website-docs/03-features/01-tenant-auth.md 与 .env.example 注释)
# - WEKNORA_TENANT_ENABLE_RBAC: 是否启用空间角色强制鉴权(true / false),默认 true
# - WEKNORA_TENANT_MAX_OWNED_PER_USER: 单个非超管自助创建空间的上限
# >0 强制限额;=0 走 handler 默认;<0 关闭限额(不建议共享部署使用)

View File

@ -9,7 +9,7 @@
# cube - the same environment plus Cube's envd daemon. Cube
# builds templates straight from the image and probes
# :49983/health, so an image without envd can only ever
# fail. See docs/sandbox-cluster.md.
# fail. See website-docs/06-development/04-sandbox-deployment.md.
# desktop-runtime - runtime plus XFCE / x11vnc / websockify. Not a published
# tag; the desktop and desktop-cube targets sit on it.
# desktop - desktop-runtime, tagged for E2B (and a future Docker

View File

@ -1,144 +0,0 @@
# 内置 MCP 服务管理指南
## 概述
内置 MCP 服务是系统级别的 MCP(Model Context Protocol)服务配置,对所有空间可见,但敏感信息会被隐藏,且不可编辑或删除。内置 MCP 服务通常用于提供系统默认的外部工具和资源接入,确保所有空间都能使用统一的 MCP 服务。
## 内置 MCP 服务特性
- **所有空间可见**:内置 MCP 服务对所有空间都可见,无需单独配置
- **安全保护**:内置 MCP 服务的敏感信息(URL、认证配置、Headers、环境变量)会被隐藏,无法查看详情
- **只读保护**:内置 MCP 服务不能被编辑或删除,仅支持测试连接
- **统一管理**:由系统管理员统一维护,确保配置一致性和安全性
## 与内置模型的对比
| 特性 | 内置模型 | 内置 MCP 服务 |
|------|---------|--------------|
| 标识字段 | `is_builtin` | `is_builtin` |
| 可见范围 | 所有空间 | 所有空间 |
| 隐藏信息 | API Key、Base URL | URL、认证配置、Headers、环境变量 |
| 编辑保护 | 不可编辑/删除 | 不可编辑/删除 |
| 前端标签 | 显示"内置"标签 | 显示"内置"标签 |
| 启停控制 | — | 禁用开关(始终启用) |
## 如何添加内置 MCP 服务
内置 MCP 服务需要通过数据库直接插入。以下是添加内置 MCP 服务的步骤:
### 1. 准备服务数据
首先,确保你已经有了要设置为内置 MCP 服务的配置信息,包括:
- 服务名称(name)
- 服务描述(description)
- 传输方式(transport_type):`sse` 或 `http-streamable`
- 服务地址(url):SSE / HTTP Streamable 必填
- 认证配置(auth_config):可选,包括 api_key、token 等
- 高级配置(advanced_config):可选,包括超时、重试策略等
- 空间ID(tenant_id):建议使用小于 10000 的空间ID,避免冲突
**支持的传输方式**:
- `sse`:Server-Sent Events,推荐用于流式体验
- `http-streamable`:HTTP Streamable,标准 HTTP 兼容
> 注意:出于安全考虑,`stdio` 传输方式在服务端已被禁用。
### 2. 执行 SQL 插入语句
使用以下 SQL 语句插入内置 MCP 服务:
```sql
-- 示例:插入一个 SSE 传输方式的内置 MCP 服务
INSERT INTO mcp_services (
id,
tenant_id,
name,
description,
enabled,
transport_type,
url,
auth_config,
advanced_config,
is_builtin
) VALUES (
'builtin-mcp-001', -- 使用固定ID,建议使用 builtin-mcp- 前缀
10000, -- 空间ID(使用第一个空间)
'Web Search', -- 服务名称
'内置 Web 搜索 MCP 服务', -- 描述
true, -- 启用状态
'sse', -- 传输方式
'https://mcp.example.com/sse', -- 服务地址
'{"api_key": "your-api-key"}'::jsonb, -- 认证配置
'{"timeout": 30, "retry_count": 3, "retry_delay": 1}'::jsonb, -- 高级配置
true -- 标记为内置服务
) ON CONFLICT (id) DO NOTHING;
-- 示例:插入一个 HTTP Streamable 传输方式的内置 MCP 服务
INSERT INTO mcp_services (
id,
tenant_id,
name,
description,
enabled,
transport_type,
url,
headers,
auth_config,
advanced_config,
is_builtin
) VALUES (
'builtin-mcp-002',
10000,
'Code Interpreter',
'内置代码解释器 MCP 服务',
true,
'http-streamable',
'https://mcp.example.com/stream',
'{"X-Custom-Header": "value"}'::jsonb,
'{"token": "your-bearer-token"}'::jsonb,
'{"timeout": 60, "retry_count": 2, "retry_delay": 2}'::jsonb,
true
) ON CONFLICT (id) DO NOTHING;
```
### 3. 验证插入结果
执行以下 SQL 查询验证内置 MCP 服务是否成功插入:
```sql
SELECT id, name, transport_type, enabled, is_builtin
FROM mcp_services
WHERE is_builtin = true
ORDER BY created_at;
```
## 注意事项
1. **ID 命名规范**:建议使用 `builtin-mcp-{序号}` 的格式,例如 `builtin-mcp-001`、`builtin-mcp-002`
2. **空间ID**:内置 MCP 服务可以属于任意空间,但建议使用第一个空间ID(通常是 10000)
3. **JSON 格式**:`auth_config`、`advanced_config`、`headers` 等字段必须是有效的 JSON 格式
4. **幂等性**:使用 `ON CONFLICT (id) DO NOTHING` 确保重复执行不会报错
5. **安全性**:内置 MCP 服务的 URL、认证信息在前端会被自动隐藏,但数据库中的原始数据仍然存在,请妥善保管数据库访问权限
6. **传输方式限制**:仅支持 `sse` 和 `http-streamable`,`stdio` 已被禁用
## 将现有 MCP 服务设置为内置服务
如果你已经有一个 MCP 服务,想将其设置为内置服务,可以使用 UPDATE 语句:
```sql
UPDATE mcp_services
SET is_builtin = true
WHERE id = '服务ID' AND name = '服务名称';
```
## 移除内置 MCP 服务
如果需要移除内置标记(恢复为普通 MCP 服务),执行:
```sql
UPDATE mcp_services
SET is_builtin = false
WHERE id = '服务ID';
```
注意:移除内置标记后,该 MCP 服务将恢复为普通服务,可以被编辑和删除。

View File

@ -1,282 +0,0 @@
# 内置模型管理指南
## 概述
内置模型是系统级别的模型配置,对所有空间可见。普通空间用户(包括空间管理员)看到的敏感信息会被隐藏,且不能修改;系统管理员可以在「模型管理」界面编辑配置和凭据。内置模型通常用于提供系统默认的模型配置,确保所有空间都能使用统一的模型服务。
## 内置模型特性
- **所有空间可见**:内置模型对所有空间都可见,无需单独配置
- **安全保护**:API Key 等凭据永远不会明文返回;只有系统管理员能看到 Base URL 等管理信息和凭据是否已配置
- **权限保护**:普通空间用户只能查看;系统管理员可以编辑配置和凭据
- **统一管理**:内置模型对所有空间生效;删除仍通过 YAML 或 SQL 管理,避免部署配置与运行时状态冲突
## 在管理界面编辑
系统管理员可直接在「设置 → 模型管理」中点击内置模型,修改模型参数或更新凭据。普通空间管理员仍然只能查看。
首次通过管理界面保存 YAML 托管的内置模型后,该行会转为运行时托管(`managed_by` 清空),后续应用启动不会再用同 ID 的 YAML 条目覆盖它。这样可以保证界面保存的结果在重启后仍然有效。若希望重新交给 YAML 管理,需要由部署管理员在数据库中把该行的 `managed_by` 恢复为 `yaml`,或移除运行时覆盖后重新启动。
## 如何添加内置模型
WeKnora 支持两种方式添加内置模型:**推荐**使用 YAML 声明式配置(自动幂等下发),保留 SQL 直插作为兼容路径。
### 方式一(推荐):YAML 配置文件
#### 文件位置
默认路径是 `config/builtin_models.yaml`(与 `config.yaml`、`builtin_agents.yaml` 同目录)。如需挂载到其他位置,设置环境变量 `BUILTIN_MODELS_CONFIG=/absolute/path/builtin_models.yaml` 覆盖。
文件不存在时启动期会跳过、不报错;解析失败仅记录 Warning、不影响主流程。每次应用启动会重新读取并按 `id` 字段 UPSERT 到 `models` 表(保留 `created_at`,刷新其他字段)。如果同 ID 模型已经由系统管理员在界面保存并转为运行时托管,则保留运行时配置,不再由 YAML 覆盖。
#### Schema
```yaml
builtin_models:
- id: <required, stable, UPSERT key>
tenant_id: <int, default 10000> # 与 tenants_id_seq 起点对齐
name: <string>
type: KnowledgeQA | Embedding | Rerank | VLLM | ASR
source: <string, default "remote"> # local | remote | aliyun | ...
description: <string, optional>
is_default: <bool, default false>
status: <string, default "active">
parameters:
base_url: <string>
api_key: <string, supports ${ENV_VAR}>
provider: <string> # openai | generic | moonshot | ...
context_window: <int, optional> # 对话/VLM 上下文窗口(token);省略则默认 200000
embedding_parameters: # 仅 Embedding 类型
dimension: <int>
truncate_prompt_tokens: <int>
```
#### 完整示例
```yaml
builtin_models:
- id: builtin-openai-chat
name: gpt-4o-mini
type: KnowledgeQA
source: remote
description: OpenAI 默认对话模型
is_default: false
parameters:
base_url: https://api.openai.com/v1
api_key: ${OPENAI_API_KEY}
provider: openai
context_window: 200000
- id: builtin-openai-embeddings
name: text-embedding-3-small
type: Embedding
source: remote
parameters:
base_url: https://api.openai.com/v1
api_key: ${OPENAI_API_KEY}
provider: openai
embedding_parameters:
dimension: 1536
truncate_prompt_tokens: 0
- id: builtin-rerank
name: bge-reranker-v2-m3
type: Rerank
source: remote
parameters:
base_url: ${RERANK_BASE_URL}
api_key: ${RERANK_API_KEY}
provider: generic
```
#### `${ENV}` 插值
`api_key` / `base_url` / `name` 等任何**字符串**字段都可以引用环境变量:`${OPENAI_API_KEY}` 会在启动时被对应的 `os.Getenv("OPENAI_API_KEY")` 替换。
- 环境变量存在 → 替换为实际值
- 环境变量不存在 → **保留字面 `${OPENAI_API_KEY}`** 字符串(让 401 错误能直接看出来 env 没设,便于排查)
- 不支持 `${VAR:-default}` 这种 shell 扩展,行为与现有 `config.yaml` 的插值实现一致
- **非字符串字段不能 env 化**(如 `type`、`dimension`、`is_default`),因为它们必须按 YAML 的目标类型解析
#### env 变量怎么进入容器
`docker-compose.yml` 的 `app` 服务已经预置了:
```yaml
env_file:
- path: .env
required: false
```
意味着把变量值写到项目根目录的 `.env` 文件里,启动时自动透传到容器。**无需**在 `environment:` 块里逐个透传。`required: false` 保证 `.env` 不存在时容器仍可启动(适配上游 fresh clone 场景)。
仓库的 `.env.example` 顶部预留了 **Built-in Models** 注释段,列出 LLM / Embedding / Rerank 的参考变量名作为起点;复制 `.env.example` 为 `.env` 后取消注释并填值即可。变量名由 YAML 自行决定,参考段只是常见样板,不是保留字。
完整端到端示例:
`.env`
```bash
LLM_MODEL_NAME=gpt-4o-mini
LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=sk-...
LLM_PROVIDER=openai
```
`config/builtin_models.yaml`
```yaml
builtin_models:
- id: builtin-llm-default
type: KnowledgeQA
is_default: true
name: ${LLM_MODEL_NAME}
parameters:
base_url: ${LLM_BASE_URL}
api_key: ${LLM_API_KEY}
provider: ${LLM_PROVIDER}
```
启动:
```bash
docker compose up -d
```
#### 启动后验证
```bash
docker compose logs app | grep -E 'Built-in models? config'
```
会看到类似:
```
Built-in model upserted: id=builtin-openai-chat name=gpt-4o-mini type=KnowledgeQA
Built-in model upserted: id=builtin-openai-embeddings name=text-embedding-3-small type=Embedding
Built-in models config applied: 2 entries from /app/config/builtin_models.yaml.
```
#### Docker 部署
在 `docker-compose.yml` 的 `app` 服务 `volumes` 块挂载文件:
```yaml
services:
app:
volumes:
- ./config/builtin_models.yaml:/app/config/builtin_models.yaml:ro
```
仓库提供了 `config/builtin_models.yaml.example` 作为起点,复制为 `config/builtin_models.yaml` 后按需修改。
### 方式二:直接 SQL 插入
支持的 provider:`generic`(自定义)、`openai`、`aliyun`、`zhipu`、`volcengine`、`hunyuan`、`deepseek`、`minimax`、`mimo`、`siliconflow`、`jina`、`openrouter`、`litellm`、`requesty`、`gemini`、`modelscope`、`moonshot`、`qianfan`、`qiniu`、`longcat`、`gpustack`
```sql
-- 示例:LLM 内置模型
INSERT INTO models (
id, tenant_id, name, type, source, description,
parameters, is_default, status, is_builtin
) VALUES (
'builtin-llm-001',
10000,
'gpt-4o-mini',
'KnowledgeQA',
'remote',
'系统内置 LLM 模型',
'{"base_url": "https://api.openai.com/v1", "api_key": "sk-xxx", "provider": "openai"}'::jsonb,
false,
'active',
true
) ON CONFLICT (id) DO NOTHING;
-- Embedding
INSERT INTO models (
id, tenant_id, name, type, source, description,
parameters, is_default, status, is_builtin
) VALUES (
'builtin-embedding-001',
10000,
'text-embedding-3-small',
'Embedding',
'remote',
'系统内置 Embedding 模型',
'{"base_url": "https://api.openai.com/v1", "api_key": "sk-xxx", "provider": "openai", "embedding_parameters": {"dimension": 1536, "truncate_prompt_tokens": 0}}'::jsonb,
false,
'active',
true
) ON CONFLICT (id) DO NOTHING;
-- Rerank
INSERT INTO models (
id, tenant_id, name, type, source, description,
parameters, is_default, status, is_builtin
) VALUES (
'builtin-rerank-001',
10000,
'bge-reranker-v2-m3',
'Rerank',
'remote',
'系统内置 Rerank 模型',
'{"base_url": "https://api.jina.ai/v1", "api_key": "jina-xxx", "provider": "jina"}'::jsonb,
false,
'active',
true
) ON CONFLICT (id) DO NOTHING;
```
### 验证插入结果
```sql
SELECT id, name, type, is_builtin, status
FROM models
WHERE is_builtin = true
ORDER BY type, created_at;
```
## 将现有模型设置为内置模型
如果你已经手工创建了一个普通模型,想把它升级为内置模型:
```sql
UPDATE models
SET is_builtin = true
WHERE id = '模型ID';
```
## 移除内置模型
**从 YAML 删除条目即可。** 应用启动时会自动软删除 `models` 表中 YAML 不再声明的 YAML 托管行 —— 你不再需要手工跑 SQL。
工作原理:每条由 YAML 写入的行会被打上 `managed_by = 'yaml'` 标记。重启时 loader 走两步:
1. UPSERT 当前 YAML 中的所有条目(按 `id` 幂等,包含把之前软删过的 `deleted_at` 重置为 NULL —— 也就是说从 YAML 拿掉再加回来等于"复活")
2. 软删除 `is_builtin = true AND managed_by = 'yaml' AND id NOT IN (当前 YAML 中的 id 集合)` 的行
**手工通过 SQL 插入的 builtin 行(`managed_by = ''`)永远不会被 loader 触碰**,与 YAML 完全隔离。
### 手工路径补充
如果你是走 SQL 路径管理的(`managed_by = ''`),删除仍然走老方法:
```sql
-- 取消 builtin 标记,恢复为普通模型
UPDATE models SET is_builtin = false WHERE id = '模型ID';
-- 或直接删除
DELETE FROM models WHERE id = '模型ID';
```
### 紧急关闭 YAML 接管
如果误改了 YAML 想立刻停用接管又不想清空文件,最快的方法是:把环境变量 `BUILTIN_MODELS_CONFIG` 指向一个不存在的路径并重启 —— loader 看到文件缺失会直接 no-op,**包括跳过 drift sweep**,已经写入的 YAML 托管行保留原状。
## 注意事项
1. **ID 命名规范**:建议使用 `builtin-{type}-{slug}` 的格式,例如 `builtin-openai-chat`、`builtin-rerank`
2. **空间ID**:内置模型可以属于任意空间,默认 `10000`(与 `tenants_id_seq` 起点一致)
3. **YAML 与 SQL 并存**:两种方式可以同时使用,loader 只动 `managed_by='yaml'` 的行;通过 SQL 插入的 builtin 行对 loader 完全不可见
4. **`is_default` 单一保证**:YAML 中将某条 entry 标记 `is_default: true` 时,loader 会先把同 `(tenant_id, type)` 下的其它默认模型置为 `false`,避免 API 路径维护的"每类型一个默认模型"语义被破坏
5. **重启即生效**:修改 YAML 后 `docker compose restart app` 即可让新配置生效
6. **加密**:API Key 在 `parameters` JSONB 中以加密形式存储(若 `SYSTEM_AES_KEY` 已配置),未配置时降级为明文兼容路径
7. **安全性**:前端会自动隐藏内置模型的 API Key 和 Base URL,但数据库中的原始数据仍然存在,请妥善保管数据库访问权限
8. **解析错误自我保护**:YAML 解析失败时 loader 仅打 warning 并跳过 reconcile,**不会**执行 drift sweep,确保一个手抖的 YAML 改动不会大规模软删既有内置模型

View File

@ -1,170 +0,0 @@
# Chunking Guide
How WeKnora splits uploaded documents before embedding, why the defaults
are what they are, and when to change them.
## Why chunking matters
Retrieval-Augmented Generation (RAG) works by embedding small slices of
your documents into a vector index, then pulling the most relevant
slices back at query time. The way a document is sliced — chunk size,
overlap, where the cuts fall — directly drives retrieval recall and the
quality of the answers your LLM produces.
Empirically (Vecta Feb-2026 benchmark across 50 academic papers):
recursive splitting at ~512 tokens with ~15% overlap is the strongest
single-knob baseline at 69% end-to-end accuracy, beating semantic
chunking and over-engineered hybrids. WeKnora uses that as the
foundation and layers smarter strategies on top when the document gives
us structural cues.
## Adaptive 3-tier chunking
Set per knowledge base via the editor's **Chunking** sidebar (or the
`strategy` field on the KB-config API).
| Strategy | When picked | What it does |
|----------|-------------|--------------|
| `auto` (recommended) | Default for new KBs | Profiles the document and picks the strongest tier from the chain below. |
| `heading` | Markdown-style structure | Splits at `#` / `##` / `###` boundaries. Each chunk gets a breadcrumb context header (`# Top > ## Section`) prepended at embedding time. |
| `heuristic` | PDF-style structure | Splits at form-feeds (page breaks), numbered sections, multilingual chapter markers (DE / EN / ZH), all-caps titles, and visual separators. |
| `legacy` (= `recursive`) | Anything else, or as fallback | Pure recursive separator-based splitter — newest version with priority recursion and overlap-cap fixes. |
A document profiler runs first and counts structural signals (Markdown
headings, form-feeds, chapter markers per language, all-caps lines,
visual separators, blank-line bursts). Auto-strategy picks the tier
chain based on those counts; a validator rejects obviously broken
output (e.g. the heading splitter producing 200 single-line chunks)
and falls through to the next tier.
## Settings reference
### Core
| Setting | Range | Default | Sweet spot for… |
|---------|-------|---------|-----------------|
| **Chunk size** | 100–4000 chars | 512 | Default works for most cases. 200–400 for FAQs / atomic Q&A. 1000–2000 for narrative documents. |
| **Chunk overlap** | 0–500 chars | 80 (~15%) | 0 for FAQs and structured records. 80 (default) for general documents. 150–200 for argumentative texts where reasoning crosses chunks. |
| **Separators** | string list | `["\n\n", "\n", "。", "!", "?", ";", ";"]` | Order matters — splitter tries higher-priority separators first and only falls back to lower ones when a piece is still oversize. |
### Parent-Child chunking
Two-level retrieval: **child chunks** (small, embedded for vector match)
and **parent chunks** (larger, returned to the LLM for context).
| Setting | Range | Default | Notes |
|---------|-------|---------|-------|
| **Enable parent-child** | toggle | on | Recommended for documents > 10 pages. Skip for short FAQs to halve storage cost. |
| **Parent chunk size** | 512–8192 chars | 4096 (~1000 EN tokens) | Larger for long-context LLMs (Claude, GPT-4-Turbo). Smaller (1024–2048) for local LLMs with 4k contexts. |
| **Child chunk size** | 64–2048 chars | 384 (~95 EN tokens) | 128–256 for Q&A-style precise matching. 512–1024 if your embedder accepts >1000 tokens (E5 / BGE-large). |
### Advanced
| Setting | Range | Default | When to set |
|---------|-------|---------|-------------|
| **Token limit** | 0–8192 | 0 (off) | Activate when your embedding model has a small token cap. See table below. |
| **Languages** | `de` / `en` / `zh` (multi-select) | empty (auto-detect) | Set explicitly for homogeneous corpora to narrow heuristic patterns. |
#### Token-limit guide per embedding model
| Embedder | Token limit | Recommended `tokenLimit` setting |
|----------|-------------|----------------------------------|
| OpenAI `text-embedding-3-small/large` | 8191 | **0 (leave off)** |
| Anthropic Voyage-3 | 32000 | **0** |
| Jina-embeddings-v3 | 8192 | **0** |
| Cohere `embed-multilingual-v3` | 512 | **400** |
| BGE-base / BGE-large / E5-large | 512 | **400** |
| Sentence-Transformer `all-MiniLM-L6-v2` | 256 | **200** |
Rule of thumb: leave at 0 for any modern embedder with > 2000 tokens.
Activate to 80% of the model's hard limit for smaller embedders so
chunks always fit even for CJK content (which is denser per character).
## Use-case presets
| Workload | Strategy | ChunkSize | Overlap | Parent-Child |
|----------|----------|-----------|---------|--------------|
| FAQ / Q&A knowledge base | `auto` (likely picks legacy) | 200–400 | 0 | off |
| Markdown documentation / wikis | `auto` (picks heading) | 512 | 80 | on |
| PDF reports with page breaks | `auto` (picks heuristic) | 800–1200 | 100–150 | on |
| Long-form narrative (books, articles) | `auto` (picks recursive) | 1000–2000 | 150–200 | on |
| Code documentation | `legacy` | 800 | 100 | optional |
| Mixed-language corpus | `auto`, languages = empty | 512 | 80 | on |
| Tabular reports / CSV-derived | `legacy` | 400 | 0 | off |
## Debugging in the UI
The KB editor's **Chunking** sidebar has a "Test with sample text"
collapsible at the bottom:
1. Paste a Markdown / plain-text snippet (max 64 KB).
2. Click **Run preview**.
3. The panel shows:
- Selected strategy tier as a colored tag
- Tiers that were rejected and why (e.g. "too many tiny chunks")
- Document profile (heading counts, form-feeds, chapter markers,
detected languages)
- Size statistics over the full chunk set (avg / min / max / stddev)
- Per-chunk cards with size in chars + approximate tokens, position
range, the section breadcrumb (when set), and a content preview
This runs read-only against a goroutine-isolated splitter pass (5s
timeout) — no DB writes, no embedding API calls. Use it to compare
configurations against the same sample before triggering a re-upload.
## API
Three endpoints can write the chunking config. The KB-config update
endpoint is the one wired to the editor UI and uses **camelCase** with a
`documentSplitting` envelope:
```http
PUT /api/v1/initialization/config/:kbId
Authorization: Bearer <jwt>
Content-Type: application/json
{
"documentSplitting": {
"chunkSize": 512,
"chunkOverlap": 80,
"separators": ["\n\n", "\n", "。", "!", "?", ";", ";"],
"strategy": "auto",
"tokenLimit": 0,
"languages": ["de", "en"],
"enableParentChild": true,
"parentChunkSize": 4096,
"childChunkSize": 384
}
}
```
The `strategy`, `tokenLimit`, and `languages` fields use pointer-based
DTOs server-side: omitting them in the payload means "no change",
sending an empty string / 0 / [] explicitly resets to default.
The KB CRUD endpoints (`POST /api/v1/knowledge-bases`,
`PUT /api/v1/knowledge-bases/:id`) take the same fields but in
**snake_case** under a `chunking_config` envelope:
`{ "chunking_config": { "chunk_size": 512, "chunk_overlap": 80,
"strategy": "auto", "token_limit": 0, "languages": ["de", "en"], ... } }`.
The preview endpoint at `POST /api/v1/chunker/preview` uses the snake_case
form too and additionally takes a `text` field for the sample to chunk.
## Known trade-offs
- **Tier-1 heading-aware chunking** prepends the section breadcrumb to
the embedding input, costing ~5% more tokens per chunk in exchange
for ~30–50% fewer chunks on structured documents (net token savings
on storage and at query time).
- **Strategy switches do not auto-reindex** existing documents. After
changing a KB's strategy, re-upload affected files (or trigger
re-indexing via the UI) to apply the new chunking.
- **OCR artifacts in PDFs** (vertical layout text broken character-
by-character into separate lines) cannot be fixed by any splitter —
this is a parser-side limitation. The heuristic tier still keeps
chunks aligned to page boundaries, which mitigates the worst cases.
- **The `recursive` strategy value** exists in the API for completeness
but is intentionally hidden from the UI: it is functionally near
`legacy` and adding a fifth dropdown option dilutes the meaningful
choice between automatic / Markdown / heuristic / legacy.

File diff suppressed because it is too large Load Diff

View File

@ -1,28 +0,0 @@
# WeKnora 知识图谱
## 快速开始
- .env 配置相关环境变量
- 启用 Neo4j: `NEO4J_ENABLE=true`
- Neo4j URI: `NEO4J_URI=bolt://neo4j:7687`
- Neo4j 用户名: `NEO4J_USERNAME=neo4j`
- Neo4j 密码: `NEO4J_PASSWORD=password`
- 启动 Neo4j
```bash
docker-compose --profile neo4j up -d
```
- 在知识库设置页面启用实体和关系提取,并根据提示配置相关内容
## 生成图谱
上传任意文档后,系统会自动提取实体和关系,并生成对应的知识图谱。
![知识图片示例](./images/graph3.png)
## 查看图谱
登录 `http://localhost:7474`,执行 `match (n) return (n)` 即可查看生成的知识图谱。
在对话时,系统会自动查询知识图谱,并获取相关知识。

View File

@ -1,312 +0,0 @@
# Langfuse 集成
WeKnora 内置了对 [Langfuse](https://langfuse.com) 的轻量级集成,用于统计 token 消耗、追踪 LLM 调用链路、并为每个对话生成可在 Langfuse 控制台查看的 trace。该集成解决 issue [#497](https://github.com/Tencent/WeKnora/issues/497)(token 使用量统计)和 discussion [#620](https://github.com/Tencent/WeKnora/discussions/620)(接入 Langfuse)。
## 1. 特性
- 自动上报 **chat / embedding / rerank / VLM(视觉语言模型)/ ASR(语音识别)** 全部 5 类模型调用的 prompt、响应和 token 使用量。
- 为每个对话、检索、**文件上传及后续异步处理**创建一条端到端 **trace**。HTTP 请求是根,asynq 任务以 SPAN 的形式挂在同一条 trace 下,文档解析 → chunk embedding → 多模态 OCR/Caption → 摘要 / 问题生成全部在同一棵树里可见。
- 支持 **流式响应**:记录首 token 延迟(Time-To-First-Token),完整响应在流结束后一次性写入。
- **跨进程 trace 透传**:HTTP 层把 `trace_id` / `parent_observation_id` 注入 asynq payload,worker 在 asynq middleware 层自动 resume;定时任务(例如数据源同步)则退化为独立 trace,依然按任务类型(`asynq.<type>`)聚合。
- **完全可选**:不配置 `LANGFUSE_*` 环境变量时,Langfuse 相关代码路径是 no-op,不产生任何性能开销。
- **异步批量上报**:不阻塞业务请求;队列满时静默丢弃,观测数据不会影响用户对话。
- **开箱即用的部署方式**:Docker Compose(`docker-compose.yml` 已内置环境变量)、Helm Chart(通过 `extraEnv`)、Lite 版本(本地单机)均支持。
## 2. 快速开始
### 2.1 获取 Langfuse 凭证
1. 登录 [cloud.langfuse.com](https://cloud.langfuse.com) 或自建 Langfuse 实例。
2. 进入 `Project Settings → API Keys`,生成一对 `Public Key` / `Secret Key`。
### 2.2 按部署方式配置
#### (A)Docker Compose 部署(推荐)
`docker-compose.yml` 已经把所有 `LANGFUSE_*` 环境变量串到 `app` 服务。下面提供两种选择。
##### A-1) 接入 Langfuse Cloud(最简单)
只需要在 **`.env`** 里加 3 行:
```bash
LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxx
LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxx
LANGFUSE_HOST=https://cloud.langfuse.com # 美区用 https://us.cloud.langfuse.com
```
然后重启服务:
```bash
docker compose up -d app
docker compose logs -f app | grep Langfuse
```
看到下面这行就说明已启用:
```
[Langfuse] enabled host=https://cloud.langfuse.com flush_at=15 flush_interval=3s sample_rate=1.00
```
##### A-2) 自建 Langfuse 栈(离线 / 内网 / 数据合规)
`docker-compose.yml` 内置了一个可选的 `langfuse` profile,用一条命令就能拉起 Langfuse v3。
**设计上已尽可能复用 WeKnora 已有容器,避免资源浪费**:
| 组件 | 来源 | 备注 |
| --- | --- | --- |
| PostgreSQL | 复用 `WeKnora-postgres` | 通过一次性的 `langfuse-db-init` 容器,在同一 pg 实例里创建独立的 `langfuse` 数据库。库级隔离,互不影响。 |
| Redis | 复用 `WeKnora-redis` | 使用独立的 Redis DB 号(默认 DB 1,WeKnora 用 DB 0)。`REDIS_CONNECTION_STRING` 指定 DB 后缀。 |
| ClickHouse | 新增 `langfuse-clickhouse` | Langfuse 专有(OLAP 事件存储),WeKnora 不用,必须独立。 |
| MinIO | 新增 `langfuse-minio` | 故意和 WeKnora 的 `minio` 分开(后者是可选 profile,未必激活;Langfuse S3 要专属 bucket)。 |
| Web / Worker | 新增 `langfuse-web` + `langfuse-worker` | Langfuse 应用本体。 |
最终 `--profile langfuse` 只新增 **4 个常驻容器 + 1 个一次性 init**,内存开销由原先的 ~1.5–2.5 GB 降到约 **1.0–1.5 GB**。
```bash
# 1. 启动自建栈(ClickHouse 首次迁移大约需要 1-2 分钟)
docker compose --profile langfuse up -d
# 2. 浏览器打开 http://localhost:3000 注册管理员账号
# 然后在 Project Settings → API Keys 生成 Public/Secret Key
# 3. 把 key 填回 .env 并把 HOST 改成容器内部地址
cat >> .env <<'EOF'
LANGFUSE_HOST=http://langfuse-web:3000
LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxx
LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxx
EOF
# 4. 让 app 重新加载配置
docker compose up -d app
```
> ⚠️ **生产部署安全提示**:`.env.example` 里的默认密码 / `SALT` / `ENCRYPTION_KEY` 都是开发占位符,生产环境必须用以下命令重新生成:
>
> ```bash
> echo "LANGFUSE_SALT=$(openssl rand -base64 32)"
> echo "LANGFUSE_ENCRYPTION_KEY=$(openssl rand -hex 32)"
> echo "LANGFUSE_NEXTAUTH_SECRET=$(openssl rand -base64 32)"
> ```
>
> 同时把 `LANGFUSE_DB_PASSWORD` / `LANGFUSE_CLICKHOUSE_PASSWORD` / `LANGFUSE_REDIS_PASSWORD` / `LANGFUSE_MINIO_PASSWORD` 全部换成强密码。完整变量清单见 `.env.example` 的 "Langfuse 自建栈配置" 段。
##### 通用调优
可选调优变量(`LANGFUSE_FLUSH_AT`、`LANGFUSE_SAMPLE_RATE` 等)都已经在 `docker-compose.yml` 中预设直通,只要在 `.env` 追加对应行即可生效。完整列表见 `.env.example` 的 Langfuse 段,或本文第 3 节。
##### 资源开销估算(A-2 自建方案)
| 组件 | 类型 | 典型 RSS | 备注 |
| --- | --- | --- | --- |
| langfuse-db-init | 一次性 | – | 创建 `langfuse` 数据库后立即退出 |
| langfuse-web | 常驻 | 300–500 MB | Next.js |
| langfuse-worker | 常驻 | 200–400 MB | Node.js,Queue consumer |
| langfuse-clickhouse | 常驻 | 500 MB–1 GB | 首次迁移稍高,稳态约 500 MB |
| langfuse-minio | 常驻 | 100–200 MB | |
| (复用)WeKnora-postgres | – | +~50 MB | 多一个 `langfuse` 数据库 |
| (复用)WeKnora-redis | – | +30–80 MB | 共用实例的 DB 1 |
| **新增合计** | | **≈ 1.0–1.5 GB** | 推荐 3 GB+ 可用内存 |
> 和"完全隔离各建一套 pg/redis"方案相比,这里节省了约 **400–500 MB** 内存。代价是 WeKnora 的 pg/redis 容量规划需要为 Langfuse 预留一点余量;Langfuse 写入量并不大(只是元数据 + 任务队列,事件主体走 ClickHouse),实际影响很小。
对单机部署而言,若只想使用 Langfuse Cloud 方案(A-1),**完全不需要**这些容器;原有服务 CPU/内存占用不变。
##### 生产环境下的注意事项
- **WeKnora-redis 的驱逐策略**:Langfuse 建议 `maxmemory-policy noeviction`(避免 Redis 在内存紧张时丢弃队列任务)。如果 WeKnora 的 redis 未配置该策略,建议在 `docker-compose.yml` 的 redis command 中加上 `--maxmemory-policy noeviction`。
- **备份**:`pg_dump -d langfuse` 可独立备份 Langfuse 的元数据;事件数据在 ClickHouse 卷(`langfuse_clickhouse_data`)中。
- **想彻底隔离**(跨机部署、强运维隔离):可以直接把 `langfuse-web` / `langfuse-worker` 的 `DATABASE_URL` 和 `REDIS_CONNECTION_STRING` 指向任意外部 pg/redis(例如 RDS + ElastiCache);`langfuse-db-init` 容器可以选择不启动,手动在目标 pg 上 `CREATE DATABASE langfuse` 即可。
#### (B)WeKnora Lite(单机)
在 `.env.lite`(或启动脚本导出的环境变量)里加:
```bash
LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxx
LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxx
LANGFUSE_HOST=https://cloud.langfuse.com
```
启动 `weknora-lite`(或 macOS `.app`)后效果同上。
#### (C)Helm Chart 部署
在 `values.yaml` 的 `app.extraEnv` 添加:
```yaml
app:
extraEnv:
- name: LANGFUSE_PUBLIC_KEY
valueFrom:
secretKeyRef:
name: langfuse-credentials
key: public_key
- name: LANGFUSE_SECRET_KEY
valueFrom:
secretKeyRef:
name: langfuse-credentials
key: secret_key
- name: LANGFUSE_HOST
value: https://cloud.langfuse.com
```
建议把 Secret Key 放到 Kubernetes Secret 中,切勿写进 values.yaml。
#### (D)二进制 / 源码运行
```bash
export LANGFUSE_PUBLIC_KEY="pk-lf-xxxx"
export LANGFUSE_SECRET_KEY="sk-lf-xxxx"
export LANGFUSE_HOST="https://cloud.langfuse.com"
./weknora-server
```
#### (E)本地开发(`docker-compose.dev.yml` + `go run`)
`docker-compose.dev.yml` 只启动基础设施容器(postgres/redis/docreader 等),`app` 走本地 `go run ./cmd/server`。Langfuse 的两种接入方式:
**E-1) 直连 Langfuse Cloud(dev 最常见)**
无需改任何 compose 文件,本地 shell 导出即可:
```bash
export LANGFUSE_PUBLIC_KEY="pk-lf-xxxx"
export LANGFUSE_SECRET_KEY="sk-lf-xxxx"
export LANGFUSE_HOST="https://cloud.langfuse.com"
go run ./cmd/server
```
**E-2) 本地自建栈调试**
dev compose 也支持对称的 `langfuse` profile(复用同一个 dev postgres + redis):
```bash
# 拉起基础设施 + Langfuse 栈
docker compose -f docker-compose.dev.yml up -d postgres redis docreader
docker compose -f docker-compose.dev.yml --profile langfuse up -d
# 浏览器打开 http://localhost:3000 注册并生成 key
# 本地 app 接入(注意是 localhost,不是 langfuse-web,因为 go run 跑在宿主机)
export LANGFUSE_HOST=http://localhost:3000
export LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxx
export LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxx
go run ./cmd/server
```
Dev 相关容器都带 `-dev` 后缀、用独立网络 `WeKnora-network-dev`,和生产 compose **不冲突**。
### 2.3 验证
发起一次知识问答(`POST /api/v1/knowledge-chat/:session_id`)或知识检索(`POST /api/v1/knowledge-search`)。等待 3 秒(或批量大小达到 `flush_at`)后,Langfuse 控制台的 **Traces** 页面会出现对应的 trace:
- 顶层节点:HTTP 请求(带 `userId` / `sessionId`)。
- 子节点依次为 rerank、chat、VLM 等具体模型调用,点击可查看 prompt、响应以及 usage(prompt/completion/total tokens)。
- 流式对话会额外标注 Time-To-First-Token。
## 3. 环境变量参考
| 变量名 | 默认值 | 说明 |
| --- | --- | --- |
| `LANGFUSE_ENABLED` | 自动 | 显式开关。未设置时,只要 `PUBLIC_KEY` + `SECRET_KEY` 都存在就自动启用。支持 `true/false/1/0/yes/no`。 |
| `LANGFUSE_HOST` | `https://cloud.langfuse.com` | Langfuse 实例地址。美区用 `https://us.cloud.langfuse.com`,自建实例填 `https://langfuse.your-domain.com`。 |
| `LANGFUSE_PUBLIC_KEY` | — | 项目 Public Key(`pk-lf-...`)。 |
| `LANGFUSE_SECRET_KEY` | — | 项目 Secret Key(`sk-lf-...`),请走密钥管理工具注入,不要提交到仓库。 |
| `LANGFUSE_RELEASE` | — | 可选,上报到 Langfuse 的版本号,例如 CI 构建号。 |
| `LANGFUSE_ENVIRONMENT` | — | 可选,环境标签(`production` / `staging` / `dev`),方便在 UI 过滤。 |
| `LANGFUSE_FLUSH_AT` | `15` | 批处理大小:缓冲区积累到该数量立即上报。 |
| `LANGFUSE_FLUSH_INTERVAL` | `3s` | 定时刷新间隔。支持 `500ms`、`5s`、`1m` 等 Go duration 写法;纯数字按秒处理。 |
| `LANGFUSE_QUEUE_SIZE` | `2048` | 内存队列容量。队列满时新事件会被静默丢弃(避免拖慢业务)。 |
| `LANGFUSE_REQUEST_TIMEOUT` | `10s` | 单次 HTTP ingest 请求超时。 |
| `LANGFUSE_SAMPLE_RATE` | `1.0` | 采样率 (0..1)。`0` 视为 `1.0`。高流量环境可下调。 |
| `LANGFUSE_DEBUG` | `false` | 打开后会在 WeKnora 日志里打印上报失败的详细原因,排障期间临时开启。 |
## 4. 观测数据说明
| Langfuse 概念 | WeKnora 对应 | 备注 |
| --- | --- | --- |
| Trace | 一次 HTTP 请求(含其触发的所有 asynq 任务) | 对于 `knowledge-chat`、`agent-chat`、`knowledge-search`、`generate_title`、`evaluation`、模型连通性测试等在线请求;以及文件上传/URL 入库/manual/reparse/move/copy、FAQ 导入、知识修改、wiki auto-fix、数据源手工触发等入库请求,HTTP 层都会开启 trace,并把 `trace_id` / `parent_observation_id` 注入 asynq payload。 |
| Span(type=SPAN) | 每个 asynq 任务的执行窗口 / 每次 Agent 执行及其每一轮 / 每次工具调用 | 由 `internal/tracing/langfuse/AsynqMiddleware` 在 `mux.Use` 注册;对每个 handler 自动创建 `asynq.<task_type>` 的 SPAN,并记录 `task_id` / `queue` / `retry` / `payload_bytes`。定时任务(无上游 trace)会退化为 `asynq.<task_type>` 独立 trace。**Agent 相关**:`AgentEngine.Execute` 会开 `agent.execute` 顶层 SPAN,其下每一轮 ReAct 循环开 `agent.round.N` SPAN,每次工具调用开 `agent.tool.<tool_name>` SPAN(参数、输出、耗时、成败、错误都会写入)。 |
| Generation(type=GENERATION) | 每次 chat / embedding / rerank / VLM / ASR 调用 | 若位于 span 下会自动设置 `parentObservationId`,所以 Langfuse UI 呈现 trace → asynq-span → generation 的树状结构;Agent 模式下是 trace → agent.execute → agent.round.N → (chat.completion.stream + agent.tool.X → rerank/embedding...) 的完整树。 |
| Input Tokens | `TokenUsage.PromptTokens` | 来自模型返回的 usage 字段。 |
| Output Tokens | `TokenUsage.CompletionTokens` | 来自模型返回的 usage 字段。 |
| Total Tokens | `TokenUsage.TotalTokens` | 大多数厂商返回;未返回时自动求和。 |
| Cache Read Tokens | `TokenUsage.CacheReadTokens` | 从 OpenAI-compatible `cached_tokens`、DeepSeek 原生 hit tokens 或 Anthropic cache read tokens 归一化。 |
| Cache Write Tokens | `TokenUsage.CacheWriteTokens` | Anthropic cache creation 或供应商等价字段;不与 Input Tokens 重复相加。 |
| Cache Miss Tokens | `TokenUsage.CacheMissTokens` | 已上报缓存口径下未从缓存读取的输入 token。 |
| Generation Metadata | `call_purpose` / `prompt_prefix_fingerprint` | 用调用用途分组缓存指标;前缀只上报不可逆短哈希,不上报原始 prompt。 |
| `userId` | `X-User-ID` / 空间 ID | 未登录时退化为 `tenant:<id>`,方便按空间汇总消耗;enqueue 时会写入 payload,worker 在无上游 trace 的场景也能保留归属。 |
| `sessionId` | URL 中的 `:session_id`(或 `RequestID` 兜底) | 可以在 Langfuse 的 Sessions 视图聚合一整场对话,或按单次异步批次聚合。 |
| Time-To-First-Token | 流式调用首条有效 chunk 的时间 | 通过 `generation-update.completionStartTime` 上报。 |
### 覆盖到的 asynq 任务类型
下表列出当前会在 Langfuse 里自动出现对应 SPAN 的 asynq 任务;每种任务的 payload 均已嵌入 `types.TracingContext`,enqueue 时由 `langfuse.InjectTracing(ctx, &payload)` 从当前 HTTP trace 拷出 `trace_id` / `parent_observation_id`。
| 任务类型常量 | Handler | 典型触发来源 |
| --- | --- | --- |
| `document:process` | `knowledgeService.ProcessDocument` | 文件 / URL / 文本 / file_url 四种入库;reparse;知识库克隆内部重派发 |
| `manual:process` | `knowledgeService.ProcessManualKnowledge` | 手工知识新建 / 更新 |
| `image:multimodal` | `ImageMultimodalService.Handle` | 文档解析时发现图片 |
| `knowledge:post_process` | `KnowledgePostProcessService.Handle` | 文档解析完成后统一调度 summary/question |
| `summary:generation` / `question:generation` | `KnowledgePostProcessService` 子任务 | 由 `knowledge:post_process` 派发 |
| `chunk:extract` | `ChunkExtractor.Handle` | 图谱提取(NEO4J 启用时) |
| `datatable:summary` | `DataTableSummaryService.Handle` | 表格文件解析 |
| `faq:import` | FAQ 批量导入 handler | FAQ 导入 / 批量创建 |
| `knowledge:move` / `knowledge:list_delete` / `index:delete` / `kb:clone` / `kb:delete` | 知识移动 / 批量删除 / 索引清理 / 知识库复制 / 知识库删除 | 对应 HTTP 路由 |
| `wiki:ingest` | `wikiIngestService.ProcessWikiIngest` | Wiki auto-fix / 重建链接 |
| `datasource:sync` | `dataSourceSyncService.Handle` | 数据源手动触发 + 定时调度(定时场景下 trace 为 standalone) |
### 各模型的 usage 处理策略
| 模型类型 | 上报名称 | Token 计量方式 | 备注 |
| --- | --- | --- | --- |
| Chat | `chat.completion` / `chat.completion.stream` | 直接使用模型返回的 `prompt_tokens` / `completion_tokens` / `total_tokens` | 流式请求会记录 TTFT。 |
| Embedding | `embedding.embed` / `embedding.batch_embed` | 模型未返回 usage 时按 `rune_count/4 + 1` 估算 input tokens | 批量接口会上报批量大小和前 5 条文本预览,避免把整批内容塞进 trace。 |
| Rerank | `rerank` | 按 `query + 所有文档` 的 rune 数估算 input tokens | 输出只上报前 10 条 `(index, score)`。 |
| VLM | `vlm.predict` | prompt/result 分别按 `rune/4` 估算 input/output | 不上传原始图片字节;仅记录图片数量与总字节大小。 |
| ASR | `asr.transcribe` | 以 **秒**(`SECONDS`)为计量单位,取转录结果最后一个 segment 的 `end` 作为音频时长 | 便于 Langfuse 按"分钟"结算 Whisper 类 API。 |
> Tip:Langfuse 的 `Settings → Models` 页面可以为自定义模型(本地 Ollama、阿里云百炼等)配置单价(每 1K tokens、每分钟等),Langfuse 会据此自动核算费用。
## 5. 高流量部署建议
- **调高 `LANGFUSE_FLUSH_AT`** 到 50–100,降低 ingest HTTP 调用频率。
- **采样**:把 `LANGFUSE_SAMPLE_RATE=0.1` 只采样 10% 的对话,生产成本与信噪比通常能得到较好的平衡。
- **扩大 `LANGFUSE_QUEUE_SIZE`** 至 8192,防止短时峰值触发事件丢弃。
- 将 Langfuse 实例部署在离 WeKnora 同机房(例如自建 Langfuse + 内网地址),可以显著降低上报延迟。
- 打开 `LANGFUSE_DEBUG=true` 几分钟即可确认链路,生产环境常态下关闭,避免日志噪音。
## 6. 禁用
删除或留空 `LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY`,或显式设置 `LANGFUSE_ENABLED=false`,再重启服务即可。所有 Langfuse 相关代码路径会回退到 no-op,不会影响其他观测组件(OpenTelemetry、LLM Debug Log)。
## 7. 故障排查
| 现象 | 建议排查步骤 |
| --- | --- |
| 启动日志没有 `[Langfuse] enabled` | 检查 `LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY` 是否被服务进程读到;容器里可 `env \| grep LANGFUSE` 验证。 |
| 控制台看不到 trace | 打开 `LANGFUSE_DEBUG=true`,观察日志中是否有 `[Langfuse] flush ... failed`。常见原因:`LANGFUSE_HOST` 错误、企业防火墙拦截 HTTPS、Secret Key 轮换后未更新。 |
| 部分 chunk 缺失 | 调大 `LANGFUSE_QUEUE_SIZE`;确认 Langfuse ingest API 没有返回 429/503。 |
| token 数为 0 | 该模型在返回中未提供 usage(常见于部分本地 Ollama / 自建模型)。可在模型侧开启 usage 统计,或在 Langfuse 配置里为该模型提供 tokenizer。 |
## 8. 代码位置
- `internal/tracing/langfuse/` — Langfuse 客户端、异步批量上报、Gin 中间件、**asynq middleware**、Span / Trace resume 实现。
- `tracer.go` — 暴露 `Trace` / `Span` / `Generation` + `StartTrace` / `StartSpan` / `StartGeneration` / `ResumeTrace`。
- `asynq.go` — `AsynqMiddleware()` 统一在 mux 上包 handler;`InjectTracing(ctx, payload)` 在 enqueue 侧把 trace/span ID 注入 payload。
- `middleware.go` — Gin 中间件 + `shouldTrace` 白名单(覆盖 chat / 入库 / FAQ / wiki / 数据源等路径)。
- `internal/types/tracing.go` — `TracingContext` POCO,所有 asynq payload 通过嵌入此结构携带 `lf_trace_id` / `lf_parent_obs_id` / `lf_user_id` / `lf_session_id`。
- `internal/models/chat/langfuse_wrapper.go` — Chat 调用装饰器(含流式)。
- `internal/models/embedding/langfuse_wrapper.go` — Embedding 调用装饰器。
- `internal/models/rerank/langfuse_wrapper.go` — Rerank 调用装饰器。
- `internal/models/vlm/langfuse_wrapper.go` — VLM(视觉语言模型)调用装饰器。
- `internal/models/asr/langfuse_wrapper.go` — ASR(语音识别)调用装饰器。
- `internal/agent/engine.go` — `agent.execute` 顶层 SPAN 和 `agent.round.<N>` 每轮 SPAN。
- `internal/agent/act.go` — `agent.tool.<tool_name>` 工具调用 SPAN(包含参数、输出、耗时、成败)。
- `internal/router/router.go` — 注册 `langfuse.GinMiddleware()`。
- `internal/router/task.go` — 在 asynq mux 上 `mux.Use(langfuse.AsynqMiddleware())`,使所有 handler 自动被 trace。
- `internal/container/container.go` — 初始化 + 资源清理。
- `docker-compose.yml` / `.env.example` / `.env.lite.example` — 预置 `LANGFUSE_*` 环境变量直通。

View File

@ -1,30 +0,0 @@
## MCP 功能使用说明
### 功能概述
- MCP(Model Context Protocol)让 WeKnora 可以安全地连接外部工具或数据源,扩展 Agent 在推理时可调用的能力。
- 在前端 `设置 > MCP 服务`(`frontend/src/views/settings/McpSettings.vue`)中集中管理所有服务,无需手动改配置文件。
- 每个服务都包含名称、传输方式(SSE / HTTP Streamable / Stdio)、连接地址或命令、认证信息以及高级超时与重试策略。
### 入口与界面
- 打开控制台左侧菜单 `设置 -> MCP 服务`,即可看到当前空间下的所有 MCP 服务列表。
- 列表中可快速启停服务、查看描述,并通过右侧菜单执行“测试 / 编辑 / 删除”。
- “添加服务”按钮会弹出 `McpServiceDialog`,用于创建或修改服务。
### 常用操作流程
1. **新建服务**
- 点击“添加服务”,填写名称与描述,选择传输方式。
- SSE / HTTP Streamable 需提供可访问的服务 URL;Stdio 需配置 `uvx`/`npx` 命令与参数,可附加环境变量。
- 根据需要填写 API Key、Bearer Token、超时与重试策略,保存后服务会出现在列表中。
2. **启停服务**
- 在列表开关中切换启用状态,系统会即时调用后端 `updateMCPService`,失败时会自动回滚状态并弹出提示。
3. **连接测试**
- 通过更多菜单选择“测试”,前端会调用 `/api/v1/mcp-services/{id}/test` 并弹出 `McpTestResult`。
- 成功时会展示服务可用的工具清单(含输入 schema)和资源列表;失败时会显示错误信息,方便排查网络或鉴权问题。
4. **编辑 / 删除**
- “编辑”会带出原有配置,修改后保存即可。
- “删除”需要在弹窗中确认,完成后列表自动刷新。
### 使用建议
- **传输方式选择**:优先使用 SSE 获取流式体验;需要标准 HTTP Streamable 兼容时再切换;本地调试或离线环境适合使用 Stdio 并在同机启动 MCP Server。
- **鉴权管理**:将 API Key / Token 保存在“认证配置”中,生产环境建议单独创建最小权限 Key,并定期轮换。
- **重试策略**:对公网或第三方服务适当提高 `retry_count` 与 `retry_delay`,避免间歇性超时导致 Agent 中断

View File

@ -1,646 +0,0 @@
# WeKnora OIDC 认证调用流程
本文档说明 WeKnora 当前 OIDC 登录能力的实际调用过程,覆盖:
- 前端如何判断是否展示 OIDC 登录入口
- 用户点击 OIDC 登录后的前后端调用链路
- 后端如何与 OIDC Provider 交互
- 登录成功后前端如何接收结果并落盘本地登录态
- 关键配置项与本地联调方式
本文内容基于当前项目实现,相关代码主要位于:
- 后端路由:`internal/router/router.go`
- 认证处理:`internal/handler/auth.go`
- 认证服务:`internal/application/service/user.go`
- 配置定义:`internal/config/config.go`
- 前端登录页:`frontend/src/views/auth/Login.vue`
- 前端全局回调处理:`frontend/src/App.vue`
- 前端认证 API:`frontend/src/api/auth/index.ts`
- 本地 Dex 示例:`misc/dex-config.yaml`
---
## 1. 整体设计说明
本项目的 OIDC 登录采用的是 **后端发起授权参数生成、后端接收回调并完成 code 换 token、前端通过 URL hash 接收最终登录结果** 的模式。
和常见的纯前端 OIDC SDK 不同,WeKnora 的特点是:
1. **前端只负责发起跳转**,不直接和 OIDC Provider 交换 token。
2. **后端负责用授权码 `code` 向 OIDC Provider 换取 token**。
3. 后端拿到 OIDC 用户信息后,会:
- 查找本地用户;
- 若用户不存在,则自动创建本地账号和默认空间;
- 最终签发 WeKnora 自己的本地 JWT(`token` / `refresh_token`)。
4. 后端不会直接把登录结果放在 query string 中,而是:
- 将登录结果 JSON( `success`、`token`、`refresh_token` 等字段)序列化后再做 base64url 编码;
- 以 `#oidc_result=...` 的形式重定向回前端;
- 前端在 `App.vue` 中统一解析 hash,再调用 `/api/v1/auth/me` 补全用户和空间信息。
因此,**OIDC Provider 的 token 只用于后端换取用户身份,本项目真正的业务访问凭证仍然是 WeKnora 自己签发的 JWT**。
---
## 2. 相关接口
当前 OIDC 相关接口均注册在 `internal/router/router.go` 中:
- `GET /api/v1/auth/oidc/config`
- 获取 OIDC 是否启用,以及 Provider 展示名称
- `GET /api/v1/auth/oidc/url`
- 生成第三方登录跳转地址
- `GET /api/v1/auth/oidc/callback`
- OIDC Provider 回调地址
其中,前端常规登录仍然使用:
- `POST /api/v1/auth/login`
- `POST /api/v1/auth/refresh`
- `POST /api/v1/auth/logout`
- `GET /api/v1/auth/me`
---
## 3. 调用流程图
### 3.1 总体时序图
```mermaid
sequenceDiagram
autonumber
participant U as 用户浏览器
participant FE as 前端(Login/App)
participant BE as WeKnora 后端
participant OP as OIDC Provider
FE->>BE: GET /api/v1/auth/oidc/config
BE-->>FE: { enabled, provider_display_name }
U->>FE: 点击“OIDC 登录”
FE->>BE: GET /api/v1/auth/oidc/url?redirect_uri=...
BE-->>FE: { success, authorization_url, state }
FE->>OP: 浏览器跳转到 authorization_url
OP-->>BE: GET /api/v1/auth/oidc/callback?code=...&state=...
BE->>OP: POST token endpoint (code 换 token)
OP-->>BE: access_token / id_token
BE->>OP: GET userinfo endpoint(可选)
OP-->>BE: 用户信息 claims
BE->>BE: 查找/自动创建本地用户
BE->>BE: 签发本地 token、refresh_token
BE-->>FE: 302 到 /#oidc_result=...
FE->>FE: App.vue 解析 hash
FE->>BE: GET /api/v1/auth/me
BE-->>FE: { user, tenant }
FE->>FE: 写入 authStore/token/user/tenant
FE-->>U: 跳转 /platform/knowledge-bases
```
### 3.2 后端回调处理分支图
```mermaid
flowchart TD
A[OIDC Provider 回调到 /api/v1/auth/oidc/callback] --> B{query 中是否有 error}
B -- 是 --> C[拼接 #oidc_error 和 error_description]
C --> D[302 重定向到前端登录页]
B -- 否 --> E[解析 state]
E --> F{state 是否合法且包含 redirect_uri}
F -- 否 --> G[302 到前端并带 #oidc_error=invalid_state]
F -- 是 --> H{是否有 code}
H -- 否 --> I[302 到前端并带 #oidc_error=missing_code]
H -- 是 --> J[调用 LoginWithOIDC,传入 code 和 redirect_uri]
J --> K[向 OIDC token endpoint 换 token]
K --> L[解析 id_token / 调用 userinfo]
L --> M{本地用户是否存在}
M -- 否 --> N[自动注册新用户并创建默认空间]
M -- 是 --> O[使用现有用户]
N --> P[签发 WeKnora JWT]
O --> P
P --> Q[编码最小必要登录结果为 oidc_result]
Q --> R[302 重定向到前端首页 hash]
```
---
## 4. 前端调用流程
## 4.1 登录页初始化:决定是否展示 OIDC 登录按钮
登录页组件位于 `frontend/src/views/auth/Login.vue`。
页面加载时会执行:
```ts
loadOIDCConfig()
```
该函数调用:
```ts
getOIDCConfig() -> GET /api/v1/auth/oidc/config
```
后端 `GetOIDCConfig` 会读取 `configInfo.OIDCAuth`:
- `enabled`: 是否启用 OIDC
- `provider_display_name`: 登录按钮上展示的供应商名称
前端据此决定:
- 是否显示 OIDC 登录按钮;
- 按钮文案是否显示为“使用 XXX 登录”。
---
## 4.2 用户点击 OIDC 登录按钮
用户点击按钮后,`Login.vue` 中会执行 `handleOIDCLogin()`。
核心逻辑:
1. 前端先构造后端回调地址:
```ts
const getBackendOIDCRedirectURI = () => `${window.location.origin}/api/v1/auth/oidc/callback`
```
其中:
- `redirect_uri`:提供给 OIDC Provider 的回调地址,必须是后端地址。
登录成功后,后端固定回跳前端首页 `/`,并通过 hash 传递 OIDC 结果。
2. 前端调用:
```ts
GET /api/v1/auth/oidc/url?redirect_uri=...
```
3. 后端返回 `authorization_url` 后,前端直接执行:
```ts
window.location.href = authorizationURL
```
浏览器随后离开 WeKnora 页面,跳转到 OIDC Provider 的授权页。
---
## 5. 后端生成授权地址
对应处理器:`AuthHandler.GetOIDCAuthorizationURL`
对应服务:`userService.GetOIDCAuthorizationURL`
### 5.1 参数校验
后端要求以下参数必须存在:
- `redirect_uri`
否则直接返回校验错误。
### 5.2 读取 OIDC 配置
`getOIDCConfig()` 会执行以下逻辑:
1. 检查 `OIDCAuth.Enable` 是否为 `true`;
2. 设置默认值:
- `ProviderDisplayName` 默认是 `OIDC`
- `Scopes` 默认是 `openid profile email`
- `UserInfoMapping.Username` 默认是 `name`
- `UserInfoMapping.Email` 默认是 `email`
3. 若未显式配置授权/令牌端点,则通过 `discovery_url` 拉取 OIDC Discovery 文档;
4. 自动补齐:
- `authorization_endpoint`
- `token_endpoint`
- `userinfo_endpoint`
### 5.3 生成 state
后端不会把 state 只当成随机串,而是编码了一个 JSON 结构:
```json
{
"nonce": "随机字符串",
"redirect_uri": "后端回调地址"
}
```
然后再做 base64url 编码,作为 `state` 传给 Provider。
这样在 OIDC Provider 回调时,后端就可以从 `state` 里还原:
- 本次使用的后端 `redirect_uri`
### 5.4 拼接授权地址
后端最终拼接的参数包含:
- `response_type=code`
- `client_id`
- `redirect_uri`
- `scope`
- `state`
然后返回给前端:
```json
{
"success": true,
"provider_display_name": "Dex",
"authorization_url": "...",
"state": "..."
}
```
---
## 6. OIDC Provider 回调到后端
OIDC Provider 完成认证后,会回调:
```text
GET /api/v1/auth/oidc/callback
```
处理器为 `AuthHandler.OIDCRedirectCallback`。
### 6.1 Provider 返回错误时
如果 query 中带有:
- `error`
- `error_description`
后端不会返回 JSON,而是直接 302 到前端首页 `/`,并带上 hash:
```text
#oidc_error=...&oidc_error_description=...
```
### 6.2 解析 state
后端会把 `state` 做 base64url 解码并解析为结构体。
如果出现以下情况,将判定失败:
- `state` 无法解码
- JSON 结构非法
- `state.redirect_uri` 为空
失败时会重定向到前端首页:
```text
#oidc_error=invalid_state
```
### 6.3 校验 code
如果没有收到 `code`,则重定向:
```text
#oidc_error=missing_code
```
### 6.4 正式执行 OIDC 登录
若 `state` 与 `code` 都合法,则调用:
```go
LoginWithOIDC(ctx, code, decodedState.RedirectURI, h.resolveDefaultTenantMode(ctx))
```
注意这里传入的是 **state 中保存的 redirect_uri**,而不是重新拼接的地址,这样保证了 code 交换时使用的 `redirect_uri` 和授权时完全一致。
第四个参数是首次自动开户时的默认空间策略,由 `resolveDefaultTenantMode` 从 `auth.default_tenant_mode`(SystemSetting,DB > `WEKNORA_AUTH_DEFAULT_TENANT_MODE` > 配置文件)解析,与本地密码注册共用同一开关;OIDC 不再有独立的 `OIDC_AUTH_DEFAULT_TENANT_MODE`。
---
## 7. 后端用 code 换 token 并解析用户身份
核心逻辑位于 `internal/application/service/user.go`。
## 7.1 换取 OIDC token
`exchangeOIDCCode()` 会向 OIDC Provider 的 `token_endpoint` 发起:
```text
POST application/x-www-form-urlencoded
```
表单参数包括:
- `grant_type=authorization_code`
- `code`
- `redirect_uri`
- `client_id`
- `client_secret`
期望返回字段:
- `access_token`
- `id_token`
- `token_type`
如果 `access_token` 和 `id_token` 都缺失,则认为失败。
## 7.2 解析用户信息
`resolveOIDCUserInfo()` 的处理顺序是:
1. 如果有 `id_token`,先本地解码 JWT payload,提取 claims;
2. 如果配置了 `userinfo_endpoint` 且有 `access_token`,再调用 userinfo 接口;
3. 将两部分 claims 合并,userinfo 的字段可覆盖前面已取到的字段;
4. 根据配置的 `user_info_mapping` 提取:
- 用户名字段
- 邮箱字段
默认映射:
- `username -> name`
- `email -> email`
另外还有回退逻辑:
1. 若 username 为空,尝试 `preferred_username`
2. 再尝试 `name`
3. 再尝试从邮箱前缀生成用户名
如果最终没有拿到邮箱,则直接报错,因为本地用户是按 email 关联的。
---
## 8. 本地用户关联与自动开通
### 8.1 通过邮箱查找用户
后端使用 OIDC 返回的邮箱执行:
```go
userRepo.GetUserByEmail(ctx, userInfo.Email)
```
### 8.2 用户不存在时自动注册
若本地不存在该邮箱用户,则调用 `provisionOIDCUser()` 自动创建账号。
自动创建逻辑包括:
1. 根据 OIDC 用户名/邮箱生成本地用户名;
2. 若用户名冲突,则自动追加 `-1`、`-2` 等后缀;
3. 生成随机密码;
4. 调用现有 `Register()` 流程创建用户;
5. `Register()` 内部还会自动创建默认空间。
因此,**首次使用 OIDC 登录的用户,不需要提前在 WeKnora 中手工建号**。
### 8.3 用户禁用处理
如果找到的本地用户 `IsActive=false`,则登录失败,回调给前端的错误信息为:
```text
Account is disabled
```
---
## 9. 生成 WeKnora 本地登录态
OIDC 登录成功后,后端不会直接把 OIDC token 交给前端使用,而是继续执行:
```go
GenerateTokens(ctx, user)
```
生成两类 JWT:
- `token`:访问令牌,默认 24 小时
- `refresh_token`:刷新令牌,默认 7 天
并写入本地 `auth_tokens` 存储(通过 `tokenRepo.CreateToken`)。
最终后端会返回 OIDC 回调载荷,其中包含:
- `token`
- `refresh_token`
- `success`
- `message`
- `is_new_user`
这一步意味着:
> OIDC 只负责“确认你是谁”,WeKnora 自己负责“签发系统内可用的业务令牌”。
---
## 10. 后端如何把结果传回前端
`OIDCRedirectCallback` 在拿到 `OIDCCallbackResponse` 后,会执行:
1. 将响应对象 JSON 序列化;
2. 用 base64url 编码;
3. 302 重定向到:
```text
/#oidc_result=ENCODED_PAYLOAD
```
失败时则返回:
```text
/#oidc_error=...&oidc_error_description=...
```
这里使用 hash 的好处是:
- 不会把结果作为 query 参数再次发送给服务端;
- 前端可以在浏览器本地直接读取并清理;
- 避免刷新时重复向后端暴露这些参数。
---
## 11. 前端如何消费 OIDC 回调结果
前端不是在 `Login.vue` 中处理回调,而是在 `frontend/src/App.vue` 中统一处理。
这样即使后端把用户重定向到 `/`,应用根组件也能接住这次 OIDC 登录结果。
## 11.1 App.vue 解析 hash
应用挂载时执行:
```ts
handleGlobalOIDCCallback()
```
它会读取:
```ts
window.location.hash
```
并解析以下字段:
- `oidc_error`
- `oidc_error_description`
- `oidc_result`
## 11.2 错误分支
如果存在 `oidc_error`:
1. 调用 `clearOIDCCallbackState('/login')` 清理 URL;
2. 跳转到 `/login`;
3. 弹出错误消息。
## 11.3 成功分支
如果存在 `oidc_result`:
1. base64url 解码并反序列化;
2. 如果 `response.success=true`:
- 先写入 `authStore.setToken(...)`
- 再写入 `authStore.setRefreshToken(...)`
- 随后调用 `/api/v1/auth/me`
- 用 `/auth/me` 返回的 `user` / `tenant` 执行 `authStore.setUser(...)` 与 `authStore.setTenant(...)`
3. 最终跳转到:
```text
/platform/knowledge-bases
```
这与普通账号密码登录成功后的持久化逻辑保持一致。
---
## 12. 关键配置项
OIDC 配置定义位于 `internal/config/config.go`,环境变量示例见 `.env.example`。
### 12.1 主要配置项
| 配置项 | 说明 |
|---|---|
| `OIDC_AUTH_ENABLE` | 是否启用 OIDC 登录 |
| `OIDC_AUTH_ISSUER_URL` | Issuer 地址,可用于自动拼 discovery URL |
| `OIDC_AUTH_DISCOVERY_URL` | OIDC Discovery 地址 |
| `OIDC_AUTH_PROVIDER_DISPLAY_NAME` | 前端按钮显示名称 |
| `OIDC_AUTH_CLIENT_ID` | OIDC Client ID |
| `OIDC_AUTH_CLIENT_SECRET` | OIDC Client Secret |
| `OIDC_AUTH_AUTHORIZATION_ENDPOINT` | 授权端点,可选 |
| `OIDC_AUTH_TOKEN_ENDPOINT` | Token 端点,可选 |
| `OIDC_AUTH_USER_INFO_ENDPOINT` | UserInfo 端点,可选 |
| `OIDC_AUTH_SCOPES` | Scope 列表,默认 `openid profile email` |
| `OIDC_USER_INFO_MAPPING_USER_NAME` | claims 中映射到用户名的字段名 |
| `OIDC_USER_INFO_MAPPING_EMAIL` | claims 中映射到邮箱的字段名 |
### 12.2 启用时的最小要求
当 `OIDC_AUTH_ENABLE=true` 时,后端校验要求:
1. 必须有 `client_id`
2. 必须有 `client_secret`
3. 必须满足以下二选一:
- 配置 `discovery_url`
- 或同时配置 `authorization_endpoint + token_endpoint`
---
## 13. 本地联调示例(Dex)
[Dex](https://dexidp.io/) 是一个简单易用的OIDC Provider,您可以通过它对接多种第三方认证系统(如OAuth2.0,Google,GitHub,LDAP等)。除了Dex之外,您也可以选择[KeyCloak](https://www.keycloak.org/)等其他符合OpenID Connect协议的Provider进行接入。
项目中已提供 Dex 示例配置:`misc/dex-config.yaml`。
其中静态客户端配置示例:
```yaml
staticClients:
- id: weknora
redirectURIs:
- 'http://127.0.0.1:5173/api/v1/auth/oidc/callback'
- 'http://127.0.0.1/api/v1/auth/oidc/callback'
name: 'WeKnora'
# secret: <YOUR_SECRET_HERE>
```
这说明本地调试时,需要确保 **Provider 注册的 redirect URI 与前端实际传给后端的 `redirect_uri` 完全一致**。
前端当前实现中使用的是:
```ts
${window.location.origin}/api/v1/auth/oidc/callback
```
所以:
- 若前端从 `http://127.0.0.1:5173` 访问,则 redirect URI 为
`http://127.0.0.1:5173/api/v1/auth/oidc/callback`
- 若通过 Nginx 统一入口访问,则可能是
`http://127.0.0.1/api/v1/auth/oidc/callback`
Provider 必须提前把这些地址加入白名单。
---
## 14. 调用链路总结
可以把当前 OIDC 登录理解为以下 4 个阶段:
### 阶段一:前端发现能力
前端调用 `/auth/oidc/config`,决定是否展示第三方登录入口。
### 阶段二:浏览器跳转授权
前端调用 `/auth/oidc/url` 获取授权地址,然后跳转到 OIDC Provider。
### 阶段三:后端完成身份兑换
Provider 回调后端 `/auth/oidc/callback`,后端用 `code` 换 token、拉取用户信息、关联或创建本地用户,并签发 WeKnora JWT。
### 阶段四:前端接收最终结果
后端 302 回前端,并通过 `#oidc_result` 传递登录结果;前端在 `App.vue` 中统一解析,写入本地登录态并进入业务页面。
---
## 15. 注意事项
1. **`redirect_uri` 必须严格匹配** Provider 客户端配置。
2. **前端首页不是 OIDC Provider 回调地址**。
- Provider 回调的是后端 `/api/v1/auth/oidc/callback`
- 后端再固定重定向到前端首页 `/`
3. **邮箱是本地账号关联主键**。
- 若 Provider 没返回 email,将无法完成登录。
4. **首次 OIDC 登录会自动创建用户和默认空间**。
5. **真正用于访问 WeKnora API 的仍是本地 JWT**,不是 OIDC access token。
6. 当前实现对 `state` 做了编码封装,但 **没有服务端持久化 state/nonce 校验**;它主要用于传递上下文和基本防错,而不是完整的防重放机制。
---
## 16. 相关源码定位
- 前端是否展示 OIDC 登录按钮:
- `frontend/src/views/auth/Login.vue`
- 前端获取授权地址:
- `frontend/src/api/auth/index.ts`
- `frontend/src/views/auth/Login.vue`
- 前端解析回调 hash:
- `frontend/src/App.vue`
- OIDC 接口路由注册:
- `internal/router/router.go`
- OIDC HTTP 处理:
- `internal/handler/auth.go`
- OIDC 业务逻辑:
- `internal/application/service/user.go`
- OIDC 配置结构与环境变量覆盖:
- `internal/config/config.go`
- Dex 本地示例:
- `misc/dex-config.yaml`

View File

@ -1,493 +0,0 @@
# 常见问题
## 1. 如何查看日志?
```bash
docker compose logs -f app docreader postgres
```
## 2. 如何启动和停止服务?
```bash
# 启动服务
./scripts/start_all.sh
# 停止服务
./scripts/start_all.sh --stop
# 清空数据库
./scripts/start_all.sh --stop && make clean-db
```
## 3. 服务启动后无法正常上传文档?
通常是Embedding模型和对话模型没有正确被设置导致。按照以下步骤进行排查
1. 查看`.env`配置中的模型信息是否配置完整,其中如果使用ollama访问本地模型,需要确保本地ollama服务正常运行,同时在`.env`中的如下环境变量需要正确设置:
```bash
# LLM Model
INIT_LLM_MODEL_NAME=your_llm_model
# Embedding Model
INIT_EMBEDDING_MODEL_NAME=your_embedding_model
# Embedding模型向量维度
INIT_EMBEDDING_MODEL_DIMENSION=your_embedding_model_dimension
# Embedding模型的ID,通常是一个字符串
INIT_EMBEDDING_MODEL_ID=your_embedding_model_id
```
如果是通过remote api访问模型,则需要额外提供对应的`BASE_URL`和`API_KEY`:
```bash
# LLM模型的访问地址
INIT_LLM_MODEL_BASE_URL=your_llm_model_base_url
# LLM模型的API密钥,如果需要身份验证,可以设置
INIT_LLM_MODEL_API_KEY=your_llm_model_api_key
# Embedding模型的访问地址
INIT_EMBEDDING_MODEL_BASE_URL=your_embedding_model_base_url
# Embedding模型的API密钥,如果需要身份验证,可以设置
INIT_EMBEDDING_MODEL_API_KEY=your_embedding_model_api_key
```
当需要重排序功能时,需要额外配置Rerank模型,具体配置如下:
```bash
# 使用的Rerank模型名称
INIT_RERANK_MODEL_NAME=your_rerank_model_name
# Rerank模型的访问地址
INIT_RERANK_MODEL_BASE_URL=your_rerank_model_base_url
# Rerank模型的API密钥,如果需要身份验证,可以设置
INIT_RERANK_MODEL_API_KEY=your_rerank_model_api_key
```
2. 查看主服务日志,是否有`ERROR`日志输出
## 4. 没有图片或者显示无效的图片链接?
当使用多模态功能时,如果遇到图片无法显示或显示无效链接的问题,请按照以下步骤排查:
### 1. 确认多模态功能已正确配置
在知识库设置中开启**高级设置 - 多模态功能**,并在界面中配置相应的多模态模型。
### 2. 确认 MinIO 服务已启动
如果多模态功能配置使用的是 MinIO 存储,需要确保 MinIO 镜像已正确启动:
```bash
# 启动 MinIO 服务
docker-compose --profile minio up -d
# 或者启动完整服务(包括 MinIO、Neo4j、Qdrant)
docker-compose --profile full up -d
```
### 3. 检查 MinIO Bucket 权限
确保 MinIO 对应的 bucket 具有正确的读写权限:
1. 访问 MinIO 控制台:`http://localhost:9001`(默认端口)
2. 使用 `.env` 中配置的 `MINIO_ACCESS_KEY_ID` 和 `MINIO_SECRET_ACCESS_KEY` 登录
3. 进入对应的 bucket,检查并设置访问策略为**公开读取**或**公开读写**
**重要提示**:
- Bucket 名称不要包含特殊字符(包括中文),建议使用小写字母、数字和连字符
- 如果无法修改现有 bucket 的权限,可以在配置中填入一个不存在的 bucket 名称,本项目会自动创建对应的 bucket 并设置好正确的权限
### 4. 配置 MINIO_PUBLIC_ENDPOINT
在 `docker-compose.yml` 文件中,`MINIO_PUBLIC_ENDPOINT` 变量默认配置为 `http://localhost:9000`。
**重要提示**:如果你需要从其他设备或容器访问图片,`localhost` 可能无法正常工作,需要将其替换为本机的实际 IP 地址:
## 5. 平台兼容性说明
**重要提示**:`OCR_BACKEND=paddle` 模式在部分平台上可能无法正常运行。如果遇到 PaddleOCR 启动失败的问题,请选择以下解决方案
### 方案一:关闭 OCR 识别
在 `docker-compose.yml` 文件的 `docreader` 服务中删除 `OCR_BACKEND` 配置,然后重启 docreader 服务
**注意**:设置为 `no_ocr` 后,文档解析将不会使用 OCR 功能,这可能会影响图片和扫描文档的文字识别效果。
### 方案二:使用外部 OCR 模型(推荐)
如果需要 OCR 功能,可以使用外部的视觉语言模型(VLM)来替代 PaddleOCR。在 `docker-compose.yml` 文件的 `docreader` 服务中配置:
```yaml
environment:
- OCR_BACKEND=vlm
- OCR_API_BASE_URL=${OCR_API_BASE_URL:-}
- OCR_API_KEY=${OCR_API_KEY:-}
- OCR_MODEL=${OCR_MODEL:-}
```
然后重启 docreader 服务
**优势**:使用外部 OCR 模型可以获得更好的识别效果,且不受平台限制。
## 6. 如何使用数据分析功能?
在使用数据分析功能前,请确保智能体已配置相关工具:
1. **智能推理**:需在工具配置中勾选以下两个工具:
- 查看数据元信息
- 数据分析
2. **快速问答智能体**:无需手动选择工具,即可直接进行简单的数据查询操作。
### 注意事项与使用规范
1. **支持的文件格式**
- 目前仅支持 **CSV** (`.csv`) 和 **Excel** (`.xlsx`, `.xls`) 格式的文件。
- 对于复杂的 Excel 文件,如果读取失败,建议将其转换为标准的 CSV 格式后重新上传。
2. **查询限制**
- 仅支持 **只读查询**,包括 `SELECT`, `SHOW`, `DESCRIBE`, `EXPLAIN`, `PRAGMA` 等语句。
- 禁止执行任何修改数据的操作,如 `INSERT`, `UPDATE`, `DELETE`, `CREATE`, `DROP` 等。
## 7. 页面里刚保存的配置几秒后又消失了?
这类问题通常不是配置真的被系统清掉了,而是浏览器代理、缓存或插件干扰导致前端读到了异常响应,页面随后又被旧状态覆盖。
建议按下面顺序排查:
1. 先关闭浏览器代理、抓包工具、自动改写请求的插件,再重新打开页面。
2. 确认浏览器没有把 `localhost` 或当前访问域名走代理;如果配置了 PAC,请将 `localhost`、`127.0.0.1` 和实际部署域名加入直连名单。
3. 强制刷新页面,或直接使用无痕窗口重新登录后再保存一次配置。
4. 打开浏览器开发者工具的 `Network` 面板,确认保存配置相关请求返回的是最新内容,且没有被代理改写、缓存命中或重定向到其他环境。
5. 如果是调试模式部署,可尝试重启 `app` 服务后再验证一次:
```bash
docker compose restart app
```
如果重启后短时间恢复正常,但再次访问又出现相同现象,仍应优先检查浏览器代理、缓存和多环境串连问题,而不是直接判断为后端配置丢失。
## 8. SSRF 校验白名单(`SSRF_WHITELIST`)
可选配置。在 `.env` 中设置 `SSRF_WHITELIST`,用于在 URL 校验等环节将指定目标加入白名单,从而绕过常规 SSRF 限制。值为逗号分隔的多条规则,每条可以是:
- **精确域名**:如 `api.internal`
- **通配域名**:如 `*.example.com`
- **IPv4**:如 `203.0.113.5`
- **IPv6**:如 `2001:db8::1`(不要带方括号)
- **CIDR**:如 `10.0.0.0/8`、`2001:db8::/32`
列入白名单的地址会在 URL 校验等处绕过常规 SSRF 规则,**生产环境请谨慎配置**,仅加入确实需要且可信的目标。
示例(与 `.env.example` 一致,可按需取消注释并修改):
```bash
# SSRF_WHITELIST=internal.service,*.corp.example,172.16.0.0/12,2001:db8::1,fd00::/8
```
## 9. 如何开启和查看 Langfuse 可观测性追踪?
WeKnora 支持通过 Langfuse 对 Agent 的 ReAct 循环、大模型 Token 消耗、工具调用以及异步任务流水线进行全链路追踪。
**开启步骤**:
1. 准备一个可用的 Langfuse 实例(支持云端版或私有部署版)。
2. 在 `.env` 文件中配置以下环境变量:
```bash
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://cloud.langfuse.com # 或你的私有部署地址
```
3. 重启服务后,系统会自动对所有支持的模型调用和 Agent 运行轨迹进行追踪,你可以在 Langfuse 的 Traces 面板中直观地看到每次对话和后台任务的详细执行瀑布图与 Token 统计。
## 10. 什么是 Wiki 模式?如何使用?
Wiki 模式允许 Agent 根据原始文档自动生成并维护一套结构化、相互链接的 Markdown Wiki 知识库,从而实现复杂知识的体系化沉淀和图谱化。
**使用方法**:
1. 进入指定**知识库的设置** -> **索引策略 (Indexing Strategy)**。
2. 开启 **Wiki** 索引功能(可同时结合开启**知识图谱**)。
3. 当你向该知识库上传文档时,系统会自动触发异步任务,通过大模型提取文档中的实体与核心概念,并自动生成结构化的 Wiki 页面及页面间的知识图谱链接。
4. 你可以在该知识库的“Wiki”标签页中,使用专用的 Wiki 浏览器查阅、管理页面,并通过可视化的知识图谱查看不同内容之间的关联关系。
## 11. 升级到 0.6.0 后,原本能做的操作变成了「权限不足」?
0.6.0 引入了空间内 RBAC(角色矩阵 + 资源归属),所有写入接口都会按角色 + `creator_id` 鉴权。常见现象:
- **看得到但点不动**:你大概率是该资源的 `Viewer` 或非创建者的 `Contributor`,UI 已经把写操作隐藏/置灰。检查 **用户菜单 → 当前工作区** 角色徽章。
- **共享空间里的 KB / Agent**:他人共享给你的 KB 默认按 `Viewer` 看待;要写需要在源空间里被授予 `Admin+`。
- **API Key 调用**:`X-API-Key` 合成虚拟用户固定为所属空间的 `Admin`(仅删除空间需 `Owner`),脚本一般无需迁移。
- **跨空间超管**:要 `User.CanAccessAllTenants=true` 且 `enable_cross_tenant_access=true`,并通过 `X-Tenant-ID` 切空间。
如需临时回退到「仅审计、不拦截」灰度窗口,可在配置里设置 `tenant.enable_rbac=false`(或环境变量 `WEKNORA_TENANT_ENABLE_RBAC=false`)。完整的角色矩阵和归属链请见 [`docs/RBAC说明.md`](./RBAC说明.md)。
## 12. 为什么登录后没有自动回到上次的工作区?
升级到 0.6.0 后系统会记住「最后活跃工作区」并在登录后自动恢复。若仍未恢复,通常是:
1. 浏览器清理了 LocalStorage / 切换了浏览器;
2. 你最后访问的那个工作区已经把你移除(`/leave` 或被管理员剔除)— 系统会回退到默认空间;
3. JWT 中携带了 `tenant_id` 但已无效 — 退出重登录即可。
## 13. 如何让多人协作时正确分配权限?
按照 [`docs/RBAC说明.md`](./RBAC说明.md) 的角色矩阵:
- 只读用户 → `Viewer`
- 普通成员(上传文档、维护「自己」的 KB / Agent)→ `Contributor`
- 运维人员(管理共享模型、向量库、解析器等基础设施)→ `Admin`
- 空间所有者(拥有删除空间权限;每空间至少一位,可以有多位,最后一位不能被降级或移除)→ `Owner`
如果你希望开启「invite-only」(不允许自助注册到本空间),可在空间设置里打开邀请制,并通过「邀请」入口签发邀请码或链接。
## 14. 文档解析卡在「处理中」/ 解析追踪时间线打不开怎么办?
0.6.1 起每个文档解析都会记录一棵 Langfuse 风格的 Span 树(`knowledge_processing_spans` 表),可在知识库卡片菜单或卡片上的「Trace」入口打开侧边时间线,逐阶段查看进度。常见情况:
- **文档长时间停在「处理中」**:先打开时间线看是哪个阶段没有推进(解析 / 切分 / 向量化 / 后处理)。0.6.1 已修复多数「卡死」场景,并加入看门狗轮询;如确认是某次解析挂死,可在时间线面板点击「中止解析」,文档会进入 finalizing 后处理状态后结束。
- **时间线一直显示「更新中」但无数据**:通常是轮询请求静默失败(网络 / 反向代理截断 SSE)。0.6.1 会显式暴露轮询失败,刷新页面或检查 Nginx 是否缓冲了响应即可。
- **升级后没有时间线数据**:确认数据库迁移 `000055_knowledge_processing_spans`、`000056_knowledge_pending_subtasks` 已执行(服务启动会自动迁移)。
## 15. 如何启用 OpenSearch 作为向量库?
0.6.1 新增了 OpenSearch 向量库驱动(k-NN)。在 **设置 → 向量库** 中新增 OpenSearch 引擎并填写连接地址、凭据即可;KB 可绑定该向量库。注意:
- 连接地址会经过 SSRF 策略校验,内网 / 回环地址需符合放行规则;可用「测试连接」先行校验。
- 集成测试与索引映射细节见 [`docs/dev/opensearch-integration-test.md`](./dev/opensearch-integration-test.md)。
## 16. 内置模型(builtin models)如何用 YAML 声明式管理?
0.6.1 起平台内置模型由 `config/builtin_models.yaml` 声明式驱动,支持 `${ENV}` 变量插值,并通过 `managed_by` 字段与漂移巡检保持数据库与 YAML 一致。常见问题:
- **改了 YAML 不生效**:内置模型在服务启动时做生命周期对账(drift sweep);确认重启了服务,且条目通过了 schema 校验(ID 长度、必填字段)。
- **Docker 下环境变量未注入**:`builtin_models` 依赖 `env_file` 数组形式注入变量,确认 compose 中按数组形式挂载了 `.env`。
- 参考样例:`config/builtin_models.yaml.example`。
## 17. 系统管理员(System Admin)与平台设置怎么用?
0.6.1 引入了系统管理员与统一平台设置面板(含平台审计日志),与空间内 RBAC 区分:系统管理员管理的是「平台级」配置,而非单个空间内的资源。首次启用需通过系统管理员 bootstrap 流程晋升首个管理员;撤销管理员权限有安全防护(避免误撤导致无人可管)。相关迁移为 `000053_system_admin_and_settings`。
## 18. 上传时如何自定义解析配置(process_config)?
0.6.2 起,文件 / URL / 文件夹上传可携带 `process_config`(`KnowledgeProcessOverrides`),在**本次批次**内覆盖知识库默认的解析引擎、分块、多模态(VLM / ASR)、问题生成、图谱抽取等设置,而不会改动 KB 全局配置。Web UI 在上传前会弹出确认对话框供调整;API 与 `weknora doc upload` 传同名 JSON 即可。
- **与 KB 默认配置的关系**:未传的字段沿用 KB 默认值;`graph_enabled` 仅在 `extract_config.enabled` 为 true 时生效。
- **重新解析**:`POST /knowledge/:id/reparse` 可在 body 中传 `process_config` 以新配置重跑解析,覆盖项会写入 `knowledge.metadata.process_overrides`。
- **图片 / 音频校验**:批次含图片时需 KB 已配置 VLM;含音频时需已配置 ASR,否则上传会被拒绝。
- 详见 [`docs/api/knowledge.md`](./api/knowledge.md)。
## 19. 升级到 0.6.2 后 `weknora` CLI 登录或 MCP 工具报错?
0.6.2 随附 **CLI v0.9**(破坏性变更),常见迁移:
- **`auth login` 不再创建 profile**:先 `weknora profile add <name> --host <url> --use`,再 `weknora auth login`;切换 profile 用全局 `--profile <name>`。
- **`auth logout` / `auth refresh` 去掉 `--name`**:作用于当前 active profile。
- **MCP 工具 `agent_invoke` 已更名为 `session_ask`**:外部 MCP 客户端需刷新工具 schema。
- **`agent create --kb` 改为 `--attach-kb`**;`doc delete --all` 与 `search chunks` / `search docs` 的 `--kb` 必填且支持名称或 ID。
- 新增 `weknora session stop <session-id>` 可中止进行中的 Agent 运行;仓库内附带 `weknora-rag-search` / `weknora-shared` 内置 Skills。
- 详见 [`cli/CHANGELOG.md`](../cli/CHANGELOG.md)。
## 20. pgvector 检索变慢或刚升级后需要做什么?
0.6.2 新增迁移 `000059_embeddings_hnsw_1024`,为 **1024 维** embedding(如 bge-m3)在 PostgreSQL pgvector 上创建 HNSW 索引。服务启动会自动执行迁移;若你使用其他维度,该索引可能不适用,需按自身 embedding 维度另行调优。升级后首次大批量入库期间索引构建可能占用额外 I/O,属正常现象。
## 21. 如何在网站嵌入 WeKnora 智能体(Embed Widget)?
0.6.3 起支持**嵌入渠道**:在 **集成中心** 或 Agent 编辑器中创建 embed 渠道,绑定自定义 Agent,获取渠道 ID 与发布 Token(`em_…`),将 `weknora-widget.js` 嵌入外部网页即可提供访客问答。
- **域名白名单**:必须在渠道配置中填写允许加载 Widget 的 Origin,否则 exchange 会返回 403。
- **安全模式(推荐)**:生产环境不要把 `em_…` 写在页面 HTML 里;由业务后端提供 `token-endpoint`,用发布 Token 调 `POST /api/v1/embed/:id/exchange` 换取短时令牌 `ems_…`(约 30 分钟有效)。详见 [`docs/embed-secure-mode.md`](./embed-secure-mode.md) 与 [`docs/embed-subdomain.md`](./embed-subdomain.md)。
- **限流**:渠道可配置每分钟 / 每日请求上限;超限返回 429。
- **子域部署**:若 embed 页面与 API 不同子域,参考 `docs/embed-subdomain.md` 配置 CORS 与 Nginx。
## 22. 文档如何设置多个标签?
0.6.3 将文档标签从单选升级为**多标签**(迁移 `000063_knowledge_multi_tags`)。在知识库列表可为文档打多个标签,侧边栏支持按标签筛选;**标签管理**抽屉可批量维护标签。API 上传 / 更新知识时传 `tag_ids` 数组(取代旧的单 `tag_id`)。
## 23. 如何批量重新解析文档?
在知识库文档列表框选多篇文档后,使用批量操作栏的 **重新解析**;也可调用 `POST /knowledge/batch-reparse`,body 可含 `ids` 与可选 `process_config`。任务异步入队,UI 会在入队后刷新状态。单篇仍可用 `POST /knowledge/:id/reparse`。
## 24. RSS 数据源如何配置?
0.6.3 新增 **RSS / Atom** 连接器。在知识库 **设置 → 数据源** 中选择 RSS,填写 Feed URL 与同步策略即可全量 / 增量拉取正文入库。若部分条目失败,同步日志会展示 partial failure 详情;编辑数据源保存配置**不会**自动触发同步,需手动点同步。
## 25. MCP 远程服务如何配置 OAuth2?
0.6.3 支持 MCP 服务的 **OAuth2 授权**(迁移 `000062_mcp_oauth`)。在 **设置 → MCP** 添加 HTTP 类型服务并选择 OAuth2,按向导完成授权回调;另支持自定义 HTTP Header 与 JSON **代码导入**快速粘贴配置。授权 Token 加密存储,过期后需在 UI 重新授权。
## 26. Embedding 维度如何覆盖?
在 **设置 → 模型** 编辑 Embedding 模型时可填写 **dimensions** 覆盖值(如 1024、1536)。0.6.3 修复了部分提供商请求未携带 `dimensions` 的问题(#1654)。若向量库索引维度与模型不一致,检索可能异常,请保持 KB 绑定向量库与模型维度一致。
## 27. Agent 提示「模型未就绪」无法对话?
0.6.3 在 Agent 选择器引入**模型就绪校验**:绑定的 LLM / Embedding / Rerank / VLM 缺失或配置无效时会阻断对话并给出修复指引。可在模型卡片打开 **调试抽屉** 先测试连通性;确认 KB 与 Agent 引用的模型均存在且可用。
## 28. 如何创建并限制权限范围 API Key?
0.7.0 引入**权限范围 API Key 与 Principal 模型**(迁移 `000064_principal_model`、`000065_tenant_api_keys`)。API Key 不再等同于某个人类用户,而是独立的 Principal,携带显式角色与能力(capability)授权:
- 在 **设置 → API 集成**(Owner 可见)中创建 Key,可勾选能力(如 `manage_kbs` 覆盖 KB 全生命周期、`manage_storage_backends` 等),并可限制到指定知识库。
- Key 的 `last_used_at` 按节流更新,避免高频写库。
- 路由级守卫会拒绝越权访问;管理类接口对 API Key Principal 默认拒绝,请为集成使用具备对应能力的 Key,而非全权 Key。
- MCP OAuth 与嵌入会话按 Principal 隔离,不同集成之间互不串号。
### 如何用一个 API Key 自动化管理多个空间?
SystemAdmin 可在 **系统管理 → 平台 API Key** 创建 `scope_type=platform` 的 Key。平台 Key 不绑定单一空间:调用普通空间 API 时必须携带 `X-Tenant-ID`,并继续受原有 capability 和知识库范围守卫约束;调用开放的系统控制面接口则需要对应的 `system_*` capability。平台 Key 不支持 `full_access`,也不能创建、轮换或吊销其他平台 Key。
## 29. 一个空间如何绑定多个对象存储实例?
0.7.0 支持**多实例存储后端**(迁移 `000068_storage_backends`)。一个空间可注册多个存储实例(`local` / `minio` / `cos` / `tos` / `s3` / `oss` / `ks3` / `obs`),不同知识库绑定到不同实例,空间维度还有一个默认实例:
- 在 **设置 → 存储后端** 创建/测试/设为默认(需 Admin+;API Key 需 `manage_storage_backends` 能力)。
- 未显式绑定的新知识库使用空间默认实例;响应中的 `access_key_id` / `secret_access_key` 会被掩码,更新时提交掩码占位符不会覆盖库中真实凭据。
- 若创建知识库时提示存储引擎不可用,请确认目标 provider 在 `STORAGE_ALLOW_LIST` 允许范围内。详见 [`docs/api/storage-backend.md`](./api/storage-backend.md)。
## 30. 后台解析/入库任务积压或需要排查失败任务怎么办?
0.7.0 新增系统管理员的**运行时任务队列面板**与 **Worker 池治理**。文档处理从单一聚合池改为分阶段独立池(core / 后处理 / enrichment / maintenance)+ 弹性共享池,Wiki 独立治理:
- 在 **系统设置 → 运行时队列** 查看队列深度、按模型并发统计、失败任务详情,并可手动重试。
- 可通过 `WEKNORA_ASYNQ_*_CONCURRENCY` 与 `asynq.*_concurrency` 系统设置调整各池并发(需重启服务);`model.max_concurrency` 用于约束单模型后台并发。
- 详见 [`docs/worker-pool-governance.md`](./worker-pool-governance.md)。注意:Worker 并发只是调度预算,仍受模型配额、DocReader 容量、向量库与数据库连接数限制。
## 31. 对话中如何临时上传图片/文档做一次性问答?
0.7.0 支持**会话级临时附件**(迁移 `000070_temporary_documents`)。在对话输入区上传图片或文档,系统异步解析后仅用于当前会话的问答,不会写入知识库。图片与附件共享一个合并数量上限;附件内容会在多轮对话中保留。
## 32. 如何接入 QQBot / Lark(飞书国际版)?
0.7.0 新增 **QQBot** 平台集成,并支持飞书国际版 **Lark**(区域感知路由)。在 **设置 → IM 集成** 添加对应渠道并填写凭据即可;飞书回复通过 reply-message 接口发送,回复会落在原消息线程内。
## 33. 如何为 Redis 启用 TLS?
0.7.0 支持 Redis 的 **TLS 连接**(#1930)。按环境变量启用 TLS 后,启动日志会打印 TLS 配置状态便于确认。若连接失败,请核对证书/CA 配置与 Redis 服务端是否要求 TLS。
## 34. 升级到 0.7.0 后 `weknora` CLI 命令找不到或行为变化?
0.7.0 随附 **CLI v0.10**(Agent 优先,破坏性变更):新增 `model` / `message` / `config` / `skills` 命令组,`doc reparse` / `doc update`,`kb config` / `kb config set`;`session continue` 更名为 `session resume`,新增 `session tool-approval`;提供 agent-first 的 chat 与 `session ask` 输出模式,并强化了 SSE 可靠性与类型化错误。详见 [`cli/CHANGELOG.md`](../cli/CHANGELOG.md)。
## 35. 如何接入云之家(Yunzhijia)?
0.7.1 新增 **云之家 IM 集成**。在 **设置 → IM 集成** 添加云之家渠道并填写应用凭据即可;集成基于 WebSocket 长连接接收消息,支持图片消息入库(带 SSRF 安全下载),默认以 **Markdown** 格式回复。若图片无法下载,请检查出站网络与凭据是否具备下载权限。
## 36. 如何使用火山引擎 Rerank / 智谱 AI 网络搜索?
0.7.1 新增两个供应商:
- **火山引擎 Rerank**:在 **设置 → 模型** 中添加 Rerank 模型并选择火山引擎。当单次请求文档数超过 API 上限时,客户端会自动分批发送并合并结果。vLLM Rerank 现默认不再发送 `truncate_prompt_tokens` 以提升兼容性。
- **智谱 AI 网络搜索**:在 **设置 → 网络搜索** 中选择智谱 AI 作为搜索供应商并填写凭据即可,用于 Agent 联网检索。
## 37. 升级到 0.7.1 后对话记忆(Memory)设置消失了?还需要 Neo4j 吗?
0.7.1 **移除了基于 Neo4j 的会话记忆(episodic memory)** 功能,相关 API 字段、设置项与嵌入开关一并下线,对话不再依赖 Neo4j 做记忆召回。**注意:知识图谱(GraphRAG / 图检索)仍然使用 Neo4j**,因此若你启用了图谱检索,Neo4j 依旧是必需组件,无需移除部署。若你此前仅为记忆功能部署 Neo4j 且未使用图谱,可按需精简。
## 38. 官方文档在哪里看?如何本地或独立部署文档站?
0.7.2 新增了完整的官方产品文档,位于仓库 [`website-docs/`](../website-docs/README.md) 目录,按「入门 → 架构 → 功能 → API → 客户端 → 开发」六个板块组织,覆盖约 360 个 API 端点、约 150 个环境变量与 9 大扩展点。
该目录现在包含官网与 VitePress 文档站,统一构建和部署。以下命令分别从仓库根目录执行:
```bash
# 本地预览(需要 Node.js 24)
(cd website-docs && npm run setup && npm run build && npm run preview)
# 独立容器部署(容器内完成构建,Nginx 监听 80)
docker build -t weknora-site website-docs
docker run -d -p 8081:80 weknora-site
```
官网位于 `/`,文档位于 `/docs/`。从旧文档容器迁移时注意将反向代理目标端口改为 `80`,并让域名根路径指向同一容器。站点版本号在构建时读取 `website-docs/VERSION`,发布时需同步更新;该目录可独立复制构建。完整部署说明见 [website-docs/README.md](../website-docs/README.md)。若某处截图显示为虚线占位框,说明 `website-docs/public/screenshots/` 下缺少同名图片,补图即可生效,不需要改 Markdown。
`website-docs/sample-data/` 下还提供了 4 份 Markdown 样例文档与 1 份 FAQ 导入 JSON,可以直接用来跑一遍「建库 → 上传 → 问答」;`examples/mcp-demo/` 是一个可直接运行的本地 MCP 服务示例。
## 39. 文件夹上传后文档标题变成了一长串路径?
这是 0.7.2 之前的行为:文件夹上传会把相对目录塞进 `file_name`,导致列表里显示整条路径,也无法按文件夹筛选。
0.7.2 把路径拆到独立的 `folder_path` 字段(迁移 `000079_knowledge_folder_path`),并**自动回填历史数据**,因此升级后已有知识库同样会呈现正确的文件夹树,无需重新上传。文档列表左侧会出现文件夹树,可以像文件管理器一样浏览、重命名文件夹,也可以通过行内的文件夹选择器把文档重新归档到其他文件夹。单独上传(非文件夹)的文档统一挂在树的根目录下。
## 40. 分块内容不准确,可以手动修改吗?改完会重新建索引吗?
可以。0.7.2 支持在界面上直接编辑检索分块(迁移 `000078_chunk_editing_and_custom_metadata`):
- 每次编辑都会把改动前的版本存入 `chunk_revisions`,可在「分块编辑历史」里逐版本查看 diff 并一键回滚。
- **编辑保存后会自动重建该分块的索引**(`index_status` 字段跟踪重建状态),无需手动 reparse。
- 分块的生成问题可以单独增删改与重新生成,且在内容编辑后仍会保留。
- 注意:重新解析(reparse)整篇文档会按新的解析结果重建分块,此前的人工编辑不会被保留,请谨慎操作。
## 41. Wiki 页面被 Agent 覆盖了,能找回旧版本吗?
能。0.7.2 为 Wiki 页面引入版本历史(迁移 `000075_wiki_page_revisions`):页面每次被覆盖前都会留存一份快照,在 Wiki 浏览器右上角打开「版本历史」抽屉即可查看完整历史、行级 diff,并一键回滚到任意版本。每个版本都会记录来源(`pipeline` 流水线 / `agent` 修复工具 / `user` 手动编辑 / `revert` 回滚),便于判断是谁改的。页面也支持在浏览器内直接手动编辑。
另外,0.7.2 移除了 Wiki 浏览器里重复的操作日志(迁移 `000077_remove_wiki_log`),Wiki 的变更记录统一并入**知识库活动流**查看。
## 42. 第三方 App 拿到的图片链接是 `resource://...` 无法显示,怎么办?
默认情况下 API 返回的是内部句柄 `resource://<handle>`,客户端需要再调用带鉴权的 `/files` 代理才能取到图。0.7.2 新增直链模式,让接口直接返回可加载的 http(s) 链接:
- **单次请求**:在 URL 上加 `?resource_urls=public`。
- **整个部署**:设置环境变量 `RESOURCE_URL_MODE=public`。
注意事项:
- 直链依赖 `APP_EXTERNAL_URL`(或存储后端本身公网可达)才能生成;无法生成时该引用会保持 `resource://` 原样,客户端仍可回退到 `/files`。
- `public` 会为每个被引用文件签发**限时匿名可读**链接(WeKnora 侧 2 小时,MinIO 24 小时),请评估是否符合你的安全要求。
- 匿名的 embed 渠道与限定了知识库范围的 API Key **始终返回 handle**,不受该变量影响。
- 建议同时配置 `SYSTEM_AES_KEY`,以便复用 grant 行、稳定直链 URL 并降低读接口的写入压力。
详见 [API 文档 · 文件与图片引用](./api/README.md)。
## 43. 使用 AWS S3 但不想在配置里写 AK/SK?
0.7.2 支持 **AWS SDK 默认凭据链**(#2008):把 `S3_ACCESS_KEY` 与 `S3_SECRET_KEY` **同时留空**即可,SDK 会依次尝试 EC2/ECS/EKS 实例角色、IRSA / Web Identity、环境变量与共享配置文件。注意两者必须同时填写或同时留空,只填一个会报配置错误。`S3_ENDPOINT` 也可留空,此时使用 `S3_REGION` 对应的 AWS 标准端点。
## 44. MCP Server 用 `uvx` 启动失败,或者应该装哪个包?
请安装**官方包 `tencent-weknora-mcp`**(由 Tencent/WeKnora 仓库 CI 通过 Trusted Publishing 发布)。此前社区包 `weknora-mcp` 非官方维护,请迁移安装命令。
0.7.2 随附 MCP Server 1.1.x,已迁移到 mcp 2.x 的高级 `MCPServer` API,修复了 `uvx` 拉到 SDK 2.x 时的启动崩溃(`AttributeError: 'Server' object has no attribute 'list_tools'`),并恢复了 HTTP(`stateless_http`)与 SSE(`/sse/messages/`)传输的路由兼容性。工具总数为 29 个,新增 `create_knowledge_from_text`(用 Markdown 文本直接建知识条目)与 `list_shared_knowledge_bases`(共享知识库也纳入按名称解析)。
行为变化提醒:工具执行失败时,MCPServer 2.x 返回 `CallToolResult(isError=True)`,不再像旧版低层 API 那样以成功响应返回 `"Error executing …"` 文本前缀。只解析 `content[0].text` 的客户端通常无感,依赖 `isError` 标志的集成方行为会更符合 MCP 规范。
## 45. 升级到 0.8.0 后技能沙箱起不来 / 找不到 Local 后端?
0.8.0 **移除了 Local 宿主机进程沙箱**。技能执行改为会话级常驻沙箱,三个后端共用同一套协议:
- **Docker**(单机 / 私有化):默认**关闭**。本机 `docker.sock` 等同宿主机 root,需系统管理员在 **设置 → 系统设置 → 网络安全** 打开,或设置 `WEKNORA_SANDBOX_DOCKER_ENABLED=true`。打开后才会出现「添加 Docker 后端」入口;已有配置仍可查看/删除。
- **E2B**:E2B Cloud,或任意 E2B 兼容控制面(含自托管)。
- **CubeSandbox**:集群模板 + 网络策略。
原 Local 配置需要按上面任一后端重建。每个空间可配多个沙箱实例,并可为每个配置设置**网络策略**(默认放行出站、关闭公网入站;可改成默认拒绝出站再写允许名单)。详见 [`docs/sandbox-docker-backend.md`](./sandbox-docker-backend.md) 与 [`docs/sandbox-protocol.md`](./sandbox-protocol.md)。
## 46. 技能目录和沙箱配置是什么关系?安装一直转圈怎么办?
0.8.0 把技能做成空间级目录(迁移 `000086_tenant_skills` / `000090_skill_catalog`),再**按沙箱配置安装成快照**:
1. 在 **设置 → 技能沙箱** 建好后端配置;
2. 从 ClawHub(`@owner/slug`)、SkillHub / skills.sh、GitHub/GitLab URL 或 zip 上传安装;
3. 安装抽屉会保持打开并显示环形进度;卡住时用「停止安装」,再用「重新安装」走已保存的安装包。
环境变量分两层:**空间级**(Admin,该空间所有人共用)和**个人级**(`/api/v1/me/env-vars`,值永远不会读回)。技能声明的 `WEKNORA_*` 凭据可以按人填写。卸载沙箱里的技能不会删掉目录里的安装包。
## 47. 0.7.1 删了 Neo4j 会话记忆,0.8.0 的「长期记忆」是一回事吗?
不是。0.7.1 去掉的是旧版 **Neo4j episodic conversation memory**;**知识图谱(GraphRAG)仍然用 Neo4j**。0.8.0 的长期记忆是全新产品(迁移 `000084_memory`):
- 空间管理员先打开,用户还可以再关掉自己的;
- 类型:`profile` / `preference` / `fact` / `task` / `interest`;
- 自动抽取的条目先停在「待确认」,不会静默写进提示词;
- 常驻画像每轮注入,情境记忆按需召回,Agent 也可用 `search_memory`;
- 反复引用的文档会形成亲和度,检索时加权。
接口在 `/api/v1/memory/*`,只操作当前调用者自己的记忆,需要 full-access API Key 或登录会话。
## 48. 文档解析能否不经过 docreader?anydoc 是什么?
0.8.0 引入进程内 **anydoc** 引擎(`third_party/anydoc-go`)。当绑定已链接时,anydoc 能转换的格式(含 doc/docx/ppt/pptx)会优先走 Go 进程,不再先打到 docreader。PPT/PPTX 在没有引擎规则时仍默认 MarkItDown。官方 app 镜像默认链接 anydoc。解析失败或格式不在 anydoc 覆盖范围时,仍回退到 docreader / MarkItDown / MinerU 等既有引擎。
## 49. OIDC 登录提示签名无效,或想跳过前端直接 302?
0.8.0 会通过 JWKS **校验 ID Token 签名**(#2799),显式配置的 token endpoint 同样走这条路径。请确认 IdP 的 JWKS URL 可达、密钥已轮换到当前 kid。若要做门户级跳转,可调用 `GET /auth/oidc/start` 直接 302 到 IdP,不必先渲染 SPA 握手页。
## 50. 开启复杂密码后注册 / 改密失败?
系统设置或 `WEKNORA_AUTH_COMPLEX_PASSWORD_ENABLED=true` 打开后,密码必须同时包含大写、小写、数字和特殊字符(`!@#$%^&*()_+-=[]{}|;:,.<>?`),长度 8–32。注册、个人中心改密、管理员重置走同一套规则。未打开时仍只要求长度。
## P.S.
如果以上方式未解决问题,请在issue中描述您的问题,并提供必要的日志信息辅助我们进行问题排查

View File

@ -1,263 +0,0 @@
# 空间 RBAC 说明
本文档介绍 WeKnora **空间内权限控制(Workspace RBAC)** 的设计、角色矩阵、资源归属模型、配置方式,以及它与 [共享空间](./共享空间说明.md) 之间的关系。
> 状态:已随 #1303 发布,由配置项 `tenant.enable_rbac` 控制,默认 `true`(强制鉴权)。可临时切到 `false` 进入「仅记录不拦截」的灰度窗口。
## 一、为什么需要 RBAC
在 RBAC 引入之前,只要通过 `X-API-Key` 或 JWT 认证成功,调用方在空间内基本等同于管理员。这在单人自部署场景没问题,但只要一个空间里出现两个及以上的真人成员(团队共享一套知识库),就必须区分:
- 谁可以删除知识库、撤销 API Key(管理员/Owner);
- 谁可以上传文档、编辑「自己」的知识库(Contributor);
- 谁只能读取与提问(Viewer)。
RBAC 在原有 JWT / API Key 认证之上,叠加了一层**空间内角色矩阵**,使三种状态都成为一等公民。
## 二、角色矩阵
每个空间成员(`tenant_members` 一行)拥有且仅拥有一个角色:
| 角色 | 标识 | 典型场景 | 关键能力 |
|------|------|----------|----------|
| 只读 | `viewer` | 只查阅、提问的成员 | 仅读,不可发起任何变更 |
| 贡献者 | `contributor` | 上传文档、维护自己的 KB / Agent | 可变更 `creator_id == 自己` 的资源;他人资源等同 Viewer |
| 管理员 | `admin` | 空间内运维 | 可变更空间内任意资源;管理成员;配置共享基础设施(模型、解析器、存储、向量库等) |
| Owner | `owner` | 空间所有者 | Admin 的全部权限 + 可删除空间;每个空间**至少有一位,可以有多位** |
角色按 `viewer < contributor < admin < owner` 递增,高角色继承低角色权限。
Owner 的数量约束是“至少一位”,而不是“只能一位”。系统允许同一空间存在多个活跃 Owner;降级或移除 Owner 时,只有会导致空间失去最后一位 Owner 的操作才会被拒绝。
### 鉴权层的两个例外
- **跨空间超管**:`User.CanAccessAllTenants=true` 且 `enable_cross_tenant_access=true` 时,通过 `X-Tenant-ID` 切换到目标空间后等同 Admin,不需要在目标空间里有 `tenant_members` 行。用于多空间运营方。
- **API Key 调用**:`X-API-Key` 合成的虚拟用户在其所属空间内固定为 Admin(仅删除空间仍需 Owner)。脚本集成无需迁移。
- **孤儿空间自愈**:若一个空间在 `tenant_members` 表里没有任何活跃成员(典型场景:仅 API Key 使用过该空间),首位通过认证的真人会被自动晋升为 Owner,避免锁死。
## 三、资源归属模型
光有角色矩阵不够,否则 Contributor 之间可以互相破坏。为此在迁移 `000043` 中给关键表加了 `creator_id`:
- `knowledge_bases.creator_id` —— 老数据回填为该空间的 Owner;空串/NULL 表示「空间共有,仅 Admin+ 可变更」。
- `custom_agents.creator_id` —— Agent 创建者。
- `custom_agents.runnable_by_viewer` —— 默认 `true`,允许 Viewer 在对话中调用该 Agent;置 `false` 则提升到 Contributor 起步。
子资源沿着归属链回溯到 KB 的 `creator_id`:
```
chunk_id ─► knowledge_id ─► kb_id ─► knowledge_bases.creator_id
```
FAQ 条目、生成的问题、KB 标签、Wiki 页面同理。
由此衍生出两类守卫:
- **角色守卫**:`Viewer()` / `Contributor()` / `Admin()` / `Owner()` —— 只看角色。用于空间级基础设施(模型、向量库、IM 通道等)。
- **归属守卫**:`OwnedKBOrAdmin()` / `OwnedAgentOrAdmin()` / `OwnedChunkKBOrAdmin()` …… —— 「我是这条资源的 `creator_id`」**或**「我至少是 Admin」二者满足其一即可。用于具体资源的写操作。
这样可以让「Contributor 在自己的 KB 里像 Owner,在别人的 KB 里像 Viewer」自然成立。
## 四、与共享空间的关系(重点)
[共享空间](./共享空间说明.md)(Organization)和空间 RBAC 解决的是**不同维度**的问题,必须同时满足才能完成一次跨空间操作:
| 维度 | 解决什么 | 主键模型 | 角色集合 |
|------|---------|---------|---------|
| **空间 RBAC** | 同一空间内「你能对自己 / 别人 / 共享基础设施做什么」 | `tenant_members(user_id, tenant_id, role)` | viewer / contributor / admin / owner |
| **共享空间** | 跨空间「把我的 KB / Agent 让别的空间的人也用」 | `organization_members(user_id, org_id, role)` + 共享关系表 | 管理员 / 编辑者 / 只读 |
两者**正交**:
- 共享空间不持有任何 KB 或 Agent,它只是「某 KB 以某权限被共享到某空间」的关系记录。
- 资源始终归属一个空间,归属与 `creator_id` 都不会因为共享而改变。
- 一次对**他人共享给你**的 KB 的写操作,需要同时满足:
1. **共享一侧**:该 KB 被以「可写」权限共享到了你和发起方都在的共享空间;
2. **空间角色一侧**:你在该共享空间内不是「只读」(即至少是编辑者);
3. **空间 RBAC 一侧**:你的访问通过共享路径解析为对源空间的「以共享空间身份」访问,仍要经过源空间的 RBAC 检查。具体地,访问检查会在确认 `kb.tenant_id == 你的当前空间` 不成立后,回落到共享路径校验。
简化的判定顺序(见 `internal/middleware/kb_access.go`):
```text
┌────────────────────────┐
│ KB 属于我当前空间? │ ──是──► 进入空间 RBAC:
└──────┬─────────────────┘ 角色 + creator_id 决定能否写
否
▼
┌────────────────────────┐
│ KB 通过共享空间分享给 │ ──否──► 403 / 404
│ 我所在的某个空间? │
└──────┬─────────────────┘
是
▼
┌────────────────────────┐
│ 我在该空间是 viewer? │ ──是──► 只读
│ │ ──否──► 按共享时设定的「只读/可写」执行
└────────────────────────┘
```
要点整理:
- **共享空间不会绕过空间 RBAC**:若一个 KB 在源空间里被标记为「仅 Admin+ 可写」(例如 `creator_id` 为空的空间共有 KB),即使共享时给了「可写」权限,外空间成员也只能读取——因为没人能跨空间成为源空间的 Admin。
- **API Key 跨空间访问**:API Key 在所属空间内是 Admin,但**不会**因此自动获得对其他空间通过共享空间共享过来的 KB 的写权限——共享空间使用的是 `organization_members.role`,与 API Key 无关。
- **审计也是分开的**:空间内角色变更写入 `audit_logs`(`rbac.member_*` 动作),共享空间内的成员、共享关系变更由共享空间自身的接口记录。
一句话总结:**空间 RBAC 是「纵向」的纵深防御,共享空间是「横向」的协作通道;任何跨空间的有写副作用的操作,都要同时穿过这两道闸口。**
## 五、配置
`config/config.yaml`:
```yaml
tenant:
# 默认 true,强制鉴权。改为 false 进入「仅记录不拦截」灰度窗口
enable_rbac: true
# 跨空间超管开关,默认 false
enable_cross_tenant_access: false
auth:
# self_serve(默认):任何人都可注册,自动建空间 + Owner 成员
# invite_only :禁止公开注册,新用户必须通过 /tenants/:id/members 邀请进入
registration_mode: self_serve
audit:
# 审计日志保留天数;每日后台清理;默认 90;置 0 关闭清理
retention_days: 90
```
环境变量(优先级高于 YAML):
| 环境变量 | YAML 路径 | 取值 |
|----------|-----------|------|
| `WEKNORA_TENANT_ENABLE_RBAC` | `tenant.enable_rbac` | `true` / `false` |
| `WEKNORA_AUDIT_RETENTION_DAYS` | `audit.retention_days` | 非负整数 |
`auth.registration_mode` 没有专属环境变量,沿用历史的 `DISABLE_REGISTRATION=true`——一旦设置,启动时会把 `auth.registration_mode` 强制改成 `invite_only`,保证后端 API 和 `/auth/config` 驱动的前端注册入口一致。
启动日志会打印一行总结,确认本次启动到底使用了哪一组配置以及覆盖来源。
## 六、审计日志
`audit_logs` 表统一记录权限相关事件:
| Action | Outcome | 触发时机 |
|--------|---------|----------|
| `rbac.member_added` | success | `POST /tenants/:id/members` 成功 |
| `rbac.member_removed` | success | `DELETE /tenants/:id/members/:user_id` 成功 |
| `rbac.member_role_changed` | success | `PUT /tenants/:id/members/:user_id` 成功 |
| `rbac.member_left` | success | `POST /tenants/:id/members/leave` 成功 |
| `rbac.access_denied` | denied | `RequireRole` / `RequireOwnershipOrRole` 拒绝时(**仅 enforcement 开启时**) |
`access_denied` 采用 1 分钟滑动窗口去重,防止恶意探测刷表;同样的拒绝在应用日志(`[rbac] role insufficient ...`)里仍然条条可见。
知识库活动记录也复用这张不可变审计表,通过 `scope_type=knowledge_base`、`scope_id=<kb_id>` 建立范围索引,而不是为每个知识库创建独立日志表。`GET /api/v1/knowledge-bases/:id/activity` 提供游标分页,覆盖知识库配置、知识/FAQ、标签、数据源、共享、克隆/移动任务和 Wiki 内容变更;原有空间审计接口只返回无资源范围的 RBAC 事件,避免知识库活动淹没成员与拒绝记录。解析阶段明细继续由 knowledge spans 展示,数据源同步明细继续由 sync logs 展示,活动记录只保存摘要与关联 ID。
该接口仅知识库创建者或所属空间 Admin+ 可读,并明确拒绝从组织共享空间读取,避免向接收方泄露源空间操作者与配置历史。活动详情不得写入知识正文、外部 URL、数据源凭据或原始错误堆栈。
后台 goroutine `AuditLogRetentionRunner` 启动 ~10 分钟后开始首轮清理,之后每 24 小时清扫一次超过 `audit.retention_days` 的旧行;保留期为 `0` 时整条 goroutine 短路,不产生任何 DB 流量。
## 七、灰度上线建议
无论是自部署运维还是上游仓库本身,从「仅记录」切到「强制鉴权」都建议走以下流程:
1. **升级**:若想保留观察窗口,升级前先设置 `tenant.enable_rbac=false`(或环境变量)。否则默认就是强制鉴权——schema 落地、`tenant_members` 自动回填(每空间一个 Owner,其余 Contributor)、所有 KB 自动写入 `creator_id`。
2. **核对成员**:调用 `GET /api/v1/tenants/:id/members` 确认:
- 每个空间都只有一位 Owner;
- Contributor / Viewer 划分符合预期;
- 通过 `PUT /api/v1/tenants/:id/members/:user_id` / `DELETE` 调整。每次调整都会写入 `audit_logs`。
3. **观察日志**:抓取应用日志里的 `[rbac] role insufficient (logged but not enforced) ...`,这些就是切换到强制鉴权后会变成 403 的请求。逐条修正成员角色或客户端身份。
4. **切回强制鉴权**:删除 `tenant.enable_rbac=false` 覆盖(或显式置 `true`),重启服务。此后:
- 角色不足 → 403;
- 同时写入 `audit_logs.rbac.access_denied`(受去重控制)。
5. **可选:禁用公开注册**:把 `auth.registration_mode` 改为 `invite_only`。登录页注册入口会自动消失,`POST /auth/register` 直接 403。
### 回滚
```bash
export WEKNORA_TENANT_ENABLE_RBAC=false
# 重启服务即可回到观察模式
```
`tenant_members` 行与 `creator_id` 列保留,下次再启用无需重做回填。除非彻底放弃这个功能,否则**不要**回滚 `000043` / `000044` 迁移——`down.sql` 会丢弃 `tenant_members` 和 `audit_logs` 整张表。
## 八、前端表现
Pinia 中的 `authStore` 暴露:
- `authStore.currentTenantRole`:成员信息加载完成前为 `''`(loading 信号,按钮等待解析后再渲染,避免「先亮再灰」的闪烁);之后为四种角色之一。
- `authStore.hasRole('admin')` 等:按层级判断的便捷函数。
- 各资源页面再叠加 `isOwner`(如 `kb.creator_id === authStore.user?.id`)做 per-resource 判断。
这是后端守卫的镜像:**任何在后端会 403 的按钮,前端直接隐藏而不是让用户点了再吃错误。**
### 前端实际界面
<table>
<tr>
<td colspan="2" align="center">
<b>成员管理页</b><br/>
<img src="./images/rbac-member-management.png" alt="成员管理" width="100%"/>
<br/><sub>同时展示「待接受的邀请」和「空间成员」两组列表;只有 Owner 可以新增 / 移除成员;右上角的「审计日志」入口跳转到 <code>audit_logs</code> 视图。</sub>
</td>
</tr>
<tr>
<td width="50%" align="center">
<b>用户菜单 + 工作区切换器</b><br/>
<img src="./images/rbac-workspace-switcher.png" alt="用户菜单 + 切换空间" width="100%"/>
<br/><sub>左侧:当前空间角色徽章 / 设置入口 / 退出;右侧:切换到其它空间,「当前」角标标识活跃工作区。</sub>
</td>
<td width="50%" align="center">
<b>自助创建工作区</b><br/>
<img src="./images/rbac-create-workspace.png" alt="创建新空间" width="100%"/>
<br/><sub>任何用户都可以自助创建空间,创建后自动成为新空间的 Owner(受 <code>WEKNORA_TENANT_MAX_PER_USER</code> 上限保护)。</sub>
</td>
</tr>
<tr>
<td colspan="2" align="center">
<b>待处理邀请弹窗</b><br/>
<img src="./images/rbac-pending-invitation.png" alt="我的邀请" width="80%"/>
<br/><sub>用户菜单上的邀请铃铛会展示来自其它空间的待处理邀请,可直接「接受 / 拒绝」;7 天未响应自动过期。</sub>
</td>
</tr>
</table>
## 九、常见问题
### 升级后所有人都变成了 Contributor,找不到 Admin?
回填逻辑选「每个空间里最早活跃的用户」作为 Owner,其余人统一变成 Contributor。如果创建空间的账号其实是一个机器人 / 共用账号,可能需要先用 `PUT /api/v1/tenants/:id/members/:user_id` 把机器人降级、把真人 Admin 提升。
### 切到强制鉴权后某个脚本开始 403?
大概率脚本的 JWT 对应的成员是 Viewer / Contributor 而非 Admin。两种解法:
- 通过 `tenant_members` 把对应用户升级到 Admin;
- 或者把脚本切到 `X-API-Key` 调用 —— API Key 在所属空间内固定 Admin。
### 共享空间里的成员为什么读不到我「以可写共享」过去的 KB?
请按第四节的判定顺序排查:
- KB 是否真的属于源空间、`tenant_id` 配置是否正确;
- 该共享关系当前是否还存在(未被取消);
- 调用方在共享空间里是不是 Viewer;
- 若 KB 的 `creator_id` 在源空间内为空且共享权限要求写,源空间的 RBAC 仍会要求 Admin+,导致跨空间写无法成立。
### 审计日志怎么有些 403 没记录?
两种可能:
- 1 分钟滑动窗口去重,同一 `(actor, path, action)` 一分钟内只会写一行。完整序列在应用日志里。
- `tenant.enable_rbac=false` 时仅记录成员管理事件,不写 `rbac.access_denied`。
### 我能不能做比「角色 + 归属」更细的 ACL?
v1 不支持。这个矩阵刻意保持成一个小固定格(Viewer < Contributor < Admin < Owner)+ 每种资源一个「creator escape hatch」。再细的策略(例如「Viewer 可以看自己的审计日志」)属于后续。
## 十、测试与可观测性
- `make test` 覆盖 `internal/middleware/rbac_test.go`、`internal/handler/rbac_lookups_test.go`、`internal/application/service/audit_log_test.go`、`internal/middleware/rbac_audit_test.go` 等约 25 个用例。
- Langfuse / OpenTelemetry span 上携带解析后的 `TenantRole` 和 `TenantID`,一次被拒绝的请求在 trace 中即可看到对应角色,不需要再去手工关联日志。
## 相关文档
- 跨空间协作:[`共享空间说明.md`](./共享空间说明.md)
- 多空间认证背景:[`OIDC认证调用流程.md`](./OIDC认证调用流程.md)
- 配置项与环境变量:[`.env.example`](../.env.example)

17
docs/README.md 100644
View File

@ -0,0 +1,17 @@
# 文档已迁至 website-docs
产品、部署、API 和开发文档统一维护在 [website-docs](../website-docs/README.md)。已迁移、重复和过时的旧手写文档已删除;历史内容可从 Git 历史查看。
- [常见问题与升级排障](../website-docs/01-getting-started/05-troubleshooting.md)
- [API 参考](../website-docs/04-api/01-api-overview.md)
- [开发指南](../website-docs/06-development/01-dev-guide.md)
- [迁移对应表与剩余依赖](../website-docs/MIGRATION.md)
本目录仅保留以下工程资源及本入口说明:
- `docs.go`、`swagger.json`、`swagger.yaml` 与契约测试:参与后端编译和测试,生成物仍由 `make docs` 更新。
- `LITE.md`:Lite 发布包复制为离线 README。
- `images/`、`assets/`:README、Helm 等仍使用的图片资源。
- `poc/docker-sandbox/`:独立 Go 实验模块,保留源码和运行说明,不作为当前产品指南。
这些资源尚有编译、发布或历史实验用途,不能直接整目录删除。新的产品说明不要再放入此处。

View File

@ -1,46 +0,0 @@
# WeKnora Roadmap
本文档描述 WeKnora 的产品规划与计划方向,会随项目进展持续更新。
## 轻量化部署
- [ ] WeKnora 官方提供原子化调用接口(Embedding、ReRank、LLM、文档解析等),并提供一定免费使用额度
- [ ] WeKnora 官方提供完整云端服务,用户可在平台上直接体验 WeKnora 能力
- [ ] 推出 WeKnora Lite 版本,供私有化部署需求不强的用户快速体验产品能力
## 知识理解
- [x] 抽象整体文档解析模块,支持切换内置解析、MinerU 或其它解析方式
- [ ] 优化文档分块策略,除规则分块外支持语义分块、章节分块等
- [ ] 文档结构可视化:展示解析后的文档章节结构、图谱关系等
- [ ] 支持音视频等更多文档格式,增强多模态理解能力
## 检索与总结
- [ ] 支持在输入框中通过「@标签」指定检索范围
- [ ] 支持在输入框中上传图片、附件进行检索
- [x] 支持对话框中上传图片
- [ ] 支持对话框中上传附件
## 知识库相关模型训练
- [ ] 训练与检索召回相关的模型(Embedding、ReRank、LLM 等)
- [ ] 在文档解析与文档理解方面持续探索,推进自研相关模型
## 知识库形态
- [ ] 扩展知识库形态,支持时序数据的存储与索引
- [ ] 探索知识库与 Memory 结合的应用场景
## IM 集成
- [x] 支持与企微、飞书等 IM 系统集成,在 IM 内使用 WeKnora 能力
## 组件与扩展
- [ ] 鼓励社区维护各厂商的模型服务、网络搜索服务等组件
- [ ] 鼓励社区提供更多与知识库相关的 Skills
## 周边生态建设
- [ ] 提供 Chrome 扩展,支持类似「剪藏」功能,将网页内容保存至知识库并支持检索、总结、问答
- [ ] 提供小程序插件(具体形态待定)
- [ ] 提供 JS SDK,便于在网页中集成 WeKnora 能力
- [ ] 鼓励社区提供 VSCode、Cursor、Claude Code 等编辑器/IDE 插件
## 文档建设
- [ ] 完善官方文档(使用说明、API、部署等)
- [ ] 鼓励用户贡献文档、博客、视频等,形成社区化文档体系
- [ ] 在知乎平台建设 WeKnora 内容合集

View File

@ -1,139 +0,0 @@
# 对话提示词拼装与可编辑范围
## 维护入口
智能推理的唯一系统提示词拼装入口是 `internal/agent/prompts.go` 中的
`BuildSystemPromptSections`。`AgentEngine.buildSystemPrompt` 和字符串兼容接口
`BuildSystemPromptWithOptions` 都使用该入口。
| 段名 | 来源 | 职责 |
| --- | --- | --- |
| `base` | 用户自定义正文、引用模板或当前模式默认模板 | 角色、领域工作流、业务要求 |
| `steering` | `steerGuidance` | 处理中途补充,保留未完成任务 |
| `runtime_contract` | `runtimePromptContract`、`types.SourceDataBoundaryPrompt` | 数据与指令边界、当前文档范围、完成条件 |
| `sources` | `grounding_prompt.go`,浏览器分支引用 `prompts_browser.go` | 依据实际工具集合确定本轮来源规则 |
| `tools` | `formatToolGuidance` | 通用执行、文件和沙箱约定;具体参数保留在工具定义中 |
| `skills` | 当前安装且可用的 Skill 元数据 | 按需加载 Skill;本地浏览器可用时避免重复的 browser Skill 入口 |
| `output` | `types.SourcedAnswerOutputPrompt` | 用户输出格式、条件配图和完成检查;在初始系统段中固定注入 |
| `memory` | 本轮召回的记忆封装 | 用户和历史任务背景 |
| `protocol` | `modelcontext.Registry` | 来源句柄与输出引用协议 |
空段不会输出。日志 `[Agent][Prompt] section=... bytes=...` 记录每段大小;现有
LLM debug 日志仍记录最终消息和工具定义。分段本身不是模型 API 的权限层级。
用户正文与运行时规则仍处于系统提示词中;可调用工具的权限由后端注册与执行路径强制控制。
不要通过在多个模板中重复加入“最高优先级”来实现权限控制。
浏览器的操作契约单独维护在 `internal/agent/tools/browserskill_prompt.go`,通过
`local_browser` 的工具描述提供;不会复制进用户可编辑正文。它负责观察与 ref 有效期、
操作顺序、停止猜测路径、人工步骤及任务窗口生命周期。参数由 `browserskill_schema.go`
定义和校验,错误恢复与结果判断由 `browserskill_result.go` 负责。上游 CLI Skill 不直接
注入,以免引入 shell、session start 和安装指令。
“个人设置 → 浏览器连接”提供浏览器搜索指令编辑器。只保存用户的搜索偏好,默认仅为
搜索引擎和 URL 模板两行;通用搜索/操作方法留在工具描述和错误恢复提示中,不重复追加。
唯一默认值是 `types.DefaultBrowserSearchInstructions`,`GET /auth/me` 返回它供编辑器展示。
`PUT /auth/me/preferences` 保存 `browser_search_instructions` 到当前用户的 JSON 偏好;
留空或保存默认文本即恢复继承,不需数据库迁移。浏览器启用的新请求通过 UserRepository
读取当前调用者的偏好,替换默认搜索段;共享 Agent 不使用创建者的个人偏好。浏览器关闭时
不读取或注入这一段。保存不影响已经运行的请求。
适配层保留 RPC 的 code/message/data(大 data 限制为恢复分类),跨节点传递同样的
结构,同时保留旧字符串错误以兼容旧节点。evaluate 的 `ok:false` 属于执行失败;
request_help 只有 `continued`/`completed` 允许继续,其他结果阻止当前轮的后续浏览器
操作。失败仍保留原始工具输出供模型检查。一般页面中的“error”文字不等于 RPC 失败。
## 不同场景
| 场景 | 系统提示词及模型输入 |
| --- | --- |
| 智能推理,无自定义正文、无知识库 | `pure` 默认模板 + 运行时各段 |
| 智能推理,无自定义正文、有知识库 | `rag` 默认模板 + 运行时各段;知识库目录在当前 user 的 `runtime_context` 中 |
| Wiki / 数据分析等类型 | 引用该类型模板作为 `base`;运行时来源选择和工具范围仍独立生效 |
| 用户自定义 Agent 正文 | 自定义正文替换 `base`,不移除运行时各段,也不增加工具权限 |
| 浏览器关闭 | 不注册 `local_browser`,不注入选中浏览器的指令;知识库、Web、MCP、Skill 范围保持原配置 |
| 浏览器开启且可用 | 注册 `local_browser`;适用的网站查询、阅读、交互应使用浏览器;知识库是补充而非前置步骤 |
| 浏览器开启但服务不可用 | 创建引擎失败并返回明确错误,不默默改用其他浏览器 |
| 普通问答 | 解析系统提示词和上下文模板;意图分支可替换系统正文,再拼来源数据边界、公共输出规则、记忆和来源协议;历史及当前用户内容保留原消息角色 |
| 模型兜底 | 使用独立兜底模板及来源数据边界,不套用“只能回答检索结果”的 RAG 模板 |
| 超出轮数 / 模型错误收尾 | 沿用当前完整消息列表,包含历史、图片、工具调用配对和已注入的 steer;不再从步骤列表重造 user 消息;最后一次请求不提供工具,并设置 `tool_choice=none` |
浏览器按钮控制**下一次提交请求**的能力和来源选择,不中断正在执行的请求,
也不等价于预览卡片的“暂停 / 结束浏览器任务”。已配对不等于本轮已开启。
来源选择规则不会要求无网站需求的任务打开无关网页;用户本轮明确的来源限制可收窄或覆盖按钮选择。
Web 开启状态占位符与来源提示都依据实际注册的工具集合渲染,避免配置标记和工具列表互相矛盾。
## 知识库与工具结果
`runtime_context` 只放本轮元数据;通用回答规则放在系统的 `runtime_contract` 中。
知识库目录保留 ID、名称、能力、数量、限长描述,以及最多两个近期文档或 FAQ 问题。
名称最多 160 字符,描述最多 240 字符,超出后添加省略标记;XML 值转义。
FAQ 答案和文档摘要不在首轮自动展开,模型需通过已授权检索工具读取实际证据。
正常工具结果保持 `tool` 角色和调用 ID。消息修复时遇到缺少调用记录的结果,
以转义后的 `untrusted_tool_result` 数据块保留,禁止转成 `system`。
Agent、普通问答和模型兜底共用 `types.SourceDataBoundaryPrompt`,说明文档中的指令
不能自行覆盖用户任务或工具权限。此规则和转义用于减少内容混淆,不是绝对防注入保证。
## 前端编辑、保存与兼容
前端编辑器展示有效正文,保存时由 `frontend/src/utils/agentPromptTemplates.ts` 处理:
- 正文与当前已知模板完全相同:保存 `system_prompt_id` / `context_template_id`,正文留空。
- 实际修改过的正文:原样保存,清除对应旧模板 ID;不将它偷偷改为追加提示词。
- 改写和兜底字段与当前默认模板完全相同:保存空值,沿用已有的默认值继承机制。
- 意图提示词继续使用已有的“只保存偏离默认值的覆盖项”机制。
例如未修改的 Wiki 模板保存为:
```json
{"agent_mode":"smart-reasoning","system_prompt_id":"wiki_researcher","system_prompt":""}
```
`config.Config.ResolveCustomAgentPrompts` 在请求时解析引用,普通问答与智能推理都调用它;
不会把解析结果写回保存对象。引用限制在所属模式和字段的模板集合内。显式正文始终优先于 ID。
编辑器再次打开时解析引用以展示当前模板。
不会批量迁移历史正文:旧版默认副本与真正的用户修改无法可靠区分。需要跟随新模板的旧配置,
可在编辑器中选择“恢复默认”后保存。未知模板引用不跨字段解析,找不到时沿用运行时默认路径。
普通问答自定义模板中已有的 `{{contexts}}` 等占位符继续兼容。
## 回归检查
```sh
go test ./internal/agent ./internal/agent/tools ./internal/config ./internal/application/service ./internal/application/service/chat_pipeline ./internal/types ./internal/modelcontext
cd frontend
npm test -- src/utils/agentPromptTemplates.test.ts src/stores/browserSource.test.ts src/api/chat/streame.test.ts
npm run type-check
npm run build
```
这些检查覆盖工具开关、实际来源组合、正文保留与引用更新、消息角色、图片和中途补充、目录转义及来源边界。
它们验证代码拼装与控制链路,不等同于某个线上模型在真实网站上的行为评测。
## 逐段审查后的规则分工
此次调整保留领域能力,但去掉模板中重复的运行时规则。默认模板与自定义正文不是同一个迁移范围:修改默认 YAML 不会重写已保存的用户自定义正文。
| 部分 | 发现的问题 | 现在的规则 |
| --- | --- | --- |
| 普通 Agent / RAG | 身份、查资料、停止条件、图片格式在模板和运行时重复;容易把所有消息都变成检索任务 | 基础模板只保留角色和领域方法;公共来源段判断是否需要补充证据,已有充分资料不重复检索 |
| Wiki / 混合检索 | Wiki 永远优先、每轮强制重检、搜索后无条件全文读取;把非 Wiki 工具误认成 MCP;禁止工具参数使用 ID | 按当前任务和实际能力选择来源;仅为证据缺口深读;工具参数使用真实提供的 ID;不根据名字猜工具种类 |
| Wiki 修复 | 假定任何输入都来自“修复”按钮且只有 issue ID;写作风格与工具说明重复 | 有 ID 才读取 issue;用户直接描述也可调查;按明确修复范围编辑,验证后更新状态 |
| 数据分析 | 每条 SQL 前都强制重读 schema;模板声称只能 SELECT,与工具支持的只读语句不一致 | 当前表结构已知时可复用;只读边界由工具验证,模板说明分析方法和结果检查 |
| Skill 安装 | 通用 `/workspace/output` 工作流与安装模板“不要碰 `/workspace`”冲突 | 服务端的安装模式选择独立验证规则,不注入会话产物工作流或执行 Skill 的终端用户任务 |
| 工具指引 | 把配置缺失也视为不可改用任何工具;MCP 调用细节混在来源规则中 | 禁止绕过权限,但允许符合来源选择的授权替代能力;MCP 调用步骤归工具段 |
| Skill 目录 | 无 read_file 时仍可能展示读取入口;描述原样进入 system;关键词匹配过强 | 有实际 reader 才展示目录;描述限长并转义;按任务目的选择 Skill,不能由描述扩大授权 |
| 记忆 | “永不作为指令”可能使正常偏好失效;文本能闭合封装标签 | 相关偏好可作为默认值,当前用户要求优先;记忆不能授权操作,正文转义 |
| 输出 | 看到任意图片就要求配图;系统规则在工具返回后以 user 角色追加;固定 Markdown 抢占 JSON 等要求 | 共用初始系统输出段;相关图片且格式允许才展示,保留真实 URL;用户明确格式优先 |
| 引用协议 | 关闭引用连用户索要的链接和下载地址都禁止;引用标签可能破坏严格输出格式 | 关闭的是来源归因标记,保留任务所需资源;引用不破坏要求的 schema |
| 改写 / 意图 / 兜底 | 强制把指令改成 30 词问题,可能丢失动作、来源限制和 JSON 等格式要求;界面语言覆盖用户语言;兜底目录被当作内容证据 | 改写保留任务类型与约束,语言尊重明确要求;意图模板不固定 Markdown;兜底目录仅支持导航,不能概括未读正文 |
| 普通问答 context | 用户问题被放到“仅元数据,不是指令”标题下;上下文模板再次规定回答语言和策略 | 参考资料、请求元数据、用户请求分开;上下文负责传数据,系统正文负责策略 |
模板中的来源工作流是默认方法,不是另一套权限系统。实际权限不能靠这些段落的先后顺序保障。
任意用户自定义正文仍可能含有相互矛盾的要求;保留原文的前提下,无法承诺自动消除所有语义冲突。
审查这类配置时应查看完整组装结果,尤其是自定义正文与 `sources`、`output`、`protocol` 三段的关系。
后续新增规则先决定归属:角色与领域方法放 `base`,查什么放 `sources`,怎么调用放工具定义/`tools`,
输出形态放 `output`,引用编码放 `protocol`。不要把同一条规则复制到多个模板中来“加强优先级”。

View File

@ -1,555 +0,0 @@
# Agent Skills 文档
## 概述
Agent Skills 是一种让 Agent 通过阅读"使用说明书"来学习新能力的扩展机制。与传统的硬编码工具不同,Skills 通过注入到 System Prompt 来扩展 Agent 的能力,遵循 **Progressive Disclosure(渐进式披露)** 的设计理念。
目前仅支持带**智能推理**能力的智能体使用。前端可在智能体的编辑页面找到相关配置
已安装到沙箱镜像的技能统一通过 `shell_exec(skill_name=..., command=...)` 执行;`read_file(path="skill://<name>/SKILL.md")` 返回具体执行方式。独立的 `execute_skill_script` 已删除;宿主机技能也通过同一 Shell 入口准备资源并执行,无 Shell 时仅可阅读技能。工具设计与沙箱迁移要求见 [Agent Tools 设计评审与重构](agent-tools-design.md)。
### 核心特性
- **非侵入式扩展**:不影响原有 Agent ReAct 流程
- **按需加载**:三级渐进式加载,优化 Token 使用
- **沙箱执行**:脚本在隔离环境中安全执行
- **灵活配置**:支持多目录、白名单过滤
## 设计理念
### Progressive Disclosure(渐进式披露)
Skills 采用三级加载机制,确保只在需要时才向 LLM 提供详细信息:
```
┌─────────────────────────────────────────────────────────────────┐
│ Level 1: 元数据 (Metadata) │
│ • 始终加载到 System Prompt │
│ • 约 100 tokens/skill │
│ • 包含:技能名称 + 简短描述 │
└─────────────────────────────────────────────────────────────────┘
↓ 用户请求匹配时
┌─────────────────────────────────────────────────────────────────┐
│ Level 2: 指令 (Instructions) │
│ • 通过 read_file 读取技能 SKILL.md │
│ • SKILL.md 的指令内容 │
│ • 包含:详细指令、代码示例、使用方法 │
└─────────────────────────────────────────────────────────────────┘
↓ 需要更多信息时
┌─────────────────────────────────────────────────────────────────┐
│ Level 3: 附加资源 (Resources) │
│ • 通过 read_file 读取技能附加文件 │
│ • 补充文档、配置模板、脚本文件 │
│ • 通过 shell_exec(skill_name=...) 执行已安装脚本 │
└─────────────────────────────────────────────────────────────────┘
```
## Skill 目录结构
每个 Skill 是一个目录,包含 `SKILL.md` 主文件和可选的附加资源:
```
my-skill/
├── SKILL.md # 必需:主文件(含 YAML frontmatter)
├── REFERENCE.md # 可选:补充文档
├── templates/ # 可选:模板文件
│ └── config.yaml
└── scripts/ # 可选:可执行脚本
├── analyze.py
└── generate.sh
```
## SKILL.md 格式
### YAML Frontmatter
每个 `SKILL.md` 必须以 YAML frontmatter 开头,定义元数据:
```markdown
---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---
# PDF Processing
This skill provides utilities for working with PDF documents.
## Quick Start
Use pdfplumber to extract text from PDFs:
```python
import pdfplumber
with pdfplumber.open("document.pdf") as pdf:
text = pdf.pages[0].extract_text()
print(text)
```
## 元数据验证规则
| 字段 | 要求 |
|------|------|
| `name` | 1-50 字符,仅允许汉字、英文字母、数字,不能是保留词 |
| `description` | 1-500 字符,描述技能用途和触发条件 |
**保留词**:`system`, `default`, `internal`, `core`, `base`, `root`, `admin`
## 配置
### AgentConfig 配置项
```go
type AgentConfig struct {
// ... 其他配置 ...
// Skills 相关配置
SkillsEnabled bool `json:"skills_enabled"` // 是否启用 Skills
SkillDirs []string `json:"skill_dirs"` // 测试/宿主技能目录(生产路径不填)
AllowedSkills []string `json:"allowed_skills"` // 白名单(空=全部允许)
TenantSkills []*TenantSkillEntity // 沙箱镜像内已安装技能
}
```
生产对话只使用当前智能体所选沙箱配置上的已安装技能(`TenantSkills`)。`SkillDirs` 仅用于测试或把宿主技能目录 stage 进会话,不再有部署级 `skills/preloaded`。
### 配置示例
```json
{
"skills_enabled": true,
"allowed_skills": ["pdf-processing", "code-review"]
}
```
### Sandbox 配置入口
Sandbox 不再把凭据和模板放进 `WEKNORA_SANDBOX_*`。后端、凭据、模板、执行超时、TTL 和私网访问策略均在「设置 → 沙箱后端」按空间保存;智能体没有选择空间配置时,脚本执行保持禁用。Docker 后端默认关闭,由系统管理员在「设置 → 系统设置」打开,或设置 `WEKNORA_SANDBOX_DOCKER_ENABLED=true`。
### Sandbox 模式
Docker、CubeSandbox、E2B 均通过同一套空间配置 CRUD、连接检查和智能体选择接口管理。CubeSandbox / E2B 的集群搭建和设置页接入流程见 [WeKnora 沙箱集群与标准模板](sandbox-cluster.md)。设置页会通过当前连接拉取模板目录;若没有 WeKnora 标准(CLI)模板,后端会从标准镜像发起创建,用户无需复制模板 ID。图形桌面模板更重,不会随刷新自动构建,须在模板步骤单独点「创建」,见 [沙箱图形桌面](sandbox-desktop.md)。
| 模式 | 状态 | 说明 |
|------|------|------|
| `docker` | 稳定 | 单机 Docker daemon;会话级持久(一个会话一个长驻容器),支持多机 WeKnora 副本(需 Redis),但沙箱都落在同一台 daemon 上。见 [Docker 沙箱后端](sandbox-docker-backend.md) |
| `cube` | 稳定 | Tencent CubeSandbox MicroVM;会话级持久,支持多机(需 Redis) |
| `e2b` | 稳定 | E2B 云端 MicroVM;会话级持久,支持多机(需 Redis);依赖第三方 SDK go-e2b |
### 工作区沙箱后端配置
一个工作区可以维护**多份具名**沙箱后端配置(「设置 → 沙箱后端」),智能体在编辑弹窗的「能力扩展 → 沙箱后端」里各自选一份。不选表示禁用脚本执行。
同一后端类型可以有多份配置:例如两份 E2B 分别指向不同账号或区域,让不同智能体的技能脚本落在不同配额上。
**空间配置是唯一运行时来源。** 端点、凭据和运行参数不会从 `.env` 回退:
| 后端 | 必填 | 可留空 |
|---|---|---|
| Cube | API 端点、Proxy 端点、沙箱域名、从集群列表选择的模板 | API Key(自建部署通常无鉴权) |
| E2B | API Key、从账号列表选择的模板 | API 端点、沙箱域名(go-e2b 自行解析默认值) |
留空必填项在保存时就会被拒绝(HTTP 400)。HTTP 超时、沙箱 TTL 和执行超时留空均使用程序内置默认值。
这条规则换来的是:库里那一行就是沙箱位置的完整描述。因此身份比较不必再去解析 `.env`,改 `.env` 也不会在无人察觉的情况下把某份配置重新指向别的账号。
**会话与配置的绑定是「随沙箱同生共死」的钉子。** 会话首次创建沙箱时,把当时用的配置 ID 记在 `sessions.sandbox_config_id` 上;此后该会话的附件上传、产物收集、沙箱销毁都锁定在这份配置上。改智能体的选择**只影响之后新建的沙箱**——否则管理员改一次配置,正在进行的会话就会去错误的账号里找产物,销毁也会打空,留下一个没人知道 ID 的 paused 沙箱持续计费。
### 安装租户技能
空间「技能沙箱」设置里可以把技能装进当前配置的镜像。除上传 zip 外,也支持从托管平台粘贴来源(每种写法只对应一种来源,不会猜测):
- ClawHub:`@owner/slug`,或不含 `/` 的 slug(如 `my-team--skill`)
- ClawHub skills.sh 联邦页:`https://clawhub.ai/skills-sh/owner/repo/slug` 或 `skills-sh:owner/repo/slug`(服务端向 ClawHub 解析钉死的 GitHub commit,不会把 URL 最后一段当成仓库子目录)
- 页面链接:ClawHub / [skillhub.cn](https://skillhub.cn) / 自托管 SkillHub、skills.sh、GitHub、GitLab
- 直接的 zip / `SKILL.md` URL
不要粘贴裸的 `owner/slug`:请改成 `@owner/slug` 或完整 `https://github.com/...` 链接。来源必须可匿名读取,服务端下载时不携带任何凭据;私有仓库请先导出 zip 再上传。安装仍走原有镜像快照流程。
**有沙箱在跑时改不了身份字段。** 身份字段分两组,成因不同但后果都足够严重:
| 组 | 字段 | 一改会怎样 |
|---|---|---|
| 控制面 | 后端类型、API 端点、API Key | 旧沙箱**再也无法列举/删除/恢复**——新凭据没有权限动它们,而 `onTimeout=pause` 意味着 TTL 也不会回收|
| 数据面 | E2B 沙箱域名;Cube 代理地址、沙箱域名 | 旧沙箱仍可删,但 envd 请求会打到错的主机 ⇒ 该配置下**所有活会话立刻失效**,而沙箱还活着继续计费 |
因此这类修改会被拒绝(HTTP 409),界面会给出沙箱数量、受影响会话数,以及两条出路:**结束或删除那些会话**(删会话会销毁其沙箱),或者**新建一份配置**把智能体指过去(旧凭据原样留着,清理能力不丢)。**没有「释放沙箱」按钮**——那等于在管理员背后销毁正在进行的对话。
**删除配置**只拦远端沙箱,不拦智能体引用:确认弹窗会列出仍指向它的智能体名单,但不阻止删除;删除后那些智能体执行技能时会明确报错,而不是静默换到别的后端。若后端已连不上、无法核实是否仍有沙箱,可以强制删除(这是唯一能强制的情形——能数出来的活沙箱永远不让强删)。
**`sessions.sandbox_config_id` 取值语义:**
| 值 | 含义 |
|---|---|
| `NULL` | 当前无活沙箱(删会话 / 销毁后会 Clear) |
| `"-"` | 旧版本部署默认沙箱的历史兼容标记;新会话不再写入 |
| UUID | 活沙箱建在工作区某份**具名配置**上 |
### 会话级 sandbox 部署要点
- **binding store 自动选择**:进程根据通用 `REDIS_ADDR` 是否配置自动决定绑定存储;Redis key 命名空间复用 `WEKNORA_REDIS_NAMESPACE`,未设置时为 `weknora`。
- **多机部署(生产推荐)**:配置 `REDIS_ADDR`。多副本共享同一 session 的沙箱绑定,通过 Redis SET NX + 可续租分布式锁串行化 create / recover / delete。
- **⚠️ binding store 现在保存承载凭证,必须做访问控制**:入站一律要求凭证,Cube / E2B 的 traffic token 随绑定一起明文存放——它是访问该沙箱公网 URL 的凭证,读到它就等于能访问那个沙箱暴露的端口。因此**存放绑定的 Redis 必须启用认证并限制网络可达范围**,不能与不受信任的服务共用实例。这里不加密是有意的:每次重连都要解密会把开销加在热路径上,而 Redis 本身的访问控制是更合适的边界。代码侧的对应约束是**绝不整体打印绑定或 handle**(日志里只出现 `sandbox_id` 与凭证的有无),改动 `session_binding.go` / 适配器日志时请一并保持。
- **单机部署**:不配置 `REDIS_ADDR`(或 Lite 模式)时使用进程内内存 binding,仅限单实例。进程重启会丢失 session→sandbox 映射,remote 侧沙箱成为孤儿(注意:**TTL 到期只会暂停、不会销毁**,见下)。绑定丢失后,**Cube / E2B 配置不会再按 metadata 领养旧沙箱**——旧沙箱的 traffic token 随绑定一起没了且 provider 不会重发,领养只会得到一个每次数据面调用都 403 的死会话。lifecycle 会直接删掉它再新建,`/workspace` 里的临时文件随之丢失。Docker 没有 traffic token 概念,照旧领养。
- **切换 provider**:不同 provider 的 sandbox ID 不通用。智能体改选配置只影响之后新建的沙箱,已有沙箱继续按 session pin 回收。
- **⚠️ 孤儿沙箱不会被 TTL 自动回收**:会话沙箱创建时使用 `onTimeout=pause` + `autoResume=true`(见 `buildSessionCreateRequest`),因此 **TTL 到期是"暂停"而非"销毁"**——保留状态本就是 pause 的目的。加上 CAS 换绑会把旧 sandboxID 从 binding store 覆盖掉,被替换的沙箱会变成**无人知晓 ID 的 paused 孤儿**,持续占用快照存储与费用。删除会话(`session.go` 的 destroyer)与 lifecycle 的惰性 orphan cleanup 都覆盖不到这种情况。生产环境需依赖按 metadata 列举并与 binding 对账的清理任务来回收(`internal/sandbox/orphan_reaper.go`),且**必须显式包含 `paused` 状态**。对账维度是 `(tenant_id, config_id)` 而非仅 `tenant_id`:同一工作区的两份配置可能指向**同一个 provider 账号**(例如同一个 E2B Key 只差模板),只按 `tenant_id` 过滤会把另一份配置的沙箱一并误删。
- **网络策略**:每份具名沙箱配置带一块 `network` 策略,作用于该配置下所有沙箱(会话、技能安装、深度检查共用同一份)。默认**出站放行**;**入站一律要求凭证**——沙箱公网 URL 必须携带创建时签发的 traffic token,WeKnora 自身的 envd 链路会自动携带(Cube 由 SDK 附加,E2B 由 WeKnora 的数据面 transport 附加)。若 Cube / E2B 没有签发 token,create 会失败并销毁该沙箱,而不是把空凭证写入 binding(数据面 403 会被当成 authentication,会话会永久卡住)。管理员可配置 allow / deny 列表,Cube 额外支持 CubeEgress L7 规则(scheme / sni / host / method / path + 审计 + header 注入),E2B 额外支持按 host 注入 header。Docker 只能整体开关(`bridge` / `none`)。表单不再提供入站开关;解析忽略已存的 `allow_public_inbound`,保存时清掉该字段。**改策略只影响之后新建的沙箱**:本期不做运行中热更新。
- **⚠️ 升级行为变更**:入站从「公网可达」改为「一律要求凭证」。浏览器或外部服务不能再直连沙箱端口;管理界面和 API 都打不开入站。
## Agent 工具
Skills 功能通过两个工具与 Agent 交互:
### read_file
统一读取沙箱文件和允许使用的技能资源,参数为 `path`、`offset`、`limit`、`max_bytes`。
```json
{"path": "skill://pdf-processing/SKILL.md"}
```
读取 SKILL.md 会返回技能指令、执行方式和文件列表。附加文件使用同一种地址:
```json
{"path": "skill://pdf-processing/FORMS.md", "offset": 1, "limit": 200}
```
沙箱文件可以使用绝对路径,也可以使用相对于 `/workspace` 的路径:
```json
{"path": "scripts/analyze.py"}
```
两类内容共用分页、输出预算和二进制抑制;内容较长时按返回的 `next_offset` 继续。技能资源经过技能白名单和包内路径校验,即使没有沙箱也能阅读。`skill://` 代表技能包资源,不是可用于 Shell 的路径;运行脚本时使用加载结果给出的执行方式。
新会话仅注册 `read_file`,不再同时暴露 `read_skill` 和 `read_sandbox_file`。旧的 Tool 实现已删除;名称只保留用于识别和展示旧记录。
### shell_exec
执行普通命令和已安装技能,共用当前会话沙箱。省略 `skill_name` 使用系统环境;指定技能后,仅本次命令使用它的 Python 虚拟环境、Node 模块路径、会话依赖目录和调用者凭据。工作目录默认 `/workspace`,相对 `work_dir` 也从这里解析;每次调用重新设置工作目录。
```json
{
"skill_name": "pdf-processing",
"command": "python3 \"$WEKNORA_SKILL_DIR/scripts/analyze.py\" /workspace/input/report.pdf --format json"
}
```
自己编写的脚本先用 `write_sandbox_file` 写入 `scripts/analyze.py`,然后以相同 `skill_name` 运行 `python3 scripts/analyze.py`。用 `edit_sandbox_file` 修改,用 `read_file` 查看;这些工具的相对路径也从 `/workspace` 解析。Shell 已启用时通过 `ls`/`find` 浏览目录,不再额外注册 `list_sandbox_files`。
生成文件放在 `/workspace/output`;原始附件位于 `/workspace/input`,应保留原样。已安装技能可在本会话沙箱内补装依赖,写入随会话销毁,不会修改其他会话使用的镜像。Node 的 `NODE_PATH` 支持 CommonJS,自建 ESM 脚本仍需在可写项目目录安装依赖,或调用技能目录中的原始脚本。
### 旧工具迁移
`read_skill`、`read_sandbox_file`、`execute_skill_script` 已删除独立实现与注册路径。旧记录仍能展示,但不会作为可执行工具重新注册。
脚本执行统一传给 `shell_exec`:
```json
{
"skill_name": "pdf-processing",
"command": "python3 \"$WEKNORA_SKILL_DIR/scripts/analyze.py\" --format json",
"stdin": "{\"query\": \"example\"}"
}
```
stdin 保留引号、Unicode 和末尾换行,最大 65536 字节;更大的输入用文件重定向。宿主机技能的脚本、辅助文件及二进制资源自动复制到会话的 `/workspace/.skills/<name>/<revision>`;使用系统运行时及会话依赖目录,不复制宿主机的虚拟环境或 node_modules。资源准备限制为 1000 个文件、合计 32 MiB,超出时需先安装到沙箱镜像。无 Shell 的后端不会获得另一套执行工具;配置支持 Shell 的沙箱后才能运行脚本。
## 创建自定义 Skill
暂时不支持用户自主创建自定义 Skill
## 沙箱安全机制
### 脚本安全校验(Script Validator)
在脚本执行前,系统会进行多层安全校验,拦截潜在的恶意操作:
#### 校验类型
| 类型 | 说明 | 示例 |
|------|------|------|
| **危险命令检测** | 检测可能破坏系统的命令 | `rm -rf /`, `mkfs`, `shutdown`, fork bombs |
| **危险模式匹配** | 正则匹配高危操作模式 | `curl \| bash`, `base64 -d`, `eval()` |
| **网络访问检测** | 检测网络请求尝试 | `curl`, `wget`, `socket.connect`, `requests.get` |
| **反向 Shell 检测** | 检测远程控制后门 | `/dev/tcp/`, `bash -i`, `nc -e` |
| **参数注入检测** | 检测命令行参数中的注入 | `&&`, `\|`, `$()`, 反引号 |
| **Stdin 注入检测** | 检测标准输入中的嵌入命令 | 嵌入的命令替换语法 |
#### 拦截的危险命令
**系统破坏类**:
- `rm -rf /`, `rm -rf /*` - 递归删除根目录
- `mkfs`, `dd if=/dev/zero` - 文件系统/磁盘操作
- Fork bombs: `:(){ :|:& };:`
**系统控制类**:
- `shutdown`, `reboot`, `halt`, `poweroff`
- `killall`, `pkill`
- `systemctl`, `service`
**权限提升类**:
- `chmod 777 /`, `chown root`
- `setuid`, `setgid`, `passwd`
- 访问 `/etc/passwd`, `/etc/shadow`, `/etc/sudoers`
**凭证窃取类**:
- 访问 `.ssh/`, `id_rsa`, `id_ed25519`
- 读取敏感配置文件
**容器逃逸类**:
- `docker`, `kubectl`, `nsenter`
- `unshare`, `capsh`
#### 拦截的危险模式
**代码注入**:
```
# 以下模式会被拦截
curl ... | bash # 下载并执行
wget ... | sh # 下载并执行
eval() # 动态代码执行
exec() # 命令执行
os.system() # 系统命令执行
subprocess.Popen(shell=True) # Shell 命令执行
```
**编码绕过尝试**:
```
# 以下模式会被拦截
base64 -d # Base64 解码执行
echo ... | base64 -d # 管道解码
xxd -r # Hex 解码
```
**Python 特有风险**:
```python
# 以下模式会被拦截
__import__() # 动态导入
pickle.load() # 反序列化(可执行任意代码)
yaml.load() # 不安全的 YAML 加载
yaml.unsafe_load() # 显式不安全加载
```
#### Shell 操作符拦截
参数中包含以下操作符时会被拦截:
| 操作符 | 说明 |
|--------|------|
| `&&`, `\|\|` | 命令链接 |
| `;` | 命令分隔 |
| `\|` | 管道 |
| `$()`, `` ` `` | 命令替换 |
| `>`, `>>`, `<` | 重定向 |
| `2>`, `&>` | 错误/组合重定向 |
| `\n`, `\r` | 换行注入 |
#### 校验结果
校验失败时返回详细的错误信息:
```go
type ValidationError struct {
Type string // 错误类型:dangerous_command, dangerous_pattern, arg_injection 等
Pattern string // 匹配到的模式
Context string // 上下文信息
Message string // 人类可读的描述
}
```
**示例错误**:
```
security validation failed [dangerous_command]: Script contains dangerous command: rm -rf / (pattern: rm -rf /, context: ...cleanup && rm -rf / && echo done...)
```
#### 使用示例
```go
// 创建校验器
validator := sandbox.NewScriptValidator()
// 校验脚本内容
result := validator.ValidateScript(scriptContent)
if !result.Valid {
for _, err := range result.Errors {
log.Printf("Security error: %s", err.Error())
}
return errors.New("script validation failed")
}
// 校验命令行参数
argsResult := validator.ValidateArgs(args)
// 校验标准输入
stdinResult := validator.ValidateStdin(stdin)
// 或一次性校验全部
fullResult := validator.ValidateAll(scriptContent, args, stdin)
```
---
### Docker 沙箱
Docker 后端为每个会话提供独立容器,当前隔离和资源配置如下(详见 [Docker 后端](./sandbox-docker-backend.md)):
- **执行账号**:默认 root;宿主机和跨会话隔离依赖容器与挂载配置,容器共享宿主机内核。
- **Capability 限制**:先移除全部,再补回 CHOWN、DAC_OVERRIDE、FOWNER、FSETID、SETGID、SETUID、KILL;启用 `no-new-privileges`。
- **文件系统**:容器可写层承载技能和工作区,根文件系统不设为只读;当前不支持挂载技能卷,技能随镜像进入会话。
- **资源限制**:默认 2 GiB 内存、2 核 CPU、512 个进程,可通过配置调整。
- **网络**:默认 `bridge`,配置禁止出网时使用 `none`;不支持域名级网络规则。
- **工具约束**:Shell 命令黑名单和文件路径前缀检查用于限制误操作,不是容器内 root 的安全边界。
#### 沙箱镜像
系统使用专用的沙箱镜像 `wechatopenai/weknora-sandbox`,预装了 Python 3.12、Node.js 20、uv 和常用 CLI 工具;技能依赖在技能安装阶段写入各自环境。3.12 才能解析技能源码里带嵌套引号的 f-string(PEP 701);安装校验用的就是镜像里的解释器。
**预拉取镜像**(推荐在首次部署时执行,避免首次执行脚本时等待下载):
```bash
# 方式一:直接拉取
docker pull wechatopenai/weknora-sandbox:main
# 方式二:本地构建
sh scripts/build_images.sh -s
```
> 如果未预拉取,创建第一个沙箱时会先拉取镜像,首次执行需要等待下载完成;也可以在设置页的模板步骤提前触发拉取。
> 示例使用 `main`;生产部署应固定已验证的版本标签,并确认镜像与应用版本兼容。
**镜像内置环境**:
- Python 3.12 + pip、uv;第三方 Python 包由技能安装阶段提供
- Node.js 20 + npm、pnpm
- CLI 工具:jq、curl、bash、grep、sed、awk 等
```bash
# Docker 执行示例
docker run --rm \
--user 1000:1000 \
--cap-drop ALL \
--read-only \
--memory=256m \
--network=none \
-v /path/to/skill:/skill:ro \
-w /skill \
wechatopenai/weknora-sandbox:main \
python scripts/analyze.py input.pdf
```
## API 参考
### SkillManager
```go
type Manager interface {
// 初始化,发现所有 Skills
Initialize(ctx context.Context) error
// 获取所有 Skill 元数据(Level 1)
GetAllMetadata() []*SkillMetadata
// 加载 Skill 指令(Level 2)
LoadSkill(ctx context.Context, skillName string) (*Skill, error)
// 读取 Skill 文件内容(Level 3)
ReadSkillFile(ctx context.Context, skillName, filePath string) (string, error)
// 列出 Skill 中的所有文件
ListSkillFiles(ctx context.Context, skillName string) ([]string, error)
// 为统一 Shell 准备技能资源和环境,命令由 shell_exec 执行
PrepareShellEnvironment(ctx context.Context, sessionID, skillName, command string, env map[string]string) (string, map[string]string, error)
// 检查是否启用
IsEnabled() bool
}
```
### Skill 结构
```go
type Skill struct {
Name string // 技能名称
Description string // 技能描述
BasePath string // 目录绝对路径
FilePath string // SKILL.md 绝对路径
Instructions string // SKILL.md 主体指令内容
Loaded bool // 是否已加载 Level 2
}
type SkillMetadata struct {
Name string // 技能名称
Description string // 技能描述
BasePath string // 目录路径
}
```
### ExecuteResult 结构
```go
type ExecuteResult struct {
ExitCode int // 退出码
Stdout string // 标准输出
Stderr string // 标准错误
Duration time.Duration // 执行时长
Error error // 执行错误
}
```
## 示例:完整工作流
以下是 Agent 处理用户请求的完整流程:
```
用户: "帮我从 report.pdf 提取表格数据"
Agent 思考:
→ 查看 System Prompt 中的 Skills 列表
→ 发现 "pdf-processing" 技能匹配
Agent 行动 1: 调用 read_file
→ {"path": "skill://pdf-processing/SKILL.md"}
→ 获取 SKILL.md 指令内容
→ 学习如何使用 pdfplumber
Agent 行动 2: 调用 shell_exec
→ {"skill_name": "pdf-processing",
"command": "python3 \"$WEKNORA_SKILL_DIR/scripts/extract_text.py\" /workspace/input/report.pdf"}
→ 脚本在沙箱中执行,返回提取的表格数据
Agent 回复:
→ 向用户展示提取的表格数据
→ 提供数据使用建议
```
## 故障排查
### Skill 未被发现
1. 检查 `skill_dirs` 配置是否正确
2. 确认目录中存在 `SKILL.md` 文件
3. 验证 YAML frontmatter 格式
```bash
# 运行 demo 验证
go run ./cmd/skills-demo/main.go
```
### 脚本执行失败
1. 检查沙箱后端配置
2. Docker 模式:确认 Docker 服务运行中
3. 检查脚本权限和语法
### 元数据验证错误
常见错误:
- `skill name too long`: 名称超过 50 字符
- `skill name contains invalid characters`: 包含非法字符
- `skill name is reserved`: 使用了保留词
- `skill description too long`: 描述超过 500 字符

View File

@ -1,176 +0,0 @@
# Agent Tools 设计评审与重构
## 结论与参考范围
WeKnora 的通用沙箱操作需要四个稳定原语:读取、写入、编辑、执行命令。技能通过指令和运行环境扩展这些原语;知识库、Wiki、历史记录等业务能力继续通过服务端工具提供,因为它们包含租户隔离、访问控制和检索语义。
本次参考 PI,克隆 `badlogic/pi-mono`,固定提交 `17de82d7bea18a6589677a9761baabc2060c9efb`(仓库现转到 `earendil-works/pi`)。重点阅读 coding-agent 的 README、系统提示词、工具注册与实现、路径及文件变更处理,以及 agent-core 的执行循环。本次没有审阅其整个 monorepo,也没有复制实现。
- [设计哲学与默认能力](https://github.com/earendil-works/pi/blob/17de82d7bea18a6589677a9761baabc2060c9efb/packages/coding-agent/README.md):最小核心、扩展机制、按需技能。
- [工具组合](https://github.com/earendil-works/pi/blob/17de82d7bea18a6589677a9761baabc2060c9efb/packages/coding-agent/src/core/tools/index.ts):默认 read、bash、edit、write;grep、find、ls 为可选工具。
- [提示词](https://github.com/earendil-works/pi/blob/17de82d7bea18a6589677a9761baabc2060c9efb/packages/coding-agent/src/core/system-prompt.ts):根据实际工具集组合说明。
- [执行循环](https://github.com/earendil-works/pi/blob/17de82d7bea18a6589677a9761baabc2060c9efb/packages/agent/src/agent-loop.ts):工具结果驱动后续步骤,支持不同执行策略。
## 评审发现及处理
| 发现 | 后果 | 本次处理 |
| --- | --- | --- |
| read_skill 和 read_sandbox_file 各自维护读取入口,技能读取没有连续分页 | 选择工具和读取大技能都多一层成本 | 合并为 read_file(path, offset, limit, max_bytes),共享分页及输出预算;按来源保留访问控制 |
| shell、技能脚本执行、目录浏览存在重复入口 | 模型需要先判断工具,再判断解释器,容易来回切换 | 已安装技能统一走 shell 的 `skill_name`;有 shell 时隐藏目录列表工具 |
| 每条工具失败都追加“换一种方式” | 权限问题反复改用其他工具尝试 | 删除统一重试提示;提示词要求先改变相关条件再重试 |
| Cube SDK 文件 API 默认 root,脚本使用 user | 文件工具创建的目录可能无法被脚本修改 | 仅在文件 API 路由统一身份;控制面认证和命令身份保持各自语义 |
| 安装器写技能文件也使用普通账号 | 安装到受保护技能目录失败 | 由服务端安装路径携带局部 maintenance 身份,不对模型开放 root 参数 |
| 目录准备失败被忽略,或移动原目录再创建 | 命令延迟失败,附件和产物路径可能改变 | 同一执行账号准备目录,失败立即返回;保留已有目录、文件和链接 |
| 底层 shell 空 cwd 依赖提供商默认,mkdir 错误被忽略 | 工具之间工作目录不一致 | 默认 `/workspace`,相对文件路径和工具 work_dir 统一解析,准备失败阻止执行 |
| 所有工具可同时执行 | 同轮写脚本、执行、读取结果之间有竞态 | 仅显式列出的读取工具并发;写入、任意命令、未知/MCP 工具按原顺序形成屏障 |
| shell 的超时结果仍标记成功 | 模型可能误判完成 | 超时、终止和执行器错误返回工具失败;普通非零退出仍保留 exit_code 语义 |
| Cube 客户端全局 HTTP 超时覆盖命令流 | 长命令被较短的 HTTP 超时提前终止 | 普通 RPC 受 HTTP 超时控制,命令流使用执行超时和调用者 context |
| Docker 实际使用 sh,但工具宣称 Bash | 数组等合法 Bash 语法失败 | Docker shell 命令显式使用 Bash |
| Prompt 重复描述工具,并要求固定检索和阅读步骤 | 无必要的工具调用与上下文成本 | 简化通用/RAG 模板;已有完整证据时不重复展开;按实际注册工具追加运行说明 |
## 最终工具组合
| 场景 | 默认或自动注册行为 |
| --- | --- |
| 支持 Shell 的技能沙箱 | `shell_exec`、`read_file`、`write_sandbox_file`、`edit_sandbox_file`;read_file 同时承担技能资源读取 |
| 已安装技能 | `shell_exec(skill_name=..., command=...)`,不额外注册 `execute_skill_script` |
| 宿主机技能 | shell_exec 自动准备脚本、辅助文件和二进制资源,再使用同一执行链 |
| 无 Shell 后端 | 技能可阅读、脚本不可执行;按后端能力继续提供文件读写 |
| 只有文件能力 | 保留 `list_sandbox_files` 加读、写、编辑;不依赖 Shell |
| 技能安装器 | 保留独立的安装命令和技能文件写入权限 |
| 未指定 allowed_tools 的后端默认值 | 从 11 项缩为 5 项:knowledge_search、grep_chunks、list_knowledge_chunks、get_document_info、search_conversations |
| 前端自动补齐知识库工具 | 只选四个知识库读取工具;图谱、SQL 需要主动启用 |
业务工具通过默认选择和按能力注册收紧;三个重复的读取/执行 Tool 已删除实现。现有业务 allowlist、预设、MCP 配置继续生效,过期的 Tool 名称不会恢复注册。Web、Memory、Wiki 等仍遵循原有配置及权限过滤。原有 `SkillsEnabled` 执行开关保留;本次没有扩大原先只允许文件访问的会话权限。
## 第二轮合并判断
| 候选 | 决定 | 原因 |
| --- | --- | --- |
| read_skill + read_sandbox_file | 合并为 read_file | 操作都是读取文本,差异由资源来源处理;模型只选路径 |
| execute_skill_script + shell_exec | 全部合并 | 已安装环境选择、宿主机文件准备和 stdin 统一由 Shell 入口承担 |
| list_sandbox_files + shell 的 ls/find | Shell 场景只留 Shell | 无 Shell 时保留目录发现能力 |
| write_skill_file/edit_skill_file 与沙箱写入/编辑 | 保留各自的权限实现 | 两组只在不同角色下注册,不会同时占用普通会话工具列表;安装器写入共享镜像,普通会话写工作区 |
| write + edit | 保留两个操作 | 全量写入和唯一匹配替换具有不同输入及失败语义,强行加 mode 会让 Schema 更难使用 |
| knowledge_search + grep_chunks | 保留 | 语义检索和关键词定位使用不同查询方式和结果结构,适用问题不同 |
| 文档信息、分块、Wiki、历史、数据工具 | 按业务启用 | 对象身份、访问范围和结果语义不同,不通过“万能 read”绕过业务服务 |
统一读取示例:
```json
{"path":"skill://pdf-processing/SKILL.md"}
{"path":"skill://pdf-processing/scripts/analyze.py","offset":1,"limit":100}
{"path":"scripts/report.py","offset":1,"limit":100}
```
`skill://` 使用技能管理器加载已授权的包资源,主文档包含指令、执行方式和附加文件列表;它不是容器路径,也不保证是安装器修改后的镜像文件。工作区路径仍使用沙箱文件 API。宿主机技能资源通过 os.Root 限制在技能目录中,禁止符号链接逃逸。新注册表只向模型暴露 `read_file`;旧读取 Tool 实现已删除,工作区读取成为私有适配器;仅保留历史名称识别和展示。@Skill 指引、模板、模型结果策略、历史压缩、前端名称和图标同步使用新入口。
## 技能执行契约
```json
{"skill_name":"pdf-processing","command":"python3 scripts/report.py"}
```
脚本可先用 `write_sandbox_file(path="scripts/report.py", ...)` 写入。默认 cwd 为 `/workspace`;`work_dir="output/report"` 会解析为 `/workspace/output/report` 并以普通用户创建。每次命令独立设置 cwd,文件在当前会话内持续存在。
指定技能时,运行时检查它是否为允许使用的已安装技能,并为本次命令设置:
- 技能 `.venv/bin`、`node_modules/.bin` 优先的 PATH;使用独立 Bash 子进程执行原命令。
- Python/Node 会话依赖目录及技能 Node 模块目录。
- `WEKNORA_SKILL_DIR`、附件目录及产物目录变量。
- 原有按调用者解析的凭据,不写入容器全局环境。
未指定技能的下一条命令使用系统运行环境。命名了不存在或未接入的技能环境时直接报错,不静默回退到系统解释器。
技能缺包时装进技能自己的环境:安装调用也带 `skill_name`,保持 `work_dir` 为默认的 `/workspace`。Python 用 `uv pip install --python "${WEKNORA_SKILL_DIR:?}/.venv/bin/python" <package>`,无需虚拟环境内已有 pip;Node 用 `npm --prefix "${WEKNORA_SKILL_DIR:?}" install <package>`。`$WEKNORA_SKILL_DIR` 由本次调用注入,指向镜像内技能或宿主机来源技能的实际暂存目录。如果尚无 `.venv`,先用 `python3 -m venv --without-pip "${WEKNORA_SKILL_DIR:?}/.venv"` 创建;自定义镜像没有 uv 时,先用该虚拟环境的 Python 执行 `-m ensurepip --upgrade`,成功后再执行 `-m pip install <package>`。随后仍带同一 `skill_name` 执行原命令。命令中的 `${WEKNORA_SKILL_DIR:?}` 会在变量缺失或为空时终止,避免误用根目录。真正的只读挂载仍需先配置可写的技能环境,root、uv 和 pip 都无法绕过挂载限制。
沙箱归本会话独占且以 root 运行,这类写入落在会话自己的容器里、随会话销毁,不会回流到其他会话启动用的镜像;因此不再需要 `/workspace` 下的包 overlay,技能的包也不会被拆到两个位置。Node 的 `NODE_PATH` 支持 CommonJS;自建 ESM 脚本应在可写项目目录安装依赖,或调用技能目录里的原始脚本,不能假定 NODE_PATH 支持 ESM。
文件工具继续保留写入预算、精确编辑校验、读取分页和二进制处理。Shell 输出保留原来的字节限额和截断策略;完整输出不自动保存,需要时显式重定向到工作区日志。产物仍由 `/workspace/output` 收集,以 `sandbox:<filename>` 引用。
`/workspace/input` 的文件工具写入限制保留;Shell 中“保留附件原件”仍是行为约定,不应解释为本次新增了文件系统只读挂载。
## 旧工具删除与执行统一
删除 `ReadSkillTool`、`ExecuteSkillScriptTool` 和独立 `ReadSandboxFileTool`;共享文件分页与工作区缓存迁入私有 `workspaceFileReader`,技能文件树为普通辅助函数。技能管理器中只服务旧工具的 ExecuteScript、执行配置构造及重复凭据处理也已移除。
`LegacyTool*` 常量和前端旧事件展示仅用于读取历史消息及忽略过期 allowlist,不提供运行时别名或回退执行。新会话没有隐藏的第二套读/执行 Tool。
Shell 的补齐能力:
- `stdin` 可传入最多 65536 字节的文本,保留字面引号、Unicode 和尾部换行;更大的输入使用工作区文件重定向。
- 宿主机技能按资源内容生成版本目录,复制到 `/workspace/.skills/<name>/<revision>`。脚本和二进制资源一起准备;单次准备上限 1000 个文件、合计 32 MiB。文件准备失败不会启动命令或标记准备完成。
- 宿主机虚拟环境、node_modules 和缓存目录不复制;这些技能使用镜像系统运行时及会话依赖目录。需要固定依赖时应安装到标准镜像。
- 相同会话及管理器内复用已准备目录;目录被清理后重新准备。其他会话独立准备。
- 三个正式远程后端都支持 Shell。没有 Shell 时只阅读技能,明确告知执行不可用,不再暴露一个实际无法承接同等能力的执行器。
原来只验证旧 Tool 包装和参数兼容的测试随旧实现删除;对应的环境、凭据、目录、资源及 stdin 行为通过新 Shell 单元测试和 Docker 集成测试验证。旧记录回放测试保留。
删除后的后端回归与专项竞态检查均通过。真实 Docker 验证覆盖已安装虚拟环境和宿主机技能资源准备,并验证二进制资源、带空格参数、Unicode、字面 `$HOME` / `$()` 和尾部换行的 stdin 传递;容器验证镜像的范围见下方验证说明。
## 事实内容与产物生成
截图中的 PPT 工作流只展示了技能/脚本读取、内容文件写入、生成及文件检查,没有展示知识库或网页内容检索。它不能证明当时已注册哪些检索工具,但暴露了 Prompt 中的真实缺口:原检索规则主要围绕“知识库问答”,而技能工作流强调执行,事实性产物容易绕过内容查证。
本次补充统一的运行时内容查证指引,应用于默认及已保存的自定义系统 Prompt:
- PPT、报告、教程、技术操作说明等事实性内容在编写正文之前查证;读取生成技能或脚本、生成文件成功,都不能作为主题事实的证据。
- 优先使用用户材料、指定文档和相关绑定知识库;用户没有写“搜索”也应查询可能相关的知识库。范围不明确时进行聚焦检索,不扫描所有无关知识库。已有充分内容不重复读取。
- 根据本轮真实工具注册表列出可用知识库/Web 检索能力;不因配置中残留工具名或开关而虚构可调用能力,也不扩大检索授权范围。相关连接资源继续按各自工具描述使用。
- `@Skill` / `@MCP` 不排除其他内容来源。纯翻译、排版、创作及已有充分证据的任务不强制检索;尊重用户限定来源或不联网的要求。
- 无可用来源、查询失败或证据不足时说明具体缺口,区分未验证背景知识和受支持结论。事实性产物适当保留来源标题/URL及重要限制,分别核验内容与文件生成。
这属于模型行为指引,没有在文件写入前加入机械的“必须先调用一次搜索”拦截。单次检索不能证明证据充分,纯排版也不应被拦截。自动测试验证默认/自定义模板注入、实际注册能力路由、无检索能力时的缺口说明,以及 PPT 技能选择仍保留知识库范围;不等同于真实模型遵循率评估。
上线后的模型回放应覆盖:
| 场景 | 预期行为 |
| --- | --- |
| 技术 PPT + 相关知识库 + 生成技能 | 写正文前检索并读取足够证据,再生成、核验产物 |
| 知识库无相关内容 + 已启用 Web | 补充权威外部来源,检查版本与前提 |
| 只有生成技能,无相关资料或检索能力 | 明确内容未查证及资料缺口,不声称验证通过 |
| 给定完整文稿,只做排版或翻译 | 直接使用文稿,不新增无关检索 |
| 用户限定只用指定资料 | 保持限定范围,缺口不以外部信息偷偷填补 |
| 有记忆但没有当前主题证据 | 不把个性化记忆或旧结论当作已查证主题事实 |
本次没有调用线上模型回放截图中的真实会话,也没有更改其绑定知识库或 Web 开关。
## 镜像契约与迁移
三个后端的标准模板均须提供:
1. 名为 `user` 的普通账号,以及可用的 HOME。
2. Bash 和工具所需的运行时。
3. 由 `user` 可写、可进入的 `/workspace`;标准镜像预建 input、output。
4. 安装流程维护的只读技能目录;普通会话不能修改它。
当前 `docker/Dockerfile.sandbox` 已满足账号和工作区所有权要求。本次现场检查发现,本机缓存的 `wechatopenai/weknora-sandbox:main` 仍只有名为 `sandbox` 的 UID 1000 账号,`/workspace` 由 root 所有。这类旧镜像不能靠换工具解决,必须使用当前 Dockerfile 重建镜像,并更新所用模板/镜像及后续会话。
不要在运行时自动提权、递归 chown、移动目录或删除链接来兼容旧镜像。已有会话中的错误所有权、目录链接会明确报错并保留数据;必要的恢复应由管理员检查具体路径后执行。切换到新模板前,应先保存所需附件和产物。
已有自定义系统提示词或存储在智能体配置里的旧模板文本不会被批量覆盖。如果其中写死了旧的读取或执行工具,应在采用新运行方式时更新;运行时会根据实际工具集追加新指引及旧读取调用的转换方式。
## 验证
后端回归已通过:
```bash
go test ./internal/sandbox ./internal/agent/... ./internal/application/service \
./internal/modelcontext ./internal/config ./internal/types ./internal/container
```
专项 `go test -race` 已通过,覆盖并发读取与变更屏障、结果归一化、技能环境、工作区准备、文件身份和 Cube 超时隔离。前端 `npm run type-check` 已通过。
统一读取的追加验证已通过:技能与工作区路由、无沙箱读取、技能白名单、路径穿越及宿主机符号链接逃逸、连续分页不丢行、二进制抑制、已安装技能的 Shell 指引。前端工具展示和国际化检查共 36 项通过;本机缺少 tsx,使用 Node 原生 TypeScript stripping 运行同一组测试(`node --experimental-strip-types --test src/utils/agent-tool-display.test.mjs src/views/chat/components/AgentStreamDisplay.style.test.mjs src/i18n/localeKeyAudit.test.ts`)。Docker 集成用例也已切到 read_file,并验证读取技能指令后执行脚本的路径。
Docker 集成测试已通过,覆盖文件写入 → 技能 Python 运行 → 编辑 → 再运行、独立命令不继承技能环境、安装器写入、普通命令无法修改技能目录、Bash/HOME、超时、附件上传及产物收集。还验证了超时实际停止进程,以及 output 被替换为链接时保留链接并拒绝执行。既有 Docker conformance 测试本次选择运行上述相关用例,未运行依赖外网安装软件包的用例。
新集成测试可以使用正式构建的标准镜像复跑:
```bash
DOCKER_INTEGRATION_IMAGE=your-standard-sandbox-image \
go test -tags=docker_integration ./internal/agent/tools \
-run '^TestShellRuntimeIntegration$' -count=1 -v -timeout=3m
```
本次正式 Dockerfile 构建在 Docker daemon 拉取 `node:20-slim` 时因 DNS 故障失败。实际容器验证使用本机缓存镜像构建的独立 fixture,按当前 Dockerfile 的账号和工作区契约修正后运行;这证明了相关运行路径,不代表完整正式镜像已构建或发布。Cube/E2B 通过本地协议测试验证,本次没有连接真实远端服务。没有进行模型端效果 A/B 测试,因此不宣称具体的 Token 或重试率降幅。

View File

@ -1,140 +0,0 @@
# WeKnora API 文档
## 目录
- [概述](#概述)
- [最权威参考:Swagger UI](#最权威参考swagger-ui)
- [基础信息](#基础信息)
- [认证机制](#认证机制)
- [错误处理](#错误处理)
- [文件与图片引用(`resource://` 与直链)](#文件与图片引用resource-与直链)
- [API 概览](#api-概览)
## 概述
WeKnora 提供了一系列 RESTful API,用于创建和管理知识库、检索知识,以及进行基于知识的问答。本文档详细描述了这些 API 的使用方式。
## 最权威参考:Swagger UI
WeKnora 同时提供基于 OpenAPI 的 Swagger 文档。**启动服务后访问 `http://localhost:8080/swagger/index.html`**,可看到所有端点的完整参数、请求/响应 schema,并可直接在浏览器内试调——它随代码自动更新,是最准确的接口参考。
本目录下的 markdown 文档提供更易读的示例与场景说明,与 swagger 同步维护;当二者出现差异时,以 swagger 为准。
> Swagger UI 仅在非 release 模式(`GIN_MODE != release`)下挂载;生产部署默认关闭。
## 基础信息
- **基础 URL**: `/api/v1`
- **响应格式**: JSON
- **认证方式**: API Key
## 认证机制
所有 API 请求需要在 HTTP 请求头中包含 `X-API-Key` 进行身份认证:
```
X-API-Key: your_api_key
```
为便于问题追踪和调试,建议每个请求的 HTTP 请求头中添加 `X-Request-ID`:
```
X-Request-ID: unique_request_id
```
### 获取 API Key
在 web 页面完成账户注册后,请前往账户信息页面获取您的 API Key。
请妥善保管您的 API Key,避免泄露。API Key 代表您的账户身份,拥有完整的 API 访问权限。
## 错误处理
所有 API 使用标准的 HTTP 状态码表示请求状态,并返回统一的错误响应格式:
```json
{
"success": false,
"error": {
"code": "错误代码",
"message": "错误信息",
"details": "错误详情"
}
}
```
## 文件与图片引用(`resource://` 与直链)
响应里的图片、图表、附件默认以内部引用 `resource://<handle>` 返回,例如问答答案中的
`![示意图](resource://xifDo7NTSL300Lp1goVutw)`。这类引用不能被浏览器直接加载,客户端需要再
调用带鉴权的 `GET /files?file_path=<引用>` 代理去取字节流。
如果你在把 WeKnora 集成进自己的 App,可以让服务端直接返回**可加载的 http(s) 直链**,省掉这一次
额外请求:
| 方式 | 用法 | 生效范围 |
|------|------|----------|
| 单次请求 | 在 URL 上加 `?resource_urls=public` | 仅该次请求 |
| 整个部署 | 环境变量 `RESOURCE_URL_MODE=public` | 所有未显式传参的请求 |
`resource_urls` 取值为 `handle`(默认,保持内部引用)或 `public`(返回直链);传其它值返回
`400`。单次请求的参数优先于环境变量,因此把部署默认设成 `public` 后,仍可用
`?resource_urls=handle` 单独退回。
支持该参数的接口:
- `POST /api/v1/knowledge-chat/{session_id}`(SSE)
- `POST /api/v1/agent-chat/{session_id}`(SSE)
- `GET /api/v1/sessions/continue-stream/{session_id}`(SSE)
- `GET /api/v1/messages/{session_id}/load`
- `POST /api/v1/knowledge-search`
- `POST /api/v1/knowledge-bases/{id}/hybrid-search`(兼容 GET)
改写覆盖答案正文、检索结果 `content` / `image_info`、`knowledge_references`、Agent 执行步骤与工具结果,以及消息
上的图片附件。流式回答里跨两个 chunk 被截断的引用会先缓冲再改写,客户端拿到的始终是完整链接。
### 注意事项
- **需要外链能力。** 直链由存储后端预签名,或由 `APP_EXTERNAL_URL` + `/r/<token>` 提供。二者都不
可用时(例如 local 存储且未设 `APP_EXTERNAL_URL`),该引用**保持 `resource://` 原样**,客户端
仍可回退到 `/files` 代理。详见 `.env.example` 中的 `APP_EXTERNAL_URL` 说明。
- **直链是限时匿名可读的**(WeKnora 签发的 grant 2 小时,MinIO 预签名 24 小时)。任何拿到链接的
人在过期前都能读取该文件,请勿写入日志或转发给不应看到该文件的一方。
- **嵌入式(embed)渠道不支持该参数。** 其访客是匿名的,`/api/v1/embed/...` 下的接口会强制使用
`handle`(即使传了 `?resource_urls=public`、或部署默认是 `public`),图片仍走渠道维度的鉴权代理。
- **限定知识库的 API Key 不能使用 `public`**,返回 `403`。这类 Key 本身也被拒绝访问 `/files`
代理,若能拿到匿名直链等于绕过同一道限制。改用 `handle` 即可正常调用。
- **同一文件的直链会在有效期内复用**:重复请求不会反复签发凭证,也不会每次都拿到不同的 URL,客户端
和 CDN 的缓存因此可以命中。凭证被吊销或过期后链接立即失效。
## API 概览
WeKnora API 按功能分为以下几类:
| 分类 | 描述 | 文档链接 |
|------|------|----------|
| 认证管理 | 用户注册、登录、令牌管理;OIDC 流程 | [auth.md](./auth.md) · [OIDC认证调用流程.md](../OIDC认证调用流程.md) |
| 空间管理 | 创建和管理空间账户 | [tenant.md](./tenant.md) |
| 知识库管理 | 创建、查询和管理知识库 | [knowledge-base.md](./knowledge-base.md) |
| 知识管理 | 上传、检索和管理知识内容 | [knowledge.md](./knowledge.md) |
| 模型管理 | 配置和管理各种AI模型 | [model.md](./model.md) |
| 分块管理 | 管理知识的分块内容 | [chunk.md](./chunk.md) |
| 标签管理 | 管理知识库的标签分类 | [tag.md](./tag.md) |
| FAQ管理 | 管理FAQ问答对 | [faq.md](./faq.md) |
| 智能体管理 | 创建和管理自定义智能体 | [agent.md](./agent.md) |
| 会话管理 | 创建和管理对话会话 | [session.md](./session.md) |
| 知识搜索 | 在知识库中搜索内容 | [knowledge-search.md](./knowledge-search.md) |
| 聊天功能 | 基于知识库和 Agent 进行问答 | [chat.md](./chat.md) |
| 消息管理 | 获取和管理对话消息 | [message.md](./message.md) |
| 评估功能 | 评估模型性能 | [evaluation.md](./evaluation.md) |
| 初始化管理 | 知识库模型配置与 Ollama 管理 | [initialization.md](./initialization.md) |
| 系统管理 | 系统信息、解析引擎、存储引擎 | [system.md](./system.md) |
| MCP 服务 | MCP 工具服务管理 | [mcp-service.md](./mcp-service.md) |
| 组织管理 | 组织、成员、知识库/智能体共享 | [organization.md](./organization.md) |
| Skills | 预装与已安装的智能体技能、技能环境变量 | [skill.md](./skill.md) |
| 长期记忆 | 当前用户的跨会话记忆(设置、条目、主题、文档亲和度、导出、整理) | [memory.md](./memory.md) |
| 网络搜索 | 网络搜索服务商 | [web-search.md](./web-search.md) |
| 向量存储 | 向量数据库连接管理 | [vector-store.md](./vector-store.md) |
| 存储后端 | 对象/文件存储实例(多实例)管理 | [storage-backend.md](./storage-backend.md) |
| IM 渠道 | 企业微信 / 飞书 / Slack 等 IM 平台对接,含渠道 CRUD 与回调 | [../IM集成开发文档.md](../IM集成开发文档.md) |
| 数据源导入 | 飞书 / 企微 / Notion / Confluence 等外部数据源接入与同步 | [../数据源导入开发文档.md](../数据源导入开发文档.md) |

View File

@ -1,553 +0,0 @@
# 智能体(Agent)管理 API
[返回目录](./README.md)
## 概述
智能体 API 用于管理自定义智能体(Custom Agent)。系统提供了内置智能体,同时支持用户创建自定义智能体来满足不同的业务场景需求。
> 智能体的共享与跨组织分发(`/agents/:id/shares` 等)属于组织协作能力,文档见 [组织管理 API](./organization.md)。本文件只覆盖智能体自身的 CRUD、复制、占位符、类型预设以及推荐问题接口。
### 内置智能体
系统默认提供以下内置智能体:
| ID | 名称 | 描述 | 模式 |
|----|------|------|------|
| `builtin-quick-answer` | 快速问答 | 基于知识库的 RAG 问答,快速准确地回答问题 | quick-answer |
| `builtin-smart-reasoning` | 智能推理 | ReAct 推理框架,支持多步思考和工具调用 | smart-reasoning |
| `builtin-data-analyst` | 数据分析师 | 专业数据分析智能体,支持 CSV/Excel 文件的 SQL 查询与统计分析 | smart-reasoning |
### 智能体模式
| 模式 | 说明 |
|------|------|
| `quick-answer` | RAG 模式,快速问答,直接基于知识库检索结果生成回答 |
| `smart-reasoning` | ReAct 模式,支持多步推理和工具调用 |
## API 列表
| 方法 | 路径 | 描述 |
| ------ | -------------------------- | -------------------------- |
| POST | `/agents` | 创建智能体 |
| GET | `/agents` | 获取智能体列表 |
| GET | `/agents/:id` | 获取智能体详情 |
| PUT | `/agents/:id` | 更新智能体 |
| DELETE | `/agents/:id` | 删除智能体 |
| POST | `/agents/:id/copy` | 复制智能体 |
| GET | `/agents/placeholders` | 获取占位符定义 |
---
## POST `/agents` - 创建智能体
创建新的自定义智能体。成功返回 HTTP 201。
**请求体参数**:
| 参数 | 类型 | 必填 | 说明 |
| ------------- | ------ | ---- | ------------------------------------------------- |
| `name` | string | 是 | 智能体名称 |
| `description` | string | 否 | 智能体描述 |
| `avatar` | string | 否 | 头像(emoji 或图标名称) |
| `config` | object | 否 | 智能体配置,详见 [配置参数](#配置参数) |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/agents' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"name": "我的智能体",
"description": "自定义智能体描述",
"avatar": "🤖",
"config": {
"agent_mode": "smart-reasoning",
"system_prompt": "你是一个专业的助手...",
"temperature": 0.7,
"max_iterations": 10,
"kb_selection_mode": "all",
"web_search_enabled": true,
"multi_turn_enabled": true,
"history_turns": 5
}
}'
```
**响应**:
```json
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "我的智能体",
"description": "自定义智能体描述",
"avatar": "🤖",
"is_builtin": false,
"tenant_id": 1,
"created_by": "user-123",
"config": {
"agent_mode": "smart-reasoning",
"system_prompt": "你是一个专业的助手...",
"temperature": 0.7,
"max_iterations": 10
},
"created_at": "2025-01-19T10:00:00Z",
"updated_at": "2025-01-19T10:00:00Z"
}
}
```
**错误响应**:
| 状态码 | 错误码 | 错误 | 说明 |
| ------ | ------ | --------------------- | --------------------------------- |
| 400 | 1000 | Bad Request | 请求参数错误或智能体名称为空 |
| 500 | 1007 | Internal Server Error | 服务器内部错误 |
---
## GET `/agents` - 获取智能体列表
获取当前空间的所有智能体,包括内置智能体和自定义智能体。响应中额外返回 `disabled_own_agent_ids`,指示当前空间在前端对话下拉框中主动隐藏的本空间自有智能体 ID 列表(不影响其他空间)。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/agents' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**:
```json
{
"success": true,
"data": [
{
"id": "builtin-quick-answer",
"name": "快速问答",
"description": "基于知识库的 RAG 问答,快速准确地回答问题",
"avatar": "💬",
"is_builtin": true,
"tenant_id": 10000,
"created_by": "",
"config": {
"agent_mode": "quick-answer",
"temperature": 0.3,
"max_completion_tokens": 2048,
"kb_selection_mode": "all",
"web_search_enabled": false,
"multi_turn_enabled": true,
"history_turns": 5
},
"created_at": "2025-12-29T20:06:01.696308+08:00",
"updated_at": "2025-12-29T20:06:01.696308+08:00",
"deleted_at": null
},
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "我的智能体",
"is_builtin": false,
"config": {
"agent_mode": "smart-reasoning"
}
}
],
"disabled_own_agent_ids": []
}
```
**错误响应**:
| 状态码 | 错误码 | 错误 | 说明 |
| ------ | ------ | --------------------- | ------------------ |
| 401 | 1001 | Unauthorized | 缺少空间上下文 |
| 500 | 1007 | Internal Server Error | 服务器内部错误 |
---
## GET `/agents/:id` - 获取智能体详情
根据 ID 获取智能体的详细信息。
**路径参数**:
| 参数 | 类型 | 说明 |
| ---- | ------ | -------- |
| `id` | string | 智能体 ID |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/agents/builtin-quick-answer' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**:
```json
{
"success": true,
"data": {
"id": "builtin-quick-answer",
"name": "快速问答",
"description": "基于知识库的 RAG 问答,快速准确地回答问题",
"is_builtin": true,
"tenant_id": 1,
"config": {
"agent_mode": "quick-answer",
"system_prompt": "",
"context_template": "请根据以下参考资料回答用户问题...",
"temperature": 0.7,
"max_completion_tokens": 2048,
"kb_selection_mode": "all",
"web_search_enabled": true,
"multi_turn_enabled": true,
"history_turns": 5
},
"created_at": "2025-01-01T00:00:00Z",
"updated_at": "2025-01-01T00:00:00Z"
}
}
```
**错误响应**:
| 状态码 | 错误码 | 错误 | 说明 |
| ------ | ------ | --------------------- | ------------------ |
| 400 | 1000 | Bad Request | 智能体 ID 为空 |
| 404 | 1003 | Not Found | 智能体不存在 |
| 500 | 1007 | Internal Server Error | 服务器内部错误 |
---
## PUT `/agents/:id` - 更新智能体
更新智能体的名称、描述、头像和配置。内置智能体不可修改。
**路径参数**:
| 参数 | 类型 | 说明 |
| ---- | ------ | -------- |
| `id` | string | 智能体 ID |
**请求体参数**:
| 参数 | 类型 | 必填 | 说明 |
| ------------- | ------ | ---- | ------------ |
| `name` | string | 否 | 智能体名称 |
| `description` | string | 否 | 智能体描述 |
| `avatar` | string | 否 | 智能体头像 |
| `config` | object | 否 | 智能体配置 |
**请求**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/agents/550e8400-e29b-41d4-a716-446655440000' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"name": "更新后的智能体",
"description": "更新后的描述",
"config": {
"agent_mode": "smart-reasoning",
"temperature": 0.8,
"max_iterations": 20
}
}'
```
**响应**:
```json
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "更新后的智能体",
"description": "更新后的描述",
"config": {
"agent_mode": "smart-reasoning",
"temperature": 0.8,
"max_iterations": 20
},
"updated_at": "2025-01-19T11:00:00Z"
}
}
```
**错误响应**:
| 状态码 | 错误码 | 错误 | 说明 |
| ------ | ------ | --------------------- | --------------------------------- |
| 400 | 1000 | Bad Request | 请求参数错误或智能体名称为空 |
| 403 | 1002 | Forbidden | 无法修改内置智能体 |
| 404 | 1003 | Not Found | 智能体不存在 |
| 500 | 1007 | Internal Server Error | 服务器内部错误 |
---
## DELETE `/agents/:id` - 删除智能体
删除指定的自定义智能体。内置智能体不可删除。
**路径参数**:
| 参数 | 类型 | 说明 |
| ---- | ------ | -------- |
| `id` | string | 智能体 ID |
**请求**:
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/agents/550e8400-e29b-41d4-a716-446655440000' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**:
```json
{
"success": true,
"message": "Agent deleted successfully"
}
```
**错误响应**:
| 状态码 | 错误码 | 错误 | 说明 |
| ------ | ------ | --------------------- | --------------------- |
| 400 | 1000 | Bad Request | 智能体 ID 为空 |
| 403 | 1002 | Forbidden | 无法删除内置智能体 |
| 404 | 1003 | Not Found | 智能体不存在 |
| 500 | 1007 | Internal Server Error | 服务器内部错误 |
---
## POST `/agents/:id/copy` - 复制智能体
复制指定的智能体,创建一个新的副本,副本始终为自定义智能体。支持复制内置智能体。成功返回 HTTP 201。
**路径参数**:
| 参数 | 类型 | 说明 |
| ---- | ------ | -------------- |
| `id` | string | 源智能体 ID |
**请求**:
```curl
curl --location --request POST 'http://localhost:8080/api/v1/agents/builtin-smart-reasoning/copy' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**:
```json
{
"success": true,
"data": {
"id": "660e8400-e29b-41d4-a716-446655440001",
"name": "智能推理 (副本)",
"description": "ReAct 推理框架,支持多步思考和工具调用",
"is_builtin": false,
"config": {
"agent_mode": "smart-reasoning",
"max_iterations": 50
},
"created_at": "2025-01-19T12:00:00Z",
"updated_at": "2025-01-19T12:00:00Z"
}
}
```
**错误响应**:
| 状态码 | 错误码 | 错误 | 说明 |
| ------ | ------ | --------------------- | ------------------ |
| 400 | 1000 | Bad Request | 智能体 ID 为空 |
| 404 | 1003 | Not Found | 智能体不存在 |
| 500 | 1007 | Internal Server Error | 服务器内部错误 |
---
## GET `/agents/placeholders` - 获取占位符定义
获取所有可用的提示词占位符定义,按字段类型分组。这些占位符可用于系统提示词和上下文模板中。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/agents/placeholders' \
--header 'X-API-Key: your_api_key'
```
**响应**:
```json
{
"success": true,
"data": {
"all": [...],
"system_prompt": [...],
"agent_system_prompt": [...],
"context_template": [...],
"rewrite_system_prompt": [...],
"rewrite_prompt": [...],
"fallback_prompt": [...]
}
}
```
---
## 配置参数
智能体的 `config` 对象支持以下配置项:
### 基础设置
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `agent_mode` | string | - | 智能体模式:`quick-answer`(RAG)或 `smart-reasoning`(ReAct) |
| `system_prompt` | string | - | 系统提示词,支持使用占位符 |
| `system_prompt_id` | string | - | 系统提示词模板 ID(引用 `prompt_templates/` YAML 文件中的模板) |
| `context_template` | string | - | 上下文模板(仅 quick-answer 模式使用) |
| `context_template_id` | string | - | 上下文模板 ID(引用 `prompt_templates/` YAML 文件中的模板) |
### 模型设置
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `model_id` | string | - | 对话模型 ID |
| `rerank_model_id` | string | - | 重排序模型 ID |
| `temperature` | float | 0.7 | 温度参数(0-1) |
| `max_completion_tokens` | int | 2048 | 最大生成 token 数 |
| `thinking` | *bool | nil | 是否启用思考模式(适用于支持扩展思考的模型) |
### Agent 模式设置
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `max_iterations` | int | 10 | ReAct 最大迭代次数。`-1` 表示不限制,直到模型自然结束或用户停止;正数上限为 100 |
| `allowed_tools` | []string | - | 允许使用的工具列表 |
| `mcp_selection_mode` | string | - | MCP 服务选择模式:`all`/`selected`/`none` |
| `mcp_services` | []string | - | 选中的 MCP 服务 ID 列表 |
| `skills_selection_mode` | string | - | Skills 选择模式:`all`/`selected`/`none` |
| `selected_skills` | []string | - | 选中的 Skill 名称列表(mode 为 `selected` 时) |
### 知识库设置
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `kb_selection_mode` | string | - | 知识库选择模式:`all`/`selected`/`none` |
| `knowledge_bases` | []string | - | 关联的知识库 ID 列表 |
| `retrieve_kb_only_when_mentioned` | bool | false | 仅在用户通过 @ 显式提及时才检索知识库 |
| `supported_file_types` | []string | - | 支持的文件类型(如 `["csv", "xlsx"]`) |
### 图片上传 / 多模态设置
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `image_upload_enabled` | bool | false | 是否允许上传图片 |
| `vlm_model_id` | string | - | 图片分析所用的 VLM 模型 ID |
| `image_storage_provider` | string | - | 图片存储提供者:`local`/`minio`/`cos`/`tos`/`oss`,为空使用全局默认 |
### FAQ 策略设置
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `faq_priority_enabled` | bool | true | FAQ 优先策略开关 |
| `faq_direct_answer_threshold` | float | 0.9 | FAQ 直接回答阈值 |
| `faq_score_boost` | float | 1.2 | FAQ 分数加成系数 |
### 网络搜索设置
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `web_search_enabled` | bool | true | 是否启用网络搜索 |
| `web_search_max_results` | int | 5 | 网络搜索最大结果数 |
| `web_search_provider_id` | string | - | 网络搜索提供者 ID,为空使用空间默认提供者 |
| `web_fetch_enabled` | bool | false | 是否自动获取重排后的搜索结果页面全文 |
| `web_fetch_top_n` | int | 3 | 重排后获取全文的最大页面数 |
### 多轮对话设置
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `multi_turn_enabled` | bool | true | 是否启用多轮对话 |
| `history_turns` | int | 5 | 保留的历史轮次数 |
### 检索策略设置
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `embedding_top_k` | int | 10 | 向量检索 TopK |
| `keyword_threshold` | float | 0.3 | 关键词检索阈值 |
| `vector_threshold` | float | 0.5 | 向量检索阈值 |
| `rerank_top_k` | int | 5 | 重排序 TopK |
| `rerank_threshold` | float | 0.5 | 重排序阈值 |
### 推荐问题设置
`question_suggestions` 是智能体拥有的统一策略。网页嵌入等渠道只能关闭展示,不能覆盖内容或生成规则。
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `question_suggestions.starters.enabled` | bool | true | 是否在首次提问前展示开场问题 |
| `question_suggestions.starters.mode` | string | `hybrid` | `curated`、`knowledge` 或 `hybrid` |
| `question_suggestions.starters.items` | []string | `[]` | 运营配置的开场问题 |
| `question_suggestions.starters.count` | int | 6 | 展示数量,范围 1-8 |
| `question_suggestions.follow_ups.enabled` | bool | false | 是否在每次完整回答后异步生成追问 |
| `question_suggestions.follow_ups.mode` | string | `hybrid` | `generated`、`knowledge` 或 `hybrid` |
| `question_suggestions.follow_ups.count` | int | 3 | 生成数量,范围 1-5 |
| `question_suggestions.follow_ups.model_id` | string | - | 独立生成模型;为空使用本轮对话模型 |
| `question_suggestions.follow_ups.categories` | []string | `clarify,deepen,action` | 允许的问题类型 |
| `question_suggestions.follow_ups.max_context_turns` | int | 2 | 生成时使用的最近对话轮数,范围 1-5 |
| `question_suggestions.follow_ups.additional_instruction` | string | - | 智能体作者的附加生成要求 |
| `question_suggestions.follow_ups.suppress_on_fallback` | bool | true | 兜底回答后不展示 |
| `question_suggestions.follow_ups.suppress_when_answer_asks_question` | bool | true | 回答本身以问题结尾时不展示 |
| `question_suggestions.follow_ups.knowledge_fallback` | bool | true | 模型失败时使用知识库候选补位 |
| `question_suggestions.follow_ups.allow_regenerate` | bool | false | 是否允许用户换一批 |
旧 `suggested_prompts` 会在数据库迁移时一次性写入 `starters.items`,API 不再接受该字段。
### 高级设置
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `enable_query_expansion` | bool | true | 是否启用查询扩展 |
| `enable_rewrite` | bool | true | 是否启用多轮对话查询改写 |
| `rewrite_prompt_system` | string | - | 改写系统提示词 |
| `rewrite_prompt_user` | string | - | 改写用户提示词模板 |
| `fallback_strategy` | string | `model` | 回退策略:`fixed`(固定回复)或 `model`(模型生成);未设置时在服务端默认为 `model` |
| `fallback_response` | string | - | 固定回退回复(`fallback_strategy` 为 `fixed` 时使用) |
| `fallback_prompt` | string | - | 回退提示词(`fallback_strategy` 为 `model` 时使用) |
---
## 使用 Agent 进行问答
创建或获取智能体后,可以通过 `/agent-chat/:session_id` 接口使用智能体进行问答。详情请参考 [聊天功能 API](./chat.md)。
在问答请求中使用 `agent_id` 参数指定要使用的智能体:
```curl
curl --location 'http://localhost:8080/api/v1/agent-chat/session-123' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"query": "帮我分析一下这份数据",
"agent_enabled": true,
"agent_id": "builtin-data-analyst"
}'
```
## 相关文档
- 智能体的组织共享、跨空间分发与禁用(`/agents/:id/shares`、`/shared-agents` 等):见 [组织管理 API](./organization.md)
- 智能体绑定 IM 渠道(`/agents/:id/im-channels`):见组织/IM 渠道相关文档
- 网络搜索提供者配置(被 `web_search_provider_id` 引用):见 [Web Search API](./web-search.md)

View File

@ -1,449 +0,0 @@
# 认证管理 API
[返回目录](./README.md)
OIDC 完整调用流程见 [../OIDC认证调用流程.md](../OIDC认证调用流程.md)。本文档作为端点参考。
## 说明
WeKnora 的 `/auth/*` 端点本身**不需要 X-API-Key**,但部分端点需要在 `Authorization: Bearer <token>` 头中携带由 `/auth/login` 或 `/auth/oidc/callback` 返回的 JWT:
| 端点 | 鉴权方式 |
| --- | --- |
| `/auth/register` `/auth/login` `/auth/config` | 无 |
| `/auth/oidc/config` `/auth/oidc/url` `/auth/oidc/callback` | 无 |
| `/auth/refresh` | refresh_token(请求体携带) |
| `/auth/validate` `/auth/me` `/auth/logout` `/auth/change-password` `/auth/switch-tenant` `/auth/me/preferences` | Bearer JWT |
注册接口可通过环境变量 `DISABLE_REGISTRATION=true` 关闭。密码策略默认 8–32 位且同时包含字母与数字;部署可通过环境变量 `WEKNORA_AUTH_COMPLEX_PASSWORD_ENABLED` 或系统设置 `auth.complex_password_enabled` 要求额外包含大小写字母与特殊字符。当前策略见 `GET /auth/config`。
## 端点一览
| 方法 | 路径 | 描述 |
| ---- | -------------------------- | ------------------------------------------ |
| GET | `/auth/config` | 公开认证配置(注册模式、密码复杂度) |
| POST | `/auth/register` | 用户注册 |
| POST | `/auth/login` | 用户登录 |
| GET | `/auth/oidc/config` | 获取 OIDC 配置元数据 |
| GET | `/auth/oidc/url` | 获取 OIDC 授权链接 |
| GET | `/auth/oidc/callback` | OIDC 授权回调(由 IdP 重定向触发) |
| POST | `/auth/refresh` | 用 refresh_token 换新的 access_token |
| GET | `/auth/validate` | 验证 JWT 有效性 |
| POST | `/auth/logout` | 退出登录 |
| GET | `/auth/me` | 获取当前用户信息 |
| PUT | `/auth/me/preferences` | 更新最近活跃空间等个人偏好 |
| POST | `/auth/switch-tenant` | 切换激活空间并换发 token |
| POST | `/auth/change-password` | 修改密码 |
---
## GET `/auth/config` - 公开认证配置
无需登录。前端用它决定是否展示注册入口,以及注册/改密表单应使用哪套密码规则。
**响应**:
```json
{
"success": true,
"registration_mode": "self_serve",
"complex_password_enabled": false
}
```
| 字段 | 说明 |
| ---- | ---- |
| `registration_mode` | `self_serve` 允许公开注册;`invite_only` 仅邀请 |
| `complex_password_enabled` | `true` 时新密码须含大小写字母、数字和特殊字符 `!@#$%^&*()_+-=[]{}|;:,.<>?` |
---
## POST `/auth/register` - 用户注册
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 校验 | 说明 |
| -------- | ------ | ---- | -------------------------- | --------- |
| username | string | 是 | 长度 2-50 | 用户名 |
| email | string | 是 | 邮箱格式 | 邮箱 |
| password | string | 是 | 8–32 位,须含字母与数字;若 `complex_password_enabled` 则还须含大小写与特殊字符 | 密码 |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/auth/register' \
--header 'Content-Type: application/json' \
--data '{
"username": "alice",
"email": "alice@example.com",
"password": "secret123"
}'
```
**响应**(201 Created):
```json
{
"success": true,
"message": "Registration successful",
"user": {
"id": "usr-...",
"username": "alice",
"email": "alice@example.com",
"tenant_id": 1,
"is_active": true,
"created_at": "2026-05-11T10:00:00+08:00",
"updated_at": "2026-05-11T10:00:00+08:00"
},
"tenant": {
"id": 1,
"name": "alice's workspace",
"api_key": "sk-..."
}
}
```
**错误**: 注册被禁用 → 403;参数校验失败 → 400。
---
## POST `/auth/login` - 用户登录
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| -------- | ------ | ---- | ------------- |
| email | string | 是 | 注册邮箱 |
| password | string | 是 | 密码 |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/auth/login' \
--header 'Content-Type: application/json' \
--data '{
"email": "alice@example.com",
"password": "secret123"
}'
```
**响应**:
```json
{
"success": true,
"message": "Login successful",
"user": { "id": "usr-...", "username": "alice", "email": "alice@example.com" },
"tenant": { "id": 1, "name": "alice's workspace", "api_key": "sk-..." },
"token": "eyJhbGciOi...",
"refresh_token": "eyJhbGciOi..."
}
```
**错误**: 邮箱或密码错误 → 401;账号被禁用 → 403。
---
## GET `/auth/oidc/config` - 获取 OIDC 配置元数据
返回 OIDC 是否启用以及 Provider 显示名,前端登录页据此决定是否展示 OIDC 登录按钮。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/auth/oidc/config'
```
**响应**:
```json
{
"success": true,
"enabled": true,
"provider_display_name": "WeKnora SSO"
}
```
---
## GET `/auth/oidc/url` - 获取 OIDC 授权链接
返回前端应跳转的 OIDC IdP 授权页 URL 与状态码。
**查询参数**:
| 字段 | 类型 | 必填 | 说明 |
| ---------- | ------ | ---- | ------------------------------------------------------- |
| redirect | string | 否 | 登录成功后前端期望落地的路径(如 `/dashboard`),透传到 state |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/auth/oidc/url?redirect=%2Fdashboard'
```
**响应**:
```json
{
"success": true,
"provider_display_name": "WeKnora SSO",
"authorization_url": "https://idp.example.com/oauth/authorize?client_id=...&state=...",
"state": "abcdef..."
}
```
---
## GET `/auth/oidc/callback` - OIDC 授权回调
由 IdP 在用户授权后重定向到此端点。一般不需要客户端代码直接调用——它的作用是把登录结果通过浏览器 hash 传回前端首页。
**查询参数**:
| 字段 | 类型 | 必填 | 说明 |
| ----------------- | ------ | ---- | ----------------------------- |
| code | string | 是 | IdP 颁发的 authorization code |
| state | string | 是 | 与 `/auth/oidc/url` 返回值一致 |
| error | string | 否 | IdP 返回的错误标识 |
| error_description | string | 否 | IdP 返回的错误详情 |
**响应**:始终返回 `302 Found`,跳转到 `/`,并把结果编码进 URL hash:
- 成功:`/#oidc_result=<base64url(JSON payload)>`,其中 payload 包含 `success` / `user` / `tenant` / `token` / `refresh_token` / `is_new_user`,与登录响应一致。
- 失败:`/#oidc_error=<reason>[&oidc_error_description=<message>]`,常见 reason 包括 `invalid_state`、`missing_code`、`login_failed`、`payload_encode_failed`。
---
## GET `/auth/oidc/start` - 发起 OIDC 登录(直接 302)
与 `/auth/oidc/url` 不同,此端点**直接 302 重定向**到 OIDC Provider 的授权页,不返回 JSON,因此无需前端 JS 介入。适用于外部平台(如企业门户 / Nexus)直接给出一个链接即可触发 OIDC 授权码流程,借助 IdP 的 SSO session 实现免再次输密码。
回调地址由后端根据请求自身的 origin(`<scheme>://<host>/api/v1/auth/oidc/callback`)自动构造,无需调用方提供。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/auth/oidc/start'
```
**响应**:`302 Found`,`Location` 指向 IdP 授权页(含 `client_id` / `state` / `redirect_uri` / `scope`)。
> 登录成功后的回调行为与 `/auth/oidc/callback` 一致:302 回前端首页并把登录结果编码进 URL hash。当前登录后固定落到默认首页 `/platform/knowledge-bases`(直达指定业务页的 `next` 参数为未来扩展)。
---
## POST `/auth/refresh` - 刷新令牌
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| ------------- | ------ | ---- | ----------------- |
| refreshToken | string | 是 | 登录时颁发的 refresh_token |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/auth/refresh' \
--header 'Content-Type: application/json' \
--data '{
"refreshToken": "eyJhbGciOi..."
}'
```
**响应**:
```json
{
"success": true,
"message": "Token refreshed successfully",
"access_token": "eyJhbGciOi...",
"refresh_token": "eyJhbGciOi..."
}
```
**错误**: refresh_token 无效或过期 → 401。
---
## GET `/auth/validate` - 验证 JWT
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/auth/validate' \
--header 'Authorization: Bearer eyJhbGciOi...'
```
**响应**:
```json
{
"success": true,
"valid": true,
"user_id": "usr-...",
"tenant_id": 1
}
```
无效 token 返回 401。
---
## POST `/auth/logout` - 退出登录
**请求**:
```curl
curl --location --request POST 'http://localhost:8080/api/v1/auth/logout' \
--header 'Authorization: Bearer eyJhbGciOi...'
```
**响应**: `{ "success": true, "message": "Logged out successfully" }`
---
## GET `/auth/me` - 获取当前用户信息
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/auth/me' \
--header 'Authorization: Bearer eyJhbGciOi...'
```
**响应**:
```json
{
"success": true,
"data": {
"user": {
"id": "usr-...",
"username": "alice",
"email": "alice@example.com",
"avatar": "",
"tenant_id": 1,
"is_active": true,
"can_access_all_tenants": false,
"created_at": "2026-05-11T10:00:00+08:00",
"updated_at": "2026-05-11T10:00:00+08:00"
},
"tenant": {
"id": 1,
"name": "My Workspace"
},
"memberships": [
{
"tenant_id": 1,
"tenant_name": "My Workspace",
"role": "owner"
}
],
"tenant_required": false,
"capabilities": {
"can_create_tenant": false,
"auto_accept_invitation": false
}
}
}
```
`capabilities` 供 SPA 读取部署级开关,无需调用超管设置 API:
| 字段 | 说明 |
| ---- | ---- |
| `can_create_tenant` | 当前用户是否可自助创建空间 |
| `auto_accept_invitation` | 全局 `tenant.auto_accept_invitation`:邮箱邀请已注册用户时是否直接加入(无需收件箱确认) |
---
## POST `/auth/switch-tenant` - 切换激活空间
为当前用户在目标空间重新签发 access / refresh token 对。调用者须在目标空间有 **active** 成员关系(`CanAccessAllTenants` 超级用户切到非 home 空间除外)。
成功换签会把目标空间写入账号级「最近活跃租户」偏好(`users.preferences.last_active_tenant_id`)。refresh JWT **不含** `tenant_id`,因此 **下次登录与 refresh 都按该偏好落点**;一次换签会改变该用户所有设备的落点。偏好写入失败则整次换签失败,**不会**发出新 token。
切回 home 时服务端写入 home ID(与 SPA 发送 `0` 清偏好在当前落点语义上等价)。Web UI 切空间走 `X-Tenant-ID` + `PUT /auth/me/preferences`,不调用本接口。
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| ------------- | ------ | ---- | ---------------------------- |
| tenant_id | uint64 | 是 | 目标空间 ID |
| refresh_token | string | 否 | 当前 refresh token,成功后撤销 |
**请求**:
```curl
curl --location --request POST 'http://localhost:8080/api/v1/auth/switch-tenant' \
--header 'Authorization: Bearer eyJhbGciOi...' \
--header 'Content-Type: application/json' \
--data '{
"tenant_id": 2
}'
```
**响应**: 与登录相同的 `LoginResponse`(`user` / `active_tenant` / `memberships` / `token` / `refresh_token`)。`user.preferences.last_active_tenant_id` 与目标空间一致。
**错误**: 无成员关系或偏好写入失败 → 403;参数校验失败 → 400。
---
## PUT `/auth/me/preferences` - 更新个人偏好
按 PATCH 语义合并 `users.preferences`(仅覆盖请求体里出现的字段)。SPA 在 UI 切空间后用此接口记住落点;`POST /auth/switch-tenant` 会在服务端写同一字段,API 客户端不必再补发本请求。
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| ---------------------- | ------- | ---- | ---- |
| last_active_tenant_id | *uint64 | 否 | 正整数 = 设置/替换;`0` = 清除(下次登录回 home);省略 = 不改 |
**请求**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/auth/me/preferences' \
--header 'Authorization: Bearer eyJhbGciOi...' \
--header 'Content-Type: application/json' \
--data '{
"last_active_tenant_id": 2
}'
```
**响应**: `{ "success": true, "data": { "last_active_tenant_id": 2 } }`
---
## POST `/auth/change-password` - 修改密码
修改当前用户的登录密码。新密码须满足 **8–32 位**且**同时包含字母与数字**;当 `GET /auth/config` 的 `complex_password_enabled` 为 true 时,还须包含大小写字母与特殊字符。不能与当前密码相同。成功后**所有会话被撤销**,需使用新密码重新登录。
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 校验 | 说明 |
| ------------- | ------ | ---- | ------- | --------- |
| old_password | string | 是 | | 当前密码 |
| new_password | string | 是 | 8–32 位,须含字母与数字(复杂模式另需大小写与特殊字符),且不同于旧密码 | 新密码 |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/auth/change-password' \
--header 'Authorization: Bearer eyJhbGciOi...' \
--header 'Content-Type: application/json' \
--data '{
"old_password": "secret123",
"new_password": "newsecret456"
}'
```
**响应**: `{ "success": true, "message": "Password changed successfully" }`
**错误**(400):
| `error.details` | 含义 |
| --------------------- | ---------------------------- |
| `invalid_old_password` | 当前密码不正确 |
| `password_policy` | 新密码不满足长度/复杂度要求 |
| `same_password` | 新密码与当前密码相同 |

View File

@ -1,192 +0,0 @@
# 聊天功能 API
[返回目录](./README.md)
| 方法 | 路径 | 描述 |
| ---- | ----------------------------- | ------------------------ |
| POST | `/knowledge-chat/:session_id` | 基于知识库的问答 |
| POST | `/agent-chat/:session_id` | 基于 Agent 的智能问答 |
| POST | `/knowledge-search` | 基于知识库的搜索知识 |
| GET | `/sessions/:session_id/messages/:message_id/suggestions` | 获取已生成的回答后推荐 |
| POST | `/sessions/:session_id/messages/:message_id/suggestions` | 确保生成或换一批推荐 |
| POST | `/sessions/:session_id/suggestion-events` | 上报曝光、点击、关闭事件 |
## POST `/knowledge-chat/:session_id` - 基于知识库的问答
基于知识库的 RAG 问答,支持 SSE 流式响应。
**查询参数**:
| 参数 | 取值 | 说明 |
|------|------|------|
| `resource_urls` | `handle`(默认)/ `public` | `public` 让答案与引用里的图片直接返回可加载的 http(s) 链接,省去逐个调用 `/files` 代理。详见[文件与图片引用](./README.md#文件与图片引用resource-与直链) |
同样适用于下面的 `/agent-chat/:session_id`、`/knowledge-search`、`/knowledge-bases/:id/hybrid-search` 与 `/sessions/continue-stream/:session_id`。
**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `query` | string | 是 | 查询文本 |
| `knowledge_base_ids` | string[] | 否 | 知识库 ID 列表 |
| `knowledge_ids` | string[] | 否 | 知识文件 ID 列表,指定具体文件进行检索 |
| `agent_id` | string | 否 | 自定义 Agent ID,指定使用的智能体 |
| `summary_model_id` | string | 否 | 覆盖默认的摘要模型 ID |
| `mentioned_items` | object[] | 否 | @提及的知识库和文件列表 |
| `disable_title` | bool | 否 | 是否禁用自动标题生成(默认 false) |
| `images` | object[] | 否 | 附带的图片(base64 格式),需要 Agent 启用图片上传 |
| `channel` | string | 否 | 来源渠道标识:`web`、`api`、`im`、`browser_extension` |
| `suggestion_attribution` | object | 否 | 用户从推荐问题发起本轮时传入 `{suggestion_set_id, question_id}`;服务端会校验归属 |
| `question_origin` | object | 否 | 用户点选智能体推荐问题(`GET /api/v1/agents/{id}/suggested-questions`)时传入该问题的 `{knowledge_base_id, knowledge_id}`。Agent 会先检索这个来源再作答;它只是本轮检索范围内的提示,不会扩大范围。对仅在 @ 提及时检索知识库的智能体,若该知识库在智能体可用范围内,则本轮检索该知识库 |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/knowledge-chat/ceb9babb-1e30-41d7-817d-fd584954304b' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"query": "彗尾的形状",
"knowledge_base_ids": ["kb-00000001"],
"agent_id": "builtin-quick-answer"
}'
```
**响应格式**:
服务器端事件流(Server-Sent Events,Content-Type: text/event-stream)
**响应**:
```
event: message
data: {"id":"3475c004-0ada-4306-9d30-d7f5efce50d2","response_type":"references","content":"","done":false,"knowledge_references":[{"id":"c8347bef-...","content":"彗星xxx。","knowledge_id":"a6790b93-...","chunk_index":0,"knowledge_title":"彗星.txt","score":4.04,"match_type":3,"chunk_type":"text","knowledge_filename":"彗星.txt"}]}
event: message
data: {"id":"3475c004-0ada-4306-9d30-d7f5efce50d2","response_type":"answer","content":"彗尾的形状主要表现为...","done":false,"knowledge_references":null}
event: message
data: {"id":"3475c004-0ada-4306-9d30-d7f5efce50d2","response_type":"answer","content":"","done":true,"knowledge_references":null}
```
## POST `/agent-chat/:session_id` - 基于 Agent 的智能问答
Agent 模式支持更智能的问答,包括工具调用、网络搜索、多知识库检索等能力。
**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `query` | string | 是 | 查询文本 |
| `knowledge_base_ids` | string[] | 否 | 知识库 ID 列表,可动态指定本次查询使用的知识库 |
| `knowledge_ids` | string[] | 否 | 知识文件 ID 列表,可动态指定本次查询使用的具体文件 |
| `agent_enabled` | bool | 否 | 是否启用 Agent 模式(默认 false,优先使用 Agent 配置) |
| `agent_id` | string | 否 | 自定义 Agent ID,指定使用的智能体(支持共享 Agent) |
| `web_search_enabled` | bool | 否 | 是否启用网络搜索(默认 false) |
| `summary_model_id` | string | 否 | 覆盖默认的摘要模型 ID |
| `mentioned_items` | object[] | 否 | @提及的知识库和文件列表 |
| `disable_title` | bool | 否 | 是否禁用自动标题生成(默认 false) |
| `images` | object[] | 否 | 附带的图片(base64 格式),需要 Agent 启用图片上传 |
| `channel` | string | 否 | 来源渠道标识:`web`、`api`、`im`、`browser_extension` |
| `suggestion_attribution` | object | 否 | 用户从推荐问题发起本轮时传入 `{suggestion_set_id, question_id}`;服务端会校验归属 |
| `question_origin` | object | 否 | 用户点选智能体推荐问题(`GET /api/v1/agents/{id}/suggested-questions`)时传入该问题的 `{knowledge_base_id, knowledge_id}`。Agent 会先检索这个来源再作答;它只是本轮检索范围内的提示,不会扩大范围。对仅在 @ 提及时检索知识库的智能体,若该知识库在智能体可用范围内,则本轮检索该知识库 |
## 回答后推荐问题
回答主消息完成后,服务端会异步生成推荐问题,不阻塞 SSE 的 `complete`/`done` 事件。生成结果按“空间、助手消息、位置、配置快照、语言”持久化并去重。
```http
POST /api/v1/sessions/{session_id}/messages/{message_id}/suggestions
Content-Type: application/json
{"regenerate": false}
```
状态包括 `generating`、`ready`、`suppressed`、`failed`。`ready` 时的每个问题都有稳定 `id`,点击后应先上报事件,并在下一次聊天请求中携带 `suggestion_attribution`。
```http
POST /api/v1/sessions/{session_id}/suggestion-events
Content-Type: application/json
{
"suggestion_set_id": "...",
"question_id": "...",
"event_type": "click"
}
```
网页嵌入提供同构接口:`/api/v1/embed/{channel_id}/sessions/{session_id}/...`,继续使用嵌入令牌和 `X-Embed-Session`。
**mentioned_items 结构**:
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 知识库或文件 ID |
| `name` | string | 显示名称 |
| `type` | string | 类型:`kb`(知识库)或 `file`(文件) |
| `kb_type` | string | 知识库类型:`document` 或 `faq`(仅 `type=kb` 时) |
**images 结构**:
| 字段 | 类型 | 说明 |
|------|------|------|
| `data` | string | base64 编码的图片数据(`data:image/png;base64,...`) |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/agent-chat/ceb9babb-1e30-41d7-817d-fd584954304b' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"query": "帮我查询今天的天气",
"agent_enabled": true,
"web_search_enabled": true,
"knowledge_base_ids": ["kb-00000001"],
"agent_id": "builtin-smart-reasoning",
"mentioned_items": [
{
"id": "kb-00000001",
"name": "天气知识库",
"type": "kb",
"kb_type": "document"
}
]
}'
```
**响应格式**:
服务器端事件流(Server-Sent Events,Content-Type: text/event-stream)
**响应类型说明**:
| response_type | 描述 |
|---------------|------|
| `agent_query` | Agent 开始处理查询 |
| `thinking` | Agent 思考过程 |
| `tool_call` | 工具调用信息 |
| `tool_result` | 工具调用结果 |
| `references` | 知识库检索引用 |
| `answer` | 最终回答内容 |
| `artifacts_pending` | Skill/沙箱产物正在上传;`data.count` 为待保存文件数。回答可能已经 `done`,文件按钮会在此期间显示加载态,直至 `complete` 带上 `artifacts` |
| `reflection` | Agent 反思内容 |
| `session_title` | 自动生成的会话标题 |
| `error` | 错误信息 |
**响应示例**:
```
event: message
data: {"id":"req-001","response_type":"thinking","content":"用户想查询天气,我需要使用网络搜索工具...","done":false}
event: message
data: {"id":"req-001","response_type":"tool_call","content":"","done":false,"data":{"tool_name":"web_search","arguments":{"query":"今天天气"}}}
event: message
data: {"id":"req-001","response_type":"tool_result","content":"搜索结果:今天晴,气温25°C...","done":false}
event: message
data: {"id":"req-001","response_type":"answer","content":"根据查询结果,今天天气晴朗,气温约25°C。","done":false}
event: message
data: {"id":"req-001","response_type":"answer","content":"","done":true}
```

View File

@ -1,220 +0,0 @@
# 分块管理 API
[返回目录](./README.md)
| 方法 | 路径 | 描述 |
| ------ | --------------------------------- | -------------------------- |
| GET | `/chunks/:knowledge_id` | 获取知识的分块列表 |
| PUT | `/chunks/:knowledge_id/:id` | 更新分块 |
| DELETE | `/chunks/:knowledge_id/:id` | 删除单个分块 |
| DELETE | `/chunks/:knowledge_id` | 删除知识下的所有分块 |
| GET | `/chunks/by-id/:id` | 根据分块 ID 直接获取分块 |
| DELETE | `/chunks/by-id/:id/questions` | 删除分块下的某个生成问题 |
## GET `/chunks/:knowledge_id` - 获取知识的分块列表
**路径参数**:
| 字段 | 类型 | 说明 |
| ------------- | ------ | ----------- |
| knowledge_id | string | 知识 ID |
**查询参数**:
| 字段 | 类型 | 默认 | 说明 |
| ---------- | ---- | ---- | ---------- |
| page | int | 1 | 页码 |
| page_size | int | 20 | 每页条数 |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/chunks/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5?page=1&page_size=1' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": [
{
"id": "df10b37d-cd05-4b14-ba8a-e1bd0eb3bbd7",
"tenant_id": 1,
"knowledge_id": "4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5",
"knowledge_base_id": "kb-00000001",
"tag_id": "",
"content": "彗星xxxx",
"chunk_index": 0,
"is_enabled": true,
"status": 2,
"start_at": 0,
"end_at": 964,
"pre_chunk_id": "",
"next_chunk_id": "",
"chunk_type": "text",
"parent_chunk_id": "",
"relation_chunks": null,
"indirect_relation_chunks": null,
"metadata": null,
"content_hash": "",
"image_info": "",
"created_at": "2025-08-12T11:52:36.168632+08:00",
"updated_at": "2025-08-12T11:52:53.376871+08:00",
"deleted_at": null
}
],
"page": 1,
"page_size": 1,
"success": true,
"total": 5
}
```
## PUT `/chunks/:knowledge_id/:id` - 更新分块
更新指定分块的内容和属性。所有字段均可选,未传则保留原值。
**路径参数**:
| 字段 | 类型 | 说明 |
| ------------- | ------ | ----------- |
| knowledge_id | string | 知识 ID |
| id | string | 分块 ID |
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| ------------ | ------- | ---- | --------------------- |
| content | string | 否 | 分块内容 |
| chunk_index | int | 否 | 分块在知识中的序号 |
| is_enabled | boolean | 否 | 是否启用 |
| start_at | int | 否 | 起始位置(字符偏移) |
| end_at | int | 否 | 结束位置(字符偏移) |
| image_info | string | 否 | 图像分块的元信息(JSON 字符串) |
**请求**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/chunks/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5/df10b37d-cd05-4b14-ba8a-e1bd0eb3bbd7' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"content": "更新后的分块内容",
"is_enabled": true
}'
```
**响应**:
```json
{
"data": {
"id": "df10b37d-cd05-4b14-ba8a-e1bd0eb3bbd7",
"content": "更新后的分块内容",
"is_enabled": true,
"...": "其他字段同 GET 响应"
},
"success": true
}
```
## DELETE `/chunks/:knowledge_id/:id` - 删除单个分块
**路径参数**: 同 PUT。
**请求**:
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/chunks/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5/df10b37d-cd05-4b14-ba8a-e1bd0eb3bbd7' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**:
```json
{
"message": "Chunk deleted",
"success": true
}
```
## DELETE `/chunks/:knowledge_id` - 删除知识下的所有分块
**路径参数**:
| 字段 | 类型 | 说明 |
| ------------- | ------ | ----------- |
| knowledge_id | string | 知识 ID |
**请求**:
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/chunks/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**:
```json
{
"message": "All chunks under knowledge deleted",
"success": true
}
```
## GET `/chunks/by-id/:id` - 根据 ID 直接获取分块
无需提供 `knowledge_id` 即可获取分块。常用于跨知识库的引用展示。
**路径参数**:
| 字段 | 类型 | 说明 |
| ---- | ------ | ------- |
| id | string | 分块 ID |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/chunks/by-id/df10b37d-cd05-4b14-ba8a-e1bd0eb3bbd7' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**: 同 `GET /chunks/:knowledge_id` 列表中的单条 data。
## DELETE `/chunks/by-id/:id/questions` - 删除分块下的某个生成问题
删除指定分块关联的某条生成问题。
**路径参数**:
| 字段 | 类型 | 说明 |
| ---- | ------ | ------- |
| id | string | 分块 ID |
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| ----------- | ------ | ---- | ----------- |
| question_id | string | 是 | 问题 ID |
**请求**:
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/chunks/by-id/df10b37d-cd05-4b14-ba8a-e1bd0eb3bbd7/questions' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"question_id": "q-00000001"
}'
```
**响应**:
```json
{
"message": "Question deleted successfully",
"success": true
}
```

View File

@ -1,161 +0,0 @@
# 评估功能 API
[返回目录](./README.md)
| 方法 | 路径 | 描述 |
| ---- | -------------- | --------------------- |
| GET | `/evaluation/` | 获取评估任务结果 |
| POST | `/evaluation/` | 创建评估任务 |
> 注:服务端路由带尾斜杠(Gin 会自动从 `/evaluation` 重定向到 `/evaluation/`),下方示例为方便阅读用了 `/evaluation`。
## GET `/evaluation` - 获取评估任务结果
**参数说明(查询参数)**:
| 字段 | 类型 | 必填 | 说明 |
| -------- | ------ | ---- | --------------------------------------------------- |
| task_id | string | 是 | 从 `POST /evaluation` 返回的任务 ID |
**请求**:
```bash
curl --location 'http://localhost:8080/api/v1/evaluation?task_id=c34563ad-b09f-4858-b72e-e92beb80becb' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": {
"task": {
"id": "c34563ad-b09f-4858-b72e-e92beb80becb",
"tenant_id": 1,
"dataset_id": "default",
"start_time": "2025-08-12T14:54:26.221804768+08:00",
"status": 2,
"total": 1,
"finished": 1
},
"params": {
"session_id": "",
"knowledge_base_id": "2ef57434-8c8d-4442-b967-2f7fc578a2fc",
"vector_threshold": 0.5,
"keyword_threshold": 0.3,
"embedding_top_k": 10,
"vector_database": "",
"rerank_model_id": "b30171a1-787b-426e-a293-735cd5ac16c0",
"rerank_top_k": 5,
"rerank_threshold": 0.7,
"chat_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c",
"summary_config": {
"max_tokens": 0,
"repeat_penalty": 1,
"top_k": 0,
"top_p": 0,
"frequency_penalty": 0,
"presence_penalty": 0,
"prompt": "这是用户和助手之间的对话。",
"context_template": "你是一个专业的智能信息检索助手",
"no_match_prefix": "<think>\n</think>\nNO_MATCH",
"temperature": 0.3,
"seed": 0,
"max_completion_tokens": 2048
},
"fallback_strategy": "",
"fallback_response": "抱歉,我无法回答这个问题。"
},
"metric": {
"retrieval_metrics": {
"precision": 0,
"recall": 0,
"ndcg3": 0,
"ndcg10": 0,
"mrr": 0,
"map": 0
},
"generation_metrics": {
"bleu1": 0.037656734016532384,
"bleu2": 0.04067392145167686,
"bleu4": 0.048963321289052536,
"rouge1": 0,
"rouge2": 0,
"rougel": 0
}
}
},
"success": true
}
```
## POST `/evaluation` - 创建评估任务
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| ----------------- | ------ | ---- | ----------------------------------------------- |
| dataset_id | string | 是 | 评估数据集,目前仅支持 `default`(官方测试集) |
| knowledge_base_id | string | 是 | 评估使用的知识库 ID |
| chat_id | string | 是 | 评估使用的对话模型 ID |
| rerank_id | string | 是 | 评估使用的重排序模型 ID |
**请求**:
```bash
curl --location 'http://localhost:8080/api/v1/evaluation' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"dataset_id": "default",
"knowledge_base_id": "kb-00000001",
"chat_id": "8aea788c-bb30-4898-809e-e40c14ffb48c",
"rerank_id": "b30171a1-787b-426e-a293-735cd5ac16c0"
}'
```
**响应**:
```json
{
"data": {
"task": {
"id": "c34563ad-b09f-4858-b72e-e92beb80becb",
"tenant_id": 1,
"dataset_id": "default",
"start_time": "2025-08-12T14:54:26.221804768+08:00",
"status": 1
},
"params": {
"session_id": "",
"knowledge_base_id": "2ef57434-8c8d-4442-b967-2f7fc578a2fc",
"vector_threshold": 0.5,
"keyword_threshold": 0.3,
"embedding_top_k": 10,
"vector_database": "",
"rerank_model_id": "b30171a1-787b-426e-a293-735cd5ac16c0",
"rerank_top_k": 5,
"rerank_threshold": 0.7,
"chat_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c",
"summary_config": {
"max_tokens": 0,
"repeat_penalty": 1,
"top_k": 0,
"top_p": 0,
"frequency_penalty": 0,
"presence_penalty": 0,
"prompt": "这是用户和助手之间的对话。",
"context_template": "你是一个专业的智能信息检索助手,xxx",
"no_match_prefix": "<think>\n</think>\nNO_MATCH",
"temperature": 0.3,
"seed": 0,
"max_completion_tokens": 2048
},
"fallback_strategy": "",
"fallback_response": "抱歉,我无法回答这个问题。"
}
},
"success": true
}
```

View File

@ -1,567 +0,0 @@
# FAQ管理 API
[返回目录](./README.md)
FAQ 接口分为两组:
- `/knowledge-bases/:id/faq/*`:知识库范围内的 FAQ 条目 CRUD、批量操作、搜索与导入导出。
- `/faq/import/progress/:task_id`:**不属于知识库分组**,用于查询异步导入/dry-run 任务的进度,仅需任务 ID 即可调用。
| 方法 | 路径 | 描述 |
| ------ | ----------------------------------------------------------------- | --------------------------------- |
| GET | `/knowledge-bases/:id/faq/entries` | 获取 FAQ 条目列表 |
| GET | `/knowledge-bases/:id/faq/entries/export` | 导出 FAQ 条目(CSV) |
| GET | `/knowledge-bases/:id/faq/entries/:entry_id` | 获取单个 FAQ 条目(按 seq_id) |
| POST | `/knowledge-bases/:id/faq/entries` | 批量 Upsert FAQ 条目(异步) |
| POST | `/knowledge-bases/:id/faq/entry` | 同步创建单个 FAQ 条目 |
| PUT | `/knowledge-bases/:id/faq/entries/:entry_id` | 更新单个 FAQ 条目 |
| POST | `/knowledge-bases/:id/faq/entries/:entry_id/similar-questions` | 为 FAQ 条目追加相似问 |
| PUT | `/knowledge-bases/:id/faq/entries/fields` | 批量更新字段(启用/推荐/标签) |
| PUT | `/knowledge-bases/:id/faq/entries/tags` | 批量更新标签 |
| DELETE | `/knowledge-bases/:id/faq/entries` | 批量删除 FAQ 条目 |
| POST | `/knowledge-bases/:id/faq/search` | FAQ 混合搜索 |
| PUT | `/knowledge-bases/:id/faq/import/last-result/display` | 更新上次导入结果卡片显示状态 |
| GET | `/faq/import/progress/:task_id` | 查询 FAQ 导入任务进度(公共) |
> **路径参数说明**:`:entry_id` 始终是 FAQ 条目的 `seq_id`(整数),不是字符串形式的 ID。同理,批量接口中的 `by_id` / `by_tag` / `exclude_ids` / `ids` 字段均为 `seq_id` 列表(整数)。
## GET `/knowledge-bases/:id/faq/entries` - 获取 FAQ 条目列表
支持分页、按标签、启用状态过滤、关键字搜索与排序。
**查询参数**:
| 参数 | 类型 | 必填 | 说明 |
| ------------ | ------ | ---- | --------------------------------------------------------------------------------------------- |
| page | int | 否 | 页码,默认 1 |
| page_size | int | 否 | 每页数量,默认 20 |
| tag_id | int | 否 | 按标签 `seq_id` 过滤 |
| keyword | string | 否 | 关键字搜索 |
| search_field | string | 否 | 搜索字段:`standard_question` / `similar_questions` / `answers`,留空则全字段搜索 |
| sort_order | string | 否 | 排序方式,`asc` 表示按更新时间正序,默认按更新时间倒序 |
| is_enabled | bool | 否 | 启用状态;`true` 仅返回已启用条目,`false` 仅返回未启用条目,不传时返回全部 |
**请求**:
```curl
# 全字段搜索
curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries?page=1&page_size=10&keyword=密码' \
--header 'X-API-Key: sk-xxxxx'
# 仅搜索标准问
curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries?keyword=密码&search_field=standard_question' \
--header 'X-API-Key: sk-xxxxx'
# 仅查看未启用条目
curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries?is_enabled=false' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**:
```json
{
"data": {
"total": 100,
"page": 1,
"page_size": 10,
"data": [
{
"id": 1,
"chunk_id": "chunk-00000001",
"knowledge_id": "knowledge-00000001",
"knowledge_base_id": "kb-00000001",
"tag_id": 12,
"tag_name": "账户",
"is_enabled": true,
"is_recommended": false,
"standard_question": "如何重置密码?",
"similar_questions": ["忘记密码怎么办", "密码找回"],
"negative_questions": ["如何修改用户名"],
"answers": ["您可以通过点击登录页面的'忘记密码'链接来重置密码。"],
"answer_strategy": "all",
"index_mode": "hybrid",
"chunk_type": "faq",
"created_at": "2025-08-12T10:00:00+08:00",
"updated_at": "2025-08-12T10:00:00+08:00"
}
]
},
"success": true
}
```
## GET `/knowledge-bases/:id/faq/entries/export` - 导出 FAQ 条目
将知识库下的所有 FAQ 条目导出为 CSV(UTF-8 带 BOM,Excel 兼容)。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries/export' \
--header 'X-API-Key: sk-xxxxx' \
--output faq_export.csv
```
**响应**: `Content-Type: text/csv; charset=utf-8`,附带文件名 `faq_export.csv`。
## GET `/knowledge-bases/:id/faq/entries/:entry_id` - 获取单个 FAQ 条目
根据 `seq_id`(整数)获取单个 FAQ 条目详情。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries/1' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**:
```json
{
"data": {
"id": 1,
"chunk_id": "chunk-00000001",
"knowledge_id": "knowledge-00000001",
"knowledge_base_id": "kb-00000001",
"tag_id": 12,
"tag_name": "账户",
"is_enabled": true,
"is_recommended": false,
"standard_question": "如何重置密码?",
"similar_questions": ["忘记密码怎么办", "密码找回"],
"negative_questions": [],
"answers": ["您可以通过点击登录页面的'忘记密码'链接来重置密码。"],
"answer_strategy": "all",
"index_mode": "hybrid",
"chunk_type": "faq",
"created_at": "2025-08-12T10:00:00+08:00",
"updated_at": "2025-08-12T10:00:00+08:00"
},
"success": true
}
```
## POST `/knowledge-bases/:id/faq/entries` - 批量 Upsert FAQ 条目(异步)
**异步**批量导入或更新 FAQ 条目。接口立即返回 `task_id`,调用方需通过 `GET /faq/import/progress/:task_id` 查询进度与结果。
支持 `dry_run=true`:异步执行仅校验(格式 / 批内重复 / 与库内重复 / 内容安全),不实际写入。
**请求体(`types.FAQBatchUpsertPayload`)**:
| 字段 | 类型 | 必填 | 说明 |
| ------------ | -------------------------- | ---- | ----------------------------------------------------------------------------------- |
| entries | `[]FAQEntryPayload` | 是 | FAQ 条目数组 |
| mode | string | 是 | `append` 或 `replace`(替换会清空已有条目) |
| knowledge_id | string | 否 | 关联的 FAQ Knowledge ID(不传则使用知识库默认 FAQ knowledge) |
| task_id | string | 否 | 任务 ID,不传则自动生成 UUID |
| dry_run | boolean | 否 | 仅验证不导入 |
`FAQEntryPayload` 字段:
| 字段 | 类型 | 必填 | 说明 |
| ------------------- | --------- | ---- | ------------------------------------------------------------- |
| id | int64 | 否 | 指定 `seq_id`(数据迁移场景,需小于自增起始值 100000000) |
| standard_question | string | 是 | 标准问 |
| similar_questions | string[] | 否 | 相似问列表 |
| negative_questions | string[] | 否 | 反例问题列表 |
| answers | string[] | 否 | 答案列表 |
| answer_strategy | string | 否 | 答案返回策略:`all` 或 `random` |
| tag_id | int64 | 否 | 标签 `seq_id` |
| tag_name | string | 否 | 标签名(用于按名匹配标签) |
| is_enabled | boolean | 否 | 是否启用 |
| is_recommended | boolean | 否 | 是否推荐 |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"mode": "append",
"entries": [
{
"standard_question": "如何联系客服?",
"similar_questions": ["客服电话", "在线客服"],
"answers": ["您可以通过拨打400-xxx-xxxx联系我们的客服。"],
"tag_id": 1
},
{
"standard_question": "退款政策是什么?",
"answers": ["我们提供7天无理由退款服务。"]
}
]
}'
```
**响应**:
```json
{
"data": { "task_id": "task-00000001" },
"success": true
}
```
> 用 `GET /faq/import/progress/:task_id` 查询任务最终状态。
## POST `/knowledge-bases/:id/faq/entry` - 同步创建单个 FAQ 条目
**同步**创建单条 FAQ 条目,会即时校验标准问/相似问与库内已有条目的重复。
**请求体**: 同上 `FAQEntryPayload`(`standard_question` 必填)。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entry' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"standard_question": "如何联系客服?",
"similar_questions": ["客服电话", "在线客服"],
"answers": ["您可以通过拨打400-xxx-xxxx联系我们的客服。"],
"tag_id": 1,
"is_enabled": true
}'
```
**响应**:
```json
{
"data": {
"id": 1,
"chunk_id": "chunk-00000001",
"knowledge_id": "knowledge-00000001",
"knowledge_base_id": "kb-00000001",
"tag_id": 1,
"tag_name": "客服",
"is_enabled": true,
"is_recommended": false,
"standard_question": "如何联系客服?",
"similar_questions": ["客服电话", "在线客服"],
"negative_questions": [],
"answers": ["您可以通过拨打400-xxx-xxxx联系我们的客服。"],
"answer_strategy": "all",
"index_mode": "hybrid",
"chunk_type": "faq",
"created_at": "2025-08-12T10:00:00+08:00",
"updated_at": "2025-08-12T10:00:00+08:00"
},
"success": true
}
```
**错误响应**(标准问或相似问重复时):
```json
{
"success": false,
"error": {
"code": "BAD_REQUEST",
"message": "标准问与已有FAQ重复"
}
}
```
## PUT `/knowledge-bases/:id/faq/entries/:entry_id` - 更新单个 FAQ 条目
按 `seq_id` 更新单条 FAQ 条目,请求体同 `FAQEntryPayload`。
**请求**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries/1' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"standard_question": "如何重置账户密码?",
"similar_questions": ["忘记密码怎么办", "密码找回", "重置密码"],
"answers": ["您可以通过以下步骤重置密码:1. 点击登录页面的\"忘记密码\" 2. 输入注册邮箱 3. 查收重置邮件"],
"is_enabled": true
}'
```
**响应**: 返回更新后的 FAQ 条目,结构同创建接口。
## POST `/knowledge-bases/:id/faq/entries/:entry_id/similar-questions` - 追加相似问
向指定 FAQ 条目(`seq_id`)追加相似问。
**请求体**:
| 字段 | 类型 | 必填 | 说明 |
| ----------------- | -------- | ---- | --------------------- |
| similar_questions | string[] | 是 | 要追加的相似问数组 |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries/1/similar-questions' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"similar_questions": ["怎样修改密码", "密码重置方法"]
}'
```
**响应**: 返回追加后的完整 FAQ 条目。
## PUT `/knowledge-bases/:id/faq/entries/fields` - 批量更新字段
**统一**的批量字段更新接口,支持同时更新 `is_enabled` / `is_recommended` / `tag_id`,并支持两种作用域:
- **按条目 ID** (`by_id`):键为条目 `seq_id`,值为该条目要更新的字段。
- **按标签 ID** (`by_tag`):键为标签 `seq_id`,对该标签下的所有条目应用相同的字段更新;可配合 `exclude_ids` 排除部分条目。
`by_id` 和 `by_tag` 至少传一项;二者可同时使用。
**请求体(`types.FAQEntryFieldsBatchUpdate`)**:
| 字段 | 类型 | 必填 | 说明 |
| ----------- | --------------------------------- | ---- | ------------------------------------------ |
| by_id | `map[int64]FAQEntryFieldsUpdate` | 否 | 按条目 `seq_id` 更新 |
| by_tag | `map[int64]FAQEntryFieldsUpdate` | 否 | 按标签 `seq_id` 对该标签下所有条目更新 |
| exclude_ids | `int64[]` | 否 | 与 `by_tag` 配合使用,排除指定条目 `seq_id` |
`FAQEntryFieldsUpdate` 字段(全部可选,仅传入的字段会被更新):
| 字段 | 类型 | 说明 |
| -------------- | ------- | -------------- |
| is_enabled | boolean | 是否启用 |
| is_recommended | boolean | 是否推荐 |
| tag_id | int64 | 标签 `seq_id` |
**请求**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries/fields' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"by_id": {
"1": {"is_enabled": true, "is_recommended": false},
"2": {"is_enabled": false}
},
"by_tag": {
"100": {"is_recommended": true}
},
"exclude_ids": [3, 4]
}'
```
**响应**:
```json
{ "success": true }
```
## PUT `/knowledge-bases/:id/faq/entries/tags` - 批量更新标签
仅更新标签关联。键为条目 `seq_id`,值为目标标签 `seq_id`;值传 `null` 表示清除标签。
**请求体**:
| 字段 | 类型 | 必填 | 说明 |
| ------- | --------------------- | ---- | -------------------------------------------- |
| updates | `map[int64]int64?` | 是 | 键:条目 `seq_id`;值:标签 `seq_id` 或 `null` |
**请求**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries/tags' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"updates": {
"1": 10,
"2": 11,
"3": null
}
}'
```
**响应**:
```json
{ "success": true }
```
## DELETE `/knowledge-bases/:id/faq/entries` - 批量删除
**请求体**:
| 字段 | 类型 | 必填 | 说明 |
| ---- | --------- | ---- | --------------------------------- |
| ids | `int64[]` | 是 | 要删除的 FAQ 条目 `seq_id` 列表 |
**请求**:
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"ids": [1, 2, 3]
}'
```
**响应**:
```json
{ "success": true }
```
## POST `/knowledge-bases/:id/faq/search` - FAQ 混合搜索
向量 + 关键字混合检索,支持两级优先级标签召回。
**请求体(`types.FAQSearchRequest`)**:
| 字段 | 类型 | 必填 | 说明 |
| ----------------------- | --------- | ---- | ----------------------------------------------------------------------------------- |
| query_text | string | 是 | 搜索文本 |
| vector_threshold | float | 否 | 向量相似度阈值(0–1) |
| match_count | int | 否 | 返回数量,默认 10,最大 200 |
| first_priority_tag_ids | `int64[]` | 否 | 第一优先级标签 `seq_id` 列表(最高优先召回范围) |
| second_priority_tag_ids | `int64[]` | 否 | 第二优先级标签 `seq_id` 列表 |
| only_recommended | boolean | 否 | 是否仅返回 `is_recommended=true` 的条目 |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/search' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"query_text": "如何重置密码",
"vector_threshold": 0.5,
"match_count": 10,
"first_priority_tag_ids": [12],
"only_recommended": false
}'
```
**响应**:
```json
{
"data": [
{
"id": 1,
"chunk_id": "chunk-00000001",
"knowledge_id": "knowledge-00000001",
"knowledge_base_id": "kb-00000001",
"tag_id": 12,
"tag_name": "账户",
"is_enabled": true,
"is_recommended": false,
"standard_question": "如何重置密码?",
"similar_questions": ["忘记密码怎么办", "密码找回"],
"answers": ["您可以通过点击登录页面的'忘记密码'链接来重置密码。"],
"answer_strategy": "all",
"chunk_type": "faq",
"score": 0.95,
"match_type": "vector",
"matched_question": "忘记密码怎么办",
"created_at": "2025-08-12T10:00:00+08:00",
"updated_at": "2025-08-12T10:00:00+08:00"
}
],
"success": true
}
```
## PUT `/knowledge-bases/:id/faq/import/last-result/display` - 更新上次导入结果显示状态
控制上次导入完成后,前端结果卡片的显示/隐藏。
**请求体**:
| 字段 | 类型 | 必填 | 说明 |
| -------------- | ------ | ---- | --------------------- |
| display_status | string | 是 | `open` 或 `close` |
**请求**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/import/last-result/display' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"display_status": "close"
}'
```
**响应**:
```json
{ "success": true }
```
## GET `/faq/import/progress/:task_id` - 查询 FAQ 导入进度
> **注意**:此接口**不在** `/knowledge-bases/:id/faq` 分组下,路径直接以 `/faq/import/progress/:task_id` 开头。任务 ID 由 `POST /knowledge-bases/:id/faq/entries` 返回。
**路径参数**:
| 参数 | 类型 | 说明 |
| ------- | ------ | -------------- |
| task_id | string | 导入任务的 ID |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/faq/import/progress/task-00000001' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**(节选关键字段):
```json
{
"data": {
"task_id": "task-00000001",
"kb_id": "kb-00000001",
"knowledge_id": "knowledge-00000001",
"status": "completed",
"progress": 100,
"total": 100,
"processed": 100,
"success_count": 95,
"failed_count": 3,
"partial_failed_count": 2,
"skipped_count": 0,
"failed_entries": [
{
"index": 5,
"reason": "标准问与已有FAQ重复",
"standard_question": "重复的问题"
}
],
"success_entries": [
{ "index": 0, "seq_id": 101, "standard_question": "如何联系客服?" }
],
"message": "",
"error": "",
"created_at": 1736582400,
"updated_at": 1736582460,
"dry_run": false,
"import_mode": "append",
"imported_at": "2025-08-12T10:01:00+08:00",
"display_status": "open",
"processing_time": 60000
},
"success": true
}
```
`status` 可能取值:`pending` / `processing` / `completed` / `failed`。
当失败条目过多时,`failed_entries` 可能不直接返回,而通过 `failed_entries_url` 提供 CSV 下载地址。
`dry_run=true` 模式下的任务同样通过此接口查询,`success_entries` 中的 `seq_id` 不会真正写入。

View File

@ -1,402 +0,0 @@
# 初始化配置 API
[返回目录](./README.md)
| 方法 | 路径 | 描述 |
| ------ | ------------------------------------------------- | -------------------------- |
| GET | `/initialization/config/:kb_id` | 获取知识库初始化配置 |
| POST | `/initialization/initialize/:kb_id` | 初始化知识库模型配置 |
| PUT | `/initialization/config/:kb_id` | 更新知识库模型配置 |
| GET | `/initialization/ollama/status` | 检查 Ollama 状态 |
| GET | `/initialization/ollama/models` | 获取本地 Ollama 模型列表 |
| POST | `/initialization/ollama/models/check` | 检查 Ollama 模型是否可用 |
| POST | `/initialization/ollama/models/download` | 下载 Ollama 模型 |
| GET | `/initialization/ollama/download/progress/:task_id` | 获取下载进度 |
| GET | `/initialization/ollama/download/tasks` | 获取所有下载任务 |
| POST | `/initialization/remote/check` | 检查远程模型 API |
| POST | `/initialization/embedding/test` | 测试嵌入模型 |
| POST | `/initialization/rerank/check` | 检查重排序模型 |
| POST | `/initialization/multimodal/test` | 测试多模态模型 |
| POST | `/initialization/extract/text-relation` | 提取文本关系 |
## GET `/initialization/config/:kb_id` - 获取知识库初始化配置
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/initialization/config/kb-00000001' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": {
"chat_model_id": "model-00000001",
"embedding_model_id": "model-00000002",
"rerank_model_id": "model-00000003",
"multimodal_id": "model-00000004"
},
"success": true
}
```
## POST `/initialization/initialize/:kb_id` - 初始化知识库模型配置
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/initialization/initialize/kb-00000001' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"chat_model_id": "model-00000001",
"embedding_model_id": "model-00000002",
"rerank_model_id": "model-00000003",
"multimodal_id": "model-00000004"
}'
```
**响应**:
```json
{
"success": true
}
```
## PUT `/initialization/config/:kb_id` - 更新知识库模型配置
**请求**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/initialization/config/kb-00000001' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"chat_model_id": "model-00000010",
"embedding_model_id": "model-00000002"
}'
```
**响应**:
```json
{
"success": true
}
```
## GET `/initialization/ollama/status` - 检查 Ollama 状态
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/initialization/ollama/status' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": {
"available": true
},
"success": true
}
```
## GET `/initialization/ollama/models` - 获取本地 Ollama 模型列表
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/initialization/ollama/models' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": [
{
"name": "llama3:8b",
"size": 4661211648,
"modified_at": "2025-08-10T15:30:00+08:00"
},
{
"name": "nomic-embed-text:latest",
"size": 274302976,
"modified_at": "2025-08-11T09:00:00+08:00"
}
],
"success": true
}
```
## POST `/initialization/ollama/models/check` - 检查 Ollama 模型是否可用
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/initialization/ollama/models/check' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"models": ["llama3:8b", "nomic-embed-text:latest", "mistral:7b"]
}'
```
**响应**:
```json
{
"data": {
"llama3:8b": true,
"nomic-embed-text:latest": true,
"mistral:7b": false
},
"success": true
}
```
## POST `/initialization/ollama/models/download` - 下载 Ollama 模型
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/initialization/ollama/models/download' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"model": "mistral:7b"
}'
```
**响应**:
```json
{
"data": {
"id": "task-00000001",
"modelName": "mistral:7b",
"status": "downloading",
"progress": 0,
"message": "开始下载",
"startTime": "2025-08-12T10:00:00+08:00"
},
"success": true
}
```
## GET `/initialization/ollama/download/progress/:task_id` - 获取下载进度
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/initialization/ollama/download/progress/task-00000001' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": {
"id": "task-00000001",
"modelName": "mistral:7b",
"status": "downloading",
"progress": 45.6,
"message": "正在下载 2.1GB / 4.6GB",
"startTime": "2025-08-12T10:00:00+08:00"
},
"success": true
}
```
## GET `/initialization/ollama/download/tasks` - 获取所有下载任务
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/initialization/ollama/download/tasks' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": [
{
"id": "task-00000001",
"modelName": "mistral:7b",
"status": "completed",
"progress": 100,
"message": "下载完成",
"startTime": "2025-08-12T10:00:00+08:00",
"endTime": "2025-08-12T10:15:00+08:00"
},
{
"id": "task-00000002",
"modelName": "llama3:70b",
"status": "downloading",
"progress": 30.2,
"message": "正在下载 12.5GB / 41.4GB",
"startTime": "2025-08-12T10:20:00+08:00"
}
],
"success": true
}
```
## POST `/initialization/remote/check` - 检查远程模型 API
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/initialization/remote/check' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"api_url": "https://api.openai.com/v1",
"api_key": "sk-xxxxx",
"model": "gpt-4o"
}'
```
**响应**:
```json
{
"data": {
"success": true,
"message": "模型可用"
},
"success": true
}
```
## POST `/initialization/embedding/test` - 测试嵌入模型
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/initialization/embedding/test' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"api_url": "https://api.openai.com/v1",
"api_key": "sk-xxxxx",
"model": "text-embedding-3-small"
}'
```
**响应**:
```json
{
"data": {
"success": true,
"message": "嵌入模型测试通过"
},
"success": true
}
```
## POST `/initialization/rerank/check` - 检查重排序模型
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/initialization/rerank/check' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"api_url": "https://api.cohere.ai/v1",
"api_key": "sk-xxxxx",
"model": "rerank-english-v3.0"
}'
```
**响应**:
```json
{
"data": {
"success": true,
"message": "重排序模型可用"
},
"success": true
}
```
## POST `/initialization/multimodal/test` - 测试多模态模型
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/initialization/multimodal/test' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"api_url": "https://api.openai.com/v1",
"api_key": "sk-xxxxx",
"model": "gpt-4o"
}'
```
**响应**:
```json
{
"data": {
"success": true,
"message": "多模态模型测试通过"
},
"success": true
}
```
## POST `/initialization/extract/text-relation` - 提取文本关系
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/initialization/extract/text-relation' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"text": "WeKnora 是一个知识管理平台,支持多种文档格式的解析和检索。",
"model_id": "model-00000001"
}'
```
**响应**:
```json
{
"data": {
"entities": [
{"name": "WeKnora", "type": "Product"},
{"name": "知识管理平台", "type": "Concept"}
],
"relations": [
{
"source": "WeKnora",
"target": "知识管理平台",
"relation": "is_a"
}
]
},
"success": true
}
```

View File

@ -1,722 +0,0 @@
# 知识库管理 API
[返回目录](./README.md)
**字段说明(知识库对象)**
- 知识库类型 `type` 为 `document`(文档)或 `faq`(FAQ),默认 `document`。
- JSON 中对象存储相关字段:**`storage_config`** 为序列化字段名(对应数据库列 `cos_config`,兼容旧数据)。旧客户端若仍发送或接收 `cos_config`,服务端会兼容解析;新集成请使用 **`storage_config`**。
- **`storage_provider_config`** 为新版存储提供者选择(如 `{"provider": "local"}`),与空间级存储引擎凭证配合使用;无配置时可为 `null`。
- 嵌套配置对象:`chunking_config`、`image_processing_config`、`vlm_config`、`asr_config`、`extract_config`、`faq_config`、`question_generation_config`、`auto_tag_config`。其中 `extract_config`、`faq_config`、`question_generation_config`、`auto_tag_config` 允许为 `null`。
- **`vector_store_id`** 为知识库绑定的向量存储 ID(参见 [vector-store.md](./vector-store.md))。未指定(或 `null`/`""`)时使用空间级默认的环境变量存储;一旦创建即不可修改。详情接口返回时会附带 `vector_store_name` / `vector_store_source` / `vector_store_engine_type` / `vector_store_status` 四个只读元数据字段,用于前端展示。
| 方法 | 路径 | 描述 |
| ------ | ----------------------------------------- | ------------------------ |
| POST | `/knowledge-bases` | 创建知识库 |
| GET | `/knowledge-bases` | 获取知识库列表 |
| GET | `/knowledge-bases/:id` | 获取知识库详情 |
| PUT | `/knowledge-bases/:id` | 更新知识库 |
| DELETE | `/knowledge-bases/:id` | 删除知识库 |
| PUT | `/knowledge-bases/:id/pin` | 置顶/取消置顶知识库 |
| POST | `/knowledge-bases/:id/hybrid-search` | 混合搜索(向量+关键词,推荐) |
| GET | `/knowledge-bases/:id/hybrid-search` | 混合搜索(兼容旧客户端,需 JSON 请求体) |
| POST | `/knowledge-bases/copy` | 拷贝知识库(异步任务) |
| GET | `/knowledge-bases/copy/progress/:task_id` | 获取拷贝进度 |
| POST | `/knowledge-bases/:id/duplicate` | 创建知识库副本(仅设置) |
| GET | `/knowledge-bases/:id/move-targets` | 获取可迁移目标知识库列表 |
## POST `/knowledge-bases` - 创建知识库
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| ----------------------------- | ------- | ---- | --------------------------------------------------------------- |
| name | string | 是 | 知识库名称 |
| description | string | 否 | 知识库描述 |
| type | string | 否 | 知识库类型:`document`(默认)或 `faq` |
| is_temporary | boolean | 否 | 是否为临时知识库(默认 `false`,临时库通常不在 UI 列表中显示) |
| chunking_config | object | 否 | 分块配置(见下方示例) |
| image_processing_config | object | 否 | 图片处理配置 |
| embedding_model_id | string | 否 | Embedding 模型 ID |
| summary_model_id | string | 否 | 摘要模型 ID |
| vlm_config | object | 否 | VLM(视觉模型)配置 |
| asr_config | object | 否 | ASR(语音识别)配置 |
| storage_provider_config | object | 否 | 存储提供者选择,如 `{"provider": "local"}` |
| storage_config | object | 否 | 旧版 COS 存储凭证(兼容字段,新集成留空即可) |
| extract_config | object | 否 | 图谱抽取配置;`enabled=true` 时需提供 `text`/`tags`/`nodes`/`relations` |
| faq_config | object | 否 | FAQ 配置(仅 FAQ 类型知识库需要) |
| question_generation_config | object | 否 | 问题生成配置 |
| auto_tag_config | object | 否 | 文档自动标签配置,默认关闭;仅适用于 `document` 类型知识库 |
| vector_store_id | string | 否 | 绑定的向量存储 ID。不传或为空字符串等同于 `null`(使用环境变量默认存储)。指定时必须是调用者所在空间拥有的向量存储 UUID;创建后不可修改。无效 UUID / 跨空间 / 未注册到引擎的 ID 会返回 `400` |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/knowledge-bases' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: sk-xxxxx' \
--data '{
"name": "weknora",
"description": "weknora description",
"type": "document",
"is_temporary": false,
"chunking_config": {
"chunk_size": 1000,
"chunk_overlap": 200,
"separators": [
"."
],
"enable_multimodal": true,
"parser_engine_rules": [
{
"file_types": [".pdf", ".docx"],
"engine": "builtin"
}
],
"enable_parent_child": false,
"parent_chunk_size": 4096,
"child_chunk_size": 384
},
"image_processing_config": {
"model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e"
},
"embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3",
"summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c",
"vlm_config": {
"enabled": true,
"model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e"
},
"asr_config": {
"enabled": false,
"model_id": "",
"language": ""
},
"storage_provider_config": {
"provider": "local"
},
"storage_config": {
"secret_id": "",
"secret_key": "",
"region": "",
"bucket_name": "",
"app_id": "",
"path_prefix": ""
},
"extract_config": null,
"faq_config": null,
"question_generation_config": {
"enabled": false,
"question_count": 3
},
"auto_tag_config": {
"enabled": true,
"model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c",
"max_tags": 3,
"skip_if_tagged": true
},
"vector_store_id": "550e8400-e29b-41d4-a716-446655440000"
}'
```
**响应**:
```json
{
"data": {
"id": "b5829e4a-3845-4624-a7fb-ea3b35e843b0",
"name": "weknora",
"description": "weknora description",
"type": "document",
"is_temporary": false,
"tenant_id": 1,
"chunking_config": {
"chunk_size": 1000,
"chunk_overlap": 200,
"separators": [
"."
],
"enable_multimodal": true,
"parser_engine_rules": [
{
"file_types": [".pdf", ".docx"],
"engine": "builtin"
}
],
"enable_parent_child": false,
"parent_chunk_size": 4096,
"child_chunk_size": 384
},
"image_processing_config": {
"model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e"
},
"embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3",
"summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c",
"vlm_config": {
"enabled": true,
"model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e"
},
"asr_config": {
"enabled": false,
"model_id": "",
"language": ""
},
"storage_provider_config": {
"provider": "local"
},
"storage_config": {
"secret_id": "",
"secret_key": "",
"region": "",
"bucket_name": "",
"app_id": "",
"path_prefix": ""
},
"extract_config": null,
"faq_config": null,
"question_generation_config": {
"enabled": false,
"question_count": 3
},
"auto_tag_config": {
"enabled": true,
"model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c",
"max_tags": 3,
"skip_if_tagged": true
},
"is_pinned": false,
"pinned_at": null,
"knowledge_count": 0,
"chunk_count": 0,
"processing_count": 0,
"vector_store_id": "550e8400-e29b-41d4-a716-446655440000",
"vector_store_name": "elasticsearch-hot",
"vector_store_source": "user",
"vector_store_engine_type": "elasticsearch",
"vector_store_status": "available",
"created_at": "2025-08-12T11:30:09.206238645+08:00",
"updated_at": "2025-08-12T11:30:09.206238854+08:00",
"deleted_at": null
},
"success": true
}
```
### 自动标签配置
`auto_tag_config` 在文档解析完成后异步调用聊天模型,从知识库已有标签中选择匹配项并增量关联到文档。该过程不会创建新标签,也不会删除或覆盖人工添加的标签。
| 字段 | 类型 | 默认值 | 说明 |
| ---------- | ------- | ------ | ---- |
| `enabled` | boolean | `false` | 是否启用自动标签 |
| `model_id` | string | `""` | 使用的聊天模型 ID;为空时使用知识库的 `summary_model_id` |
| `max_tags` | integer | `3` | 单个文档最多自动关联的标签数,取值范围为 `1` 到 `10` |
| `skip_if_tagged` | boolean | `true` | 文档已有标签时是否跳过自动标签。开启时不会调用模型,可避免稀释人工分类;设为 `false` 则在已有标签基础上追加 |
自动标签仅对启用该配置后新解析或重新解析的文档生效。模型调用失败不会阻塞文档解析完成,异步任务会按照任务队列策略重试。
候选标签按知识库排序取前 500 个参与分类;标签数超出时会记录告警并使用该前缀,不会跳过任务。模型按候选序号返回结果,服务端会校验序号范围并映射回标签 ID,越界或重复的序号将被丢弃。
**`vector_store_*` 响应字段说明**:
| 字段 | 类型 | 说明 |
| -------------------------- | ------ | ---------------------------------------------------------------------------------------------------------- |
| `vector_store_id` | string | 绑定的向量存储 ID(创建时未指定时为 `null`,从响应中省略) |
| `vector_store_name` | string | 绑定存储的展示名。未绑定时返回 `"System default"`;跨空间共享 KB 视图中被隐藏 |
| `vector_store_source` | string | `"user"`(DB 中创建的存储)/ `"env"`(环境变量虚拟存储)/ `"shared"`(跨空间共享 KB)/ `"unavailable"`(绑定的存储已不可解析) |
| `vector_store_engine_type` | string | 引擎类型(`elasticsearch` / `qdrant` / `milvus` 等)。`shared` / `unavailable` 时为空 |
| `vector_store_status` | string | `"available"` / `"unavailable"`。`unavailable` 表示绑定的存储已被删除或不在内存注册表中,UI 可据此提示用户重新绑定 |
**错误码(Phase 2 新增)**:
| HTTP | code | 说明 |
| ---- | ---- | ----------------------------------------------------------------- |
| 400 | 2200 | `vector_store_id` 无效:格式错误、不存在或属于其他空间(统一返回,避免枚举泄漏) |
| 400 | 2201 | 指定的向量存储当前不可用:存在于数据库但未注册到引擎注册表,请检查 connection_config |
## GET `/knowledge-bases` - 获取知识库列表
返回当前空间拥有的全部知识库。当传入 `agent_id` 时,校验调用者对该共享智能体的访问权限后,返回该智能体配置可见的知识库范围(用于 `@` 提及)。
**Query 参数**:
| 字段 | 类型 | 必填 | 说明 |
| -------- | ------ | ---- | ---------------------------------------------------------- |
| agent_id | string | 否 | 共享智能体 ID;传入时按智能体配置(`all` / `selected` / `none`)过滤可见知识库 |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/knowledge-bases' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**: `data` 为数组,每个元素的字段结构同 `POST /knowledge-bases` 响应,并额外携带 `knowledge_count` / `chunk_count` / `processing_count` / `share_count` / `is_pinned` / `pinned_at` 这些聚合与状态字段。
> **注意(Phase 2)**:列表接口不包含 `vector_store_name` / `vector_store_source` / `vector_store_engine_type` / `vector_store_status` 这四个解析后的元数据字段(避免 N+1 查询);仅 `vector_store_id` 来自数据库本身。需要展示存储名称时请单独调用详情接口或 `/vector-stores/:id`。
## GET `/knowledge-bases/:id` - 获取知识库详情
根据 ID 获取知识库详情。当通过共享智能体访问时,可传 `agent_id` 进行权限校验;此时返回对象会附加 `my_permission` 字段以指示当前用户对该知识库的角色(如 `viewer`)。
**路径参数**:
| 字段 | 类型 | 说明 |
| ---- | ------ | --------- |
| id | string | 知识库 ID |
**Query 参数**:
| 字段 | 类型 | 必填 | 说明 |
| -------- | ------ | ---- | ------------------------------------------ |
| agent_id | string | 否 | 共享智能体 ID(用于校验该智能体是否有权访问) |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**: 字段结构同 `POST /knowledge-bases` 响应(包含 Phase 2 的 `vector_store_*` 元数据字段),并附 `is_pinned` / `pinned_at` / `knowledge_count` / `chunk_count` / `processing_count` 状态字段。通过共享智能体访问时还会附加 `my_permission`;同时 `vector_store_name` / `vector_store_engine_type` 会被隐藏(`vector_store_source` 返回 `"shared"`),避免跨空间泄漏存储展示名。
## PUT `/knowledge-bases/:id` - 更新知识库
仅知识库 owner(admin)或具备 `editor` 权限的用户可调用。注意:**`vector_store_id` 在创建后不可修改**,更新接口不接收该字段。
**路径参数**:
| 字段 | 类型 | 说明 |
| ---- | ------ | --------- |
| id | string | 知识库 ID |
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| ----------- | ------ | ---- | ------------------------------------------------------------- |
| name | string | 是 | 知识库名称 |
| description | string | 否 | 知识库描述 |
| config | object | 否 | 更新配置;包含 `chunking_config` / `image_processing_config` / `faq_config` / `wiki_config` / `indexing_strategy` |
**请求**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/b5829e4a-3845-4624-a7fb-ea3b35e843b0' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: sk-xxxxx' \
--data '{
"name": "weknora new",
"description": "weknora description new",
"config": {
"chunking_config": {
"chunk_size": 1000,
"chunk_overlap": 200,
"separators": [
"\n\n",
"\n",
"。",
"!",
"?",
";",
";"
],
"enable_multimodal": true,
"parser_engine_rules": [
{
"file_types": [".md", ".txt"],
"engine": "builtin"
}
],
"enable_parent_child": true,
"parent_chunk_size": 4096,
"child_chunk_size": 384
},
"image_processing_config": {
"model_id": ""
}
}
}'
```
**响应**: 字段结构同 `POST /knowledge-bases` 响应(返回更新后的完整知识库对象,包含 Phase 2 的 `vector_store_*` 元数据字段。`vector_store_id` 与创建时保持一致,无法通过该接口更改)。
## DELETE `/knowledge-bases/:id` - 删除知识库
仅知识库 owner(与所属空间匹配的 admin)可调用,删除将级联清理知识库下所有知识与切片。
**路径参数**:
| 字段 | 类型 | 说明 |
| ---- | ------ | --------- |
| id | string | 知识库 ID |
**请求**:
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/knowledge-bases/b5829e4a-3845-4624-a7fb-ea3b35e843b0' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**:
```json
{
"message": "Knowledge base deleted successfully",
"success": true
}
```
## PUT `/knowledge-bases/:id/pin` - 置顶/取消置顶知识库
切换知识库的置顶状态。无需请求体,每次调用会自动反转当前 `is_pinned`。置顶时会同步写入 `pinned_at` 时间戳。
**路径参数**:
| 字段 | 类型 | 说明 |
| ---- | ------ | --------- |
| id | string | 知识库 ID |
**请求**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/pin' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**: 字段结构同 `POST /knowledge-bases` 响应(包含 Phase 2 的 `vector_store_*` 元数据字段),本接口操作后 `is_pinned` 翻转、`pinned_at` 同步更新。
## POST `/knowledge-bases/:id/hybrid-search` - 混合搜索
在指定知识库内执行向量召回 + 关键词召回的混合检索。请求参数通过 JSON 请求体传递(`SearchParams`)。
> **兼容说明**:`GET` 方法同样可用(需携带 JSON 请求体),供旧版客户端兼容;新集成请使用 `POST`。
**路径参数**:
| 字段 | 类型 | 说明 |
| ---- | ------ | --------- |
| id | string | 知识库 ID |
**查询参数**:
- `resource_urls`: `handle`(默认)或 `public`。`public` 把检索结果 `content` / `image_info` 里的 `resource://` 引用换成可加载的 http(s) 链接,详见[文件与图片引用](./README.md#文件与图片引用resource-与直链)
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| ------------------------ | -------- | ---- | ---------------------------------------------------------------- |
| query_text | string | 是 | 查询文本 |
| vector_threshold | number | 否 | 向量相似度阈值(0-1) |
| keyword_threshold | number | 否 | 关键词匹配阈值 |
| match_count | integer | 否 | 返回结果数量上限 |
| disable_keywords_match | boolean | 否 | 关闭关键词召回 |
| disable_vector_match | boolean | 否 | 关闭向量召回 |
| knowledge_ids | string[] | 否 | 仅在指定的知识 ID 范围内召回 |
| tag_ids | string[] | 否 | 标签过滤(FAQ 类型常用于优先级过滤) |
| only_recommended | boolean | 否 | 仅返回标记为推荐的内容 |
| knowledge_base_ids | string[] | 否 | 跨知识库召回(需共享相同 embedding 模型),优先级高于路径中的 `:id` |
| skip_context_enrichment | boolean | 否 | 跳过父子片段/相邻片段的上下文补全(chat 流程使用) |
**请求**:
```curl
curl --location --request POST 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/hybrid-search?resource_urls=public' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"query_text": "如何使用知识库",
"vector_threshold": 0.5,
"match_count": 10
}'
```
**响应**:
```json
{
"data": [
{
"id": "chunk-00000001",
"content": "知识库是用于存储和检索知识的系统...",
"knowledge_id": "knowledge-00000001",
"chunk_index": 0,
"knowledge_title": "知识库使用指南",
"start_at": 0,
"end_at": 500,
"seq": 1,
"score": 0.95,
"chunk_type": "text",
"image_info": "",
"metadata": {},
"knowledge_filename": "guide.pdf",
"knowledge_source": "file"
}
],
"success": true
}
```
## POST `/knowledge-bases/copy` - 拷贝知识库
异步拷贝整个知识库(配置 + 全部知识内容)。请求会被入队到 Asynq 后台任务(队列 `default`,最多重试 3 次),并立即返回 `task_id` 供轮询进度。
**约束**:源知识库 `source_id` 必须属于调用者所在空间;若指定 `target_id`,目标知识库同样必须属于调用者空间,否则返回 `403 Forbidden`。
**Phase 2 同步预检(当 `target_id` 非空时)**:
| 检查 | 失败时响应 |
| -------------- | ----------------------------------------------------------------------------- |
| 嵌入模型一致性 | `400` `source and target knowledge bases use different embedding models; clone into a target with the same embedding model` |
| 向量存储一致性 | `400` `source and target knowledge bases are bound to different vector stores; cross-store cloning is not yet supported` |
预检失败时任务不会入队、不会生成 `task_id`,调用方直接收到 `400`;这两个检查在异步 worker 中会再次执行(defense in depth),但在握手时即时拒绝是为了避免用户需要轮询 `progress` 才能看到错误。当 `target_id` 为空(新建目标库)时,目标库会自动复制源库的 `vector_store_id` 与 `embedding_model_id`,因此预检不会触发。
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| ---------- | ------ | ---- | ------------------------------------------------------------- |
| source_id | string | 是 | 源知识库 ID(必须属于当前空间) |
| target_id | string | 否 | 目标知识库 ID(若复用已存在知识库;同样必须属于当前空间) |
| task_id | string | 否 | 自定义任务 ID;不传则由服务端生成(基于空间、源 ID、时间戳) |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/knowledge-bases/copy' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"source_id": "kb-00000001"
}'
```
**响应**:
```json
{
"data": {
"task_id": "kb_clone_1_kb-00000001_1736582400",
"source_id": "kb-00000001",
"target_id": "",
"message": "Knowledge base copy task started"
},
"success": true
}
```
## GET `/knowledge-bases/copy/progress/:task_id` - 获取拷贝进度
查询拷贝任务的当前状态与进度(数据由 worker 写入 Redis)。
**路径参数**:
| 字段 | 类型 | 说明 |
| ------- | ------ | ------------------------------------------------- |
| task_id | string | 由 `POST /knowledge-bases/copy` 返回的任务 ID |
**响应字段(`data`)**:
| 字段 | 类型 | 说明 |
| ---------- | ------- | ------------------------------------------------------------ |
| task_id | string | 任务 ID |
| source_id | string | 源知识库 ID |
| target_id | string | 目标知识库 ID(任务开始后填入) |
| status | string | `pending` / `processing` / `completed` / `failed` |
| progress | integer | 进度百分比 0–100 |
| total | integer | 计划拷贝的知识总数 |
| processed | integer | 已处理的知识数 |
| message | string | 当前状态描述 |
| error | string | 失败时的错误信息 |
| created_at | integer | 任务创建时间(Unix 秒) |
| updated_at | integer | 最后更新时间(Unix 秒) |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/knowledge-bases/copy/progress/kb_clone_1_kb-00000001_1736582400' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": {
"task_id": "kb_clone_1_kb-00000001_1736582400",
"source_id": "kb-00000001",
"target_id": "kb-00000002",
"status": "completed",
"progress": 100,
"total": 10,
"processed": 10,
"message": "Task completed successfully",
"error": "",
"created_at": 1736582400,
"updated_at": 1736582460
},
"success": true
}
```
## POST `/knowledge-bases/:id/duplicate` - 创建知识库副本
同步创建一个**仅包含设置**的新知识库副本。会复制分块、模型、索引策略、Wiki/FAQ 配置等设置字段,但**不会**复制知识条目、分块内容、FAQ 条目、Wiki 页面、向量/关键词索引、数据源绑定、分享关系或置顶状态。
与 `POST /knowledge-bases/copy` 的区别:
| 能力 | `/duplicate` | `/copy` |
| ---- | ------------ | ------- |
| 执行方式 | 同步,立即返回新 KB | 异步任务,需轮询 progress |
| 复制内容 | 仅设置 | 设置 + 全部知识内容 |
| 新 KB ID | 服务端自动生成 UUID | 可指定已有目标库或新建 |
**权限**:需要 `Contributor+`,且对源知识库至少有 `Viewer` 读权限(路由层 `KBAccessRead`)。源知识库必须属于调用者所在空间,否则返回 `403 Forbidden`。
**命名规则**:新 KB 名称在源名称后追加本地化后缀(依据 `Accept-Language` 或 `WEKNORA_LANGUAGE`),例如中文 `原名 副本`、英文 `Original Name Copy`;若同名已存在则递增为 `原名 副本 2`、`Original Name Copy 2` 等。
**路径参数**:
| 字段 | 类型 | 说明 |
| ---- | ------ | ----------- |
| id | string | 源知识库 ID |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/duplicate' \
--header 'Authorization: Bearer <token>' \
--header 'Accept-Language: zh-CN' \
--request POST
```
**响应**(HTTP 201):
```json
{
"success": true,
"data": {
"source_id": "kb-00000001",
"target_id": "kb-00000002",
"message": "Knowledge base duplicate created",
"knowledge_base": {
"id": "kb-00000002",
"name": "产品文档 副本",
"type": "document",
"description": "…",
"embedding_model_id": "embed-1",
"chunking_config": {},
"knowledge_count": 0,
"chunk_count": 0
}
}
}
```
**响应字段(`data`)**:
| 字段 | 类型 | 说明 |
| --------------- | ------ | ---------------------------- |
| source_id | string | 源知识库 ID |
| target_id | string | 新创建的知识库 ID |
| message | string | 操作结果描述 |
| knowledge_base | object | 新副本的完整知识库对象 |
**常见错误**:
| 场景 | HTTP | 说明 |
| -------------------- | ---- | ---- |
| 源知识库不存在 | 404 | `Source knowledge base not found` |
| 源库属于其他空间 | 403 | `No permission to duplicate this knowledge base` |
| 向量存储绑定无效 | 400 | 源库绑定的 vector store 不可用 |
## GET `/knowledge-bases/:id/move-targets` - 获取可迁移目标知识库列表
返回当前知识库的内容**可以迁移到**的目标知识库列表。筛选规则:
- 与源知识库 `type` 相同
- 与源知识库 `embedding_model_id` 相同
- 非临时知识库(`is_temporary = false`)
- 不包含源知识库自身
- 仅同空间的知识库
**路径参数**:
| 字段 | 类型 | 说明 |
| ---- | ------ | ------------- |
| id | string | 源知识库 ID |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/move-targets' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": [
{
"id": "kb-00000002",
"name": "技术文档知识库",
"description": "技术文档相关知识",
"type": "document",
"is_temporary": false,
"tenant_id": 1,
"chunking_config": {
"chunk_size": 1000,
"chunk_overlap": 200,
"separators": ["\n\n", "\n"],
"enable_multimodal": true,
"parser_engine_rules": [],
"enable_parent_child": false,
"parent_chunk_size": 4096,
"child_chunk_size": 384
},
"image_processing_config": {
"model_id": ""
},
"embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3",
"summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c",
"vlm_config": {
"enabled": false,
"model_id": ""
},
"asr_config": {
"enabled": false,
"model_id": "",
"language": ""
},
"storage_provider_config": {
"provider": "local"
},
"storage_config": {
"secret_id": "",
"secret_key": "",
"region": "",
"bucket_name": "",
"app_id": "",
"path_prefix": ""
},
"extract_config": null,
"faq_config": null,
"question_generation_config": null,
"is_pinned": false,
"pinned_at": null,
"knowledge_count": 8,
"chunk_count": 210,
"processing_count": 0,
"created_at": "2025-08-12T11:30:09.206238+08:00",
"updated_at": "2025-08-12T11:30:09.206238+08:00",
"deleted_at": null
}
],
"success": true
}
```

View File

@ -1,101 +0,0 @@
# 知识搜索 API
[返回目录](./README.md)
| 方法 | 路径 | 描述 |
| ---- | ------------------ | -------- |
| POST | `/knowledge-search` | 知识搜索 |
## POST `/knowledge-search` - 知识搜索
在知识库中搜索相关内容(不使用 LLM 总结),直接返回检索结果。
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| ------------------- | -------- | ---- | ---------------------------------------------------------- |
| query | string | 是 | 搜索查询文本 |
| knowledge_base_id | string | 否 | 单个知识库 ID(向后兼容);与 `knowledge_base_ids` 互斥 |
| knowledge_base_ids | string[] | 否 | 多个知识库 ID 列表,跨知识库搜索 |
| knowledge_ids | string[] | 否 | 进一步限定到指定知识(文件);不传则在整库范围内搜索 |
> 必须指定 `knowledge_base_id` 或 `knowledge_base_ids` 中的至少一个。
**查询参数**:
- `resource_urls`: `handle`(默认)或 `public`。`public` 把检索结果 `content` / `image_info` 里的 `resource://` 引用换成可加载的 http(s) 链接,详见[文件与图片引用](./README.md#文件与图片引用resource-与直链)
**请求**:
```curl
# 搜索单个知识库
curl --location 'http://localhost:8080/api/v1/knowledge-search' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"query": "如何使用知识库",
"knowledge_base_id": "kb-00000001"
}'
# 搜索多个知识库
curl --location 'http://localhost:8080/api/v1/knowledge-search' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"query": "如何使用知识库",
"knowledge_base_ids": ["kb-00000001", "kb-00000002"]
}'
# 搜索指定文件
curl --location 'http://localhost:8080/api/v1/knowledge-search' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"query": "如何使用知识库",
"knowledge_ids": ["4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5"]
}'
```
**响应**:
```json
{
"data": [
{
"id": "chunk-00000001",
"content": "知识库是用于存储和检索知识的系统...",
"knowledge_id": "knowledge-00000001",
"chunk_index": 0,
"knowledge_title": "知识库使用指南",
"start_at": 0,
"end_at": 500,
"seq": 1,
"score": 0.95,
"chunk_type": "text",
"image_info": "",
"metadata": {},
"knowledge_filename": "guide.pdf",
"knowledge_source": "file"
}
],
"success": true
}
```
**响应字段说明(data[])**:
| 字段 | 类型 | 说明 |
| ------------------ | ------- | ------------------------------------- |
| id | string | 分块 ID |
| content | string | 命中的分块文本 |
| knowledge_id | string | 该分块所属的知识 ID |
| chunk_index | int | 分块在知识中的序号 |
| knowledge_title | string | 来源知识标题 |
| start_at / end_at | int | 分块在源文档中的字符偏移 |
| seq | int | 命中排序号 |
| score | number | 相似度(rerank 后归一化后的最终得分) |
| chunk_type | string | 分块类型(`text` / `image` / ...) |
| image_info | string | 图像分块的额外信息(JSON 字符串) |
| metadata | object | 自定义元数据 |
| knowledge_filename | string | 来源文件名 |
| knowledge_source | string | 来源类型(`file` / `url` / `manual`) |

File diff suppressed because it is too large Load Diff

View File

@ -1,623 +0,0 @@
# MCP Service API
[返回目录](./README.md)
MCP(Model Context Protocol)服务管理接口,提供 MCP 服务的 CRUD、连通性测试、工具/资源发现,以及工具人工审批策略配置。
| 方法 | 路径 | 描述 |
| ------ | ------------------------------------------------- | --------------------------------------------- |
| POST | `/mcp-services` | 创建 MCP 服务 |
| GET | `/mcp-services` | 获取当前空间的 MCP 服务列表 |
| GET | `/mcp-services/:id` | 获取 MCP 服务详情 |
| PUT | `/mcp-services/:id` | 更新 MCP 服务(部分字段更新) |
| DELETE | `/mcp-services/:id` | 删除 MCP 服务 |
| POST | `/mcp-services/:id/test` | 测试 MCP 服务连通性 |
| GET | `/mcp-services/:id/tools` | 获取 MCP 服务工具列表 |
| GET | `/mcp-services/:id/metadata` | 读取已保存的工具目录(不连接上游) |
| POST | `/mcp-services/:id/metadata/refresh` | 连接上游并同步完整工具目录 |
| GET | `/mcp-services/:id/resources` | 获取 MCP 服务资源列表 |
| GET | `/mcp-services/:id/tool-approvals` | 列出该服务下各工具的人工审批策略 |
| PUT | `/mcp-services/:id/tool-approvals/:tool_name` | 设置/更新某工具的人工审批策略 |
| POST | `/agent/tool-approvals/:pending_id` | 处理 Agent 工具调用待审批请求 |
## POST `/mcp-services` - 创建 MCP 服务
**请求参数**:
| 字段 | 类型 | 必填 | 说明 |
| ---------------- | ------- | ---- | --------------------------------------------------------------------------------------------- |
| name | string | 是 | 服务名称 |
| description | string | 否 | 服务描述 |
| transport_type | string | 是 | 传输类型,可选:`sse`、`http-streamable`、`stdio` |
| url | string | 条件 | 服务地址;当 `transport_type` 为 `sse` / `http-streamable` 时必填(受 SSRF 安全校验约束) |
| headers | object | 否 | 自定义请求头 |
| auth_config | object | 否 | 认证配置,支持 `api_key`、`token` |
| advanced_config | object | 否 | 高级配置,支持 `timeout`、`retry_count`、`retry_delay` |
| stdio_config | object | 条件 | stdio 传输配置,包含 `command`、`args`;当 `transport_type` 为 `stdio` 时必填 |
| env_vars | object | 否 | 环境变量(stdio 场景常用) |
| enabled | boolean | 否 | 是否启用 |
| usage_instructions | string | 否 | 给模型看的服务级使用说明;刷新工具目录时不会覆盖 |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/mcp-services' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"name": "天气查询服务",
"description": "提供全球天气信息查询",
"transport_type": "sse",
"url": "https://mcp.example.com/weather/sse",
"headers": {
"X-Custom-Header": "value"
},
"auth_config": {
"api_key": "weather-api-key-xxxxx"
},
"advanced_config": {
"timeout": 30,
"retry_count": 3,
"retry_delay": 1
}
}'
```
**响应**:
```json
{
"data": {
"id": "mcp-00000001",
"tenant_id": 1,
"name": "天气查询服务",
"description": "提供全球天气信息查询",
"enabled": true,
"transport_type": "sse",
"url": "https://mcp.example.com/weather/sse",
"headers": {
"X-Custom-Header": "value"
},
"auth_config": {
"api_key": "weather-api-key-xxxxx"
},
"advanced_config": {
"timeout": 30,
"retry_count": 3,
"retry_delay": 1
},
"is_builtin": false,
"created_at": "2025-08-12T10:00:00+08:00",
"updated_at": "2025-08-12T10:00:00+08:00"
},
"success": true
}
```
**创建 stdio 类型的 MCP 服务示例**:
```curl
curl --location 'http://localhost:8080/api/v1/mcp-services' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"name": "本地文件服务",
"description": "通过 stdio 访问本地文件系统",
"transport_type": "stdio",
"stdio_config": {
"command": "/usr/local/bin/mcp-file-server",
"args": ["--root", "/data"]
},
"env_vars": {
"MCP_LOG_LEVEL": "info"
}
}'
```
## GET `/mcp-services` - 获取 MCP 服务列表
返回当前空间已配置的所有 MCP 服务。每条记录可带 `catalog`:已保存工具目录的数量与是否过期;从未同步时该字段省略。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/mcp-services' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": [
{
"id": "mcp-00000001",
"tenant_id": 1,
"name": "天气查询服务",
"description": "提供全球天气信息查询",
"enabled": true,
"transport_type": "sse",
"url": "https://mcp.example.com/weather/sse",
"headers": {},
"auth_config": {
"api_key": "weather-api-key-xxxxx"
},
"advanced_config": {
"timeout": 30,
"retry_count": 3,
"retry_delay": 1
},
"is_builtin": false,
"catalog": {
"tool_count": 12,
"stale": false,
"synced_at": "2026-09-09T12:00:00+08:00"
},
"created_at": "2025-08-12T10:00:00+08:00",
"updated_at": "2025-08-12T10:00:00+08:00"
},
{
"id": "mcp-00000002",
"tenant_id": 1,
"name": "本地文件服务",
"description": "通过 stdio 访问本地文件系统",
"enabled": true,
"transport_type": "stdio",
"headers": {},
"auth_config": null,
"advanced_config": null,
"stdio_config": {
"command": "/usr/local/bin/mcp-file-server",
"args": ["--root", "/data"]
},
"env_vars": {
"MCP_LOG_LEVEL": "info"
},
"is_builtin": false,
"created_at": "2025-08-12T11:00:00+08:00",
"updated_at": "2025-08-12T11:00:00+08:00"
}
],
"success": true
}
```
## GET `/mcp-services/:id` - 获取 MCP 服务详情
**路径参数**:
| 字段 | 类型 | 说明 |
| ---- | ------ | -------------- |
| id | string | MCP 服务 ID |
> 注:内置(`is_builtin: true`)服务在响应中会隐藏敏感凭证字段。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/mcp-services/mcp-00000001' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": {
"id": "mcp-00000001",
"tenant_id": 1,
"name": "天气查询服务",
"description": "提供全球天气信息查询",
"enabled": true,
"transport_type": "sse",
"url": "https://mcp.example.com/weather/sse",
"headers": {},
"auth_config": {
"api_key": "weather-api-key-xxxxx"
},
"advanced_config": {
"timeout": 30,
"retry_count": 3,
"retry_delay": 1
},
"is_builtin": false,
"created_at": "2025-08-12T10:00:00+08:00",
"updated_at": "2025-08-12T10:00:00+08:00"
},
"success": true
}
```
## PUT `/mcp-services/:id` - 更新 MCP 服务
支持部分字段更新,可传入下列任意子集:`name`、`description`、`enabled`、`transport_type`、`url`、`stdio_config`、`env_vars`、`headers`、`auth_config`、`advanced_config`。其中 `url` 若提供,会再次执行 SSRF 安全校验。
**请求**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/mcp-services/mcp-00000001' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"name": "天气查询服务(更新)",
"description": "提供全球天气信息查询,支持实时数据",
"enabled": false
}'
```
**响应**:
```json
{
"data": {
"id": "mcp-00000001",
"tenant_id": 1,
"name": "天气查询服务(更新)",
"description": "提供全球天气信息查询,支持实时数据",
"enabled": false,
"transport_type": "sse",
"url": "https://mcp.example.com/weather/sse",
"headers": {},
"auth_config": {
"api_key": "weather-api-key-xxxxx"
},
"advanced_config": {
"timeout": 30,
"retry_count": 3,
"retry_delay": 1
},
"is_builtin": false,
"created_at": "2025-08-12T10:00:00+08:00",
"updated_at": "2025-08-12T12:00:00+08:00"
},
"success": true
}
```
## DELETE `/mcp-services/:id` - 删除 MCP 服务
**请求**:
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/mcp-services/mcp-00000001' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"success": true,
"message": "MCP service deleted successfully"
}
```
## POST `/mcp-services/:id/test` - 测试 MCP 服务连通性
后端会以已保存配置建立一次 MCP 连接,返回连接结果及探测到的工具/资源列表。连接失败时 HTTP 仍为 200,但 `data.success` 为 `false`,错误原因在 `data.message` 中。
**请求**:
```curl
curl --location --request POST 'http://localhost:8080/api/v1/mcp-services/mcp-00000001/test' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": {
"success": true,
"message": "连接成功",
"description": "提供全球天气信息查询",
"tools": [
{
"name": "get_weather",
"description": "获取指定城市的天气信息",
"inputSchema": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "城市名称"
}
},
"required": ["city"]
}
}
],
"resources": [
{
"uri": "weather://cities",
"name": "城市列表",
"description": "支持查询的城市列表",
"mimeType": "application/json"
}
]
},
"success": true
}
```
## GET `/mcp-services/:id/metadata` - 读取已保存的工具目录
只读数据库,不连接上游 MCP Server。未同步时 `data` 为 `null`。连接或认证配置变更后,旧快照仍返回,但 `stale` 为 `true`,运行时不会使用。OAuth 目录按当前授权主体隔离,不会回退到其他用户或租户共享快照。Viewer 及以上可调用。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/mcp-services/mcp-00000001/metadata' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**(已同步):
```json
{
"success": true,
"data": {
"service_id": "mcp-00000001",
"tools": [
{
"name": "get_weather",
"description": "获取指定城市的天气信息",
"inputSchema": {
"type": "object",
"properties": {
"city": {"type": "string"}
},
"required": ["city"]
}
}
],
"instructions": "Use IATA city codes.",
"server_name": "weather",
"server_version": "1.0",
"server_description": "Weather MCP",
"synced_at": "2026-09-09T02:00:00Z",
"stale": false
}
}
```
未同步时 `data` 为 `null`。常见错误:服务不存在 `404`;OAuth 目录缺少授权主体 `401`。
## POST `/mcp-services/:id/metadata/refresh` - 同步工具目录
显式连接上游并原子替换完整目录。静态认证写入租户共享快照,需要 Admin(或具备 MCP 管理能力的 API key);OAuth 服务写入当前用户的快照,Viewer 及以上可调用,以便对话内授权后的用户保存自己的目录。刷新失败保留原快照,响应不会带回上游 URL 等连接细节。
连接配置在刷新过程中被改写时返回 `409`。目录过大或不完整返回 `400`。静态认证且调用者不是管理员时返回 `403`。
**请求**:
```curl
curl --location --request POST 'http://localhost:8080/api/v1/mcp-services/mcp-00000001/metadata/refresh' \
--header 'X-API-Key: sk-xxxxx'
```
成功响应形状与 `GET /mcp-services/:id/metadata` 相同。
## GET `/mcp-services/:id/tools` - 获取 MCP 服务工具列表
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/mcp-services/mcp-00000001/tools' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": [
{
"name": "get_weather",
"description": "获取指定城市的天气信息",
"inputSchema": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "城市名称"
}
},
"required": ["city"]
}
},
{
"name": "get_forecast",
"description": "获取未来天气预报",
"inputSchema": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "城市名称"
},
"days": {
"type": "integer",
"description": "预报天数"
}
},
"required": ["city"]
}
}
],
"success": true
}
```
## GET `/mcp-services/:id/resources` - 获取 MCP 服务资源列表
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/mcp-services/mcp-00000001/resources' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": [
{
"uri": "weather://cities",
"name": "城市列表",
"description": "支持查询的城市列表",
"mimeType": "application/json"
},
{
"uri": "weather://config",
"name": "服务配置",
"description": "当前服务配置信息",
"mimeType": "application/json"
}
],
"success": true
}
```
## GET `/mcp-services/:id/tool-approvals` - 列出工具人工审批策略
返回该 MCP 服务下各工具持久化的 `require_approval` 标记。仅返回数据库中已显式配置过的工具记录;未出现在列表中的工具默认无需审批。
**路径参数**:
| 字段 | 类型 | 说明 |
| ---- | ------ | ----------- |
| id | string | MCP 服务 ID |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/mcp-services/mcp-00000001/tool-approvals' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**:
```json
{
"data": [
{
"tool_name": "delete_file",
"require_approval": true,
"updated_at": "2025-09-20T15:30:00+08:00"
},
{
"tool_name": "get_weather",
"require_approval": false,
"updated_at": "2025-09-20T15:31:00+08:00"
}
],
"success": true
}
```
## PUT `/mcp-services/:id/tool-approvals/:tool_name` - 设置工具人工审批策略
为指定 MCP 服务下的某个工具设置/更新人工审批要求。当 `require_approval` 为 `true` 时,Agent 在调用该工具前会阻塞并产生一条待审批记录,需要前端调用 `POST /agent/tool-approvals/:pending_id` 完成审批。
**路径参数**:
| 字段 | 类型 | 说明 |
| ---------- | ------ | ------------------------------------------------------------------- |
| id | string | MCP 服务 ID |
| tool_name | string | 工具名(由 Gin 自动 URL 解码,调用方需对名称中的 `%`、`/` 做 URL 编码) |
**请求体**:
| 字段 | 类型 | 必填 | 说明 |
| ----------------- | ------- | ---- | ----------------------------------- |
| require_approval | boolean | 是 | 是否要求人工审批后才能执行该工具 |
**请求**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/mcp-services/mcp-00000001/tool-approvals/delete_file' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"require_approval": true
}'
```
**响应**:
```json
{
"success": true
}
```
## POST `/agent/tool-approvals/:pending_id` - 处理待审批工具调用
用于 Agent 在执行过程中阻塞等待人工审批的场景:当 Agent 命中一个 `require_approval = true` 的工具时会生成一条 `pending_id`,前端拿到这个 ID 后调用此接口将审批结果回传给 Agent,Agent 才会继续执行(或终止)。
**鉴权要求**:请求上下文中必须有已认证用户(`user_id`),且该用户必须是当前 pending 会话的所有者;空间与用户两层都会做 fail-close 校验。
**路径参数**:
| 字段 | 类型 | 说明 |
| ----------- | ------ | ------------------- |
| pending_id | string | 待审批记录 ID |
**请求体**:
| 字段 | 类型 | 必填 | 说明 |
| -------------- | ------ | ---- | ----------------------------------------------------------------------------------------------------------------- |
| decision | string | 是 | 审批结论,必须为 `approve` 或 `reject` |
| modified_args | object | 否 | 仅在 `approve` 时生效,允许人工修改本次工具调用的参数;必须是非 null 的 JSON 对象,否则返回 400 |
| reason | string | 否 | 审批理由(任意,便于审计) |
**请求(通过)**:
```curl
curl --location --request POST 'http://localhost:8080/api/v1/agent/tool-approvals/pending-abcdef123456' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"decision": "approve",
"modified_args": {
"path": "/tmp/safe-target.txt"
},
"reason": "已确认目标路径安全"
}'
```
**请求(驳回)**:
```curl
curl --location --request POST 'http://localhost:8080/api/v1/agent/tool-approvals/pending-abcdef123456' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"decision": "reject",
"reason": "目标路径在受保护目录"
}'
```
**响应**:
```json
{
"success": true
}
```
**错误码说明**:
| HTTP | 触发条件 |
| ---- | --------------------------------------------------------------------------------------- |
| 400 | `decision` 不是 `approve`/`reject`;或 `modified_args` 是 `null`/非对象;或空间/用户错配 |
| 401 | 上下文缺失认证用户(中间件未注入 `user_id`) |
| 404 | `pending_id` 不存在或已完成(超时/取消已先一步消费) |

View File

@ -1,104 +0,0 @@
# 长期记忆 API
[返回目录](./README.md)
长期记忆空间始终绑定在**当前调用者**上:路径里没有 subject id,服务端从凭证推导身份。因此 Viewer+ 的会话令牌,或 **full-access API Key** 才能访问;带知识库范围的集成 Key 不能继承某个人的记忆。
工作空间管理员先在设置里打开空间级开关,用户还可以再关掉自己的记忆。推断出的条目会停在 `pending`,确认后才进入提示词。
| 方法 | 路径 | 描述 |
| ---- | ---- | ---- |
| GET | `/memory/settings` | 获取合并后的记忆开关(空间级 + 个人级)与条数 |
| PUT | `/memory/settings` | 开启或关闭当前用户自己的长期记忆 |
| GET | `/memory/items` | 分页列出记忆,可按状态过滤 |
| POST | `/memory/items` | 手动新增一条记忆 |
| PUT | `/memory/items/{id}` | 修改内容与重要度(之后不会被后台抽取覆盖) |
| DELETE | `/memory/items/{id}` | 永久删除一条记忆 |
| POST | `/memory/items/{id}/confirm` | 确认一条推断出的记忆 |
| POST | `/memory/items/{id}/reject` | 否决一条推断出的记忆 |
| DELETE | `/memory/items` | 清空当前用户的全部记忆 |
| GET | `/memory/topics` | 列出尚未提升为长期关注的主题计数 |
| POST | `/memory/topics/{id}/promote` | 立即把主题记为长期关注 |
| DELETE | `/memory/topics/{id}` | 停止跟踪一个主题 |
| GET | `/memory/documents` | 列出反复引用的文档(未达习惯门槛的不展示) |
| DELETE | `/memory/documents/{id}` | 停止用某份文档做个性化检索 |
| GET | `/memory/export` | 以 JSON 导出全部记忆 |
| POST | `/memory/consolidate` | 立刻整理(合并近义条目、归档到期事项) |
## GET `/memory/settings`
```curl
curl --location 'http://localhost:8080/api/v1/memory/settings' \
--header 'Authorization: Bearer <token>'
```
**响应**:
```json
{
"success": true,
"data": {
"workspace_enabled": true,
"user_enabled": true,
"effective": true,
"write_mode": "auto",
"item_count": 12,
"max_items": 200
}
}
```
`write_mode` 为 `explicit_only`(只记用户明确要求记住的)或 `auto`(后台从对话蒸馏)。`effective` = 空间开关 ∧ 个人开关。
## PUT `/memory/settings`
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/memory/settings' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{"enabled": true}'
```
`enabled` 必填。只改个人开关,不能用这个接口改空间级配置。
## GET `/memory/items`
查询参数:
| 参数 | 说明 |
| ---- | ---- |
| `status` | 可选:`active` / `superseded` / `archived` / `pending`;省略则不过滤 |
| `limit` | 默认 50,最大 200 |
| `offset` | 默认 0 |
`kind` 取值:`profile` / `preference` / `fact` / `task` / `interest`。
## POST `/memory/items`
```json
{
"kind": "preference",
"content": "回答直接给结论,少铺垫",
"importance": 3
}
```
## POST `/memory/items/{id}/confirm` / `reject`
推断出的记忆(`status=pending`)确认后才注入提示词;否决会留下 tombstone,避免下一轮蒸馏把同一句话再写回来。
如果推断用于修改已有记忆,确认前旧记忆继续生效;确认会在同一事务中激活推断并替换旧条目。已经失效、到期或基于已修改或已删除内容的推断不能再次确认,接口返回 HTTP 409,客户端应刷新列表。编辑正文会同时使旧向量失效,并尝试生成新向量;生成失败时保留词面检索,后续整理可补齐向量。
自动提取在独立的 `memory_extraction_sessions` 表按会话保存 `(created_at, message_id)` 游标、排队状态和重试计数,每次最多领取 32 个会话。用户记录只保存工作进程租约,读取记忆时不加载全部会话历史。已完成的游标仍保留,避免旧会话再次提取全部历史。
单条无效决策或已失效的更新目标不会阻塞同批其他结果。无法解析或持续截断的模型输出按消息段最多尝试三轮(每轮截断后可增加预算重试一次),随后记录失败范围并推进该段游标;同会话后续消息及其他会话继续处理。进度表保留该会话最近一次失败的起止游标、错误类别、次数和跳过时间,不保存原始模型输出;被跳过的范围不会自动补提取。网络、模型配置和数据库错误不适用跳过策略,仍保留进度供重试。批次截断、工作进程重启和提取期间的新消息都保留待处理状态。
升级时沿用旧的用户级游标作为各会话的初始边界,之后该边界不再推进;旧待处理列表在首次调度时导入独立表。这样避免升级触发全量历史重放,但不会自动恢复旧实现已跳过、且位于旧游标之前的消息。
## GET `/memory/export`
返回 `{success, total, truncated, data}`,并带 `Content-Disposition: attachment; filename="weknora-memories.json"`。`truncated` 仅在触达导出上限(2 万条)时为 true。
## POST `/memory/consolidate`
不等待每日后台整理,立刻合并意思接近的条目并归档到期事项。返回 `merged` / `demoted` / `expired` / `reviewed` / `candidates`;若什么都没合并,`skipped` 会说明原因(例如 `too_few_items`)。

View File

@ -1,267 +0,0 @@
# 消息管理 API
[返回目录](./README.md)
| 方法 | 路径 | 描述 |
| ------ | ---------------------------- | ------------------------ |
| GET | `/messages/:session_id/load` | 获取最近的会话消息列表 |
| DELETE | `/messages/:session_id/:id` | 删除消息 |
| POST | `/messages/search` | 搜索历史对话 |
| GET | `/messages/chat-history-stats` | 获取聊天历史知识库统计 |
## GET `/messages/:session_id/load` - 获取最近的会话消息列表
**查询参数**:
- `before_time`: 上一次拉取的最早一条消息的 created_at 字段,为空拉取最近的消息
- `limit`: 每页条数(默认 20)
- `resource_urls`: `handle`(默认)或 `public`。`public` 把历史消息里的 `resource://` 图片引用换成可加载的 http(s) 链接,详见[文件与图片引用](./README.md#文件与图片引用resource-与直链)
**请求**:
```curl
curl --location --request GET 'http://localhost:8080/api/v1/messages/ceb9babb-1e30-41d7-817d-fd584954304b/load?limit=3&before_time=2030-08-12T14%3A35%3A42.123456789Z' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"query": "彗尾的形状"
}'
```
**响应**:
```json
{
"data": [
{
"id": "b8b90eeb-7dd5-4cf9-81c6-5ebcbd759451",
"session_id": "ceb9babb-1e30-41d7-817d-fd584954304b",
"request_id": "hCA8SDjxcAvv",
"content": "<think>\n好的",
"role": "assistant",
"knowledge_references": [
{
"id": "c8347bef-127f-4a22-b962-edf5a75386ec",
"content": "彗星xxx",
"knowledge_id": "a6790b93-4700-4676-bd48-0d4804e1456b",
"chunk_index": 0,
"knowledge_title": "彗星.txt",
"start_at": 0,
"end_at": 2760,
"seq": 0,
"score": 4.038836479187012,
"match_type": 4,
"sub_chunk_id": [
"688821f0-40bf-428e-8cb6-541531ebeb76",
"c1e9903e-2b4d-4281-be15-0149288d45c2",
"7d955251-3f79-4fd5-a6aa-02f81e044091"
],
"metadata": {},
"chunk_type": "text",
"parent_chunk_id": "",
"image_info": "",
"knowledge_filename": "彗星.txt",
"knowledge_source": ""
},
{
"id": "fa3aadee-cadb-4a84-9941-c839edc3e626",
"content": "# 文档名称\n彗星.txt\n\n# 摘要\n彗星是由冰和尘埃构成的太阳系小天体,接近太阳时会释放气体形成彗发和彗尾。其轨道周期差异大,来源包括柯伊伯带和奥尔特云。彗星与小行星的区别逐渐模糊,部分彗星已失去挥发物质,类似小行星。目前已知彗星数量众多,且存在系外彗星。彗星在古代被视为凶兆,现代研究揭示其复杂结构与起源。",
"knowledge_id": "a6790b93-4700-4676-bd48-0d4804e1456b",
"chunk_index": 6,
"knowledge_title": "彗星.txt",
"start_at": 0,
"end_at": 0,
"seq": 6,
"score": 0.6131043121858466,
"match_type": 0,
"sub_chunk_id": null,
"metadata": {},
"chunk_type": "summary",
"parent_chunk_id": "c8347bef-127f-4a22-b962-edf5a75386ec",
"image_info": "",
"knowledge_filename": "彗星.txt",
"knowledge_source": ""
}
],
"agent_steps": [],
"is_completed": true,
"is_fallback": false,
"agent_duration_ms": 2500,
"channel": "web",
"created_at": "2025-08-12T10:24:38.370548+08:00",
"updated_at": "2025-08-12T10:25:40.416382+08:00",
"deleted_at": null
},
{
"id": "7fa136ae-a045-424e-baac-52113d92ae94",
"session_id": "ceb9babb-1e30-41d7-817d-fd584954304b",
"request_id": "3475c004-0ada-4306-9d30-d7f5efce50d2",
"content": "彗尾的形状",
"role": "user",
"knowledge_references": [],
"agent_steps": [],
"is_completed": true,
"mentioned_items": [],
"images": [],
"channel": "web",
"created_at": "2025-08-12T14:30:39.732246+08:00",
"updated_at": "2025-08-12T14:30:39.733277+08:00",
"deleted_at": null
},
{
"id": "9bcafbcf-a758-40af-a9a3-c4d8e0f49439",
"session_id": "ceb9babb-1e30-41d7-817d-fd584954304b",
"request_id": "3475c004-0ada-4306-9d30-d7f5efce50d2",
"content": "<think>\n好的",
"role": "assistant",
"knowledge_references": [
{
"id": "c8347bef-127f-4a22-b962-edf5a75386ec",
"content": "彗星xxx",
"knowledge_id": "a6790b93-4700-4676-bd48-0d4804e1456b",
"chunk_index": 0,
"knowledge_title": "彗星.txt",
"start_at": 0,
"end_at": 2760,
"seq": 0,
"score": 4.038836479187012,
"match_type": 3,
"sub_chunk_id": [
"688821f0-40bf-428e-8cb6-541531ebeb76",
"c1e9903e-2b4d-4281-be15-0149288d45c2",
"7d955251-3f79-4fd5-a6aa-02f81e044091"
],
"metadata": {},
"chunk_type": "text",
"parent_chunk_id": "",
"image_info": "",
"knowledge_filename": "彗星.txt",
"knowledge_source": ""
},
{
"id": "fa3aadee-cadb-4a84-9941-c839edc3e626",
"content": "# 文档名称\n彗星.txt\n\n# 摘要\n彗星是由冰和尘埃构成的太阳系小天体,接近太阳时会释放气体形成彗发和彗尾。其轨道周期差异大,来源包括柯伊伯带和奥尔特云。彗星与小行星的区别逐渐模糊,部分彗星已失去挥发物质,类似小行星。目前已知彗星数量众多,且存在系外彗星。彗星在古代被视为凶兆,现代研究揭示其复杂结构与起源。",
"knowledge_id": "a6790b93-4700-4676-bd48-0d4804e1456b",
"chunk_index": 6,
"knowledge_title": "彗星.txt",
"start_at": 0,
"end_at": 0,
"seq": 6,
"score": 0.6131043121858466,
"match_type": 3,
"sub_chunk_id": null,
"metadata": {},
"chunk_type": "summary",
"parent_chunk_id": "c8347bef-127f-4a22-b962-edf5a75386ec",
"image_info": "",
"knowledge_filename": "彗星.txt",
"knowledge_source": ""
}
],
"agent_steps": [],
"is_completed": true,
"is_fallback": false,
"agent_duration_ms": 2500,
"channel": "web",
"created_at": "2025-08-12T14:30:39.735108+08:00",
"updated_at": "2025-08-12T14:31:17.829926+08:00",
"deleted_at": null
}
],
"success": true
}
```
## DELETE `/messages/:session_id/:id` - 删除消息
**请求**:
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/messages/ceb9babb-1e30-41d7-817d-fd584954304b/9bcafbcf-a758-40af-a9a3-c4d8e0f49439' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"message": "Message deleted successfully",
"success": true
}
```
## POST `/messages/search` - 搜索历史对话
搜索历史对话消息,支持混合搜索、关键词搜索和向量搜索模式。
**请求参数**:
- `query`: 搜索关键词(必填)
- `mode`: 搜索模式,可选 `hybrid`、`keyword`、`vector`(可选,默认 `hybrid`)
- `limit`: 返回结果数量(可选,默认 20)
- `session_ids`: 限定搜索的会话ID列表(可选)
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/messages/search' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"query": "彗星的结构",
"mode": "hybrid",
"limit": 20,
"session_ids": []
}'
```
**响应**:
```json
{
"data": {
"items": [
{
"request_id": "3475c004-0ada-4306-9d30-d7f5efce50d2",
"session_id": "ceb9babb-1e30-41d7-817d-fd584954304b",
"session_title": "彗星知识问答",
"query_content": "彗尾的形状",
"answer_content": "彗尾的形状主要取决于...",
"score": 0.85,
"match_type": "hybrid",
"created_at": "2025-08-12T14:30:39.732246+08:00"
}
],
"total": 1
},
"success": true
}
```
## GET `/messages/chat-history-stats` - 获取聊天历史知识库统计
获取当前空间的聊天历史知识库索引统计信息。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/messages/chat-history-stats' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": {
"enabled": true,
"embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3",
"knowledge_base_id": "kb-chat-00000001",
"knowledge_base_name": "聊天历史知识库",
"indexed_message_count": 1024,
"has_indexed_messages": true
},
"success": true
}
```

View File

@ -1,503 +0,0 @@
# 模型管理 API
[返回目录](./README.md)
模型管理接口用于维护当前空间下可用的 LLM / Embedding / Rerank / VLLM / ASR 模型配置。
| 方法 | 路径 | 描述 |
| ------ | ------------------- | --------------------- |
| GET | `/models/providers` | 获取模型服务商列表 |
| POST | `/models` | 创建模型 |
| GET | `/models` | 获取模型列表 |
| GET | `/models/:id` | 获取模型详情 |
| PUT | `/models/:id` | 更新模型 |
| DELETE | `/models/:id` | 删除模型 |
## 服务商支持 (Provider Support)
WeKnora 支持多种主流 AI 模型服务商,在创建模型时可通过 `parameters.provider` 字段指定服务商类型以获得更好的兼容性。
### 支持的服务商列表
| 服务商标识 | 名称 | 支持的模型类型 |
| -------------- | ---------------------------- | ------------------------------- |
| `generic` | 自定义 (OpenAI 兼容接口) | Chat, Embedding, Rerank, VLLM |
| `openai` | OpenAI | Chat, Embedding, Rerank, VLLM |
| `aliyun` | 阿里云 DashScope | Chat, Embedding, Rerank, VLLM |
| `zhipu` | 智谱 BigModel | Chat, Embedding, Rerank, VLLM |
| `volcengine` | 火山引擎 Volcengine | Chat, Embedding, Rerank, VLLM |
| `hunyuan` | 腾讯混元 Hunyuan | Chat, Embedding |
| `deepseek` | DeepSeek | Chat |
| `minimax` | MiniMax | Chat |
| `mimo` | 小米 MiMo | Chat |
| `siliconflow` | 硅基流动 SiliconFlow | Chat, Embedding, Rerank, VLLM |
| `jina` | Jina | Embedding, Rerank |
| `openrouter` | OpenRouter | Chat, VLLM |
| `litellm` | LiteLLM (self-hosted proxy) | Chat, Embedding, VLLM |
| `requesty` | Requesty | Chat, Embedding, VLLM |
| `gemini` | Google Gemini | Chat |
| `modelscope` | 魔搭 ModelScope | Chat, Embedding, VLLM |
| `moonshot` | 月之暗面 Moonshot | Chat, VLLM |
| `qianfan` | 百度千帆 Baidu Cloud | Chat, Embedding, Rerank, VLLM |
| `qiniu` | 七牛云 Qiniu | Chat |
| `longcat` | LongCat AI | Chat |
| `gpustack` | GPUStack | Chat, Embedding, Rerank, VLLM |
> 实际可用的服务商以 `GET /models/providers` 返回为准。
>
> `litellm` 的目录默认地址是占位符 `http://your_litellm_proxy/v1`,保存前请换成实际可解析的主机名。`localhost` / `127.0.0.1` / `host.docker.internal` 默认会被 SSRF 拦截;自托管时把该主机加入 `SSRF_WHITELIST`。创建模型时 `source` 仍为 `remote`,厂商写在 `parameters.provider`。
## GET `/models/providers` - 获取模型服务商列表
根据模型类型获取支持的服务商列表及配置信息(系统级元数据,与空间无关)。
**查询参数**:
| 字段 | 类型 | 必填 | 说明 |
| ---------- | ------ | ---- | --------------------------------------------------- |
| model_type | string | 否 | 模型类型,可选值:`chat` / `embedding` / `rerank` / `vllm` / `asr`;省略则返回全部 |
**请求**:
```curl
# 获取所有服务商
curl --location 'http://localhost:8080/api/v1/models/providers' \
--header 'X-API-Key: your_api_key'
# 获取支持 Embedding 类型的服务商
curl --location 'http://localhost:8080/api/v1/models/providers?model_type=embedding' \
--header 'X-API-Key: your_api_key'
```
**响应**:
```json
{
"success": true,
"data": [
{
"value": "aliyun",
"label": "阿里云 DashScope",
"description": "qwen-plus, tongyi-embedding-vision-plus, qwen3-rerank, etc.",
"defaultUrls": {
"chat": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"embedding": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"rerank": "https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank"
},
"modelTypes": ["chat", "embedding", "rerank", "vllm"]
},
{
"value": "zhipu",
"label": "智谱 BigModel",
"description": "glm-4.7, embedding-3, rerank, etc.",
"defaultUrls": {
"chat": "https://open.bigmodel.cn/api/paas/v4",
"embedding": "https://open.bigmodel.cn/api/paas/v4/embeddings",
"rerank": "https://open.bigmodel.cn/api/paas/v4/rerank"
},
"modelTypes": ["chat", "embedding", "rerank", "vllm"]
}
]
}
```
## POST `/models` - 创建模型
为当前空间创建一个新的模型配置。
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| ----------- | ------ | ---- | --------------------------------------------------------------- |
| name | string | 是 | 模型名称(远程模型对应服务商的 model id,本地模型为 Ollama tag)|
| type | string | 是 | 模型类型,可选值:`KnowledgeQA` / `Embedding` / `Rerank` / `VLLM` / `ASR` |
| source | string | 是 | 模型来源,可选值:`local` / `remote` |
| description | string | 否 | 模型描述 |
| parameters | object | 是 | 模型参数,详见下方 [Parameters](#parameters-模型参数) |
> 当 `parameters.base_url` 不为空时,后端会执行 SSRF 校验,校验失败将返回 400。
### 创建对话模型(KnowledgeQA)
**本地 Ollama 模型**:
```curl
curl --location 'http://localhost:8080/api/v1/models' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: your_api_key' \
--data '{
"name": "qwen3:8b",
"type": "KnowledgeQA",
"source": "local",
"description": "LLM Model for Knowledge QA",
"parameters": {
"base_url": "",
"api_key": ""
}
}'
```
**远程 API 模型(指定服务商)**:
```curl
curl --location 'http://localhost:8080/api/v1/models' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: your_api_key' \
--data '{
"name": "qwen-plus",
"type": "KnowledgeQA",
"source": "remote",
"description": "阿里云 Qwen 大模型",
"parameters": {
"base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"api_key": "sk-your-dashscope-api-key",
"provider": "aliyun"
}
}'
```
### 创建嵌入模型(Embedding)
**本地 Ollama 模型**:
```curl
curl --location 'http://localhost:8080/api/v1/models' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: your_api_key' \
--data '{
"name": "nomic-embed-text:latest",
"type": "Embedding",
"source": "local",
"description": "Embedding Model",
"parameters": {
"base_url": "",
"api_key": "",
"embedding_parameters": {
"dimension": 768,
"truncate_prompt_tokens": 0
}
}
}'
```
**远程 API 模型(阿里云 DashScope)**:
```curl
curl --location 'http://localhost:8080/api/v1/models' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: your_api_key' \
--data '{
"name": "text-embedding-v3",
"type": "Embedding",
"source": "remote",
"description": "阿里云通义千问 Embedding 模型",
"parameters": {
"base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"api_key": "sk-your-dashscope-api-key",
"provider": "aliyun",
"embedding_parameters": {
"dimension": 1024,
"truncate_prompt_tokens": 0
}
}
}'
```
**远程 API 模型(Jina AI)**:
```curl
curl --location 'http://localhost:8080/api/v1/models' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: your_api_key' \
--data '{
"name": "jina-embeddings-v3",
"type": "Embedding",
"source": "remote",
"description": "Jina AI Embedding 模型",
"parameters": {
"base_url": "https://api.jina.ai/v1",
"api_key": "jina_your_api_key",
"provider": "jina",
"embedding_parameters": {
"dimension": 1024,
"truncate_prompt_tokens": 0
}
}
}'
```
### 创建排序模型(Rerank)
**远程 API 模型(阿里云 DashScope)**:
```curl
curl --location 'http://localhost:8080/api/v1/models' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: your_api_key' \
--data '{
"name": "gte-rerank",
"type": "Rerank",
"source": "remote",
"description": "阿里云 GTE Rerank 模型",
"parameters": {
"base_url": "https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank",
"api_key": "sk-your-dashscope-api-key",
"provider": "aliyun"
}
}'
```
**远程 API 模型(Jina AI)**:
```curl
curl --location 'http://localhost:8080/api/v1/models' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: your_api_key' \
--data '{
"name": "jina-reranker-v2-base-multilingual",
"type": "Rerank",
"source": "remote",
"description": "Jina AI Rerank 模型",
"parameters": {
"base_url": "https://api.jina.ai/v1",
"api_key": "jina_your_api_key",
"provider": "jina"
}
}'
```
**远程 API 模型(火山引擎 VikingDB)**:
火山 Rerank 使用 AK/SK 签名,不使用方舟 API Key。`api_key` 保存 Access Key ID,
`app_secret` 保存 Secret Access Key;两项均按模型凭证加密存储。
```curl
curl --location 'http://localhost:8080/api/v1/models' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: your_api_key' \
--data '{
"name": "doubao-seed-rerank",
"type": "Rerank",
"source": "remote",
"description": "火山引擎托管 Rerank 模型",
"parameters": {
"base_url": "https://api-knowledgebase.mlp.cn-beijing.volces.com",
"api_key": "your-volcengine-access-key-id",
"app_secret": "your-volcengine-secret-access-key",
"provider": "volcengine"
}
}'
```
### 创建视觉模型(VLLM)
```curl
curl --location 'http://localhost:8080/api/v1/models' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: your_api_key' \
--data '{
"name": "qwen-vl-plus",
"type": "VLLM",
"source": "remote",
"description": "阿里云通义千问视觉模型",
"parameters": {
"base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"api_key": "sk-your-dashscope-api-key",
"provider": "aliyun"
}
}'
```
**响应**:
```json
{
"success": true,
"data": {
"id": "09c5a1d6-ee8b-4657-9a17-d3dcbd5c70cb",
"tenant_id": 1,
"name": "text-embedding-v3",
"type": "Embedding",
"source": "remote",
"description": "阿里云通义千问 Embedding 模型",
"parameters": {
"base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"api_key": "sk-***",
"provider": "aliyun",
"embedding_parameters": {
"dimension": 1024,
"truncate_prompt_tokens": 0
}
},
"is_default": false,
"status": "active",
"created_at": "2025-08-12T10:39:01.454591766+08:00",
"updated_at": "2025-08-12T10:39:01.454591766+08:00",
"deleted_at": null
}
}
```
## GET `/models` - 获取模型列表
返回当前空间下的所有模型。内置模型(`is_builtin = true`)的 `base_url` 与 `api_key` 会被清空以隐藏敏感信息。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/models' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: your_api_key'
```
**响应**: `data` 为数组,每个元素的字段结构同 `POST /models` 响应。内置模型的 `base_url` 与 `api_key` 字段为空字符串。
## GET `/models/:id` - 获取模型详情
**路径参数**:
| 字段 | 类型 | 必填 | 说明 |
| ---- | ------ | ---- | -------- |
| id | string | 是 | 模型 ID |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/models/dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: your_api_key'
```
**响应**: 字段结构同 `POST /models` 响应。404 表示模型不存在。
## PUT `/models/:id` - 更新模型
**路径参数**:
| 字段 | 类型 | 必填 | 说明 |
| ---- | ------ | ---- | -------- |
| id | string | 是 | 模型 ID |
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| ----------- | ------ | ---- | --------------------------------------------------------------- |
| name | string | 否 | 模型名称(为空字符串时保留原值) |
| description | string | 否 | 模型描述(始终覆盖,传空字符串会清空) |
| type | string | 否 | 模型类型,取值同创建接口 |
| source | string | 否 | 模型来源,取值同创建接口 |
| parameters | object | 否 | 模型参数;`parameter_size` 由后端管理,请求中无需提供;`extra_config` 为空时会沿用旧值 |
> 同样会对 `parameters.base_url` 做 SSRF 校验,失败时返回 400。
**请求**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/models/8fdc464d-8eaa-44d4-a85b-094b28af5330' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: your_api_key' \
--data '{
"name": "gte-rerank-v2",
"type": "Rerank",
"source": "remote",
"description": "阿里云 GTE Rerank 模型 V2",
"parameters": {
"base_url": "https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank",
"api_key": "sk-your-new-api-key",
"provider": "aliyun"
}
}'
```
**响应**: 字段结构同 `POST /models` 响应,返回更新后的完整模型对象。
## DELETE `/models/:id` - 删除模型
**路径参数**:
| 字段 | 类型 | 必填 | 说明 |
| ---- | ------ | ---- | -------- |
| id | string | 是 | 模型 ID |
**请求**:
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/models/8fdc464d-8eaa-44d4-a85b-094b28af5330' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: your_api_key'
```
**响应**:
```json
{
"success": true,
"message": "Model deleted"
}
```
如果知识库、智能体或当前空间的长期记忆仍引用该模型,接口保持 HTTP 400,并返回专用错误码 `2300` 和结构化引用详情。例如:
```json
{
"success": false,
"error": {
"code": 2300,
"message": "model is used by 2 knowledge base(s); reconfigure or remove those references before deleting",
"details": {
"knowledge_bases": [
{"id": "kb-1", "name": "Product docs", "bindings": ["vlm_model"]},
{"id": "kb-2", "name": "Engineering", "bindings": ["vlm_model"]}
],
"agents": [],
"long_term_memory": {"bindings": []},
"knowledge_base_total": 2,
"agent_total": 0
}
}
}
```
`bindings` 是稳定的配置类型标识:知识库可能返回 `embedding_model`、`summary_model`、`image_processing_model`、`vlm_model`、`asr_model`、`wiki_synthesis_model`、`auto_tag_model`;智能体可能返回 `chat_model`、`rerank_model`、`vlm_model`、`asr_model`、`query_understand_model`、`follow_up_model`;长期记忆可能返回 `embedding_model`、`extract_model`。同一对象的多处引用会合并到一个 `bindings` 数组。`knowledge_bases` / `agents` 最多各返回 50 条;未截断的引用数在 `knowledge_base_total` / `agent_total`。404 表示模型不存在。
## 参数说明
### ModelType (模型类型)
| 值 | 前端别名 | 说明 | 用途 |
| ----------- | ----------- | ------------ | ------------------------------ |
| KnowledgeQA | `chat` | 对话模型 | 知识库问答、对话生成 |
| Embedding | `embedding` | 嵌入模型 | 文本向量化、知识库检索 |
| Rerank | `rerank` | 排序模型 | 检索结果重排序、相关性优化 |
| VLLM | `vllm` | 视觉语言模型 | 多模态分析、图文理解 |
| ASR | `asr` | 语音识别模型 | 音频转写 |
> 创建/更新接口请求体的 `type` 字段使用第一列的后端枚举值(如 `KnowledgeQA`);`GET /models/providers?model_type=` 查询参数使用第二列的前端别名(如 `chat`)。
### ModelSource (模型来源)
| 值 | 说明 | 配置要求 |
| -------- | ---------- | -------------------------------- |
| local | 本地模型 | 需要已安装 Ollama 并拉取模型 |
| remote | 远程 API | 需要提供 `base_url` 和 `api_key` |
### Parameters (模型参数)
| 字段 | 类型 | 必填 | 说明 |
| -------------------- | ----------------- | ---- | ---------------------------------------------------------- |
| base_url | string | 否 | API 服务地址;远程模型必填,会经过 SSRF 校验 |
| api_key | string | 否 | API 密钥;远程模型必填,存储时使用 AES-256 加密 |
| provider | string | 否 | 服务商标识(见上方支持列表),用于选择特定的 API 适配器 |
| interface_type | string | 否 | 接口风格标识(OpenAI 兼容请留空) |
| embedding_parameters | object | 否 | Embedding 模型专用参数,见下方 |
| parameter_size | string | 否 | 模型参数规模(如 `7B`/`13B`/`70B`),通常由后端写入 |
| extra_config | object<string,string> | 否 | 服务商特定的额外配置 |
| custom_headers | object<string,string> | 否 | 调用上游 API 时附加的自定义 HTTP 头;保留头会被忽略 |
| supports_vision | bool | 否 | 模型是否支持图像/多模态输入 |
### EmbeddingParameters (嵌入参数)
| 字段 | 类型 | 必填 | 说明 |
| ---------------------- | ---- | ---- | ------------------------------- |
| dimension | int | 否 | 向量维度(如 768、1024) |
| truncate_prompt_tokens | int | 否 | 截断 Token 数(0 表示不截断) |

File diff suppressed because it is too large Load Diff

View File

@ -1,522 +0,0 @@
# 会话管理 API
[返回目录](./README.md)
会话(Session)是纯粹的对话容器,仅存储基础信息(标题、描述、置顶状态等)。所有与知识库、模型、检索策略相关的配置均在查询时由 Custom Agent 提供,不再存储在会话中。
| 方法 | 路径 | 描述 |
| ------ | ------------------------------------------ | ----------------------------- |
| POST | `/sessions` | 创建会话 |
| DELETE | `/sessions/batch` | 批量删除会话 |
| GET | `/sessions/:id` | 获取会话详情 |
| GET | `/sessions` | 获取当前空间的会话列表 |
| PUT | `/sessions/:id` | 更新会话 |
| DELETE | `/sessions/:id` | 删除会话 |
| DELETE | `/sessions/:id/messages` | 清空会话消息 |
| POST | `/sessions/:session_id/generate_title` | 生成会话标题 |
| POST | `/sessions/:session_id/stop` | 停止生成 |
| POST | `/sessions/:session_id/pin` | 置顶会话 |
| DELETE | `/sessions/:id/pin` | 取消置顶会话 |
| GET | `/sessions/continue-stream/:session_id` | 继续未完成的流式响应 |
| POST | `/sessions/:session_id/sandbox/desktop-ticket` | 签发一次性桌面 WebSocket 票据 |
| POST | `/sessions/:session_id/sandbox/desktop/activity` | 上报桌面键鼠活动(parser 降级时续 TTL) |
| GET | `/sessions/:id/sandbox/desktop` | 沙箱桌面 RFB WebSocket 中继(query `ticket`) |
> **路由命名说明**:置顶接口的 POST 与 DELETE 使用了不同的路径参数名(POST 用 `:session_id`,DELETE 用 `:id`)。这是由于 gin 路由器为每个 HTTP 方法维护独立的 radix tree,且既有树中的通配符命名不同,必须保留以避免注册时的 `wildcard conflicts` panic。两者语义上都指会话 ID。
## POST `/sessions` - 创建会话
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/sessions' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"title": "我的新对话",
"description": "关于 AI 的讨论"
}'
```
**请求参数**:
| 字段 | 类型 | 必填 | 描述 |
| ------------- | ------ | ---- | -------- |
| `title` | string | 否 | 会话标题 |
| `description` | string | 否 | 会话描述 |
**响应**:
```json
{
"success": true,
"data": {
"id": "411d6b70-9a85-4d03-bb74-aab0fd8bd12f",
"title": "我的新对话",
"description": "关于 AI 的讨论",
"tenant_id": 1,
"user_id": "u-001",
"is_pinned": false,
"created_at": "2026-03-27T12:26:19.611616+08:00",
"updated_at": "2026-03-27T12:26:19.611616+08:00",
"deleted_at": null
}
}
```
> 通过 API-Key 调用时 `user_id` 可能为空,此时会话以空间级可见。
## DELETE `/sessions/batch` - 批量删除会话
支持两种模式:按 ID 列表批量删除,或删除当前空间的所有会话。
**请求 - 按 ID 列表删除**:
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/sessions/batch' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"ids": [
"411d6b70-9a85-4d03-bb74-aab0fd8bd12f",
"ceb9babb-1e30-41d7-817d-fd584954304b"
]
}'
```
**请求 - 删除所有会话**:
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/sessions/batch' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"delete_all": true
}'
```
**请求参数**:
| 字段 | 类型 | 必填 | 描述 |
| ------------ | -------- | ---- | ---------------------------------------------------------- |
| `ids` | string[] | 否 | 要删除的会话 ID 列表(`delete_all` 为 `false` 时必填) |
| `delete_all` | bool | 否 | 设为 `true` 时删除当前空间的所有会话,忽略 `ids` 字段 |
**响应**:
```json
{
"success": true,
"message": "Sessions deleted successfully"
}
```
`delete_all=true` 时 `message` 为 `"All sessions deleted successfully"`。
## GET `/sessions/:id` - 获取会话详情
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/sessions/ceb9babb-1e30-41d7-817d-fd584954304b' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**路径参数**:
| 字段 | 类型 | 必填 | 描述 |
| ---- | ------ | ---- | ------- |
| `id` | string | 是 | 会话 ID |
**响应**:
```json
{
"success": true,
"data": {
"id": "ceb9babb-1e30-41d7-817d-fd584954304b",
"title": "模型优化策略",
"description": "",
"tenant_id": 1,
"user_id": "u-001",
"is_pinned": true,
"pinned_at": "2026-04-01T09:12:33.123456+08:00",
"created_at": "2026-03-27T10:24:38.308596+08:00",
"updated_at": "2026-03-27T10:25:41.317761+08:00",
"deleted_at": null
}
}
```
会话不存在时返回 `404`。
## GET `/sessions` - 获取当前空间的会话列表
获取当前空间的会话列表,支持分页、关键字搜索、按来源 / Agent 过滤。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/sessions?page=1&page_size=10&keyword=AI&source=web' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**查询参数**:
| 字段 | 类型 | 必填 | 描述 |
| ----------- | ------ | ---- | ----------------------------------------------------------------- |
| `page` | int | 否 | 页码(默认 1) |
| `page_size` | int | 否 | 每页数量(默认 10) |
| `keyword` | string | 否 | 按标题模糊匹配(ILIKE `%keyword%`) |
| `source` | string | 否 | 来源过滤:`web`(无 IM 映射)或 IM 平台名,如 `feishu`、`wechat`、`slack` |
| `agent_id` | string | 否 | 按 Agent 过滤(仅对 IM 会话生效) |
**响应**:
```json
{
"success": true,
"data": [
{
"id": "411d6b70-9a85-4d03-bb74-aab0fd8bd12f",
"title": "我的新对话",
"description": "",
"tenant_id": 1,
"user_id": "u-001",
"is_pinned": true,
"pinned_at": "2026-04-01T09:12:33.123456+08:00",
"created_at": "2026-03-27T12:26:19.611616+08:00",
"updated_at": "2026-03-27T12:26:19.611616+08:00",
"deleted_at": null,
"im_platform": "feishu",
"im_chat_id": "oc_xxx",
"im_agent_id": "agent-001"
}
],
"total": 1,
"page": 1,
"page_size": 10
}
```
> 列表项始终包含置顶状态字段,IM 来源相关字段(`im_platform`、`im_chat_id`、`im_thread_id`、`im_user_id`、`im_agent_id`、`im_channel_id`)仅对 IM 创建的会话填充,Web 会话省略。
## PUT `/sessions/:id` - 更新会话
**请求**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/sessions/411d6b70-9a85-4d03-bb74-aab0fd8bd12f' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"title": "WeKnora 技术讨论",
"description": "关于 WeKnora 架构的讨论"
}'
```
**路径参数**:
| 字段 | 类型 | 必填 | 描述 |
| ---- | ------ | ---- | ------- |
| `id` | string | 是 | 会话 ID |
**请求参数**:
| 字段 | 类型 | 必填 | 描述 |
| ------------- | ------ | ---- | -------- |
| `title` | string | 否 | 会话标题 |
| `description` | string | 否 | 会话描述 |
**响应**:
```json
{
"success": true,
"data": {
"id": "411d6b70-9a85-4d03-bb74-aab0fd8bd12f",
"title": "WeKnora 技术讨论",
"description": "关于 WeKnora 架构的讨论",
"tenant_id": 1,
"user_id": "u-001",
"is_pinned": false,
"created_at": "2026-03-27T12:26:19.611616+08:00",
"updated_at": "2026-03-27T14:20:56.738424+08:00",
"deleted_at": null
}
}
```
会话不存在时返回 `404`。
## DELETE `/sessions/:id` - 删除会话
**请求**:
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/sessions/411d6b70-9a85-4d03-bb74-aab0fd8bd12f' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**路径参数**:
| 字段 | 类型 | 必填 | 描述 |
| ---- | ------ | ---- | ------- |
| `id` | string | 是 | 会话 ID |
**响应**:
```json
{
"success": true,
"message": "Session deleted successfully"
}
```
## DELETE `/sessions/:id/messages` - 清空会话消息
删除会话中的所有消息,同时清除 LLM 上下文和聊天历史知识库条目。会话本身保留。
**请求**:
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/sessions/ceb9babb-1e30-41d7-817d-fd584954304b/messages' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**路径参数**:
| 字段 | 类型 | 必填 | 描述 |
| ---- | ------ | ---- | ------- |
| `id` | string | 是 | 会话 ID |
**响应**:
```json
{
"success": true,
"message": "Session messages cleared successfully"
}
```
## POST `/sessions/:session_id/generate_title` - 生成会话标题
根据消息内容自动生成会话标题。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/sessions/ceb9babb-1e30-41d7-817d-fd584954304b/generate_title' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"messages": [
{
"role": "user",
"content": "你好,我想了解关于人工智能的知识"
},
{
"role": "assistant",
"content": "人工智能是计算机科学的一个分支..."
}
]
}'
```
**路径参数**:
| 字段 | 类型 | 必填 | 描述 |
| ------------ | ------ | ---- | ------- |
| `session_id` | string | 是 | 会话 ID |
**请求参数**:
| 字段 | 类型 | 必填 | 描述 |
| ---------- | --------- | ---- | ---------------------------- |
| `messages` | Message[] | 是 | 用作标题生成上下文的消息列表 |
**响应**:
```json
{
"success": true,
"data": "人工智能基础知识"
}
```
## POST `/sessions/:session_id/stop` - 停止生成
停止当前正在进行的助手回复生成任务。后端会向流中追加一条 `stop` 事件,由活跃的 SSE 处理协程感知并发起取消。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/sessions/7c966c74-610e-4516-8d5b-05e14b2e4ee0/stop' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"message_id": "ebbf7e53-dfe6-44d5-882f-36a4104910b5"
}'
```
**路径参数**:
| 字段 | 类型 | 必填 | 描述 |
| ------------ | ------ | ---- | ------- |
| `session_id` | string | 是 | 会话 ID |
**请求参数**:
| 字段 | 类型 | 必填 | 描述 |
| ------------ | ------ | ---- | ----------------------- |
| `message_id` | string | 是 | 要停止生成的助手消息 ID |
**响应**:
```json
{
"success": true,
"message": "Generation stopped"
}
```
若消息已完成(无需停止):
```json
{
"success": true,
"message": "Message already completed"
}
```
> 消息不属于当前会话返回 `403`;消息或会话不存在返回 `404`。
## POST `/sessions/:session_id/pin` - 置顶会话
将指定会话置顶(用户维度)。
**请求**:
```curl
curl --location --request POST 'http://localhost:8080/api/v1/sessions/ceb9babb-1e30-41d7-817d-fd584954304b/pin' \
--header 'X-API-Key: sk-xxxxx'
```
**路径参数**:
| 字段 | 类型 | 必填 | 描述 |
| ------------ | ------ | ---- | ------- |
| `session_id` | string | 是 | 会话 ID |
**响应**:
```json
{
"success": true,
"is_pinned": true
}
```
会话不存在或对当前用户不可见时返回 `404`。
## DELETE `/sessions/:id/pin` - 取消置顶会话
取消指定会话的置顶。
**请求**:
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/sessions/ceb9babb-1e30-41d7-817d-fd584954304b/pin' \
--header 'X-API-Key: sk-xxxxx'
```
**路径参数**:
| 字段 | 类型 | 必填 | 描述 |
| ---- | ------ | ---- | ------- |
| `id` | string | 是 | 会话 ID |
**响应**:
```json
{
"success": true,
"is_pinned": false
}
```
> 同上,`POST /pin` 与 `DELETE /pin` 路径参数名不同,但语义上都是会话 ID。
## GET `/sessions/continue-stream/:session_id` - 继续未完成的流式响应
用于在 SSE 连接断开后重新连接正在进行的流式响应:先回放该消息已产生的所有事件,再继续推送后续事件,直至 `complete`。
**路径参数**:
| 字段 | 类型 | 必填 | 描述 |
| ------------ | ------ | ---- | ------- |
| `session_id` | string | 是 | 会话 ID |
**查询参数**:
| 字段 | 类型 | 必填 | 描述 |
| ------------ | ------ | ---- | ------------------------------------------------------------------------------- |
| `message_id` | string | 是 | 从 `/messages/:session_id/load` 接口中获取的 `is_completed` 为 `false` 的消息 ID |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/sessions/continue-stream/ceb9babb-1e30-41d7-817d-fd584954304b?message_id=b8b90eeb-7dd5-4cf9-81c6-5ebcbd759451' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应格式**:
服务器端事件流(Server-Sent Events),事件结构与 `/knowledge-chat/:session_id`、`/agent-chat/:session_id` 返回结果一致。若该消息当前在流中已无事件返回 `404 No stream events found`;若消息记录不存在返回 `404 Incomplete message not found`。
## POST `/sessions/:session_id/sandbox/desktop-ticket` - 签发桌面票据
为沙箱图形桌面 WebSocket 签发一次性握手票据。访问 JWT 只出现在这次已认证 POST 上,不会进入 WS URL。票据 TTL 为 2 分钟,消费时 `GETDEL`,用过、过期、未知均返回同一类未授权错误。
这些端点与终端 WebSocket 一样**未进入 Swagger**。行为说明见 [沙箱图形桌面](../sandbox-desktop.md)。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/sessions/ceb9babb-1e30-41d7-817d-fd584954304b/sandbox/desktop-ticket' \
--header 'Authorization: Bearer <access_token>'
```
**响应**:
```json
{
"success": true,
"data": {
"ticket": "hex-encoded-32-byte-id",
"expires_in": 120
}
}
```
## GET `/sessions/:id/sandbox/desktop` - 桌面 RFB WebSocket
浏览器 noVNC 将上一步的 `ticket` 放在 query 上升级为 WebSocket。该路由注册在全局 JWT 中间件之前,只认一次性票据。每个会话同一时刻只允许一条中继。
沙箱未绑定、已暂停、镜像不支持桌面、启动失败等状态会先 upgrade 再以 close reason 断开(`SANDBOX_NOT_BOUND` / `SANDBOX_PAUSED` / `DESKTOP_UNSUPPORTED` / `DESKTOP_START_FAILED` 等),因为 JS WebSocket API 拿不到失败握手的 HTTP 状态。
**请求**:
```
GET /api/v1/sessions/ceb9babb-1e30-41d7-817d-fd584954304b/sandbox/desktop?ticket=<ticket>
Upgrade: websocket
```
## POST `/sessions/:session_id/sandbox/desktop/activity` - 上报桌面活动
浏览器在键鼠事件时 POST。这是 RFB parser 遇到未知 opcode 时的降级续命;parser 健康时服务端忽略该请求,避免仅靠轮询延长沙箱 TTL。

View File

@ -1,305 +0,0 @@
# Skills API
[返回目录](./README.md)
| 方法 | 路径 | 描述 |
| ---- | --------- | ------------------ |
| GET | `/skills` | 获取预装 Skills 列表 |
| POST | `/sandbox-configs/{id}/skills` | 安装技能(zip 上传或托管平台 source) |
| POST | `/sandbox-configs/{id}/skills/{skillId}/reinstall` | 用已保存的安装包重试安装 |
| POST | `/sandbox-configs/{id}/skills/{skillId}/stop` | 停止卡住的安装 |
| GET | `/sandbox-configs/{id}/skills/{skillId}/files` | 列出已安装技能的文件 |
| GET | `/sandbox-configs/{id}/skills/{skillId}/files/content` | 读取已安装技能中的单个文件 |
| PATCH | `/sandbox-configs/{id}/skills/{skillId}` | 启用/停用技能,或设置空间级环境变量 |
| GET | `/me/env-vars` | 列出自己的环境变量与各技能的声明 |
| PUT | `/me/env-vars/skill` | 设置自己在某个技能上的变量值 |
| DELETE | `/me/env-vars/skill` | 删除自己在某个技能上的变量值 |
| PUT | `/me/env-vars/sandbox` | 设置自己在某个沙箱配置上的变量值 |
| DELETE | `/me/env-vars/sandbox` | 删除自己在某个沙箱配置上的变量值 |
## GET `/skills` - 获取预装 Skills 列表
获取系统中所有预装的智能体技能列表。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/skills' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": [
{
"name": "web_search",
"description": "搜索互联网获取最新信息"
},
{
"name": "code_interpreter",
"description": "执行代码并返回结果"
},
{
"name": "image_generation",
"description": "根据文本描述生成图片"
}
],
"skills_available": true,
"success": true
}
```
当系统未配置 Skills 时,`skills_available` 返回 `false`,`data` 为空数组:
```json
{
"data": [],
"skills_available": false,
"success": true
}
```
## POST `/sandbox-configs/{id}/skills` - 安装技能
把技能安装到指定沙箱配置的镜像上。安装会启动沙箱并运行数分钟,本接口只负责受理,随后通过
`GET /sandbox-configs/{id}/skills/{skillId}/install-events` 跟随进度。
两种请求体二选一:
### 1. 上传 zip(multipart)
```curl
curl --location 'http://localhost:8080/api/v1/sandbox-configs/{id}/skills' \
--header 'X-API-Key: sk-xxxxx' \
--form 'file=@"skill.zip"'
```
### 2. 从托管平台安装(JSON)
`source` 只接受一种明确写法,不会根据下载结果猜测:
| 输入 | 含义 |
| --- | --- |
| `@owner/slug`、`@owner/slug@1.2.0` | ClawHub(默认 registry) |
| `my-skill`、`my-skill@1.2.0`(不含 `/`) | ClawHub slug |
| `https://clawhub.ai/skills-sh/owner/repo/slug`、`skills-sh:owner/repo/slug` | ClawHub 上的 skills.sh 联邦条目(经 ClawHub install API 解析到钉死的 GitHub commit;仓库内路径可能比 URL slug 更深) |
| `https://clawhub.ai/...`、`https://skillhub.cn/...`、自托管 SkillHub 页面 | 对应 registry |
| `https://github.com/...`、`https://gitlab.com/...`、`https://skills.sh/...` | Git 托管;`skills.sh` 的 `owner/repo/slug` 页面同样走 ClawHub resolver |
| `https://…/foo.zip` 或 `…/SKILL.md` | 直接下载 |
`owner/slug`(无 `@`、无 URL)会 400:它既是 ClawHub id 也是 GitHub 仓库,请改成 `@owner/slug` 或粘贴完整链接。
来源必须可匿名读取:服务端不会为这次下载附带任何凭据,因此私有仓库/私有 registry 需要先自行导出 zip 再上传。
```curl
curl --location 'http://localhost:8080/api/v1/sandbox-configs/{id}/skills' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{"source":"@owner/slug"}'
```
**响应**(202):
```json
{
"success": true,
"data": {
"skill_id": "..."
}
}
```
## POST `/sandbox-configs/{id}/skills/{skillId}/reinstall` - 重试安装
用服务端已保存的安装包重新跑一遍安装,无需重新上传 zip 或重新提供 source。适用于安装失败的原因与安装包本身无关的情况:沙箱不可达、依赖源超时、安装过程被中断等。
与安装接口一样只负责受理,进度同样通过
`GET /sandbox-configs/{id}/skills/{skillId}/install-events` 跟随。技能会复用同一个 `skill_id`,不会产生新记录。
已经在当前镜像中正常服务、且安装包未变的技能会被跳过,不会重复构建快照。若该技能的安装包已不在存储中,返回 400,此时只能重新上传。
```curl
curl --location --request POST \
'http://localhost:8080/api/v1/sandbox-configs/{id}/skills/{skillId}/reinstall' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**(202):
```json
{
"success": true,
"data": {
"skill_id": "..."
}
}
```
## POST `/sandbox-configs/{id}/skills/{skillId}/stop` - 停止安装
中止进行中的安装,之后可以重试或卸载。服务重启后安装行可能一直停在 `installing` 且没有存活进程,本接口会立刻改写该行,不必等 stuck-run reaper。卸载不受影响。
状态变为 `failed`,错误为「安装已停止」。
```curl
curl --location --request POST \
'http://localhost:8080/api/v1/sandbox-configs/{id}/skills/{skillId}/stop' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**(200):
```json
{
"success": true,
"data": {
"id": "...",
"status": "failed",
"error": "安装已停止"
}
}
```
若技能不是 `installing`(且不是已经 `failed`),返回 400。已经 `failed` 的停止是幂等成功。
## GET `/sandbox-configs/{id}/skills/{skillId}/files` - 列出技能文件
返回该技能存档里的文件路径与大小。路径相对技能根目录(`SKILL.md` 所在目录),不启动沙箱。
```curl
curl --location 'http://localhost:8080/api/v1/sandbox-configs/{id}/skills/{skillId}/files' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**:
```json
{
"success": true,
"data": [
{ "path": "SKILL.md", "size": 412 },
{ "path": "scripts/extract.py", "size": 1280 }
]
}
```
## GET `/sandbox-configs/{id}/skills/{skillId}/files/content` - 读取技能文件
`path` 为技能根目录相对路径。文本以 UTF-8 返回;较小的图片为 base64;其它二进制文件不返回正文,并设置 `binary: true`。
```curl
curl --location 'http://localhost:8080/api/v1/sandbox-configs/{id}/skills/{skillId}/files/content?path=SKILL.md' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**:
```json
{
"success": true,
"data": {
"path": "SKILL.md",
"size": 412,
"encoding": "utf-8",
"media_type": "text/markdown",
"content": "---\nname: pdf-tools\n..."
}
}
```
## 技能的环境变量
技能安装时会声明自己需要哪些环境变量(名称、说明、是否必填)。变量的**值**分两层,执行时按「本人的值 → 空间级值」的顺序取,取不到必填项则拒绝执行:
| 层级 | 谁能写 | 作用范围 | 接口 |
| --- | --- | --- | --- |
| 空间级 | Admin+ | 该空间所有人 | `PATCH /sandbox-configs/{id}/skills/{skillId}` |
| 个人级 | 任何登录成员 | 仅本人 | `PUT /me/env-vars/skill` |
任何接口都**不会**回读已保存的值,只返回 `unset` / `workspace` / `user` 三种状态。清空一个值用 DELETE,而不是写入空字符串——「没填」和「不需要」是两种状态。
个人级的值按**调用身份**存放,而不是按用户 ID。用 API Key 驱动的调用与网页登录是不同身份:在网页 Settings 里填的值不会作用于 API Key 发起的执行,反之亦然。集成方若通过 API Key 运行需要凭据的技能,请让管理员配置空间级值。
### PATCH `/sandbox-configs/{id}/skills/{skillId}` - 更新技能
`enabled` 与 `envs` 都是可选的,可只送其一,但不能都不送(400)。`envs` 只写技能已声明的名称,未声明的名称会被忽略而不是报错;值为空字符串表示清空该值并保留声明。
```curl
curl --location --request PATCH \
'http://localhost:8080/api/v1/sandbox-configs/{id}/skills/{skillId}' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{"enabled":true,"envs":{"TAVILY_API_KEY":"tvly-xxxxx"}}'
```
### GET `/me/env-vars` - 列出自己的环境变量
按沙箱配置分组,返回本人的配置级变量,以及该配置下每个已启用技能声明的变量。`source` 表示这次执行实际会用哪一层的值。
```curl
curl --location 'http://localhost:8080/api/v1/me/env-vars' \
--header 'Authorization: Bearer <token>'
```
**响应**:
```json
{
"success": true,
"data": [
{
"sandbox_config_id": "cfg-1",
"sandbox_config_name": "默认沙箱",
"description": "日常对话用的沙箱",
"vars": [
{ "name": "HTTP_PROXY", "source": "user", "updated_at": "2026-08-27T10:00:00Z" }
],
"skills": [
{
"skill_id": "sk-1",
"skill_name": "web-search",
"description": "通过 Tavily 检索网页",
"vars": [
{ "name": "TAVILY_API_KEY", "description": "Tavily 搜索密钥", "required": true, "source": "workspace" },
{ "name": "REGION", "source": "unset" }
]
}
]
}
]
}
```
### PUT / DELETE `/me/env-vars/skill` - 设置或删除自己在技能上的值
`name` 必须是该技能声明过的名称,否则 400。删除后该技能重新回落到空间级值(若有)。
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/me/env-vars/skill' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{"skill_id":"sk-1","name":"TAVILY_API_KEY","value":"tvly-xxxxx"}'
```
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/me/env-vars/skill' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{"skill_id":"sk-1","name":"TAVILY_API_KEY"}'
```
删除一个本就没设过的值返回 404。
### PUT / DELETE `/me/env-vars/sandbox` - 设置或删除自己的配置级变量
配置级变量不依附于任何技能,名称自定,会注入本人在该沙箱配置上的每一次技能脚本与 shell 命令。`WEKNORA_` 前缀与 `PATH` 等保留名会被拒绝。
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/me/env-vars/sandbox' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{"sandbox_config_id":"cfg-1","name":"HTTP_PROXY","value":"http://127.0.0.1:7890"}'
```

View File

@ -1,341 +0,0 @@
# Storage Backend API
[返回目录](./README.md)
存储后端(StorageBackend)API 用于管理空间的对象/文件存储实例。一个空间可以注册多个存储实例(`local`、`minio`、`cos`、`tos`、`s3`、`oss`、`ks3`、`obs`),并将不同知识库绑定到不同实例;空间维度还有一个默认实例(`default_storage_backend_id`),未显式绑定的新知识库使用该默认实例。
接口同时管理用户创建的实例(`source: "user"`)以及从环境变量快照生成的只读实例(`source: "env"`)。存储后端 CRUD 需要 **Admin+** 角色;对 API Key 需具备 `manage_storage_backends` capability(或 full-access)。
| 方法 | 路径 | 描述 | 最低权限 |
| ------ | --------------------------------- | -------------------------------------- | -------- |
| GET | `/storage-backends/types` | 获取 `STORAGE_ALLOW_LIST` 允许的存储类型 | Viewer+ |
| POST | `/storage-backends/test` | 使用原始配置测试连通性(不落库) | Admin+ |
| POST | `/storage-backends` | 创建存储实例 | Admin+ |
| GET | `/storage-backends` | 获取存储实例列表 | Viewer+ |
| GET | `/storage-backends/:id` | 获取存储实例详情 | Viewer+ |
| PUT | `/storage-backends/:id` | 更新存储实例(名称/凭据/状态) | Admin+ |
| DELETE | `/storage-backends/:id` | 删除存储实例(软删除) | Admin+ |
| POST | `/storage-backends/:id/test` | 测试已保存实例的连通性 | Admin+ |
| PUT | `/storage-backends/:id/default` | 设为空间默认存储实例 | Admin+ |
> 所有响应中的敏感字段(`access_key_id`、`secret_access_key`)都会被掩码。更新时若提交掩码占位符,则保留库中原有的真实凭据,不会被占位符覆盖。
## 存储配置字段(`config`)
不同 provider 使用同一套归一化的配置对象,按 provider 取用其中的子集:
| 字段 | 类型 | 说明 |
| ------------------- | ------- | ------------------------------------------------------------- |
| mode | string | MinIO 模式:`docker`(复用环境变量凭据)或 `remote` |
| endpoint | string | 对象存储 endpoint(COS 使用 region,不需要 endpoint) |
| region | string | 区域 |
| access_key_id | string | 访问密钥 ID(COS 对应 SecretID);响应中掩码 |
| secret_access_key | string | 访问密钥 Secret(COS 对应 SecretKey);响应中掩码 |
| bucket_name | string | Bucket 名称 |
| path_prefix | string | 对象前缀,必须为相对路径,禁止 `/` 开头或 `..` 上跳 |
| app_id | string | 腾讯云 COS AppID |
| use_ssl | boolean | 是否使用 SSL |
| force_path_style | boolean | S3 是否使用 path-style 寻址 |
| use_temp_bucket | boolean | OSS 是否使用临时 bucket |
| temp_bucket_name | string | 临时 bucket 名称 |
| temp_region | string | 临时 bucket 区域 |
> `endpoint`、`region`、`bucket_name`、`path_prefix` 决定对象的物理位置,**创建后不可变更**(更新时会被拒绝);如需迁移请使用存储迁移流程。凭据可通过更新单独轮换。
## GET `/storage-backends/types` - 获取允许的存储类型
返回 `STORAGE_ALLOW_LIST` 允许的 provider 列表,可用于前端动态表单生成。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/storage-backends/types' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**:
```json
{
"success": true,
"data": ["local", "minio", "cos", "s3"]
}
```
## POST `/storage-backends/test` - 使用原始配置测试连通性
用前端表单中尚未保存的配置执行一次连通性测试,不会写入数据库。
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| -------- | ------ | ---- | ------------------------------------------- |
| name | string | 是 | 实例显示名 |
| provider | string | 是 | 存储类型,取自 `/storage-backends/types` |
| config | object | 否 | 该 provider 对应的存储配置字段 |
**请求**:
```curl
curl --location --request POST 'http://localhost:8080/api/v1/storage-backends/test' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"name": "s3-hot",
"provider": "s3",
"config": {
"endpoint": "https://s3.example.com",
"region": "ap-test-1",
"access_key_id": "AKID",
"secret_access_key": "SECRET",
"bucket_name": "weknora"
}
}'
```
**响应(成功)**:
```json
{
"success": true
}
```
**响应(失败)**:
```json
{
"success": false,
"error": "连接被拒绝,请确认服务已启动且端口正确"
}
```
> 测试失败时 HTTP 状态码仍为 `200`,错误信息通过 `success: false` + `error` 返回;`error` 已脱敏,不会泄漏内部主机名、IP、端口或 TLS 细节。
## POST `/storage-backends` - 创建存储实例
为当前空间创建一个新的存储实例。创建前会先校验配置、执行 SSRF 校验(本地存储与 docker 模式 MinIO 除外),并执行一次连通性测试;任一环节失败都会返回 `400`。同一空间内实例名称不允许重复。
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| -------- | ------ | ---- | ------------------------------------------- |
| name | string | 是 | 实例显示名(空间内唯一) |
| provider | string | 是 | 存储类型,取自 `/storage-backends/types` |
| config | object | 否 | 该 provider 对应的存储配置字段 |
| status | string | 否 | `active`(默认)或 `disabled` |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/storage-backends' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"name": "s3-hot",
"provider": "s3",
"config": {
"endpoint": "https://s3.example.com",
"region": "ap-test-1",
"access_key_id": "AKID",
"secret_access_key": "SECRET",
"bucket_name": "weknora",
"path_prefix": "prod"
}
}'
```
**响应** (201):
```json
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "s3-hot",
"provider": "s3",
"config": {
"endpoint": "https://s3.example.com",
"region": "ap-test-1",
"access_key_id": "***",
"secret_access_key": "***",
"bucket_name": "weknora",
"path_prefix": "prod"
},
"source": "user",
"status": "active",
"legacy_alias": false,
"created_at": "2026-07-15T10:00:00Z",
"updated_at": "2026-07-15T10:00:00Z"
}
}
```
## GET `/storage-backends` - 获取存储实例列表
返回当前空间的所有存储实例(凭据已掩码),并在顶层返回空间默认实例 id。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/storage-backends' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**:
```json
{
"success": true,
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "s3-hot",
"provider": "s3",
"config": { "endpoint": "https://s3.example.com", "access_key_id": "***", "secret_access_key": "***", "bucket_name": "weknora" },
"source": "user",
"status": "active",
"legacy_alias": false
}
],
"default_storage_backend_id": "550e8400-e29b-41d4-a716-446655440000"
}
```
## GET `/storage-backends/:id` - 获取存储实例详情
根据 ID 获取当前空间下的单个存储实例,凭据已掩码。
**路径参数**:
| 字段 | 类型 | 必填 | 说明 |
| ---- | ------ | ---- | ------------- |
| id | string | 是 | 存储实例 ID |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/storage-backends/550e8400-e29b-41d4-a716-446655440000' \
--header 'X-API-Key: sk-xxxxx'
```
## PUT `/storage-backends/:id` - 更新存储实例
更新实例的可变字段(`name`、凭据、`status`)。`provider` 与物理位置字段(`endpoint`、`region`、`bucket_name`、`path_prefix`)不可变更,尝试更改会返回 `400`。环境变量来源(`source: "env"`)的实例只读,不可更新。更新同样会执行校验与连通性测试。
> 若 `access_key_id` / `secret_access_key` 提交为掩码占位符(`***`),则保留库中原有真实凭据。
**禁用保护**:将当前为默认实例、或仍有知识库绑定的实例改为 `disabled` 会被拒绝(`400`)。
**路径参数**:
| 字段 | 类型 | 必填 | 说明 |
| ---- | ------ | ---- | ------------- |
| id | string | 是 | 存储实例 ID |
**请求**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/storage-backends/550e8400-e29b-41d4-a716-446655440000' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"name": "s3-hot-renamed",
"provider": "s3",
"config": {
"access_key_id": "***",
"secret_access_key": "NEW_SECRET"
}
}'
```
## DELETE `/storage-backends/:id` - 删除存储实例
对存储实例执行软删除。以下情况删除会被拒绝(`400`):实例是空间默认实例、仍有知识库绑定、环境变量来源(只读)、或为 legacy 别名(旧文件路径可能仍引用它)。删除在事务中执行;PostgreSQL 上对目标行加行锁以避免并发绑定竞态。
**路径参数**:
| 字段 | 类型 | 必填 | 说明 |
| ---- | ------ | ---- | ------------- |
| id | string | 是 | 存储实例 ID |
**请求**:
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/storage-backends/550e8400-e29b-41d4-a716-446655440000' \
--header 'X-API-Key: sk-xxxxx'
```
**响应(成功)**:
```json
{
"success": true
}
```
## POST `/storage-backends/:id/test` - 测试已保存实例的连通性
对已保存的存储实例用其存储的凭据执行一次连通性测试。
**路径参数**:
| 字段 | 类型 | 必填 | 说明 |
| ---- | ------ | ---- | ------------- |
| id | string | 是 | 存储实例 ID |
**请求**:
```curl
curl --location --request POST 'http://localhost:8080/api/v1/storage-backends/550e8400-e29b-41d4-a716-446655440000/test' \
--header 'X-API-Key: sk-xxxxx'
```
**响应(成功)**:
```json
{
"success": true
}
```
> 与 `/storage-backends/test` 一致,测试失败时 HTTP 状态码仍为 `200`,错误经脱敏后通过 `success: false` + `error` 返回。
## PUT `/storage-backends/:id/default` - 设为空间默认实例
将某个存储实例标记为空间默认实例。仅 `active` 状态的实例可以设为默认。未显式绑定存储实例的新知识库将使用默认实例。
**路径参数**:
| 字段 | 类型 | 必填 | 说明 |
| ---- | ------ | ---- | ------------- |
| id | string | 是 | 存储实例 ID |
**请求**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/storage-backends/550e8400-e29b-41d4-a716-446655440000/default' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**:
```json
{
"success": true
}
```
## 环境变量存储实例
通过 `STORAGE_TYPE` 等环境变量配置的存储会以只读实例(`source: "env"`、`legacy_alias: true`)形式参与实例解析,使 env-only 部署与用户管理的实例走同一套解析路径。这类实例在每次启动时按环境变量刷新,且不可通过 API 更新或删除。
## 错误码
| HTTP 状态码 | 含义 |
| ----------- | ---------------------------------------------------------------- |
| 400 | 请求参数错误、校验失败、SSRF 校验失败、连通性测试失败、尝试更改不可变字段、修改只读实例、删除受保护实例、禁用被引用实例、设为默认时实例非 active |
| 401 | 未认证(缺少空间上下文或 API Key) |
| 403 | 权限不足(需 Admin+ 或 API Key `manage_storage_backends` capability) |
| 404 | 存储实例不存在 |
| 409 | 同名存储实例已存在 |

View File

@ -1,255 +0,0 @@
# 系统管理 API
[返回目录](./README.md)
| 方法 | 路径 | 描述 |
| ------ | --------------------------------- | ---------------------- |
| GET | `/system/capabilities` | 获取部署能力清单 |
| GET | `/system/info` | 获取系统信息 |
| GET | `/system/parser-engines` | 获取解析引擎列表 |
| POST | `/system/parser-engines/check` | 检查解析引擎可用性 |
| POST | `/system/docreader/reconnect` | 重连文档解析服务 |
| GET | `/system/storage-engine-status` | 获取存储引擎状态 |
| POST | `/system/storage-engine-check` | 检查存储引擎连通性 |
## GET `/system/capabilities` - 获取部署能力清单
返回当前部署版本,以及各功能模块是否已在后端注册对应路由。`supported: false` 表示 SPA 应隐藏相关入口;字段缺失或接口不可用时不应据此清空整个菜单(fail-open),但 Lite 版会始终将 `organizations` 标记为不支持。
**权限**:Viewer+(租户成员);任意有效 API Key 可读(`apiKeyAny`)。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/system/capabilities' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"code": 0,
"msg": "success",
"data": {
"edition": "standard",
"capabilities": {
"organizations": { "supported": true },
"agents": { "supported": true },
"integrations.im": { "supported": true },
"integrations.embed": { "supported": false, "reason": "route_not_registered" },
"integrations.api": { "supported": true },
"settings.mcp": { "supported": true },
"settings.websearch": { "supported": true },
"settings.vectorstore": { "supported": true },
"settings.storage": { "supported": true },
"settings.sandbox": { "supported": true }
}
}
}
```
Lite 版示例(共享空间不可用):
```json
{
"capabilities": {
"organizations": {
"supported": false,
"reason": "not_supported_in_lite"
}
}
}
```
## GET `/system/info` - 获取系统信息
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/system/info' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": {
"version": "1.2.0",
"edition": "community",
"commit_id": "a1b2c3d",
"build_time": "2025-08-12T08:00:00Z",
"go_version": "go1.21.5",
"keyword_index_engine": "bleve",
"vector_store_engine": "milvus",
"graph_database_engine": "neo4j",
"minio_enabled": true,
"db_version": "20250810_001"
},
"success": true
}
```
## GET `/system/parser-engines` - 获取解析引擎列表
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/system/parser-engines' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": [
{
"name": "docreader",
"label": "DocReader",
"description": "高精度文档解析引擎",
"available": true
},
{
"name": "tika",
"label": "Apache Tika",
"description": "通用文档解析引擎",
"available": false
}
],
"connected": true,
"success": true
}
```
## POST `/system/parser-engines/check` - 检查解析引擎可用性
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/system/parser-engines/check' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"addr": "http://docreader:8000"
}'
```
**响应**:
```json
{
"data": [
{
"name": "docreader",
"label": "DocReader",
"description": "高精度文档解析引擎",
"available": true
}
],
"success": true
}
```
## POST `/system/docreader/reconnect` - 重连文档解析服务
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/system/docreader/reconnect' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"addr": "http://docreader:8000"
}'
```
**响应**:
```json
{
"success": true
}
```
## GET `/system/storage-engine-status` - 获取存储引擎状态
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/system/storage-engine-status' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": {
"engines": [
{
"name": "minio",
"available": true,
"description": "MinIO 对象存储"
},
{
"name": "cos",
"available": false,
"description": "腾讯云 COS 对象存储"
},
{
"name": "s3",
"available": false,
"description": "AWS S3 对象存储"
},
{
"name": "oss",
"available": false,
"description": "阿里云 OSS 对象存储"
}
],
"minio_env_available": true
},
"success": true
}
```
## POST `/system/storage-engine-check` - 检查存储引擎连通性
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/system/storage-engine-check' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"provider": "minio",
"minio": {
"endpoint": "localhost:9000",
"access_key": "minioadmin",
"secret_key": "minioadmin",
"bucket": "weknora",
"use_ssl": false
}
}'
```
**响应**:
```json
{
"data": {
"ok": true,
"message": "连接成功",
"bucket_created": false
},
"success": true
}
```

View File

@ -1,183 +0,0 @@
# 标签管理 API
[返回目录](./README.md)
| 方法 | 路径 | 描述 |
| ------ | ------------------------------------- | ------------------------ |
| GET | `/knowledge-bases/:id/tags` | 获取知识库标签列表 |
| POST | `/knowledge-bases/:id/tags` | 创建标签 |
| PUT | `/knowledge-bases/:id/tags/:tag_id` | 更新标签 |
| DELETE | `/knowledge-bases/:id/tags/:tag_id` | 删除标签 |
## GET `/knowledge-bases/:id/tags` - 获取知识库标签列表
**查询参数**:
- `page`: 页码(默认 1)
- `page_size`: 每页条数(默认 20)
- `keyword`: 标签名称关键字搜索(可选)
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/tags?page=1&page_size=10' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": {
"total": 2,
"page": 1,
"page_size": 10,
"data": [
{
"id": "tag-00000001",
"tenant_id": 1,
"knowledge_base_id": "kb-00000001",
"name": "技术文档",
"color": "#1890ff",
"sort_order": 1,
"created_at": "2025-08-12T10:00:00+08:00",
"updated_at": "2025-08-12T10:00:00+08:00",
"knowledge_count": 5,
"chunk_count": 120
},
{
"id": "tag-00000002",
"tenant_id": 1,
"knowledge_base_id": "kb-00000001",
"name": "常见问题",
"color": "#52c41a",
"sort_order": 2,
"created_at": "2025-08-12T10:00:00+08:00",
"updated_at": "2025-08-12T10:00:00+08:00",
"knowledge_count": 3,
"chunk_count": 45
}
]
},
"success": true
}
```
## POST `/knowledge-bases/:id/tags` - 创建标签
**路径参数**:
| 字段 | 类型 | 说明 |
| ---- | ------ | ----------- |
| id | string | 知识库 ID |
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| ---------- | ------ | ---- | ------------------------ |
| name | string | 是 | 标签名(同库内唯一) |
| color | string | 否 | 标签颜色(CSS 颜色字符串) |
| sort_order | int | 否 | 排序值(数值越小越靠前) |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/tags' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"name": "产品手册",
"color": "#faad14",
"sort_order": 3
}'
```
**响应**:
```json
{
"data": {
"id": "tag-00000003",
"tenant_id": 1,
"knowledge_base_id": "kb-00000001",
"name": "产品手册",
"color": "#faad14",
"sort_order": 3,
"created_at": "2025-08-12T11:00:00+08:00",
"updated_at": "2025-08-12T11:00:00+08:00"
},
"success": true
}
```
## PUT `/knowledge-bases/:id/tags/:tag_id` - 更新标签
**路径参数**:
| 字段 | 类型 | 说明 |
| ------ | ------ | ----------- |
| id | string | 知识库 ID |
| tag_id | string | 标签 ID |
**参数说明(请求体)**: 同创建接口,所有字段均可选;未传则保留原值。
**请求**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/tags/tag-00000003' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"name": "产品手册更新",
"color": "#ff4d4f"
}'
```
**响应**:
```json
{
"data": {
"id": "tag-00000003",
"tenant_id": 1,
"knowledge_base_id": "kb-00000001",
"name": "产品手册更新",
"color": "#ff4d4f",
"sort_order": 3,
"created_at": "2025-08-12T11:00:00+08:00",
"updated_at": "2025-08-12T11:30:00+08:00"
},
"success": true
}
```
## DELETE `/knowledge-bases/:id/tags/:tag_id` - 删除标签
**路径参数**:
| 字段 | 类型 | 说明 |
| ------ | ------ | -------- |
| id | string | 知识库 ID |
| tag_id | string | 标签 ID |
**查询参数**:
| 字段 | 类型 | 默认 | 说明 |
| ----- | ------- | ----- | --------------------------------------------- |
| force | boolean | false | 设置为 `true` 时强制删除(即使标签被引用) |
**请求**:
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/tags/tag-00000003?force=true' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"success": true
}
```

View File

@ -1,649 +0,0 @@
# 空间管理 API
[返回目录](./README.md)
包含两组接口:
- 空间 CRUD(`/tenants`、`/tenants/:id`):当前认证用户对自己所属空间进行管理;跨空间访问需要管理员权限。
- 跨空间接口(`/tenants/all`、`/tenants/search`):**需要服务端启用 `EnableCrossTenantAccess` 且当前用户具备 `CanAccessAllTenants` 权限**,否则返回 403。
- 空间 KV 配置(`/tenants/kv/:key`):当前空间级别的通用配置项,**`tenant_id` 从认证上下文中获取,不在 URL 中传入**。
| 方法 | 路径 | 描述 |
| ------ | -------------------------- | ------------------------------------------------- |
| GET | `/tenants/all` | 获取所有空间列表(需跨空间权限) |
| GET | `/tenants/search` | 分页搜索空间(需跨空间权限) |
| POST | `/tenants` | 创建新空间 |
| GET | `/tenants/:id` | 获取指定空间信息 |
| PUT | `/tenants/:id` | 更新空间信息 |
| DELETE | `/tenants/:id` | 删除空间 |
| GET | `/tenants/:id/api-keys` | 列出空间 API Key(Owner) |
| POST | `/tenants/:id/api-keys` | 创建带角色的 API Key(Owner) |
| DELETE | `/tenants/:id/api-keys/:key_id` | 吊销指定 API Key(Owner) |
| GET | `/tenants/:id/api-principal-config` | 获取 API Key 用户身份配置(Owner) |
| PUT | `/tenants/:id/api-principal-config` | 更新 API Key 用户身份配置(Owner) |
| GET | `/tenants` | 获取当前用户可见的空间列表 |
| GET | `/tenants/kv/:key` | 获取当前空间的 KV 配置(空间由认证上下文确定) |
| PUT | `/tenants/kv/:key` | 更新当前空间的 KV 配置(空间由认证上下文确定) |
## GET `/tenants/all` - 获取所有空间列表
获取系统中所有空间列表,需要跨空间权限。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/tenants/all' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: sk-An7_t_izCKFIJ4iht9Xjcjnj_MC48ILvwezEDki9ScfIa7KA'
```
**响应**:
```json
{
"data": {
"items": [
{
"id": 10001,
"name": "weknora-1",
"description": "weknora workspaces 1",
"status": "active",
"business": "wechat",
"created_at": "2025-08-11T20:37:28.39698+08:00",
"updated_at": "2025-08-11T20:37:28.405693+08:00"
},
{
"id": 10002,
"name": "weknora-2",
"description": "weknora workspaces 2",
"status": "active",
"business": "wechat",
"created_at": "2025-08-11T20:52:58.05679+08:00",
"updated_at": "2025-08-11T20:52:58.060495+08:00"
}
]
},
"success": true
}
```
## GET `/tenants/search` - 搜索空间
按关键词搜索空间,需要跨空间权限。
**查询参数**:
- `keyword`: 搜索关键词(可选)
- `tenant_id`: 按空间ID筛选(可选)
- `page`: 页码(默认 1)
- `page_size`: 每页条数(默认 20)
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/tenants/search?keyword=weknora&page=1&page_size=10' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: sk-An7_t_izCKFIJ4iht9Xjcjnj_MC48ILvwezEDki9ScfIa7KA'
```
**响应**:
```json
{
"data": {
"items": [
{
"id": 10002,
"name": "weknora",
"description": "weknora workspaces",
"status": "active",
"business": "wechat",
"created_at": "2025-08-11T20:52:58.05679+08:00",
"updated_at": "2025-08-11T20:52:58.060495+08:00"
}
],
"total": 1,
"page": 1,
"page_size": 10
},
"success": true
}
```
## POST `/tenants` - 创建新空间
创建一个新的空间。**默认不会**自动发放 API Key;请在创建后通过 `POST /tenants/:id/api-keys` 创建密钥。从旧版本升级时,原有 `tenants.api_key` 会迁移到 `tenant_api_keys` 表并继续可用,直至被吊销。
> **兼容旧行为(可选)**:如需恢复旧版「创建空间即下发默认 API Key」的行为,可将系统设置 `tenant.auto_create_api_key` 置为 `true`(或设置环境变量 `WEKNORA_TENANT_AUTO_CREATE_API_KEY=true`)。开启后,创建空间会自动生成一个 `full_access` 权限的 API Key,并在响应体 `data.api_key` 中返回其明文 token(仅本次创建响应返回,请妥善保存)。默认 `false`。
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| ----------------- | ------ | ---- | ------------------------------------------------------ |
| name | string | 是 | 空间名称 |
| description | string | 否 | 空间描述 |
| business | string | 否 | 业务标识(如 `wechat`) |
| retriever_engines | object | 否 | 检索引擎组合配置(`engines` 数组:每项含 `retriever_type` 与 `retriever_engine_type`) |
| storage_quota | int | 否 | 存储配额(字节) |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/tenants' \
--header 'Content-Type: application/json' \
--data '{
"name": "weknora",
"description": "weknora workspaces",
"business": "wechat",
"retriever_engines": {
"engines": [
{
"retriever_type": "keywords",
"retriever_engine_type": "postgres"
},
{
"retriever_type": "vector",
"retriever_engine_type": "postgres"
}
]
}
}'
```
**响应**(默认,不含 API Key):
```json
{
"data": {
"id": 10000,
"name": "weknora",
"description": "weknora workspaces",
"status": "active",
"retriever_engines": {
"engines": [
{
"retriever_engine_type": "postgres",
"retriever_type": "keywords"
},
{
"retriever_engine_type": "postgres",
"retriever_type": "vector"
}
]
},
"business": "wechat",
"storage_quota": 10737418240,
"storage_used": 0,
"created_at": "2025-08-11T20:37:28.396980093+08:00",
"updated_at": "2025-08-11T20:37:28.396980301+08:00",
"deleted_at": null
},
"success": true
}
```
当开启 `tenant.auto_create_api_key`(或 `WEKNORA_TENANT_AUTO_CREATE_API_KEY=true`)时,响应的 `data` 中会额外包含 `api_key` 字段(`full_access` 密钥的明文 token):
```json
{
"data": {
"id": 10000,
"name": "weknora",
"description": "weknora workspaces",
"api_key": "sk-aaLRAgvCRJcmtiL2vLMeB1FB5UV0Q-qB7DlTE1pJ9KA93XZG",
"status": "active",
"business": "wechat",
"storage_quota": 10737418240,
"storage_used": 0,
"created_at": "2025-08-11T20:37:28.396980093+08:00",
"updated_at": "2025-08-11T20:37:28.396980301+08:00",
"deleted_at": null
},
"success": true
}
```
## GET `/tenants/:id` - 获取指定空间信息
获取指定 ID 的空间详情。只能访问自己所属空间;访问其他空间需要跨空间权限,否则返回 403。
**路径参数**:
| 字段 | 类型 | 说明 |
| ---- | ---- | ------- |
| id | int | 空间 ID |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/tenants/10000' \
--header 'X-API-Key: sk-aaLRAgvCRJcmtiL2vLMeB1FB5UV0Q-qB7DlTE1pJ9KA93XZG' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": {
"id": 10000,
"name": "weknora",
"description": "weknora workspaces",
"api_key": "sk-aaLRAgvCRJcmtiL2vLMeB1FB5UV0Q-qB7DlTE1pJ9KA93XZG",
"status": "active",
"retriever_engines": {
"engines": [
{
"retriever_engine_type": "postgres",
"retriever_type": "keywords"
},
{
"retriever_engine_type": "postgres",
"retriever_type": "vector"
}
]
},
"business": "wechat",
"storage_quota": 10737418240,
"storage_used": 0,
"created_at": "2025-08-11T20:37:28.39698+08:00",
"updated_at": "2025-08-11T20:37:28.405693+08:00",
"deleted_at": null
},
"success": true
}
```
## PUT `/tenants/:id` - 更新空间信息
更新指定空间的基础信息。访问规则同 `GET /tenants/:id`。
**路径参数**:
| 字段 | 类型 | 说明 |
| ---- | ---- | ------- |
| id | int | 空间 ID |
**参数说明(请求体)**: 与 `POST /tenants` 相同字段;未传字段保持原值。
**请求**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/tenants/10000' \
--header 'X-API-Key: sk-aaLRAgvCRJcmtiL2vLMeB1FB5UV0Q-qB7DlTE1pJ9KA93XZG' \
--header 'Content-Type: application/json' \
--data '{
"name": "weknora new",
"description": "weknora workspaces new",
"status": "active",
"retriever_engines": {
"engines": [
{
"retriever_engine_type": "postgres",
"retriever_type": "keywords"
},
{
"retriever_engine_type": "postgres",
"retriever_type": "vector"
}
]
},
"business": "wechat",
"storage_quota": 10737418240
}'
```
**响应**:
```json
{
"data": {
"id": 10000,
"name": "weknora new",
"description": "weknora workspaces new",
"api_key": "sk-aaLRAgvCRJcmtiL2vLMeB1FB5UV0Q-qB7DlTE1pJ9KA93XZG",
"status": "active",
"retriever_engines": {
"engines": [
{
"retriever_engine_type": "postgres",
"retriever_type": "keywords"
},
{
"retriever_engine_type": "postgres",
"retriever_type": "vector"
}
]
},
"business": "wechat",
"storage_quota": 10737418240,
"storage_used": 0,
"created_at": "2025-08-11T20:37:28.39698+08:00",
"updated_at": "2025-08-11T20:49:02.13421034+08:00",
"deleted_at": null
},
"success": true
}
```
## DELETE `/tenants/:id` - 删除空间
删除指定空间。访问规则同 `GET /tenants/:id`。
**路径参数**:
| 字段 | 类型 | 说明 |
| ---- | ---- | ------- |
| id | int | 空间 ID |
**请求**:
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/tenants/10000' \
--header 'X-API-Key: sk-aaLRAgvCRJcmtiL2vLMeB1FB5UV0Q-qB7DlTE1pJ9KA93XZG' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"message": "Workspace deleted successfully",
"success": true
}
```
## API Key 管理(`tenant_api_keys`)
自 scoped API Key 改造后,密钥以独立记录存储,支持:
- **role**:`viewer`(只读 + 语义检索 POST)、`contributor`(知识库写入)、`admin`(空间级管理,不含 `/api-keys` 管理面)
- **knowledge_base_ids**:可选,将 Key 限制在指定知识库
- **吊销**:`DELETE /tenants/:id/api-keys/:key_id`
- **过期**:创建时可选 `expires_at_unix`
空间 Key 固定绑定创建时的空间。路由级 capability 鉴权与 KB 访问守卫会在 `X-API-Key` 认证后继续强制执行。
### 平台 API Key
系统管理员可在“系统管理 → 平台 API Key”创建不绑定单一空间的 Key。平台 Key 默认可以选择任意存在的空间,但每项操作仍必须具备对应 capability;平台 Key 不支持 `full_access`。
- 管理接口:`GET/POST /system/admin/api-keys`、`DELETE /system/admin/api-keys/:key_id`,仅人类 SystemAdmin 会话可调用,平台 Key 不能创建或吊销其他平台 Key。
- 调用普通空间 API 时必须同时传 `X-Tenant-ID: <空间 ID>`;服务端解析目标空间后继续复用原有空间 Context、路由 capability 和知识库范围检查。
- 调用明确开放的 `/system/admin/*` 控制面接口时不需要 `X-Tenant-ID`,需要 `system_*` capability。
- 平台 Key 明文仅在创建响应的 `data.token` 返回一次;列表仅返回脱敏值。
```bash
curl 'http://localhost:8080/api/v1/knowledge-bases' \
-H 'X-API-Key: <platform-api-key>' \
-H 'X-Tenant-ID: 10000'
```
平台 capability:
| capability | 权限 |
| --- | --- |
| `system_tenants_read` | 列出、搜索、查看全部空间 |
| `system_tenants_manage` | 创建、更新、删除空间以及应用全局空间配置 |
| `system_settings_read` | 读取系统设置 |
| `system_settings_manage` | 更新、重置系统设置 |
| `system_runtime_read` | 查看运行时队列和任务 |
| `system_runtime_manage` | 重试、立即执行、取消、删除运行时任务 |
| `system_audit_read` | 读取平台审计日志 |
平台 Key 也可以携带现有空间 capability,例如 `retrieve`、`ingest`、`manage_kbs`;这些能力作用于请求中 `X-Tenant-ID` 指定的空间。
## API Key Principal:隔离边界与安全说明
`api-principal-config` 控制 `X-API-Key` 请求如何映射为终端 **Principal**。请先理解以下边界,再选择模式。
### Principal 隔离范围(当前实现)
Principal **仅**用于按终端用户隔离以下能力:
- **对话 Session**(创建、列表、读取按外部用户分开;`仅空间` 模式仍共用空间级 Session)
- **MCP OAuth** 访问令牌(同一空间下不同外部用户各自授权,token 互不共用)
- 对话内 MCP OAuth 提示、MCP 工具审批等与终端用户绑定的流程
Principal **不会**缩小 API Key 的 HTTP 路由权限:路由访问由 Key 的 `role` 控制;空间内 RBAC 角色与 `role` 一致。知识库、Agent 等资源的细粒度访问另受 KB 守卫约束。
### 模式与安全假设
| mode | 适用场景 | 安全假设 |
| ---- | -------- | -------- |
| `tenant` | 无 per-user MCP 需求 | 全空间共用一个 MCP OAuth 身份 |
| `direct_header` | 仅可信服务端到服务端 | 用户 ID 来自调用方请求头,**可被持有 API Key 的任意调用方伪造**(冒充其他外部用户并共用/劫持其 MCP OAuth 授权)。面向终端用户或不可信客户端时**禁止**使用;若必须使用,请开启 `require_direct_header` 并确保 API Key 仅保存在可信后端 |
| `signed_token` | 面向终端用户的集成(**推荐**) | 由业务后端使用 `hmac_secret` 为外部用户签发短期 HS256 JWT;无效或缺失 token 返回 401,**不回退**为空间级 Principal |
`direct_header` 模式下,若未携带用户 ID 请求头:`require_direct_header=false` 时回退为空间级 Principal;`require_direct_header=true` 时返回 401。
## GET `/tenants/:id/api-principal-config` - 获取 API Key 用户身份配置
返回空间级 API Key 请求如何映射为终端 Principal 的配置。**需要 Owner 权限**。
**响应字段**:
| 字段 | 类型 | 说明 |
| ---- | ---- | ---- |
| mode | string | `tenant` / `direct_header` / `signed_token` |
| direct_header_name | string | 直接传用户 ID 时的请求头名,默认 `X-External-User-ID` |
| signed_token_header_name | string | 签名 token 模式请求头名,默认 `X-External-User-Token` |
| require_direct_header | bool | `direct_header` 模式下是否强制要求用户 ID 请求头 |
| has_hmac_secret | bool | 是否已配置 HMAC secret(不返回明文) |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/tenants/10000/api-principal-config' \
--header 'Authorization: Bearer <token>'
```
**响应**:
```json
{
"success": true,
"data": {
"mode": "signed_token",
"direct_header_name": "X-External-User-ID",
"signed_token_header_name": "X-External-User-Token",
"require_direct_header": false,
"has_hmac_secret": true
}
}
```
## PUT `/tenants/:id/api-principal-config` - 更新 API Key 用户身份配置
更新 API Key 请求的 Principal 映射方式。**需要 Owner 权限**。
**请求体**:
| 字段 | 类型 | 说明 |
| ---- | ---- | ---- |
| mode | string | 必填,`tenant` / `direct_header` / `signed_token` |
| direct_header_name | string | 可选 |
| signed_token_header_name | string | 可选 |
| require_direct_header | bool | 可选,`direct_header` 模式下缺 header 是否 401 |
| hmac_secret | string | 可选,`signed_token` 模式 HMAC 密钥;省略则保留现有值 |
`signed_token` 模式首次启用时必须提供 `hmac_secret`。
外部用户 JWT 要求:HS256 签名、`aud=weknora`、包含 `sub` 与 `tenant_id`、有效期不超过 24 小时。
**请求**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/tenants/10000/api-principal-config' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"mode": "direct_header",
"direct_header_name": "X-External-User-ID",
"require_direct_header": true
}'
```
## GET `/tenants` - 获取空间列表
返回当前认证上下文对应的空间(普通用户为单条;管理员仍只返回自身空间)。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/tenants' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": {
"items": [
{
"id": 10002,
"name": "weknora",
"description": "weknora workspaces",
"api_key": "sk-An7_t_izCKFIJ4iht9Xjcjnj_MC48ILvwezEDki9ScfIa7KA",
"status": "active",
"retriever_engines": {
"engines": [
{
"retriever_engine_type": "postgres",
"retriever_type": "keywords"
},
{
"retriever_engine_type": "postgres",
"retriever_type": "vector"
}
]
},
"business": "wechat",
"storage_quota": 10737418240,
"storage_used": 0,
"created_at": "2025-08-11T20:52:58.05679+08:00",
"updated_at": "2025-08-11T20:52:58.060495+08:00",
"deleted_at": null
}
]
},
"success": true
}
```
## GET `/tenants/kv/:key` - 获取空间 KV 配置
获取当前空间的 KV 配置项。**空间 ID 从认证上下文中获取**(即由 `X-API-Key` / Bearer Token 对应的空间决定),URL 中不需要也不接受 tenant_id。
**路径参数**:
| 字段 | 类型 | 说明 |
| ---- | ------ | ---------------------------------------------- |
| key | string | 配置键名(见下方支持的 key 列表,不支持的键返回 400) |
**支持的 key 值**:
| key | 说明 |
| ---------------------- | ----------------------------- |
| `agent-config` | Agent 配置(最大迭代次数、温度、System Prompt、可用工具等) |
| `web-search-config` | 网页搜索配置 |
| `conversation-config` | 普通模式会话/对话配置 |
| `prompt-templates` | 系统提示词模板(只读,按用户语言本地化) |
| `parser-engine-config` | 解析引擎配置(如 MinerU) |
| `storage-engine-config`| 存储引擎配置(Local/MinIO/COS) |
| `chat-history-config` | 聊天历史索引配置 |
| `retrieval-config` | 全局检索配置 |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/tenants/kv/agent-config' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应(以 `agent-config` 为例)**:
```json
{
"data": {
"max_iterations": 10,
"allowed_tools": ["knowledge_search", "web_search"],
"temperature": 0.3,
"system_prompt": "...",
"use_custom_system_prompt": false,
"available_tools": [
{ "name": "knowledge_search", "label": "知识库检索", "description": "..." }
],
"available_placeholders": [
{ "name": "web_search_status", "label": "联网搜索状态", "description": "..." }
]
},
"success": true
}
```
失败时(不支持的键):
```json
{ "success": false, "error": "unsupported key" }
```
## PUT `/tenants/kv/:key` - 更新空间 KV 配置
更新当前空间的 KV 配置项。**空间 ID 从认证上下文中获取**,请求体结构按 `key` 不同而异。`prompt-templates` 为只读,不支持 PUT。
**路径参数**:
| 字段 | 类型 | 说明 |
| ---- | ------ | ----------------------------- |
| key | string | 配置键名(见 GET 接口的支持列表,`prompt-templates` 除外) |
**请求(以 `agent-config` 为例)**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/tenants/kv/agent-config' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"max_iterations": 20,
"temperature": 0.3,
"system_prompt": ""
}'
```
**响应**:
```json
{
"data": {
"max_iterations": 20,
"allowed_tools": ["knowledge_search", "web_search"],
"temperature": 0.3,
"system_prompt": "",
"use_custom_system_prompt": false
},
"message": "Agent configuration updated successfully",
"success": true
}
```
**约束**:
- `agent-config`: `max_iterations` 为正整数时上限 100,`-1` 表示不限制;`temperature` 取值范围 `[0, 2]`。
- `web-search-config`: `max_results` 取值范围 `[1, 50]`。
- `conversation-config`: 包含多项阈值校验(如 `keyword_threshold` / `vector_threshold` ∈ `[0, 1]`,`rerank_threshold` ∈ `[-10, 10]`,`temperature` ∈ `[0, 2]`,`max_completion_tokens` ∈ `[1, 100000]` 等)。
- `retrieval-config`: `embedding_top_k` / `rerank_top_k` ∈ `[0, 200]`;阈值范围同上。
- `storage-engine-config`: `default_provider` 必须在 `STORAGE_ALLOW_LIST` 允许的列表内。
- `chat-history-config`: 启用且设置了 `embedding_model_id` 而尚未关联知识库时,会自动创建一个隐藏知识库并将其 ID 写入配置。
## 空间邀请(邮箱邀请已注册用户)
`POST /tenants/:id/invitations` 通过邮箱邀请**已注册**用户。全局开关 `tenant.auto_accept_invitation`(环境变量 `WEKNORA_TENANT_AUTO_ACCEPT_INVITATION`,默认 `false`)控制行为:
| 开关 | 行为 | 成功响应 `data` 形状 |
| ---- | ---- | -------------------- |
| `false` | 创建 pending 邀请,受邀人须在 `/me/invitations` 接受 | `TenantInvitation`(含 `id`、`status: pending`) |
| `true` | 直接写入 `tenant_members`,并 reconcile 已有 pending 行 | `TenantMember`(含 `user_id`、`status: active`) |
开启 auto-accept 时,无默认空间的受邀人会将该空间设为 home tenant(与手动接受邀请一致)。SPA 通过 `GET /auth/me` 的 `capabilities.auto_accept_invitation` 感知开关,无需读取系统设置 API。

View File

@ -1,437 +0,0 @@
# Vector Store API
[返回目录](./README.md)
向量存储(VectorStore)API 用于管理空间的向量数据库连接配置,支持 Elasticsearch、PostgreSQL、Qdrant、Milvus、Weaviate、Tencent VectorDB、SQLite 等引擎。接口同时管理用户在 DB 中创建的配置(`source: "user"`)以及通过 `RETRIEVE_DRIVER` 环境变量配置的虚拟存储(`source: "env"`,只读)。
| 方法 | 路径 | 描述 |
| ------ | ---------------------------- | -------------------------------- |
| GET | `/vector-stores/types` | 获取支持的引擎类型及字段元数据 |
| POST | `/vector-stores/test` | 使用原始凭据测试连接(不落库) |
| POST | `/vector-stores` | 创建向量存储 |
| GET | `/vector-stores` | 获取向量存储列表 |
| GET | `/vector-stores/:id` | 获取向量存储详情 |
| PUT | `/vector-stores/:id` | 更新向量存储(仅名称可改) |
| DELETE | `/vector-stores/:id` | 删除向量存储(软删除) |
| POST | `/vector-stores/:id/test` | 测试已保存或环境变量存储的连通性 |
## GET `/vector-stores/types` - 获取支持的引擎类型
返回所有支持的引擎类型及其连接配置字段、索引配置字段的定义,可用于前端动态表单生成。系统级元数据,无需鉴权感知,但仍需 `X-API-Key`。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/vector-stores/types' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**:
```json
{
"success": true,
"data": [
{
"type": "elasticsearch",
"display_name": "Elasticsearch (Keywords + Vector)",
"connection_fields": [
{ "name": "addr", "type": "string", "required": true, "description": "Elasticsearch URL (e.g., http://localhost:9200)" },
{ "name": "username", "type": "string", "required": false },
{ "name": "password", "type": "string", "required": false, "sensitive": true }
],
"index_fields": [
{ "name": "index_name", "type": "string", "required": false, "default": "xwrag_default" },
{ "name": "number_of_shards", "type": "number", "required": false },
{ "name": "number_of_replicas", "type": "number", "required": false }
]
},
{
"type": "postgres",
"display_name": "PostgreSQL (Keywords + Vector)",
"connection_fields": [
{ "name": "use_default_connection", "type": "boolean", "required": false, "default": true, "description": "Use the application's default database connection" },
{ "name": "addr", "type": "string", "required": false, "description": "PostgreSQL connection string (required if use_default_connection is false)" },
{ "name": "username", "type": "string", "required": false },
{ "name": "password", "type": "string", "required": false, "sensitive": true }
]
}
]
}
```
## POST `/vector-stores/test` - 使用原始凭据测试连接
用前端表单中尚未保存的凭据执行一次连通性测试,不会写入数据库。成功时返回自动检测到的服务器版本(如 ES 版本号);某些引擎(如 Milvus、SQLite)无法检测版本,`version` 会返回空字符串。
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| ----------------- | ------ | ---- | ------------------------------------------------------------- |
| engine_type | string | 是 | 引擎类型,取自 `/vector-stores/types` 的 `type` |
| connection_config | object | 是 | 该引擎对应的连接配置字段(与 `connection_fields` 对应) |
**请求**:
```curl
curl --location --request POST 'http://localhost:8080/api/v1/vector-stores/test' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"engine_type": "elasticsearch",
"connection_config": {
"addr": "http://es:9200",
"username": "elastic",
"password": "changeme"
}
}'
```
**响应(成功)**:
```json
{
"success": true,
"version": "7.10.1"
}
```
**响应(失败)**:
```json
{
"success": false,
"error": "failed to connect to elasticsearch: connection refused or authentication failed"
}
```
> 注意:测试失败时 HTTP 状态码仍为 `200`,错误信息通过 `success: false` + `error` 字段返回。
## POST `/vector-stores` - 创建向量存储
为当前空间创建一个新的向量存储配置。同一 endpoint + index 组合在空间内不允许重复(与环境变量配置的存储也会冲突)。
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| ----------------- | ------ | ---- | --------------------------------------------------------------- |
| name | string | 是 | 存储显示名(空间内友好名) |
| engine_type | string | 是 | 引擎类型,取自 `/vector-stores/types` |
| connection_config | object | 是 | 连接配置(与所选引擎的 `connection_fields` 对应) |
| index_config | object | 否 | 索引配置(与所选引擎的 `index_fields` 对应) |
> Tencent VectorDB 使用 `engine_type: "tencent_vectordb"`。`connection_config` 中 `addr`、`username`、`api_key` 必填,`database` 可选;`index_config.collection_name` 表示集合名前缀,实际集合会按向量维度追加后缀(例如 `weknora_embeddings_768`);`index_config.replica_number` 表示创建集合时使用的副本数。该适配器同时支持向量检索和基于 BM25 sparse vector 的关键词检索;旧版本已创建且没有 `sparse_vector` 索引的集合需要重建并重新导入数据后才能启用关键词检索。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/vector-stores' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"name": "elasticsearch-hot",
"engine_type": "elasticsearch",
"connection_config": {
"addr": "http://es-hot:9200",
"username": "elastic",
"password": "changeme"
},
"index_config": {
"index_name": "my_index"
}
}'
```
**Tencent VectorDB 请求示例**:
```curl
curl --location 'http://localhost:8080/api/v1/vector-stores' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"name": "tencent-vectordb",
"engine_type": "tencent_vectordb",
"connection_config": {
"addr": "http://your-instance.tencentvectordb.com",
"username": "root",
"api_key": "your_api_key",
"database": "weknora"
},
"index_config": {
"collection_name": "weknora_embeddings",
"replica_number": 1
}
}'
```
**响应** (201):
```json
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "elasticsearch-hot",
"engine_type": "elasticsearch",
"connection_config": {
"addr": "http://es-hot:9200",
"username": "elastic",
"password": "***"
},
"index_config": {
"index_name": "my_index"
},
"source": "user",
"readonly": false,
"created_at": "2026-04-07T10:00:00Z",
"updated_at": "2026-04-07T10:00:00Z"
}
}
```
> 响应中的敏感字段(`password`、`api_key` 等)会被掩码为 `"***"`。`connection_config.version` 字段在连接测试成功后才会自动填充,创建时为空。
## GET `/vector-stores` - 获取向量存储列表
返回当前空间的所有向量存储,包含 `RETRIEVE_DRIVER` 环境变量配置的虚拟存储(`source: "env"`、`readonly: true`)和用户在 DB 中创建的存储(`source: "user"`、`readonly: false`)。环境变量存储排列在前。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/vector-stores' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**:
```json
{
"success": true,
"data": [
{
"id": "__env_postgres__",
"name": "postgres (env)",
"engine_type": "postgres",
"connection_config": {
"use_default_connection": true
},
"source": "env",
"readonly": true
},
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "elasticsearch-hot",
"engine_type": "elasticsearch",
"connection_config": {
"addr": "http://es-hot:9200",
"username": "elastic",
"password": "***"
},
"source": "user",
"readonly": false
}
]
}
```
## GET `/vector-stores/:id` - 获取向量存储详情
根据 ID 获取单个向量存储。支持 DB 存储 UUID 和 `__env_*` 形式的环境变量存储 ID(例如 `__env_postgres__`)。
**路径参数**:
| 字段 | 类型 | 必填 | 说明 |
| ---- | ------ | ---- | --------------------------------------------------- |
| id | string | 是 | 向量存储 ID(DB UUID 或 `__env_{driver}__`) |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/vector-stores/550e8400-e29b-41d4-a716-446655440000' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**:
```json
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "elasticsearch-hot",
"engine_type": "elasticsearch",
"connection_config": {
"addr": "http://es-hot:9200",
"username": "elastic",
"password": "***",
"version": "7.10.1"
},
"index_config": {
"index_name": "my_index"
},
"source": "user",
"readonly": false,
"created_at": "2026-04-07T10:00:00Z",
"updated_at": "2026-04-07T10:00:00Z"
}
}
```
## PUT `/vector-stores/:id` - 更新向量存储
仅支持更新 `name`。`engine_type`、`connection_config`、`index_config` 创建后不可变更;环境变量存储不可修改(返回 `400`)。
**路径参数**:
| 字段 | 类型 | 必填 | 说明 |
| ---- | ------ | ---- | -------------- |
| id | string | 是 | 向量存储 ID |
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| ---- | ------ | ---- | ----------------- |
| name | string | 是 | 新的存储显示名 |
**请求**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/vector-stores/550e8400-e29b-41d4-a716-446655440000' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"name": "elasticsearch-hot-renamed"
}'
```
**响应**:
```json
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "elasticsearch-hot-renamed",
"engine_type": "elasticsearch",
"connection_config": {
"addr": "http://es-hot:9200",
"username": "elastic",
"password": "***"
},
"index_config": {
"index_name": "my_index"
},
"source": "user",
"readonly": false,
"created_at": "2026-04-07T10:00:00Z",
"updated_at": "2026-04-07T10:05:00Z"
}
}
```
## DELETE `/vector-stores/:id` - 删除向量存储
对 DB 中的存储执行软删除。环境变量存储不可删除(返回 `400`)。
**Phase 2 — 绑定保护**:
删除请求在事务中执行,并按 `(tenant_id, vector_store_id)` 复合索引统计当前空间中仍绑定到该存储的活跃知识库数量。**只要存在任意绑定的知识库(已软删除的 KB 不计入),删除即被拒绝**,调用者必须先解绑或删除这些知识库才能继续。在 PostgreSQL 上,事务期间会对 `vector_stores` 行加 `SELECT … FOR UPDATE` 行锁,阻止并发的知识库创建请求悄悄落到正在被删除的存储上(SQLite 上则依赖 WAL + 单写入序列化达成同样语义)。
**路径参数**:
| 字段 | 类型 | 必填 | 说明 |
| ---- | ------ | ---- | -------------- |
| id | string | 是 | 向量存储 ID |
**请求**:
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/vector-stores/550e8400-e29b-41d4-a716-446655440000' \
--header 'X-API-Key: sk-xxxxx'
```
**响应(成功)**:
```json
{
"success": true
}
```
**响应(绑定保护触发)**:
```json
{
"success": false,
"error": {
"code": 1000,
"message": "vector store still has 3 knowledge base(s) bound to it; unbind or delete them before removing the store"
}
}
```
HTTP `400`。错误消息中包含具体的知识库数量(便于运营定位),但不包含任何 KB 的 ID/名称,以避免跨空间信息泄漏。删除被拒绝时,DB 中的存储行保持原状,进程内引擎注册表也不会被清除。
## POST `/vector-stores/:id/test` - 测试已保存或环境变量存储的连接
对已保存的 DB 存储或环境变量虚拟存储执行一次连接测试。成功时返回检测到的服务器版本;对 DB 存储,检测到的版本会被自动写回 `connection_config.version`,环境变量存储不会更新。
**路径参数**:
| 字段 | 类型 | 必填 | 说明 |
| ---- | ------ | ---- | --------------------------------------------------- |
| id | string | 是 | 向量存储 ID(DB UUID 或 `__env_{driver}__`) |
**请求**:
```curl
curl --location --request POST 'http://localhost:8080/api/v1/vector-stores/550e8400-e29b-41d4-a716-446655440000/test' \
--header 'X-API-Key: sk-xxxxx'
```
**响应(成功)**:
```json
{
"success": true,
"version": "7.10.1"
}
```
**响应(失败)**:
```json
{
"success": false,
"error": "failed to connect to elasticsearch: connection refused or authentication failed"
}
```
> 与 `/vector-stores/test` 一致,测试失败时 HTTP 状态码仍为 `200`,错误通过 `success: false` + `error` 返回。
## 环境变量存储
通过 `RETRIEVE_DRIVER` 环境变量配置的向量存储以虚拟条目形式出现在列表和详情中。这些条目的特征:
- **ID 格式**:`__env_{driver}__`(如 `__env_postgres__`、`__env_elasticsearch_v8__`)
- **source**:`"env"`
- **readonly**:`true`
- **不可修改/删除**:`PUT` 和 `DELETE` 返回 `400`
- **可测试连通性**:`POST /vector-stores/:id/test` 正常工作
- **被知识库绑定时**:未指定 `vector_store_id` 创建的知识库默认使用环境变量存储;这种知识库在响应中显示为 `vector_store_name="System default"` + `vector_store_source="env"`。
Tencent VectorDB 环境变量存储可通过 `TENCENT_VECTORDB_REPLICA_NUMBER` 覆盖默认集合副本数。默认值为 `1`;单节点 QA 环境可设为 `0`,生产环境可按 Tencent VectorDB 集群规模调整。
## 错误码
| HTTP 状态码 | code | 含义 |
| ----------- | ---- | --------------------------------------------------- |
| 400 | 1000 | 请求参数错误、校验失败、尝试修改环境变量存储、删除时仍有知识库绑定 |
| 400 | 2200 | 知识库创建时引用的 `vector_store_id` 无效(不存在或属于其他空间) |
| 400 | 2201 | 知识库创建时引用的存储当前不可用(DB 中存在但未注册到引擎) |
| 401 | 1001 | 未认证(缺少空间上下文或 API Key) |
| 404 | 1003 | 向量存储不存在 |
| 409 | 1005 | 同一 endpoint + index 组合已存在 |
| 500 | 1007 | 内部服务器错误 |
> `2200` / `2201` 由 `POST /knowledge-bases` 等知识库创建路径返回(详见 [knowledge-base.md](./knowledge-base.md)),列于此处仅为完整覆盖与向量存储相关的所有错误码。

View File

@ -1,278 +0,0 @@
# Web Search API
[返回目录](./README.md)
包含两组接口:
- `/web-search/providers`:返回**可用的 provider 类型**(只读元数据)
- `/web-search-providers/*`:当前空间**自定义保存**的 provider CRUD 与连通性测试
| 方法 | 路径 | 描述 |
| ------ | ------------------------------------- | ----------------------------------- |
| GET | `/web-search/providers` | 获取网络搜索服务商类型列表 |
| GET | `/web-search-providers/types` | 获取 Provider 类型元数据(含参数定义) |
| POST | `/web-search-providers/test` | 使用原始凭证测试连通性(不落库) |
| POST | `/web-search-providers` | 创建空间级 Provider 配置 |
| GET | `/web-search-providers` | 获取当前空间已保存的 Provider 列表 |
| GET | `/web-search-providers/:id` | 获取指定 Provider 详情 |
| PUT | `/web-search-providers/:id` | 更新 Provider |
| DELETE | `/web-search-providers/:id` | 删除 Provider |
| POST | `/web-search-providers/:id/test` | 使用已保存凭证测试连通性 |
## GET `/web-search/providers` - 获取网络搜索服务商类型列表
获取系统中可用的网络搜索服务商列表(系统级元数据,与空间无关)。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/web-search/providers' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'
```
**响应**:
```json
{
"data": [
{
"name": "google",
"label": "Google Search",
"description": "通过 Google 自定义搜索 API 进行网络搜索",
"enabled": true
},
{
"name": "bing",
"label": "Bing Search",
"description": "通过 Bing Search API 进行网络搜索",
"enabled": true
},
{
"name": "serpapi",
"label": "SerpAPI",
"description": "通过 SerpAPI 进行搜索引擎结果抓取",
"enabled": false
}
],
"success": true
}
```
## GET `/web-search-providers/types` - 获取 Provider 类型元数据
返回 UI 表单需要的所有 provider 类型及参数定义(每种 provider 需要哪些字段、类型、是否必填)。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/web-search-providers/types' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**:
```json
{
"data": [
{
"provider": "google",
"label": "Google Search",
"description": "...",
"parameter_schema": [
{ "name": "api_key", "label": "API Key", "type": "string", "required": true },
{ "name": "cx", "label": "Search Engine ID", "type": "string", "required": true }
]
}
],
"success": true
}
```
## POST `/web-search-providers/test` - 使用原始凭证测试连通性
前端表单"测试连接"按钮使用:用尚未保存的凭证发起一次样本搜索。
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| ---------- | ------ | ---- | --------------------------------- |
| provider | string | 是 | provider 类型(如 `google`、`bing`) |
| parameters | object | 是 | 该 provider 所需凭证与参数(与 `/types` 中 `parameter_schema` 对应) |
**请求**:
```curl
curl --location --request POST 'http://localhost:8080/api/v1/web-search-providers/test' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"provider": "google",
"parameters": {
"api_key": "AIza...",
"cx": "0123456789:abcdefg"
}
}'
```
**响应**:
```json
{ "success": true }
```
失败时:
```json
{ "success": false, "error": "google api: 403 forbidden" }
```
### 智谱 AI 配置
智谱使用独立的 Web Search API。`search_engine` 和 `content_size` 存放在
`parameters.extra_config` 中;未指定时分别使用 `search_std` 和 `medium`。
```json
{
"provider": "zhipu",
"parameters": {
"api_key": "your-zhipu-api-key",
"extra_config": {
"search_engine": "search_std",
"content_size": "medium"
}
}
}
```
`search_engine` 支持 `search_std`、`search_pro`、`search_pro_sogou` 和
`search_pro_quark`;`content_size` 支持 `medium` 和 `high`。
## POST `/web-search-providers` - 创建 Provider
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| ----------- | ------- | ---- | ------------------------------------------ |
| name | string | 是 | Provider 显示名(在空间内唯一友好名) |
| provider | string | 是 | Provider 类型(来自 `/web-search-providers/types`) |
| description | string | 否 | 备注 |
| parameters | object | 否 | 凭证与参数 |
| is_default | boolean | 否 | 是否设为当前空间默认 Provider |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/web-search-providers' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"name": "公司 Google CSE",
"provider": "google",
"description": "用于内网搜索",
"parameters": {
"api_key": "AIza...",
"cx": "0123456789:abcdefg"
},
"is_default": true
}'
```
**响应**:
```json
{
"data": {
"id": "wsp-...",
"tenant_id": 1,
"name": "公司 Google CSE",
"provider": "google",
"is_default": true,
"parameters": { "api_key": "***", "cx": "0123456789:abcdefg" }
},
"success": true
}
```
## GET `/web-search-providers` - 获取 Provider 列表
返回当前空间已保存的所有 Provider。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/web-search-providers' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**:
```json
{
"data": [
{ "id": "wsp-001", "name": "公司 Google CSE", "provider": "google", "is_default": true }
],
"success": true
}
```
## GET `/web-search-providers/:id` - 获取 Provider 详情
**路径参数**:
| 字段 | 类型 | 说明 |
| ---- | ------ | ----------- |
| id | string | Provider ID |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/web-search-providers/wsp-001' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**: 同创建接口。404 表示不存在。
## PUT `/web-search-providers/:id` - 更新 Provider
**说明**:`provider` 字段(类型)创建后不可修改,仅支持更新 `name` / `description` / `parameters` / `is_default`。
**参数说明(请求体)**: 同创建接口,但不包含 `provider`。
**请求**:
```curl
curl --location --request PUT 'http://localhost:8080/api/v1/web-search-providers/wsp-001' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"name": "公司 Google CSE (v2)",
"parameters": { "api_key": "NEW...", "cx": "0123456789:abcdefg" },
"is_default": false
}'
```
**响应**: `{ "data": {...更新后实体...}, "success": true }`
## DELETE `/web-search-providers/:id` - 删除 Provider
**请求**:
```curl
curl --location --request DELETE 'http://localhost:8080/api/v1/web-search-providers/wsp-001' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**: `{ "success": true }`
## POST `/web-search-providers/:id/test` - 测试已保存的 Provider
使用数据库中已保存的凭证发起一次样本搜索。
**请求**:
```curl
curl --location --request POST 'http://localhost:8080/api/v1/web-search-providers/wsp-001/test' \
--header 'X-API-Key: sk-xxxxx'
```
**响应**: 同 `POST /web-search-providers/test`。

View File

@ -1,135 +0,0 @@
# BrowserSkill 本机浏览器接入
WeKnora 使用 Tencent/BrowserSkill 的官方 daemon 和基于官方源码的配套扩展执行浏览器操作,通过 `local_browser` 薄工具适配接入,无需沙箱、浏览器技能包或用户运行本机命令。
## 使用流程
1. Docker 部署使用包含 BrowserSkill 的 app 和 frontend 镜像,默认从用户当前页面生成连接地址。原生部署需先运行 `./scripts/build_browserskill.sh`,配置下面的两个文件路径并重启服务。
2. 用户在个人设置 → 浏览器连接下载配套扩展,解压后在 Chrome 扩展程序页面加载。WeKnora 配套扩展通过此 ZIP 分发,官方原版扩展不包含全部任务控制接口。
3. 在设置页复制一次性配对链接,打开扩展「连接设置」,选择「远程连接」,粘贴链接并保存。同一空间内多个对话共用设备授权。
4. 回到对话描述浏览器任务。首次工具调用打开独立 Agent Window(请求不抢前台焦点),后续在该窗口中操作明确授权的标签。扩展不再提供后台标签组模式。
5. 主对话小预览可按住标题栏上下、左右拖动,也可定位任务标签、暂停操作、继续操作或结束浏览器任务。暂停中断当前浏览器调用并保留页面,结束会关闭任务新建标签、归还借用标签;这些按钮只控制当前对话的浏览器,不会停止整段对话或撤销浏览器配对。人工帮助和标签借用沿用官方交互,可能聚焦任务窗口或展示确认;借用标签会移入任务窗口,归还时恢复原位置。
自动化操作期间,从已授权页面通过 `target="_blank"`、`window.open` 等直接打开的新标签,只有 Chrome 导航事件能确认来源时才归当前任务管理,支持继续读取、切换、关闭及任务结束时清理。手动新建、拖入或无法确认来源的标签仍需借用确认;`tab_borrow` 可以在当前任务窗口内完成授权,无需先拖到普通窗口。拒绝借用后不能反复尝试读取或关闭;借用页面通过 `tab_return` 归还并保留。
`tab_list` 中 `scope: user` 的页面不属于当前任务,必须先借用成功再选择、读取或请求人工协助。普通网站查询优先在任务页打开,同一 Chrome 的登录 Cookie 可复用。借用确认默认等待五分钟,小窗提示到目标网页点击允许;确认超时后需先恢复任务,再重新发起一次借用,恢复本身不授予标签权限。
模型通过 `tab_close` 关闭任务最后一页时,扩展会临时保留一个归当前任务所有的空白标签,随后由任务结束流程统一回收。这样不会把 Chrome 随之关闭窗口误判为人工中断;用户主动关闭任务窗口仍会暂停任务,需显式继续。
授权只覆盖任务显式创建或借用的标签;窗口归属不作为授权依据。手动移入任务窗口的页面仍不可读取或操作。结束或断线清理会归还借用标签、关闭任务创建的标签,并保留用户页面。
## 人工参与与恢复
遇到登录、短信验证码、验证码挑战或授权时,Agent 应调用 `request_help`,说明需要用户完成的步骤。对话小预览显示具体提示,小窗自动展开并突出操作说明和定位按钮,长提示可滚动;点击定位按钮或预览进入浏览器,完成操作后在浏览器帮助提示中确认完成;原工具调用收到完成结果后,Agent 重新观察页面再继续。人工步骤只由用户在浏览器帮助提示中明确确认结束;不向模型暴露自动完成条件,网关也移除旧调用中的 `completion_criteria`,避免页面已有文字提前触发完成。帮助调用成功不代表登录成功,Agent 必须重新观察验证,仍未完成时再次请求人工协助。人工帮助默认等待 5 分钟,上限也是 5 分钟;Agent、网关 RPC 和跨节点转发为结果返回预留额外时间。
人工接管必须由工具调用触发。模型仅回复「请登录后告诉我」不会显示接管提示,也不会自动保留任务页面。系统级浏览器指引和工具说明要求先打开登录页,再调用 `request_help`;登录完成后继续原任务。排查「没有提示」时,先确认执行记录是否实际调用了该方法;如果返回 `disabled`,再检查扩展的人工帮助开关。提示词修改需要重新部署后端才会用于后续模型请求。
取消或超时会保留页面并暂停任务。浏览器窗口里的“中断”和对话预览里的“暂停”都由网关管理暂停状态,并取消正在执行的调用。点击预览“继续操作”后可在同一对话、同一浏览器任务中继续;如果 Agent 已结束本轮,再发送继续指令。恢复前重新读取页面,不自动重放中断的点击或提交。已连接但暂停时无需重新配对;只有设备连接确实断开时才提示等待重连。
## 预览与命令
自动化命令按对话串行执行。UI 预览通过扩展现有 WSS 的独立请求获取,不进入 daemon 自动化队列,因此长导航或人工等待不会占住截图通道。
预览获取当前任务标签的 CDP 画面,不调用激活窗口/标签 API。JPEG 宽度最多 640 像素。预览直接截取视口,再缩小实际位图,不在每次轮询前额外调用布局查询。任务活动期间,前端每次获取画面后间隔 1 秒刷新;服务端短缓存和扩展在途合并限制重复截图。页面隐藏时停止刷新,回到页面后立即更新。它是约 1 fps 的低帧率截图同步,不是视频流;失败超过 5 秒会提示画面暂未更新。
后台任务标签在调试连接期间启用 CDP `Emulation.setFocusEmulationEnabled`,让页面的可见性/焦点与绘制回调继续工作,不激活 Chrome 标签或窗口。仅任务新建或明确借用的标签启用此行为,由官方会话控制接口管理;独立预览也显式获取同一控制权,由官方会话结束或标签归还流程释放。否则依赖 `requestAnimationFrame` 或可见性事件加载内容的页面可能停在 Loading,直到用户切到该标签。
扩展对截图命令设置 3 秒等待上限,对 DOM 快照、无障碍树等读取命令设置 10 秒上限;读取超时会终止对应采集路径,避免同一页面继续走回退读取。错误保留具体 CDP 命令,扩展后台控制台记录超过 2 秒的命令及耗时。此保护不等于取消已经交给 Chrome 的命令,也不自动重放点击或提交。截图超时后仍保留在途标记,直到 Chrome 实际返回或调试连接释放;期间预览不再发送重复截图。框架自动附加配置按调试会话复用,断开后重建,失败后可重试。
上述上限针对单条 CDP 命令,并非整个 `observe`。复杂页面还要在扩展中进行语义树转换和文本渲染;重复操作按钮的上下文收集复用已扫描的兄弟节点前缀,避免逐按钮重复扫描整个列表。缓存仅存在于本次渲染,按作用域、目标名称和已有上下文隔离,每个父节点最多保留 64 种缓存项。CDP 等待超过 2 秒时记录方法与耗时,不记录页面内容。
本轮 Agent 执行结束时,沿用官方会话生命周期:成功完成的普通查询调用 `session_stop`,关闭任务创建的页面、归还借用标签并释放调试连接;输入框的本机浏览器选择偏好仍保留。调用时可设置顶层 `keep_open: true`,为用户要求保留的页面、交付结果或未完成的人工步骤保留整项任务;该标记仅对本轮有效。`request_help` 自动保留任务,人工步骤完成后可通过后续调用的 `keep_open: false` 恢复自动回收。报错、取消、暂停的任务保留现场,不自动关闭。保留任务时不主动断开调试连接或清除元素引用,下一轮继续使用同一官方会话,并重新观察页面。轮次结束后,WeKnora 停止预览轮询并返回缓存画面,卡片显示「已保留最后画面」;下一次浏览器调用恢复轮询。此空闲标记仅用于服务端收尾和预览状态,不表示浏览器已释放控制。真正结束任务时,扩展先阻止新预览并等待在途截图结束,再执行官方停止流程,避免截图重新附加到正在关闭的标签。
导航默认等待 `domcontentloaded`,避免已经可读的页面被慢图片等资源拖住;需要完整加载或网络空闲时可显式指定 `wait_until: "load"` 或 `"networkidle"`。文档就绪不代表异步应用内容已加载,操作前仍需观察目标内容是否出现。
页面显示错误内容和导航生命周期超时是两种不同状态:HTTP 错误页加载完成后仍可正常观察;已显示内容也可能仍在等待文档加载事件。扩展跟随主框架已提交的跳转文档,忽略旧文档及子框架事件,避免一直等跳转前文档的完成事件。daemon 为导航结果额外预留 2 秒传输时间,避免与扩展的同期限等待竞争,导致普通导航等待超时被升级为 RPC 中断。导航返回 `reached: "timeout"` 时,即使 RPC 成功返回,也会标记该次操作未完成并保留任务现场。模型应先重新观察页面,再决定下一步,不能因等待超时自动重放导航。用户点击“结束任务”时会先阻止后续命令、取消正在执行的操作(包括创建任务),再清理任务标签;归还标签失败或清理超时会保留暂停状态,可再次点击结束重试。
模型可调用 `{"method":"screenshot"}` 截取当前视口,或使用最近观察中的元素引用,例如 `{"method":"screenshot","ref":"e3"}` 截取元素区域;可选 `tab_id` 限定到任务内标签。截图通过独立图片内容传给支持视觉的对话模型;非视觉模型使用已配置的图片描述模型,未配置或描述失败时明确告知模型无法查看图片。Base64 不进入工具文本,结果卡片和历史消息保留截图。预览的小尺寸 JPEG 仅用于用户查看,与模型截图分开。
结果卡片展示控制台消息与堆栈、网络请求状态与错误、脚本返回值及具体失败原因;较长结果会截断并提示。小预览展示最近动作、动作耗时、已知页面地址和最近错误;页面地址去掉账号、查询参数和片段。耗时在动作执行期间更新,结束后固定。
支持 Document Picture-in-Picture 的浏览器可点击预览标题栏的“弹出悬浮窗”,把同一个预览和暂停、继续、结束按钮移到置顶窗口。切换标签页时继续同步画面;关闭悬浮窗或点击“返回对话小窗”会恢复页内预览,不结束浏览器任务。任务结束、切换会话或离开对话页面时关闭该会话的悬浮窗。此功能依赖安全上下文(HTTPS 或本机 localhost)及用户点击;不支持的浏览器保留页内小窗,打开失败时显示提示并允许重试。悬浮窗依赖原页面,不能在关闭 WeKnora 页面后独立运行。
模型调用采用扁平参数,例如 `{"method":"navigate","url":"https://example.com"}`、`{"method":"click","ref":"e3"}`、`{"method":"observe"}`。Schema 不再提供 `params` 字段,旧的嵌套格式直接拒绝。服务端校验所选动作的必填字段、字段类型及定位条件,再将参数转换为 BrowserSkill 原生 RPC 信封;会话和设备 ID 始终由服务端绑定。
`wait_ms` 的外层参数为 `duration_ms`,范围 0–10000 毫秒;工具描述、参数 schema 和执行前校验保持一致。命令超时或中断后暂停任务,不自动重放点击/提交。前端显示具体浏览器动作与可读错误,结果卡片分别展示网页内容、截图或标签列表,不展示原始协议 JSON。任务窗口沿用官方实现,标签归属及窗口内借用由配套补丁补充。
## 构建与部署
扩展和 daemon 均从官方 `main` 固定提交 `fa953dc6fcd868827b93164e3bea26198e691224` 构建(位于 `ext-v0.3.0` 之后,版本号仍为 0.3.0,协议 v1.3),固定于 `scripts/browserskill-release.json`。后台执行、后台截图、VOM 性能优化和导航重定向跟踪已采用官方实现;仍保留读取保护、任务控制、弹窗归属、末页生命周期及 daemon 导航响应宽限补丁。官方 CLI 0.3.0 二进制不包含最后一项修复,不能直接替代配套 daemon。构建按文件名顺序应用 `patches/browserskill/*.patch`,使用冻结的 pnpm 依赖和 Cargo.lock;本机构建需 Rust/Cargo、C 编译器,Linux 还需 CMake。可设置 `CARGO_TARGET_DIR` 复用编译缓存;Docker 构建阶段在目标架构运行,原生脚本不静默生成其他架构的二进制。详见 `patches/browserskill/README.md`。产物位于 `artifacts/browserskill/`,不提交二进制。
虽然扩展显示版本号仍为 0.3.0,已有用户仍需下载本次重新构建的配套 ZIP,覆盖原解压目录并在 Chrome 扩展程序页面重新加载;仅重启服务端不会更新扩展。保持原扩展 ID 时,上游会将旧的本地凭据迁移到扩展源 IndexedDB;重新安装导致 ID 改变时需要重新配对。
### Docker 部署
`docker/Dockerfile.app` 在独立 Node 构建阶段生成配套扩展,按目标 `linux/amd64` 或 `linux/arm64` 从同一固定源码构建 daemon,并将 `bsk`、扩展 ZIP 和许可证复制到运行镜像的 `/opt/weknora/browserskill/`。镜像已预设 `BROWSERSKILL_BINARY` 和 `BROWSERSKILL_EXTENSION_PATH`,无需安装 Chrome 或启用沙箱。不要用宿主机的 macOS `bsk` 替换容器中的 Linux 文件。
默认无需设置 `BROWSERSKILL_PUBLIC_URL`。设置页在申请配对时提交 `window.location.origin`,服务端保留域名和端口,将 HTTPS 转为 WSS(本机 HTTP 转为 WS),追加 `/api/v1/local-browser/extension`。例如访问 `https://weknora.example.com:8443`,自动生成 `wss://weknora.example.com:8443/api/v1/local-browser/extension`。地址不依赖反向代理传递的内部 Host 或协议。
仅当网关使用独立域名、自定义代理路径等特殊部署时,在 `.env` 显式覆盖:
```dotenv
BROWSERSKILL_PUBLIC_URL=wss://weknora.example.com/api/v1/local-browser/extension
```
将 app 和 frontend 更新到包含本次修改的镜像后,使用 `docker compose up -d app frontend` 重新创建服务;`docker compose restart` 不会加载修改后的环境变量。需要关闭此功能时,在 `.env` 显式设置 `BROWSERSKILL_BINARY=`。
配套 frontend Nginx 已处理扩展 WebSocket Upgrade,授权 POST 走普通 API 转发,集群内部接口返回 404。若外层还有 Ingress/Nginx,仍需为扩展路径转发 WebSocket,并提供浏览器信任的 TLS 证书;直接暴露 app 的部署须自行屏蔽公共入口的 `/api/v1/local-browser/internal`。
### 原生部署
构建需要 Git、Node.js(镜像使用 Node 24)、Python 3、Rust/Cargo 和 C 编译器,以及访问固定的上游源码、npm 和 Cargo 依赖的网络。执行 `./scripts/build_browserskill.sh` 后,将产物复制到下列路径,或将变量改为产物的实际绝对路径。连接地址同样默认从页面自动生成:
```dotenv
BROWSERSKILL_BINARY=/opt/weknora/browserskill/bsk
BROWSERSKILL_EXTENSION_PATH=/opt/weknora/browserskill/browser-skill-weknora-0.3.0.zip
```
构建脚本第二个参数可指定目标平台,例如 `./scripts/build_browserskill.sh ./artifacts/browserskill-linux linux/amd64`;不传时按宿主机系统和架构构建。
本机调试可用 `ws://localhost:8080/api/v1/local-browser/extension`;远程部署要求 WSS,内网可使用受浏览器信任的企业 CA。详细授权、重连、多副本路由、迁移及容量边界见 [生产部署链路](browser-skill-production.md)。
扩展使用官方 MIT 许可,分发时保留 `BrowserSkill-LICENSE`。配对授权遵循上游第三方网关协议;`gateway.task_preview`、`gateway.task_focus` 仍是配套补丁接口。预览和定位需要配套 ZIP;保留会话及任务收尾均采用官方机制,不依赖定制收尾接口。
## 验证
```bash
go test -race ./internal/browserskill ./internal/agent/... ./internal/handler/session \
./internal/router ./internal/application/service ./internal/container ./internal/middleware
```
原生/真实扩展测试另设:
```dotenv
BROWSERSKILL_TEST_BINARY=/absolute/path/to/bsk
BROWSERSKILL_TEST_EXTENSION=/absolute/path/to/unpacked-extension
BROWSERSKILL_TEST_CHROMIUM=/absolute/path/to/Chromium
BROWSERSKILL_TEST_PLAYWRIGHT=/absolute/path/to/playwright-core/index.mjs
BROWSERSKILL_TEST_HEADED=1
```
测试使用独立浏览器资料目录,覆盖配对、独立窗口、任务弹窗完整操作、窗口内借用确认与权限释放、导航/输入/点击、目标标签截图、人工等待期间预览、显式定位、暂停/继续/结束、任务隔离、授权持久化和双节点路由。目标部署网络、真实模型任务与规模容量仍须现场验收;本机浏览器不保证免除网站验证或 403。
补丁中的 `task-focus.browser.test.ts` 使用独立 Chrome 与原生 CDP 验证后台绘制、内容读取、截图和释放后的可见性恢复,避免 Playwright 默认的焦点模拟掩盖问题。在应用补丁后的 BrowserSkill 源码中,设置 `BSK_GEOMETRY_CHROME` 为测试 Chrome 路径,再执行 `pnpm --filter @browser-skill/extension exec vitest run src/browser-driver/__tests__/task-focus.browser.test.ts`(Node 20 另需 `NODE_OPTIONS=--experimental-websocket`)。
仅验证预览组件的真实 PiP 窗口(使用模拟任务 API,不需要扩展或模型):
```bash
BROWSERSKILL_TEST_CHROMIUM=/absolute/path/to/Chrome \
BROWSERSKILL_TEST_PLAYWRIGHT=/absolute/path/to/playwright-core/index.mjs \
node frontend/scripts/verify-browser-preview-pip.mjs
```
该验收覆盖真实弹出/还原、窗口样式、切换标签页后同步、隐藏页面分支、共享操作按钮、会话切换清理及不支持/打开失败的回退。
### 输入框选择本机浏览器
任务统一使用上游独立 Agent Window;旧的“后台标签组”设置不再生效。升级前结束已有任务。后台绘制保护只作用于明确授权的标签;完全遮挡或最小化时仍需按目标站点验收性能。
Agent 模式的输入框提供“本机浏览器”开关,可与联网搜索同时开启。选中后,请求携带 `local_browser_enabled: true`;本轮提示词明确要求使用 `local_browser` 完成适用的网页查询与操作,而不是把设备已配对当作使用意图。知识库、MCP、Skill、Shell 等工具仍按智能体配置和本轮选择正常提供,可以配合检索、处理内容及生成文件。联网搜索与浏览器同时开启时,可以先搜索发现链接,再用浏览器读取和操作网页。
浏览器不可用时必须说明原因,不能隐瞒失败或声称已通过浏览器读取。该选择不缩减工具注册范围,实际调用由模型遵循提示词和用户任务安排。选择状态随会话最近一次输入设置恢复,切换智能体会清除;关闭浏览器选择不会改变其他开关。此功能需要使用 Agent 接口,普通问答接口拒绝该字段为 true 的请求。
### 旧标签组清理
新版不创建标签组。旧版遗留的已保存分组不会自动删除,需要用户在 Chrome 中手动删除。

View File

@ -1,100 +0,0 @@
# BrowserSkill 生产部署链路
当前实现支持单实例调试与多个 WeKnora app 副本。浏览器执行、队列、标签借用与归还继续复用官方 BrowserSkill daemon/扩展。每个 app 按需启动一个共享 daemon;设备授权、连接归属和任务中断标记放在共用数据库中。
## 配对与重连
```mermaid
sequenceDiagram
participant U as 个人设置
participant E as Chrome 扩展
participant L as HTTPS/WSS 入口
participant A as WeKnora 节点
participant DB as PostgreSQL
participant B as 共享 BrowserSkill daemon
U->>A: 登录态生成一次性配对链接
A->>DB: 保存配对哈希(5 分钟)
A-->>U: WSS 地址 + fragment 配对令牌
U->>E: 粘贴链接,确认服务器
E->>L: HTTPS 激活(配对令牌 + 新设备令牌)
L->>A: /local-browser/extension/authorize
A->>DB: 原子消费配对记录、保存设备令牌哈希
A-->>E: 设备 ID、有效期与轮换时间
E->>L: WSS,子协议携带设备令牌
L->>A: 任一可用 app 副本
A->>DB: 校验设备、账号、成员状态;竞争连接租约
A->>B: 转发握手,替换为服务器分配的浏览器 ID
B-->>E: 完成原生握手
loop 连接有效期间
A->>DB: 每 10 秒检查授权并续租
end
```
- 配对链接仅供激活,5 分钟有效。生成新链接不会断开现有设备,成功激活新设备后才替换旧授权。
- 当前每个「空间+用户」保留一个设备授权;更换浏览器会替换旧设备。多个对话共用授权,各自创建任务窗口。
- 扩展生成 256 位随机设备令牌,仅放在扩展源 IndexedDB;服务器保存 SHA-256 哈希。设备令牌有效期 90 天,30 天后自动轮换。
- 轮换前扩展先保存候选令牌;响应丢失时使用同一候选重试,不会因客户端或服务器重启丢失新凭据。旧令牌提供 5 分钟连接宽限。相同设备的令牌轮换不重启活动的浏览器任务。
- 首次激活响应丢失时,重新生成配对链接激活即可;一次性配对凭据不能再次创建授权。
- 设备撤销、用户停用、成员资格暂停/移除都会阻止后续调用。活动连接在下一次授权检查时关闭;在途操作的取消不能撤销网页上已经发生的动作。
- 配对与设备令牌不放在 URL 查询参数中,不进入模型。相关接口不采集请求/响应正文日志,避免凭据、页面内容和截图进入日志。
## 多副本控制流
```mermaid
flowchart LR
Agent[任一 app 的 Agent / 会话 API] --> DB[(共用 PostgreSQL)]
DB -->|连接归属节点| Agent
Agent -->|签名内部 RPC,仅转发一次| Owner[持有连接的 app]
Owner -->|Unix Socket RPC| B[该节点的共享 daemon]
B <-->|本机 WebSocket| Owner
Owner <-->|WSS| E[用户 Chrome 扩展]
```
每次操作使用服务端持有的 tenant/user/session 绑定;模型不能覆盖原生 session ID 或浏览器 ID。内部转发需要共同密钥签名,签名覆盖时间戳、随机 nonce、目标节点和请求体。目标节点校验时效、去重并重新检查授权;请求不能被转发第二次,也不会自动重试点击等操作。
数据库连接租约为 45 秒,持有节点每 10 秒续租;每次连接有独立 lease key,旧连接的延迟释放不能清除新连接的租约。正常关闭主动释放节点租约;宕机后需等待旧租约到期,再加扩展的重连退避时间。WebSocket 不要求会话粘性,普通 HTTP 请求通过归属路由到连接节点。
一个节点的 daemon 故障会影响该节点承载的浏览器;其他节点不受进程故障影响。下一次通过认证的扩展连接会按需启动 daemon。节点启动采用合并等待,等待过程不持有全局状态锁。
## 任务恢复语义
设备自动重连与任务继续是两回事。开始原生任务前先写入持久化中断标记;连接或进程丢失后,旧任务一律显示暂停。用户点击对话小预览中的「继续任务」后才允许新调用。恢复后需重新观察页面,不能自动重放原来的点击、付款、发送或提交。
任务使用上游独立 Agent Window。断线清理会关闭任务创建的标签并归还借用标签,保留用户后来加入的页面。当前不承诺恢复之前的页面、DOM 引用、窗口布局或在途命令结果。小预览的「定位到浏览器」仅定位已存在的任务标签,不启动任务、不恢复自动化。这个 UI 操作通过网关传给扩展,复用上游 SessionManager 查找标签;模型不具备该 UI 控制入口。
## 配置
Docker app 镜像已内置匹配目标架构的配套 bsk、扩展和许可证,并预设两个文件路径;单实例默认无需额外环境变量,配对地址从用户当前页面的 origin 生成,保留外部域名和端口。`BROWSERSKILL_PUBLIC_URL` 仅作为独立网关域名/路径等特殊部署的优先覆盖项。原生部署各节点需自行安装产物。配置示例如下:
```dotenv
BROWSERSKILL_BINARY=/opt/weknora/browserskill/bsk
# 可选覆盖;省略时从页面自动生成。
# BROWSERSKILL_PUBLIC_URL=wss://weknora.example.com/api/v1/local-browser/extension
BROWSERSKILL_EXTENSION_PATH=/opt/weknora/browserskill/browser-skill-weknora-0.3.0.zip
BROWSERSKILL_MAX_CONNECTIONS=32
```
单实例无需下面两项。多副本必须额外配置:
```dotenv
# 每个节点各不相同,须直达本节点;不能填写负载均衡 Service 地址。
BROWSERSKILL_INTERNAL_URL=http://10.0.0.12:8080
# 所有副本相同,从 Secret 注入至少 32 字符的随机值。
BROWSERSKILL_CLUSTER_SECRET=<shared-random-secret>
```
Kubernetes 可通过 Downward API 获取 Pod IP,再设置节点直连地址。各节点共用 PostgreSQL;不要用多个独立 SQLite 文件部署多副本。签名保护内部 RPC 的认证与完整性;内部 HTTP 仅适用于可信隔离网络,需要传输保密时配置 HTTPS 和受信任证书。
入口代理开放 `/api/v1/local-browser/extension` 的 WebSocket Upgrade,以及其 `/authorize` POST。配套 frontend Nginx 已配置这两条链路,并拒绝 `/api/v1/local-browser/internal`。外层 Ingress/代理也须支持 WebSocket;绕过 frontend 直接暴露 app 时需自行拒绝公共入口的内部接口。通过网络策略仅允许 app 节点互访此内部接口。不要记录 Authorization、Sec-WebSocket-Protocol 或授权请求正文。WSS 可以使用企业 CA,无需公网;远程明文 WS 不受支持。
迁移:PostgreSQL `000093_browser_authorization`,SQLite `000014_browser_authorization`。默认自动迁移;若关闭 `AUTO_MIGRATE`,须先执行迁移。数据库只持久化授权/租约/中断标记,不存浏览器 Cookie 或截图。
扩展必须更新到 WeKnora 配套 0.3.0 构建。官方 0.3.0 原版缺少预览和定位接口,不能直接替换配套 ZIP。升级前结束任务;在原解压目录覆盖文件后重新加载扩展,可沿用原扩展 ID 并迁移授权凭据。重新安装导致 ID 改变时重新配对。服务端必须同步升级 bsk:从与扩展相同的固定源码提交 `fa953dc6fcd868827b93164e3bea26198e691224` 构建(版本号仍为 0.3.0,需重新构建并更新扩展),然后重启后端以释放旧 daemon。官方 CLI 0.3.0 不包含配套 daemon 的导航响应宽限补丁。
## 容量与验收
32 是单节点活动设备记录的默认保护上限,不是实测吞吐结论。每个用户仍有一条外部 WSS 和一条本机 WebSocket;共享 daemon 减少进程固定开销,不减少连接数。任务上限 64/用户。对话预览每轮完成后间隔 1 秒刷新,JPEG 宽度限制 640 像素;隐藏页面不轮询。截图独立于自动化队列,长命令或人工等待期间仍可更新。自动化请求按任务串行,预览使用短缓存与在途合并限制重复工作。
已提供自动测试:一次性配对、令牌轮换丢响应重试、账号停用检查、并发共享 daemon、跨用户/租户隔离、连接租约竞争及旧租约隔离、服务重启后使用原设备令牌连接且任务保持暂停、双 app 实例路由、内部签名防伪与防重放、真实 Chrome 扩展连接和任务标签定位。
生产上线仍需在目标集群完成 TLS/入口代理/NetworkPolicy 联调及负载测试:关注每节点 RSS、daemon CPU、活动连接数、截图流量、RPC 延迟/失败率和重连耗时。当前测试证明功能和故障隔离,不代表已经取得某个用户规模的容量保证。

View File

@ -1,44 +0,0 @@
# Steering an active conversation
While an agent is running, you can queue a follow-up or guide the current task.
| Action | Behavior |
| --- | --- |
| Enter or the send button | Queue the draft to send after the current answer finishes. |
| Command+Enter or Alt/Option+Enter | Send the draft as guidance for the active task. With an empty draft, promote the first eligible queued message. |
| Up arrow on a queued message | Send that message as guidance immediately. |
| Remove on a queued message | Remove the queued message. |
| Stop button | Stop generation. This replaces the send button while the agent is running and the draft is empty. |
| Shift+Enter or Ctrl+Enter | Insert a newline. |
Outside an active agent run, Enter sends a normal message. Input methods can
confirm composed text without accidentally sending it. Modes without steering
support keep the stop action during generation.
Queued messages appear in a compact strip immediately above the input's focus
border. Guidance moves into the conversation immediately; delivery failures can
be retried or removed. Earlier work remains visible, and guidance does not mark
the ongoing task as complete. Sending and entering a newly created session keep
the composer ready for further input.
Guidance applies to the task in progress. The agent retains unfinished goals and
constraints unless the user explicitly changes or cancels them. A short tagged
reminder accompanies each guidance message; existing context and tool results
are reused without an additional model call to classify the message. Message IDs
and execution boundaries preserve ordering across live updates and history reloads.
The conversation outline includes both user and assistant messages and highlights
all messages intersecting the visible conversation area.
## Component previews
These previews use sample messages and isolated production components; they do
not contain real conversation data or invoke a model.
Running with an empty draft:
![Queued guidance, visible outline entries, and Stop](images/chat-steer-preview.png)
Running with a draft:
![The same primary control becomes Send](images/chat-steer-send-preview.png)

View File

@ -1,36 +0,0 @@
# Client and integration upgrade notes
## Upgrade requirements
- **DingTalk:** HTTP callbacks are disabled. PostgreSQL migration 000096 and
SQLite migration 000017 convert DingTalk `webhook` channels to `websocket`.
Enable **Stream** in the DingTalk developer console using the existing
application credentials. Other platforms and channel settings are preserved.
The down migrations retain Stream mode.
- **Signing keys:** configure a unique `SYSTEM_SIGNING_KEY` (for example,
`openssl rand -hex 32`), or retain a valid private `SYSTEM_AES_KEY` as the
signing fallback. Pass the same key to all replicas. Known example keys cannot
sign links or embed sessions. The native desktop creates a persistent,
owner-only `signing.key` under its existing user configuration directory.
Do not overwrite an existing AES encryption key: that would make encrypted
credentials unreadable. Signing-key changes invalidate outstanding signed
links. All previous embed session handles are invalidated by the new signing
algorithm; visitors need a new session.
- **Lite:** anonymous HTTP auto-setup is no longer available. Native desktop
auto-login uses a random per-process capability obtained through the Wails
bridge. Browser clients use normal registration/login.
- **Organization invitations:** the candidate picker resolves an exact workspace
ID. Global workspace-name search is removed. Invitation links remain supported.
- **MCP uploads:** stdio now defaults to the working-directory upload boundary,
matching HTTP/SSE. Set `MCP_ALLOWED_UPLOAD_DIRS` to explicit trusted directories
if uploads outside that directory are required; symbolic links escaping those
directories are rejected.
- **MCP OAuth:** frontend redirects must be application-relative or use the
exact origin in `APP_EXTERNAL_URL`. Configure canonical MCP/OAuth endpoint URLs;
cross-origin redirects from their HTTP clients are refused.
- **IM webhooks:** configure the platform verification secret for each supported
HTTP channel. Empty secrets are rejected. Gateway/Stream channels cannot be
reached through the HTTP callback endpoint. Slack downloads require
`https://files.slack.com` or legacy `https://slack.com/files-pri/` URLs;
DingTalk session replies require its exact platform
endpoint.

View File

@ -1,22 +0,0 @@
# WeKnora 云镜像打包指南
把 WeKnora 打包成可分发的云镜像(AMI / 自定义镜像 / Snapshot),用户基于镜像创建实例后开机即用、自动随机化密钥、零私密泄漏。
## 通用工具
云无关的脚本和详细说明:[`scripts/cloud-image/README.md`](../../scripts/cloud-image/README.md)
包含 `prepare.sh` / `cleanup.sh` / `firstboot.sh` 三个脚本和两个 systemd 单元,已在多种发行版(Ubuntu / Debian / CentOS / TencentOS)上验证。
## 各平台具体操作
| 平台 | 文档 | 状态 |
|---|---|---|
| 腾讯云轻量应用服务器 / CVM | [tencent-lighthouse.md](./tencent-lighthouse.md) | ✅ |
| AWS EC2 (AMI) | _欢迎贡献_ | ⏳ |
| 阿里云 ECS | _欢迎贡献_ | ⏳ |
| 火山引擎 ECS | _欢迎贡献_ | ⏳ |
| 华为云 ECS | _欢迎贡献_ | ⏳ |
| 本地 KVM / Proxmox | _欢迎贡献_ | ⏳ |
> 各平台文档结构尽量保持一致:实例规格建议 → 制作镜像操作 → 共享/公开方式 → 该平台独有的注意事项。

View File

@ -1,100 +0,0 @@
# 腾讯云轻量应用服务器 / CVM 镜像制作指南
> **前置阅读**:通用脚本与流程见 [`scripts/cloud-image/README.md`](../../scripts/cloud-image/README.md)。本文只补充腾讯云平台专属的操作步骤。
## 实例规格建议
| 项 | 建议值 |
|---|---|
| 实例类型 | 轻量应用服务器(Lighthouse) / 云服务器 CVM 标准型 |
| CPU / 内存 | 至少 4 核 8G(推荐 4 核 16G,跑全功能 RAG + Agent) |
| 系统盘 | 至少 80G SSD |
| 镜像 | Ubuntu Server 22.04 LTS / TencentOS Server 3.1 |
| 地域 | 选你后续主要用户所在地域(同地域才能跨账号共享) |
## 完整流程
1. 控制台买一台符合上述规格的实例
2. SSH 进去,按 [scripts/cloud-image/README.md](../../scripts/cloud-image/README.md) 执行 `prepare.sh`
3. 浏览器访问 `http://<公网IP>` 验证功能
4. 执行 `cleanup.sh`(会自动 `poweroff`)
5. 控制台「**制作镜像**」(见下)
6. 用新镜像创建一台测试实例,验证 firstboot 工作正常
7. 「**共享镜像**」给其他账号 / 申请「**镜像市场**」上架(见下)
## 制作镜像
**轻量应用服务器**:
1. 控制台 → 轻量应用服务器 → 选中已关机的实例
2. 「更多」→「**制作镜像**」
3. 镜像名建议带版本号:`weknora-v0.5.0-ubuntu2204`
4. 等待 5–30 分钟(取决于系统盘大小)
**云服务器 CVM**:
1. 控制台 → 云服务器 → 选中已关机的实例
2. 「更多」→「制作镜像」→ 选「整机镜像」
3. 同样建议带版本号
> 同一账号下,自定义镜像有数量配额(默认 20 个),可在控制台查看。
## 验证镜像
强烈建议用新镜像创建一台测试实例,至少验证:
- [ ] 能 SSH 进去(用控制台的默认密码 / 你导入的 key)
- [ ] `systemctl status weknora-firstboot` 显示已成功执行(或已 disable + 文件被删)
- [ ] `cat /root/weknora-credentials.txt` 里有随机密码
- [ ] 浏览器打开公网 IP 能访问 WeKnora,能注册管理员
- [ ] `docker compose -f /opt/WeKnora/docker-compose.yml ps` 全部 healthy
- [ ] `cat /opt/WeKnora/.cloud-image-meta` 显示正确的版本
## 共享给其他用户
按「覆盖范围」递增有 3 种方式:
### 方式 A:跨账号共享(私下分享)
控制台 → 自定义镜像 → 选中镜像 → 「**共享**」→ 输入对方腾讯云账号 ID(UIN)。
- 对方在自己的「共享镜像」列表能看到,可直接基于它创建实例
- **限制**:必须同地域;对方账号必须已开通对应产品(Lighthouse / CVM)
- 适合小范围、合作伙伴、内测用户
### 方式 B:跨地域使用
Lighthouse 的镜像可以「共享给 CVM」,转成 CVM 自定义镜像后即可:
- 跨地域复制
- 导出为 `qcow2` 文件下载到本地(更通用,可用于 KVM / 其他云)
### 方式 C:通过腾讯云市场上架镜像商品(公开一键部署)
这是真正「任何用户都能在云市场搜到并一键购买/部署」的形态。流程比较重,适合长期运营。
参考文档(请以官方为准):
- [云市场 - 镜像服务上架流程](https://cloud.tencent.com/document/product/306/3019)
- [云市场 - 镜像商品制作说明](https://cloud.tencent.com/document/product/306/30128)
- [Lighthouse - 应用镜像使用说明](https://cloud.tencent.com/document/product/1207/72665)
- [Lighthouse - 管理镜像(操作指南)](https://cloud.tencent.com/document/product/1207/63263)
大致步骤:
1. 登录 [腾讯云市场服务商管理控制台](https://console.cloud.tencent.com/serviceprovider),注册成为服务商
2. 「商品管理 → 商品列表 → 新建商品」,接入类型选「**镜像**」
3. 选择已制作好的自定义镜像(即上面方式 A/B 制作的那份)
4. **完成主机安全(专业版)检测**——这是镜像上架的硬性前置条件,需要自付 CVM + 主机安全专业版费用,建议用按量付费跑完即释放
5. 填写商品名称、版本、亮点、详情、使用指南(必传 PDF/Word/PPT/ZIP/RAR,≤2MB)、售后说明
6. 选择售卖方式(按量计费 / 按周期计费),按量计费目前仅支持 0 元规格
7. 提交审核(云市场运营人员审核约 7 个工作日)
8. 审核通过后,用户在云市场或购买 CVM 时即可选到你的镜像
> WeKnora 是腾讯系开源项目(`Tencent/WeKnora`),如果想推动官方上架,建议在 [WeKnora GitHub Issues](https://github.com/Tencent/WeKnora/issues) 联系维护团队,而不是个人单独申请。
## 注意事项
- 腾讯云的 cloud-init 兼容性良好,`cleanup.sh` 里的 `cloud-init clean` 能正常工作
- Lighthouse 的镜像默认大小限制为系统盘大小,请提前预估
- 若使用域名 + HTTPS,建议在 firstboot 之外通过 [acme.sh](https://acme.sh) / certbot 单独配置,不要把证书烤进镜像

View File

@ -1,176 +0,0 @@
# 代码瘦身审计与实施记录
审计日期:2026-09-16。基线:`d5efe5ced`。目标:保留现有功能,减少重复维护和理解成本。
## 扫描范围与口径
- 统计 Git 跟踪的源码物理行数,包含注释、空行;分开统计测试、生成文件、翻译与 i18n 辅助代码。行数用于定位,不作为质量评分。
- 对 `frontend/src` 的 TypeScript 和 Vue script 建立静态 import、re-export、字面量动态 import 依赖图,从 `main.ts`、`embed-main.ts` 两个实际入口遍历;额外检查模板名称、路由、全局组件注册、glob 和构建入口。
- 对 `internal` 下 Go 文件进行 AST 扫描,统计函数长度,寻找包内没有其他标识符引用的非导出自由函数;计入测试文件引用。另对重复代码块、相同函数体进行候选扫描并抽查调用方。
- 检查最近 200 个非 merge commit 的文件变更频率,结合重复程度和状态复杂度排序。
- `cli`、`client`、`docreader`、`mcp-server`、`packages`、`miniprogram` 做体量与结构初筛;本轮没有完成这些子项目的逐函数调用审计。
- 依赖图不是运行时覆盖证明;后端候选未经过所有平台、构建标签和集成测试验证,不等同于可直接删除的清单。
基线体量:
| 范围 | 生产源码行数 | 测试行数 |
| --- | ---: | ---: |
| `frontend/src` | 189,597 | 13,930 |
| `internal` | 319,317 | 181,900 |
前端另有 39,411 行翻译/i18n 辅助代码、693 行生成代码。整个仓库的测试和生成代码不应被当作优先削减对象。
## 第一批已实施
### 删除 10 个不可达组件
两个应用入口均无法到达以下组件;仓库内没有引用其文件路径的测试、脚本或注册入口。Vite 未配置组件自动注册,发现的资源 glob 用于 provider SVG,不会加载这些 Vue 文件。
| 文件(相对 `frontend/src`) | 行数 | 核查结果 |
| --- | ---: | --- |
| `views/settings/StorageEngineSettings.vue` | 1,687 | `Settings.vue` 实际导入 `StorageBackendSettings.vue`;同步修正了旧组件别名 |
| `views/organization/OrganizationEditorModal.vue` | 914 | 组织列表实际使用 `OrganizationSettingsModal.vue` |
| `views/settings/components/McpTestResultBody.vue` | 434 | 没有 import、注册或动态加载入口 |
| `components/SourceSwitcherDropdown.vue` | 163 | 没有 import、注册或动态加载入口 |
| `components/settings/SettingCard.vue` | 152 | 仅剩过时注释提及,注释一并清理 |
| `views/organization/JoinOrganization.vue` | 127 | `/join` 已重定向到组织列表,通过 `invite_code` 处理加入 |
| `components/SessionGroupByDropdown.vue` | 123 | 没有 import、注册或动态加载入口 |
| `views/knowledge/settings/KBIndexingStrategy.vue` | 109 | 没有 import、注册或动态加载入口 |
| `views/chat/components/sendMsg.vue` | 22 | 与仍在使用的 `sendMsg` 函数同名,但组件本身没有入口 |
| `views/platform/RoutePlaceholder.vue` | 7 | 没有路由或组件引用 |
共删除 3,738 行失效组件。它们原本不在应用入口依赖链中,因此这是源码维护收益,不能换算为构建产物缩小比例。
### 合并标签选择与创建逻辑
`TagEditDialog.vue`、`BatchTagDialog.vue` 共享新的 `composables/useKnowledgeTagSelection.ts`:
- 选择集合、名称映射、搜索过滤、切换与清空。
- 打开时恢复父组件选中值,重新打开时清空草稿。
- 创建标签的加载状态、结果处理、错误回调;手动输入沿用精确同名复用规则。
- 接口调用和通知通过参数提供,两个组件保留各自提交、关闭和 loading 行为。
两个弹窗的 template 和 style 与基线逐字节一致。新增 7 项行为测试,覆盖父数据更新、缺失标签 ID、搜索、创建响应、失败重试和实例隔离。
第一批生产源码净减少 **3,819 行**,已计入新增共享逻辑,未把新增测试和本文档计入生产源码。
## 第二批已实施:Skill 安装模型配置
基于第一批合并后的 `bfa7f0ed6`,将 `SandboxSkillsPanel.vue` 和 `SkillSettings.vue` 的重复配置逻辑收敛到 `composables/useSkillInstallerModel.ts`。生产源码净减少 40 行。
- 两个页面复用模型读取、最近聊天模型回退、保存、选择器错误通知和 loading 处理;每个实例仍保持独立状态。
- 保存只替换配置中的 `model_id`,保留现有 Agent 元数据与其他配置;读取失败、返回缺少 data、localStorage 不可用时沿用原有回退行为。
- 面板清空配置时调用 `resetInstallerModel`,继续清除已加载 Agent 与模型选择。此方法不增加异步请求取消语义。
- 页面继续控制何时加载、何时安装以及安装前的保存。进度订阅、安装/卸载流程、模板和样式未修改。
- 新增 10 项行为测试,覆盖优先级、回退、配置保留、响应缺省、保存失败重试、错误传播与实例隔离。
- `scripts/verify_frontend_pr.sh` 通过:917 项前端测试、类型检查和生产构建。两个页面的 template/style 与本批基线逐字节一致。未做浏览器视觉验收;未修改或测试后端。
## 第三批已实施:Skill 安装进度订阅
基于第二批合并后的 `5bcc43d72`,面板改为复用 `useConfigSkillInstallProgress`,统一 SSE 请求、配置/Skill 标识、连接去重、取消和完成事件处理。
- 目录页继续只保留所跟踪任务的进度;面板通过 `retainProgress` 保留完成事件与卸载失败原因,显式重试时清空。面板的百分比显示规则和卸载初始进度保持不变。
- 连接回调和 Promise 清理检查当前连接身份,避免旧事件、旧请求拒绝或结束回调覆盖/取消替代连接。正常 EOF 也释放订阅标记,允许后续轮询重新连接。
- 配置切换立即停止原订阅和轮询;面板读取、重试、停止和卸载请求的后续处理检查面板代次,避免迟到结果在另一配置或卸载后重新订阅。
- 新增 11 项行为测试,包含真实面板 setup 的配置切换、卸载失败展示、相同 Skill ID 重试、异步请求迟到和卸载清理;替换原有一项订阅源码正则断言。
- `scripts/verify_frontend_pr.sh` 通过:927 项前端测试、类型检查和生产构建。面板 template/style 与本批基线逐字节一致;未做浏览器视觉验收,未修改或测试后端。
## 第四批已实施:聊天引用浮层
基于第三批合入并同步后的 `42e616398`,`useChatCitationPopover` 与 `useEmbedCitationPopover` 改为复用 `useCitationPopover`。计入新增共享实现后,生产源码净减少 174 行。
- 统一浮层状态、定位、悬停延迟、关闭计时、引用抽屉和事件绑定;两个入口保留 API 选择、缓存作用域和错误展示策略。独立嵌入入口即使凭证为空,也继续只调用嵌入接口。
- 保留主聊天的会话缓存、嵌入的 channel/token 缓存隔离、主聊天滚动/缩放关闭逻辑、嵌入 Wiki 点击拦截,以及两种入口原有的悬停引用 ID 解析差异。
- 绑定对象单独记录,节点替换时移除旧节点监听;根节点、作用域或浮层目标变化后,迟到请求不会覆盖当前内容或写回缓存。卸载时清理监听和计时器。
- 嵌入消息组件直接使用共享关闭计时器,修复触发区与浮层之间无法取消彼此关闭任务的问题;相同节点的流式内容更新不会重置浮层。
- 新增 15 项真实 composable 行为测试,覆盖两个入口、接口路由、缓存、引用抽屉、请求竞争、计时和 Vue 挂载/卸载生命周期。
- `scripts/verify_frontend_pr.sh` 通过:948 项测试通过,1 项原有浏览器场景测试跳过,类型检查和生产构建通过。嵌入消息 template/style 与本批基线逐字节一致;未做浏览器视觉验收,未修改或测试后端。
## 第五批已实施:Go 未引用私有函数
基于第四批合入后的 `d645334d0`,逐包核实原有 16 个候选,全部确认无调用;同时删除仅被候选使用的 `collectTableAliases` 与 `escapeDoubleQuotes`。共移除 18 个私有函数和 3 个失效 import,生产 Go 源码净减少 235 行。
- 使用 Go AST 检查候选所属 12 个包目录中的 894 个 Go 文件,包括测试、带构建标签和平台后缀的源码;删除集合以外没有对应标识符引用。全仓搜索同时检查文档、脚本和特殊链接引用。
- 对修改的生产 Go 文件逐函数比较:453 个保留函数的签名与函数体完全一致。Qdrant 的 `tokenizeQuery`、Agent 工具包的 `formatFileSize`、JSON 解析包的 `formatValue` 等同名活跃实现继续保留。
- 更新分块配置相关注释和开发文档,指向仍在使用的 `buildSplitterConfigFromChunking` / `NormalizeSplitterConfig`;迁移历史注释保留旧名称。
- 13 个受影响包执行 `go test -count=1`:12 个包通过,微信适配包无测试文件但编译通过;3,529 项顶层测试通过、1 项原有测试跳过,计入子测试为 5,274 项通过。跳过项为需要可替换连接探测或真实后端的向量存储创建测试。
- `integration,e2b_integration,docker_integration` 标签下的 sandbox/tools 测试代码编译通过,未执行需要外部服务的集成测试。未修改前端,未运行前端或浏览器检查。
- 本批只删除无调用代码,复用现有包测试和编译检查,没有添加仅断言函数不存在的测试。
- 推送检查暴露新合入的 fork 测试未隔离 Git hook 环境:继承的 `GIT_DIR` 等变量使临时仓库操作指向当前仓库。测试辅助函数现清除继承的 `GIT_*` 变量;真实仓库测试主动注入指向临时路径的仓库变量,验证旧实现失败、修复后通过。该测试修复单独提交,不改变生产逻辑。
## 第六批已实施:外部来源文件名清理
基于第五批合入后的 `10973ed32`,IMA、语雀、RSS 复用 `datasource.SanitizeFileName`,统一无效标点替换、空标题回退和 200 字节 UTF-8 边界截断。计入新增共享实现后,生产 Go 源码净减少 49 行。
- IMA 的媒体与笔记路径、语雀文档直接调用共享函数;RSS 仅保留换行/制表符转空格和首尾空白清理,再调用共享函数。
- 保留原有扩展名拼接、源标题、空白、控制字符和无效 UTF-8 输入处理行为。飞书的扩展名保留、钉钉的控制字符/尾部标点清理、Confluence 的按字符截断规则不同,本批未合并。
- 将两份旧 helper 测试收敛到共享函数测试,补充 16 个边界用例;在实际连接器读取/组装路径新增 15 个用例,覆盖 IMA 两类内容、语雀和 RSS 的最终文件名。
- 用重构前的三个实现对 30,000 组确定性生成输入执行差异校验,结果一致;输入包含中文、emoji、空白、非法字节和截断边界。临时对比代码未留在仓库,避免长期维护旧实现副本。
- 4 个受影响包测试通过:104 项顶层测试,包含既有同步、游标和错误处理测试。未修改前端,未运行浏览器检查或真实外部来源服务测试。
## 第七批已实施:知识库标签筛选与遗留样式
基于第六批合入后的 `820a14daf`,文档页与 FAQ 页复用 `KnowledgeTagFilter`,统一筛选浮层、多选、清空、搜索和管理入口。计入新增组件后,生产前端源码净减少 1,061 行。
- 页面继续负责标签 API、分页、搜索防抖、持久化选择和列表刷新;共享组件只负责展示与交互,保留文档数量/FAQ 分块数量、清空占位文案和管理权限差异。
- 删除两份无效的已选标签补齐逻辑:缺失项原本仍从同一个标签列表生成的映射中查找,因此不可能补齐;未加载的选中 ID 仍保留在选择状态中。
- 删除 `KnowledgeBase.vue` 中 682 行失效 scoped 样式,包括已移入子组件的卡片菜单、标签、悬浮详情和旧上传区域样式。保留仍在当前模板使用的骨架卡片、FAQ 容器和响应式布局。
- 对迁移前后编译后的 CSS 做临时声明对比,检查 2,196 项声明,确认保留的父组件规则与两种筛选界面的原有属性值一致;这不替代浏览器视觉验收。
- 新增 9 项真实 Vue 组件行为测试,覆盖两种计数、多选/清空、搜索、加载/空态、分页、管理权限及父级选择更新。
- `scripts/verify_frontend_pr.sh` 通过:957 项测试通过,1 项原有测试跳过,类型检查与生产构建通过。未做浏览器视觉验收;未修改后端。
## 后续优先级
| 优先级 | 证据 | 建议边界 | 验证重点 |
| --- | --- | --- | --- |
| P2 | `AgentEditorModal.vue` 6,756 行,其中 script 3,023 行;近期变更 9 次 | 按提示词编辑、知识库选择、工具配置分离状态和表单序列化责任 | 编辑回填、模式切换、保存 payload 保持兼容 |
| P2 | `WikiBrowser.vue` 6,592 行,其中 script 4,086 行;`FAQEntryManager.vue` 5,650 行,其中 style 2,780 行 | 分开文档导航/编辑状态、批量动作与可复用展示区域 | 页面切换后的异步结果、选中项、保存与批量操作 |
| P2 | `knowledge_process.go` 4,091 行;`processChunks` 470 行、`ProcessDocument` 441 行 | 先划分分块入库、摘要、问题生成、重解析阶段的输入与输出,再抽函数 | 任务归属、取消、失败回写、重试与索引状态 |
| P2 | `wiki_ingest_batch.go` 的 `ProcessWikiIngest` 718 行、`mapOneDocument` 446 行、`reduceSlugUpdates` 422 行 | 分离任务协调、单文档处理、页面归并;保留现有检查点 | 删除 KB、重复投递、部分失败、并发归并 |
| P2 | `internal/im/service.go` 3,493 行,`handleMessageStream` 450 行 | 按通道生命周期、请求准备、流式回复拆责任 | completion/error 顺序、取消、最终持久化与平台发送失败 |
这些条目的行号、长度和变更频率是本次基线快照。仅按长度分文件不会自动降低复杂度,验收应检查状态归属和业务规则是否集中。
### 后端重复的具体判断
- Qdrant 与 Weaviate 的 `tokenizeQuery` 函数体相同,但只有 Qdrant 的关键字检索调用它;Weaviate 使用 `WithQuery(params.Query)`。第五批已删除 Weaviate 的失效函数,保留 Qdrant 实现。
- 第六批已合并 IMA、语雀、RSS 的文件名标点替换和 UTF-8 截断逻辑;RSS 的空白预处理保留在连接器内。飞书、钉钉、Confluence 的其他规则继续独立维护。
- Milvus/Qdrant/Weaviate 的结果映射体相似,但接收不同后端类型。当前各约 17 行,为此引入通用接口或泛型转换层未必减少维护成本。
- 终端和桌面 WebSocket ticket handler 重复检查会话、用户、租户和 token,但签发方式不同。后续可共享前置身份校验,保留 ticket 和连接生命周期各自的契约。
- 资源权限已经有 `internal/application/access`;继续沿已有授权边界收敛,避免新建与其并行的权限工具层。
### 第五批已核实并删除的 Go 私有自由函数
初次扫描的 16 个候选和 2 个仅被候选调用的辅助函数已清理:
| 文件(相对 `internal`) | 函数 |
| --- | --- |
| `application/repository/retriever/weaviate/repository.go` | `tokenizeQuery` |
| `im/wechat/crypto.go` | `encryptAES128ECB` |
| `application/repository/retriever/milvus/filter.go` | `formatValue`、`escapeDoubleQuotes` |
| `agent/tools/todo_write.go` | `getStringArrayField`、`getStringField` |
| `agent/prompts.go` | `formatFileSize` |
| `utils/inject.go` | `extractTableAliasMap`、`collectTableAliases` |
| `application/service/wiki_ingest_dedup.go` | `countEntityConceptPages` |
| `agent/tools/sandbox_ls.go` | `relativeSkillFileFromImagePath` |
| `infrastructure/docparser/json_converter.go` | `indentJSON` |
| `handler/knowledge.go` | `mimeTypeByExt` |
| `application/service/tenant_skill_source.go` | `normalizeFetchedSkillArchive` |
| `sandbox/gateway_transport.go` | `newGatewayDataTransport` |
| `application/service/knowledge_process.go` | `buildSplitterConfig` |
| `im/service.go` | `imLocalStorageBaseDir` |
| `handler/session/helpers.go` | `getRequestID` |
## 测试维护与验证结果
抽查发现,标签弹窗、安装进度的部分测试通过正则检查源码文本;IM 部分流式测试使用镜像状态结构,同时也存在直接调用生产路径的退出/投递测试。重构时应逐步补真实行为覆盖,不应只调整正则或同时修改两份镜像逻辑来获得通过。
第一批验证:
- 修改前 `npm run type-check` 通过,作为类型检查基线。
- 11 项定向测试通过,其中 7 项是新增行为测试。
- `scripts/verify_frontend_pr.sh` 完整通过:907 项测试、`vue-tsc --build`、Vite 生产构建。
- 构建仍报告大 chunk 提示;本轮未以 bundle 体积为目标,也没有测量构建前后的体积差异。
- 未修改后端,未运行后端测试;未做浏览器视觉验收。
下一批优先检查终端与桌面 WebSocket ticket 的重复身份校验,沿现有授权边界确定共享范围。涉及聊天、任务重试、权限或共享状态的改动应单独成批,以可验证的行为等价为边界。

View File

@ -1,123 +0,0 @@
# OpenSearch k-NN driver — local integration test
This guide brings up a single-node OpenSearch cluster and exercises the
OpenSearch retrieve engine end to end. The driver lives in
`internal/application/repository/retriever/opensearch/`.
## 1. Start a dev cluster
```bash
docker compose -f docker-compose.dev.yml --profile opensearch up -d
```
This starts:
- `opensearch` on `http://localhost:9200` — single-node, **security plugin
disabled** (plain HTTP, no auth/TLS). The image bundles the
`opensearch-knn` plugin.
> **OpenSearch Dashboards is optional** and lives in a separate
> `opensearch-ui` profile, so it is *not* started by `--profile opensearch`.
> The whole integration test below is curl-verifiable against `:9200`. If you
> want the web UI (Dev Tools console / visual index inspection), start it on
> demand:
>
> ```bash
> docker compose -f docker-compose.dev.yml --profile opensearch-ui up -d
> # opensearch-dashboards on http://localhost:5601 (depends_on pulls the cluster in)
> ```
Verify:
```bash
curl -s localhost:9200 | jq '.version.distribution, .version.number'
# "opensearch" "3.3.2"
curl -s 'localhost:9200/_cat/plugins?format=json' | jq -r '.[].component' | grep opensearch-knn
```
> Production clusters must enable the security plugin (TLS + auth). The dev
> profile disables it only to keep local setup trivial. When connecting to a
> secured cluster, set `username` / `password` and — for self-signed certs in
> dev only — `insecure_skip_verify=true`.
## 2. Register the store
### Option A — DB store (UI / API)
> **SSRF whitelist (dev).** `CreateStore` and the raw connection test validate
> the user-supplied `addr` against the SSRF policy. `http://localhost:9200`
> is rejected by default — `localhost` is a restricted hostname and `9200` is
> a blocked port. When the backend runs on the host (`go run`), add `localhost`
> to the whitelist in your `.env` before registering:
>
> ```bash
> SSRF_WHITELIST=localhost
> ```
>
> The containerised compose deployment whitelists the bundled vector-store
> service names automatically (`SSRF_WHITELIST_EXTRA`), so this step is
> dev-only. The env-store path (Option B) is not affected.
`POST /api/v1/vector-stores`:
```json
{
"name": "opensearch-local",
"engine_type": "opensearch",
"connection_config": { "addr": "http://localhost:9200" },
"index_config": {
"number_of_shards": 1,
"number_of_replicas": 0,
"hnsw_m": 16,
"hnsw_ef_construction": 100,
"knn_engine": "lucene"
}
}
```
`CreateStore` runs the connection probe (version + k-NN plugin) before
persisting; a bad address / unsupported version / missing plugin is rejected
with `400`.
### Option B — env store
```bash
export RETRIEVE_DRIVER=opensearch
export OPENSEARCH_ADDR=http://localhost:9200
# export OPENSEARCH_USERNAME / OPENSEARCH_PASSWORD for a secured cluster
# export OPENSEARCH_INSECURE_SKIP_VERIFY=true # self-signed dev TLS only
```
## 3. Single-node note (important)
On a single-node cluster, any index created with `number_of_replicas >= 1`
leaves its replica shard **unassigned**, so the index health goes **Yellow**.
Yellow does **not** block reads or writes — it is safe for local testing — but
to keep the cluster Green set **`number_of_replicas: 0`** at store
registration (as in the Option A example above). The driver default is `1`
(it assumes a ≥2-node cluster).
## 4. Exercise the flow
1. Bind a knowledge base to the store and ingest a few documents.
2. Confirm the per-dimension index appears:
`curl -s 'localhost:9200/_cat/indices?v' | grep weknora`
(e.g. `weknora_<storeprefix>_768` + alias, plus `weknora_<storeprefix>_keywords`).
3. Run a retrieval query against the bound KB and confirm hits come back.
4. Copy the KB to another KB and confirm the docs are reindexed
(`opensearch.reindex_executed` audit event).
5. Toggle chunk enabled-status / tag and confirm `_update_by_query` applies it.
## 5. Tear down
```bash
docker compose -f docker-compose.dev.yml --profile opensearch down -v
```
## Scope notes
- Large-batch async reindex / delete (task polling) is a follow-up; the sync
paths handle typical KB sizes (pagination is bounded by `max_result_window`,
default 10000).
- Native `hybrid` query + search pipeline is out of scope — fusion stays at the
service layer (RRF).

View File

@ -1,180 +0,0 @@
# Embed 安全模式
> **一句话**:长期密钥(发布 Token `em_…`)只放在**你自己的服务器**;访客浏览器里只有 30 分钟有效的短时令牌(`ems_…`)。
## 为什么要用?
| 方式 | 发布 Token 在哪 | 风险 |
|------|-----------------|------|
| iframe / 普通 Widget | 写在页面 HTML 或 URL hash 里 | 任何人「查看源代码」就能复制,等于公开密钥 |
| **安全模式 Widget** | 仅环境变量 / 密钥管理,在服务端 | 浏览器拿不到长期密钥;还可先校验访客是否登录 |
生产环境对外嵌入,**应优先用安全模式**。
## 两种 Token
| 名称 | 格式 | 谁持有 | 用途 |
|------|------|--------|------|
| 发布 Token | `em_…` | 仅你的服务端 | 向 WeKnora 换取短时令牌;在管理端「渠道密钥」查看 |
| 会话 Token | `ems_…` | 访客浏览器(iframe 内) | 调聊天、上传等 embed API;约 30 分钟过期,Widget 会自动刷新 |
## 工作流程
```
访客浏览器 你的后端(shop 的服务器) WeKnora
│ │ │
│ 1. 加载 Widget │ │
│ data-token-endpoint │ │
│ (不含 em_) │ │
│─────────────────────────────►│ │
│ │ 2. 校验访客已登录(可选) │
│ │ 3. POST .../embed/:id/exchange │
│ │ Authorization: Embed em_… │
│ │─────────────────────────────►│
│ │◄──── session_token (ems_…) ───│
│◄── 4. { token, expiresIn } ──│ │
│ 5. iframe 用 ems_ 聊天 │ │
```
对应管理端「嵌入渠道 → 安全模式」里的两段代码:
1. **页面脚本**:`data-token-endpoint="https://你的域名/weknora/embed-token"`(没有 `data-token`)
2. **服务端接口**:用发布 Token 调 exchange,把 `ems_…` 返回给前端
## 集成步骤
### 第 1 步:在 WeKnora 创建渠道
- 记下 **渠道 ID** 和 **发布 Token**(`em_…`)
- 配置域名白名单(见下)
- 配置分钟 / 日限流
### 第 2 步:部署取令牌接口
在你的业务后端新增一个 HTTP 接口(路径自定),要求:
**入参**:浏览器 GET 请求(Widget 会 `fetch` 这个地址)
**你必须做**:
- 校验调用方是合法访客(Session Cookie、JWT 等),未登录返回 `401`
- 用发布 Token 调 WeKnora exchange
- 成功时返回 JSON:`{ "token": "<ems_…>", "expiresIn": 1800 }`
**调 exchange 的约定**:
```http
POST https://<weknora-host>/api/v1/embed/<channel_id>/exchange
Authorization: Embed <发布 Token em_…>
Origin: https://<你的业务站点> ← 须与渠道白名单一致,否则 403
```
> 服务端 `fetch` 默认不带 `Origin`,需要**手动设置**与白名单匹配的 `Origin` 头。
### 第 3 步:粘贴安全模式 Widget 代码
把 `data-token-endpoint` 改成上一步的真实 URL。完整示例在管理端「安全模式」Tab 可复制。
## 服务端示例
以下 `<WEKNORA_HOST>`、`<CHANNEL_ID>` 替换为实际值;发布 Token 放环境变量 `WEKNORA_PUBLISH_TOKEN`,**不要**写进前端。
### Node.js(Express)
```javascript
const WEKNORA_BASE = 'https://<WEKNORA_HOST>';
const CHANNEL_ID = '<CHANNEL_ID>';
const ALLOWED_ORIGIN = 'https://shop.example.com'; // 与渠道白名单一致
app.get('/weknora/embed-token', async (req, res) => {
const hasSession = Boolean(req.cookies?.session_id);
const auth = req.headers.authorization || '';
if (!hasSession && !auth.startsWith('Bearer ')) {
return res.status(401).json({ error: 'unauthorized' });
}
const r = await fetch(`${WEKNORA_BASE}/api/v1/embed/${CHANNEL_ID}/exchange`, {
method: 'POST',
headers: {
Authorization: 'Embed ' + process.env.WEKNORA_PUBLISH_TOKEN,
Origin: ALLOWED_ORIGIN,
},
});
const body = await r.json();
if (!body?.data?.session_token) {
return res.status(502).json({ error: 'mint failed' });
}
res.json({ token: body.data.session_token, expiresIn: body.data.expires_in });
});
```
### Go(net/http)
```go
func embedTokenHandler(w http.ResponseWriter, r *http.Request) {
if r.Header.Get("Authorization") == "" && r.Header.Get("Cookie") == "" {
http.Error(w, `{"error":"unauthorized"}`, http.StatusUnauthorized)
return
}
req, _ := http.NewRequest(http.MethodPost,
"https://<WEKNORA_HOST>/api/v1/embed/<CHANNEL_ID>/exchange", nil)
req.Header.Set("Authorization", "Embed "+os.Getenv("WEKNORA_PUBLISH_TOKEN"))
req.Header.Set("Origin", "https://shop.example.com") // 与渠道白名单一致
resp, err := http.DefaultClient.Do(req)
if err != nil || resp.StatusCode >= 300 {
http.Error(w, `{"error":"mint failed"}`, http.StatusBadGateway)
return
}
defer resp.Body.Close()
var body struct {
Data struct {
SessionToken string `json:"session_token"`
ExpiresIn int `json:"expires_in"`
} `json:"data"`
}
if json.NewDecoder(resp.Body).Decode(&body) != nil || body.Data.SessionToken == "" {
http.Error(w, `{"error":"mint failed"}`, http.StatusBadGateway)
return
}
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(map[string]any{
"token": body.Data.SessionToken, "expiresIn": body.Data.ExpiresIn,
})
}
```
管理端「安全模式 → 服务端示例」Tab 会按当前渠道 ID 生成带真实 URL 的片段。
## 域名白名单怎么填?
A 网站(例如 `https://shop.example.com`)嵌入 B 上的 WeKnora 时,只需填写 A。iframe 的正常同源 API 调用不要求把 B 额外加入白名单。
业务后端调用 exchange 时,继续发送 `Origin: https://shop.example.com`,与实际宿主和渠道白名单一致。这里声明的是业务来源,不是后端机器的部署地址。完整部署及升级要求见[独立子域配置](./embed-subdomain.md#3-域名白名单填什么)。
开发环境可临时使用 `*`;**生产环境禁止 `*`**。
## 上线检查
- [ ] 发布 Token 仅通过环境变量 / 密钥服务注入,未提交到 Git、未打进前端静态包
- [ ] 取令牌接口校验访客身份
- [ ] 全链路 HTTPS
- [ ] 白名单已包含宿主网站 A,exchange 使用同一 Origin
- [ ] 已配置限流;敏感智能体不要用普通模式把 Token 暴露在网页里
- [ ] 轮换发布 Token 后,同步更新服务端环境变量
## 常见问题
| 现象 | 原因与处理 |
|------|------------|
| exchange 返回 **401** / `publish token required` | 发布 Token 错误、已轮换,或误用了 `ems_` 会话 Token |
| exchange 或聊天 API 返回 **403** `origin not allowed` | 服务端 exchange 需手动加白名单中的业务 `Origin`;同源聊天失败时检查代理是否保留 Host(含端口)、协议和 `Sec-Fetch-Site` |
| iframe 被 **frame-ancestors** 拒绝 | 将宿主网站 A 加入渠道白名单,确认所有祖先页面均被允许;旧渠道只填 B 的配置需要更新 |
| iframe 一直「等待 Token」 | `token-endpoint` 未返回 `{ token, expiresIn }`,或 CORS 未允许 Widget 所在源站访问你的接口 |
| 取令牌接口 **502** `mint failed` | WeKnora 不可达、渠道已停用,或 exchange 响应格式不对 |
| 访客随便就能聊 | 取令牌接口未做登录校验——在 exchange 前加 Session / JWT 检查 |
## 相关
- 可选:embed 独立子域 → [embed-subdomain.md](./embed-subdomain.md)
- Widget SDK 注释:`frontend/public/weknora-widget.js`
- 代码生成:`frontend/src/api/embed/index.ts`

View File

@ -1,108 +0,0 @@
# Embed 独立子域部署(可选)
> **一句话**:把聊天页面单独放到 `embed.example.com`,与主站 `app.example.com` 分开。**大多数部署不需要这一步**——主站和 embed 同域就能用。只有对安全隔离有明确要求时再考虑。
## 先搞清楚三个「网站」
嵌入聊天时,实际涉及三类地址(可以相同,也可以不同):
| 角色 | 举例 | 干什么 |
|------|------|--------|
| **A. 业务站点(宿主)** | `https://shop.example.com` | 你的商城 / 文档站;在这里粘贴 Widget 脚本或 iframe |
| **B. Embed 页面源站** | `https://app.example.com` 或 `https://embed.example.com` | 提供 `embed.html`、`weknora-widget.js`;聊天 iframe 加载自这里 |
| **C. WeKnora API** | 通常与 B 同域,如 `https://app.example.com/api` | 后端接口 |
**默认(推荐入门)**:B 和主站管理后台都在 `https://app.example.com`,A 可以是任意第三方域名。
```
shop.example.com app.example.com
┌─────────────────┐ ┌──────────────────────────┐
│ <script src= │ │ /weknora-widget.js │
│ app.../widget> │──────►│ /embed/:channelId │
│ │ │ /api/v1/embed/... │
│ (浮窗 iframe) │◄──────│ │
└─────────────────┘ └──────────────────────────┘
```
**独立子域(进阶)**:把 B 拆到 `https://embed.example.com`,主站 `https://app.example.com` 只留管理后台。
```
shop.example.com embed.example.com app.example.com
┌─────────────────┐ ┌──────────────────┐ ┌─────────────┐
│ Widget 脚本 │──────►│ embed 静态页+API │ │ 管理后台 │
│ iframe 指向 embed│◄──────│ (无 index SPA) │ │ (可选分离) │
└─────────────────┘ └──────────────────┘ └─────────────┘
```
## 什么时候需要独立子域?
| 场景 | 是否需要 |
|------|----------|
| 内测、PoC、单域 Docker 部署 | **不需要** |
| 主站 `X-Frame-Options: SAMEORIGIN`,但要把聊天嵌到第三方页面 | **不需要**(被嵌的是 `/embed/*` 页面,不是管理后台 SPA) |
| 希望 embed 站点不携带主站登录 Cookie、缩小暴露面 | **可以考虑** |
| 希望 CDN / WAF 对 embed 流量单独限速、缓存 | **可以考虑** |
| 合规要求「对外嵌入」与「内部管理」必须不同源 | **需要** |
本地开发:`http://localhost:5173` 同域即可,Vite 已把 `/embed/*` 指到 `embed.html`,**不必**配子域。
## 怎么配置
### 1. 告诉管理端「embed 页面公网地址」
管理端生成 iframe / Widget 代码时,需要知道 B 的地址。在 `frontend/public/config.js`(或 Docker 启动脚本生成的配置)里设置:
```javascript
window.__RUNTIME_CONFIG__ = {
// embed 页面与 widget.js 的源站;留空则使用当前浏览器所在域名
EMBED_BASE_URL: 'https://embed.example.com',
MAX_FILE_SIZE_MB: 50,
};
```
构建期也可通过环境变量注入:`VITE_EMBED_BASE_URL=https://embed.example.com`(可选)。
### 2. Nginx:单独 server 块只服务 embed
`frontend/nginx.conf` 顶部有注释掉的示例。要点:
- `server_name embed.example.com`
- 只暴露:`/embed/*` → `embed.html`,`/weknora-widget.js`,`/assets/*`
- `/api/` 反代到 WeKnora 后端(与主站相同后端即可)
- **不要**在这个 server 上挂完整 `index.html` 管理 SPA(减少攻击面)
主站 `server` 块可继续 `X-Frame-Options: SAMEORIGIN`,不影响第三方嵌 embed 子域的 iframe。
### 3. 域名白名单填什么?
填写**允许嵌入的宿主网站 Origin**:A 网站嵌入 B 上的 WeKnora,就填 A,例如 `https://shop.example.com`,不需要为了聊天 API 再添加 B。
- 每行一个完整 Origin(协议、域名、可选端口),不能带业务路径、查询参数或用户名。允许末尾 `/`,匹配时会规范化。
- `*.example.com` 允许 HTTP(S) 子域名及其端口,不包含根域 `example.com`;`*.example.com:8443` 可限定端口。
- 嵌入 HTML 的 `Content-Security-Policy: frame-ancestors` 由渠道白名单生成,由浏览器检查所有祖先页面;同源管理端预览也允许。
- iframe 内 API 请求来自 B,正常同源请求不再要求 B 出现在宿主白名单。安全模式下业务后端换取令牌仍需手动发送 `Origin: https://shop.example.com`,与白名单一致。
- 空白名单、无效或停用渠道拒绝加载;不要用 `*` 作为生产配置。
**部署要求**:标准前端 Nginx 的 `/embed/` 必须保留 `auth_request`、内部 `/_embed-frame-policy` 和 CSP 响应头配置。它通过后端 `/api/v1/embed-frame-policy` 获取策略,再直接返回 `embed.html`。后端不可用时拒绝返回嵌入页面。Lite 在 Go 静态页面响应上设置同一策略。自定义网关/CDN 不得移除或缓存该响应头;HTTPS 代理应保留原始 Host(含端口)、协议和 `Sec-Fetch-Site`。
**升级已有渠道**:过去仅填写 WeKnora 的 B 地址的渠道,需改为实际宿主 A;同时更新前端 Nginx 和后端。不会自动猜测或放行未知宿主。安全模式的业务来源配置保持一致。
白名单限制浏览器嵌入,不替代用户认证。直接打开链接或非浏览器客户端仍由 token、会话签名和限流保护;需控制访客身份时使用安全模式。
## Widget 跨域与 sandbox
当宿主站 A 与 embed 源站 B **不同域**时,`weknora-widget.js` 会自动给内部 iframe 加上 `sandbox`(也可手动 `data-sandbox="true"`)。
A 与 B 同域时保持默认即可,无需 `data-sandbox`。
## 检查清单
- [ ] `EMBED_BASE_URL` 与真实访问地址一致(含 `https`)
- [ ] embed 子域能打开 `/embed/<渠道ID>` 和 `/weknora-widget.js`
- [ ] embed 子域 `/api/` 能连到后端
- [ ] 渠道白名单包含实际宿主网站 A;安全模式 exchange 声明同一业务 Origin
- [ ] 管理端复制的 snippet 里 URL 已变为 embed 子域
## 相关文档
- 发布 Token 不落浏览器:[embed-secure-mode.md](./embed-secure-mode.md)

View File

@ -1,83 +0,0 @@
# MCP 配置、持久目录与按需调用
## 设置页面
MCP 配置分两步,使用现有 SettingDrawer,步骤导航沿用沙箱的圆形编号与连接线,分组使用标题和细分隔线。
1. **连接配置**:名称、启用状态、传输协议、URL、请求头、认证及超时。保存后进入第二步;OAuth 授权仍按用户独立进行。
2. **工具与用途说明**:编辑用途摘要和使用说明。进入本步时若还没有目录,会自动连接并拉取 Tools;已保存的目录直接展示,只有点刷新才会再次访问 MCP Server。连接已变更的旧目录不会自动覆盖,需手动刷新。工具启用和审批开关即时保存。
编辑时无需为展示 Tools 再次连接上游。首次使用旧服务需要同步一次:此前数据库只有工具的启用/审批设置,没有完整工具目录可以迁移。
## 存储及字段来源
迁移 `000092_mcp_metadata` 新增服务使用说明及持久目录表。
| 数据 | 存储位置 | 来源与更新方式 |
|---|---|---|
| 服务名称、用途摘要 | `mcp_services.name / description` | 人工配置 |
| 使用说明 | `mcp_services.usage_instructions` | 人工配置;刷新不会覆盖 |
| 原始服务说明 | `mcp_metadata.instructions` | `initialize.result.instructions` |
| 服务端名称、版本及简介 | `mcp_metadata.server_name / server_version / server_description` | `initialize.result.serverInfo` |
| 工具名称、完整描述、完整 schema | `mcp_metadata.tools` JSONB | 完整分页读取 `tools/list` 后原子保存 |
| 同步时间、连接指纹 | `mcp_metadata.synced_at / config_fingerprint` | 后端生成;指纹不返回前端 |
| 工具启用、审批策略 | 原有 `mcp_tool_approvals` | 单独保存;同步不会覆盖 |
目录按 `(tenant_id, service_id, principal)` 隔离。非 OAuth 服务在同一租户内共享一份快照;OAuth 服务使用有效授权主体的 StorageID,同一服务可以有多份用户目录,不回退读取其他用户的快照。主表的服务列表查询不会携带完整 Tools JSON。
连接指纹覆盖传输方式、URL、请求头、认证配置、stdio 配置和环境变量。密钥只参与指纹计算,不写入目录或模型上下文。修改用途文字不使目录失效;修改连接或认证配置后,旧目录仍可在管理页面查看,但标为 stale,不参与运行时工具加载。
刷新使用独立连接,30 秒超时;获取全部工具成功后才写库。失败保留原有快照,页面展示本次错误;不把不完整目录发布成成功结果。成功返回空列表则移除旧工具。刷新前后核对连接指纹,较早开始的慢刷新不能覆盖较新快照。现有客户端限制为 100 页、2,000 个工具及单个 schema 256 KiB;完整快照另有 8 MiB 上限,超限明确失败。
## API
- `GET /api/v1/mcp-services/:id/metadata`:只读库,未同步返回 `data:null`,旧连接的快照返回 `stale:true`;Viewer 及以上权限。
- `POST /api/v1/mcp-services/:id/metadata/refresh`:显式连接并同步。静态认证写入租户共享快照,需要 Admin(或具备 MCP 管理能力的 API key);OAuth 写入当前用户快照,Viewer 及以上可调用,以便对话内授权后落库。刷新失败对外返回笼统错误,不带回上游地址。
- 服务原有 POST / PUT 接收 `description` 和 `usage_instructions`。凭证继续走独立子资源,编辑说明不会覆盖密钥。
- 旧 `/test`、`/tools` 和 `/resources` API 保留原有行为;新分步页面不通过它们读取缓存。
## 模型暴露链路
**入库不等于全量发送给模型。** 默认使用普通函数调用实现应用层按需加载,不依赖 Responses 或 Anthropic 的原生 tool-search 协议。
1. `registerMCPTools` 筛选当前租户及 Agent 授权范围内的启用服务,安装受权限约束的目录。生产路径注入只读快照 loader;目录缺失时(升级后尚未同步)可在已授权连接上 live `tools/list` 并写入当前主体的快照。OAuth 服务在预加载阶段不会 live 连接(避免弹出授权窗);对话内工具执行上下文中才允许 live-fill。连接已变更的 stale 快照不会在预加载时 live-fill。模型调用 `list_tools` 且 `refresh=true` 时会重新拉取上游并尝试落库;设置页刷新对静态认证需要 Admin,OAuth 仍可由授权用户同步。
2. `PrepareMCPTools` 预读数据库快照,不连接上游。读取最多 8 路并发,初始等待窗口 1 秒,整体受请求取消及 30 秒超时约束。未就绪服务仍展示在来源目录中。
3. 首轮模型只看到两个入口 `discover_mcp_tools` / `call_mcp_tool`,以及服务级名称、用途说明和状态。来源摘要有 16 KiB 总预算:能放下时模型应直接 `list_tools` / `describe`,不要先 `list_servers`;超出时才提示通过 `list_servers` 分页枚举。每个工具的完整描述和 schema 不在首轮 tools 中。
4. 模型按服务 `list_tools` / `search`,再 `describe` 一个具体工具。`describe` 返回完整描述、schema、原始服务 instructions、人工使用说明、`function_name` 和 `tool_ref`,并记录本次 engine 已读取的定义版本。
5. 下一次模型请求前,`RefreshMCPTools` 把已 describe、或本会话历史里已经用过的工具发布为普通函数。新 engine 会从对话历史恢复 `mcp_*` 函数名和 `call_mcp_tool` 的 `tool_ref`,避免多轮必须重新 describe。也可继续用 `call_mcp_tool` 兼容代理调用。目录操作和后台读取线程不会在并行执行期间修改 registry。
6. 实际执行目标 MCP 工具时才建立所需连接。权限、审批、OAuth 等待、参数校验和结果处理继续走原有执行链。
没有 mention 也能看到所有获准服务;mention 只设置优先使用项,不缩小或扩大 Agent 配置的 `all / selected / none` 授权范围。
`PrepareMCPToolsDirect` 保留全量函数暴露的兼容路径,生产默认不使用。OpenAI 兼容和 Anthropic Messages 都支持上述普通函数的按需加载;Anthropic 适配器支持 tools、tool_use、并行 tool_result 和流式参数拼接。截断的参数流不会作为完整调用执行。
## 与 Codex 的对应和边界
对照 `openai/codex@2cbbf0c9b542a36a1c3284b5e804917635b6f666`:
- `codex-rs/codex-mcp/src/rmcp_client.rs`:初始化后读取工具目录,普通 MCP 的 namespace description 来自 `initialize.instructions`;Apps 使用 Connector 元数据。
- `codex-rs/core/src/mcp_tool_exposure.rs`:工具搜索启用时 Deferred,否则 Direct。
- `codex-rs/core/src/tools/handlers/tool_search_spec.rs`:首轮按来源去重展示名称及可选说明;world state 已声明来源时省略重复列表。
- `codex-rs/core/src/tools/handlers/mcp.rs` / `tool_search.rs`:逐工具元数据构建后台 BM25 索引,命中后加载完整工具定义。
本项目采用相同的“来源可感知、具体定义按需加载”原则,但当前检索是单服务名称/描述子串匹配,加分页枚举和精确 describe,不是 Codex 的原生 BM25 tool_search 协议。持久化管理目录也是本项目的服务端设计,不宣称照搬 Codex 的存储方式。
## 目录完整性、权限和历史
列表默认 20 项、最大 50 项。遵循 `next_cursor` 直到 `has_more=false`;列表摘要不提供可调用引用,必须 describe 完整定义。搜索为空时可以不带 query 枚举,工具可达性不依赖搜索排名。
当前 engine 的目录绑定租户、调用主体及有效 OAuth 主体。读取和执行重新检查服务配置、工具策略;缓存不缓存权限决策。新增到 Agent 授权范围外的服务不会自动进入当前目录。运行时 `list_tools(refresh:true)` 重新读取持久快照,上游同步由管理页面显式发起。
具体函数使用原始服务 ID 和工具名生成稳定哈希后缀,避免 Unicode、大小写、标点、超长名称清洗后冲突。调用引用绑定服务、原始工具名和 schema,旧 schema 被替换后无法沿用旧引用。新 engine 会根据会话历史恢复已用过的函数,无需再 describe 一次。
完整 JSON Schema 校验覆盖组合约束、额外属性、嵌套结构和本地引用。验证器不访问外部 URL 或文件。参数转换和审批后的修改也经过校验。定义结果超过预算会明确失败或整体替换为说明,不使用半截 JSON。
`ToolCall.Name / Args / ID / ProviderMetadata` 保留模型原始调用;`ToolCall.Target` 保存实际服务、工具名及内层参数,供界面和日志展示。工具图片、外部标识及内容项沿用现有处理,不改写成知识库身份。
服务端元数据是外部使用文档,不具有覆盖用户请求或权限策略的权威。函数说明带 external 前缀;目录结果的 notice 和执行结果的 untrusted 标记保留。人工说明与服务端原文分别保存、展示。
## 验证
覆盖完整 Tools/schema 入库及离线读取、刷新失败保留快照、较旧刷新不覆盖新快照、成功空目录、连接变更失效、人工说明保留、租户及 OAuth 主体隔离。1,000 个工具时,默认首轮仍只暴露来源和入口,describe 后只加载目标工具。
HTTP 集成测试覆盖 OpenAI / Anthropic 两种适配器的 Direct 和按需加载流程,验证未 mention 的模型请求、缓存发现阶段无上游请求、实际 MCP 执行和调用历史回传。既有权限、分页、schema、审批及图片回归测试继续保留。

View File

@ -1,181 +0,0 @@
# Database migration troubleshooting
This guide is linked from the system info page when WeKnora's startup database
migration fails. It covers the most common causes, how to diagnose them, and
how to recover without losing data.
If none of these match your situation, jump to
[Reporting an issue](#reporting-an-issue) at the bottom.
---
## What "migration failed" means
WeKnora auto-runs `golang-migrate` migrations on every startup. When a
migration fails, the application **still finishes starting up** (so the UI
remains reachable to help you diagnose the problem), but:
- The failing migration is rolled back, leaving the database at the previous
version. Any tables / indexes introduced by that migration **are not
created**.
- Downstream features depending on those tables (Wiki ingest, knowledge graph,
task queues, …) may silently produce nothing.
- The system info page shows the partial DB version + a red "Migration failed"
tag and the captured error.
The cached error message you see in the UI is the same one logged at startup
under `Database migration failed: ...`. Recent container logs are the
authoritative source — copy them before doing anything destructive.
---
## Common causes
### 1. Missing PostgreSQL extension
Many migrations require extensions (`pg_trgm`, `vector`, `pg_search`) created
by `CREATE EXTENSION IF NOT EXISTS`. **`IF NOT EXISTS` does not validate that
the extension is actually installed** — it only checks the catalog. If the
extension's shared library is missing or the role lacks `CREATE` privilege,
the statement may succeed in the migration that nominally creates it but a
later migration that uses the extension (e.g. building a `gin_trgm_ops` index)
will fail.
**Symptoms in the error**:
```
ERROR: operator class "gin_trgm_ops" does not exist for access method "gin"
ERROR: type "vector" does not exist
ERROR: function ... does not exist
```
**Fix**:
```sql
-- Connect as a superuser (typically `postgres`):
\c your_weknora_database
CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE EXTENSION IF NOT EXISTS vector; -- if RETRIEVE_DRIVER includes pgvector
CREATE EXTENSION IF NOT EXISTS pg_search; -- only on ParadeDB
-- Verify they are actually loaded:
SELECT extname, extversion FROM pg_extension WHERE extname IN ('pg_trgm','vector','pg_search');
```
Then restart WeKnora. The next startup will pick up where the failing
migration left off.
If `CREATE EXTENSION` itself errors with **"could not open extension control
file"** or **"permission denied"**, the extension is not installed on your
PostgreSQL server — install the corresponding OS package (e.g.
`postgresql-contrib` for `pg_trgm`) or switch to an image that ships it
preinstalled, then retry.
### 2. Dirty migration state
If a migration crashed partway through (OOM, container kill, network blip)
`golang-migrate` marks the schema as "dirty" at the failing version. By
default, WeKnora's startup tries to auto-recover; if you disabled that with
`AUTO_RECOVER_DIRTY=false` you'll see:
```
database is in dirty state at version N. ...
```
**Fix** — use the bundled helpers:
```bash
# Check the recorded version
make migrate-version
# Force the version to the last successful migration (N - 1 in the message)
make migrate-force version=<N-1>
# Re-run pending migrations
make migrate-up
```
After that, restart WeKnora.
Or set `AUTO_RECOVER_DIRTY=true` (the default in recent versions) and just
restart — startup will perform the same `force` + retry automatically.
### 3. Insufficient privileges on the database role
Some migrations create extensions or alter shared catalogs, which require
either superuser or `CREATEROLE` / `CREATEDB`. Errors look like:
```
ERROR: permission denied to create extension "pg_trgm"
ERROR: must be owner of database ...
```
**Fix**: grant the role used by `DB_USER` the necessary privileges, or
pre-create the extensions / objects as a superuser ahead of time, then
restart. The migration's `CREATE EXTENSION IF NOT EXISTS` will then no-op.
### 4. Out-of-disk during `CREATE INDEX`
GIN / pgvector indexes can require significant temporary space. Errors:
```
ERROR: could not extend file ...: No space left on device
ERROR: cannot create temporary tables in transaction
```
**Fix**: free disk on the volume backing `PGDATA`, then restart. The
migration will retry the index build.
### 5. Schema drift from manual edits
If you previously edited tables / columns by hand and a later migration
expects the original shape, it will fail with mismatched-type errors. The
safest recovery is to align the live schema with the previous successful
migration's `*.up.sql` and then re-run pending migrations.
---
## Generic diagnostic checklist
1. **Read the full error**: the cached message in the UI is truncated only by
your browser scroll — it is the complete `golang-migrate` error. The
container log shows the same content with stack context.
2. **Identify the failing migration**: the version number in the error (or
`make migrate-version`) points to a file under `migrations/versioned/`.
Open `migrations/versioned/<version>_*.up.sql` and look for the statement
matching the error type (extension, index, function, foreign key, …).
3. **Run the failing statement manually** against the DB using `psql`. The
error will be far more specific than the migration wrapper's.
4. **Fix the underlying cause** (install extension, fix privileges, free
disk, …), then either:
- Restart WeKnora and let auto-recovery retry; **or**
- Run `make migrate-up` from a checkout to apply migrations outside the
server process.
5. **Verify**: the system info page should now show the DB version without
the "Migration failed" tag, and the previously broken feature (Wiki, KG,
…) should start producing output.
---
## Reporting an issue
If you've worked through the checklist and the migration still fails, please
open an issue at:
<https://github.com/Tencent/WeKnora/issues/new?template=bug_report.yml>
Include:
- WeKnora version + commit ID (from the system info page).
- The full error from the system info page (or container logs).
- PostgreSQL version (`SELECT version();`) and how it was deployed (vanilla,
ParadeDB, Aurora, Aliyun RDS, …).
- The output of:
```sql
SELECT extname, extversion FROM pg_extension;
```
- Any non-default values of `RETRIEVE_DRIVER`, `AUTO_MIGRATE`, and
`AUTO_RECOVER_DIRTY`.
The "Report issue" link on the system info page pre-fills a body with the
captured error for you — clicking it is the fastest path.

View File

@ -1,119 +0,0 @@
# ParadeDB 0.22.2 → 0.22.6 (PostgreSQL 17)
The production and development Compose files use `paradedb/paradedb:v0.22.6-pg17`.
The `langfuse-db-init` client uses the same image; Langfuse shares the Postgres
server and has its own database.
ParadeDB 0.22.2 compiles its Linux x86 extension for `x86-64-v3`, which can crash
with `Illegal instruction` on CPUs without AVX2. Version 0.22.6 lowers that
baseline to `x86-64-v2` (including SSE4.2 and POPCNT). This does **not** remove the
ARM `neoverse-n1` requirement or establish CPU compatibility for other services.
- [Upstream CPU fix](https://github.com/paradedb/paradedb/pull/4672)
- [0.22.6 release](https://github.com/paradedb/paradedb/releases/tag/v0.22.6)
- [Version-specific upgrade instructions](https://github.com/paradedb/paradedb/blob/v0.22.6/docs/deploy/upgrading.mdx)
## Existing deployments
Keep PostgreSQL on major version **17** and retain the existing data volume.
Do not use `docker compose down -v`, remove the volume, or substitute a PG18
image. This procedure covers the 0.22.2 → 0.22.6 patch upgrade; the Helm chart's
older 0.18.9 default is outside this validated upgrade path.
1. Stop application writers (`docker compose stop app` and, if enabled,
`docker compose stop langfuse-web langfuse-worker`; stop a locally running
development backend as well).
2. Take a restorable backup of all databases, including Langfuse and roles:
```bash
umask 077
docker compose exec -T postgres sh -c 'pg_dumpall -U "$POSTGRES_USER"' > paradedb-before-upgrade.sql
```
Check the command succeeded and keep the backup outside the database volume.
If the old server cannot start on this CPU, first preserve a cold snapshot of
the stopped volume; make a logical backup on a compatible host or validate
recovery from that snapshot before changing the only copy.
3. With the updated Compose file, replace only the database container:
```bash
docker compose pull postgres
docker compose up -d --no-deps --wait postgres
```
4. Complete the extension's SQL upgrade. Replacing the image alone leaves the
existing database's `pg_extension` catalog at 0.22.2:
```bash
docker compose exec -T postgres sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -v ON_ERROR_STOP=1' <<'SQL'
ALTER EXTENSION pg_search UPDATE TO '0.22.6';
SELECT extname, extversion FROM pg_extension WHERE extname IN ('pg_search', 'vector');
SELECT * FROM paradedb.version_info();
SQL
```
Run the same SQL in **every other database containing `pg_search`**, including
`postgres` and any template or Langfuse database where it was installed.
Do not install it into databases that do not use it. The catalog and
`paradedb.version_info()` should both report 0.22.6; pgvector stays at 0.8.1.
Migration `000099` also performs this step in the WeKnora database when the
installed extension is 0.22.2–0.22.5 and the 0.22.6 package is available.
It respects `app.skip_embedding` and leaves absent extensions and other
release lines alone. If the migration
ran before the new database image was installed, perform the SQL step above
manually: applied migrations are not repeated. Older application releases
without migration `000099` also require the manual step.
5. Resume the application writers, check migration status and run representative
keyword/vector searches. No `REINDEX` or document re-ingestion is required
by this patch upgrade. Preserve the backup until deployment checks pass.
For development use `docker compose -f docker-compose.dev.yml` in the commands
above. If rollback is necessary, restore the pre-upgrade backup/snapshot into a
separate volume with the old image. Merely changing the image tag back does not
reverse extension SQL changes; the migration's down file intentionally does not
attempt that.
## Reproducible verification
```bash
docker pull paradedb/paradedb:v0.22.2-pg17
docker pull paradedb/paradedb:v0.22.6-pg17
python3 scripts/test_paradedb_upgrade.py
```
The Python 3/Docker test uses uniquely named disposable containers and volumes,
publishes no ports, and does not access an existing WeKnora database. It saves
snapshots, query plans, a synthetic-data backup and logs in its printed output
directory, then removes only its own Docker resources.
It applies the real baseline migrations, seeds 720 embeddings across 798, 1024
and 3584 dimensions plus tenant/model/knowledge/session/message records, and
restarts the **same data volume** under the new image. It checks:
- All project table contents, columns, sequence values and index file identities.
- 104 keyword/vector queries: Chinese and English, missing/empty terms, KB,
document and tag filters, disabled/NULL-enabled rows, Top-K and thresholds.
- Both normal planner choices and explicitly exercised HNSW index scans; BM25
uses the production `|||` operator and `paradedb.score`. Equal BM25 scores use
an ID tie-breaker to make comparisons reproducible.
- Extension migration, idempotence, skip-embedding, unavailable target and absent extension.
- Results after another restart; committed insert/update/delete and vector lookup.
- A fresh database with the full migration chain and a Chinese BM25 query.
This verifies the fixture and upgrade path, not every production corpus or
workload. Production backup/restore and representative retrieval checks remain
part of the deployment procedure.
### Validation recorded on 2026-09-17
The test passed on Linux ARM64 with PostgreSQL 17.9 and pgvector 0.8.1 in both
images: all 70 project table snapshots and all 104 retrieval results were
identical after upgrade and after restart, including scores and index file IDs.
A separate restore of the pre-upgrade dump into 0.22.2 also preserved all table
hashes/counts and sequence values.
The Linux AMD64 0.22.6 image was additionally started under QEMU user emulation
with `QEMU_CPU=Nehalem`. A CPUID probe confirmed AVX2 was absent; initialization,
BM25/HNSW index creation, keyword search and vector lookup passed. This is an
emulation check, not a test on the affected physical server or Kunpeng hardware.

View File

@ -1,24 +0,0 @@
# FAQ 条目启用状态筛选设计
## 背景
FAQ 条目管理接口支持分页、标签、关键词和排序,但不能按 `is_enabled` 筛选。前端在分页结果返回后过滤会导致当前页数据和总数不准确。
## 接口
`GET /api/v1/knowledge-bases/{id}/faq/entries` 增加可选查询参数 `is_enabled`:
- 不传:返回全部条目,保持现有行为。
- `true`:只返回已启用条目。
- `false`:只返回未启用条目。
- 其他值:返回 `400 Bad Request`。
## 实现
Handler 区分参数缺失与布尔值,Service 将 `*bool` 传给已有的 Repository 查询。Repository 已在统计总数和分页数据查询中应用该条件,不需要数据库变更。
前端 API 参数类型补充 `is_enabled?: boolean`,本次不增加界面控件。Go 客户端保留现有方法签名,避免破坏调用方。
## 测试
补充查询参数解析测试,覆盖未传、`true`、`false` 和非法值;执行相关 Go 测试、前端类型检查及差异检查。

View File

@ -1,6 +1,6 @@
# Docker 沙箱后端可行性 PoC
配套文档:[Docker 沙箱后端重做调研](../../sandbox-docker-backend.md)。
当前实现与部署要求见[沙箱部署与排障](../../../website-docs/06-development/04-sandbox-deployment.md)。本 PoC 仅保留历史可行性实验,不代表当前适配器行为。
这个程序直接打 Docker Engine API,逐项验证「Docker 能不能承载 WeKnora
`RemoteSandboxClient` 契约 + E2B 那套 Snapshot 工作流」。它不是产品代码,也不参与主模块构建

View File

@ -1,4 +1,4 @@
// PoC for docs/sandbox-docker-backend.md: can the Docker Engine API back the
// Historical PoC: can the Docker Engine API back the
// semantics WeKnora's RemoteSandboxClient contract requires (session-persistent
// sandbox, exec, filesystem, metadata, lifecycle), plus the snapshot workflow
// planned for E2B?

View File

@ -1,130 +0,0 @@
# WeKnora 沙箱集群与标准模板
本文面向部署和平台管理员,说明如何把 CubeSandbox 或 E2B 接入 WeKnora。Docker、CubeSandbox、E2B 都在同一个空间设置页面通过同一套配置与检查接口管理;只有远端后端需要本文所述的集群和模板准备。普通智能体使用者不需要搭建模板,也不应该逐项猜测运行环境。
## 谁负责什么
| 角色 | 职责 |
| --- | --- |
| WeKnora 发布流程 | 维护 `docker/Dockerfile.sandbox`,发布与 WeKnora 版本匹配的 `wechatopenai/weknora-sandbox` 镜像 |
| 集群管理员 | 部署 CubeSandbox 或开通 E2B,并保证控制面模板 API 可用 |
| 空间管理员 | 在“设置 → 沙箱后端”中填写集群地址和凭据,先完成连接验证,再选择接口返回的模板 |
| 智能体管理员 | 在智能体的 Skills 配置中选择已经验证过的沙箱后端 |
“WeKnora 标准模板”指模板内容由 WeKnora 维护,并不代表所有集群共享同一个模板 ID。CubeSandbox 的模板 ID、E2B 的模板 ID/别名都属于具体集群或账号;跨集群硬编码一个 ID 会指向不存在或内容不一致的模板。
## 标准模板包含什么
标准镜像定义在 `docker/Dockerfile.sandbox`,当前包含:
- Python 3.12;
- Node.js 20、npm 与 npx;
- jq 及基础 Shell 工具;
- `/workspace` 工作目录;
- UID 1000 的 `user` 账号(E2B 模板约定的账号名,保留供按名字寻址的工具与 `sudo` 使用;WeKnora 执行脚本与文件操作默认用的是 root,见 `DefaultSandboxExecUser`)。
生产环境应使用与 WeKnora 相同的版本标签,不建议长期指向 `latest`。Skills 新增系统依赖时,应先更新标准镜像并重新注册模板,再切换集群的默认模板 ID。
### 镜像变体
`docker/Dockerfile.sandbox` 产出多个 target。CLI 变体内容相同、入口不同;桌面变体在同一套 Python 3.12 runtime 上再叠 XFCE,体积明显更大:
| 变体 | 标签 | 用途 |
| --- | --- | --- |
| `sandbox`(默认) | `wechatopenai/weknora-sandbox:<版本>` | Docker 后端的会话容器镜像;同时作为 E2B CLI 模板的基础镜像 |
| `cube` | `wechatopenai/weknora-sandbox:<版本>-cube` | CubeSandbox CLI 模板 |
| `desktop` | `wechatopenai/weknora-sandbox:<版本>-desktop` | E2B 图形桌面模板的基础镜像 |
| `desktop-cube` | `wechatopenai/weknora-sandbox:<版本>-desktop-cube` | CubeSandbox 图形桌面模板 |
区别在于 Cube 变体额外注入了 envd。Cube 直接把 OCI 镜像变成模板,并以 `GET :49983/health` 探活,这个端点只有 envd 提供;不带 envd 的镜像建模板必然以 `connection refused` 失败。E2B 不需要这个变体,因为它的构建流程会自行注入 envd;Docker 后端则完全不需要 envd,也**尚未**使用 `desktop` 变体。详见 [Cube 自带镜像接入](https://cubesandbox.com/zh/guide/tutorials/bring-your-own-image.html)。图形桌面的中继、票据与安全约束见 [沙箱图形桌面](./sandbox-desktop.md)。
Cube 变体只发布 linux/amd64——envd 的来源镜像 `cubesandbox-base` 没有 arm64,Cube 自身的 PVM 形态也只支持 x86_64。变体内 envd 以 root 运行,脚本按请求指定的账号执行;WeKnora 默认显式指定 root。
## CubeSandbox
### 先选部署形态
| 形态 | 适用 | 硬性前提 |
| --- | --- | --- |
| 裸金属 / 物理机 | 已有可用 KVM 的机器 | `/dev/kvm` 可读写;root 权限 |
| PVM | 云厂商屏蔽了嵌套虚拟化、`/dev/kvm` 不可用 | 仅 x86_64;需安装 PVM 宿主机内核并重启;ARM64 不支持 |
| Kubernetes(preview) | 已有集群、要多节点 | K8s 1.24+;计算节点打标签;计算节点非裸金属时需开启 PVM bootstrap |
三种形态共同的前提:
- glibc ≥ 2.31(官方二进制基于 Ubuntu 20.04 构建);
- `/data/cubelet` 挂载 XFS,且开启 reflink(快照的 Copy-on-Write 依赖它)。Ubuntu/Debian 默认 ext4,需要单独准备分区或 loop 设备;
- 至少 50 GB 可用磁盘(要做多个模板则建议 200 GB 以上)、内存 ≥ 8 GB;
- 内核支持 eBPF 且 `/sys/fs/bpf` 已挂载为 bpffs(Cubelet 的网络运行时依赖);
- 具备 `resolvectl` 或 NetworkManager(安装脚本据此配置 `cube.app` 的 DNS 解析);
- Docker 可用(MySQL/Redis 以 Docker Compose 运行)。
安装脚本会把 CubeMaster、Cubelet、CubeShim 作为宿主机进程运行,因此**不能在没有 systemd 的容器化环境里部署**。CI 容器、无 init 系统的开发机请改用 K8s 形态或另找一台主机。
### 制作模板并对接 WeKnora
1. 按 [CubeSandbox Quick Start](https://github.com/TencentCloud/CubeSandbox/blob/master/docs/zh/guide/quickstart.md) 完成控制面、计算节点、CubeProxy 与域名解析。生产环境还需按官方文档完成鉴权、TLS、网络策略与多节点部署。
2. 在 WeKnora 的空间设置中填写 CubeAPI、CubeProxy、sandbox domain 和可选 API Key。需要自定义 guest DNS 时填写「DNS 服务器」(须为 IP);留空则使用集群默认。若这些端点位于 RFC1918/loopback 网络,显式打开“允许访问私网集群地址”。
3. 点击“连接并继续”。WeKnora 先验证控制面地址与凭据,通过后才进入模板步骤并列出集群模板。**不会自动创建桌面模板**。没有 WeKnora 标准(CLI)模板时在占位卡片上点「创建」,会从 `wechatopenai/weknora-sandbox:main-cube` 发起构建。需要图形桌面时再点桌面占位卡片上的「创建」(XFCE 镜像更重,E2B 为 4CPU/4GB,Cube 可写层 8G)。改 DNS 或需要换镜像时在对应卡片上点「重建」:优先对现有模板做 in-place rebuild(模板 ID 不变);只有 redo 被拒绝时才先建新模板、成功后再删旧的。已安装 Skill 的配置(以及同一集群上其它已装 Skill 的配置)不能重建,也不能在 CLI / 桌面之间切换。失败模板同样用「重建」(CubeMaster 拒绝 redo、错误码 130400 时尤其需要)。
4. 模板构建状态会自动刷新。状态变为 `READY` 后才可选择并进入运行配置;界面显示模板名称、状态和版本,配置内部才保存该集群自己的 `template_id`。
标准模板保留 uid 1000 的 `user` 兼容账号;WeKnora 默认显式以 root 执行脚本与文件操作。模板应提供可写的 `/workspace`,运行前会准备 `input`、`output` 和本次工作目录。技能安装的维护调用只准备其工作目录。自定义只读挂载仍限制 root 的写入。
多实例 WeKnora 必须配置 Redis,以共享 session 到 sandbox 的绑定,以及桌面中继的「上次 sandbox ID」(技能安装重建后跨副本仍能发出 `SANDBOX_REBUILT`)。只有单实例开发环境才应使用内存绑定。
### 验证
界面上的“连接验证”只覆盖控制面,“完整验证”会真实创建、执行并销毁一个沙箱。要覆盖 WeKnora 实际依赖的全部语义(会话内状态保持、shell_exec 复用同一沙箱、附件暂存、产物收集、执行超时),在能访问集群的机器上跑一致性测试:
```bash
CUBE_API_URL=http://127.0.0.1:33000 \
CUBE_PROXY_URL=http://127.0.0.1:80 \
CUBE_TEMPLATE_ID=<模板 ID> \
go test -tags=integration ./internal/sandbox -run Integration -count=1 -v
```
测试结束会归还自己创建的沙箱;跑完用 `cubemastercli` 确认没有残留实例。
### 排障
| 现象 | 排查方向 |
| --- | --- |
| 连接验证失败 | CubeAPI 地址是否是控制面端口(不是 Dashboard 端口);私网地址是否已打开“允许访问私网集群地址” |
| 连接通过但执行报数据面错误 | CubeProxy 地址与 sandbox domain 是否与集群 `CUBE_API_SANDBOX_DOMAIN` 一致;Proxy 是否对 WeKnora 可达 |
| 模板长期停在构建中 | 镜像体积与网络;用 `cubemastercli tpl watch --job-id <id>` 看真实进度 |
| 模板构建失败 | 卡片上会显示集群返回的失败原因。未安装 Skill 时可点「重建」删掉失败模板并用当前配置新建;仅刷新列表不会再自动重建。已安装 Skill 的配置会拒绝重建,请新建沙箱 |
| 失败原因含 `TOOMANYREQUESTS` / Docker Hub 限流 | Cube 节点匿名拉 `wechatopenai/weknora-sandbox` 触发了 Hub 限额。等限额恢复后再刷新,或在节点上 `docker login` 后重试 |
| 失败原因是 `Get "http://<IP>:49983/health": connect: connection refused` | 模板镜像里没有 envd。确认建模板用的是 `-cube` 变体镜像;若已是该变体,再查 Cube 沙箱网段(默认 `192.168.0.0/18`)是否与物理内网冲突 |
| 沙箱能执行但「出网可用」失败 | 先看模板「公网访问」是否开启;WeKnora 标准模板构建会带 `allowInternetAccess`。guest DNS 来自标准模板构建时写入的 `dns`(设置页「DNS 服务器」/`dns_servers`)。留空时 Cubelet 会落到 `119.29.29.29`;私网或云上 UDP 53 到不了公网 DNS 时,填 Cube 宿主机 `/etc/resolv.conf` 里能用的地址,并避开 CubeVS 默认拒绝的 `10/8`、`172.16/12`、`192.168/16`。未安装 Skill 时,已有标准模板改 DNS 后在 weknora 卡片上点「重建」;已装 Skill 的配置请新建沙箱。其次 Cube 把沙箱 80/443 TPROXY 到 `192.168.0.1:8080/8443`,宿主机占用 `0.0.0.0:8080` 时 cube-egress 起不来。探测目标 `1.1.1.1` 在腾讯云也经常不通,国内目标可达即可 |
| 会话重连后状态丢失 | 多副本部署是否配置了 Redis 绑定存储;沙箱是否已被空闲 TTL 回收 |
### 已知限制
- K8s 部署仍是 preview:计算节点资源紧张时 Pod 可能被误驱逐,计算面升级会重建 Big Pod 并中断存量沙箱。
- 官方镜像的 Multi-Arch 覆盖尚不完整,ARM64 环境需自行构建模板镜像。
- 暂不支持 GPU 直通。
其它 E2B 兼容后端(含容器隔离的 Kubernetes 实现)与协议层的统一方案见 [沙箱协议接入说明](./sandbox-protocol.md)。
## E2B 及其它 E2B 兼容实现
E2B 官方托管服务、自建 E2B Infrastructure,以及任意实现 E2B 协议的控制面(例如 Kubernetes 上以容器隔离的 Agent-Sandbox)都通过同一个 E2B 配置接入;自建集群通常还要填写 `proxy_url` 数据面网关,详见 [沙箱协议接入说明](./sandbox-protocol.md)。填写 API Key 后先执行“连接并继续”,流程与 Cube 相同:验证连接后列出账号可见模板;缺少 `weknora` 时点「创建 WeKnora 标准模板」,通过 E2B Template API 从标准镜像启动后台构建。自建部署还需填写 API URL 和 sandbox domain;E2B 上游通过 Terraform 提供 AWS、GCP 等部署方式,具体以 [E2B self-hosting guide](https://github.com/e2b-dev/infra/blob/main/self-host.md) 和 [E2B Template 文档](https://e2b.dev/docs/template/quickstart) 为准。
## 在设置页面完成接入
1. 打开“设置 → 沙箱后端”,点击“添加沙箱后端”。
2. 填写该集群自己的 API、Proxy、sandbox domain 和凭据;这些值只保存在当前空间配置中,不读取 Sandbox 环境变量。
3. 点击“连接并继续”,验证控制面地址和凭据;连接通过后才加载模板列表。
4. 没有标准模板时点占位卡片上的「创建」,或选择集群已有的兼容模板;需要图形界面时再单独创建桌面模板。改 DNS / 镜像后在对应卡片上点「重建」。**该配置已安装 Skill 时不能更换或重建模板,也不能把 CLI 底模改成桌面(或反过来)**——技能环境绑在快照上,新底模不会进去;请新建一份沙箱再装 Skill。构建中的模板不可选择,状态会自动刷新。
5. 配置运行参数;上线前可执行一次“完整验证”。完整验证会真实创建、执行并销毁一个沙箱。
6. 保存后,在智能体 Skills 配置中选择该后端。对配置的修改只影响之后新建的沙箱;已有会话仍固定使用创建时的配置。
## 上线检查
- 模板版本与 WeKnora 版本匹配,且不依赖浮动的 `latest`;
- WeKnora 到控制面、Proxy 和 sandbox domain 的 DNS、TLS 与防火墙均已打通;
- 多实例部署已配置 Redis;
- API Key 只通过密钥管理或加密配置保存;
- “连接验证”和“完整验证”均通过;
- 已配置运行中与 paused 沙箱的容量监控、费用监控和孤儿清理;
- 切换模板或集群前已确认旧会话和旧沙箱的回收策略。

View File

@ -1,70 +0,0 @@
# 沙箱图形桌面
会话沙箱可以带一个 XFCE 图形桌面(x11vnc + websockify),由 WeKnora 把 RFB 中继到对话侧栏的「桌面」页。本文说明它如何接入、为什么默认不创建,以及部署时必须避开的几条路径。
Docker 后端目前**没有**桌面路径;只有 CubeSandbox / E2B 的桌面模板能打开该页。集群与 CLI 标准模板见 [沙箱集群与标准模板](./sandbox-cluster.md)。
## 架构
浏览器里的 noVNC **不持有任何沙箱凭据**。流量路径是:
```
浏览器 (noVNC)
⇄ WeKnora 中继 一次性票据鉴权、14 字节 RFB 握手、opcode 空闲判定
⇄ 提供商网关 e2b-traffic-access-token + Authorization: Basic
⇄ 沙箱内 websockify :6080 ⇄ 127.0.0.1:5900 上的 x11vnc(-nopw)⇄ Xvfb ⇄ XFCE
```
两端凭据都只存在于后端 → 沙箱这一跳:
- websockify Basic 密码写在沙箱内 `/run/desktop/secret`,由后端 Exec 读取,**从不**下发给浏览器;
- x11vnc 只绑在 `127.0.0.1:5900`,无 RFB 密码。
桌面是惰性启动的:E2B 以 envd 为 init、Cube 的 ENTRYPOINT 也是 envd,镜像 CMD 不会跑起来。第一次打开桌面 tab 时,后端在已有沙箱上 Exec `/usr/local/bin/start-desktop.sh`。查找连接(只 lookup、不 provision)不会为了预览去创建或恢复微虚拟机。
## 镜像
`docker/Dockerfile.sandbox` 在 CLI runtime(Python 3.12)之上再叠 XFCE:
| 变体 | 标签 | 用途 |
| --- | --- | --- |
| `desktop` | `wechatopenai/weknora-sandbox:<版本>-desktop` | E2B 桌面模板的基础镜像 |
| `desktop-cube` | `wechatopenai/weknora-sandbox:<版本>-desktop-cube` | Cube 桌面模板(amd64,带 envd) |
E2B 桌面模板构建为 4 CPU / 4 GB;Cube 桌面模板的可写层是 8G(标准 CLI 模板是 1G)。不要把 Python 运行时或 `/workspace` 权限改成「桌面专用」——那会连带改掉所有沙箱镜像。
## 模板是显式创建的
打开「设置 → 沙箱后端」并刷新模板列表时,**只会**在缺省时自动 ensure 官方 CLI 模板。桌面模板必须在模板步骤点「创建」才会带 `ensure_desktop`;否则会在集群里悄悄拉起一套更重的镜像。
保存时 `desktop_enabled` 跟所选目录卡片走:选中桌面卡则为 `true`,选中 CLI 卡则为 `false`。已安装 Skill 的配置不能改这个位——技能环境叠在当时的底模上,换 CLI/桌面等于换代。
对话侧栏只在当前智能体的沙箱配置 `desktop_enabled=true` 时显示「桌面」tab。Docker / 未选沙箱的智能体看不到该 tab。共享智能体若本空间拿不到那份配置,仍显示 tab,由后端返回 `DESKTOP_UNSUPPORTED`。
## Cube:6080 不要做宿主机 NAT
Cube 模板的 `exposedPorts` **只**含 envd 的 `49983`。Cube 会把这份列表用 eBPF static NAT 打到宿主机网卡,从而绕过 CubeProxy。
WeKnora 访问 websockify 的方式和访问 envd 一样:CubeProxy Host `{port}-{id}.{domain}`(即 `6080-{sandboxId}.{domain}`)加上入站 token。不要把 6080 写进 `exposedPorts`:沙箱内 agent/技能默认以 root Exec,读得到 `/run/desktop/secret`,一旦 6080 暴露在宿主机上就可以跳过票据中继、空闲断开和审计。
websockify 上的 Basic auth 只是叠加路径上的纵深防御,不是可以把端口公网化的理由。
## 票据与 WebSocket
桌面 WebSocket **不走**全局 JWT 中间件(和终端一样),握手用一次性票据:
1. 已登录的 `POST /api/v1/sessions/:session_id/sandbox/desktop-ticket` 签发票据(TTL 2 分钟)。
2. 浏览器把票据放在 `GET /api/v1/sessions/:id/sandbox/desktop?ticket=` 的 query 上。
3. 服务端 `GETDEL` 消费票据;用过、过期、未知都是同一类错误,避免探测。
票据是不透明随机串,不是 JWT,避免出现在网关 access log 和浏览器历史里。nginx 对该路径使用 `api_no_query` 日志格式,避免把 `ticket` 打进访问日志。
每个会话同一时刻只允许一条桌面中继(跨副本用 Redis 槽位)。技能安装可能重建沙箱;中继用 Redis 键 `weknora:desktop-last-sandbox:`(TTL 7 天)记住上次连上的 sandbox ID,换 ID 时以 `SANDBOX_REBUILT` 关掉连接,避免多副本重连进空白桌面还以为 `/workspace` 还在。未配 Redis 时退回进程内存储,只适合单实例。
## 空闲断开
中继根据 RFB opcode 判断键鼠活动(`FramebufferUpdateRequest` 不算)。浏览器还可以 `POST /api/v1/sessions/:session_id/sandbox/desktop/activity`,但**只有 RFB parser 降级时**才会续 TTL;parser 健康时该 POST 是空操作,避免靠轮询白嫖沙箱寿命。
## 相关接口
手写说明见 [会话管理 API](./api/session.md)。这些端点与终端 WebSocket 一样未进 Swagger。

View File

@ -1,224 +0,0 @@
# Docker 沙箱后端
面向部署方与要改这块代码的人。本文说明 docker 后端现在是什么形态、怎么配、边界在哪,
以及为什么是这个设计。协议层的整体立场见 [沙箱协议接入说明](./sandbox-protocol.md),
CubeSandbox / E2B 的集群与模板见 [沙箱集群与标准模板](./sandbox-cluster.md)。
## 结论先说
- docker 后端已经是**会话级后端**:一个会话一个长驻容器,脚本、`shell_exec`、附件暂存、
产物收集都落在同一个容器里,与 E2B/Cube 在应用层的行为一致。
- 实现方式是 `RemoteSandboxClient` 适配器(`internal/sandbox/docker_remote_client.go`),
直接打 Docker Engine API。session→sandbox 绑定、生命周期锁、能力矩阵一行没改——
这正是当初把 provider 抽象成 `RemoteSandboxClient` 的收益。
- 它适合单机 / 私有化部署。跨主机调度、内核级隔离、内存态快照仍然要用 E2B 协议后端,
原因见「边界」一节。
- **默认关闭。** 本机 `docker.sock` 等同宿主机 root。系统管理员可在「设置 → 系统设置 → 网络安全」打开,立即生效;也可用环境变量 `WEKNORA_SANDBOX_DOCKER_ENABLED=true` 作为未落库时的回退。设置页始终保留 Docker 标签:未打开时没有「添加」入口,只说明如何启用。已有配置仍可查看/删除,但不会再创建容器。
- Docker 官方的 Docker Sandboxes(`sbx`)不能当后端:那是开发者本机 CLI,要 Docker 账号登录、
工作区是宿主机目录直挂、没有多租户服务端 API。
## 之前为什么不行
旧实现每次执行都是 `docker run --rm` 加一个只读 bind mount,和 E2B 不是「能力少一点」,
而是模型不同。具体是这几条(都在改造中修掉了):
| 旧行为 | 后果 |
| --- | --- |
| 执行完即销毁容器 | 没有会话状态,`shell_exec`、附件暂存、产物收集在能力矩阵里根本不注册 |
| 超时 `kill` 的是 `docker run` 客户端进程 | 容器继续跑到自己结束;WeKnora 已经给用户返回超时了。实测见 [PoC](./poc/docker-sandbox) |
| `/workspace` 只读挂载 | 脚本写不了 `/workspace/output`,而 skills 框架恰恰把 `WEKNORA_SKILL_OUTPUT_DIR` 指到那里 |
| bind mount 由宿主机 daemon 解释 | WeKnora 自己跑在容器里时挂进去的是宿主机上的同名目录,通常不存在 |
| 走 docker CLI 而不是 API | 依赖宿主机装 CLI,错误只能靠字符串匹配,拿不到容器 ID 做对账与回收 |
| 配置面只有一个 `image` | CPU、内存、网络、TTL 都没法按空间配置 |
## 现在的形态
一个沙箱就是一个容器。标准镜像以 `USER root` 结尾,创建时仍显式指定 uid 0,这样即便换成以非 root 结尾的自定义镜像,入口也能在 `/var/lib` 写下活跃标记;脚本按每次调用指定的账号执行,默认是 root(见 `DefaultSandboxExecUser`)。一个会话独占一个沙箱,容器内没有第二个账号需要用文件权限隔开,隔离边界在容器本身。PID 1 是 `sleep infinity`,所有工作都通过 exec 进去做。
这层 wrapper 是通过 `Entrypoint` 下发并把 `Cmd` 显式清空的:daemon 会把镜像自带的
ENTRYPOINT 拼到 Cmd 前面,所以只设 Cmd 时,任何声明了 ENTRYPOINT 的镜像(本文件的
`cube` target 就有)都会顶掉 PID 1,活跃标记不会生成、exec 也会打到别的东西上。
| 契约方法 | Docker 实现 |
| --- | --- |
| `Health` | `GET /_ping` |
| `Create` | `POST /containers/create` + `/start`,metadata 落成 labels,镜像缺失时先 pull |
| `Connect` | `GET /containers/{id}/json`;容器被停掉时重新 `start`,被 pause 时 `unpause` |
| `Get` / `List` | `GET /containers/json?filters=label=…`,服务端按 label 过滤 |
| `Delete` | `DELETE /containers/{id}?force=1&v=1` |
| `Exec` | `POST /containers/{id}/exec` → `/exec/{id}/start`(hijack)→ `/exec/{id}/json` |
| `WriteFile` / `ReadFile` / `Stat` | 刻意不用 archive 接口,走 exec 的 `cat > "$1"` / `cat` / `find -maxdepth 0 -printf`(见下) |
| `MakeDir` / `Remove` / `ListDir` | 没有原生接口,用 exec 的 `mkdir -p` / `rm -rf` / `find -printf` |
几个不显然但要紧的决定:
**超时由容器内的 `timeout(1)` 执行。** 取消 HTTP 请求不会终止容器里的进程([PoC](./poc/docker-sandbox)
里专门复现了这条),所以每次 exec 都包一层
`sh -c 'touch <marker>; exec timeout -s KILL <n> "$@"' weknora-exec <cmd> <args...>`。
命令通过位置参数传进去,不做任何字符串拼接,脚本里的引号和换行不会改变实际执行的东西。
退出码 137/124 被翻译成 `Killed=true`。
**空闲回收是 WeKnora 自己的事。** daemon 没有任何 TTL 概念。上面那层 wrapper 顺手 `touch`
一个活跃标记文件,清扫时用一次 `HEAD /archive` 读它的 mtime 就知道容器多久没干活了——
不需要额外往容器里 exec,也不需要 Redis 记账。清扫在 `Create`/`Connect` 时触发,
按 daemon 端点限流(默认最快一分钟一次),在后台跑。删掉一个空闲容器不需要跟绑定存储协调:
生命周期本来就把「provider 上已经没有的沙箱」当作可重新绑定,这跟 E2B 沙箱被自己的 TTL
回收后的路径完全一样。每个容器把创建时的 TTL 记在 label 上,所以 A 配置触发的清扫不会拿
自己的 TTL 去衡量 B 配置的容器。
标记文件必须对沙箱账号可写(只跑脚本的会话也要能刷新它),因此它的 mtime 是容器可影响的:
落在未来的时间戳一律不采信,退回按容器启动时间判断,否则一次 `touch -d 2099-01-01`
就能让容器永久免于回收。往前改只会让自己更早被回收,不构成问题。此外清扫在真正删除前
会再读一次标记:列举加逐个 stat 在繁忙 daemon 上不是瞬时的,期间会话可能已被恢复。
残留风险:标记对沙箱账号可写是刻意的(只跑脚本的会话也要能刷新它),所以任何能在容器里
执行命令的东西——包括普通技能脚本,不需要 root——都可以起一个后台循环持续 `touch` 标记,
把自己维持成「一直活跃」。当前没有硬寿命上限,需要的话应由部署方在 daemon 侧限制。
**所有 exec 都显式指定账号,默认是 root。** 脚本执行、`shell_exec`、全部文件操作、以及
manager 自己的产物目录 bootstrap 都跑在 `DefaultSandboxExecUser` 下;`RemoteExecRequest.User`
留空时适配器解析成这个常量而不是镜像声明的账号,因此一次调用落到哪个账号,不取决于空间选了
哪个后端。
默认 root 的前提是一个会话独占一个沙箱:容器内没有第二个租户的文件需要用 mode bit 隔开,跨
租户与宿主机的隔离都落在容器边界上。镜像里仍然保留 uid 1000 的 `user` 账号,供 E2B/Cube 侧
按名字寻址的工具以及 `sudo` 使用。
容器 `CapDrop: ALL` 之后额外补回 CHOWN/DAC_OVERRIDE/FOWNER/FSETID/SETGID/SETUID/KILL,
Docker 默认给的 NET_RAW、MKNOD、SYS_CHROOT 等一律不给。exec 以 root 运行之后这批 capability
就是实际在用的(装包、修属主都要);收紧它们需要先确认技能安装路径不依赖,是可以独立推进的
加固项。
**文件操作走 exec,不走 archive 接口。** exec 为文件操作统一提供显式账号、超时控制和活跃标记更新;
archive 接口由 daemon 执行,不遵循这些逐次 exec 设置。默认账号已经是 root,因此这两条路径都不能
靠容器内的属主和 mode bit 把文件访问限制在 `/workspace`。路径前缀检查也不是符号链接隔离:
`/workspace/output/esc` 指向 `/root` 时,经它访问的文件仍可能由 root exec 读写。
`Stat` 用 `find`,不跟随**最后一段**链接,会将该链接报告为 `other`;中间层链接仍由路径解析展开,
所以 `/workspace/output/链接/passwd` 可能被报告为普通文件。单独的 Stat 检查也不能防止检查后替换链接。
产物目录约定不构成文件系统权限边界。宿主机和跨会话隔离依赖容器及挂载配置,真正的只读挂载仍限制 root。
若后续文件 API 需要严格的路径隔离,应在路径解析和实际访问时实施,不能沿用「exec 的内核账号检查会挡住链接」的前提。
archive 接口里只剩 `HEAD` 还在用,且仅用于读固定路径的活跃标记。
**PID 1 开 tini(`HostConfig.Init`)。** 容器入口是 `sleep`,它从不调用 `wait()`。长会话里
后台进程一旦活得比启动它的 exec 久,退出后就会变成没人回收的僵尸,堆到 `pids_limit` 之后所有
后续 exec 都会失败。
**镜像即模板。** `ListTemplates` 列出 daemon 上带 `com.weknora.sandbox.template=true` 标签的、
或名字就是标准镜像的镜像;`EnsureStandardTemplate` 在后台拉取,拉取期间模板状态显示为
`building`,与其它后端的模板构建流程对齐。
## 配置
在「设置 → 沙箱后端」中新建配置并选择 Docker:
系统管理员可在「设置 → 系统设置 → 网络安全」打开 Docker 沙箱(立即生效)。未落库时回退到 `WEKNORA_SANDBOX_DOCKER_ENABLED`。默认关闭,因为能保存 Docker 配置的空间管理员可以在本进程够得到的 Engine API 上创建容器,而本机 `docker.sock` 等同宿主机 root。设置页始终有 Docker 标签;未打开时没有添加按钮,只提示如何启用。
| 字段 | 说明 |
| --- | --- |
| 镜像 | 必填。会话容器都从它创建,等价于其它后端的 template ID |
| Docker 守护进程地址 | 留空跟随本机 `docker` CLI(`DOCKER_HOST` 或当前 `docker context`),因此 Colima / Docker Desktop 不必手填 socket。远程填 `tcp://host:2376`,**必须**同时填 TLS 证书目录;私网地址要打开「允许访问私网集群地址」 |
| TLS 证书目录 | 远程 daemon 必填。WeKnora 主机上包含 `ca.pem`/`cert.pem`/`key.pem` 的目录,证书不入库 |
| 空闲回收 | 容器多久没执行任何命令就回收。留空 1800 秒 |
| CPU / 内存 / 进程数上限 | 单个沙箱的资源上限。留空 2 核 / 2048 MB / 512 进程 |
| 网络模式 | 只接受 `bridge`(默认)与 `none`(完全禁止出网)。`host`、`container:` 以及自定义网络名一律拒绝:常见部署通过挂载的 `docker.sock` 连 daemon,填上部署自身的 compose 网络就会让沙箱与 Postgres / Redis 同网 |
`tcp://` daemon 的连接与其它后端的租户端点同一口径:保存时校验地址,实际拨号时再按
「允许访问私网地址」开关过一遍 `SafeDialControl`,这样保存校验解析到公网、连接时被
重解析到 169.254.169.254 的情况也拦得住。unix socket 不经过这一层。
镜像要求:可按名执行的 `root` 账号、可写的 `/workspace`、
GNU `find`(`-printf`)与 coreutils `timeout`。标准镜像另保留 uid 1000 的 `user` 账号,
并将工作区属主设为该账号以兼容显式选择 `user` 的工具;默认 root 执行不依赖这个属主。`docker/Dockerfile.sandbox` 产出的标准镜像满足这些,
Debian 系基础镜像天然带 find 和 timeout。
部署形态:
| 形态 | 适用 | 关键约束 |
| --- | --- | --- |
| 本机 socket | 单机、私有化、开发 | app 与 daemon 同机;`docker.sock` 等于宿主机 root,只能暴露给 app 进程 |
| 远程 daemon(mTLS) | 沙箱负载与应用分离 | 必须配 TLS 证书;daemon 端口不得暴露到公网 |
| 每租户独立 daemon | 有强隔离诉求但没有 KVM | 由部署方分配,不同配置指向不同 host |
WeKnora 自己跑在容器里时,要把 **实际的** docker socket 挂进 app 容器(并接受它等同宿主机 root 的事实),
或者改用远程 daemon。Linux 上通常是 `/var/run/docker.sock`;macOS 上 Colima / Docker Desktop / OrbStack
各自有 `$HOME` 下的 socket,以 `docker context show` 为准。入口脚本在 `gosu` 降权前会按
socket 的 GID 把 `appuser` 加入对应组;不要依赖 compose `group_add`,也不要 `chmod 666`
宿主机 socket。若 socket 是 `root:root` 且仅所有者可写,容器内无法安全补权,需在宿主机把
socket 改成非 root 组的 `660`。
## 边界
这些是 Docker 给不了的,写在这里以免被当成 bug:
- **跨主机调度**:一个配置就是一个 daemon,也就是一台机器。要多机就得自己选机、分发镜像、
在绑定里记住会话落在哪台机器上——那就是在写一个控制面,这条边界是刻意保留的。
- **内核级隔离**:容器共享宿主机内核。要更强只能叠 gVisor / Kata(配置里的 runtime 字段)。
- **内存态快照**:`docker commit` 只保存文件系统。CRIU(`docker checkpoint`)是 experimental,
默认 daemon 直接拒绝。E2B 的 pause/snapshot 会保存内存,Docker 不会。
- **域名级出网策略**:Docker 只有 L3/L4。`RemoteNetworkPolicy` 里的域名 allow/deny 在这个后端
只能表达成「全开」或「全关」,要按域名放行得在部署侧加 egress proxy。
- **卷挂载**:`SupportsVolumes` 目前是 false,租户级共享卷还没有映射到 Docker named volume。
- **图形桌面**:`desktop` 镜像变体尚未接到 Docker 后端。对话侧栏在 Docker 配置上不显示「桌面」tab;Cube / E2B 见 [沙箱图形桌面](./sandbox-desktop.md)。
## 快照
「空间级管理沙箱装 skill → commit 成快照 → 会话从快照起容器 → 增量出下一版」这套流程已经接入:
`DockerRemoteClient` 实现 `RemoteSnapshotManager`,`docker commit` 打出带
`com.weknora.sandbox.skill-snapshot` 标签的本地镜像(命名空间 `weknora-skill/`),
会话启动时用该镜像覆盖配置里的基础 image。安装器用 root `shell_exec` 写
`/opt/weknora/tenant/skills`,与 Cube / E2B 同一条技能安装链路。
两个要注意的约束:镜像层上限 127,长期增量要定期压平;快照是本机资产,多机部署必须推到 registry。
压平和跨 daemon 分发还不在这条路径里。
磁盘占用的实际形态和 Cube / E2B 不一样,值得单独说清楚:
- 第 N+1 代是从第 N 代起的容器 commit 出来的,**N 的层完整包含在 N+1 里**。所以两代镜像并存
时,旧的那个 tag 不额外占盘;反过来说,`PruneSupersededSnapshots` 到期删掉旧 tag 也几乎
回收不了空间。真正回收发生在整条链的 tag 全部退役之后,因此 `DeleteSnapshot` 必须带
`PruneChildren`(即 `noprune=0`),否则无 tag 的祖先层会永久留下。
- **卸载一个 skill 会让镜像变大**:`rm -rf` 在 overlay 上是新增一层 whiteout,被删的文件仍
留在父层。也就是说装和卸都只增不减,Cube / E2B 是每代一张独立模板、到期真删,只有 Docker
是单调累积。要把空间还回来,只能从基础模板重建整条链——`SkillSnapshotTriggerRebuild` 为此
预留了,但重建流程尚未实现。
- 快照的 owner fingerprint 只在 host 是**显式配置**时才把 host 计入。留空的配置一律记成
`local-daemon`,不能采用 `DetectLocalDockerHost()` 的结果:那个值来自 `DOCKER_HOST` 或当前
docker context,切一次 Colima / Docker Desktop / OrbStack 就会变,而它一变就等价于「凭据
轮换」——会话静默退回基础模板(skill 全部消失)、安装被拒、快照清理被永久跳过。本机 daemon
换个 host 字符串通常还是同一块盘上的同一批镜像,跨账号那套推理在这里不成立。
回收路径依赖 ledger 能给每张快照命名,而 `snapshot_id` 只有在 provider 应答之后才写得下来。
进程死在 commit 与那次写入之间,就会留下一张谁都叫不出名字的快照:`PruneSupersededSnapshots`
因为状态是 `building` 而跳过它,`ReconcileSnapshots` 只告警不删,配置删除时空 `snapshot_id`
被当成「无需释放」。因此 `planned_name` 在 commit **之前**就落库(迁移 000088),之后靠
provider 的 `ListSnapshots` 按名字认领:Cube / E2B 会把请求的名字回显在 `Names` 里,Docker 的
ID 本身就是这个名字加上 `weknora-skill/` 前缀。两条路径会用它——周期清理里的
`reapAbandonedBuilds`,以及配置删除时的 `resolveAbandonedBuildIDs`(配置一删,周期清理就再也
遍历不到这张快照,那是最后一次机会)。只有**认领成功**才会删;名字对不上时不动,因为无法区分
「commit 从未发生」和「该 provider 不回显名字」,猜错就等于丢掉一张仍然存在的快照的唯一记录。
## 测试
单元测试用一个内存版 Engine API 驱动适配器,不需要 daemon:
```bash
go test ./internal/sandbox -run 'TestDocker' -count=1
```
一致性测试打真实 daemon,覆盖会话状态保持、包安装跨执行存活、`shell_exec` 复用同一沙箱、
附件暂存与产物收集、超时确实终止进程、容器被外部停掉后恢复:
```bash
docker build -f docker/Dockerfile.sandbox --target sandbox -t wechatopenai/weknora-sandbox:dev .
DOCKER_INTEGRATION_IMAGE=wechatopenai/weknora-sandbox:dev \
go test -tags=docker_integration ./internal/sandbox \
-run '^TestDocker.*Integration' -count=1 -v -timeout=15m
```
它和 E2B 的一致性测试断言的是同一批语义,这是刻意重复:一个后端只过其中一个,
就说明两者在应用层还不能互换。
[docs/poc/docker-sandbox](./poc/docker-sandbox) 是当初的可行性验证,保留下来作为
「Docker 能做什么、不能做什么」的可复现证据,它不参与主模块构建。

View File

@ -1,103 +0,0 @@
# WeKnora 沙箱:以 E2B 协议为唯一接入契约
本文说明 WeKnora 为什么把 E2B 协议当作沙箱后端的唯一对接契约、现在还有哪些例外、以及可以直接拿来用的开源实现有哪些。面向部署方与要新接一种沙箱后端的开发者。
## 结论
- 跨主机、需要内核级隔离的部署走 E2B 协议(控制面 REST + 数据面 envd):WeKnora 只维护一套这样的客户端,具体隔离能力由社区实现提供,见下面的选型表。
- 单机 / 私有化部署可以直接用 `docker` 后端:它现在也是会话级后端(一个会话一个长驻容器),在应用层与 E2B 行为一致,代价是空闲回收、执行超时这些控制面职责由 WeKnora 承担。详见 [Docker 沙箱后端](./sandbox-docker-backend.md)。
- `local` 后端在 WeKnora 主机上直接跑脚本,没有任何隔离,只适合可信的开发空间。
## 当前的后端形态
| 后端 | 协议 | 会话内状态 | shell_exec / 附件暂存 / 产物收集 | 定位 |
| --- | --- | --- | --- | --- |
| `e2b` | E2B 协议 | 持久(一个会话一个沙箱) | 支持 | 生产主路径,可指向任意 E2B 兼容控制面 |
| `cube` | E2B 兼容(走 Cube 官方 Go SDK) | 持久 | 支持 | CubeSandbox 专用适配器,见“为什么还留着 cube 适配器” |
| `docker` | 无(Docker Engine API) | 持久(一个会话一个容器) | 支持 | 单机 / 私有化部署,见 [Docker 沙箱后端](./sandbox-docker-backend.md) |
| `local` | 无(本机进程) | 无 | 不支持 | 本机开发调试,隔离性最弱 |
`docker` 与 E2B 协议后端的分界不在能力而在规模:一个 docker 配置就是一台 daemon,跨主机调度、内核级隔离、内存态快照都不在它的能力范围内,那些正是 E2B 兼容实现提供的东西。`local` 依然不参与会话级能力集。能力矩阵在 `internal/sandbox/capabilities.go` 中显式表达,agent 侧据此决定是否注册 shell/文件类工具。
## 可直接使用的开源实现
| 实现 | 隔离方式 | 部署前提 | 适用场景 |
| --- | --- | --- | --- |
| [CubeSandbox](https://github.com/TencentCloud/CubeSandbox)(Apache-2.0) | KVM MicroVM,eBPF 网络隔离 | 裸金属/物理机需 `/dev/kvm`;普通云主机可用 PVM 内核;`/data/cubelet` 需 XFS(reflink);K8s 部署为 preview | 需要内核级隔离、高密度、快照/回滚 |
| [Agent-Sandbox](https://github.com/agent-sandbox/agent-sandbox)(Apache-2.0) | Kubernetes Pod(容器),可叠加 gVisor/Kata runtimeClass | 一个 K8s 集群(1.26+),`kubectl apply -f install.yaml` | 已有 K8s、想要“容器版 E2B”、不想引入虚拟化依赖 |
| [e2b-dev/infra](https://github.com/e2b-dev/infra)(Apache-2.0) | Firecracker MicroVM | Nomad/Consul + 云厂商 Terraform(AWS/GCP) | 想自建与 E2B Cloud 完全一致的栈 |
| [E2B Cloud](https://e2b.dev) | 托管 MicroVM | 只需 API Key | 不想自己运维 |
选型要点:
- 只有容器可用(没有 KVM、也不想上 PVM 内核)时,走 Agent-Sandbox 这类 K8s 原生实现,而不是给 WeKnora 加一个 Docker 控制面。
- 单机、有 KVM 或可装 PVM 内核,走 CubeSandbox。
- 上述实现都通过同一个 `e2b` 配置接入,WeKnora 侧零改动。
不建议采用的方向:`e2bgateway`、`circlesac/sandbox`、`Cage` 这类项目虽然也宣称 E2B 兼容并支持 Docker 后端,但当前 star 数与维护强度都在个位数量级,作为生产依赖风险过高。
## 怎么接入一个 E2B 兼容控制面
在“设置 → 沙箱后端”中新建配置,选择 `E2B`,填写:
| 字段 | 说明 |
| --- | --- |
| `api_key` | 控制面凭据。自建集群通常是它自己签发的 token |
| `api_url` | 控制面地址,例如 `http://agent-sandbox.internal/e2b/v1`。留空则用 E2B Cloud |
| `sandbox_domain` | 沙箱域名。数据面地址形如 `49983-<sandboxID>.<sandbox_domain>` |
| `proxy_url` | 数据面网关地址。见下 |
| `template_id` | 模板 / 镜像标识 |
| 允许访问私网集群地址 | 集群位于 RFC1918/loopback 时必须打开 |
`proxy_url` 是自建集群的关键:E2B Cloud 通过公网 DNS 解析每个沙箱的域名并提供证书,自建集群通常把所有沙箱收敛到一个网关地址、按 Host 头路由。填了 `proxy_url` 之后,WeKnora 会把数据面请求直接拨到该网关,同时保留沙箱域名在 Host 头里;网关是 `http://` 时还会把数据面 scheme 一并降级——E2B SDK 把它写死成 https,这一步省掉了为泛域名申请证书的成本。控制面请求不受影响,仍走共享连接池(实现见 `internal/sandbox/gateway_transport.go`)。
配置保存前先执行“连接并继续”,上线前执行一次“完整验证”,后者会真实创建、执行并销毁一个沙箱。
## envd 协议的兼容性坑
数据面 envd 的契约和 `github.com/matiasinsaurralde/go-e2b` 的实现之间有两处偏差,WeKnora 在 `internal/sandbox/envd_compat_transport.go` 里统一补齐:
- 认证:envd 要求 `Authorization: Basic base64("<user>:")`,SDK 发的是 `X-User-ID` 头。E2B Cloud 对此宽容,其他实现直接返回 `unauthenticated: no user specified`。
- 文件上传:envd 的 `POST /files` 只接受 `multipart/form-data`,SDK 发的是裸 `application/octet-stream`,会得到 500。
另外健康探针改用 `GET /v2/sandboxes`:旧的 `GET /sandboxes` 已不在客户端其他调用路径上,部分 E2B 兼容实现也只实现了 v2,用旧接口探活会把健康的后端判成不可用。文件操作显式声明执行账号(默认 `root`,见 `DefaultSandboxExecUser`),与脚本运行账号保持一致,而不是依赖各实现的默认值。
标准模板保留 `user` 账号(uid 1000)供兼容工具显式选用;WeKnora 默认以 `root` 执行脚本与文件操作。模板应提供可写的 `/workspace`,普通调用会准备 `/workspace/output`、`/workspace/input` 和本次工作目录,维护调用只准备其工作目录。工作目录参数的前缀检查不是 root 命令的文件系统隔离边界;自定义只读挂载也不会因为使用 root 而变成可写。
## 一致性测试
`internal/sandbox/e2b_compatible_integration_test.go` 是面向任意 E2B 兼容控制面的一致性测试,覆盖会话内状态保持、shell_exec 复用同一沙箱、附件暂存、产物收集、执行超时。接一种新后端时先跑它:
```bash
E2B_INTEGRATION_API_URL=http://127.0.0.1:18080/e2b/v1 \
E2B_INTEGRATION_API_KEY=<token> \
E2B_INTEGRATION_TEMPLATE=code-interpreter \
E2B_INTEGRATION_SANDBOX_DOMAIN=localhost \
E2B_INTEGRATION_PROXY_URL=http://127.0.0.1:18080 \
go test -tags=e2b_integration ./internal/sandbox \
-run '^TestE2BCompatibleControlPlaneConformance' -count=1 -v -timeout=15m
```
针对 E2B Cloud 时不要设置 `E2B_INTEGRATION_PROXY_URL`。该套件已在 Kubernetes 上的 Agent-Sandbox(容器后端)实测通过。
### 在本机复现一个容器版 E2B 后端
只需要 Docker,用 kind 起一个单节点集群即可,全程不涉及 KVM:
```bash
kind create cluster --name e2b-poc
kubectl create namespace agent-sandbox
kubectl apply -n agent-sandbox -f https://raw.githubusercontent.com/agent-sandbox/agent-sandbox/main/install.yaml
# 控制面需要一份模板配置;集群里没有 gVisor 时,先把模板的 runtimeClassName 去掉
kubectl -n agent-sandbox create configmap agent-sandbox \
--from-file=sandbox.yaml --from-file=templates.json
kubectl -n agent-sandbox port-forward svc/agent-sandbox 18080:80
```
之后把 `api_url` 指向 `http://127.0.0.1:18080/e2b/v1`、`proxy_url` 指向 `http://127.0.0.1:18080`、`sandbox_domain` 填 `localhost`,即可用上面的命令跑一致性测试。默认 token 在 install.yaml 中,生产部署务必替换。
## 为什么还留着 cube 适配器
CubeSandbox 兼容 E2B SDK,理论上可以只用 `e2b` 配置接入。目前仍保留独立适配器,原因是它使用 Cube 官方 Go SDK,模板构建、网络策略等控制面能力与 Cube 的 API 一一对应,而这些在通用 E2B 客户端里还没有等价物。合并的前置条件是:在真实 Cube 集群上跑通上面的一致性测试,并把模板构建、网络策略两块能力对齐到通用客户端。数据面路由已经不再是障碍——`proxy_url` 已经泛化成所有远端后端共用的能力。

View File

@ -1,91 +0,0 @@
---
title: API文档概览
tags: [API参考, REST, 认证, 接口]
aliases: [API概览, API文档, API参考]
source: api/README.md
---
# API 文档概览
WeKnora 提供了一系列 RESTful API,用于创建和管理知识库、检索知识,以及进行基于知识的问答。
## 基础信息
- **基础 URL**: `/api/v1`
- **响应格式**: JSON
- **认证方式**: API Key
> API 认证使用 WeKnora 本地 JWT,OIDC 认证流程参见 [OIDC认证调用流程](../安全认证/OIDC认证调用流程.md)
## 认证机制
所有 API 请求需要在 HTTP 请求头中包含 `X-API-Key`:
```
X-API-Key: your_api_key
X-Request-ID: unique_request_id # 建议,便于追踪
```
API Key 在 Web 页面完成账户注册后,前往账户信息页面获取。
## 错误处理
```json
{
"success": false,
"error": {
"code": "错误代码",
"message": "错误信息",
"details": "错误详情"
}
}
```
## API 分类
| 分类 | 描述 | 详细文档 |
|------|------|----------|
| 认证管理 | 用户注册、登录、令牌管理;OIDC 流程 | [auth.md](../../api/auth.md) · [OIDC认证调用流程.md](../安全认证/OIDC认证调用流程.md) |
| 空间管理 | 创建和管理空间账户 | [tenant.md](../../api/tenant.md) |
| 知识库管理 | 创建、查询和管理知识库 | [knowledge-base.md](../../api/knowledge-base.md) |
| 知识管理 | 上传、检索和管理知识内容 | [knowledge.md](../../api/knowledge.md) |
| 模型管理 | 配置和管理各种AI模型 | [model.md](../../api/model.md) |
| 分块管理 | 管理知识的分块内容 | [chunk.md](../../api/chunk.md) |
| 标签管理 | 管理知识库的标签分类 | [tag.md](../../api/tag.md) |
| FAQ管理 | 管理FAQ问答对 | [faq.md](../../api/faq.md) |
| 智能体管理 | 创建和管理自定义智能体 | [agent.md](../../api/agent.md) |
| 会话管理 | 创建和管理对话会话 | [session.md](../../api/session.md) |
| 知识搜索 | 在知识库中搜索内容 | [knowledge-search.md](../../api/knowledge-search.md) |
| 聊天功能 | 基于知识库和 Agent 进行问答 | [chat.md](../../api/chat.md) |
| 消息管理 | 获取和管理对话消息 | [message.md](../../api/message.md) |
| 评估功能 | 评估模型性能 | [evaluation.md](../../api/evaluation.md) |
| 初始化管理 | 知识库模型配置与 Ollama 管理 | [initialization.md](../../api/initialization.md) |
| 系统管理 | 系统信息、解析引擎、存储引擎 | [system.md](../../api/system.md) |
| MCP 服务 | MCP 工具服务管理 | [mcp-service.md](../../api/mcp-service.md) |
| 组织管理 | 组织、成员、知识库/智能体共享 | [organization.md](../../api/organization.md) |
| Skills | 预装智能体技能 | [skill.md](../../api/skill.md) |
| 网络搜索 | 网络搜索服务商 | [web-search.md](../../api/web-search.md) |
| 向量存储 | 向量数据库连接管理 | [vector-store.md](../../api/vector-store.md) |
> 各 API 的详细说明参见 `docs/api/` 目录下的对应文档
## 相关主题
- [OIDC认证调用流程](../安全认证/OIDC认证调用流程.md) — API 认证的 OIDC 流程
- [内置模型管理](../核心功能/内置模型管理.md) — 模型管理 API 的配置参考
- [MCP功能使用说明](../核心功能/MCP功能使用说明.md) — MCP 服务管理 API 的使用
- [共享空间说明](../安全认证/共享空间说明.md) — 组织管理 API 的业务逻辑
- [IM集成开发](../集成扩展/IM集成开发.md) — IM 渠道管理 API
- [数据源导入开发](../集成扩展/数据源导入开发.md) — 数据源管理 API
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [OIDC认证调用流程](../安全认证/OIDC认证调用流程.md) — API 认证机制与 OIDC 相关
- [内置模型管理](../核心功能/内置模型管理.md) — 模型管理 API 的底层配置
- [MCP功能使用说明](../核心功能/MCP功能使用说明.md) — MCP 服务 API 的使用场景
- [共享空间说明](../安全认证/共享空间说明.md) — 组织管理 API 的业务逻辑
- [IM集成开发](../集成扩展/IM集成开发.md) — IM 渠道 API 的使用场景
- [数据源导入开发](../集成扩展/数据源导入开发.md) — 数据源 API 的使用场景

View File

@ -1,127 +0,0 @@
---
title: WeKnora Wiki 首页
tags: [首页, 导航, MOC]
aliases: [Home, Index, wiki首页]
---
# WeKnora Wiki
欢迎使用 WeKnora 知识库 wiki!这里是 WeKnora 项目文档的互联知识网络,所有页面通过双向链接关联,帮助你从任意入口探索整个知识体系。
---
## 项目概述
| 页面 | 简介 |
|------|------|
| [版本路线图](项目概述/版本路线图.md) | 产品规划与计划方向 |
| [Lite与标准版区别](项目概述/Lite与标准版区别.md) | 轻量版与标准版的功能对比 |
## 核心功能
| 页面 | 简介 |
|------|------|
| [知识图谱](核心功能/知识图谱.md) | Neo4j 知识图谱的快速开始与使用 |
| [开启知识图谱功能](核心功能/开启知识图谱功能.md) | 知识图谱功能的完整启用流程 |
| [MCP功能使用说明](核心功能/MCP功能使用说明.md) | MCP 服务的用户操作指南 |
| [内置MCP服务管理](核心功能/内置MCP服务管理.md) | 内置 MCP 服务的系统级管理 |
| [内置模型管理](核心功能/内置模型管理.md) | 内置模型的系统级管理 |
| [Agent技能系统](核心功能/Agent技能系统.md) | Agent Skills 扩展机制与沙箱技能 |
## 集成与扩展
| 页面 | 简介 |
|------|------|
| [IM集成开发](集成扩展/IM集成开发.md) | 企业即时通讯平台接入开发 |
| [数据源导入开发](集成扩展/数据源导入开发.md) | 外部平台数据自动同步与导入 |
| [添加网络搜索引擎](集成扩展/添加网络搜索引擎.md) | 扩展新的网络搜索 Provider |
| [集成向量数据库](集成扩展/集成向量数据库.md) | 集成新的向量数据库检索引擎 |
## 安全与认证
| 页面 | 简介 |
|------|------|
| [OIDC认证调用流程](安全认证/OIDC认证调用流程.md) | OIDC 第三方登录的完整调用链路 |
| [空间RBAC说明](安全认证/RBAC说明.md) | 空间内角色矩阵、资源归属与审计 |
| [共享空间说明](安全认证/共享空间说明.md) | 跨空间协作与知识库/智能体共享 |
## 开发与部署
| 页面 | 简介 |
|------|------|
| [开发指南](开发部署/开发指南.md) | 本地开发环境搭建与工作流 |
| [快速开发模式](开发部署/快速开发模式.md) | 后端/前端热更新开发模式 |
## 运维与排障
| 页面 | 简介 |
|------|------|
| [常见问题](运维排障/常见问题.md) | 部署与使用中的 FAQ |
## API 参考
| 页面 | 简介 |
|------|------|
| [API文档概览](API参考/API文档概览.md) | RESTful API 基础信息与分类索引 |
---
## 知识图谱
```mermaid
graph TB
Home[WeKnora Wiki]
Home --> 项目概述
Home --> 核心功能
Home --> 集成扩展
Home --> 安全认证
Home --> 开发部署
Home --> 运维排障
Home --> API参考
项目概述 --> ROADMAP[版本路线图]
项目概述 --> LITE[Lite与标准版区别]
核心功能 --> KG[知识图谱]
核心功能 --> KGSetup[开启知识图谱功能]
核心功能 --> MCP[MCP功能使用说明]
核心功能 --> BuiltinMCP[内置MCP服务管理]
核心功能 --> BuiltinModel[内置模型管理]
核心功能 --> Skills[Agent技能系统]
集成扩展 --> IM[IM集成开发]
集成扩展 --> DS[数据源导入开发]
集成扩展 --> WebSearch[添加网络搜索引擎]
集成扩展 --> VecDB[集成向量数据库]
安全认证 --> OIDC[OIDC认证调用流程]
安全认证 --> RBAC[空间RBAC说明]
安全认证 --> SharedSpace[共享空间说明]
开发部署 --> DevGuide[开发指南]
开发部署 --> QuickDev[快速开发模式]
运维排障 --> FAQ[常见问题]
API参考 --> APIOverview[API文档概览]
KG -.-> KGSetup
MCP -.-> BuiltinMCP
BuiltinMCP -.-> BuiltinModel
Skills -.-> IM
IM -.-> DS
DS -.-> SharedSpace
OIDC -.-> RBAC
RBAC -.-> SharedSpace
OIDC -.-> SharedSpace
LITE -.-> SharedSpace
WebSearch -.-> VecDB
DevGuide -.-> QuickDev
FAQ -.-> DevGuide
```
---
## 反向链接
本页为 wiki 首页,所有页面均链接回此处。

View File

@ -1,91 +0,0 @@
---
title: OIDC认证调用流程
tags: [安全认证, OIDC, 认证, 登录, SSO]
aliases: [OIDC, OIDC认证, SSO登录, 第三方登录]
source: OIDC认证调用流程.md
---
# OIDC 认证调用流程
本文档说明 WeKnora 当前 OIDC 登录能力的实际调用过程,覆盖前后端完整链路。
> OIDC 认证是标准版多空间场景下的登录方式,[Lite 版](../项目概述/Lite与标准版区别.md)不需要
## 整体设计说明
本项目的 OIDC 登录采用 **后端发起授权参数生成、后端接收回调并完成 code 换 token、前端通过 URL hash 接收最终登录结果** 的模式。
核心特点:
1. **前端只负责发起跳转**,不直接和 OIDC Provider 交换 token
2. **后端负责用授权码 `code` 向 OIDC Provider 换取 token**
3. 后端拿到 OIDC 用户信息后,会查找本地用户;若不存在则自动创建本地账号和默认空间
4. 最终签发 WeKnora 自己的本地 JWT,OIDC token 只用于后端换取用户身份
> 自动创建用户与空间的逻辑与 [共享空间说明](../安全认证/共享空间说明.md) 的多空间模型相关
## 相关接口
| 接口 | 说明 |
|------|------|
| `GET /api/v1/auth/oidc/config` | 获取 OIDC 是否启用及 Provider 展示名称 |
| `GET /api/v1/auth/oidc/url` | 生成第三方登录跳转地址 |
| `GET /api/v1/auth/oidc/callback` | OIDC Provider 回调地址 |
## 调用流程(4 个阶段)
### 阶段一:前端发现能力
前端调用 `/auth/oidc/config`,决定是否展示第三方登录入口。
### 阶段二:浏览器跳转授权
前端调用 `/auth/oidc/url` 获取授权地址,然后跳转到 OIDC Provider。
### 阶段三:后端完成身份兑换
Provider 回调后端 `/auth/oidc/callback`,后端用 `code` 换 token、拉取用户信息、关联或创建本地用户,并签发 WeKnora JWT。
### 阶段四:前端接收最终结果
后端 302 回前端,通过 `#oidc_result` 传递登录结果;前端在 `App.vue` 中统一解析。
## 关键配置项
| 配置项 | 说明 |
|--------|------|
| `OIDC_AUTH_ENABLE` | 是否启用 OIDC 登录 |
| `OIDC_AUTH_CLIENT_ID` | OIDC Client ID |
| `OIDC_AUTH_CLIENT_SECRET` | OIDC Client Secret |
| `OIDC_AUTH_DISCOVERY_URL` | OIDC Discovery 地址 |
| `OIDC_AUTH_SCOPES` | Scope 列表,默认 `openid profile email` |
启用时的最小要求:`client_id` + `client_secret` + (`discovery_url` 或 `authorization_endpoint + token_endpoint`)
## 本地联调示例(Dex)
项目中已提供 Dex 示例配置:`misc/dex-config.yaml`。
> 除 Dex 外,也可以使用 KeyCloak 等其他符合 OpenID Connect 协议的 Provider
## 注意事项
1. **`redirect_uri` 必须严格匹配** Provider 客户端配置
2. **邮箱是本地账号关联主键** — 若 Provider 没返回 email,将无法完成登录
3. **首次 OIDC 登录会自动创建用户和默认空间**
4. **真正用于访问 API 的是本地 JWT**,不是 OIDC access token
## 相关主题
- [共享空间说明](../安全认证/共享空间说明.md) — 多空间场景下的用户与组织管理
- [Lite与标准版区别](../项目概述/Lite与标准版区别.md) — Lite 版无需 OIDC(单空间)
- [API文档概览](../API参考/API文档概览.md) — API 认证机制
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [共享空间说明](../安全认证/共享空间说明.md) — OIDC 创建的用户与空间可用于共享空间
- [Lite与标准版区别](../项目概述/Lite与标准版区别.md) — Lite 不需要 OIDC(单空间无需注册)
- [API文档概览](../API参考/API文档概览.md) — API 的认证机制与 OIDC JWT 相关

View File

@ -1,114 +0,0 @@
---
title: 空间RBAC说明
tags: [安全认证, RBAC, 权限, 多空间, 角色]
aliases: [RBAC, 角色权限, 空间角色, TenantRBAC]
source: RBAC说明.md
---
# 空间 RBAC 说明
本文档介绍 WeKnora 的**空间内权限控制(Workspace RBAC)**,包括角色矩阵、资源归属模型,以及它与 [共享空间](./共享空间说明.md) 的关系。
> 状态:已发布;由配置项 `tenant.enable_rbac` 控制,默认 `true`(强制鉴权)。
> 完整说明、灰度方案、Schema、路由守卫等参见 [`docs/RBAC说明.md`](../../RBAC说明.md)。
## 解决的问题
RBAC 引入前,只要通过 `X-API-Key` 或 JWT 认证成功,调用方在空间内基本等同管理员。一旦一个空间出现多名真人成员,就需要区分:
- 谁可以删除知识库、撤销 API Key;
- 谁可以编辑「自己」的 KB / Agent;
- 谁只读。
## 角色矩阵
| 角色 | 标识 | 关键能力 |
|------|------|----------|
| 只读 | `viewer` | 仅读 |
| 贡献者 | `contributor` | 可变更 `creator_id == 自己` 的资源;他人资源按 Viewer |
| 管理员 | `admin` | 可变更空间内任意资源;管理成员、共享基础设施 |
| Owner | `owner` | Admin + 可删空间;每个空间至少一位,可以有多位 |
层级 `viewer < contributor < admin < owner`,高角色继承低角色。
Owner 的数量约束是“至少一位”,而不是“只能一位”。系统允许同一空间存在多个活跃 Owner;降级或移除 Owner 时,只有会导致空间失去最后一位 Owner 的操作才会被拒绝。
### 鉴权层的例外
- **跨空间超管**:`enable_cross_tenant_access` 打开且账号 `CanAccessAllTenants=true`,通过 `X-Tenant-ID` 切换后等同 Admin。
- **API Key**:合成虚拟用户在所属空间内固定 Admin(删空间除外)。
- **孤儿空间自愈**:首位认证的真人自动晋升 Owner,避免 API Key-only 空间锁死。
## 资源归属
迁移 `000043` 在关键表加上 `creator_id`:
- `knowledge_bases.creator_id` —— 老数据回填为该空间的 Owner;
- `custom_agents.creator_id` + `runnable_by_viewer`(默认 `true`,允许 Viewer 在对话中调用)。
子资源沿 `chunk → knowledge → kb → creator_id` 链回溯。
由此得到两类守卫:
- **角色守卫**:只看角色,用于空间级基础设施(模型、向量库、IM 通道等)。
- **归属守卫**`OwnedXxxOrAdmin`:creator 或 Admin+ 二者其一即放行,用于具体资源写操作。
## 与共享空间的关系
| 维度 | 解决什么 | 主键 |
|------|---------|------|
| **空间 RBAC** | 同一空间内「你能对自己/别人/共享基础设施做什么」 | `tenant_members(user_id, tenant_id, role)` |
| **共享空间** | 跨空间「让别的空间的人也能用我的 KB / Agent」 | `organization_members` + 共享关系 |
两者**正交**:
- 共享空间不持有 KB / Agent,只记录「以何种权限共享到了哪个空间」;资源归属与 `creator_id` 不变;
- 一次对**他人共享过来**的 KB 的写操作,需要同时满足:共享时设了「可写」 + 你在该空间不是 Viewer + 源空间的 RBAC 仍然放行;
- API Key 跨空间访问**不会**带 Admin 光环——共享路径由 `organization_members.role` 决定,与 API Key 无关。
判定顺序见 `internal/middleware/kb_access.go`:
```text
KB 属于我当前空间?─是─► 走空间 RBAC(角色 + creator_id)
└─否─► KB 共享给我所在空间?─是─► 取 min(共享权限, 空间角色)
└─否─► 403 / 404
```
一句话:**空间 RBAC 是纵向的纵深防御,共享空间是横向的协作通道;跨空间写动作必须同时穿过两道闸口。**
## 配置
```yaml
tenant:
enable_rbac: true # false 则进入「仅记录不拦截」灰度窗口
enable_cross_tenant_access: false
auth:
registration_mode: self_serve # 或 invite_only
audit:
retention_days: 90 # 0 表示不清理
```
环境变量 `WEKNORA_TENANT_ENABLE_RBAC` / `WEKNORA_AUDIT_RETENTION_DAYS` 覆盖 YAML。`DISABLE_REGISTRATION=true` 等价于把 `registration_mode` 强制设为 `invite_only`。
## 审计
`audit_logs` 表记录:
- `rbac.member_added` / `removed` / `role_changed` / `left`
- `rbac.access_denied`(仅强制鉴权时;1 分钟滑动窗口去重)
每日后台 goroutine 清理超过 `audit.retention_days` 的旧行。
## 相关主题
- [共享空间说明](./共享空间说明.md) — 跨空间协作与共享,与 RBAC 正交
- [OIDC认证调用流程](./OIDC认证调用流程.md) — 多空间用户体系的认证入口
- [Lite与标准版区别](../项目概述/Lite与标准版区别.md) — Lite 单用户场景下 RBAC 实际不发挥作用
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [共享空间说明](./共享空间说明.md) — 共享空间访问最终落到空间 RBAC 校验
- [OIDC认证调用流程](./OIDC认证调用流程.md) — JWT 解析后即进入 RBAC 角色匹配

View File

@ -1,78 +0,0 @@
---
title: 共享空间说明
tags: [安全认证, 共享空间, 协作, 多空间, 权限]
aliases: [共享空间, SharedSpace, Organization, 组织]
source: 共享空间说明.md
---
# 共享空间说明
本文档说明 WeKnora 中的**共享空间**功能,包括空间创建与加入、成员角色与权限、知识库与智能体共享规则。
> 共享空间是标准版功能,[Lite 版](../项目概述/Lite与标准版区别.md)不提供
## 共享空间概述
共享空间是跨空间协作的载体。用户可以在同一系统内属于不同空间(账户),通过**加入同一共享空间**,实现:
- 共享知识库:将本空间的知识库共享到空间,供空间内其他成员使用
- 共享智能体:将本空间的智能体共享到空间,供空间内其他成员在对话等场景中使用
- 访问他人共享的知识库和智能体
### 核心概念对照
| 概念 | 说明 |
|------|------|
| 共享空间 | 系统中的「组织」(Organization),用于跨空间共享 |
| 空间创建者 | 自动成为管理员,不可被移除或降级 |
| 空间成员 | 管理员 / 编辑者 / 只读 三种角色 |
| 知识库/智能体归属 | 始终属于一个空间;共享不改变归属 |
## 角色与权限
| 能力 | 管理员 | 编辑者 | 只读 |
|------|:-:|:-:|:-:|
| 查看、检索共享知识库 | ✓ | ✓ | ✓ |
| 编辑共享知识库内容 | ✓ | ✓ | ✗ |
| 将知识库共享到本空间 | ✓ | ✓ | ✗ |
| 管理空间设置与成员 | ✓ | ✗ | ✗ |
| 生成/刷新邀请码 | ✓ | ✗ | ✗ |
## 知识库共享规则
- 只有知识库所属空间下的用户才能发起共享
- 发起人必须是目标空间的**管理员**或**编辑者**
- 共享时指定权限:只读或可写
- 同一知识库可共享到多个空间,各自独立配置权限
## 智能体共享规则
- 智能体共享到空间时**仅支持只读**
- 同一智能体可共享到多个空间
> 智能体须已配置完成(如已选模型、若使用知识库则已选 rerank 模型等)方可共享。模型配置参见 [内置模型管理](../核心功能/内置模型管理.md)
## 智能体停用机制
- 停用是当前空间对**通过共享空间获得的智能体**的个人偏好设置
- 仅影响本空间在对话中选择智能体时的展示,不改变共享关系
- 不影响其他成员
## 相关主题
- [空间RBAC说明](./RBAC说明.md) — 单空间内的角色与资源归属,跨空间写操作需同时满足两边
- [Lite与标准版区别](../项目概述/Lite与标准版区别.md) — Lite 不支持共享空间
- [OIDC认证调用流程](../安全认证/OIDC认证调用流程.md) — 多空间场景下的用户认证
- [数据源导入开发](../集成扩展/数据源导入开发.md) — 数据源导入的知识库可被共享
- [内置模型管理](../核心功能/内置模型管理.md) — 智能体共享前需确保模型已配置
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [空间RBAC说明](./RBAC说明.md) — 共享空间访问最终落到空间 RBAC 校验
- [Lite与标准版区别](../项目概述/Lite与标准版区别.md) — Lite 不支持共享空间
- [OIDC认证调用流程](../安全认证/OIDC认证调用流程.md) — 多空间用户体系支撑共享空间
- [数据源导入开发](../集成扩展/数据源导入开发.md) — 导入的知识库可通过共享空间共享
- [内置模型管理](../核心功能/内置模型管理.md) — 智能体共享前的模型配置要求

View File

@ -1,93 +0,0 @@
---
title: 开发指南
tags: [开发部署, 开发, 本地开发, 环境搭建]
aliases: [开发环境, DevGuide, 开发指南]
source: 开发指南.md
---
# 开发指南
## 快速开发模式(推荐)
如果需要频繁修改 `app` 或 `frontend` 代码,不需要每次都重新构建 Docker 镜像,可以使用本地开发模式。
> 详细的开发模式说明参见 [快速开发模式](../开发部署/快速开发模式.md)
### 方式一:使用 Make 命令(推荐)
```bash
# 终端 1:启动基础设施
make dev-start
# 终端 2:启动后端
make dev-app
# 终端 3:启动前端
make dev-frontend
```
### 方式二:使用脚本命令
```bash
./scripts/dev.sh start # 启动基础设施
./scripts/dev.sh app # 启动后端
./scripts/dev.sh frontend # 启动前端
```
## 访问地址
| 服务 | 地址 |
|------|------|
| 前端开发服务器 | http://localhost:5173 |
| 后端 API | http://localhost:8080 |
| PostgreSQL | localhost:5432 |
| Redis | localhost:6379 |
| MinIO Console | http://localhost:9001 |
| Neo4j Browser | http://localhost:7474 |
> Neo4j 的使用参见 [知识图谱](../核心功能/知识图谱.md) 和 [开启知识图谱功能](../核心功能/开启知识图谱功能.md)
## 使用 Air 实现后端热重载
```bash
go install github.com/air-verse/air@latest
make dev-app # 检测到 Air 时自动启用热重载
```
## 前端独立开发
```bash
cd frontend
npm run dev # 连接到 http://localhost:8080 的后端 API
```
## 生产环境部署
```bash
sh scripts/build_images.sh # 构建所有镜像
sh scripts/start_all.sh # 启动生产环境
```
## 常见问题
- **启动 dev-app 时报错连接不到数据库**:确保先运行了 `make dev-start`
- **前端 CORS 错误**:检查 `vite.config.ts` 中的代理配置
- **DocReader 需要重新构建**:`sh scripts/build_images.sh -d`
> 更多排查建议参见 [常见问题](../运维排障/常见问题.md)
## 相关主题
- [快速开发模式](../开发部署/快速开发模式.md) — 开发模式的架构说明
- [知识图谱](../核心功能/知识图谱.md) — 开发环境中的 Neo4j 配置
- [Agent技能系统](../核心功能/Agent技能系统.md) — 沙箱镜像的构建
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [快速开发模式](../开发部署/快速开发模式.md) — 开发模式的架构对比说明
- [知识图谱](../核心功能/知识图谱.md) — 开发环境中的 Neo4j 启动
- [开启知识图谱功能](../核心功能/开启知识图谱功能.md) — 开发环境中启用图谱功能
- [常见问题](../运维排障/常见问题.md) — 开发相关故障排查

View File

@ -1,84 +0,0 @@
---
title: 快速开发模式
tags: [开发部署, 开发, 热更新, Air]
aliases: [快速开发, QuickDev, dev模式]
source: 快速开发模式说明.md
---
# 快速开发模式
解决开发流程中,每次修改 `app`(后端)或 `frontend`(前端)代码后,都需要打包 Docker 镜像的问题,实现这两个模块的热更新。
> 本页是 [开发指南](../开发部署/开发指南.md) 的补充,提供更详细的架构说明
## 使用方法
### 方式 1:Make 命令(推荐)
```bash
make dev-start # 终端 1:启动基础设施
make dev-app # 终端 2:启动后端
make dev-frontend # 终端 3:启动前端
```
### 方式 2:开发脚本
```bash
./scripts/dev.sh start # 终端 1
./scripts/dev.sh app # 终端 2
./scripts/dev.sh frontend # 终端 3
```
### 方式 3:一键启动
```bash
./scripts/quick-dev.sh
```
### 使用 Air 实现后端热重载
```bash
go install github.com/air-verse/air@latest
make dev-app # 自动检测 Air 并使用
```
## 架构对比
### 开发模式
```
本地后端 App (:8080) ← 本地前端 UI (:5173) → Docker 基础设施容器
(PostgreSQL/Redis/MinIO/Neo4j/DocReader)
```
- 后端/前端在本地直接运行,修改后秒级生效
- 基础设施仍使用 Docker 容器
### 生产模式
```
容器后端 App (:8080) ← 容器前端 UI (:80) → 基础设施容器
```
- 所有服务均运行在 Docker 容器中
- 每次修改需要重新构建镜像
## 效率对比
| 方式 | 每次修改耗时 |
|------|------------|
| 旧方式(重建镜像) | 2-5 分钟 |
| 新方式(本地开发) | 后端 5-10 秒,前端实时热重载 |
## 相关主题
- [开发指南](../开发部署/开发指南.md) — 完整的开发环境搭建指南
- [常见问题](../运维排障/常见问题.md) — 开发模式相关问题排查
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [开发指南](../开发部署/开发指南.md) — 完整开发指南(本页的补充说明)
- [常见问题](../运维排障/常见问题.md) — 开发模式相关故障排查

View File

@ -1,90 +0,0 @@
---
title: Agent技能系统
tags: [核心功能, Agent, Skills, 技能, 沙箱]
aliases: [Agent Skills, 技能系统, agent-skills]
source: agent-skills.md
---
# Agent 技能系统
## 概述
Agent Skills 是一种让 Agent 通过阅读"使用说明书"来学习新能力的扩展机制。与传统的硬编码工具不同,Skills 通过注入到 System Prompt 来扩展 Agent 的能力,遵循 **Progressive Disclosure(渐进式披露)** 的设计理念。目前仅支持带**智能推理**能力的智能体使用。
### 核心特性
- **非侵入式扩展**:不影响原有 Agent ReAct 流程
- **按需加载**:三级渐进式加载,优化 Token 使用
- **沙箱执行**:脚本在隔离环境中安全执行
- **灵活配置**:支持多目录、白名单过滤
> Skills 与 [MCP](../核心功能/MCP功能使用说明.md) 是两种不同的 Agent 扩展机制:Skills 通过 Prompt 注入,MCP 通过协议调用外部工具。
## 设计理念
### Progressive Disclosure(渐进式披露)
```
┌─────────────────────────────────────────────────────────────────┐
│ Level 1: 元数据 (Metadata) │
│ • 始终加载到 System Prompt • 约 100 tokens/skill │
│ • 包含:技能名称 + 简短描述 │
└─────────────────────────────────────────────────────────────────┘
↓ 用户请求匹配时
┌─────────────────────────────────────────────────────────────────┐
│ Level 2: 指令 (Instructions) │
│ • 通过 read_file 读取技能 SKILL.md • SKILL.md 的指令内容 │
│ • 包含:详细指令、代码示例、使用方法 │
└─────────────────────────────────────────────────────────────────┘
↓ 需要更多信息时
┌─────────────────────────────────────────────────────────────────┐
│ Level 3: 附加资源 (Resources) │
│ • 通过 read_file 加载特定文件 │
│ • 通过 shell_exec(skill_name=...) 执行脚本 │
└─────────────────────────────────────────────────────────────────┘
```
## Skill 目录结构
```
my-skill/
├── SKILL.md # 必需:主文件(含 YAML frontmatter)
├── REFERENCE.md # 可选:补充文档
├── templates/ # 可选:模板文件
└── scripts/ # 可选:可执行脚本
```
## 沙箱安全机制
### 脚本安全校验
执行前进行多层安全校验:危险命令检测、危险模式匹配、网络访问检测、反向 Shell 检测、参数注入检测等。
### Sandbox 配置
空间管理员在「设置 → 沙箱后端」中统一维护 Docker、CubeSandbox 或 E2B 配置。远端模板从目标集群实时获取;缺少 WeKnora 标准模板时由系统自动创建。智能体在编辑页选择一份空间配置,没有选择时不执行技能脚本。Docker、CubeSandbox、E2B 均保留会话级沙箱。
## 配置示例
```json
{
"skills_enabled": true,
"skill_dirs": ["/path/to/project/skills"],
"allowed_skills": ["pdf-processing", "code-review"]
}
```
## 相关主题
- [MCP功能使用说明](MCP功能使用说明.md) — 另一种 Agent 扩展机制
- [IM集成开发](../集成扩展/IM集成开发.md) — Agent 可通过 IM 渠道使用技能
- [开发指南](../开发部署/开发指南.md) — 沙箱镜像的构建
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [MCP功能使用说明](MCP功能使用说明.md) — 与 Skills 并列的 Agent 扩展机制
- [IM集成开发](../集成扩展/IM集成开发.md) — Agent 在 IM 渠道中可使用技能
- [版本路线图](../项目概述/版本路线图.md) — 路线图中的 Skills 社区扩展方向

View File

@ -1,66 +0,0 @@
---
title: MCP功能使用说明
tags: [核心功能, MCP, 工具集成]
aliases: [MCP使用, MCP功能]
source: MCP功能使用说明.md
---
# MCP 功能使用说明
## 功能概述
- MCP(Model Context Protocol)让 WeKnora 可以安全地连接外部工具或数据源,扩展 Agent 在推理时可调用的能力。
- 在前端 `设置 > MCP 服务`(`frontend/src/views/settings/McpSettings.vue`)中集中管理所有服务,无需手动改配置文件。
- 每个服务都包含名称、传输方式(SSE / HTTP Streamable / Stdio)、连接地址或命令、认证信息以及高级超时与重试策略。
> 关于系统级的内置 MCP 服务管理,参见 [内置MCP服务管理](内置MCP服务管理.md)
## 入口与界面
- 打开控制台左侧菜单 `设置 -> MCP 服务`,即可看到当前空间下的所有 MCP 服务列表。
- 列表中可快速启停服务、查看描述,并通过右侧菜单执行"测试 / 编辑 / 删除"。
- "添加服务"按钮会弹出 `McpServiceDialog`,用于创建或修改服务。
## 常用操作流程
### 1. 新建服务
- 点击"添加服务",填写名称与描述,选择传输方式。
- SSE / HTTP Streamable 需提供可访问的服务 URL;Stdio 需配置 `uvx`/`npx` 命令与参数,可附加环境变量。
- 根据需要填写 API Key、Bearer Token、超时与重试策略,保存后服务会出现在列表中。
### 2. 启停服务
- 在列表开关中切换启用状态,系统会即时调用后端 `updateMCPService`,失败时会自动回滚状态并弹出提示。
### 3. 连接测试
- 通过更多菜单选择"测试",前端会调用 `/api/v1/mcp-services/{id}/test` 并弹出 `McpTestResult`。
- 成功时会展示服务可用的工具清单(含输入 schema)和资源列表;失败时会显示错误信息,方便排查网络或鉴权问题。
### 4. 编辑 / 删除
- "编辑"会带出原有配置,修改后保存即可。
- "删除"需要在弹窗中确认,完成后列表自动刷新。
## 使用建议
- **传输方式选择**:优先使用 SSE 获取流式体验;需要标准 HTTP Streamable 兼容时再切换;本地调试或离线环境适合使用 Stdio 并在同机启动 MCP Server。
- **鉴权管理**:将 API Key / Token 保存在"认证配置"中,生产环境建议单独创建最小权限 Key,并定期轮换。
- **重试策略**:对公网或第三方服务适当提高 `retry_count` 与 `retry_delay`,避免间歇性超时导致 Agent 中断
## 相关主题
- [内置MCP服务管理](../核心功能/内置MCP服务管理.md) — 系统管理员视角的内置 MCP 服务配置
- [Agent技能系统](Agent技能系统.md) — 另一种 Agent 扩展机制
- [IM集成开发](../集成扩展/IM集成开发.md) — IM 渠道中 Agent 使用 MCP 工具
- [添加网络搜索引擎](../集成扩展/添加网络搜索引擎.md) — 扩展搜索能力的另一种方式
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [内置MCP服务管理](内置MCP服务管理.md) — MCP 的系统级管理(管理员视角)
- [Agent技能系统](Agent技能系统.md) — 与 MCP 并列的 Agent 扩展机制
- [IM集成开发](../集成扩展/IM集成开发.md) — Agent 在 IM 渠道中可调用 MCP 工具

View File

@ -1,105 +0,0 @@
---
title: 内置MCP服务管理
tags: [核心功能, MCP, 系统管理, 内置服务]
aliases: [内置MCP, BuiltinMCP, BUILTIN_MCP_SERVICES]
source: BUILTIN_MCP_SERVICES.md
---
# 内置 MCP 服务管理指南
## 概述
内置 MCP 服务是系统级别的 MCP(Model Context Protocol)服务配置,对所有空间可见,但敏感信息会被隐藏,且不可编辑或删除。内置 MCP 服务通常用于提供系统默认的外部工具和资源接入,确保所有空间都能使用统一的 MCP 服务。
> 用户视角的 MCP 服务操作参见 [MCP功能使用说明](MCP功能使用说明.md)
## 内置 MCP 服务特性
- **所有空间可见**:内置 MCP 服务对所有空间都可见,无需单独配置
- **安全保护**:内置 MCP 服务的敏感信息(URL、认证配置、Headers、环境变量)会被隐藏,无法查看详情
- **只读保护**:内置 MCP 服务不能被编辑或删除,仅支持测试连接
- **统一管理**:由系统管理员统一维护,确保配置一致性和安全性
## 与内置模型的对比
| 特性 | 内置模型 | 内置 MCP 服务 |
|------|---------|--------------|
| 标识字段 | `is_builtin` | `is_builtin` |
| 可见范围 | 所有空间 | 所有空间 |
| 隐藏信息 | API Key、Base URL | URL、认证配置、Headers、环境变量 |
| 编辑保护 | 不可编辑/删除 | 不可编辑/删除 |
| 前端标签 | 显示"内置"标签 | 显示"内置"标签 |
| 启停控制 | — | 禁用开关(始终启用) |
> 内置模型的详细管理参见 [内置模型管理](内置模型管理.md)
## 如何添加内置 MCP 服务
内置 MCP 服务需要通过数据库直接插入。
### 1. 准备服务数据
- 服务名称(name)
- 服务描述(description)
- 传输方式(transport_type):`sse` 或 `http-streamable`
- 服务地址(url)
- 认证配置(auth_config)
- 高级配置(advanced_config)
- 空间ID(tenant_id):建议使用小于 10000 的空间ID
**支持的传输方式**:
- `sse`:Server-Sent Events,推荐用于流式体验
- `http-streamable`:HTTP Streamable,标准 HTTP 兼容
> 注意:出于安全考虑,`stdio` 传输方式在服务端已被禁用。
### 2. 执行 SQL 插入语句
```sql
INSERT INTO mcp_services (
id, tenant_id, name, description, enabled,
transport_type, url, auth_config, advanced_config, is_builtin
) VALUES (
'builtin-mcp-001', 10000, 'Web Search', '内置 Web 搜索 MCP 服务',
true, 'sse', 'https://mcp.example.com/sse',
'{"api_key": "your-api-key"}'::jsonb,
'{"timeout": 30, "retry_count": 3, "retry_delay": 1}'::jsonb,
true
) ON CONFLICT (id) DO NOTHING;
```
### 3. 验证插入结果
```sql
SELECT id, name, transport_type, enabled, is_builtin
FROM mcp_services WHERE is_builtin = true ORDER BY created_at;
```
## 注意事项
1. **ID 命名规范**:建议使用 `builtin-mcp-{序号}` 格式
2. **空间ID**:建议使用第一个空间ID(通常是 10000)
3. **JSON 格式**:`auth_config`、`advanced_config`、`headers` 必须是有效的 JSON
4. **幂等性**:使用 `ON CONFLICT (id) DO NOTHING` 确保重复执行不会报错
5. **安全性**:内置 MCP 服务的 URL、认证信息在前端会被自动隐藏
6. **传输方式限制**:仅支持 `sse` 和 `http-streamable`
## 将现有 MCP 服务设置为内置服务
```sql
UPDATE mcp_services SET is_builtin = true WHERE id = '服务ID' AND name = '服务名称';
```
## 移除内置 MCP 服务
```sql
UPDATE mcp_services SET is_builtin = false WHERE id = '服务ID';
```
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [MCP功能使用说明](MCP功能使用说明.md) — 用户视角的 MCP 服务操作
- [内置模型管理](内置模型管理.md) — 同为内置系统配置,模式相似

View File

@ -1,83 +0,0 @@
---
title: 内置模型管理
tags: [核心功能, 模型, 系统管理, 内置服务]
aliases: [内置模型, BuiltinModel, BUILTIN_MODELS]
source: BUILTIN_MODELS.md
---
# 内置模型管理指南
## 概述
内置模型是系统级别的模型配置,对所有空间可见,但敏感信息会被隐藏,且不可编辑或删除。内置模型通常用于提供系统默认的模型配置,确保所有空间都能使用统一的模型服务。
> 同为内置系统配置的还有 [内置MCP服务管理](内置MCP服务管理.md)
## 内置模型特性
- **所有空间可见**:无需单独配置
- **安全保护**:API Key、Base URL 被隐藏
- **只读保护**:不能被编辑或删除,只能设置为默认模型
- **统一管理**:由系统管理员统一维护
## 如何添加内置模型
### 1. 准备模型数据
- 模型名称(name)
- 模型类型(type):`KnowledgeQA`、`Embedding`、`Rerank` 或 `VLLM`
- 模型来源(source):`local` 或 `remote`
- 模型参数(parameters):包括 base_url、api_key、provider 等
- 空间ID(tenant_id):建议使用小于10000的空间ID
**支持的服务商(provider)**:`generic`、`openai`、`aliyun`、`zhipu`、`volcengine`、`hunyuan`、`deepseek`、`minimax`、`mimo`、`siliconflow`、`jina`、`openrouter`、`litellm`、`requesty`、`gemini`、`modelscope`、`moonshot`、`qianfan`、`qiniu`、`longcat`、`gpustack`
### 2. 执行 SQL 插入语句
```sql
-- LLM 内置模型
INSERT INTO models (
id, tenant_id, name, type, source, description, parameters,
is_default, status, is_builtin
) VALUES (
'builtin-llm-001', 10000, 'GPT-4', 'KnowledgeQA', 'remote',
'内置 LLM 模型',
'{"base_url": "https://api.openai.com/v1", "api_key": "sk-xxx", "provider": "openai"}'::jsonb,
false, 'active', true
) ON CONFLICT (id) DO NOTHING;
-- Embedding 内置模型
INSERT INTO models (...) VALUES (...) ON CONFLICT (id) DO NOTHING;
-- Rerank 内置模型
INSERT INTO models (...) VALUES (...) ON CONFLICT (id) DO NOTHING;
```
### 3. 验证
```sql
SELECT id, name, type, is_builtin, status
FROM models WHERE is_builtin = true ORDER BY type, created_at;
```
## 注意事项
1. **ID 命名规范**:建议使用 `builtin-{type}-{序号}` 格式
2. **空间ID**:建议使用第一个空间ID(通常是 10000)
3. **参数格式**:`parameters` 字段必须是有效的 JSON 格式
4. **幂等性**:使用 `ON CONFLICT (id) DO NOTHING`
5. **安全性**:API Key 和 Base URL 在前端会被自动隐藏
## 模型配置与常见问题
- 如果 Embedding 模型未正确配置,会导致文档无法上传。排查步骤参见 [常见问题](../运维排障/常见问题.md)
- 模型参数中的 `provider` 决定了 API 调用格式和认证方式
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [内置MCP服务管理](../核心功能/内置MCP服务管理.md) — 同为内置系统配置,模式相似
- [常见问题](../运维排障/常见问题.md) — 模型配置相关的故障排查
- [版本路线图](../项目概述/版本路线图.md) — 路线图中模型训练方向

View File

@ -1,104 +0,0 @@
---
title: 开启知识图谱功能
tags: [核心功能, 知识图谱, Neo4j, 配置]
aliases: [知识图谱配置, KnowledgeGraphSetup]
source: 开启知识图谱功能.md
---
# 开启知识图谱功能
本文档介绍如何在 WeKnora 中启用并验证知识图谱(Neo4j)功能,帮助你完成从环境准备到前端配置的全流程。
## 前置条件
- 已完成 WeKnora 后端与前端的基础部署
- 具备可用的 Docker/Docker Compose 运行环境
- 本地或远端可访问的 Neo4j 服务(推荐使用项目自带的 Docker Compose)
> 快速入门参见 [知识图谱](知识图谱.md)
## 步骤一:配置环境变量
在项目根目录的 `.env` 文件中新增或修改以下变量:
```
NEO4J_ENABLE=true
NEO4J_URI=bolt://neo4j:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_strong_password
# 可选:NEO4J_DATABASE=neo4j
```
说明:
- `NEO4J_ENABLE` 设置为 `true` 才会启用知识图谱相关逻辑
- `NEO4J_URI` 中的 `neo4j` 为 docker-compose 服务名,如使用外部实例请替换为实际地址
- 如果生产环境使用密钥管理,请确保密码通过安全方式注入
## 步骤二:启动 Neo4j 服务
项目附带 Neo4j 组件,可直接用以下命令启动:
```bash
docker-compose --profile neo4j up -d
```
常见验证命令:
```bash
docker ps | grep neo4j
```
> 开发环境中 Neo4j 的启动方式参见 [开发指南](../开发部署/开发指南.md)
## 步骤三:重启 WeKnora 服务
为了让新的环境变量生效,重启后端与前端:
```bash
make stop && make start
# 或者
docker compose up -d --build
```
确保后端日志中出现 `neo4j` 初始化成功的提示。
## 步骤四:在前端启用实体/关系抽取
1. 登录 WeKnora 前端管理页面
2. 打开「知识库设置」或创建新的知识库
3. 勾选「启用实体抽取」与「启用关系抽取」开关
4. 根据界面提示补充所需的 LLM、回调或模型参数(若有)
保存后,系统会在文档入库阶段自动触发实体与关系抽取任务。
## 步骤五:验证知识图谱
### 方式一:Neo4j 控制台
1. 访问 `http://localhost:7474`(或对应主机/端口)
2. 使用 `.env` 中的账号密码登录
3. 执行 `MATCH (n) RETURN n LIMIT 50;` 检查是否有新节点/关系
### 方式二:WeKnora 界面
在知识库或对话页面中上传文档后,前端应展示图谱可视化入口;对话时系统会自动根据意图查询图谱并返回补充信息。
## 常见问题排查
- **无法连接 Neo4j**:确认网络可达、`NEO4J_URI` 与用户名密码正确,并检查 Neo4j 容器日志
- **未生成节点**:确认知识库已开启实体/关系抽取,且上传的文档已完成解析;查看后端日志中是否有抽取任务异常
- **查询无结果**:尝试在 Neo4j 控制台执行 `CALL db.schema.visualization;` 查看 schema 是否存在,必要时重新导入文档
> 更多排查建议参见 [常见问题](../运维排障/常见问题.md)
完成以上步骤后,知识图谱功能即成功启用,可结合 RAG 及 Agent 流程提升问答质量。
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [知识图谱](知识图谱.md) — 知识图谱快速入门(本页的精简版)
- [开发指南](../开发部署/开发指南.md) — 开发环境中 Neo4j 的启动与配置
- [常见问题](../运维排障/常见问题.md) — 图谱功能相关的故障排查

View File

@ -1,50 +0,0 @@
---
title: 知识图谱
tags: [核心功能, 知识图谱, Neo4j]
aliases: [KnowledgeGraph, 图谱]
source: KnowledgeGraph.md
---
# 知识图谱
## 快速开始
- .env 配置相关环境变量
- 启用 Neo4j: `NEO4J_ENABLE=true`
- Neo4j URI: `NEO4J_URI=bolt://neo4j:7687`
- Neo4j 用户名: `NEO4J_USERNAME=neo4j`
- Neo4j 密码: `NEO4J_PASSWORD=password`
- 启动 Neo4j
```bash
docker-compose --profile neo4j up -d
```
- 在知识库设置页面启用实体和关系提取,并根据提示配置相关内容
> 详细的启用步骤参见 [开启知识图谱功能](开启知识图谱功能.md)
## 生成图谱
上传任意文档后,系统会自动提取实体和关系,并生成对应的知识图谱。
![知识图片示例](../../images/graph3.png)
## 查看图谱
登录 `http://localhost:7474`,执行 `match (n) return (n)` 即可查看生成的知识图谱。
在对话时,系统会自动查询知识图谱,并获取相关知识。
## 相关主题
- [开启知识图谱功能](../核心功能/开启知识图谱功能.md) — 知识图谱功能的完整启用指南
- [常见问题](../运维排障/常见问题.md) — 知识图谱相关的故障排查
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [开启知识图谱功能](开启知识图谱功能.md) — 本页的详细版本,包含完整的启用流程
- [开发指南](../开发部署/开发指南.md) — 开发环境中 Neo4j 的配置与启动

View File

@ -1,106 +0,0 @@
---
title: 常见问题
tags: [运维排障, FAQ, 故障排查, 部署]
aliases: [FAQ, 故障排查, QA]
source: QA.md
---
# 常见问题
## 1. 如何查看日志?
```bash
docker compose logs -f app docreader postgres
```
## 2. 如何启动和停止服务?
```bash
./scripts/start_all.sh # 启动服务
./scripts/start_all.sh --stop # 停止服务
./scripts/start_all.sh --stop && make clean-db # 清空数据库
```
> 开发模式下的启停参见 [开发指南](../开发部署/开发指南.md)
## 3. 服务启动后无法正常上传文档?
通常是 Embedding 模型和对话模型没有正确被设置导致。
### 排查步骤
1. 查看 `.env` 配置中的模型信息是否配置完整:
```bash
INIT_LLM_MODEL_NAME=your_llm_model
INIT_EMBEDDING_MODEL_NAME=your_embedding_model
INIT_EMBEDDING_MODEL_DIMENSION=your_embedding_model_dimension
INIT_EMBEDDING_MODEL_ID=your_embedding_model_id
```
2. 如果使用 remote API,还需提供 `BASE_URL` 和 `API_KEY`
3. 如需重排序功能,额外配置 Rerank 模型
4. 查看主服务日志,是否有 `ERROR` 日志输出
> 模型管理参见 [内置模型管理](../核心功能/内置模型管理.md)
## 4. 没有图片或者显示无效的图片链接?
1. 确认多模态功能已正确配置(知识库设置 → 高级设置 → 多模态功能)
2. 确认 MinIO 服务已启动
3. 检查 MinIO Bucket 权限
4. 配置 `MINIO_PUBLIC_ENDPOINT`(如需从其他设备访问)
**重要**:Bucket 名称不要包含特殊字符;如无法修改权限,可填入不存在的 bucket 名称,系统会自动创建。
## 5. 平台兼容性说明
`OCR_BACKEND=paddle` 在部分平台上可能无法正常运行。
- **方案一**:关闭 OCR 识别(删除 `OCR_BACKEND` 配置)
- **方案二**:使用外部 OCR 模型(推荐)— 配置 `OCR_BACKEND=vlm`
## 6. 如何使用数据分析功能?
- **智能推理**:需在工具配置中勾选「查看数据元信息」和「数据分析」
- **快速问答智能体**:无需手动选择工具
### 注意事项
- 仅支持 CSV 和 Excel 格式
- 仅支持只读查询(SELECT、SHOW 等)
## 7. 页面里刚保存的配置几秒后又消失了?
通常是浏览器代理、缓存或插件干扰导致。建议:
1. 关闭浏览器代理和抓包工具
2. 强制刷新或使用无痕窗口
3. 检查 Network 面板确认请求未被代理改写
## 8. SSRF 校验白名单
`SSRF_WHITELIST` 配置项用于绕过常规 SSRF 限制,支持:精确域名、通配域名、IPv4/IPv6、CIDR。
```bash
# SSRF_WHITELIST=internal.service,*.corp.example,172.16.0.0/12
```
> 生产环境请谨慎配置。搜索引擎的 API 端点硬编码策略参见 [添加网络搜索引擎](../集成扩展/添加网络搜索引擎.md)
## 相关主题
- [开发指南](../开发部署/开发指南.md) — 开发环境问题排查
- [开启知识图谱功能](../核心功能/开启知识图谱功能.md) — 知识图谱功能故障排查
- [内置模型管理](../核心功能/内置模型管理.md) — 模型配置问题
- [IM集成开发](../集成扩展/IM集成开发.md) — IM 集成相关问题
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [开发指南](../开发部署/开发指南.md) — 开发环境搭建与问题排查
- [开启知识图谱功能](../核心功能/开启知识图谱功能.md) — 知识图谱功能相关故障排查
- [内置模型管理](../核心功能/内置模型管理.md) — 模型配置相关问题
- [快速开发模式](../开发部署/快速开发模式.md) — 开发模式相关问题
- [添加网络搜索引擎](../集成扩展/添加网络搜索引擎.md) — SSRF 白名单与搜索 API 安全策略

View File

@ -1,130 +0,0 @@
---
title: IM集成开发
tags: [集成扩展, IM, 企微, 飞书, Lark, Slack, Telegram, 钉钉, Mattermost]
aliases: [IM集成, IM开发, 企业微信, 即时通讯]
source: IM集成开发文档.md
---
# IM 集成开发
WeKnora 的 IM 集成模块将企业即时通讯平台(企业微信、飞书、Lark、Slack、Telegram、钉钉、Mattermost)接入 WeKnora 知识问答管道,支持在 IM 中直接向 AI 提问并获得实时流式回答。
IM 渠道绑定到 Agent,一个 Agent 可接入多个 IM 渠道。
> IM 渠道中的 Agent 可以使用 [MCP 工具](../核心功能/MCP功能使用说明.md) 和 [Skills 技能](../核心功能/Agent技能系统.md)
## 支持的平台
| 平台 | WebSocket 模式 | Webhook 模式 | 流式输出 |
|------|:-:|:-:|:-:|
| 企业微信 | ✅ | ✅ | ✅ |
| 飞书 | ✅ | ✅ | ✅ (CardKit) |
| Lark(飞书国际版) | ✅ | ✅ | ✅ (CardKit) |
| Slack | ✅ (Socket Mode) | ✅ (Events API) | ✅ |
| Telegram | ✅ (长轮询) | ✅ | ✅ |
| 钉钉 | ✅ (Stream) | ✅ | ✅ (AI 卡片) |
| Mattermost | — | ✅ | ✅ |
## 快速接入指南
### 前置条件
- WeKnora 已部署并运行
- 已创建至少一个 Agent(自定义智能体)
- Agent 已配置好模型和知识库
> Agent 配置模型参见 [内置模型管理](../核心功能/内置模型管理.md)
### 企业微信接入
提供两种模式:
- **WebSocket 模式**(智能机器人,推荐)— 无需公网域名
- **Webhook 模式**(自建应用)— 需要公网回调地址
### 飞书接入
- **WebSocket 模式**(推荐)— 无需公网域名
- **Webhook 模式** — 需要公网回调地址
> 飞书同时也是数据源导入的支持平台,参见 [数据源导入开发](数据源导入开发.md)
### Lark 接入
Lark 是飞书的国际版,IM 接口一致,与飞书共用同一套适配器。接入步骤基本相同,但开放平台
与**权限清单**不同:
- 飞书:<https://open.feishu.cn/>
- Lark:<https://open.larksuite.com/>
> **权限不可套用飞书的清单**:飞书清单混入了数据源连接器(Wiki 同步)用的权限,其中部分在
> Lark 并不存在,整份导入会失败。Lark 只需 IM 相关的 6 项,见
> [IM集成开发文档 — Lark 权限配置](../../IM集成开发文档.md#lark-权限配置)。
> 两朵云的应用互不通用,凭证只在创建它的那朵云上有效。
### Slack 接入
- **Socket Mode**(推荐)— 无需公网域名
- **Events API** — 需要公网回调地址
### Telegram 接入
- **长轮询模式**(推荐)— 无需公网域名
- **Webhook 模式** — 需要 HTTPS 公网回调
### 钉钉接入
- **Stream 模式**(推荐)— 无需公网域名
- **Webhook 模式** — 需要公网回调地址
### Mattermost 接入
- 仅支持 **Webhook 模式**(出站 Webhook + REST API v4)
## 架构设计
系统采用 **Adapter Pattern**,每个平台实现 `im.Adapter` 接口,通过 `AdapterFactory` 动态创建。核心设计模式包括:
| 模式 | 用途 |
|------|------|
| Adapter Pattern | 统一不同 IM 平台的差异 |
| Factory Pattern | 从数据库渠道配置动态创建 Adapter |
| Command Pattern | 可插拔的斜杠指令系统 |
| Producer-Consumer | QA 队列 + Worker Pool |
## 斜杠指令系统
| 指令 | 说明 |
|------|------|
| `/help` | 显示所有可用指令 |
| `/info` | 查看当前绑定智能体信息 |
| `/search` | 对知识库执行混合检索 |
| `/stop` | 取消当前 QA 请求 |
| `/clear` | 清空当前对话记忆 |
## 扩展新平台
接入新的 IM 平台只需 3 步:
1. 实现 `im.Adapter` 接口(可选 `StreamSender`、`FileDownloader`)
2. 注册适配器工厂
3. 前端添加平台选项
> 扩展开发模式与 [添加网络搜索引擎](添加网络搜索引擎.md) 和 [集成向量数据库](集成向量数据库.md) 类似
## 相关主题
- [数据源导入开发](../集成扩展/数据源导入开发.md) — 飞书数据源同步(共享飞书应用凭证)
- [MCP功能使用说明](../核心功能/MCP功能使用说明.md) — Agent 可调用 MCP 工具
- [Agent技能系统](../核心功能/Agent技能系统.md) — Agent 可使用 Skills 技能
- [开发指南](../开发部署/开发指南.md) — 开发环境搭建
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [数据源导入开发](../集成扩展/数据源导入开发.md) — 同样涉及飞书集成,可共享应用凭证
- [MCP功能使用说明](../核心功能/MCP功能使用说明.md) — IM 中 Agent 可调用 MCP 工具
- [Agent技能系统](../核心功能/Agent技能系统.md) — IM 中 Agent 可使用 Skills
- [版本路线图](../项目概述/版本路线图.md) — IM 集成已完成的里程碑

View File

@ -1,121 +0,0 @@
---
title: 数据源导入开发
tags: [集成扩展, 数据源, 飞书, 钉钉, 同步, 连接器]
aliases: [数据源导入, DataSource, 数据同步]
source: 数据源导入开发文档.md
---
# 数据源导入开发
WeKnora 的数据源导入模块支持从外部平台(飞书、钉钉、企业微信、Notion、Confluence 等)自动导入和同步内容到知识库。用户可配置数据源连接,选择需要同步的资源,并通过手动触发或定时调度自动完成内容的增量/全量同步。
数据源绑定到知识库,一个知识库可接入多个数据源。凭证使用 AES-256-GCM 加密存储。
> 数据源导入与 [IM集成开发](../集成扩展/IM集成开发.md) 都涉及飞书集成,可考虑共享飞书应用凭证
## 当前支持的连接器
| 连接器 | 认证方式 | 增量同步 | 删除同步 |
|--------|---------|:-:|:-:|
| 飞书 (Feishu) | OAuth2 (Tenant Access Token) | ✅ | ✅ |
| 钉钉文档 (DingTalk Docs) | OAuth2 (App Access Token) | ✅ | ✅ |
## 快速接入:飞书知识库
1. 创建飞书应用,获取 App ID / App Secret
2. 开通权限:`wiki:wiki:readonly`、`drive:drive:readonly`、`drive:export:readonly`、`docx:document:readonly`
3. 在知识库设置页添加数据源,选择飞书,填写凭证
4. 测试连接,选择知识库空间,配置同步策略
5. 触发首次同步验证
> 注意:飞书国际版(Lark)同样支持,自动适配 `https://open.larksuite.com` 的 API 地址
## 快速接入:钉钉文档
1. 创建并发布钉钉企业内部应用
2. 开通权限:`Wiki.Workspace.Read`、`Wiki.Node.Read`、`Storage.File.Read`
3. 添加“钉钉文档”数据源,填写 Client ID、Client Secret、操作人 Union ID
4. 测试连接,按知识库空间、文件夹或单篇文档选择范围
5. 触发首次同步;当前仅同步 `ALIDOC/adoc` 在线文档
连接器只使用公开 OpenAPI,将文档 Block 转换为 Markdown,不依赖灰度导出接口。增量版本优先使用毫秒 `modifiedTimestamp`;Blocks 接口只返回一级块,空容器会标记 `nested_blocks_unavailable`。测试连接会探测节点列表和样本文档读取。全量同步也会对照上次游标对账删除。目录读取不完整或文档抓取失败时会保留原游标,避免误删并允许下次重试。
同步以所有已选范围的可见文档集合统一判断删除,文档在已选文件夹之间移动不会触发删除。
某个范围不可访问或已选节点失效时,其他正常范围继续同步,失败范围保留旧游标;在所有范围
恢复可完整读取之前,暂缓删除并保留待核对记录。正文抓取失败的文档也会在后续同步重试。
失效的单篇文档或文件夹选择需要检查权限,必要时重新选择资源,不能直接将不可见等同于源端删除。
开启“同步删除”后,确认源端删除的文档会从 WeKnora 知识库移除;关闭该开关则保留本地内容。
钉钉配置和同步失败提示覆盖中文、英语、日语、韩语、俄语。
## 飞书 docx 解析模式与环境变量
飞书新版云文档(docx)的解析路径由环境变量 `FEISHU_DOCX_PARSE_MODE` 控制(作用于 app 服务,对飞书知识库和飞书云盘两个连接器同时生效):
| 模式 | 值 | 解析路径 | 图片与文档关联 | 速度 | docx 内附件 |
|---|---|---|---|---|---|
| export(默认) | 留空 / `export` | 异步导出 -> .docx 二进制 -> docreader 解析 | ✅ 图片 inline 进父文档,`parent_chunk_id` 关联 | 慢 | 丢失 |
| blocks | `blocks` | blocks API -> Markdown | ❌ 图片作为独立知识条目,与文档割裂 | 快 | 保留 |
**优缺点对比:**
- **export**:导出 .docx 交 docreader 解析,图片 inline 进父文档(与普通 docx 上传一致),通过 `parent_chunk_id` 建立同知识条目父子关联,三个场景都能关联图片内容;代价是同步变慢(异步导出 + docx 解析)、docx 内附件丢失、图片 OCR/caption 依赖多模态配置。
- **blocks**:图片 block 渲染成空 `![图片]()` 占位符,图片单独下载成独立知识条目,检索 / Wiki / 智能体无法把图片内容关联回文档;但同步快、保留 docx 内 file block 附件。
配置方法:默认即为 export,无需设置;需要 blocks 模式时在 `.env` 或 `docker-compose.yml` 的 app 服务环境变量中设置 `FEISHU_DOCX_PARSE_MODE=blocks`,重启 app 服务生效。详见 [飞书云盘数据源接入说明](飞书云盘数据源接入说明.md#6-docx-解析模式与环境变量)。
## 架构设计
```
外部平台 API → Connector → ConnectorRegistry → DataSourceService → WeKnora Core (知识入库管道)
```
核心设计模式:
| 模式 | 用途 |
|------|------|
| Adapter Pattern | 统一不同平台的差异 |
| Registry Pattern | 按类型动态查找连接器 |
| Strategy Pattern | SyncMode(增量/全量)、ConflictStrategy(覆盖/跳过) |
| Cursor-based Pagination | 增量同步基于 SyncCursor 跟踪变更 |
## 关键概念
- **DataSource** — 数据源:外部平台连接与知识库的绑定
- **Connector** — 连接器:与外部平台交互的适配层
- **SyncCursor** — 同步游标:增量同步的状态标记
- **FetchedItem** — 拉取到的文档条目
## API 端点
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/datasource/types` | 获取可用连接器类型 |
| POST | `/api/v1/datasource/validate-credentials` | 验证凭证 |
| POST | `/api/v1/datasource` | 创建数据源 |
| GET | `/api/v1/datasource?kb_id=xxx` | 列出数据源 |
| POST | `/api/v1/datasource/:id/sync` | 手动触发同步 |
| POST | `/api/v1/datasource/:id/pause` | 暂停 |
| POST | `/api/v1/datasource/:id/resume` | 恢复 |
## 扩展新连接器
1. 实现 `Connector` 接口(Validate、ListResources、FetchAll、FetchIncremental)
2. 注册连接器到 `ConnectorRegistry`
3. 前端添加配置
> 扩展开发模式与 [添加网络搜索引擎](../集成扩展/添加网络搜索引擎.md) 和 [集成向量数据库](../集成扩展/集成向量数据库.md) 类似
## 相关主题
- [IM集成开发](../集成扩展/IM集成开发.md) — IM 渠道中的飞书集成
- [共享空间说明](../安全认证/共享空间说明.md) — 知识库共享机制
- [常见问题](../运维排障/常见问题.md) — 数据源同步相关故障排查
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [IM集成开发](../集成扩展/IM集成开发.md) — 同样涉及飞书集成,可共享应用凭证
- [共享空间说明](../安全认证/共享空间说明.md) — 知识库共享与数据源导入互补
- [添加网络搜索引擎](../集成扩展/添加网络搜索引擎.md) — 同类扩展开发模式

View File

@ -1,102 +0,0 @@
---
title: 添加网络搜索引擎
tags: [集成扩展, 搜索, 网络搜索, Provider]
aliases: [网络搜索, WebSearch, 搜索引擎扩展]
source: 添加新的网络搜索引擎.md
---
# 添加新的网络搜索引擎
本文档说明如何在 WeKnora 中添加一个新的网络搜索引擎类型(如 Brave Search、Searx 等)。
## 架构概述
搜索引擎的 API 端点**硬编码**在代码中,不向用户暴露 BaseURL,从源头消除 SSRF 风险。
```
internal/types/web_search_provider.go # 实体定义 + Provider 类型元数据
internal/infrastructure/web_search/ # Provider 实现(bing/google/duckduckgo/tavily)
internal/container/container.go # DI 注册
internal/types/interfaces/web_search.go # WebSearchProvider 接口
```
> 类似的扩展开发模式参见 [集成向量数据库](../集成扩展/集成向量数据库.md)
## 步骤
以添加 **Brave Search** 为例:
### 1. 注册类型常量
在 `internal/types/web_search_provider.go` 中添加:
```go
WebSearchProviderTypeBrave WebSearchProviderType = "brave"
```
### 2. 添加类型元数据
在 `GetWebSearchProviderTypes()` 中添加:
```go
{
ID: "brave", Name: "Brave Search", Free: false,
RequiresAPIKey: true, Description: "Brave Search API",
DocsURL: "https://brave.com/search/api/",
}
```
### 3. 创建 Provider 实现
新建 `internal/infrastructure/web_search/brave.go`:
- 构造函数签名:`func(types.WebSearchProviderParameters) (interfaces.WebSearchProvider, error)`
- API 端点**硬编码**为常量
- 实现 `interfaces.WebSearchProvider` 接口:`Name()` 和 `Search()`
### 4. 添加参数校验
在 `isValidProviderType()` 中添加新类型。
### 5. DI 注册
在 `registerWebSearchProviders` 中注册。
### 6. 验证
```bash
go build ./...
# 调用 API 验证
curl http://localhost:8080/api/v1/web-search-providers/types
```
## 需要额外参数的情况
如果新引擎需要 API Key 以外的参数:
- **方式一**:使用 `WebSearchProviderParameters.ExtraConfig` 字段
- **方式二**:在 `WebSearchProviderParameters` 中添加专用字段
## 文件变更清单
| 文件 | 操作 |
|------|------|
| `internal/types/web_search_provider.go` | 添加常量 + 类型元数据 |
| `internal/infrastructure/web_search/brave.go` | **新建** Provider 实现 |
| `internal/application/service/web_search_provider.go` | `isValidProviderType` 加新类型 |
| `internal/container/container.go` | `registerWebSearchProviders` 注册 |
## 相关主题
- [集成向量数据库](../集成扩展/集成向量数据库.md) — 同类扩展开发模式(接口实现 + 注册 + DI)
- [MCP功能使用说明](../核心功能/MCP功能使用说明.md) — MCP 也可集成搜索工具
- [常见问题](../运维排障/常见问题.md) — SSRF 白名单配置
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [集成向量数据库](../集成扩展/集成向量数据库.md) — 同类扩展开发模式
- [MCP功能使用说明](../核心功能/MCP功能使用说明.md) — MCP 搜索工具与网络搜索引擎互补
- [版本路线图](../项目概述/版本路线图.md) — 路线图中的社区组件扩展方向

View File

@ -1,123 +0,0 @@
---
title: 集成向量数据库
tags: [集成扩展, 向量数据库, 检索引擎, 扩展]
aliases: [向量数据库, VecDB, 向量检索, RetrieveEngine]
source: 使用其他向量数据库.md
---
# 集成新的向量数据库
本文提供了向 WeKnora 项目添加新向量数据库支持的完整指南。通过实现标准化接口和遵循结构化流程,开发者可以高效地集成自定义向量数据库。
> 类似的扩展开发模式参见 [添加网络搜索引擎](../集成扩展/添加网络搜索引擎.md)
## 集成流程
### 1. 实现基础检索引擎接口
```go
type RetrieveEngine interface {
EngineType() types.RetrieverEngineType
Retrieve(ctx context.Context, params types.RetrieveParams) ([]*types.RetrieveResult, error)
Support() []types.RetrieverType
}
```
### 2. 实现存储层接口
实现 `RetrieveEngineRepository` 接口,扩展基础检索引擎能力,添加索引管理功能:
- `Save` / `BatchSave` — 保存索引
- `EstimateStorageSize` — 估算存储空间
- `DeleteByChunkIDList` / `DeleteByKnowledgeIDList` — 删除索引
- `CopyIndices` — 复制索引
### 3. 实现服务层接口
创建 `RetrieveEngineService` 实现,负责索引创建和管理的业务逻辑。
### 4. 添加环境变量配置
```
RETRIEVE_DRIVER=postgres,elasticsearch_v8,your_database
YOUR_DATABASE_ADDR=host:port
YOUR_DATABASE_USERNAME=username
YOUR_DATABASE_PASSWORD=password
```
### 5. 注册检索引擎
在 `internal/container/container.go` 的 `initRetrieveEngineRegistry` 中添加初始化与注册逻辑。
### 6. 定义检索引擎类型常量
在 `internal/types/retriever.go` 中添加新的引擎类型常量。
## 参考实现
建议参考现有实现:
- PostgreSQL: `internal/application/repository/retriever/postgres/`
- ElasticsearchV7: `internal/application/repository/retriever/elasticsearch/v7/`
- ElasticsearchV8: `internal/application/repository/retriever/elasticsearch/v8/`
- Apache Doris 4.1: `internal/application/repository/retriever/doris/`
- Tencent VectorDB: `internal/application/repository/retriever/tencentvectordb/`
## Apache Doris 4.1 集成要点
Doris 是 MPP 风格的分析型 SQL 库,其接入方式与 NoSQL 向量库有几处特殊点:
- **协议**:MySQL 协议(FE 9030)走主链路;HTTP API(FE 8030)走 Stream Load partial update。
- **表结构**:每维度一张 `<DORIS_TABLE_PREFIX>_<dim>` 表,`UNIQUE KEY(id)` + `enable_unique_key_merge_on_write=true`。
- **索引**:INVERTED 索引覆盖过滤字段、`content` 字段使用 `chinese` parser;ANN 索引使用 HNSW + cosine_distance(异步构建,建表后自动轮询 30s 等待 `FINISHED`)。
- **分数语义**:使用 `1 - cosine_distance_approximate(...)`,threshold 比较 `>=`、`ORDER BY DESC`,与 Qdrant cosine 相似度方向一致。
- **关键词检索**:基于 Doris 倒排索引的 `MATCH_ANY`,无需在 Go 端做 jieba 分词。
- **批量字段更新**:`BatchUpdateChunkEnabledStatus` 与 `BatchUpdateChunkTagID` 通过 Stream Load partial update 协议实现,支持 1MiB 自动分批。
环境变量:
```
RETRIEVE_DRIVER=doris
DORIS_ADDR=doris-fe:9030
DORIS_HTTP_PORT=8030
DORIS_DATABASE=weknora
DORIS_USERNAME=root
DORIS_PASSWORD=
DORIS_TABLE_PREFIX=weknora_embeddings
```
启动方式:`docker compose --profile doris up -d`,然后在 FE 上 `CREATE DATABASE weknora;`。
## Tencent VectorDB
WeKnora 内置 Tencent VectorDB 适配器,驱动名为 `tencent_vectordb`。该适配器支持向量检索、基于 BM25 sparse vector 的关键词检索和索引管理,可参与 WeKnora 上层混合检索。
```env
RETRIEVE_DRIVER=tencent_vectordb
TENCENT_VECTORDB_ADDR=http://your-instance.tencentvectordb.com
TENCENT_VECTORDB_USERNAME=root
TENCENT_VECTORDB_API_KEY=your_tencent_vectordb_api_key
TENCENT_VECTORDB_DATABASE=weknora
TENCENT_VECTORDB_COLLECTION=weknora_embeddings
TENCENT_VECTORDB_REPLICA_NUMBER=1
```
`TENCENT_VECTORDB_COLLECTION` 是集合名前缀。WeKnora 会按向量维度创建实际集合,例如 `weknora_embeddings_768`。
`TENCENT_VECTORDB_REPLICA_NUMBER` 是创建集合时使用的副本数,默认 `1`;单节点 QA 环境可设为 `0`,生产环境可按 Tencent VectorDB 集群规模调整。
关键词检索依赖 Tencent VectorDB sparse vector 索引。新建集合会自动创建 `sparse_vector` 索引;旧版本已创建的向量集合如果没有该索引,需要重建集合并重新导入知识库数据后才能启用关键词检索。
## 相关主题
- [添加网络搜索引擎](../集成扩展/添加网络搜索引擎.md) — 同类扩展开发模式(接口实现 + 注册 + DI)
- [知识图谱](../核心功能/知识图谱.md) — 知识图谱功能依赖 Neo4j 而非向量数据库
- [常见问题](../运维排障/常见问题.md) — Embedding 模型配置与向量维度相关
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [添加网络搜索引擎](../集成扩展/添加网络搜索引擎.md) — 同类扩展开发模式
- [知识图谱](../核心功能/知识图谱.md) — 另一种知识检索方式(基于图而非向量)
- [版本路线图](../项目概述/版本路线图.md) — 路线图中的检索能力扩展方向

View File

@ -1,167 +0,0 @@
# 飞书云盘数据源使用说明
飞书云盘数据源(`feishu_drive` / `lark_drive`)可以把飞书/Lark 云盘某个文件夹下的文档和文件自动同步到 WeKnora 知识库,支持增量同步、定时同步和子文件夹递归。
---
## 1. 前置条件:创建飞书应用
1. 登录[飞书开放平台](https://open.feishu.cn/app)(Lark 用户使用 [Lark 开放平台](https://open.larksuite.com/app)),创建**企业自建应用**。
2. 记录应用的 **App ID**(`cli_` 开头)和 **App Secret**,配置数据源时需要填写。
3. 按下节表格开通权限,并**发布应用版本**(权限修改后必须重新发布才生效)。
> 注意:飞书(open.feishu.cn)和 Lark(open.larksuite.com)是两个独立体系,应用不通用。同步飞书云盘用飞书应用,同步 Lark Drive 用 Lark 应用,凭据不能混用。
---
## 2. 所需权限(详细)
在应用后台「权限管理」中开通以下 **3 个权限**:
| 权限标识 | 名称 | 用途 | 缺少时的表现 |
|---|---|---|---|
| `drive:drive:readonly` | 查看云空间中的文件 | 列举文件夹内容(list API)、下载云盘普通文件 | 加载文件夹/同步时报 403,提示「需先将文件夹分享给应用所在的群」 |
| `drive:export:readonly` | 导出云文档 | 把 docx/doc/sheet/bitable 导出为 docx/xlsx 再解析 | 云文档类文件同步失败 |
| `docx:document:readonly` | 读取新版文档内容 | 通过 blocks API 解析 docx 文档正文与附件(导出失败时的主路径) | docx 文档解析失败或回退导出也失败 |
说明:
- 与「飞书知识库」连接器相比,云盘**不需要** `wiki:wiki:readonly`,其余权限相同。
- list API 本身还接受 `drive:drive`(读写)或 `space:document:retrieve` 作为替代,但推荐只开只读的 `drive:drive:readonly`,最小授权。
- 权限开通后必须**创建并发布新版本**,否则接口仍报无权限。
---
## 3. 关键一步:把文件夹分享给应用
飞书的权限模型要求:即使应用开通了上述 API 权限,也只能访问**被显式分享给它的文件**。
1. 创建一个飞书(Lark)群或复用某个飞书(Lark)群
2. 将需要导入的**飞书云盘管理者**拉进群
> PS: 不拉进群也会导致没有访问权限
3. 在飞书云盘中打开目标文件夹;
4. 点击「分享」/「··· → 添加协作者」,把文件夹分享给**应用所在的群**(把应用拉进一个群,再将文件夹分享给该群),权限给「可阅读」即可;
5. 子文件夹和其中的文件会随父文件夹一起获得授权,无需逐个分享;
6. 如果之后新增的文件同步报 403,检查该文件是否在这棵已分享的目录树下。
这是一次性操作,但不做的话,加载文件夹会直接报「应用无权访问该文件夹」。
---
## 4. 配置数据源(四步)
入口:知识库 → 设置 → 数据源 → 新建数据源,选择「飞书云盘」。
### 第 1 步:选择类型
选择「飞书云盘」(国际版选「Lark Drive」)。
### 第 2 步:配置凭证
填写 App ID 和 App Secret,点击下一步时系统会自动测试连接(验证 tenant_access_token 能否获取)。此步只验证应用身份,不验证文件夹权限。
### 第 3 步:选择范围
1. 在「云盘文件夹 Token」输入框填入目标文件夹的 `folder_token`,**或直接粘贴文件夹的完整链接**(飞书 `https://xxx.feishu.cn/drive/folder/<token>` 或 Lark `https://xxx.larksuite.com/drive/folder/<token>`,系统按路径自动提取 token,两种链接都支持);
2. 点击「加载」,列出该文件夹下的完整目录树;
3. 勾选要同步的文件/文件夹,支持逐级展开、全选/折叠分支。
注意:
- **不支持云空间根目录**(根目录不分页且不返回快捷方式),必须选择具体文件夹;
- 加载失败时按提示处理:403 → 回到第 3 节分享文件夹;token 无效 → 重新从文件夹 URL 复制。
### 第 4 步:同步策略
| 配置项 | 说明 | 默认值 |
|---|---|---|
| 同步计划 | cron 表达式,默认每 6 小时一次;留空则只手动触发 | `0 0 */6 * * *` |
| 同步模式 | 增量(按修改时间游标)/ 全量 | 增量 |
| 冲突策略 | 内容变更时覆盖 / 跳过 | 覆盖 |
| 同步删除 | 源端删除的文档**只计数,不自动删除知识库内容**,需在知识库手动删除 | 开启 |
保存后数据源开始按策略运行,也可在数据源卡片上手动「触发同步」。
---
## 5. 支持的文件类型
| 云盘类型 | 处理方式 |
|---|---|
| `docx` / `doc`(新旧文档) | blocks API 解析正文与附件,失败时回退导出为 docx 解析 |
| `sheet` / `bitable`(表格/多维表格) | 导出为 xlsx 解析 |
| `file`(普通上传文件,如 PDF/PPT/图片) | 直接下载后按文件类型解析 |
| `shortcut`(快捷方式) | 自动解析为目标文件同步(快捷方式不能指向文件夹) |
| `folder`(文件夹) | 递归遍历 |
| `mindnote` / `slides` / `board` | 不支持,跳过 |
补充行为:
- docx 中的**附件**会作为独立知识条目同步(与父文档关联,父文档更新时自动清理已移除的附件);
- 文档内嵌图片会尝试 OCR/多模态解析,未配置对象存储或 VLM 时自动跳过,不影响正文同步。
---
## 6. docx 解析模式与环境变量
飞书新版云文档(docx)有两种解析路径,由环境变量 `FEISHU_DOCX_PARSE_MODE` 控制。该变量作用于 WeKnora **app 服务**(不是数据源配置),对飞书云盘和飞书知识库两个连接器同时生效。
### 模式对比
| | export(默认) | blocks |
|---|---|---|
| 环境变量值 | 留空 / `export` | `blocks` |
| 解析路径 | 异步导出 API -> .docx 二进制 -> docreader 解析 | blocks API -> Markdown |
| 图片与文档关联 | ✅ 图片 inline 进父文档,`parent_chunk_id` 关联 | ❌ 图片作为独立知识条目,与文档割裂 |
| 检索 / Wiki / 智能体能否关联图片 | 是 | 否 |
| 同步速度 | 慢(异步导出 + docx 解析) | 快 |
| docx 内附件(file block) | 丢失(.docx 导出不含) | 保留,作为独立条目 |
| 所需权限 | `drive:drive:readonly` + `drive:export:readonly` | `drive:drive:readonly` + `drive:export:readonly` + `docx:document:readonly` |
### 为什么图片关联有差异
- **export 模式**:导出 .docx 后由 docreader 解析,图片 inline 进父文档(与普通 docx 上传一致),通过 `parent_chunk_id` 建立同知识条目的父子关联,三个场景都能在一次检索中把图片内容与文档一起返回。
- **blocks 模式**:走 blocks API,图片 block 渲染成空 `![图片]()` 占位符,图片单独下载成独立知识条目,与父文档只有元数据级弱关联。WeKnora 的检索、Wiki 构建、智能体问答链路都不会把图片内容关联回文档,图片和正文是割裂的。
### 配置方法
在 WeKnora 服务的 `.env` 或 `docker-compose.yml` 的 app 服务环境变量中设置:
```env
FEISHU_DOCX_PARSE_MODE=blocks
```
不设置或设为 `export` 即用默认模式。修改后需重启 app 服务生效。
### export 模式的代价
- **同步变慢**:每个 docx 都要走异步导出(创建任务 + 轮询 + 下载)+ docreader 解析,比 blocks API 慢。
- **附件丢失**:docx 内 file block 附件不随 .docx 导出下载,如需附件用 blocks 模式或单独同步。
- **图片内容依赖多模态**:图片 inline 后 OCR/caption 由多模态服务异步生成,未配置对象存储或 VLM 时图片只存储不生成内容(前端展示正常,但检索层面仍弱)。
### 选择建议
- 需要图片内容在检索 / Wiki / 智能体中与文档关联:用默认 **export**。
- 只需文档正文、要保留附件、追求同步速度:用 **blocks**。
---
## 7. 同步行为说明
- **增量同步**:以文件修改时间为游标,只拉取上次同步后变更的内容;中断后从断点续传。
- **部分失败不中断**:某个子文件夹无权限或某个文件下载失败时,该条目记为失败,其余内容继续同步,失败明细可在「同步日志」中查看。
- **更新语义**:内容变更的文件会先删除旧知识条目再重建,解析期间该文档短暂不可用,属正常现象。
- **安全约束**:为避免误删,源端删除的文件不会自动从知识库移除(见第 4 步「同步删除」)。
---
## 8. 常见问题
| 现象 | 原因与处理 |
|---|---|
| 「请输入具体文件夹的 folder_token,不支持云空间根目录」 | 输入为空或粘贴的是根目录链接,换具体文件夹链接 |
| 「应用无权访问该文件夹。请…分享给应用所在的群」 | 未完成第 3 节的分享,或分享的对象不是应用所在的群 |
| 「应用凭证无效或缺少云盘权限」 | App ID/Secret 错误,或第 2 节权限未开通/未发布版本 |
| 「folder_token 不存在或已删除」 | token 复制有误,从文件夹「分享 → 复制链接」重新获取 |
| 同步日志中部分条目失败 | 点开日志看失败阶段:`list_children` 多为子文件夹未授权,`fetch` 多为单文件权限或类型不支持 |
| 知识列表中来源显示 | 云盘同步的文档来源标记为「飞书云盘」,与知识库同步的「飞书」区分 |

View File

@ -1,37 +0,0 @@
---
title: Lite与标准版区别
tags: [项目概述, 部署, Lite]
aliases: [Lite, LITE, 标准版区别]
source: LITE.md
---
# Lite 与标准版区别
Lite 面向希望快速在本地使用、部署尽量简单的场景;标准版面向多空间协作与完整企业能力。主要差异如下。
| 维度 | Lite | 标准版 |
|------|------|--------|
| **共享空间** | 不提供共享空间(成员邀请、跨成员共享知识库与智能体等) | 提供共享空间及空间隔离检索等协作能力 |
| **空间与账号** | 单空间;开箱即用,**无需注册** | 多空间;通常需要注册、登录与组织管理 |
| **文档解析** | 内置仅 **Simple** 类型解析引擎;可通过 **Cloud** 等方式接入其他解析能力 | 可配置多种解析引擎(含高精度等),与完整文档处理链路集成 |
| **部署形态** | **单应用、零依赖**(不依赖独立的数据库、消息队列等外部服务栈) | 典型为 Docker Compose 等多服务部署,依赖与组件更多 |
| **数据归属** | 数据**完全在本地**存储与处理 | 私有化部署时数据也可在本地;具体取决于你的部署方式 |
| **网络暴露** | **默认仅本机访问**;可按需配置,**选择是否放行到公网** | 按部署与安全策略自行绑定地址与网关 |
> 若你不需要多团队协作、复杂解析流水线与多服务架构,Lite 更适合个人或小团队在本机零依赖试用;需要共享空间、多空间与完整解析引擎矩阵时,请使用标准版。
## 相关主题
- 共享空间的详细说明参见 [共享空间说明](../安全认证/共享空间说明.md) — 标准版独有功能
- 认证体系参见 [OIDC认证调用流程](../安全认证/OIDC认证调用流程.md) — 标准版多空间 OIDC 登录
- 开发环境搭建参见 [开发指南](../开发部署/开发指南.md)
- 部署相关 FAQ 参见 [常见问题](../运维排障/常见问题.md)
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [版本路线图](版本路线图.md) — 路线图中的轻量化部署方向
- [共享空间说明](../安全认证/共享空间说明.md) — Lite 不支持的共享空间功能的详细说明
- [OIDC认证调用流程](../安全认证/OIDC认证调用流程.md) — 标准版多空间场景下的认证方式

View File

@ -1,83 +0,0 @@
---
title: 版本路线图
tags: [项目概述, 路线图, 规划]
aliases: [ROADMAP, Roadmap]
source: ROADMAP.md
---
# 版本路线图
本文档描述 WeKnora 的产品规划与计划方向,会随项目进展持续更新。
## 轻量化部署
- [ ] WeKnora 官方提供原子化调用接口(Embedding、ReRank、LLM、文档解析等),并提供一定免费使用额度
- [ ] WeKnora 官方提供完整云端服务,用户可在平台上直接体验 WeKnora 能力
- [ ] 推出 WeKnora Lite 版本,供私有化部署需求不强的用户快速体验产品能力
> 关于 Lite 版本的详细差异,参见 [Lite与标准版区别](Lite与标准版区别.md)
## 知识理解
- [x] 抽象整体文档解析模块,支持切换内置解析、MinerU 或其它解析方式
- [ ] 优化文档分块策略,除规则分块外支持语义分块、章节分块等
- [ ] 文档结构可视化:展示解析后的文档章节结构、图谱关系等
- [ ] 支持音视频等更多文档格式,增强多模态理解能力
> 知识图谱相关功能参见 [知识图谱](../核心功能/知识图谱.md) 与 [开启知识图谱功能](../核心功能/开启知识图谱功能.md)
## 检索与总结
- [ ] 支持在输入框中通过「@标签」指定检索范围
- [ ] 支持在输入框中上传图片、附件进行检索
- [x] 支持对话框中上传图片
- [ ] 支持对话框中上传附件
> 检索引擎扩展参见 [集成向量数据库](../集成扩展/集成向量数据库.md)
## 知识库相关模型训练
- [ ] 训练与检索召回相关的模型(Embedding、ReRank、LLM 等)
- [ ] 在文档解析与文档理解方面持续探索,推进自研相关模型
> 模型管理参见 [内置模型管理](../核心功能/内置模型管理.md)
## 知识库形态
- [ ] 扩展知识库形态,支持时序数据的存储与索引
- [ ] 探索知识库与 Memory 结合的应用场景
## IM 集成
- [x] 支持与企微、飞书等 IM 系统集成,在 IM 内使用 WeKnora 能力
> IM 集成开发详见 [IM集成开发](../集成扩展/IM集成开发.md)
## 组件与扩展
- [ ] 鼓励社区维护各厂商的模型服务、网络搜索服务等组件
- [ ] 鼓励社区提供更多与知识库相关的 Skills
> 扩展开发参见 [添加网络搜索引擎](../集成扩展/添加网络搜索引擎.md)、[集成向量数据库](../集成扩展/集成向量数据库.md)、[Agent技能系统](../核心功能/Agent技能系统.md)
## 周边生态建设
- [ ] 提供 Chrome 扩展,支持类似「剪藏」功能
- [ ] 提供小程序插件(具体形态待定)
- [ ] 提供 JS SDK,便于在网页中集成 WeKnora 能力
- [ ] 鼓励社区提供 VSCode、Cursor、Claude Code 等编辑器/IDE 插件
## 文档建设
- [ ] 完善官方文档(使用说明、API、部署等)
- [ ] 鼓励用户贡献文档、博客、视频等,形成社区化文档体系
- [ ] 在知乎平台建设 WeKnora 内容合集
---
## 反向链接
- [Home](../Home.md) — Wiki 首页导航
- [Lite与标准版区别](Lite与标准版区别.md) — Lite 版本定位与路线图中的轻量化部署方向对应
- [内置模型管理](../核心功能/内置模型管理.md) — 路线图中模型训练方向关联内置模型管理
- [IM集成开发](../集成扩展/IM集成开发.md) — 路线图中 IM 集成已完成的里程碑

View File

@ -1,85 +0,0 @@
# Worker Pool Governance
WeKnora uses guaranteed per-stage worker pools plus an elastic pool for the
document ingestion pipeline. Worker concurrency is a scheduling budget, not a
replacement for model quotas, DocReader capacity, vector-store limits, or
database connection limits.
## Topology
| Pool | Default per instance | Queues | Purpose |
| --- | ---: | --- | --- |
| Core | 8 | `default` | Document parsing and manual reparse guarantee |
| Post-process | 2 | `postprocess` | Parse finalization and enrichment fan-out |
| Enrichment | 12 | `summary`, `multimodal`, `graph`, `question` | Model-heavy enrichment guarantee |
| Maintenance | 4 | `sync`, `low` | Source sync, batch work, move/delete/cleanup |
| Shared | 6 | Core and enrichment queues | Elastic capacity borrowed by the side with backlog |
| Wiki | 8 | `wiki` | Independently governed Wiki generation |
The upstream total remains 32 workers per service instance by default. Wiki is
separate and is not included in that total.
Post-process has its own physical queue so lightweight fan-out work cannot sit
behind long DocReader calls. Maintenance is intentionally excluded from the
shared pool because its long-running tasks could pin elastic capacity needed by
the user-facing pipeline.
Asynq dequeue is atomic. Dedicated and shared servers may safely subscribe to
the same core/enrichment queues; one task is still processed by one worker.
## Configuration
All settings are available under System settings and require a service restart:
- `asynq.core_concurrency` / `WEKNORA_ASYNQ_CORE_CONCURRENCY`
- `asynq.postprocess_concurrency` / `WEKNORA_ASYNQ_POSTPROCESS_CONCURRENCY`
- `asynq.enrichment_concurrency` / `WEKNORA_ASYNQ_ENRICHMENT_CONCURRENCY`
- `asynq.maintenance_concurrency` / `WEKNORA_ASYNQ_MAINTENANCE_CONCURRENCY`
- `asynq.shared_concurrency` / `WEKNORA_ASYNQ_SHARED_CONCURRENCY`
- `asynq.wiki_concurrency` / `WEKNORA_WIKI_ASYNQ_CONCURRENCY`
The old aggregate `asynq.concurrency` / `WEKNORA_ASYNQ_CONCURRENCY` setting is
retired. Deployments that set it must migrate to the explicit pool settings.
Persisted old rows are ignored and hidden from the System settings page so they
cannot be mistaken for an effective runtime control.
## Capacity layers
Tune these layers independently:
1. Worker concurrency controls the number of task handlers admitted per
service instance.
2. Model quota governance controls provider concurrency, RPM, and TPM across
replicas and quota groups.
3. DocReader, vector stores, object storage, Postgres, and local CPU/RAM retain
their own resource limits.
If model limiter waiting grows while worker queues are busy, adding workers
only creates more waiters. Increase the provider quota or reduce worker
admission instead.
## Sizing
For each pool, estimate peak required workers using:
```text
required workers = ceil(peak task arrival rate * mean task runtime / 0.70)
```
Use task arrival rate after fan-out. One parsed document can create one summary,
multiple question batches, one graph task per chunk, and multiple image tasks.
Queue count is not a capacity signal.
The runtime dashboard reports:
- configured concurrency per instance;
- live server instance count;
- cluster capacity aggregated from active asynq heartbeats;
- active workers and utilization;
- queue backlog, retries, dead letters, and oldest pending age;
- model concurrency and limiter waiting.
Increase a pool only when backlog age grows while its downstream dependency has
headroom. Reallocate to enrichment when core stays underutilized and fan-out
queues grow. Reduce core admission when DocReader CPU, memory, or latency is the
bottleneck.

View File

@ -1,42 +0,0 @@
# MCP 工具人工审核(危险调用)
对应需求:智能体调用 MCP 工具前可中断,待人工确认后再执行(GitHub #1173)。
## 行为说明
1. 在 **设置 → MCP** 中连接测试成功后,在工具列表上打开 **「需人工审核」** 开关,即可为该工具打标。
2. Agent 运行时若即将调用已打标的工具,会推送 `tool_approval_required` 事件,对话界面展示审批卡片(可编辑 JSON 参数)。
3. 用户 **通过** 或 **拒绝** 后,后端恢复执行;拒绝时工具返回错误信息给模型,不会调用远端 MCP。
4. 若超时未处理(默认 10 分钟,可通过配置 `agent.tool_approval_timeout_seconds` 调整),视为拒绝。
## 配置示例
任选一种:
**1. config.yaml**
```yaml
agent:
tool_approval_timeout_seconds: 600 # 可选,默认 600(秒)
```
**2. 环境变量**(优先级高于 yaml)
```bash
# 支持纯秒数或 Go duration(30s / 5m / 1h)
WEKNORA_AGENT_TOOL_APPROVAL_TIMEOUT=600
```
## API
- `GET /api/v1/mcp-services/:id/tool-approvals` — 列出已保存的审核配置
- `PUT /api/v1/mcp-services/:id/tool-approvals/:tool_name` — 设置某工具是否需审核(`{"require_approval": true}`)
- `POST /api/v1/agent/tool-approvals/:pending_id` — 在审批卡片中提交结果
- body: `{"decision":"approve"|"reject","modified_args":{...}可选,"reason":"..."可选}`
## 部署与限制
- **审批等待状态保存在进程内存** 中:`pending_id` 仅对当前实例有效;进程重启后进行中的等待会失败(表现为拒绝/取消)。
- **多副本部署**:当配置了 `REDIS_ADDR` 时,`Resolve` 会通过 Redis Pub/Sub(频道 `weknora:mcp_approval:resolve`)跨实例转发,因此 SSE 与提交审批的 HTTP 请求落到不同实例也能正确唤醒等待者;未配置 Redis 时退化为单机模式,需要使用会话粘滞(sticky session)。
- **审批等待不会被工具默认 60s 超时取消**:审批阶段使用 round 级别的 ctx(不带 `defaultToolExecTimeout`),仅受 `agent.tool_approval_timeout_seconds` 与请求级取消控制。
- 安全边界:审核通过后的参数仍由当前登录空间提交;请仅在可信环境下授予「通过」权限。

View File

@ -1,298 +0,0 @@
### 如何集成新的向量数据库
本文提供了向 WeKnora 项目添加新向量数据库支持的完整指南。通过实现标准化接口和遵循结构化流程,开发者可以高效地集成自定义向量数据库。
### 集成流程
#### 1. 实现基础检索引擎接口
首先需要实现 `interfaces` 包中的 `RetrieveEngine` 接口,定义检索引擎的核心能力:
```go
type RetrieveEngine interface {
// 返回检索引擎的类型标识
EngineType() types.RetrieverEngineType
// 执行检索操作,返回匹配结果
Retrieve(ctx context.Context, params types.RetrieveParams) ([]*types.RetrieveResult, error)
// 返回该引擎支持的检索类型列表
Support() []types.RetrieverType
}
```
#### 2. 实现存储层接口
实现 `RetrieveEngineRepository` 接口,扩展基础检索引擎能力,添加索引管理功能:
```go
type RetrieveEngineRepository interface {
// 保存单个索引信息
Save(ctx context.Context, indexInfo *types.IndexInfo, params map[string]any) error
// 批量保存多个索引信息
BatchSave(ctx context.Context, indexInfoList []*types.IndexInfo, params map[string]any) error
// 估算索引存储所需空间
EstimateStorageSize(ctx context.Context, indexInfoList []*types.IndexInfo, params map[string]any) int64
// 通过分块ID列表删除索引
DeleteByChunkIDList(ctx context.Context, indexIDList []string, dimension int) error
// 复制索引数据,避免重新计算嵌入向量
CopyIndices(
ctx context.Context,
sourceKnowledgeBaseID string,
sourceToTargetKBIDMap map[string]string,
sourceToTargetChunkIDMap map[string]string,
targetKnowledgeBaseID string,
dimension int,
) error
// 通过知识ID列表删除索引
DeleteByKnowledgeIDList(ctx context.Context, knowledgeIDList []string, dimension int) error
// 继承RetrieveEngine接口
RetrieveEngine
}
```
#### 3. 实现服务层接口
创建实现 `RetrieveEngineService` 接口的服务,负责处理索引创建和管理的业务逻辑:
```go
type RetrieveEngineService interface {
// 创建单个索引
Index(ctx context.Context,
embedder embedding.Embedder,
indexInfo *types.IndexInfo,
retrieverTypes []types.RetrieverType,
) error
// 批量创建索引
BatchIndex(ctx context.Context,
embedder embedding.Embedder,
indexInfoList []*types.IndexInfo,
retrieverTypes []types.RetrieverType,
) error
// 估算索引存储空间
EstimateStorageSize(ctx context.Context,
embedder embedding.Embedder,
indexInfoList []*types.IndexInfo,
retrieverTypes []types.RetrieverType,
) int64
// 复制索引数据
CopyIndices(
ctx context.Context,
sourceKnowledgeBaseID string,
sourceToTargetKBIDMap map[string]string,
sourceToTargetChunkIDMap map[string]string,
targetKnowledgeBaseID string,
dimension int,
) error
// 删除索引
DeleteByChunkIDList(ctx context.Context, indexIDList []string, dimension int) error
DeleteByKnowledgeIDList(ctx context.Context, knowledgeIDList []string, dimension int) error
// 继承RetrieveEngine接口
RetrieveEngine
}
```
#### 4. 添加环境变量配置
在环境配置中添加新数据库的必要连接参数:
```
# 在RETRIEVE_DRIVER中添加新数据库驱动名称(多个驱动用逗号分隔)
RETRIEVE_DRIVER=postgres,elasticsearch_v8,your_database
# 新数据库的连接参数
YOUR_DATABASE_ADDR=your_database_host:port
YOUR_DATABASE_USERNAME=username
YOUR_DATABASE_PASSWORD=password
# 其他必要的连接参数...
```
#### 5. 注册检索引擎
在 `internal/container/container.go` 文件的 `initRetrieveEngineRegistry` 函数中添加新数据库的初始化与注册逻辑:
```go
func initRetrieveEngineRegistry(db *gorm.DB, cfg *config.Config) (interfaces.RetrieveEngineRegistry, error) {
registry := retriever.NewRetrieveEngineRegistry()
retrieveDriver := strings.Split(os.Getenv("RETRIEVE_DRIVER"), ",")
log := logger.GetLogger(context.Background())
// 已有的PostgreSQL和Elasticsearch初始化代码...
// 添加新向量数据库的初始化代码
if slices.Contains(retrieveDriver, "your_database") {
// 初始化数据库客户端
client, err := your_database.NewClient(your_database.Config{
Addresses: []string{os.Getenv("YOUR_DATABASE_ADDR")},
Username: os.Getenv("YOUR_DATABASE_USERNAME"),
Password: os.Getenv("YOUR_DATABASE_PASSWORD"),
// 其他连接参数...
})
if err != nil {
log.Errorf("Create your_database client failed: %v", err)
} else {
// 创建检索引擎仓库
yourDatabaseRepo := your_database.NewYourDatabaseRepository(client, cfg)
// 注册检索引擎
if err := registry.Register(
retriever.NewKVHybridRetrieveEngine(
yourDatabaseRepo, types.YourDatabaseRetrieverEngineType,
),
); err != nil {
log.Errorf("Register your_database retrieve engine failed: %v", err)
} else {
log.Infof("Register your_database retrieve engine success")
}
}
}
return registry, nil
}
```
#### 6. 定义检索引擎类型常量
在 `internal/types/retriever.go` 文件中添加新的检索引擎类型常量:
```go
// RetrieverEngineType 定义检索引擎类型
const (
ElasticsearchRetrieverEngineType RetrieverEngineType = "elasticsearch"
PostgresRetrieverEngineType RetrieverEngineType = "postgres"
YourDatabaseRetrieverEngineType RetrieverEngineType = "your_database" // 添加新数据库类型
)
```
## 参考实现示例
建议参考现有的 PostgreSQL 和 Elasticsearch 实现作为开发模板。这些实现位于以下目录:
- PostgreSQL: `internal/application/repository/retriever/postgres/`
- ElasticsearchV7: `internal/application/repository/retriever/elasticsearch/v7/`
- ElasticsearchV8: `internal/application/repository/retriever/elasticsearch/v8/`
- Apache Doris 4.1: `internal/application/repository/retriever/doris/`
- Tencent VectorDB: `internal/application/repository/retriever/tencentvectordb/`
通过遵循以上步骤和参考现有实现,你可以成功集成新的向量数据库到 WeKnora 系统中,扩展其向量检索能力。
## Apache Doris 4.1 集成说明
Doris 是一种 MPP 风格的分析型数据库;它的接入策略与 NoSQL 向量库(Qdrant/Milvus/Weaviate)有几处特殊点:
### 协议层
| 通道 | 端口 | 用途 |
| ---- | ---- | ---- |
| MySQL 协议 | FE 9030 | 主链路 CRUD、ANN 检索、全文检索 |
| HTTP API | FE 8030 / BE 8040 | Stream Load partial update |
WeKnora 通过 `database/sql + go-sql-driver/mysql` 调用 MySQL 协议;
通过 `net/http` 调用 Stream Load。两条通道复用同一份用户名/密码。
### 表结构与维度分表
每个 embedding 维度对应一张物理表 `<DORIS_TABLE_PREFIX>_<dim>`(如 `weknora_embeddings_768`)。
表关键属性:
```sql
ENGINE=OLAP
UNIQUE KEY(id)
DISTRIBUTED BY HASH(id) BUCKETS 10
PROPERTIES(
"replication_num"="1",
"enable_unique_key_merge_on_write"="true"
);
```
`enable_unique_key_merge_on_write=true` 是 Stream Load partial update 的前提条件。
### 索引
- 倒排索引(INVERTED):`chunk_id / knowledge_id / knowledge_base_id / source_id / tag_id / is_enabled` 用于过滤;`content` 加上 `parser=chinese` 支持中文全文检索。
- ANN 索引(HNSW + cosine_distance):在 `embedding ARRAY<FLOAT>` 列上构建。
注:Doris ANN 索引在建表后**异步构建**,索引未就绪期间查询会退化为 brute-force(结果正确,速度较慢)。WeKnora 在 `ensureTable` 中会轮询 `SHOW INDEX FROM <table>` 等待 `idx_emb` 进入 `FINISHED`/`NORMAL` 状态,超时上限 30s。
### 分数语义
向量检索使用:
```sql
1 - cosine_distance_approximate(embedding, <vec>) AS score
```
将 distance 翻转为 similarity,与 Qdrant cosine 相似度方向一致:值越大越相似。
threshold 比较使用 `HAVING score >= ?`、排序使用 `ORDER BY score DESC LIMIT ?`。
### 关键词检索
依赖 Doris 内建的 `MATCH_ANY` 与 `chinese` parser,无需在 Go 端做 jieba 分词。
跨维度的多张表会逐表查询并合并取 topK,与 Milvus/Weaviate 现状一致。
### 批量字段更新
`BatchUpdateChunkEnabledStatus / BatchUpdateChunkTagID` 通过 Stream Load partial update 实现:
- HTTP PUT `http://<fe_http>/api/<db>/<table>/_stream_load`
- Headers:`partial_columns: true`、`columns: id,is_enabled`、`merge_type: APPEND`、`format: json`、`strip_outer_array: true`
- Body:`[{"id": "...", "is_enabled": true}, ...]`
每批 ≤ 1MiB 自动拆批,请求体通过 `bytes.Reader` + `req.GetBody` 闭包构造,
确保 FE → BE 的 307 redirect 时可以重发 Body。
### 环境变量
```bash
RETRIEVE_DRIVER=doris
DORIS_ADDR=doris-fe:9030 # FE MySQL 协议地址
DORIS_HTTP_PORT=8030 # FE HTTP 端口(Stream Load)
DORIS_DATABASE=weknora # 目标库
DORIS_USERNAME=root
DORIS_PASSWORD=
DORIS_TABLE_PREFIX=weknora_embeddings
```
### 本地起 Doris
```bash
docker compose --profile doris up -d
docker exec -it WeKnora-doris-fe mysql -h 127.0.0.1 -P 9030 -uroot \
-e "CREATE DATABASE IF NOT EXISTS weknora;"
```
随后启动 WeKnora 后端,知识库写入即会按维度自动建表。
## Tencent VectorDB
WeKnora 内置 Tencent VectorDB 适配器,驱动名为 `tencent_vectordb`。该适配器支持向量检索、基于 BM25 sparse vector 的关键词检索和索引管理,可参与 WeKnora 上层混合检索。
### 环境变量示例
```env
RETRIEVE_DRIVER=tencent_vectordb
TENCENT_VECTORDB_ADDR=http://your-instance.tencentvectordb.com
TENCENT_VECTORDB_USERNAME=root
TENCENT_VECTORDB_API_KEY=your_tencent_vectordb_api_key
TENCENT_VECTORDB_DATABASE=weknora
TENCENT_VECTORDB_COLLECTION=weknora_embeddings
TENCENT_VECTORDB_REPLICA_NUMBER=1
```
`TENCENT_VECTORDB_COLLECTION` 是集合名前缀。WeKnora 会按向量维度创建实际集合,例如 `weknora_embeddings_768`,用于隔离不同 embedding 模型维度的数据。
`TENCENT_VECTORDB_REPLICA_NUMBER` 是创建集合时使用的副本数,默认 `1`;单节点 QA 环境可设为 `0`,生产环境可按 Tencent VectorDB 集群规模调整。
关键词检索依赖 Tencent VectorDB sparse vector 索引。新建集合会自动创建 `sparse_vector` 索引;旧版本已创建的向量集合如果没有该索引,需要重建集合并重新导入知识库数据后才能启用关键词检索。

View File

@ -1,193 +0,0 @@
# 共享空间说明文档
本文档说明 WeKnora 中的**共享空间**功能,包括空间创建与加入、成员角色与权限、知识库与智能体共享规则、智能体停用机制,以及用户对知识库的最终访问权限计算方式。
> 共享空间解决「跨空间协作」,与单空间内的角色权限([空间 RBAC 说明](./RBAC说明.md))正交:一次跨空间的写操作必须同时穿过两道闸口。详见 RBAC 文档「与共享空间的关系」一节。
---
## 一、共享空间概述
### 1.1 什么是共享空间
共享空间是跨空间协作的载体。用户可以在同一系统内属于不同空间(账户),通过**加入同一共享空间**,实现:
- 共享知识库:将本空间的知识库共享到空间,供空间内其他成员使用;
- 共享智能体:将本空间的智能体共享到空间,供空间内其他成员在对话等场景中使用;
- 访问他人共享的知识库:在「知识库列表」中看到并打开通过空间共享给自己的知识库;
- 在对话、智能体等场景中选择并使用这些共享知识库与共享智能体。
数据与权限关系简要如下:
- **空间**:知识库、智能体的归属单位,每个知识库/智能体属于一个空间;
- **共享空间**:不拥有知识库或智能体,只记录「某知识库/智能体被共享到某空间」以及「共享时的权限」;
- **成员**:用户通过邀请码或管理员邀请加入空间,在空间内拥有一个角色(管理员 / 编辑者 / 只读)。
### 1.2 核心概念对照
| 概念 | 说明 |
|------|------|
| 共享空间 | 系统中的「组织」(Organization),用于跨空间共享知识库与智能体 |
| 空间创建者 | 创建该空间的用户,自动成为该空间的管理员,且不可被移除或降级 |
| 空间成员 | 通过邀请码加入或由管理员邀请加入的用户,拥有管理员、编辑者或只读之一角色 |
| 知识库/智能体归属 | 知识库、智能体始终属于一个空间;共享到空间不改变归属,只建立「空间 ↔ 知识库/智能体」的共享关系 |
| 共享关系 | 一条记录表示:某知识库以某种权限(只读/可写)被共享到某共享空间;或某智能体以只读方式被共享到某共享空间 |
---
## 二、共享空间的创建、加入与离开
### 2.1 创建空间
- 任意已登录用户均可创建空间。
- 创建时需填写空间名称;描述、头像、邀请码有效期等为可选项。
- 创建者自动成为该空间的**管理员**,且:
- 不能将自己移出空间;
- 不能将自己的角色改为编辑者或只读。
### 2.2 加入空间
加入方式有两种:
1. **邀请码直接加入**
- 若空间未开启「加入需审批」,用户输入有效邀请码即可加入。
- 加入后默认角色为**只读**。
2. **提交加入申请(需审批)**
- 若空间开启了「加入需审批」,用户输入邀请码后提交加入申请。
- 空间管理员审批通过时可指定角色(管理员/编辑者/只读);若不指定,则使用申请时填写的角色或默认只读。
- 审批拒绝后,用户不是成员,无法访问该空间及其共享知识库。
### 2.3 成员人数上限
- 空间可设置**成员人数上限**(默认 200;设为 0 表示不限制)。
- 达到或超过上限时:
- 邀请码加入、管理员添加成员、审批通过加入均会被拒绝,并提示「该空间成员已满」;
- 已满时不允许提交新的加入申请。
- 管理员在设置中调低上限时,若当前成员数已超过新上限,不允许保存,需先移除成员或设置更大的上限。
### 2.4 邀请码
- 仅空间**管理员**可生成或刷新邀请码。
- 邀请码可设置有效期(例如 1 天、7 天、30 天或永不过期);过期后需重新生成才能使用。
- 同一时间一个空间仅有一个有效邀请码;重新生成会使旧邀请码失效。
### 2.5 离开空间
- 成员可主动退出空间(无需管理员同意)。
- 管理员可移除其他成员(不能移除空间创建者)。
- 退出或移除后,该用户不再拥有该空间内的任何角色,也无法再通过该空间访问其共享的知识库。
### 2.6 删除空间
- 仅空间**创建者**可删除空间。
- 删除空间时会解除该空间下所有知识库的共享关系,成员将无法再通过该空间访问这些知识库。
---
## 三、空间内角色与权限
共享空间内共有三种角色,权限从高到低为:**管理员 > 编辑者 > 只读**。
### 3.1 角色定义
| 角色 | 英文标识 | 说明 |
|------|----------|------|
| 管理员 | admin | 空间设置、成员、邀请码及知识库共享的全面管理 |
| 编辑者 | editor | 可编辑空间内共享的知识库内容,可将自己的知识库共享到空间;不可管理空间设置与成员 |
| 只读 | viewer | 仅可查看与检索空间内共享的知识库;不可共享知识库到空间,不可管理空间 |
### 3.2 权限矩阵(空间内能力)
| 能力 | 管理员 | 编辑者 | 只读 |
|------|--------|--------|------|
| 查看、检索空间内共享的知识库 | ✓ | ✓ | ✓ |
| 编辑空间内共享的知识库内容 | ✓ | ✓ | ✗ |
| **将知识库共享到本空间** | ✓ | ✓ | ✗ |
| 管理空间内知识库共享(取消共享、修改共享权限等) | ✓(见下) | 仅限自己发起的共享 | ✗ |
| 管理空间设置(名称、描述、头像、邀请码有效期、是否需审批等) | ✓ | ✗ | ✗ |
| 管理成员(邀请、移除、修改角色) | ✓ | ✗ | ✗ |
| 生成/刷新邀请码 | ✓ | ✗ | ✗ |
| 审批加入申请、权限升级申请 | ✓ | ✗ | ✗ |
| 提交权限升级申请 | — | ✓ | ✓ |
| 退出空间 | ✓ | ✓ | ✓ |
说明:
- **「将知识库共享到本空间」**:仅**管理员**和**编辑者**可以执行;只读成员不能把自己的知识库共享到该空间。
- **管理空间内知识库共享**:
- 共享的发起人可取消自己发起的共享、修改该条共享的权限;
- 空间**管理员**可取消任意一条指向本空间的共享(例如内容治理、发起人已离开等)。
---
## 四、知识库共享规则
### 4.1 谁可以发起共享
- 只有**知识库所属空间下的用户**(即「拥有」该知识库的账户下的用户)才能将该知识库共享到某个共享空间。
- 同时,该用户必须是目标共享空间的**成员**,且角色为**管理员**或**编辑者**。
即:**只读成员不能把任何知识库(包括自己的)共享到该空间。**
### 4.2 共享时的权限设置
将知识库共享到空间时,需为「该空间」指定一个**共享权限**:
- **只读(viewer)**:空间成员在该知识库上最多只读(实际权限还会受成员在空间内的角色限制,见下)。
- **可写(editor)**:空间成员在该知识库上可被赋予编辑能力(同样受成员角色限制)。
同一知识库可以共享到多个共享空间,且每个空间可以设置不同的共享权限(例如空间 A 只读、空间 B 可写)。
### 4.3 更新与取消共享
- **修改某条共享的权限**:仅**发起该次共享的用户**可以修改(只读 ↔ 可写)。
- **取消某条共享**:
- **发起该次共享的用户**可随时取消;
- 目标空间的**管理员**也可取消该空间下的任意共享(包括他人发起的)。
### 4.4 同一知识库共享到多个空间
- 允许将同一知识库共享到多个共享空间。
- 每个空间一条共享记录,各自独立配置权限(只读/可写)。
- 例如:知识库 K 共享到空间 A(只读)、空间 B(可写),互不影响。
---
## 五、智能体共享规则
智能体也可通过共享空间在成员间共享,供成员在对话等场景中选择使用。规则与知识库共享类似,但权限仅支持只读。
### 5.1 谁可以发起智能体共享
- 只有**智能体所属空间下的用户**才能将该智能体共享到某个共享空间。
- 同时,该用户必须是目标共享空间的**成员**,且角色为**管理员**或**编辑者**(与知识库共享一致)。
- 智能体须已配置完成(如已选模型、若使用知识库则已选 rerank 模型等)方可共享。
### 5.2 共享时的权限
- 智能体共享到空间时**仅支持只读**:空间成员只能以「使用」方式使用该智能体(如在对话中选择),不能编辑该智能体的配置或删除共享关系以外的管理操作。
- 同一智能体可以共享到多个共享空间。
### 5.3 更新与取消共享
- **取消某条智能体共享**:
- **发起该次共享的用户**可随时取消;
- 目标空间的**管理员**也可取消该空间下的任意智能体共享(包括他人发起的)。
---
## 六、智能体停用机制
「停用」是当前空间对**通过共享空间获得的智能体**的一种个人偏好设置,仅影响本空间在**对话中选择智能体**时的展示与使用体验,不改变共享关系,也不影响其他成员。
### 6.1 停用的含义
- 当某空间将某个「通过共享空间获得的智能体」标记为**已停用**时:
- 在该空间的对话界面中,该智能体可在下拉列表中被隐藏或标记为已停用,减少干扰;
- 该智能体仍对该共享空间的其他成员可见、可用;
- 共享关系不变,发起共享的用户与空间管理员仍可照常管理该条共享。
- 停用状态按「空间 + 智能体(含来源空间)」记录,即:同一智能体被多个空间共享时,用户停用后在所有入口对该智能体的展示偏好一致。
### 6.2 停用与恢复
- 用户可随时将已停用的共享智能体**恢复**,恢复后该智能体重新在对话下拉等列表中正常显示。
- 停用/恢复仅影响当前空间自己的视图与选择列表,不影响他人,也不影响该用户通过直接链接等方式访问该智能体。

View File

@ -1,221 +0,0 @@
# WeKnora 开发指南
## 快速开发模式(推荐)
如果你需要频繁修改 `app` 或 `frontend` 代码,**不需要每次都重新构建 Docker 镜像**,可以使用本地开发模式。
### 方式一:使用 Make 命令(推荐)
#### 1. 启动基础设施服务
```bash
make dev-start
```
这将启动以下服务的 Docker 容器:
- PostgreSQL(数据库)
- Redis(缓存)
- MinIO(对象存储)
- Neo4j(图数据库)
- DocReader(文档读取服务)
#### 2. 启动后端应用(新终端)
```bash
make dev-app
```
这将在本地直接运行 Go 应用,修改代码后 Ctrl+C 停止,重新运行即可。
#### 3. 启动前端(新终端)
```bash
make dev-frontend
```
这将启动 Vite 开发服务器,支持热重载,修改代码后自动刷新。
#### 4. 查看服务状态
```bash
make dev-status
```
#### 5. 停止所有服务
```bash
make dev-stop
```
### 方式二:使用脚本命令
如果你更喜欢直接使用脚本:
```bash
# 启动基础设施
./scripts/dev.sh start
# 启动后端(新终端)
./scripts/dev.sh app
# 启动前端(新终端)
./scripts/dev.sh frontend
# 查看日志
./scripts/dev.sh logs
# 停止所有服务
./scripts/dev.sh stop
```
## 访问地址
### 开发环境
- **前端开发服务器**: http://localhost:5173
- **后端 API**: http://localhost:8080
- **PostgreSQL**: localhost:5432
- **Redis**: localhost:6379
- **MinIO Console**: http://localhost:9001
- **Neo4j Browser**: http://localhost:7474
## 开发工作流对比
### ❌ 旧方式(慢)
```bash
# 每次修改代码后都需要:
sh scripts/build_images.sh -p # 重新构建镜像(很慢)
sh scripts/start_all.sh --no-pull # 重启容器
```
**耗时**:每次修改需要 2-5 分钟
### ✅ 新方式(快)
```bash
# 首次启动(只需要一次):
make dev-start
# 在另外两个终端分别运行:
make dev-app # 修改 Go 代码后 Ctrl+C 重启即可(秒级)
make dev-frontend # 修改前端代码自动热重载(无需重启)
```
**耗时**:
- 首次启动:1-2 分钟
- 后续修改后端:5-10 秒(重启 Go 应用)
- 后续修改前端:实时热重载
## 使用 Air 实现后端热重载(可选)
如果你希望后端代码修改后也能自动重启,可以安装 `air`:
```bash
go install github.com/air-verse/air@latest
```
项目根目录已内置 `.air.toml`,不需要手动创建配置文件。`make dev-app` 会检测本机是否安装了 Air:检测到 Air 时使用热重载模式,未检测到时使用普通 `go run` 模式。
## 其他开发技巧
### 只修改前端
如果只修改前端,只需要:
```bash
cd frontend
npm run dev
```
前端会连接到 http://localhost:8080 的后端 API。
### 只修改后端
如果只修改后端,只需要:
```bash
# 启动基础设施
make dev-start
# 运行后端
make dev-app
```
### 调试模式
#### 后端调试
使用 VS Code 或 GoLand 的调试功能,配置连接到本地运行的 Go 应用。
VS Code 配置示例(`.vscode/launch.json`):
```json
{
"version": "0.2.0",
"configurations": [
{
"name": "Launch Server",
"type": "go",
"request": "launch",
"mode": "auto",
"program": "${workspaceFolder}/cmd/server",
"env": {
"DB_HOST": "localhost",
"DOCREADER_ADDR": "localhost:50051",
"MINIO_ENDPOINT": "localhost:9000",
"REDIS_ADDR": "localhost:6379",
"NEO4J_URI": "bolt://localhost:7687"
},
"args": []
}
]
}
```
#### 前端调试
使用浏览器开发者工具即可,Vite 提供了 source map。
## 生产环境部署
当你完成开发需要部署时,才需要构建镜像:
```bash
# 构建所有镜像
sh scripts/build_images.sh
# 或只构建特定镜像
sh scripts/build_images.sh -p # 只构建后端
sh scripts/build_images.sh -f # 只构建前端
sh scripts/build_images.sh -d # 只构建文档读取器
sh scripts/build_images.sh -s # 只构建沙箱镜像(Agent Skills 执行环境)
# 启动生产环境
sh scripts/start_all.sh
```
## 常见问题
### Q: 启动 dev-app 时报错连接不到数据库
A: 确保先运行了 `make dev-start`,并等待所有服务启动完成(大约 30 秒)。
### Q: 前端访问 API 时报 CORS 错误
A: 检查前端的代理配置,确保 `vite.config.ts` 中配置了正确的代理。
### Q: DocReader 服务需要重新构建怎么办?
A: DocReader 仍然使用 Docker 镜像,如果需要修改,需要重新构建:
```bash
sh scripts/build_images.sh -d
make dev-restart
```
## 总结
- **日常开发**:使用 `make dev-*` 命令,快速迭代
- **测试集成**:使用 `sh scripts/start_all.sh --no-pull` 测试完整环境
- **生产部署**:使用 `sh scripts/build_images.sh` + `sh scripts/start_all.sh`

View File

@ -1,85 +0,0 @@
# 开启知识图谱功能指南
本文档介绍如何在 WeKnora 中启用并验证知识图谱(Neo4j)功能,帮助你完成从环境准备到前端配置的全流程。
## 前置条件
- 已完成 WeKnora 后端与前端的基础部署。
- 具备可用的 Docker/Docker Compose 运行环境。
- 本地或远端可访问的 Neo4j 服务(推荐使用项目自带的 Docker Compose)。
## 步骤一:配置环境变量
在项目根目录的 `.env` 文件中新增或修改以下变量:
```
NEO4J_ENABLE=true
NEO4J_URI=bolt://neo4j:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_strong_password
# 可选:NEO4J_DATABASE=neo4j
```
说明:
- `NEO4J_ENABLE` 设置为 `true` 才会启用知识图谱相关逻辑。
- `NEO4J_URI` 中的 `neo4j` 为 docker-compose 服务名,如使用外部实例请替换为实际地址。
- 如果生产环境使用密钥管理,请确保密码通过安全方式注入。
## 步骤二:启动 Neo4j 服务
项目附带 Neo4j 组件,可直接用以下命令启动:
```bash
docker-compose --profile neo4j up -d
```
常见验证命令:
```bash
docker ps | grep neo4j
```
若需要自定义挂载或内存,可编辑 `docker-compose.yml` 中 `neo4j` 服务配置。
## 步骤三:重启 WeKnora 服务
为了让新的环境变量生效,重启后端与前端(示例仅供参考):
```bash
make stop && make start
# 或者
docker compose up -d --build
```
确保后端日志中出现 `neo4j` 初始化成功的提示。
## 步骤四:在前端启用实体/关系抽取
1. 登录 WeKnora 前端管理页面。
2. 打开「知识库设置」或创建新的知识库。
3. 勾选「启用实体抽取」与「启用关系抽取」开关。
4. 根据界面提示补充所需的 LLM、回调或模型参数(若有)。
保存后,系统会在文档入库阶段自动触发实体与关系抽取任务。
## 步骤五:验证知识图谱
### 方式一:Neo4j 控制台
1. 访问 `http://localhost:7474`(或对应主机/端口)。
2. 使用 `.env` 中的账号密码登录。
3. 执行 `MATCH (n) RETURN n LIMIT 50;` 检查是否有新节点/关系。
### 方式二:WeKnora 界面
在知识库或对话页面中上传文档后,前端应展示图谱可视化入口;对话时系统会自动根据意图查询图谱并返回补充信息。
## 常见问题排查
- **无法连接 Neo4j**:确认网络可达、`NEO4J_URI` 与用户名密码正确,并检查 Neo4j 容器日志。
- **未生成节点**:确认知识库已开启实体/关系抽取,且上传的文档已完成解析;查看后端日志中是否有抽取任务异常。
- **查询无结果**:尝试在 Neo4j 控制台执行 `CALL db.schema.visualization;` 查看 schema 是否存在,必要时重新导入文档。
完成以上步骤后,知识图谱功能即成功启用,可结合 RAG 及 Agent 流程提升问答质量。

View File

@ -1,106 +0,0 @@
# 快速开发模式说明
解决开发流程中,每次修改 `app`(后端)或 `frontend`(前端)代码后,都需要打包Docker镜像的问题,实现这两个模块的热更新
## 🚀 使用方法
### 方式 1:使用 Make 命令(推荐)
```bash
# 终端 1:启动基础设施
make dev-start
# 终端 2:启动后端
make dev-app
# 终端 3:启动前端
make dev-frontend
```
### 方式 2:使用开发脚本
```bash
# 终端 1
./scripts/dev.sh start
# 终端 2
./scripts/dev.sh app
# 终端 3
./scripts/dev.sh frontend
```
### 方式 3:一键启动(交互式)
```bash
./scripts/quick-dev.sh
```
### 使用 Air 实现后端热重载
安装 Air 后,后端代码修改会自动重新编译和重启:
```bash
# 安装 Air
go install github.com/air-verse/air@latest
# 确保在 PATH 中
export PATH=$PATH:$(go env GOPATH)/bin
# 使用 Air 启动(自动检测)
make dev-app
```
## 🔄 架构说明
### 开发模式架构
```
┌─────────────────────────────────────────────────────────┐
│ 本地开发环境 │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ │
│ │ 后端 App │◄────────┤ 前端 UI │ │
│ │ (本地运行)│ │ (本地运行)│ │
│ │ :8080 │ │ :5173 │ │
│ └────┬─────┘ └──────────┘ │
│ │ │
│ │ 连接基础设施服务 │
│ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Docker 基础设施容器 │ │
│ ├─────────────────────────────────────────────────┤ │
│ │ PostgreSQL │ Redis │ MinIO │ Neo4j │ DocReader │ │
│ │ :5432 │ :6379 │ :9000 │ :7687 │ :50051 │ │
│ └─────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
```
### 生产模式架构
```
┌─────────────────────────────────────────────────────────┐
│ Docker Compose 环境 │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ │
│ │ 后端 App │◄────────┤ 前端 UI │ │
│ │ (容器运行)│ │ (容器运行)│ │
│ │ :8080 │ │ :80 │ │
│ └────┬─────┘ └──────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 基础设施容器 │ │
│ ├─────────────────────────────────────────────────┤ │
│ │ PostgreSQL │ Redis │ MinIO │ Neo4j │ DocReader │ │
│ └─────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
```

View File

@ -1,988 +0,0 @@
# 数据源导入开发文档
WeKnora 的数据源导入模块支持从外部平台(飞书、企业微信、Notion、Confluence 等)自动导入和同步内容到知识库。用户可配置数据源连接,选择需要同步的资源,并通过手动触发或定时调度自动完成内容的增量/全量同步。
数据源绑定到知识库,一个知识库可接入多个数据源。所有配置通过前端知识库设置页面管理,凭证使用 AES-256-GCM 加密存储在数据库中。
## 目录
- [快速接入指南](#快速接入指南)
- [飞书知识库接入](#飞书知识库接入)
- [前端管理](#前端管理)
- [架构总览](#架构总览)
- [数据模型](#数据模型)
- [API 端点](#api-端点)
- [核心概念](#核心概念)
- [同步处理流程](#同步处理流程)
- [接口定义](#接口定义)
- [连接器详解](#连接器详解)
- [飞书 (Feishu)](#飞书-feishu)
- [定时调度](#定时调度)
- [关键参数与阈值](#关键参数与阈值)
- [错误处理](#错误处理)
- [扩展新连接器](#扩展新连接器)
---
## 快速接入指南
### 前置条件
- WeKnora 已部署并运行
- 已创建至少一个知识库
- 拥有外部平台(如飞书、企业微信)的管理权限,可创建应用并授权
### 飞书知识库接入
从飞书知识库(Wiki)同步文档到 WeKnora。支持 docx、doc、sheet、bitable、file 类型文档的自动导入。
#### 第一步:创建飞书应用
1. 登录 [飞书开放平台](https://open.feishu.cn/) → **开发者后台** → **创建企业自建应用**
2. 在 **凭证与基础信息** 页获取:
- **App ID**
- **App Secret**
#### 第二步:开通权限
在 **权限管理** 中搜索并开通以下权限:
| 权限 | 说明 |
|------|------|
| `wiki:wiki:readonly` | 读取知识库空间列表和节点树 |
| `drive:drive:readonly` | 读取云文档基础信息 |
| `drive:export:readonly` | 导出文档内容(docx/xlsx) |
| `docx:document:readonly` | 读取新版文档内容 |
> **docx 内嵌内容下钻权限(可选)**
>
> 若需同步 docx 文档中内嵌的附件和图片,还需额外开通以下权限(缺失时自动回退到导出 docx,不会同步失败,仅无法获取内嵌表格/附件):
>
> - `docx:document:readonly` — 读取文档块(上表已含,此处仅供核对)
> - `drive:drive:readonly` / `docs:document.media:download` — 下载附件、图片
> - `sheets:spreadsheet:readonly` — 读取内嵌电子表格
> - `bitable:app:readonly` — 读取内嵌多维表格
#### 第三步:发布应用
在 **版本管理与发布** 中创建版本并提交审核。审核通过后方可正常调用 API。
#### 第四步:在 WeKnora 中添加数据源
1. 进入知识库设置页 → **数据源** 标签页
2. 点击 **添加数据源**
3. 选择连接器类型:**飞书**
4. 填写凭证:
- **App ID**:填入从飞书获取的 App ID
- **App Secret**:填入从飞书获取的 App Secret
5. 点击 **测试连接**,验证凭证有效
6. 选择要同步的知识库空间(Wiki Space)
7. 配置同步策略:
- **同步模式**:增量同步(推荐)或全量同步
- **同步频率**:选择预设的 Cron 表达式(如每 30 分钟、每小时、每天凌晨 2 点)
- **冲突策略**:覆盖(推荐)或跳过
- **同步删除**:是否同步源端的删除操作
8. 点击保存
#### 第五步:验证
保存后可点击 **立即同步** 触发首次同步。在同步日志中查看同步进度和结果:
- **成功**:显示已创建/更新/跳过/失败的文档数量
- **失败**:显示错误信息,常见原因为权限不足或 Token 过期
---
### Lark 知识库接入
Lark 是飞书的国际版。Wiki / docx / drive 接口与飞书一致,**共用同一套连接器代码**,接入步骤
与[飞书知识库接入](#飞书知识库接入)相同,差别只有三处:
| | 飞书 | Lark |
|---|---|---|
| 开放平台 | <https://open.feishu.cn/> | <https://open.larksuite.com/> |
| 连接器类型 | 「飞书」 | 「Lark」 |
| API 地址 | `https://open.feishu.cn` | `https://open.larksuite.com`(选中 Lark 类型后自动使用) |
#### Lark 权限
权限标识与飞书相同,在 Lark 开放平台的 **权限管理** 中开通:
| 权限 | 说明 | Lark 官方文档核对 |
|------|------|------|
| `wiki:wiki:readonly` | 读取知识库空间列表和节点树 | ✅ 已核对 |
| `drive:export:readonly` | 导出文档内容(docx/xlsx) | ✅ 已核对 |
| `drive:drive:readonly` | 读取云文档基础信息、下载文件 | ✅ 已核对 |
| `docx:document:readonly` | 读取新版文档内容 | ⚠️ 未能核对(Lark 文档页渲染受限),沿用飞书侧标识 |
> **不要套用 [IM 集成文档](./IM集成开发文档.md#飞书接入)里的那份权限 JSON**:那份清单混入了
> `aily:file:*`、`corehr:file:download` 等在 Lark 并不存在的权限(整份导入会失败),
> 且反而**缺少**上表中数据源真正需要的 `drive:*` / `docx:*`。
>
> 若同一个 Lark 应用既做 IM 机器人又做知识库同步,请使用
> [IM 集成文档 — Lark 权限配置](./IM集成开发文档.md#lark-权限配置)中的合并清单。
#### 应用互不通用
在 open.feishu.cn 创建的应用无法读取 Lark 知识库,反之亦然——凭证只在创建它的那朵云上有效。
若你此前用「飞书」连接器加 `base_url=https://open.larksuite.com` 的方式接入过 Lark,该配置
仍然有效(`base_url` 保留为显式覆盖项),但新建数据源请直接选「Lark」类型。
---
### 钉钉文档接入
1. 在钉钉开放平台创建并发布企业内部应用。
2. 为应用开通 `Wiki.Workspace.Read`、`Wiki.Node.Read`、`Storage.File.Read` 权限。
3. 添加“钉钉文档”数据源,填写 Client ID、Client Secret,以及有权访问目标知识库的操作人 Union ID。
4. 测试连接后,可按知识库空间、文件夹或单篇文档选择同步范围。
连接器通过钉钉公开 OpenAPI 读取知识库节点及文档 Block,并转换为 Markdown;当前只同步
`ALIDOC/adoc` 在线文档。增量同步优先用节点的毫秒 `modifiedTimestamp` 作为版本,避免官方示例中
分钟精度 `modifiedTime`(如 `2023-05-15T11:29Z`)导致同一分钟内的编辑被跳过。目录遍历不完整或
单篇文档读取失败时会保留原游标,避免误删或跳过后续重试。实现不依赖灰度权限、异步导出或回调服务。
钉钉 Blocks 查询接口只返回文档根下的一级块。高亮块等容器若响应内联了 `children` 会继续渲染;
若容器没有子块,连接器会在文档元数据中记录 `nested_blocks_unavailable`,而不是把残缺正文当成
完整导入。列表项若是块级 children 也会尝试展开。
测试连接除列出知识库外,还会读取根节点,并在根下存在在线文档时试读 Blocks,以便在保存前发现
缺少 `Wiki.Node.Read` 或 `Storage.File.Read`。全量同步(含手动 ForceFull)会对照上次游标对账删除。
同步以所有已选范围的可见文档集合统一判断删除,文档在已选文件夹之间移动不会触发删除。
某个范围不可访问或已选节点失效时,其他正常范围继续同步,失败范围保留旧游标;在所有范围
恢复可完整读取之前,暂缓删除并保留待核对记录。正文抓取失败的文档也会在后续同步重试。
失效的单篇文档或文件夹选择需要检查权限,必要时重新选择资源,不能直接将不可见等同于源端删除。
开启“同步删除”后,确认源端删除的文档会从 WeKnora 知识库移除;关闭该开关则保留本地内容。
钉钉配置和同步失败提示覆盖中文、英语、日语、韩语、俄语。
---
## 前端管理
数据源在知识库设置页的 **数据源** 标签页中管理。
### 创建向导
添加数据源使用多步向导流程:
1. **选择类型**:从可用连接器列表中选择平台
2. **配置凭证**:填写平台凭证,支持即时「测试连接」验证
3. **选择资源**:浏览并勾选要同步的资源(如飞书知识库空间)
4. **同步策略**:配置 Cron 调度、同步模式、冲突策略等
### 数据源列表
每个数据源以卡片形式展示,包含:
- **连接器类型标识**:飞书(蓝色)等
- **数据源名称**:用户自定义
- **同步状态**:活跃 / 暂停 / 错误
- **最近同步时间**:上次成功同步的时间
- **最近同步结果**:已同步的文档数量摘要
- **操作按钮**:立即同步、暂停/恢复、编辑、删除
### 同步日志
每个数据源可查看历史同步日志,包含:
- 同步状态:运行中 / 成功 / 部分成功 / 失败 / 已取消
- 开始时间 / 结束时间
- 文档计数:总数、已创建、已更新、已删除、已跳过、失败
- 错误信息(如有)
---
## 架构总览
```
┌───────────────────────────────────────────────────────────────────────────┐
│ 数据源导入架构 │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 飞书 │ │ Notion │ │Confluence│ │ GitHub │ │ 其他... │ │
│ │ (Wiki) │ │ │ │ │ │ │ │ │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ API │ API │ API │ API │ │
│ ─────┼─────────────┼────────────┼─────────────┼─────────────┼────── │
│ ▼ ▼ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Feishu │ │ Notion │ │Confluence│ │ GitHub │ │ ... │ │
│ │Connector │ │Connector │ │Connector │ │Connector │ │Connector │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │ │ 连接 │
│ ─────┴─────────────┴─────────────┴──────────────┴─────────────┘ 器层 │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────┐ │
│ │ ConnectorRegistry │ 连接器注册表 │
│ │ · 按类型查找连接器实例 │ │
│ │ · 连接器元数据(名称、认证方式、能力) │ │
│ └──────────────────┬───────────────────────────┘ │
│ │ │
│ ───────────────────┼──────────────────────────────────────────────── │
│ ▼ │
│ ┌──────────────────────────────────────────────┐ │
│ │ DataSourceService (业务逻辑层) │ │
│ │ │ │
│ │ ┌────────────────────────────────────────┐ │ │
│ │ │ · 数据源 CRUD │ │ │
│ │ │ · 连接验证 (ValidateConnection) │ │ │
│ │ │ · 资源发现 (ListAvailableResources) │ │ │
│ │ │ · 手动同步 (ManualSync) │ │ │
│ │ │ · 暂停/恢复 │ │ │
│ │ │ · 同步执行 (ProcessSync) │ │ │
│ │ │ · 内容入库 (ingestItem) │ │ │
│ │ └────────────────────────────────────────┘ │ │
│ └──────────────────┬───────────────────────────┘ │
│ │ │
│ ───────────────────┼──────────────────────────────────────────────── │
│ ▼ │
│ ┌──────────────────────────────────┐ ┌────────────────────────────┐ │
│ │ Scheduler (Cron 调度器) │ │ Task Queue (asynq) │ │
│ │ · robfig/cron(含秒) │ │ · 异步同步任务 │ │
│ │ · DB 加载活跃数据源 │ │ · Redis / Lite 模式 │ │
│ │ · 任务去重 (TaskID + Running) │ │ · TypeDataSourceSync │ │
│ └──────────────────────────────────┘ └────────────────────────────┘ │
│ │ │
│ ───────────────────┼──────────────────────────────────────────────── │
│ ▼ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ WeKnora Core (知识入库管道) │ │
│ │ KnowledgeService · KnowledgeBaseService │ │
│ │ 文档解析 → 分块 → 向量化 → 索引 │ │
│ └──────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────────────────┘
```
**设计模式:**
| 模式 | 用途 |
|------|------|
| Adapter Pattern | 统一不同平台的差异,每个平台实现 `Connector` 接口 |
| Registry Pattern | 通过 `ConnectorRegistry` 按类型动态查找连接器实例 |
| Strategy Pattern | `SyncMode`(增量/全量)、`ConflictStrategy`(覆盖/跳过)可选策略 |
| Producer-Consumer | 手动/定时触发 → asynq 任务队列 → Worker 异步执行同步 |
| Cursor-based Pagination | 增量同步基于 `SyncCursor` 状态跟踪变更 |
---
## 数据模型
### data_sources 表
数据源配置存储在 `data_sources` 表中,绑定到知识库:
```sql
CREATE TABLE data_sources (
id VARCHAR(36) PRIMARY KEY,
tenant_id BIGINT NOT NULL,
knowledge_base_id VARCHAR(36) NOT NULL,
name VARCHAR(255) NOT NULL DEFAULT '',
type VARCHAR(50) NOT NULL, -- 连接器类型
config JSONB NOT NULL DEFAULT '{}', -- 加密的凭证和配置
sync_schedule VARCHAR(100) DEFAULT '', -- Cron 表达式(6 段,含秒)
sync_mode VARCHAR(20) DEFAULT 'incremental', -- 'incremental' | 'full'
status VARCHAR(20) DEFAULT 'active', -- 'active' | 'paused' | 'error' | 'deleted'
conflict_strategy VARCHAR(20) DEFAULT 'overwrite', -- 'overwrite' | 'skip'
sync_deletions BOOLEAN DEFAULT true,
last_sync_at TIMESTAMPTZ,
last_sync_cursor JSONB,
last_sync_result JSONB,
error_message TEXT DEFAULT '',
sync_log_retention_days INTEGER DEFAULT 30,
created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
deleted_at TIMESTAMPTZ
);
```
**config 字段结构(解密后):**
```json
{
"type": "feishu",
"credentials": {
"app_id": "cli_xxx",
"app_secret": "xxx"
},
"resource_ids": ["space_id_1", "space_id_2"],
"settings": {}
}
```
**各连接器凭证字段:**
| 连接器类型 | 凭证字段 | 认证方式 |
|-----------|---------|---------|
| 飞书 (feishu) | `app_id`, `app_secret` | OAuth2 (Tenant Access Token) |
### sync_logs 表
同步日志记录每次同步操作的执行情况:
```sql
CREATE TABLE sync_logs (
id VARCHAR(36) PRIMARY KEY,
data_source_id VARCHAR(36) NOT NULL REFERENCES data_sources(id) ON DELETE CASCADE,
tenant_id BIGINT NOT NULL,
status VARCHAR(20) NOT NULL, -- 'running' | 'success' | 'partial' | 'failed' | 'canceled'
started_at TIMESTAMPTZ NOT NULL,
finished_at TIMESTAMPTZ,
items_total INTEGER DEFAULT 0,
items_created INTEGER DEFAULT 0,
items_updated INTEGER DEFAULT 0,
items_deleted INTEGER DEFAULT 0,
items_skipped INTEGER DEFAULT 0,
items_failed INTEGER DEFAULT 0,
error_message TEXT DEFAULT '',
result JSONB, -- 详细同步结果
created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
);
```
---
## API 端点
所有端点位于 `/api/v1/datasource` 路径下,需认证。
### 连接器元数据
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/datasource/types` | 获取可用连接器类型列表 |
**响应示例:**
```json
[
{
"type": "feishu",
"name": "飞书",
"description": "Import documents from Feishu/Lark Wiki spaces",
"icon": "feishu",
"priority": 1,
"auth_type": "oauth2",
"capabilities": ["incremental", "deletion_sync"]
}
]
```
### 凭证验证(不落库)
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/datasource/validate-credentials` | 验证凭证(创建前的测试连接) |
**请求体:**
```json
{
"type": "feishu",
"credentials": {
"app_id": "cli_xxx",
"app_secret": "xxx"
}
}
```
### 数据源管理
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/datasource` | 创建数据源 |
| GET | `/api/v1/datasource?kb_id=xxx` | 列出知识库的所有数据源 |
| GET | `/api/v1/datasource/:id` | 获取数据源详情 |
| PUT | `/api/v1/datasource/:id` | 更新数据源配置 |
| DELETE | `/api/v1/datasource/:id` | 删除数据源(软删除) |
### 操作
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/datasource/:id/validate` | 测试已有数据源的连接(会更新状态) |
| GET | `/api/v1/datasource/:id/resources` | 浏览外部系统的可用资源 |
| POST | `/api/v1/datasource/:id/sync` | 手动触发同步 |
| POST | `/api/v1/datasource/:id/pause` | 暂停数据源(停止定时同步) |
| POST | `/api/v1/datasource/:id/resume` | 恢复数据源 |
### 同步日志
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/datasource/:id/logs?limit=10&offset=0` | 获取同步日志列表 |
| GET | `/api/v1/datasource/logs/:log_id` | 获取单条同步日志详情 |
---
## 核心概念
### DataSource — 数据源
每个数据源代表一个外部平台连接与 WeKnora 知识库的绑定关系。一个知识库可以添加多个数据源,实现从多个平台汇聚内容。
数据源的核心属性:
- **类型 (Type)**:绑定的连接器类型,如 `feishu`、`notion` 等
- **配置 (Config)**:加密存储的凭证、选中的资源 ID 列表和额外设置
- **同步模式 (SyncMode)**:`incremental`(增量同步,只同步变更)或 `full`(全量同步,每次拉取所有)
- **同步调度 (SyncSchedule)**:6 段 Cron 表达式(含秒),为空则仅支持手动触发
- **冲突策略 (ConflictStrategy)**:源端与本地均有变更时的处理策略
- **同步删除 (SyncDeletions)**:源端删除文档时是否同步删除本地知识
### Connector — 连接器
连接器是与外部平台交互的适配层,每个平台实现一个连接器。所有连接器通过 `ConnectorRegistry` 注册和管理。
连接器提供四个核心能力:
| 能力 | 说明 |
|------|------|
| `Validate` | 验证凭证和连接是否可用 |
| `ListResources` | 列出外部系统中可选的资源(如知识库空间、文件夹) |
| `FetchAll` | 全量拉取指定资源中的所有文档 |
| `FetchIncremental` | 基于游标增量拉取变更的文档 |
### SyncCursor — 同步游标
增量同步的状态标记,记录上次同步的位点。游标内容因连接器类型而异,由连接器自行管理。如飞书连接器的游标包含每个节点的最后编辑时间,用于判断哪些文档发生了变更。
```go
type SyncCursor struct {
LastSyncTime *time.Time // 上次同步时间
ConnectorCursor map[string]interface{} // 连接器自定义状态
LastSchemaHash string // Schema 变更检测
}
```
### FetchedItem — 拉取到的文档条目
连接器从外部平台拉取文档后,统一封装为 `FetchedItem`:
```go
type FetchedItem struct {
ExternalID string // 外部平台的文档唯一标识
Title string // 文档标题
Content []byte // 文档内容(二进制)
ContentType string // MIME 类型
FileName string // 文件名(含扩展名)
URL string // 原始 URL
UpdatedAt *time.Time // 最后更新时间
Metadata map[string]string // 元数据(来源、作者等)
IsDeleted bool // 标记为已删除(增量同步)
SourceResourceID string // 所属资源 ID
}
```
### Resource — 可选资源
外部系统中可选择同步的资源节点,支持层级结构:
```go
type Resource struct {
ExternalID string // 外部 ID
Name string // 名称
Type string // 类型(如 wiki_space)
Description string // 描述
URL string // 外部链接
ModifiedAt *time.Time // 最后修改时间
ParentID string // 父节点 ID(支持树形结构)
Metadata map[string]string // 附加信息
}
```
---
## 同步处理流程
### 完整同步流程
```
手动触发 / Cron 定时触发
│
▼
┌─ 创建 SyncLog (status: running) ──────────────────┐
│ 入队异步任务 (asynq: TypeDataSourceSync) │
│ · 手动同步 → 队列: default │
│ · 定时同步 → 队列: low, TaskID 去重 │
└──────────────────────────┬────────────────────────┘
│
▼
┌─ ProcessSync (Worker 异步执行) ───────────────────┐
│ 1. 解析任务体 (DataSourceSyncPayload) │
│ 2. 加载数据源配置 │
│ 3. 解密凭证 → 获取 Connector │
│ 4. 设置空间上下文 │
│ 5. 创建/获取自动标签 (连接器名·数据源名) │
│ 6. 判断同步模式: │
│ ├─ ForceFull 或 SyncModeFull → FetchAll │
│ └─ SyncModeIncremental → FetchIncremental │
│ 7. 遍历 FetchedItem 列表: │
│ └─ ingestItem → KnowledgeService │
│ 8. 更新 SyncLog (计数、状态、耗时) │
│ 9. 更新 DataSource (游标、最后同步时间、结果) │
└──────────────────────────────────────────────────┘
```
### ingestItem — 单文档入库
```
FetchedItem
│
├─ IsDeleted = true?
│ └─ 按 external_id 查找已有知识 → 软删除
│
├─ 有文件内容 (Content)?
│ └─ CreateKnowledgeFromFile
│ · 按 external_id 查找已有知识
│ · 已存在 → 删除旧版本 → 重建
│ · 不存在 → 新建
│ · metadata: external_id, source_resource_id, datasource_id
│ · channel: 连接器类型 (如 "feishu")
│ · 自动关联标签
│
└─ 仅有 URL (无 Content)?
└─ CreateKnowledgeFromURL
· 同上查重逻辑
```
### 数据源生命周期
```
创建数据源 (前端向导)
│
▼
┌─ DataSourceService.Create ────────────────────┐
│ 1. 验证知识库存在 │
│ 2. 获取对应 Connector │
│ 3. 验证配置和凭证 (connector.Validate) │
│ 4. 加密凭证写库 │
│ 5. 若有 SyncSchedule → 注册 Cron 任务 │
└───────────────────────────────────────────────┘
暂停数据源:
status → paused, 移除 Cron 任务
恢复数据源:
status → active, 重新注册 Cron 任务
删除数据源:
deleted_at = NOW(), 移除 Cron 任务, 级联删除 sync_logs
连接错误:
ValidateConnection 失败 → status → error, 记录 error_message
ValidateConnection 成功且原为 error → status → active, 清空 error_message
```
---
## 接口定义
### Connector — 连接器接口(必须实现)
```go
type Connector interface {
Type() string
Validate(ctx context.Context, config *types.DataSourceConfig) error
ListResources(ctx context.Context, config *types.DataSourceConfig) ([]types.Resource, error)
FetchAll(ctx context.Context, config *types.DataSourceConfig, resourceIDs []string) ([]types.FetchedItem, error)
FetchIncremental(ctx context.Context, config *types.DataSourceConfig, cursor *types.SyncCursor) ([]types.FetchedItem, *types.SyncCursor, error)
}
```
| 方法 | 职责 |
|------|------|
| `Type()` | 返回连接器类型标识,用于注册和路由 |
| `Validate()` | 验证凭证和连接可用性,如尝试获取 Access Token |
| `ListResources()` | 列出外部系统中可选的顶层资源(如知识库空间、工作区) |
| `FetchAll()` | 全量拉取指定资源下的所有文档,返回 `FetchedItem` 列表 |
| `FetchIncremental()` | 基于上次游标增量拉取变更,返回变更列表和新游标 |
### DataSourceService — 业务服务接口
```go
type DataSourceService interface {
CreateDataSource(ctx context.Context, ds *types.DataSource) (*types.DataSource, error)
GetDataSource(ctx context.Context, id string) (*types.DataSource, error)
ListDataSources(ctx context.Context, knowledgeBaseID string) ([]*types.DataSource, error)
UpdateDataSource(ctx context.Context, ds *types.DataSource) (*types.DataSource, error)
DeleteDataSource(ctx context.Context, id string) error
ValidateConnection(ctx context.Context, dataSourceID string) error
ValidateCredentials(ctx context.Context, connectorType string, credentials map[string]interface{}) error
ListAvailableResources(ctx context.Context, dataSourceID string) ([]types.Resource, error)
ManualSync(ctx context.Context, dataSourceID string) (*types.SyncLog, error)
PauseDataSource(ctx context.Context, dataSourceID string) error
ResumeDataSource(ctx context.Context, dataSourceID string) error
GetSyncLogs(ctx context.Context, dataSourceID string, limit, offset int) ([]*types.SyncLog, error)
GetSyncLog(ctx context.Context, syncLogID string) (*types.SyncLog, error)
ProcessSync(ctx context.Context, task *asynq.Task) error
}
```
### ConnectorMetadata — 连接器元数据
```go
type ConnectorMetadata struct {
Type string `json:"type"`
Name string `json:"name"`
Description string `json:"description"`
Icon string `json:"icon"`
Priority int `json:"priority"`
AuthType string `json:"auth_type"`
Capabilities []string `json:"capabilities"`
}
```
| 字段 | 说明 |
|------|------|
| `Type` | 连接器类型标识(如 `feishu`) |
| `Name` | 显示名称(如 `飞书`) |
| `Priority` | 排序优先级,数值越小越靠前 |
| `AuthType` | 认证方式:`oauth2` / `api_key` / `token` / `password` / `none` |
| `Capabilities` | 支持的能力:`incremental`(增量同步)、`webhook`、`deletion_sync`(删除同步) |
---
## 连接器详解
### 飞书 (Feishu)
飞书连接器支持从飞书知识库(Wiki)同步文档到 WeKnora。
#### 认证机制
```
App ID + App Secret
│
▼
POST /open-apis/auth/v3/tenant_access_token/internal
│
▼
获取 Tenant Access Token(有效期 2 小时)
│
▼
Token 缓存,提前 5 分钟刷新
```
- **认证类型**:企业自建应用,Tenant Access Token
- **Token 有效期**:2 小时,内置缓存,提前 5 分钟自动刷新
- **API 地址**:默认 `https://open.feishu.cn`,国际版 Lark 使用 `https://open.larksuite.com`
#### 资源发现
`ListResources` 调用飞书 Wiki Space API 列出所有知识库空间:
```
GET /open-apis/wiki/v2/spaces (分页, page_size=50)
```
每个知识库空间映射为一个 `Resource`:
| 字段 | 值 |
|------|------|
| `Type` | `wiki_space` |
| `ExternalID` | 空间 ID (space_id) |
| `URL` | `https://feishu.cn/wiki/{space_id}` |
| `Metadata.visibility` | 空间可见性 |
#### 全量同步 (FetchAll)
```
对每个选中的 Wiki Space:
1. 递归列举空间下所有节点 (ListAllWikiNodesRecursive)
└─ GET /open-apis/wiki/v2/spaces/{space_id}/nodes (parent 为空 → 顶层)
└─ 对 has_child=true 的节点递归
2. 对每个节点:
└─ fetchNodeContent → 判断文档类型 → 导出/下载
```
#### 增量同步 (FetchIncremental)
增量同步基于节点编辑时间对比,而非飞书事件订阅:
```
1. 加载上次游标 (feishuCursor)
└─ SpaceNodeTimes[space_id][node_token] = 上次记录的编辑时间
2. 对每个 Space 递归列举所有节点(全树遍历)
3. 对比变更:
├─ 新节点(游标中不存在)→ 拉取内容
├─ obj_edit_time 变更(优先)或 node_edit_time 变更 → 拉取内容
├─ 编辑时间未变 → 跳过
└─ 游标中存在但本次遍历不存在 → 标记为 IsDeleted
4. 返回新游标(含本轮每个节点的最新编辑时间)
```
> **注意**:增量同步的 API 调用量与知识库空间的节点树大小相关,因为需要遍历完整节点树来检测变更。对于大型空间,建议适当降低同步频率。
#### 支持的文档类型
| `obj_type` | 支持 | 获取方式 | 导出格式 |
|------------|------|---------|---------|
| `docx` | 是 | 导出 .docx(默认)/ blocks API 转 Markdown(blocks 模式) | `.docx` / Markdown |
| `doc` | 是 | 导出任务 (Export API) | `.docx` |
| `sheet` | 是 | 导出任务 (Export API) | `.xlsx` |
| `bitable` | 是 | 导出任务 (Export API) | `.xlsx` |
| `file` | 是 | 直接下载 (Drive Download API) | 原格式 |
| `mindnote` | 否 | — | — |
| `slides` | 否 | — | — |
#### 内容获取流程
**docx(新版云文档):** 由环境变量 `FEISHU_DOCX_PARSE_MODE` 控制解析路径(作用于 app 服务,飞书知识库和飞书云盘连接器同时生效)。
- **export 模式(默认,留空或 `export`)**:走异步导出 API
```
1. CreateExportTask -> 创建导出任务
2. 轮询 GetExportTaskStatus(间隔 2 秒,最长约 60 秒)
3. DownloadExportFile -> 下载 .docx 二进制
4. .docx 交 docreader 解析(图片 inline 进父文档,与普通 docx 上传一致)
```
- **blocks 模式(`FEISHU_DOCX_PARSE_MODE=blocks`)**:走 blocks API
```
1. GET /open-apis/docx/v1/documents/{obj_token}/blocks (分页 500)
2. blocksToMarkdown -> 转换为 Markdown 正文
├─ 文本/标题/列表/表格/代码块 -> Markdown
├─ image block -> ![图片]() 空占位符(图片单独下载为独立知识条目)
└─ file block -> 附件,作为独立知识条目
3. blocks API 失败或渲染空 -> 回退 export
```
**doc / sheet / bitable:** 走异步导出 API(同 export 模式流程),导出为 .docx / .xlsx 后交 docreader 解析。
**文件 (file):**
```
DownloadDriveFile -> GET /drive/v1/files/{token}/download
```
##### blocks vs export 优缺点
| | export(默认) | blocks |
|---|---|---|
| 解析路径 | 导出 .docx -> docreader | blocks API -> Markdown |
| 图片与文档关联 | ✅ 图片 inline 进父文档,`parent_chunk_id` 关联 | ❌ 图片作为独立知识条目,与文档割裂 |
| 检索 / Wiki / 智能体关联图片 | 是 | 否 |
| 同步速度 | 慢(异步导出 + docx 解析) | 快 |
| docx 内附件(file block) | 丢失(.docx 导出不含) | 保留 |
| 所需权限 | 不需要(但建议保留以便切换) | 需 `docx:document:readonly` |
- **export**:图片 inline 进父文档(同普通 docx 上传),通过 `parent_chunk_id` 建立同知识条目父子关联,三个场景都能关联图片内容;代价是同步慢、docx 内附件丢失、图片 OCR/caption 依赖多模态配置。
- **blocks**:快、保留附件,但图片 block 渲染成空占位符、图片独立入库,与父文档只有元数据级弱关联,检索 / Wiki / 智能体都无法把图片内容关联回文档。
> 环境变量配置见 `.env.example` 的 E9 段。
#### 源码文件
| 文件 | 职责 |
|------|------|
| `internal/datasource/connector/feishu/core/types.go` | 飞书 API 类型定义、配置结构(Config)、Region 常量 |
| `internal/datasource/connector/feishu/core/client.go` | API 客户端:Token 管理、Wiki/Drive API 调用、导出/下载 |
| `internal/datasource/connector/feishu/core/blocks.go` | docx blocks API 类型(DocxBlock 等)、listDocumentBlocks |
| `internal/datasource/connector/feishu/core/markdown.go` | blocksToMarkdown:block 数组转 Markdown |
| `internal/datasource/connector/feishu/core/shared.go` | 共享逻辑:FetchDocxWithBlocks、ParseFeishuConfig、exportDocxFallback |
| `internal/datasource/connector/feishu/core/engine.go` | 通用同步引擎:NodeOps 接口、FetchStreamEngine / FetchAllEngine |
| `internal/datasource/connector/feishu/core/region.go` | Region(飞书 / Lark 云区分)、URL 构造 |
| `internal/datasource/connector/feishu/wiki/connector.go` | 飞书知识库 Connector 实现(wikiOps) |
| `internal/datasource/connector/feishu/drive/connector.go` | 飞书云盘 Connector 实现(driveOps) |
| `internal/datasource/connector/feishu/{core,wiki,drive}/*_test.go` | 单元测试:使用 HTTP Mock 模拟飞书开放平台 |
## 定时调度
### Cron 调度器
数据源同步调度基于 `robfig/cron/v3`,使用 **6 段 Cron 表达式(含秒)**:
```
秒 分 时 日 月 星期
```
**常用预设:**
| 表达式 | 说明 |
|--------|------|
| `0 */30 * * * *` | 每 30 分钟 |
| `0 0 * * * *` | 每小时整点 |
| `0 0 */6 * * *` | 每 6 小时 |
| `0 0 0 * * *` | 每天午夜 |
| `0 0 2 * * *` | 每天凌晨 2 点 |
### 调度生命周期
```
服务启动
│
▼
Scheduler.Start(ctx)
│
├─ 1. 从 DB 加载所有活跃数据源 (FindActive)
│ 条件: status = active, sync_schedule != '', deleted_at IS NULL
│
├─ 2. 为每个数据源注册 Cron Entry
│
└─ 3. 启动 Cron Runner
Cron 触发时:
├─ 检查是否有运行中的同步 (HasRunningSync)
│ 是 → 跳过本次触发
│
├─ 创建 SyncLog (status: running)
│
└─ 入队 asynq 任务
队列: low
TaskID: dssync:<dsID>:<UTC minute>(去重)
```
### 任务去重(两层保护)
1. **DB 层**:`HasRunningSync` 检查该数据源是否已有运行中的同步任务,防止同步耗时超过调度间隔时产生重叠
2. **队列层**:基于 `TaskID`(格式 `dssync:<dataSourceID>:<UTC minute>`)去重,同一分钟内多实例触发时只有第一个成功入队,其余标记为 `canceled`
### 动态管理
| 操作 | 行为 |
|------|------|
| 创建数据源(含 schedule) | 注册 Cron Entry |
| 更新数据源 schedule | 移除旧 Entry → 注册新 Entry |
| 暂停数据源 | 移除 Cron Entry |
| 恢复数据源 | 重新注册 Cron Entry |
| 删除数据源 | 移除 Cron Entry |
---
## 关键参数与阈值
| 参数 | 值 | 说明 |
|------|------|------|
| Token 缓存安全余量 | 5 min | Token 过期前提前刷新(飞书/企微通用) |
| 飞书 Wiki Space 分页大小 | 50 | ListResources 每页返回数 |
| 飞书导出任务轮询间隔 | 2s | 飞书 Export API 状态检查间隔 |
| 飞书导出任务最大等待 | ~60s | 导出任务超时时间 |
| 企微文档列表分页大小 | 50 | wedoc/doc_list 每页返回数 |
| 企微微盘文件列表分页大小 | 1000 | wedrive/file_list 每次拉取最大数 |
| 企微 access_token 有效期 | 7200s | 2 小时,缓存提前 5 分钟刷新 |
| 同步日志保留天数 | 30 天 | 默认值,可配置 |
| 同步日志默认分页 | 10 | GetSyncLogs 默认 limit |
| Cron 表达式格式 | 6 段含秒 | robfig/cron WithSeconds() |
| 定时同步队列 | `low` | asynq 低优先级队列 |
| 手动同步队列 | `default` | asynq 默认队列 |
---
## 错误处理
| 场景 | 处理策略 |
|------|---------|
| 凭证验证失败 | 返回错误信息,数据源状态标记为 `error`,记录 `error_message` |
| 凭证验证成功(原为 error) | 恢复状态为 `active`,清空 `error_message` |
| 连接器未找到 | 返回 `ErrConnectorNotFound` |
| 知识库不存在 | 创建/更新时校验,返回 `ErrKnowledgeBaseNotFound` |
| 数据源不存在 | 返回 `ErrDataSourceNotFound` |
| 数据源非活跃状态触发同步 | 仅允许 `active` 或 `error` 状态手动同步 |
| 同步任务入队失败 | SyncLog 标记为 `failed`,记录错误 |
| 定时同步任务去重 | SyncLog 标记为 `canceled`,错误信息 `deduplicated: another instance enqueued first` |
| 单文档拉取失败 | 记录错误到 FetchedItem.Metadata,不中断整体同步 |
| 单文档入库失败 | 计入 `items_failed`,不中断整体同步 |
| 重复文档 (DuplicateKnowledgeError) | 计入 `items_skipped` |
| 不支持的文档类型 | 静默跳过(如飞书的 mindnote、slides) |
---
## 扩展新连接器
接入新的外部平台只需 3 步:
### 1. 实现 Connector 接口
在 `internal/datasource/connector/<type>/` 下创建连接器:
```go
package myplatform
type Connector struct {
// 连接器配置
}
func NewConnector() *Connector {
return &Connector{}
}
func (c *Connector) Type() string {
return types.ConnectorTypeMyPlatform
}
func (c *Connector) Validate(ctx context.Context, config *types.DataSourceConfig) error {
// 验证凭证:尝试获取 Token 或调用 API
}
func (c *Connector) ListResources(ctx context.Context, config *types.DataSourceConfig) ([]types.Resource, error) {
// 列出可选资源(工作区、空间、文件夹等)
}
func (c *Connector) FetchAll(ctx context.Context, config *types.DataSourceConfig, resourceIDs []string) ([]types.FetchedItem, error) {
// 全量拉取所有文档
}
func (c *Connector) FetchIncremental(ctx context.Context, config *types.DataSourceConfig, cursor *types.SyncCursor) ([]types.FetchedItem, *types.SyncCursor, error) {
// 增量拉取变更(可复用 FetchAll 逻辑 + 编辑时间对比)
}
```
建议的文件结构:
```
internal/datasource/connector/myplatform/
├── types.go # 平台 API 类型定义
├── client.go # API 客户端(Token 管理、HTTP 调用)
└── connector.go # Connector 接口实现
```
### 2. 注册连接器
在 `internal/container/container.go` 的 `initConnectorRegistry` 中注册:
```go
func initConnectorRegistry() *datasource.ConnectorRegistry {
registry := datasource.NewConnectorRegistry()
registry.Register(feishuConnector.NewConnector())
registry.Register(myplatform.NewConnector()) // 新增
return registry
}
```
在 `internal/datasource/connector.go` 的 `ConnectorMetadataRegistry` 中添加元数据:
```go
types.ConnectorTypeMyPlatform: {
Type: types.ConnectorTypeMyPlatform,
Name: "My Platform",
Description: "Import documents from My Platform",
Icon: "myplatform",
Priority: 10,
AuthType: "api_key",
Capabilities: []string{"incremental"},
},
```
在 `internal/types/datasource.go` 中添加类型常量:
```go
const ConnectorTypeMyPlatform = "myplatform"
```
### 3. 前端添加配置
在 `frontend/src/views/knowledge/settings/DataSourceEditorDialog.vue` 中:
- 添加连接器类型选项
- 添加该平台的凭证表单字段
- 标记 `available: true`
在 i18n 文件中添加平台名称翻译。
> Service 层(`DataSourceService`)不需要修改 — 数据源管理、同步调度、内容入库、日志记录全部由 Service 统一处理。可参考飞书连接器 (`internal/datasource/connector/feishu/`) 作为实现参考。

Some files were not shown because too many files have changed in this diff Show More