diff --git a/.env.example b/.env.example index f5092657..52c105c4 100644 --- a/.env.example +++ b/.env.example @@ -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 已预设,不必重复配置)。 diff --git a/.env.lite.example b/.env.lite.example index 27a8ee8c..828c5613 100644 --- a/.env.lite.example +++ b/.env.lite.example @@ -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 diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 9a5b8014..a8d0150d 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -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 diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 4f3b6d55..2fe12c0b 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 2ffc17b5..c3af888e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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: diff --git a/README.md b/README.md index 7ffb788a..790a0b80 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/README_CN.md b/README_CN.md index 1d9c26e0..922d6083 100644 --- a/README_CN.md +++ b/README_CN.md @@ -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) ## 🤝 贡献指南 diff --git a/README_JA.md b/README_JA.md index 47d9bf94..ee879e45 100644 --- a/README_JA.md +++ b/README_JA.md @@ -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) ## 🤝 貢献ガイド diff --git a/README_KO.md b/README_KO.md index 9effadb1..8018bdad 100644 --- a/README_KO.md +++ b/README_KO.md @@ -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) ## 🤝 기여하기 diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml index e4bd51ba..bf802ef8 100644 --- a/docker-compose.dev.yml +++ b/docker-compose.dev.yml @@ -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 diff --git a/docker-compose.yml b/docker-compose.yml index 7d04a7aa..0f15de3c 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -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 关闭限额(不建议共享部署使用) diff --git a/docker/Dockerfile.sandbox b/docker/Dockerfile.sandbox index fc6c8db2..b789ed42 100644 --- a/docker/Dockerfile.sandbox +++ b/docker/Dockerfile.sandbox @@ -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 diff --git a/docs/BUILTIN_MCP_SERVICES.md b/docs/BUILTIN_MCP_SERVICES.md deleted file mode 100644 index ecef2d6f..00000000 --- a/docs/BUILTIN_MCP_SERVICES.md +++ /dev/null @@ -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 服务将恢复为普通服务,可以被编辑和删除。 diff --git a/docs/BUILTIN_MODELS.md b/docs/BUILTIN_MODELS.md deleted file mode 100644 index 3b1eb4d8..00000000 --- a/docs/BUILTIN_MODELS.md +++ /dev/null @@ -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: - tenant_id: # 与 tenants_id_seq 起点对齐 - name: - type: KnowledgeQA | Embedding | Rerank | VLLM | ASR - source: # local | remote | aliyun | ... - description: - is_default: - status: - parameters: - base_url: - api_key: - provider: # openai | generic | moonshot | ... - context_window: # 对话/VLM 上下文窗口(token);省略则默认 200000 - embedding_parameters: # 仅 Embedding 类型 - dimension: - truncate_prompt_tokens: -``` - -#### 完整示例 - -```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 改动不会大规模软删既有内置模型 diff --git a/docs/CHUNKING.md b/docs/CHUNKING.md deleted file mode 100644 index 5aa32ae1..00000000 --- a/docs/CHUNKING.md +++ /dev/null @@ -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 -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. diff --git a/docs/IM集成开发文档.md b/docs/IM集成开发文档.md deleted file mode 100644 index f961be0a..00000000 --- a/docs/IM集成开发文档.md +++ /dev/null @@ -1,1807 +0,0 @@ -# IM 集成开发文档 - -WeKnora 的 IM 集成模块将企业即时通讯平台(企业微信、飞书、Lark、Slack、Telegram、钉钉、Mattermost)接入 WeKnora 知识问答管道,支持在 IM 中直接向 AI 提问并获得实时流式回答。 - -IM 渠道绑定到 Agent,一个 Agent 可接入多个 IM 渠道,所有配置通过前端 Agent 编辑器管理,存储在数据库中。 - -## 目录 - -- [快速接入指南](#快速接入指南) - - [企业微信接入](#企业微信接入) - - [飞书接入](#飞书接入) - - [Lark 接入](#lark-接入) - - [Slack 接入](#slack-接入) - - [Telegram 接入](#telegram-接入) - - [钉钉接入](#钉钉接入) - - [Mattermost 接入](#mattermost-接入) -- [前端管理](#前端管理) -- [架构总览](#架构总览) -- [数据模型](#数据模型) -- [API 端点](#api-端点) -- [核心概念](#核心概念) -- [消息处理流程](#消息处理流程) -- [接口定义](#接口定义) -- [平台适配器详解](#平台适配器详解) - - [企业微信 (WeCom)](#企业微信-wecom) - - [飞书 (Feishu) 与 Lark](#飞书-feishu-与-lark) - - [Slack](#slack) - - [Telegram](#telegram) - - [钉钉 (DingTalk)](#钉钉-dingtalk) - - [Mattermost](#mattermost) -- [斜杠指令系统](#斜杠指令系统) -- [QA 队列与限流](#qa-队列与限流) -- [流式输出机制](#流式输出机制) -- [文件消息处理](#文件消息处理) -- [关键参数与阈值](#关键参数与阈值) -- [错误处理](#错误处理) -- [扩展新平台](#扩展新平台) - ---- - -## 快速接入指南 - -### 前置条件 - -- WeKnora 已部署并运行 -- 已创建至少一个 Agent(自定义智能体) -- Agent 已配置好模型和知识库 - -> **回复图片需公网可达**:IM 显示知识库图片需让 IM 端拿到公网 http 图片 URL,二选一—— -> (A) 存储后端本身公网可达(对象存储公网 endpoint / `MINIO_ENDPOINT` 设为公网); -> (B) 配 `APP_EXTERNAL_URL`,图片走 WeKnora 的 `/r/` 短链(nginx 已内置 `/r/` 代理)。 -> 默认 MinIO 部署走 (B) 最简单。详见 `.env.example` 中 `APP_EXTERNAL_URL` 说明。 - -### 企业微信接入 - -企业微信提供两种接入模式,根据你的应用类型选择: - -#### 方式一:WebSocket 模式(智能机器人,推荐) - -> 无需公网域名,适合快速验证和内网部署。 - -**第一步:创建智能机器人** - -1. 登录 [企业微信工作台](确认已升级到最新版企业微信) → **智能机器人** → **创建机器人** → **手动创建** → **切换API模式创建** → **选择"使用长连接"** -2. 创建完成后,在机器人详情页获取: - - **BotID** — 机器人唯一标识 - - **BotSecret** — 机器人密钥(点击重置可重新生成) - -**第二步:在 WeKnora 中添加 IM 渠道** - -1. 进入 Agent 编辑器 → 左侧导航选择 **IM 集成** 标签页 -2. 点击 **添加渠道** -3. 填写配置: - - **平台**:选择「企业微信」 - - **渠道名称**:自定义名称,方便辨识(如「客服机器人」) - - **接入模式**:选择「WebSocket」 - - **输出模式**:选择「流式输出」(推荐) - - **Bot ID**:填入从企业微信获取的 BotID - - **Bot Secret**:填入从企业微信获取的 BotSecret -4. 点击保存 - -**第三步:验证** - -保存后 WeKnora 会自动建立到企业微信的 WebSocket 长连接。日志中出现以下内容表示连接成功: - -``` -[IM] WeCom WebSocket connecting (bot_id=xxx)... -``` - -此时在企业微信中给机器人发消息即可收到 AI 回复。 - ---- - -#### 方式二:Webhook 模式(自建应用) - -> 需要公网可达的回调地址,适合已有自建应用的场景。 - -**第一步:创建自建应用** - -1. 登录 [企业微信管理后台](https://work.weixin.qq.com/) → **应用管理** → **自建** → **创建应用** -2. 记录以下信息: - - **CorpID** — 在 **我的企业** → **企业信息** 页面底部 - - **AgentID** — 应用详情页中的 AgentId(整数) - - **Secret** — 应用详情页中的 Secret - -**第二步:在 WeKnora 中添加 IM 渠道** - -1. 进入 Agent 编辑器 → **IM 集成** 标签页 → **添加渠道** -2. 填写配置: - - **平台**:选择「企业微信」 - - **接入模式**:选择「Webhook」 - - **输出模式**:选择「流式输出」 - - **Corp ID**:企业 ID - - **Agent Secret**:应用 Secret - - **Token**:自定义或随机生成(记录下来) - - **EncodingAESKey**:自定义或随机生成(记录下来) - - **Corp Agent ID**:应用 AgentID(整数) -3. 保存后,渠道卡片上会显示**回调地址**,格式为 `https://你的域名/api/v1/im/callback/{channel_id}` -4. 复制该回调地址 - -**第三步:配置企业微信接收消息** - -1. 在应用详情页 → **接收消息** → **设置 API 接收** -2. 填写: - - **URL**:粘贴上一步复制的回调地址 - - **Token**:填入在 WeKnora 中设置的 Token - - **EncodingAESKey**:填入在 WeKnora 中设置的 EncodingAESKey -3. 点击保存,企业微信会发送 GET 验证请求,WeKnora 会自动响应 - -**第四步:配置可信域名(可选)** - -如需在群聊中使用,在应用详情页 → **网页授权及 JS-SDK** 中添加可信域名。 - ---- - -### 飞书接入 - -飞书同样提供两种模式,WebSocket 模式配置更简单。 - -#### 方式一:WebSocket 模式(推荐) - -> 无需公网域名,无需配置事件加密。 - -**第一步:创建飞书应用** - -1. 登录 [飞书开放平台](https://open.feishu.cn/) → **开发者后台** → **创建企业自建应用** -2. 在 **凭证与基础信息** 页获取: - - **App ID** - - **App Secret** - -**第二步:开通权限与事件** - -1. **添加应用能力**:在应用详情页 → **添加应用能力** → 添加 **机器人** 能力 -2. **配置权限**:在 **权限管理** 中搜索并开通以下权限:你的应用 → 权限管理 → 批量导入,粘贴下面 JSON(原文内容不变): -```json -{ - "scopes": { - "tenant": [ - "aily:file:read", - "aily:file:write", - "application:application.app_message_stats.overview:readonly", - "application:application:self_manage", - "application:bot.menu:write", - "cardkit:card:write", - "contact:user.employee_id:readonly", - "corehr:file:download", - "docs:document.content:read", - "event:ip_list", - "im:chat", - "im:chat.access_event.bot_p2p_chat:read", - "im:chat.members:bot_access", - "im:message", - "im:message.group_at_msg:readonly", - "im:message.group_msg", - "im:message.p2p_msg:readonly", - "im:message:readonly", - "im:message:send_as_bot", - "im:resource", - "sheets:spreadsheet", - "wiki:wiki:readonly" - ], - "user": [ - "aily:file:read", - "aily:file:write", - "im:chat.access_event.bot_p2p_chat:read" - ] - } -} -``` -3. **配置事件订阅**: - - 在 **事件与回调** → **事件配置** 中,选择请求方式为 **使用长连接接收事件** - - 添加事件 `im.message.receive_v1`(接收消息) - -**第三步:发布应用** - -在 **版本管理与发布** 中创建版本并提交审核。审核通过后用户才能与机器人交互。 - -**第四步:在 WeKnora 中添加 IM 渠道** - -1. 进入 Agent 编辑器 → **IM 集成** → **添加渠道** -2. 填写配置: - - **平台**:选择「飞书」 - - **接入模式**:选择「WebSocket」 - - **输出模式**:选择「流式输出」(需开启 cardkit:card 权限) - - **App ID**:填入从飞书获取的 App ID - - **App Secret**:填入从飞书获取的 App Secret -3. 保存 - -启动后日志出现以下内容表示连接成功: - -``` -[IM] Feishu WebSocket connecting (app_id=xxx)... -``` - ---- - -#### 方式二:Webhook 模式 - -> 需要公网可达的回调地址。 - -**前置步骤**同上(创建应用、开通权限),额外需要: - -**第一步:在 WeKnora 中添加 IM 渠道** - -1. 进入 Agent 编辑器 → **IM 集成** → **添加渠道** -2. 填写配置: - - **平台**:选择「飞书」 - - **接入模式**:选择「Webhook」 - - **App ID** / **App Secret** - - **Verification Token**:从飞书事件订阅页面获取 - - **Encrypt Key**:从飞书事件订阅页面获取 -3. 保存后,复制渠道卡片上显示的**回调地址** - -**第二步:配置飞书事件订阅** - -1. 在 **事件与回调** → **事件配置** 中,选择请求方式为 **将事件发送到开发者服务器** -2. **请求地址**:粘贴从 WeKnora 复制的回调地址 -3. 添加事件 `im.message.receive_v1` -4. 点击保存时飞书会发送 URL 验证请求(challenge),WeKnora 会自动响应 - ---- - -#### API Base URL(可选,内网代理) - -渠道配置里的 **API Base URL** 是可选字段,用于让 WeKnora 通过反向代理访问飞书开放平台: - -- **服务器能直连外网** → **留空**即可,默认访问 `https://open.feishu.cn` -- **服务器需要代理才能访问外网**(如内网部署)→ 填写反向代理地址(如 nginx,`http://10.0.0.1:8080/feishu`) - -该地址同时覆盖飞书 IM 的所有出站调用,一个字段统一管控: - -| 出站 | 说明 | -|---|---| -| WebSocket bootstrap | SDK 拿 wss 地址的请求 | -| wss 长连接 | 收消息的 WebSocket(经改写后的地址) | -| HTTP API | token、发消息、下载文件、CardKit 流式卡片 | - -**nginx 反向代理要点**(WebSocket 模式,已生产验证): - -飞书 bootstrap 返回的 ws 地址 host 是 **`msg-frontier.feishu.cn`**(长连接专用域名,**不是 `open.feishu.cn`**),path 是 `/ws/v2`。因此 nginx 需要**三个 location**,upstream 不同不能混: - -| location | 匹配 | upstream | 作用 | -|---|---|---|---| -| `= /<前缀>/callback/ws/endpoint` | bootstrap POST | `open.feishu.cn` | 拿 ws 地址 + `sub_filter` 改写 | -| `/<前缀>/ws/` | ws dial(GET+Upgrade) | **`msg-frontier.feishu.cn`** | WebSocket 长连接反代 | -| `/<前缀>/` | OpenAPI HTTP | `open.feishu.cn` | token/发消息/下载文件/卡片 | - -- `sub_filter` 替换的是 `wss://msg-frontier.feishu.cn`(不是 `open.feishu.cn`),改成 `ws:///<前缀>`,WeKnora 才会明文回连 nginx -- ws dial 的 upstream 必须是 `msg-frontier.feishu.cn`,若误指 `open.feishu.cn` 会 404(open.feishu.cn 不处理 `/ws/v2`) -- `rewrite` 模式要与 location 前缀一致(如 `location /weknora/feishu/ws/` 配 `rewrite ^/weknora/feishu/(.*)$ /$1 break`),否则前缀不剥离 -> 飞书 404 -> ws 握手失败 -- `map $http_upgrade $connection_upgrade` 区分 POST(Connection=close)与 ws(Connection=upgrade),三者共存 -- 不需要 nginx 支持 CONNECT - -以下为生产验证通过的完整配置(按实际调整地址与前缀): - -```nginx -map $http_upgrade $connection_upgrade { - default upgrade; - '' close; -} - -server { - listen 80; - server_name <能访问外网的Nginx 主机IP>; - - # ① bootstrap:POST /callback/ws/endpoint -> open.feishu.cn + sub_filter 改写 wss URL - location = /weknora/feishu/callback/ws/endpoint { - resolver 114.114.114.114 8.8.8.8 valid=300s ipv6=off; - set $feishu_host "open.feishu.cn"; - rewrite ^/weknora/feishu/(.*)$ /$1 break; - proxy_pass https://$feishu_host; - - proxy_ssl_server_name on; - proxy_ssl_name open.feishu.cn; - proxy_ssl_protocols TLSv1.2 TLSv1.3; - proxy_ssl_verify off; - proxy_set_header Host open.feishu.cn; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_http_version 1.1; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection $connection_upgrade; - - # 禁 gzip,sub_filter 才能改写 JSON - proxy_set_header Accept-Encoding ""; - # 飞书下发的 wss host 是 msg-frontier.feishu.cn(长连接专用域名,非 open.feishu.cn) - sub_filter 'wss://msg-frontier.feishu.cn' 'ws://<能访问外网的Nginx 主机IP>/weknora/feishu'; - sub_filter_once off; - sub_filter_types application/json; - } - - # ② ws dial:WebSocket 长连接 -> msg-frontier.feishu.cn(upstream 不是 open.feishu.cn!) - location /weknora/feishu/ws/ { - resolver 114.114.114.114 8.8.8.8 valid=300s ipv6=off; - set $feishu_host "msg-frontier.feishu.cn"; - rewrite ^/weknora/feishu/(.*)$ /$1 break; - proxy_pass https://$feishu_host; - - proxy_ssl_server_name on; - proxy_ssl_name msg-frontier.feishu.cn; - proxy_ssl_protocols TLSv1.2 TLSv1.3; - proxy_ssl_verify off; - proxy_set_header Host msg-frontier.feishu.cn; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - - proxy_http_version 1.1; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection $connection_upgrade; - - proxy_buffering off; - proxy_cache off; - proxy_request_buffering off; - chunked_transfer_encoding on; - - proxy_connect_timeout 60s; - proxy_send_timeout 3600s; - proxy_read_timeout 3600s; - send_timeout 3600s; - - client_max_body_size 0; - proxy_max_temp_file_size 0; - } - - # ③ OpenAPI HTTP:token/发消息/下载文件/CardKit -> open.feishu.cn - location /weknora/feishu/ { - resolver 114.114.114.114 8.8.8.8 valid=300s ipv6=off; - set $feishu_host "open.feishu.cn"; - rewrite ^/weknora/feishu/(.*)$ /$1 break; - proxy_pass https://$feishu_host; - - proxy_ssl_server_name on; - proxy_ssl_name open.feishu.cn; - proxy_ssl_protocols TLSv1.2 TLSv1.3; - proxy_ssl_verify off; - proxy_set_header Host open.feishu.cn; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - - proxy_http_version 1.1; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection $connection_upgrade; - - proxy_buffering off; - proxy_read_timeout 3600s; - proxy_send_timeout 3600s; - client_max_body_size 0; - } -} -``` - -> 验证 sub_filter 生效:`curl -s http://127.0.0.1/weknora/feishu/callback/ws/endpoint -X POST -H 'Content-Type: application/json' -d '{"AppID":"xxx","AppSecret":"xxx"}'`,返回的 `data.URL` 应为 `ws://<能访问外网的Nginx 主机IP>/weknora/feishu/ws/v2?...`(不再是 `wss://msg-frontier.feishu.cn/...`)。WeKnora 日志出现 `[IM] Feishu WebSocket connected successfully` 即长连接建立。 - -**SSRF 白名单**:若 `api_base_url` 是内网地址,需把主机名加入 `SSRF_WHITELIST` 环境变量,否则 SSRF 防护会拦截。 - -> Webhook 模式下,`api_base_url` 只影响出站 HTTP API;飞书回调 WeKnora 的入站路径不受影响(回调地址在渠道卡片上单独配置)。 -> Lark 国际版同理,只是默认域名换成 `https://open.larksuite.com`。 - ---- - -### Lark 接入 - -Lark 是飞书的国际版。两者是同一产品部署在两朵相互隔离的云上,**IM 的 API 接口、事件结构、 -凭证字段、接入模式一致**,因此 WeKnora 中 Lark 与飞书共用同一套适配器代码。 - -但「代码一致」不等于「配置一致」,接入时有三处差别: - -| | 飞书 | Lark | -|---|---|---| -| 开放平台 | | | -| 添加渠道时的**平台**选项 | 「飞书」 | 「Lark(飞书国际版)」 | -| 权限清单 | [飞书接入](#飞书接入)一节的 JSON | [Lark 权限配置](#lark-权限配置)一节的 JSON(**不可套用飞书的**) | - -创建应用、添加机器人能力、订阅 `im.message.receive_v1` 事件、发布版本、填写 -App ID / App Secret 等步骤与[飞书接入](#飞书接入)一节相同。**唯独权限配置不同,见下。** - -#### Lark 权限配置 - -在 Lark 开放平台 **权限管理 → 批量导入** 粘贴下面的 JSON,覆盖 IM 机器人与知识库(Wiki) -数据源两块功能: - -```json -{ - "scopes": { - "tenant": [ - "im:message", - "im:message:send_as_bot", - "im:resource", - "im:message.p2p_msg:readonly", - "im:message.group_at_msg:readonly", - "cardkit:card:write", - "wiki:wiki:readonly", - "drive:export:readonly", - "drive:drive:readonly", - "docx:document:readonly" - ], - "user": [] - } -} -``` - -> 不要套用[飞书接入](#飞书接入)一节的 JSON:其中 `aily:file:*`、`corehr:file:download` -> 在 Lark 不存在,整份导入会失败。 - -> **注意**:飞书应用与 Lark 应用互不通用。在 open.feishu.cn 创建的应用无法用于 Lark 渠道, -> 反之亦然——凭证只在创建它的那朵云上有效,跨云调用会认证失败。 - -WebSocket 模式启动后日志出现以下内容表示连接成功: - -``` -[IM] Lark WebSocket connecting (app_id=xxx)... -``` - -同一个 App ID 在两朵云上分别注册时,WeKnora 通过 `平台:app_id` 区分(如 `feishu:cli_xxx` -与 `lark:cli_xxx`),两个渠道可以并存,会话互不干扰。 - ---- - -### Slack 接入 - -Slack 提供两种接入模式,推荐使用 WebSocket (Socket Mode) 模式,无需公网域名。 - -#### 方式一:WebSocket 模式(Socket Mode,推荐) - -> 无需公网域名,适合快速验证和内网部署。 - -**第一步:创建 Slack App** - -1. 登录 [Slack API](https://api.slack.com/apps) → **Create New App** → **From scratch** -2. 填写 App Name 并选择要安装的 Workspace。 - -**第二步:生成 App-Level Token** - -1. 在应用详情页左侧导航栏选择 **Basic Information**。 -2. 滚动到 **App-Level Tokens** 区域,点击 **Generate Token and Scopes**。 -3. 填写 Token Name,添加 `connections:write` scope。 -4. 点击 Generate,复制生成的 Token(以 `xapp-` 开头),这就是 **App Token**。 - -**第三步:开启 Socket Mode** - -1. 在左侧导航栏选择 **Socket Mode**。 -2. 开启 **Enable Socket Mode** 开关。 - -**第四步:配置 Event Subscriptions** - -1. 在左侧导航栏选择 **Event Subscriptions**。 -2. 开启 **Enable Events** 开关。 -3. 展开 **Subscribe to bot events**,添加以下事件: - - `app_mention` (在频道中 @ 机器人) - - `message.channels` (频道消息) - - `message.groups` (私有频道消息) - - `message.im` (私聊消息) - - `message.mpim` (多人私聊消息) -4. 点击 **Save Changes**。 - -**第五步:配置权限 (OAuth & Permissions)** - -1. 在左侧导航栏选择 **OAuth & Permissions**。 -2. 滚动到 **Scopes** -> **Bot Token Scopes**,确保包含以下权限(添加事件时通常会自动添加): - - `app_mentions:read` - - `channels:history` - - `chat:write` - - `groups:history` - - `im:history` - - `mpim:history` - - `files:read` (用于接收文件) -3. 滚动到顶部,点击 **Install to Workspace**。 -4. 授权后,复制 **Bot User OAuth Token**(以 `xoxb-` 开头),这就是 **Bot Token**。 - -**第六步:在 WeKnora 中添加 IM 渠道** - -1. 进入 Agent 编辑器 → **IM 集成** → **添加渠道** -2. 填写配置: - - **平台**:选择「Slack」 - - **接入模式**:选择「WebSocket」 - - **输出模式**:选择「流式输出」 - - **App Token**:填入以 `xapp-` 开头的 Token - - **Bot Token**:填入以 `xoxb-` 开头的 Token -3. 保存 - -启动后日志出现以下内容表示连接成功: - -``` -[IM] Slack WebSocket connecting... -``` - ---- - -#### 方式二:Webhook 模式 (Events API) - -> 需要公网可达的回调地址。 - -**第一步:创建 Slack App 并获取凭证** - -1. 登录 [Slack API](https://api.slack.com/apps) 创建应用。 -2. 在 **Basic Information** 页面,滚动到 **App Credentials** 区域,复制 **Signing Secret**。 -3. 在 **OAuth & Permissions** 页面,配置 Bot Token Scopes(同上),安装到 Workspace,复制 **Bot User OAuth Token**(Bot Token)。 - -**第二步:在 WeKnora 中添加 IM 渠道** - -1. 进入 Agent 编辑器 → **IM 集成** → **添加渠道** -2. 填写配置: - - **平台**:选择「Slack」 - - **接入模式**:选择「Webhook」 - - **Bot Token**:填入以 `xoxb-` 开头的 Token - - **Signing Secret**:填入 Signing Secret -3. 保存后,复制渠道卡片上显示的**回调地址**。 - -**第三步:配置 Event Subscriptions** - -1. 在 Slack App 设置页左侧导航栏选择 **Event Subscriptions**。 -2. 开启 **Enable Events** 开关。 -3. 在 **Request URL** 中粘贴从 WeKnora 复制的回调地址。Slack 会发送一个 challenge 请求,WeKnora 会自动响应并验证通过。 -4. 展开 **Subscribe to bot events**,添加需要的事件(同上)。 -5. 点击 **Save Changes**。 - ---- - -### Telegram 接入 - -Telegram 提供两种接入模式,推荐使用 WebSocket(长轮询)模式,无需公网域名。 - -#### 方式一:WebSocket 模式(长轮询,推荐) - -> 无需公网域名,适合快速验证和内网部署。 - -**第一步:创建 Telegram Bot** - -1. 在 Telegram 中搜索 [@BotFather](https://t.me/BotFather) 并开始对话 -2. 发送 `/newbot`,按提示填写 Bot 名称和用户名 -3. 创建完成后获取 **Bot Token**(格式如 `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`) - -**第二步:在 WeKnora 中添加 IM 渠道** - -1. 进入 Agent 编辑器 → **IM 集成** → **添加渠道** -2. 填写配置: - - **平台**:选择「Telegram」 - - **接入模式**:选择「WebSocket」 - - **输出模式**:选择「流式输出」(推荐) - - **Bot Token**:填入从 BotFather 获取的 Token -3. 保存 - -启动后日志出现以下内容表示连接成功: - -``` -[IM] Telegram long polling connecting... -``` - -此时在 Telegram 中给 Bot 发送消息即可收到 AI 回复。 - ---- - -#### 方式二:Webhook 模式 - -> 需要公网可达的回调地址(HTTPS)。 - -**第一步:创建 Telegram Bot 并获取凭证** - -同上,通过 BotFather 创建 Bot 并获取 Bot Token。 - -**第二步:在 WeKnora 中添加 IM 渠道** - -1. 进入 Agent 编辑器 → **IM 集成** → **添加渠道** -2. 填写配置: - - **平台**:选择「Telegram」 - - **接入模式**:选择「Webhook」 - - **Bot Token**:填入 Bot Token - - **Secret Token**(可选):自定义密钥,用于验证回调请求的 `X-Telegram-Bot-Api-Secret-Token` 头 -3. 保存后,复制渠道卡片上显示的**回调地址** - -**第三步:配置 Webhook** - -通过 Telegram Bot API 设置 Webhook: - -```bash -curl -X POST "https://api.telegram.org/bot/setWebhook" \ - -H "Content-Type: application/json" \ - -d '{"url": "", "secret_token": ""}' -``` - -> 注意:Telegram Webhook 必须使用 HTTPS。 - ---- - -### 钉钉接入 - -钉钉提供两种接入模式,推荐使用 Stream 模式(WebSocket),无需公网域名。 - -#### 方式一:WebSocket 模式(Stream,推荐) - -> 无需公网域名,适合快速验证和内网部署。 - -**第一步:创建钉钉机器人** - -1. 登录 [钉钉开放平台](https://open-dev.dingtalk.com/) → **应用开发** → **创建应用** -2. 在应用详情页 → **添加应用能力** → 添加 **机器人** 能力 -3. 在 **凭证与基础信息** 页获取: - - **Client ID**(AppKey) - - **Client Secret**(AppSecret) - -**第二步:配置机器人** - -1. 在应用详情页 → **机器人** → 配置消息接收模式为 **Stream 模式** -2.(可选)如需流式 AI 卡片效果,在 **互动卡片** 中创建一个 **AI 卡片模板**,记录 **Card Template ID** - -**第三步:在 WeKnora 中添加 IM 渠道** - -1. 进入 Agent 编辑器 → **IM 集成** → **添加渠道** -2. 填写配置: - - **平台**:选择「钉钉」 - - **接入模式**:选择「WebSocket」 - - **输出模式**:选择「流式输出」(推荐) - - **Client ID**:填入 AppKey - - **Client Secret**:填入 AppSecret - - **Card Template ID**(可选):填入 AI 卡片模板 ID,启用后流式回复将以 AI 卡片形式展示 -3. 保存 - -启动后日志出现以下内容表示连接成功: - -``` -[IM] DingTalk Stream connecting... -``` - -> **关于 AI 卡片**:配置 Card Template ID 后,流式回复将通过钉钉 AI 卡片实时展示打字效果;未配置时流式内容将在结束后一次性发送。 - ---- - -#### 方式二:Webhook 模式 - -> 需要公网可达的回调地址。 - -**第一步:创建钉钉机器人并获取凭证** - -同上,创建应用并获取 Client ID 和 Client Secret。 - -**第二步:在 WeKnora 中添加 IM 渠道** - -1. 进入 Agent 编辑器 → **IM 集成** → **添加渠道** -2. 填写配置: - - **平台**:选择「钉钉」 - - **接入模式**:选择「Webhook」 - - **Client ID**:填入 AppKey - - **Client Secret**:填入 AppSecret - - **Card Template ID**(可选):同上 -3. 保存后,复制渠道卡片上显示的**回调地址** - -**第三步:配置钉钉事件订阅** - -1. 在应用详情页 → **机器人** → 配置消息接收模式为 **HTTP 模式** -2. **消息接收地址**:粘贴从 WeKnora 复制的回调地址 -3. 钉钉会通过 HmacSHA256 签名验证回调请求 - ---- - -### Mattermost 接入 - -Mattermost 为**自建部署**,当前仅支持 **Webhook** 模式:**出站 Webhook(Outgoing Webhook)** 将用户消息 POST 到 WeKnora,Bot 通过 **REST API v4** 发回频道/线程回复。与 Slack Events API 类似,回调需快速返回 `200`,实际回答由 Bot Token 异步调用接口完成。 - -> 需要公网或内网可达的回调 URL(Mattermost 服务器能访问 WeKnora 的 `/api/v1/im/callback/{channel_id}`)。若 WeKnora 在内网,请在 Mattermost 中配置 [Trusted Internal Connections](https://docs.mattermost.com/configure/environment-configuration-settings.html) 或将回调地址加入允许列表。 - -#### 第一步:创建 Bot 账户并获取 Token - -1. 在 Mattermost 中创建专用 Bot 账户(或使用个人账户的 **Personal Access Token**,不推荐生产环境)。 -2. 为 Bot 授予在目标频道/团队发消息、读取文件等所需权限(若需将用户上传的文件写入知识库,需能下载附件)。 -3. 在 **Profile → Security → Personal Access Tokens**(或 Bot 设置)生成 Token,复制保存为 **Bot Token**。 - -#### 第二步:创建 Outgoing Webhook - -1. 打开 **产品菜单 → 集成 → 出站 Webhook**(若不可见,需系统管理员在 **系统控制台 → 集成** 中启用出站 Webhook)。 -2. 点击 **Add Outgoing Webhook**,填写标题与描述。 -3. **Content Type** 建议选择 **application/json**(也支持 `application/x-www-form-urlencoded`,WeKnora 两种均可解析)。 -4. 选择触发频道,或配置**触发词**(与频道组合规则以 Mattermost 说明为准)。 -5. **Callback URLs** 先留空或填占位;保存后在 WeKnora 创建渠道后会得到正式地址。 -6. 保存后复制页面上的 **Token**(出站 Webhook 密钥),即 **Outgoing Webhook Token**。 - -#### 第三步:在 WeKnora 中添加 IM 渠道 - -1. 进入 Agent 编辑器 → **IM 集成** → **添加渠道**。 -2. 填写配置: - - **平台**:选择「Mattermost」 - - **接入模式**:固定为 **Webhook**(选择 Mattermost 后界面会禁用 WebSocket) - - **输出模式**:流式输出 / 完整输出(流式通过编辑帖子实现) - - **Site URL**:Mattermost 站点根地址,如 `https://mattermost.example.com`(无尾部 `/`) - - **Bot Token**:上一步生成的 Token - - **Outgoing Webhook Token**:出站 Webhook 页面复制的 Token(用于校验回调,且参与 `bot_identity` 去重) - - **Bot User ID**(可选):Bot 在 Mattermost 中的用户 ID;填写后可忽略 Bot 自身触发的回调,避免自回复循环 -3. 保存后,复制渠道卡片上的 **回调地址**,回到 Mattermost 出站 Webhook 配置,将 **Callback URLs** 设为该地址并保存。 - -#### 第四步:验证 - -在绑定频道发送触发出站 Webhook 的消息,应收到 WeKnora 的回复;回复默认出现在**触发帖所在线程**(使用 Mattermost 的 `root_id` 与触发 `post_id` 对齐)。 - -**参考文档:** [Outgoing webhooks](https://developers.mattermost.com/integrate/webhooks/outgoing/) - - ---- - -## 前端管理 - -IM 渠道在 Agent 编辑器的 **IM 集成** 标签页中管理(仅编辑模式可见,创建 Agent 时不显示)。 - -### 渠道列表 - -每个渠道以卡片形式展示,包含: -- **平台标识**:企业微信(绿色)/ 飞书(青色)/ Lark(蓝色)/ Slack(紫色)/ Telegram(蓝色)/ 钉钉(蓝色)/ Mattermost(蓝色) -- **渠道名称**:用户自定义 -- **接入模式**:WebSocket / Webhook -- **输出模式**:流式输出 / 完整输出 -- **启用开关**:可即时启用/停用渠道 -- **回调地址**:Webhook 模式下显示,可一键复制 -- **编辑/删除**:管理渠道配置 - -### 渠道操作 - -- **添加渠道**:选择平台 → 填写凭证 → 选择模式 → 保存 -- **编辑渠道**:可修改名称、模式、输出模式和凭证(平台不可更改) -- **启用/停用**:通过开关即时切换,停用的渠道不会处理消息 -- **删除渠道**:删除后不可恢复 - ---- - -## 架构总览 - -``` -┌──────────────────────────────────────────────────────────────────────────────┐ -│ IM 集成架构 │ -│ │ -│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ -│ │ 企业微信 │ │ 飞书 │ │ Slack │ │ Telegram │ │ 钉钉 │ IM层│ -│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ -│ │ WH/WS │ WH/WS │ WH/WS │ WH/LP │ WH/Stream │ -│ ─────┼─────────────┼────────────┼─────────────┼─────────────┼────────── │ -│ ▼ ▼ ▼ ▼ ▼ │ -│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ -│ │ WeCom │ │ Feishu │ │ Slack │ │ Telegram │ │ DingTalk │ 适配 │ -│ │ Adapter │ │ Adapter │ │ Adapter │ │ Adapter │ │ Adapter │ 器层 │ -│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ -│ │ │ │ │ │ │ -│ ─────┼─────────────┼─────────────┼──────────────┼─────────────┼──────── │ -│ └─────────────┼─────────────┼──────────────┘─────────────┘ │ -│ │ │ -│ ┌────┴────────────┐ │ -│ │ Mattermost │ Webhook-only │ -│ └────────┬────────┘ │ -│ ▼ │ -│ ┌────────────────┐ │ -│ │ Mattermost │ │ -│ │ Adapter │ │ -│ └────────┬────────┘ │ -│ │ │ -│ ──────────────────┴────────────────────────────────────────────────────│ -│ ▼ │ -│ ┌──────────────────────────────────┐ │ -│ │ im.Service │ 服务编排层 │ -│ │ │ · IM 渠道管理 (CRUD) │ -│ │ ┌────────────────────────────┐ │ · Adapter Factory (动态创建) │ -│ │ │ CommandRegistry │ │ · 斜杠指令分发 │ -│ │ │ qaQueue (Worker Pool) │ │ · QA 队列调度 (有界, 异步) │ -│ │ │ rateLimiter (滑动窗口) │ │ · 滑动窗口限流 │ -│ │ │ processedMsgs (去重) │ │ · 消息去重 (MessageID + TTL) │ -│ │ │ inflight (取消跟踪) │ │ · 会话映射 (ChannelSession) │ -│ │ └────────────────────────────┘ │ · 流式/全量路由 │ -│ └──────────────┬───────────────────┘ │ -│ │ │ -│ ───────────────┼─────────────────────────────────────────────────────── │ -│ ▼ │ -│ ┌──────────────────────────────────────┐ │ -│ │ WeKnora Core (QA Pipeline) │ 核心层 │ -│ │ SessionService · MessageService │ │ -│ │ TenantService · AgentService │ │ -│ │ KnowledgeService (文件保存) │ │ -│ └──────────────────────────────────────┘ │ -└──────────────────────────────────────────────────────────────────────────────┘ -``` - -**设计模式:** - -| 模式 | 用途 | -|------|------| -| Adapter Pattern | 统一不同 IM 平台的差异,每个平台实现 `im.Adapter` 接口 | -| Factory Pattern | 通过 `AdapterFactory` 从数据库渠道配置动态创建 Adapter 实例 | -| Strategy Pattern | `StreamSender`、`FileDownloader` 可选接口,按需实现 | -| Command Pattern | `Command` 接口 + `CommandRegistry` 实现可插拔的斜杠指令系统 | -| Producer-Consumer | `qaQueue` 有界队列 + Worker Pool,解耦消息接收与 QA 执行 | -| Event-Driven | 通过 `EventBus` 解耦 QA 管道与 IM 输出,支持实时块推送 | - ---- - -## 数据模型 - -### im_channels 表 - -IM 渠道配置存储在 `im_channels` 表中,绑定到 Agent: - -```sql -CREATE TABLE im_channels ( - id VARCHAR(36) PRIMARY KEY, - tenant_id BIGINT NOT NULL, - agent_id VARCHAR(36) NOT NULL, -- 绑定的 Agent ID - platform VARCHAR(20) NOT NULL, -- 'wecom' | 'feishu' | 'lark' | 'slack' | 'telegram' | 'dingtalk' | 'mattermost' - name VARCHAR(255) NOT NULL DEFAULT '', - enabled BOOLEAN NOT NULL DEFAULT true, - mode VARCHAR(20) NOT NULL DEFAULT 'websocket', -- 'webhook' | 'websocket' - output_mode VARCHAR(20) NOT NULL DEFAULT 'stream', -- 'stream' | 'full' - knowledge_base_id VARCHAR(36), -- 可选,绑定知识库以接收文件消息 - bot_identity VARCHAR(255), -- 计算字段,防止重复机器人 - credentials JSONB NOT NULL DEFAULT '{}', -- 平台凭证 - created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP, - updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP, - deleted_at TIMESTAMPTZ -); -``` - -**credentials 字段结构:** - -| 平台 | 模式 | 字段 | -|------|------|------| -| 企业微信 | WebSocket | `bot_id`, `bot_secret` | -| 企业微信 | Webhook | `corp_id`, `agent_secret`, `token`, `encoding_aes_key`, `corp_agent_id` | -| 飞书 / Lark | WebSocket | `app_id`, `app_secret` | -| 飞书 / Lark | Webhook | `app_id`, `app_secret`, `verification_token`, `encrypt_key` | -| Slack | WebSocket | `app_token`, `bot_token` | -| Slack | Webhook | `bot_token`, `signing_secret` | -| Telegram | WebSocket | `bot_token` | -| Telegram | Webhook | `bot_token`, `secret_token`(可选) | -| 钉钉 | WebSocket | `client_id`, `client_secret`, `card_template_id`(可选) | -| 钉钉 | Webhook | `client_id`, `client_secret`, `card_template_id`(可选) | -| Mattermost | Webhook(唯一支持) | `site_url`, `bot_token`, `outgoing_token`(必填);`bot_user_id`(可选,过滤机器人自身消息) | - -`mattermost` 渠道的 `mode` 在数据库中固定为 `webhook`(创建时若未指定,服务端与模型钩子会默认 `webhook`)。`bot_identity` 形如 `mattermost:wh:{outgoing_token}`,用于防止同一出站 Webhook 重复绑定多个渠道。 - -### im_channel_sessions 表 - -将 IM 渠道中的用户会话映射到 WeKnora 会话: - -``` -(im_channel_id, Platform, UserID, ChatID, TenantID) → SessionID -``` - -首次交互自动创建,后续消息复用同一会话。`/clear` 指令会软删除会话记录,下次消息重新创建。 - ---- - -## API 端点 - -### IM 渠道管理 API(需认证) - -| 方法 | 路径 | 说明 | -|------|------|------| -| POST | `/api/v1/agents/:id/im-channels` | 创建 IM 渠道 | -| GET | `/api/v1/agents/:id/im-channels` | 列出 Agent 的所有 IM 渠道 | -| PUT | `/api/v1/im-channels/:id` | 更新 IM 渠道 | -| DELETE | `/api/v1/im-channels/:id` | 删除 IM 渠道 | -| POST | `/api/v1/im-channels/:id/toggle` | 启用/停用 IM 渠道 | - -### IM 回调端点(无需认证,平台签名验证) - -| 方法 | 路径 | 说明 | -|------|------|------| -| GET/POST | `/api/v1/im/callback/:channel_id` | 通用回调(根据 channel_id 自动路由到对应 Adapter) | - -> Webhook 模式下,每个渠道有唯一的回调地址 `/api/v1/im/callback/{channel_id}`,在前端渠道卡片上可一键复制。回调路由注册在认证中间件**之前**,由平台签名验证保护。 - ---- - -## 核心概念 - -### IMChannel — IM 渠道 - -每个 IM 渠道代表一个 IM 平台机器人与 WeKnora Agent 的绑定关系。一个 Agent 可以绑定多个渠道(如同时接入企业微信、飞书、Slack 与 Mattermost),同一平台也可以创建多个渠道(如不同的企业微信机器人)。 - -渠道有一个计算字段 `BotIdentity`,由平台类型、模式和核心凭证推导,用于防止同一机器人被重复创建。 - -渠道启动时,Service 通过 `AdapterFactory` 根据平台类型和凭证动态创建对应的 Adapter 实例。 - -### IncomingMessage — 统一入站消息 - -所有平台的消息在解密、解析后被归一化为 `IncomingMessage`,抹平平台差异: - -```go -type IncomingMessage struct { - Platform Platform // "wecom" | "feishu" | "lark" | "slack" | "telegram" | "dingtalk" | "mattermost" - MessageType MessageType // "text" | "file" | "image" - UserID string // 平台用户标识 - UserName string // 显示名 (可选) - ChatID string // 群聊 ID (私聊为空) - ChatType ChatType // "direct" | "group" - Content string // 纯文本内容 - MessageID string // 平台消息 ID (用于去重) - FileKey string // 文件标识 (文件/图片消息) - FileName string // 文件名 (文件/图片消息) - FileSize int64 // 文件大小 (字节) - Extra map[string]string // 平台特有字段 (如 req_id、aes_key) -} -``` - -### ReplyMessage — 统一出站回复 - -```go -type ReplyMessage struct { - Content string // Markdown 文本 - IsStreaming bool // 是否为流式块 - IsFinal bool // 是否为最后一块 - Extra map[string]string // 平台特有字段 -} -``` - -### ChannelSession — 会话映射 - -将 IM 渠道 (渠道 ID + 用户 + 群聊) 映射到 WeKnora 会话,实现对话上下文持续性。首次交互自动创建,后续消息复用同一会话。并发创建通过唯一约束 + fallback 查询处理。存储于 `im_channel_sessions` 表。 - ---- - -## 消息处理流程 - -### 完整消息处理流程 - -``` -用户在 IM 中发送消息 - │ - ▼ -┌─ HTTP Handler / WebSocket 回调 ─────────────────┐ -│ 1. 根据 channel_id 查找渠道配置 │ -│ 2. 获取对应 Adapter │ -│ 3. 签名验证 (VerifyCallback) │ -│ 4. URL 验证处理 (HandleURLVerification) │ -│ 5. 解密 + 解析 → IncomingMessage (ParseCallback) │ -│ 6. 立即返回 HTTP 200 (异步处理) │ -└──────────────────────────┬──────────────────────-┘ - │ goroutine - ▼ -┌─ im.Service.HandleMessage ──────────────────────┐ -│ 1. 去重检查 (MessageID, 5 分钟 TTL) │ -│ 2. 内容长度校验 (≤ 4096 rune,超出截断) │ -│ 3. 斜杠指令检测 → 命中则分发到 CommandRegistry │ -│ 4. 限流检查 (滑动窗口, 10次/60s) │ -│ 5. 从渠道配置获取 agent_id、tenant_id │ -│ 6. 解析/创建 ChannelSession │ -│ 7. 获取 WeKnora Session │ -│ 8. 加载 Agent 配置(获取知识库、模型等信息) │ -│ 9. 所有消息提交到 qaQueue (有界队列, 异步执行) │ -└───────────┬─────────────────────────────────────┘ - │ - ▼ -┌─ qaQueue Worker ────────────────────────────────┐ -│ 从队列取出请求,记录 inflight,判断流式/全量模式 │ -└───────────┬─────────────────────┬───────────────┘ - │ │ - 流式模式 ▼ 全量模式 ▼ -┌────────────────────┐ ┌─────────────────────┐ -│ handleMessageStream│ │ runQA (阻塞收集完整 │ -│ │ │ 回答后一次性发送) │ -│ · StartStream │ └─────────────────────┘ -│ · EventBus 订阅 │ -│ · 300ms 批量刷新 │ -│ · 工具事件展示 │ -│ · UpdateStreamContent │ -│ · FinalizeStream │ -│ · EndStream │ -└────────────────────┘ - │ - ▼ - 消息持久化 (user + assistant) -``` - -### 渠道生命周期 - -``` -渠道创建/更新 (前端 UI) - │ - ▼ -┌─ im.Service ──────────────────────────┐ -│ 1. 保存渠道配置到数据库 │ -│ 2. 如果渠道已启用: │ -│ a. AdapterFactory 创建 Adapter │ -│ b. WebSocket 模式:建立长连接 │ -│ c. Webhook 模式:注册回调处理 │ -│ 3. 维护 channels map (channel_id → │ -│ channelState{Channel, Adapter}) │ -└────────────────────────────────────────┘ - -服务启动时: - LoadAndStartChannels() → 从 DB 加载所有 enabled 的渠道 → 逐个 StartChannel() - -渠道停用/删除时: - StopChannel() → 取消 Adapter 上下文 → 从 map 移除 -``` - ---- - -## 接口定义 - -### im.Adapter — 平台适配器 (必须实现) - -```go -type Adapter interface { - Platform() Platform - VerifyCallback(c *gin.Context) error - ParseCallback(c *gin.Context) (*IncomingMessage, error) - SendReply(ctx context.Context, incoming *IncomingMessage, reply *ReplyMessage) error - HandleURLVerification(c *gin.Context) bool -} -``` - -| 方法 | 职责 | -|------|------| -| `Platform()` | 返回平台标识,用于路由和注册 | -| `VerifyCallback()` | 验证回调请求的签名/Token | -| `ParseCallback()` | 解密并解析回调为 `IncomingMessage`,非消息事件返回 `nil` | -| `SendReply()` | 通过平台 API 发送完整回复 | -| `HandleURLVerification()` | 处理平台初始 URL 验证(首次配置时调用) | - -### im.StreamSender — 流式推送 (可选) - -```go -type StreamSender interface { - StartStream(ctx context.Context, incoming *IncomingMessage) (streamID string, err error) - UpdateStreamContent(ctx context.Context, incoming *IncomingMessage, streamID string, fullContent string) error - FinalizeStream(ctx context.Context, incoming *IncomingMessage, streamID string, finalContent string) error - EndStream(ctx context.Context, incoming *IncomingMessage, streamID string) error -} -``` - -- `UpdateStreamContent`:流式过程中用**当前可见全文**替换消息(replace 语义,非增量追加) -- `FinalizeStream`:结束前最后一次替换,通常为折叠思考/工具进度后的最终展示(多为纯答案) - -实现此接口后,Service 会自动路由到流式模式。渠道配置 `output_mode: "full"` 可强制关闭。 - -### im.FileDownloader — 文件下载 (可选) - -```go -type FileDownloader interface { - DownloadFile(ctx context.Context, msg *IncomingMessage) (io.ReadCloser, string, error) -} -``` - -实现此接口后,文件和图片可作为 QA 附件供模型理解。配置 `knowledge_base_id` 时,附件还会在后台保存到指定知识库;未配置时仅跳过保存。 - -### im.AdapterFactory — 适配器工厂 - -```go -type AdapterFactory func(ctx context.Context, channel *IMChannel, msgHandler func(*IncomingMessage)) (Adapter, CancelFunc, error) -``` - -每个平台注册一个工厂函数,Service 在启动渠道时调用工厂创建 Adapter 实例。工厂函数根据渠道的 `mode` 和 `credentials` 决定创建哪种 Adapter。 - ---- - -## 平台适配器详解 - -### 企业微信 (WeCom) - -提供两种连接模式,对应两套适配器实现: - -#### Webhook 模式 (`WebhookAdapter`) - -适用于**自建应用**,需要公网可访问的回调地址。 - -``` -企业微信服务器 ──HTTP POST──▶ /api/v1/im/callback/{channel_id} - │ - 解密 (AES-256-CBC) - 解析 XML → IncomingMessage - │ - 处理完成后调用 WeCom REST API 回复 -``` - -- **加密方案:** AES-256-CBC,Key 由 `encoding_aes_key` Base64 解码得到(32 字节),IV 为 Key 前 16 字节 -- **消息格式:** `random(16) + msg_len(4) + message + corp_id`,PKCS#7 填充 -- **签名验证:** SHA-1(`sort([token, timestamp, nonce, encrypt])`),常量时间比较 -- **消息类型:** 支持 `text`(文本)和 `image`(图片,PicUrl 直接下载或 MediaId 临时素材 API) -- **群聊回复:** 优先尝试 `appchat/send` 群聊 API,失败时降级到私聊直发 -- **回复方式:** 通过 `/cgi-bin/message/send` 接口发送 Markdown 消息 - -#### WebSocket 模式 (`WSAdapter` + `LongConnClient`) - -适用于**智能客服机器人**,无需公网域名,由客户端主动建立 WebSocket 长连接。 - -``` -LongConnClient ══WebSocket══▶ wss://openws.work.weixin.qq.com - │ - 1. 发送 aibot_subscribe (bot_id + secret) - 2. 接收 aibot_msg_callback 消息帧 - 3. 通过 aibot_respond_msg 回复 - 4. 每 30s 心跳保活 (ping/pong) - 5. 断连自动重连 (指数退避 1s → 30s) -``` - -- **认证:** Bot ID + Bot Secret -- **消息类型:** `text`(文本)、`image`(图片)、`file`(文件)、`voice`(语音,服务端已转文本)、`mixed`(混合,文本 + 图片)、`event`(服务器事件) -- **文件解密:** 附件使用每消息独立 AES-256-CBC 密钥解密(IV 为密钥前 16 字节) -- **流式回复:** 通过 WebSocket 帧发送累积全文,`finish=true` 标记结束 -- **容错:** 指数退避重连(基础 1s,上限 30s),读超时 = 3 × 心跳间隔(90s) - -#### 源码文件 - -| 文件 | 职责 | -|------|------| -| `internal/im/wecom/webhook_adapter.go` | Webhook 模式:回调解密、签名验证、REST API 回复、群聊发送、Token 缓存、文件下载 | -| `internal/im/wecom/ws_adapter.go` | WebSocket 模式适配器壳,代理到 `LongConnClient` | -| `internal/im/wecom/longconn.go` | WebSocket 客户端:连接管理、心跳、帧协议、自动重连、多消息类型解析、文件解密 | - ---- - -### 飞书 (Feishu) 与 Lark - -统一适配器同时支持 Webhook 和 WebSocket 模式,且原生实现 `StreamSender` 和 `FileDownloader` 接口。 - -#### 双云共用一套适配器 - -飞书与 Lark 是同一产品部署在两朵隔离的云上,API 与事件结构完全一致,因此 `internal/im/feishu` -包同时服务两个平台,由 `Region` 决定具体连哪朵云: - -```go -// internal/im/feishu/region.go -type Region struct { - Platform im.Platform // "feishu" | "lark",写入 IncomingMessage - OpenBaseURL string // https://open.feishu.cn | https://open.larksuite.com - Label string // 日志前缀 [Feishu] / [Lark] - ThinkingText string // 流式卡片占位文案(中文 / 英文) - ImageFallbackLabel string // 图片上传失败时降级链接的文案 -} - -var ( - RegionFeishu = Region{Platform: im.PlatformFeishu, OpenBaseURL: "https://open.feishu.cn", ...} - RegionLark = Region{Platform: im.PlatformLark, OpenBaseURL: "https://open.larksuite.com", ...} -) -``` - -容器中注册为两个平台: - -```go -// internal/container/container.go -imService.RegisterAdapterFactory("feishu", feishu.NewFactory(feishu.RegionFeishu)) -imService.RegisterAdapterFactory("lark", feishu.NewFactory(feishu.RegionLark)) -``` - -适配器所有 API 调用经 `a.api(path, args...)` 拼接 `region.OpenBaseURL`;WebSocket 模式通过 -`larkws.WithDomain(region.OpenBaseURL)` 指向对应云(SDK 默认连 open.feishu.cn,Lark 不指定会认证失败)。 - -> **跨云资源不通用**:`tenant_access_token`、`image_key`、`file_key`、`card_id` 均由单朵云的 -> 单个应用签发,跨云或跨应用使用会被拒绝。图片上传缓存因此以 `app_id` 为前缀分区。 - -#### IM 适配器实际调用的接口与所需权限 - -下表说明适配器**实际**依赖哪些权限。表中的权限标识已对照 Lark 官方 API 文档逐条核对, -飞书侧同名。 - -> **两朵云的权限清单并不等价。** API 与事件结构一致,不代表权限目录一致——飞书开放平台 -> 上存在的部分权限,Lark 开放平台并没有。因此各自的配置清单请分别参照 -> [飞书接入](#飞书接入)与 [Lark 权限配置](#lark-权限配置),不要跨云复制粘贴。 -> -> 飞书一节的 JSON 还同时覆盖了**飞书数据源连接器**(Wiki 同步),所以包含 -> `wiki:wiki:readonly`、`docs:document.content:read`、`sheets:spreadsheet` 等 IM 用不到的权限。 - -| 适配器调用 | 用途 | 所需权限(满足其一即可) | -|---|---|---| -| `POST /auth/v3/tenant_access_token/internal` | 换取 tenant access token | 无需权限(凭 App ID / Secret) | -| `POST /im/v1/messages/{id}/reply` | 回复消息(主路径) | `im:message`、`im:message:send_as_bot` 或 `im:message:send` | -| `POST /im/v1/messages` | 发送消息(回复失败时降级) | 同上 | -| `GET /im/v1/messages/{id}/resources/{key}` | 下载用户发来的文件 / 图片 | `im:message` 或 `im:message:readonly` | -| `POST /im/v1/images` | 上传图片以取得 `image_key` | `im:resource` 或 `im:resource:upload` | -| `POST /cardkit/v1/cards`
`PUT /cardkit/v1/cards/{id}/elements/{eid}/content`
`PATCH /cardkit/v1/cards/{id}/settings` | 流式卡片(仅流式输出模式需要) | `cardkit:card:write` | -| 订阅事件 `im.message.receive_v1`(单聊) | 接收私聊消息 | `im:message.p2p_msg` 或 `im:message.p2p_msg:readonly` | -| 订阅事件 `im.message.receive_v1`(群聊 @) | 接收群内 @机器人 消息 | `im:message.group_at_msg` 或 `im:message.group_at_msg:readonly` | - -因此 IM 功能全开(私聊 + 群聊 @ + 文件 + 图片 + 流式卡片)最少需要 5 类权限:收私聊、收群 @、 -发消息、读写资源、写卡片。若关闭流式输出(输出模式选「完整输出」),`cardkit:card:write` 可省略。 - -#### Webhook 模式 - -``` -飞书服务器 ──HTTP POST──▶ /api/v1/im/callback/{channel_id} - │ - 解密 (AES-256-CBC,可选) - 解析 JSON → IncomingMessage - │ - 通过飞书 Open API 回复 -``` - -- **加密方案:** AES-256-CBC,Key 为 `SHA-256(encrypt_key)`,IV 为密文前 16 字节 -- **事件过滤:** 仅处理 `im.message.receive_v1` 事件,忽略其他事件类型 -- **消息类型:** `text`(文本)、`file`(文件)、`image`(图片)、`post`(富文本,提取标题 + 结构化内容) -- **群消息处理:** 自动去除 `@_user_xxx` 提及前缀 - -#### WebSocket 模式 - -通过飞书官方 SDK (`github.com/larksuite/oapi-sdk-go`) 建立长连接,事件推送与 Webhook 等价,无需公网域名,内置自动重连。 - -#### 流式回复 (CardKit v1) - -飞书的流式输出基于 **CardKit 卡片流式更新**,是官方推荐的最佳实践: - -``` -StartStream: - 1. POST /cardkit/v1/cards → 创建卡片实体 (streaming_mode: true) - 2. POST /im/v1/messages → 发送卡片消息到聊天 - -UpdateStreamContent: - 3. PUT /cardkit/v1/cards/{id}/elements/{eid}/content → 更新元素内容 (累积全文) - -FinalizeStream: - 4. PUT /cardkit/v1/cards/{id}/elements/{eid}/content → 最终可见内容(通常为纯答案) - -EndStream: - 5. PATCH /cardkit/v1/cards/{id}/settings → 设置 streaming_mode: false -``` - -每次 `UpdateStreamContent` / `FinalizeStream` 发送的是**累积全文**而非增量,由 `feishuStreamState` 跟踪完整内容和严格递增的 `sequence` 序号。 - -**Think 块处理:** 流式输出中的 `...` 块会被转换为飞书 Markdown 引用块格式: - -``` -> 💭 **思考过程** -> [thinking content line 1] -> [thinking content line 2] -``` - -> **已知限制**:`Region.ThinkingText` 只本地化了卡片的初始占位文案(Lark 显示 `Thinking...`)。 -> 一旦开始流式输出,think 块标题来自共享的 `MarkdownThinkStyle`,目前对所有平台 -> (Lark、Slack、Telegram、Mattermost 等)都是中文。本地化它需要把 locale 贯穿到 -> `FormatIMDisplayContent`,属于跨平台改动,不在 Lark 接入范围内。 - -**孤立流清理:** 后台协程每 1 分钟扫描超过 5 分钟未关闭的流式卡片,自动调用 `EndStream` 关闭(防止内存泄漏)。 - -#### 源码文件 - -| 文件 | 职责 | -|------|------| -| `internal/im/feishu/region.go` | `Region` 定义(飞书 / Lark 的域名、平台标识、日志前缀、本地化文案) | -| `internal/im/feishu/adapter.go` | 事件解析、CardKit 流式实现、Token 缓存、AES 解密、Think 块转换、文件下载 | -| `internal/im/feishu/longconn.go` | WebSocket 长连接(封装飞书 SDK)、事件分发 | -| `internal/im/feishu/factory.go` | 按 `Region` 构造适配器与长连接客户端 | - ---- - -### Slack - -统一适配器同时支持 Webhook 和 WebSocket (Socket Mode) 模式,且原生实现 `StreamSender` 接口。 - -#### Webhook 模式 (Events API) - -``` -Slack 服务器 ──HTTP POST──▶ /api/v1/im/callback/{channel_id} - │ - 签名验证 (HMAC-SHA256) - 解析 JSON → IncomingMessage - │ - 通过 Slack Web API 回复 -``` - -- **签名验证:** 使用 `signing_secret` 对请求体进行 HMAC-SHA256 签名验证,防止伪造请求。 -- **事件过滤:** 仅处理 `message` 和 `app_mention` 事件,忽略机器人自己发送的消息。 -- **URL 验证:** 自动处理 Slack 的 `url_verification` challenge 请求。 - -#### WebSocket 模式 (Socket Mode) - -通过 `slack-go/slack/socketmode` 建立长连接,事件推送与 Webhook 等价,无需公网域名,内置自动重连。 - -``` -LongConnClient ══WebSocket══▶ wss://wss-primary.slack.com - │ - 1. 使用 App Token 建立连接 - 2. 接收 Events API 消息帧 - 3. 确认消息 (Ack) - 4. 通过 Slack Web API 回复 -``` - -#### 流式回复 - -Slack 的流式输出基于消息更新 (chat.update) 实现: - -``` -StartStream: - 1. POST /chat.postMessage → 发送初始消息,获取 ts (timestamp) - -UpdateStreamContent: - 2. POST /chat.update → 根据 ts 更新消息内容 (累积全文) - -FinalizeStream: - 3. POST /chat.update → 最终可见内容替换 - -EndStream: - 4. 无需特殊操作 -``` - -每次 `UpdateStreamContent` / `FinalizeStream` 发送的是**累积全文**而非增量。 - -#### 源码文件 - -| 文件 | 职责 | -|------|------| -| `internal/im/slack/adapter.go` | 事件解析、签名验证、流式实现、文件下载 | -| `internal/im/slack/longconn.go` | WebSocket 长连接(封装 slack-go Socket Mode) | - ---- - -### Telegram - -统一适配器同时支持 Webhook 和长轮询模式,原生实现 `StreamSender` 和 `FileDownloader` 接口。 - -#### Webhook 模式 - -``` -Telegram 服务器 ──HTTP POST──▶ /api/v1/im/callback/{channel_id} - │ - Secret Token 验证(可选) - 解析 JSON → IncomingMessage - │ - 通过 Telegram Bot API 回复 -``` - -- **签名验证:** 通过 `X-Telegram-Bot-Api-Secret-Token` 请求头与配置的 `secret_token` 进行常量时间比较 -- **消息类型:** `text`(文本)、`document`(文件,通过 file_id 下载)、`photo`(图片,自动选择最大尺寸) -- **群消息处理:** 自动去除 `@bot` 提及前缀 - -#### 长轮询模式 (Long Polling) - -Telegram 的 WebSocket 模式实际使用长轮询(Long Polling)而非真正的 WebSocket,通过持续调用 `getUpdates` API 获取新消息。 - -``` -LongConnClient ──HTTP POST──▶ https://api.telegram.org/bot/getUpdates - │ - 1. 发送 getUpdates (timeout=30s,长轮询) - 2. 解析返回的 Update 列表 - 3. 更新 offset 以确认已处理 - 4. 循环继续 - 5. 错误时退避 3 秒重试 -``` - -- **超时设置:** HTTP 客户端 35s,长轮询 timeout 30s -- **消息确认:** 通过 `offset` 参数自动确认已处理的消息 - -#### 流式回复 - -Telegram 的流式输出基于消息编辑 (editMessageText) 实现: - -``` -StartStream: - 1. POST sendMessage → 发送初始 "正在思考..." 消息,获取 message_id - -UpdateStreamContent: - 2. POST editMessageText → 根据 message_id 更新消息内容(累积全文,纯文本) - -FinalizeStream: - 3. POST editMessageText → 最终可见内容替换(与流式阶段相同,纯文本) - -EndStream: - 4. 清理流状态 -``` - -每次 `UpdateStreamContent` / `FinalizeStream` 发送的是**累积全文**而非增量,最小编辑间隔 500ms(避免触发 Telegram 速率限制)。中间态与终态均使用纯文本,避免 Markdown 解析失败。 - -**Think 块处理:** 流式输出中的 `...` 块会被转换为 Telegram 引用块格式: - -``` -> 💭 *思考过程* -> [thinking content line 1] -> [thinking content line 2] -``` - -**孤立流清理:** 后台协程每 1 分钟扫描超过 5 分钟未关闭的流式消息,自动清理(防止内存泄漏)。 - -#### 文件下载 - -Telegram 支持文件和图片消息的下载,流程: -1. 调用 `getFile` API 获取文件路径 -2. 通过 `https://api.telegram.org/file/bot/` 下载文件 - -#### 源码文件 - -| 文件 | 职责 | -|------|------| -| `internal/im/telegram/adapter.go` | 事件解析、Secret Token 验证、流式实现(editMessage)、文件下载 | -| `internal/im/telegram/longconn.go` | 长轮询客户端:getUpdates 循环、offset 管理、错误退避 | - ---- - -### 钉钉 (DingTalk) - -统一适配器同时支持 Webhook 和 Stream 模式,原生实现 `StreamSender` 接口。支持可选的 AI 卡片流式输出。 - -#### Webhook 模式 - -``` -钉钉服务器 ──HTTP POST──▶ /api/v1/im/callback/{channel_id} - │ - HmacSHA256 签名验证 - 解析 JSON → IncomingMessage - │ - 通过 sessionWebhook 或 OpenAPI 回复 -``` - -- **签名验证:** 使用 `client_secret` 对 `timestamp + "\n" + secret` 进行 HmacSHA256 签名,Base64 编码后与请求头 `Sign` 比较,时间戳 1 小时内有效 -- **回复方式:** 优先使用回调消息体中的 `sessionWebhook` 回复(适用于群聊场景),失败或不可用时降级到 OpenAPI - - 群聊:`/v1.0/robot/groupMessages/send` - - 私聊:`/v1.0/robot/oToMessages/batchSend` -- **消息格式:** Markdown 格式(`sampleMarkdown`) -- **认证:** 通过 `/v1.0/oauth2/accessToken` 获取 Access Token,带缓存(提前 5 分钟刷新) - -#### Stream 模式 (WebSocket) - -通过钉钉官方 SDK (`github.com/open-dingtalk/dingtalk-stream-sdk-go`) 建立 Stream 连接,事件推送与 Webhook 等价,无需公网域名,内置自动重连。 - -``` -LongConnClient ══Stream══▶ 钉钉 Stream 服务 - │ - 1. 使用 ClientID + ClientSecret 建立连接 - 2. 注册 ChatBot 回调处理 - 3. 接收消息事件 - 4. SDK 内置重连和心跳 -``` - -#### 流式回复 (AI 卡片) - -钉钉的流式输出基于 **AI 互动卡片** 实现(需配置 `card_template_id`): - -``` -StartStream: - 1. POST /v1.0/card/instances/createAndDeliver → 创建并投递 AI 卡片 - -UpdateStreamContent: - 2. PUT /v1.0/card/streaming → 流式更新卡片内容(累积全文) - -FinalizeStream: - 3. PUT /v1.0/card/streaming → 最终可见内容替换 - -EndStream: - 4. PUT /v1.0/card/streaming (isFinalize=true) → 标记流式结束 -``` - -每次 `UpdateStreamContent` / `FinalizeStream` 发送的是**累积全文**(`isFull: true`),最小更新间隔 500ms。 - -**无卡片模板时的降级策略:** 未配置 `card_template_id` 时,流式内容在内存中累积,`EndStream` 时一次性通过 `sessionWebhook` 或 OpenAPI 发送完整回复。 - -**Think 块处理:** 使用与飞书相同的 Markdown 引用块格式(`MarkdownThinkStyle`): - -``` -> 💭 **思考过程** -> [thinking content line 1] -> [thinking content line 2] -``` - -**孤立流清理:** 后台协程每 1 分钟扫描超过 5 分钟未关闭的流,自动清理防止内存泄漏。 - -#### 源码文件 - -| 文件 | 职责 | -|------|------| -| `internal/im/dingtalk/adapter.go` | 事件解析、HmacSHA256 签名验证、AI 卡片流式实现、Access Token 缓存、OpenAPI 调用 | -| `internal/im/dingtalk/longconn.go` | Stream 客户端(封装钉钉 SDK)、ChatBot 消息分发 | - ---- - -### Mattermost - -仅支持 **Webhook** 模式:Mattermost **Outgoing Webhook** 将请求体 POST 到 WeKnora 统一回调地址;适配器实现 `Adapter`、`StreamSender`、`FileDownloader`(标准库 HTTP 调用 REST API,无第三方 SDK)。 - -#### Webhook 模式(Outgoing Webhook) - -``` -Mattermost 服务器 ──HTTP POST──▶ /api/v1/im/callback/{channel_id} - │ - 校验 body 中 token = outgoing_token - 解析 JSON 或 x-www-form-urlencoded - │ - 通过 REST API v4 回复(Bearer Bot Token) -``` - -- **安全校验:** 请求体中的 `token` 必须与渠道凭证中的 `outgoing_token` 一致(创建渠道时工厂会校验 `outgoing_token` 非空)。 -- **载荷格式:** 支持 `application/json` 与 `application/x-www-form-urlencoded`(与 [官方文档](https://developers.mattermost.com/integrate/webhooks/outgoing/) 一致)。 -- **机器人过滤:** 若配置了 `bot_user_id`,且 `user_id` 与之相同,则返回 `nil` 消息,避免自激。 -- **线程回复:** `IncomingMessage.Extra` 中保存 `thread_root_id`(有 `root_id` 时用其值,否则用触发帖 `post_id`);`SendReply` / `CreatePost` 时设置 `root_id`,使回复出现在同一线程。 -- **消息去重:** `MessageID` 使用触发帖的 `post_id`。 -- **文件消息:** 若载荷含 `file_ids`,取首个文件 ID 作为 `FileKey`;`DownloadFile` 先 `GET /api/v4/files/{id}/info` 再 `GET /api/v4/files/{id}` 下载内容。 - -#### 流式回复 - -与 Slack 类似,通过**编辑同一条帖子**展示累积全文: - -``` -StartStream: - 1. POST /api/v4/posts → 创建占位帖(如「正在思考...」),得到 post id - -UpdateStreamContent: - 2. PUT /api/v4/posts/{post_id}/patch → Patch message 字段(累积全文) - -FinalizeStream: - 3. PUT /api/v4/posts/{post_id}/patch → 最终可见内容替换 - -EndStream: - 4. 清理流状态 -``` - -流式刷新间隔由 Service 侧 `streamFlushInterval`(300ms)批量合并,以降低编辑频率、减轻 API 压力。 - -#### URL 验证 - -Mattermost 出站 Webhook 无 Slack/Feishu 类 challenge 流程,`HandleURLVerification` 恒为 `false`。 - -#### 源码文件 - -| 文件 | 职责 | -|------|------| -| `internal/im/mattermost/adapter.go` | 出站 Webhook 解析、Token 校验、发帖/补丁流式、文件下载 | -| `internal/im/mattermost/client.go` | REST v4:`CreatePost`、`PatchPostMessage`、文件 info/下载 | -| `internal/im/mattermost/form_parse.go` | 表单编码 body 与 `file_ids` 辅助解析 | - ---- - -## 斜杠指令系统 - -IM 渠道支持斜杠指令(Slash Commands),用户在聊天中输入 `/指令名` 即可触发,无需经过 QA 管道,且不受限流约束。 - -### 内置指令 - -| 指令 | 参数 | 说明 | -|------|------|------| -| `/help` | `[指令名]` | 显示所有可用指令列表;带参数时显示指定指令的详细用法 | -| `/info` | — | 查看当前绑定智能体的名称、角色设定、知识库列表等信息 | -| `/search` | `<关键词>` | 对绑定的知识库执行混合检索(向量 + 关键词),返回最多 5 条原文片段,不经过 AI 总结 | -| `/stop` | — | 取消当前排队中或正在执行的 QA 请求 | -| `/clear` | — | 清空当前对话记忆(软删除 ChannelSession),下次消息开始全新会话 | - -### 指令分发流程 - -``` -用户消息 ──▶ HandleMessage - │ - ├─ 以 "/" 开头? - │ │ - │ ├─ 已注册指令 → CommandRegistry.Parse → Command.Execute → 回复结果 - │ │ │ - │ │ ActionClear → 软删除 ChannelSession - │ │ ActionStop → 取消排队/执行中的 QA - │ │ - │ └─ LooksLikeCommand() = true 但未注册 - │ → 回复 "未知指令,发送 /help 查看" - │ LooksLikeCommand() = false (如 "/api/v2/users") - │ → 当作普通消息,进入 QA 管道 - │ - └─ 普通消息 → 限流检查 → qaQueue → QA 管道 -``` - -> `LooksLikeCommand()` 通过检查首 token 是否含有 `/` 分隔符来区分指令尝试和 URL 路径,避免误拦截。 - -### 扩展自定义指令 - -实现 `im.Command` 接口并在 Service 初始化时注册到 `CommandRegistry`: - -```go -type Command interface { - Name() string // 指令名 (不含 "/") - Description() string // 一行描述,用于 /help 输出 - Execute(ctx context.Context, cmdCtx *CommandContext, args []string) (*CommandResult, error) -} -``` - -**设计约定:** -- 依赖(DB、Service)通过构造函数注入,不放在 `CommandContext` 中 -- 用户输入错误通过 `CommandResult` 返回友好提示,`error` 仅用于基础设施故障(DB 异常、网络错误等) -- 通过 `CommandResult.Action` 声明副作用意图(如清空会话),由 Service 执行 -- 重复注册同名指令会在启动时 panic,确保配置错误尽早暴露 - -### 源码文件 - -| 文件 | 职责 | -|------|------| -| `internal/im/command.go` | Command 接口、CommandAction、CommandContext 定义 | -| `internal/im/command_registry.go` | CommandRegistry:指令注册、解析、分发、LooksLikeCommand | -| `internal/im/cmd_help.go` | `/help` 指令实现 | -| `internal/im/cmd_info.go` | `/info` 指令实现(展示 Agent 信息、知识库列表) | -| `internal/im/cmd_search.go` | `/search` 指令实现(混合检索,最多 5 条,内容截断 200 rune) | -| `internal/im/cmd_stop.go` | `/stop` 指令实现 | -| `internal/im/cmd_clear.go` | `/clear` 指令实现 | - ---- - -## QA 队列与限流 - -### QA 队列 (qaQueue) - -有界工作池队列管理 QA 请求,防止并发过载: - -``` -消息 ──▶ Enqueue ──▶ [ 等待队列 (≤50) ] ──▶ Worker Pool (5 workers) ──▶ QA 管道 - │ │ - ├─ 队列已满 → 拒绝并回复提示 │ - ├─ 用户排队超限 (≤3) → 拒绝 ├─ 等待超时 (>60s) → 丢弃并通知 - └─ /stop → Remove(userKey) 取消 └─ 正常执行 QA -``` - -**设计要点:** - -- **有界队列**:最大容量 50,防止内存无限增长 -- **Per-User 背压**:单用户最多同时排队 3 个请求,避免单用户刷屏占满队列 -- **排队等待提示**:入队成功且队列非空时,回复 "前面还有 N 条消息在处理,请稍候" -- **排队超时**:请求在队列中等待超过 60 秒自动丢弃,回复超时提示 -- **可取消**:`/stop` 指令通过 `qaQueue.Remove(userKey)` 取消排队请求,通过 `inflight` map 中的 `context.CancelFunc` 取消执行中请求 -- **指标监控**:每 30 秒输出队列深度、活跃 Worker 数、入队/处理/拒绝/超时计数(仅在有活动时输出) - -### 滑动窗口限流 (rateLimiter) - -在消息进入 QA 队列之前,按 `channelID:userID:chatID` 维度进行滑动窗口限流: - -| 参数 | 值 | 说明 | -|------|------|------| -| 窗口大小 | 60s | 滑动时间窗口 | -| 最大请求数 | 10 次/窗口 | 每个用户每分钟最多 10 条消息进入 QA | -| 清理周期 | 1 min | 自动清理过期条目,防止内存泄漏 | - -超出限流时回复提示消息,不计入队列。斜杠指令不受限流约束。 - -### 源码文件 - -| 文件 | 职责 | -|------|------| -| `internal/im/qaqueue.go` | qaQueue:有界队列、Worker Pool、QueueMetrics、指标上报 | -| `internal/im/ratelimit.go` | slidingWindowLimiter:per-key 滑动窗口限流、并发安全清理 | - ---- - -## 流式输出机制 - -流式模式通过 `EventBus` 实时收集 QA 管道产生的内容块,以 **300ms 间隔批量推送**,在延迟与 API 限频之间取得平衡: - -``` -QA 管道 ──chunk──chunk──chunk──▶ EventBus - │ - 每 300ms 刷新 - │ - ┌───────────▼───────────┐ - │ 累积内容 → 完整替换推送 │ - │ (非增量,每次发送全文) │ - └───────────────────────┘ -``` - -### 内容处理 - -- **Think 块过滤/转换**:`...` 块在飞书和钉钉中转换为 Markdown 引用块展示,在 Telegram 中转换为引用块(斜体标题),在其他平台中过滤 -- **工具事件展示**:Agent 工具调用实时展示调用状态 - - 调用中:`⏳ [工具名]`(包裹在 think 块内) - - 调用成功:`✅ [工具名] · [摘要]` - - 调用失败:`⚠️ [工具名] 失败` - - 内部工具(thinking、todo_write 等)不展示给用户 -- **空内容回退**:流式过程中无可见内容产生时,回退到完整回复模式 (`fallbackNonStream`) -- **完整持久化**:完整内容(含 thinking)持久化到数据库,确保历史完整 - -### 平台流式特殊处理 - -- **"正在思考..." 占位**:飞书和 Telegram 在流式初始化后立即显示占位文本,提升用户感知 -- **孤立流清理**:飞书、Telegram、钉钉的后台协程每 `streamReaperInterval`(1 分钟)扫描超过 `streamOrphanTTL`(5 分钟)未关闭的流,自动关闭防止内存泄漏 -- **Think 块转换**:飞书和钉钉将 `` 标签转换为 Markdown 引用块(`> 💭 **思考过程**`),Telegram 使用斜体标题(`> 💭 *思考过程*`) - ---- - -## 文件消息处理 - -文件和图片会作为 QA 附件供模型理解,用户只收到该消息对应的 QA 回复。`knowledge_base_id` 配置后会额外触发后台入库;未配置时不入库、不报错。入库结果和后续解析不再产生额外 IM 通知。解析出的附件文本最多保留前 500 行且不超过 32 KiB;发生任一限制时,模型会收到通用的截断提示。 - -**各平台文件下载方式:** - -| 平台 | 方式 | -|------|------| -| 飞书 | GetMessageResource API(通过 FileKey) | -| 企业微信 Webhook | PicUrl 直接下载 或 MediaId 临时素材 API | -| 企业微信 WebSocket | 加密附件 URL + per-message AES 密钥解密 | -| Telegram | getFile API 获取文件路径 + HTTPS 下载(支持文档和图片) | -| Mattermost | `GET /api/v4/files/{file_id}/info` + `GET /api/v4/files/{file_id}`(Bearer Bot Token) | - ---- - -## 关键参数与阈值 - -| 参数 | 值 | 说明 | -|------|------|------| -| `qaTimeout` | 120s | QA 管道最大执行时间 | -| `dedupTTL` | 5 min | 消息去重 ID 保留时长 | -| `dedupCleanupInterval` | 1 min | 去重清理周期 | -| `maxContentLength` | 4096 | 消息最大长度 (rune),超出截断 | -| `streamFlushInterval` | 300ms | 流式内容批量刷新间隔 | -| `defaultMaxQueueSize` | 50 | QA 队列最大容量 | -| `defaultMaxPerUser` | 3 | 单用户最大排队请求数 | -| `defaultWorkers` | 5 | QA 并发 Worker 数 | -| `queueTimeout` | 60s | 请求在队列中的最大等待时间 | -| `rateLimitWindow` | 60s | 限流滑动窗口大小 | -| `rateLimitMaxRequests` | 10 | 每用户每窗口最大请求数 | -| `metricsLogInterval` | 30s | 队列指标日志上报周期 | -| `streamOrphanTTL` | 5 min | 飞书/Telegram/钉钉 孤立流超时时间 | -| `streamReaperInterval` | 1 min | 飞书/Telegram/钉钉 孤立流清理扫描周期 | -| Telegram 编辑间隔 | 500ms | editMessageText 最小调用间隔(避免速率限制)| -| Telegram 长轮询超时 | 30s | getUpdates timeout 参数 | -| Telegram 错误退避 | 3s | getUpdates 失败后等待时间 | -| DingTalk 卡片更新间隔 | 500ms | AI 卡片流式更新最小间隔 | -| DingTalk 签名有效期 | 1h | Webhook 回调签名时间戳有效窗口 | -| WeCom WS 心跳 | 30s | WebSocket 保活频率 | -| WeCom WS 读超时 | 90s | 3 × 心跳间隔,允许一次心跳丢失 | -| WeCom WS 重连退避 | 1s → 30s | 指数退避,上限 30 秒 | -| Token 缓存安全余量 | 5 min | Token 过期前提前刷新 | - ---- - -## 错误处理 - -| 场景 | 处理策略 | -|------|---------| -| 流式初始化失败 | 自动降级到全量模式 (`fallbackNonStream`) | -| QA 管道异常 | 回复 "抱歉,处理您的问题时出现了异常,请稍后再试。" | -| QA 超时 (>120s) | 标记消息完成,回复超时提示 | -| 空回答 | 回复 "抱歉,我暂时无法回答这个问题。" | -| 空流式内容 | 无可见内容时回退到完整回复 | -| WebSocket 断连 | 指数退避自动重连 | -| 平台重试 | MessageID 去重,5 分钟内自动跳过 | -| 渠道启动失败 | 日志记录错误,不影响其他渠道 | -| QA 队列已满 | 拒绝请求并回复 "当前排队人数较多,请稍后再试。" | -| 用户排队超限 | 拒绝请求并回复提示(单用户 ≤3) | -| 排队等待超时 | 超过 60s 自动丢弃,回复 "您的消息等待超时,请重新发送。" | -| 消息限流 | 滑动窗口内超过 10 次,回复限流提示 | -| 飞书孤立流 | 每分钟扫描,超过 5 分钟未关闭的自动结束 | -| Telegram/钉钉孤立流 | 同飞书,每分钟扫描并自动清理 | -| 企业微信群聊回复失败 | appchat API 失败时降级到用户私聊 | -| 钉钉 AI 卡片创建失败 | 降级到 sessionWebhook 或 OpenAPI 回复 | -| 钉钉 sessionWebhook 不可用 | 降级到 OpenAPI(群聊/私聊分别调用不同端点) | - ---- - -## 扩展新平台 - -接入新的 IM 平台只需 3 步: - -### 1. 实现 `im.Adapter` 接口 - -在 `internal/im//` 下创建适配器: - -```go -package myplatform - -type Adapter struct { /* 平台配置 */ } - -func (a *Adapter) Platform() im.Platform { return "myplatform" } -func (a *Adapter) VerifyCallback(c *gin.Context) error { /* 签名验证 */ } -func (a *Adapter) ParseCallback(c *gin.Context) (*im.IncomingMessage, error) { /* 解析消息 */ } -func (a *Adapter) SendReply(ctx context.Context, incoming *im.IncomingMessage, reply *im.ReplyMessage) error { /* 发送回复 */ } -func (a *Adapter) HandleURLVerification(c *gin.Context) bool { /* URL 验证 */ } -``` - -可选接口: -- 实现 `im.StreamSender` 以支持流式输出 -- 实现 `im.FileDownloader` 以支持文件消息自动保存到知识库 - -> 可参考已有的 Telegram(纯 HTTP API)和 DingTalk(SDK + AI 卡片)适配器作为实现参考。 - -### 2. 注册适配器工厂 - -在 `internal/container/container.go` 的 `registerIMAdapterFactories` 中注册工厂函数: - -```go -imService.RegisterAdapterFactory("myplatform", func(ctx context.Context, channel *im.IMChannel, msgHandler func(*im.IncomingMessage)) (im.Adapter, im.CancelFunc, error) { - creds := parseCredentials(channel.Credentials) - appKey := getString(creds, "app_key") - appSecret := getString(creds, "app_secret") - - adapter := myplatform.NewAdapter(appKey, appSecret) - - // WebSocket 模式需要启动长连接 - if channel.Mode == "websocket" { - cancelCtx, cancel := context.WithCancel(ctx) - go adapter.StartLongConn(cancelCtx, msgHandler) - return adapter, func() { cancel() }, nil - } - - return adapter, func() {}, nil -}) -``` - -### 3. 前端添加平台选项 - -在 `IMChannelPanel.vue` 中: -- 添加平台 radio 选项 -- 添加该平台的凭证表单字段 - -在 i18n 文件中添加平台名称翻译。 - -Service 层 (`im.Service`) 不需要任何修改 — 渠道管理、指令分发、消息编排、会话管理、QA 调度、限流、流式控制全部由 Service 统一处理。 diff --git a/docs/KnowledgeGraph.md b/docs/KnowledgeGraph.md deleted file mode 100644 index 1eb9e194..00000000 --- a/docs/KnowledgeGraph.md +++ /dev/null @@ -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)` 即可查看生成的知识图谱。 - -在对话时,系统会自动查询知识图谱,并获取相关知识。 diff --git a/docs/Langfuse集成.md b/docs/Langfuse集成.md deleted file mode 100644 index 5e9c280b..00000000 --- a/docs/Langfuse集成.md +++ /dev/null @@ -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.`)聚合。 -- **完全可选**:不配置 `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.` 的 SPAN,并记录 `task_id` / `queue` / `retry` / `payload_bytes`。定时任务(无上游 trace)会退化为 `asynq.` 独立 trace。**Agent 相关**:`AgentEngine.Execute` 会开 `agent.execute` 顶层 SPAN,其下每一轮 ReAct 循环开 `agent.round.N` SPAN,每次工具调用开 `agent.tool.` 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:`,方便按空间汇总消耗;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.` 每轮 SPAN。 -- `internal/agent/act.go` — `agent.tool.` 工具调用 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_*` 环境变量直通。 diff --git a/docs/MCP功能使用说明.md b/docs/MCP功能使用说明.md deleted file mode 100644 index 82155f72..00000000 --- a/docs/MCP功能使用说明.md +++ /dev/null @@ -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 中断 \ No newline at end of file diff --git a/docs/OIDC认证调用流程.md b/docs/OIDC认证调用流程.md deleted file mode 100644 index 415a49fc..00000000 --- a/docs/OIDC认证调用流程.md +++ /dev/null @@ -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: -``` - -这说明本地调试时,需要确保 **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` diff --git a/docs/QA.md b/docs/QA.md deleted file mode 100644 index 7e770136..00000000 --- a/docs/QA.md +++ /dev/null @@ -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 --host --use`,再 `weknora auth login`;切换 profile 用全局 `--profile `。 -- **`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 ` 可中止进行中的 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://`,客户端需要再调用带鉴权的 `/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中描述您的问题,并提供必要的日志信息辅助我们进行问题排查 diff --git a/docs/RBAC说明.md b/docs/RBAC说明.md deleted file mode 100644 index 56fc77e5..00000000 --- a/docs/RBAC说明.md +++ /dev/null @@ -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=` 建立范围索引,而不是为每个知识库创建独立日志表。`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 的按钮,前端直接隐藏而不是让用户点了再吃错误。** - -### 前端实际界面 - - - - - - - - - - - - -
- 成员管理页
- 成员管理 -
同时展示「待接受的邀请」和「空间成员」两组列表;只有 Owner 可以新增 / 移除成员;右上角的「审计日志」入口跳转到 audit_logs 视图。 -
- 用户菜单 + 工作区切换器
- 用户菜单 + 切换空间 -
左侧:当前空间角色徽章 / 设置入口 / 退出;右侧:切换到其它空间,「当前」角标标识活跃工作区。 -
- 自助创建工作区
- 创建新空间 -
任何用户都可以自助创建空间,创建后自动成为新空间的 Owner(受 WEKNORA_TENANT_MAX_PER_USER 上限保护)。 -
- 待处理邀请弹窗
- 我的邀请 -
用户菜单上的邀请铃铛会展示来自其它空间的待处理邀请,可直接「接受 / 拒绝」;7 天未响应自动过期。 -
- -## 九、常见问题 - -### 升级后所有人都变成了 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) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..d66e6466 --- /dev/null +++ b/docs/README.md @@ -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 实验模块,保留源码和运行说明,不作为当前产品指南。 + +这些资源尚有编译、发布或历史实验用途,不能直接整目录删除。新的产品说明不要再放入此处。 diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md deleted file mode 100644 index 3a935ae4..00000000 --- a/docs/ROADMAP.md +++ /dev/null @@ -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 内容合集 diff --git a/docs/agent-prompt-assembly.md b/docs/agent-prompt-assembly.md deleted file mode 100644 index f79bfdee..00000000 --- a/docs/agent-prompt-assembly.md +++ /dev/null @@ -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`。不要把同一条规则复制到多个模板中来“加强优先级”。 diff --git a/docs/agent-skills.md b/docs/agent-skills.md deleted file mode 100644 index 2bccc3e0..00000000 --- a/docs/agent-skills.md +++ /dev/null @@ -1,555 +0,0 @@ -# Agent Skills 文档 - -## 概述 - -Agent Skills 是一种让 Agent 通过阅读"使用说明书"来学习新能力的扩展机制。与传统的硬编码工具不同,Skills 通过注入到 System Prompt 来扩展 Agent 的能力,遵循 **Progressive Disclosure(渐进式披露)** 的设计理念。 -目前仅支持带**智能推理**能力的智能体使用。前端可在智能体的编辑页面找到相关配置 - -已安装到沙箱镜像的技能统一通过 `shell_exec(skill_name=..., command=...)` 执行;`read_file(path="skill:///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//`;使用系统运行时及会话依赖目录,不复制宿主机的虚拟环境或 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 字符 diff --git a/docs/agent-tools-design.md b/docs/agent-tools-design.md deleted file mode 100644 index bd10bbe8..00000000 --- a/docs/agent-tools-design.md +++ /dev/null @@ -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" `,无需虚拟环境内已有 pip;Node 用 `npm --prefix "${WEKNORA_SKILL_DIR:?}" install `。`$WEKNORA_SKILL_DIR` 由本次调用注入,指向镜像内技能或宿主机来源技能的实际暂存目录。如果尚无 `.venv`,先用 `python3 -m venv --without-pip "${WEKNORA_SKILL_DIR:?}/.venv"` 创建;自定义镜像没有 uv 时,先用该虚拟环境的 Python 执行 `-m ensurepip --upgrade`,成功后再执行 `-m pip install `。随后仍带同一 `skill_name` 执行原命令。命令中的 `${WEKNORA_SKILL_DIR:?}` 会在变量缺失或为空时终止,避免误用根目录。真正的只读挂载仍需先配置可写的技能环境,root、uv 和 pip 都无法绕过挂载限制。 - -沙箱归本会话独占且以 root 运行,这类写入落在会话自己的容器里、随会话销毁,不会回流到其他会话启动用的镜像;因此不再需要 `/workspace` 下的包 overlay,技能的包也不会被拆到两个位置。Node 的 `NODE_PATH` 支持 CommonJS;自建 ESM 脚本应在可写项目目录安装依赖,或调用技能目录里的原始脚本,不能假定 NODE_PATH 支持 ESM。 - -文件工具继续保留写入预算、精确编辑校验、读取分页和二进制处理。Shell 输出保留原来的字节限额和截断策略;完整输出不自动保存,需要时显式重定向到工作区日志。产物仍由 `/workspace/output` 收集,以 `sandbox:` 引用。 - -`/workspace/input` 的文件工具写入限制保留;Shell 中“保留附件原件”仍是行为约定,不应解释为本次新增了文件系统只读挂载。 - -## 旧工具删除与执行统一 - -删除 `ReadSkillTool`、`ExecuteSkillScriptTool` 和独立 `ReadSandboxFileTool`;共享文件分页与工作区缓存迁入私有 `workspaceFileReader`,技能文件树为普通辅助函数。技能管理器中只服务旧工具的 ExecuteScript、执行配置构造及重复凭据处理也已移除。 - -`LegacyTool*` 常量和前端旧事件展示仅用于读取历史消息及忽略过期 allowlist,不提供运行时别名或回退执行。新会话没有隐藏的第二套读/执行 Tool。 - -Shell 的补齐能力: - -- `stdin` 可传入最多 65536 字节的文本,保留字面引号、Unicode 和尾部换行;更大的输入使用工作区文件重定向。 -- 宿主机技能按资源内容生成版本目录,复制到 `/workspace/.skills//`。脚本和二进制资源一起准备;单次准备上限 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 或重试率降幅。 diff --git a/docs/api/README.md b/docs/api/README.md deleted file mode 100644 index 6fbe7827..00000000 --- a/docs/api/README.md +++ /dev/null @@ -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://` 返回,例如问答答案中的 -`![示意图](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/` 提供。二者都不 - 可用时(例如 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) | diff --git a/docs/api/agent.md b/docs/api/agent.md deleted file mode 100644 index a41d46a3..00000000 --- a/docs/api/agent.md +++ /dev/null @@ -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) diff --git a/docs/api/auth.md b/docs/api/auth.md deleted file mode 100644 index a18a08db..00000000 --- a/docs/api/auth.md +++ /dev/null @@ -1,449 +0,0 @@ -# 认证管理 API - -[返回目录](./README.md) - -OIDC 完整调用流程见 [../OIDC认证调用流程.md](../OIDC认证调用流程.md)。本文档作为端点参考。 - -## 说明 - -WeKnora 的 `/auth/*` 端点本身**不需要 X-API-Key**,但部分端点需要在 `Authorization: Bearer ` 头中携带由 `/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=`,其中 payload 包含 `success` / `user` / `tenant` / `token` / `refresh_token` / `is_new_user`,与登录响应一致。 -- 失败:`/#oidc_error=[&oidc_error_description=]`,常见 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(`:///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` | 新密码与当前密码相同 | diff --git a/docs/api/chat.md b/docs/api/chat.md deleted file mode 100644 index b3bb8f56..00000000 --- a/docs/api/chat.md +++ /dev/null @@ -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} -``` diff --git a/docs/api/chunk.md b/docs/api/chunk.md deleted file mode 100644 index 460d35f1..00000000 --- a/docs/api/chunk.md +++ /dev/null @@ -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 -} -``` diff --git a/docs/api/evaluation.md b/docs/api/evaluation.md deleted file mode 100644 index c81aae79..00000000 --- a/docs/api/evaluation.md +++ /dev/null @@ -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": "\n\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": "\n\nNO_MATCH", - "temperature": 0.3, - "seed": 0, - "max_completion_tokens": 2048 - }, - "fallback_strategy": "", - "fallback_response": "抱歉,我无法回答这个问题。" - } - }, - "success": true -} -``` diff --git a/docs/api/faq.md b/docs/api/faq.md deleted file mode 100644 index ab8bf4f2..00000000 --- a/docs/api/faq.md +++ /dev/null @@ -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` 不会真正写入。 diff --git a/docs/api/initialization.md b/docs/api/initialization.md deleted file mode 100644 index b23fd3a0..00000000 --- a/docs/api/initialization.md +++ /dev/null @@ -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 -} -``` diff --git a/docs/api/knowledge-base.md b/docs/api/knowledge-base.md deleted file mode 100644 index 65f06a2e..00000000 --- a/docs/api/knowledge-base.md +++ /dev/null @@ -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 ' \ ---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 -} -``` diff --git a/docs/api/knowledge-search.md b/docs/api/knowledge-search.md deleted file mode 100644 index 96a3b9f2..00000000 --- a/docs/api/knowledge-search.md +++ /dev/null @@ -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`) | diff --git a/docs/api/knowledge.md b/docs/api/knowledge.md deleted file mode 100644 index ec095058..00000000 --- a/docs/api/knowledge.md +++ /dev/null @@ -1,1079 +0,0 @@ -# 知识管理 API - -[返回目录](./README.md) - -知识(Knowledge)是知识库下的一条可检索内容(来自文件、URL 或手工录入的 Markdown)。本文档涵盖知识的创建、查询、更新、删除、迁移与文件预览/下载等接口。 - -| 方法 | 路径 | 描述 | -| ------ | ------------------------------------------ | ------------------------------------------ | -| POST | `/knowledge-bases/:id/knowledge/file` | 上传文件创建知识(multipart) | -| POST | `/knowledge-bases/:id/knowledge/url` | 从 URL 创建知识(网页抓取或文件下载) | -| POST | `/knowledge-bases/:id/knowledge/manual` | 创建手工 Markdown 知识 | -| GET | `/knowledge-bases/:id/knowledge` | 列出知识库下的知识(支持分页/筛选) | -| GET | `/knowledge-bases/:id/knowledge/folders` | 获取知识库文件夹目录树 | -| PUT | `/knowledge-bases/:id/knowledge/folders` | 重命名或移动文件夹(含子目录) | -| DELETE | `/knowledge-bases/:id/knowledge` | 清空知识库下的所有知识(异步任务) | -| GET | `/knowledge/batch` | 按 ID 列表批量获取知识 | -| GET | `/knowledge/:id` | 获取知识详情 | -| PUT | `/knowledge/:id` | 更新知识(标题/描述/标签等) | -| DELETE | `/knowledge/:id` | 删除单条知识 | -| PUT | `/knowledge/manual/:id` | 更新手工 Markdown 知识 | -| POST | `/knowledge/:id/reparse` | 重新解析知识(异步) | -| POST | `/knowledge/:id/cancel-parse` | 取消正在进行的解析任务 | -| GET | `/knowledge/:id/download` | 下载原始文件(attachment) | -| POST | `/knowledge-bases/:id/knowledge/batch-download` | 将所选文档打包下载为 ZIP | -| GET | `/knowledge/:id/preview` | 内联预览文件(按扩展名设置 Content-Type) | -| PUT | `/knowledge/image/:id/:chunk_id` | 更新分块图像信息 | -| PUT | `/knowledge/tags` | 批量更新知识标签 | -| GET | `/knowledge/search` | 跨知识库搜索/过滤知识 | -| POST | `/knowledge/batch-reparse` | 同一知识库内批量重新解析知识(异步任务) | -| POST | `/knowledge/batch-delete` | 同一知识库内批量删除知识(异步任务) | -| POST | `/knowledge/folder` | 批量移动知识到指定文件夹(仅改归类) | -| POST | `/knowledge/move` | 迁移知识到另一知识库(异步任务) | -| GET | `/knowledge/move/progress/:task_id` | 查询知识迁移任务进度 | - -> **公共说明**: -> - 路径中的 `:id`(知识库路径下)为**知识库 ID**,`/knowledge/:id` 中的 `:id` 为**知识 ID**。 -> - 所有写操作(创建、更新、删除、迁移、重新解析、取消解析)需要当前用户在知识库所属组织内具有 `editor` 或 `admin` 权限;清空知识库内容仅 KB **所有者**(admin 且空间匹配)可操作。 -> - 关键状态字段:`parse_status` 取值 `pending` / `processing` / `finalizing` / `completed` / `failed` / `cancelled`;`enable_status` 取值 `enabled` / `disabled`。 -> - `processing` 指 DocReader / 分块 / 向量化阶段;`finalizing` 指主解析已完成、仍在执行摘要 / 问题生成 / 图谱抽取等索引优化任务;只有当全部子任务到达终态后才进入 `completed`。 -> - `cancelled` 表示解析被用户主动取消,可通过 `reparse` 重新触发。`pending` / `processing` / `finalizing` 这三种状态都可通过 `cancel-parse` 终止。 - -## POST `/knowledge-bases/:id/knowledge/file` - 上传文件创建知识 - -通过 `multipart/form-data` 上传文件创建知识条目。文件大小受 `MAX_FILE_SIZE_MB` 环境变量限制。 - -**路径参数**: - -| 字段 | 类型 | 说明 | -| ---- | ------ | --------- | -| id | string | 知识库 ID | - -**表单字段**: - -| 字段 | 类型 | 必填 | 说明 | -| ------------------- | ------- | ---- | -------------------------------------------------------------------- | -| `file` | file | 是 | 待上传的文件 | -| `fileName` | string | 否 | 自定义文件名,用于"文件夹上传"时保留相对路径(如 `docs/intro.md`) | -| `metadata` | string | 否 | JSON 字符串,会被反序列化为 `map[string]string` | -| `enable_multimodel` | string | 否 | `"true"` / `"false"`,是否启用图文多模态解析 | -| `process_config` | string | 否 | JSON 字符串,批次解析配置覆盖(`KnowledgeProcessOverrides`);写入 `knowledge.metadata.process_overrides`。未传时行为与现网一致 | -| `tag_id` | string | 否 | 标签 ID;传 `__untagged__` 或空字符串表示未分类 | -| `channel` | string | 否 | 来源渠道标识(写入 `channel` 字段,默认 `web`) | - -`process_config` 可选字段包括:`parser_engine_rules`、`chunking_config`、`enable_multimodel`、`vlm_config`、`asr_config`、`question_generation_config`、`graph_enabled`、`extract_config`。若同时传 `enable_multimodel` 与 `process_config.enable_multimodel`,以 `process_config` 为准。 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/knowledge/file' \ ---header 'X-API-Key: sk-xxxxx' \ ---form 'file=@"/Users/xxxx/tests/彗星.txt"' \ ---form 'enable_multimodel="true"' \ ---form 'tag_id="tag-00000001"' \ ---form 'metadata="{\"source\":\"manual_upload\"}"' -``` - -> 注意:使用 `-F`/`--form` 时 curl 会自动设置 `Content-Type: multipart/form-data; boundary=...`,不要再手动加 `--header 'Content-Type: application/json'`,否则请求体会被错误解析。 - -**响应**(创建成功,`parse_status=processing` 表示解析任务已入队): - -```json -{ - "data": { - "id": "4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "type": "file", - "title": "彗星.txt", - "description": "", - "source": "", - "channel": "web", - "tag_id": "tag-00000001", - "summary_status": "none", - "parse_status": "processing", - "enable_status": "disabled", - "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", - "file_name": "彗星.txt", - "file_type": "txt", - "file_size": 7710, - "file_hash": "d69476ddbba45223a5e97e786539952c", - "file_path": "data/files/1/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5/1754970756171067621.txt", - "storage_size": 0, - "metadata": null, - "created_at": "2025-08-12T11:52:36.168632288+08:00", - "updated_at": "2025-08-12T11:52:36.173612121+08:00", - "processed_at": null, - "error_message": "", - "deleted_at": null - }, - "success": true -} -``` - -文件重复时返回 409 与已存在知识的引用;超过大小限制返回 400 `文件大小不能超过 N MB`。 - -## POST `/knowledge-bases/:id/knowledge/url` - 从 URL 创建知识 - -可创建**网页知识**或**远程文件知识**。后端根据下列规则自动判定: - -- 当 `file_name` / `file_type` 任一被显式提供,或 URL 路径含已知文件扩展名时,按"文件下载模式"处理(拉取远端文件保存); -- 否则按"网页抓取模式"处理。 - -URL 会经过 SSRF 安全校验,禁止指向内网/回环地址。 - -**请求体**: - -| 字段 | 类型 | 必填 | 说明 | -| ------------------- | ------- | ---- | ------------------------------------------------- | -| `url` | string | 是 | 目标 URL | -| `file_name` | string | 否 | 显式指定文件名,强制走文件下载模式 | -| `file_type` | string | 否 | 显式指定文件类型(如 `pdf`、`docx`) | -| `enable_multimodel` | boolean | 否 | 是否启用多模态解析 | -| `title` | string | 否 | 自定义标题 | -| `tag_id` | string | 否 | 标签 ID | -| `channel` | string | 否 | 来源渠道标识 | - -**请求(网页模式)**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/knowledge/url' \ ---header 'X-API-Key: sk-xxxxx' \ ---header 'Content-Type: application/json' \ ---data '{ - "url": "https://github.com/Tencent/WeKnora", - "enable_multimodel": true -}' -``` - -**请求(远程文件模式)**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/knowledge/url' \ ---header 'X-API-Key: sk-xxxxx' \ ---header 'Content-Type: application/json' \ ---data '{ - "url": "https://example.com/papers/whitepaper.pdf", - "file_name": "whitepaper.pdf", - "file_type": "pdf" -}' -``` - -**响应**(HTTP 201): - -```json -{ - "data": { - "id": "9c8af585-ae15-44ce-8f73-45ad18394651", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "type": "url", - "title": "", - "description": "", - "source": "https://github.com/Tencent/WeKnora", - "channel": "web", - "tag_id": "", - "summary_status": "none", - "parse_status": "processing", - "enable_status": "disabled", - "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", - "file_name": "", - "file_type": "", - "file_size": 0, - "file_hash": "", - "file_path": "", - "storage_size": 0, - "metadata": null, - "created_at": "2025-08-12T11:55:05.709266776+08:00", - "updated_at": "2025-08-12T11:55:05.712918234+08:00", - "processed_at": null, - "error_message": "", - "deleted_at": null - }, - "success": true -} -``` - -## POST `/knowledge-bases/:id/knowledge/manual` - 创建手工 Markdown 知识 - -适用于直接编写 Markdown 内容(无源文件)的场景。 - -**请求体**: - -| 字段 | 类型 | 必填 | 说明 | -| --------- | ------ | ---- | --------------------------------------------------- | -| `title` | string | 是 | 标题 | -| `content` | string | 是 | Markdown 正文 | -| `status` | string | 否 | 草稿/发布等业务状态(草稿不会触发解析) | -| `tag_id` | string | 否 | 标签 ID | -| `channel` | string | 否 | 来源渠道标识 | - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/knowledge/manual' \ ---header 'X-API-Key: sk-xxxxx' \ ---header 'Content-Type: application/json' \ ---data '{ - "title": "产品使用指南", - "content": "# 产品使用指南\n\n## 快速入门\n\n这是一份产品使用指南...", - "status": "published", - "tag_id": "tag-00000001" -}' -``` - -**响应**: - -```json -{ - "data": { - "id": "5a3b2c1d-0e9f-4a8b-7c6d-5e4f3a2b1c0d", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "type": "manual", - "title": "产品使用指南", - "description": "", - "source": "", - "channel": "web", - "tag_id": "tag-00000001", - "summary_status": "none", - "parse_status": "processing", - "enable_status": "disabled", - "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", - "file_name": "", - "file_type": "md", - "file_size": 0, - "file_hash": "", - "file_path": "", - "storage_size": 0, - "metadata": null, - "created_at": "2025-08-12T12:00:00.000000+08:00", - "updated_at": "2025-08-12T12:00:00.000000+08:00", - "processed_at": null, - "error_message": "", - "deleted_at": null - }, - "success": true -} -``` - -## GET `/knowledge-bases/:id/knowledge` - 列出知识库下的知识 - -支持分页与按标签/关键词/文件类型筛选。 - -**路径参数**: - -| 字段 | 类型 | 说明 | -| ---- | ------ | --------- | -| id | string | 知识库 ID | - -**查询参数**: - -| 字段 | 类型 | 默认 | 说明 | -| -------------- | ------- | ---- | --------------------------------------------------------------------------------------------------- | -| `page` | integer | 1 | 页码(从 1 开始) | -| `page_size` | integer | 20 | 每页条数 | -| `tag_id` | string | - | 按标签 ID 过滤 | -| `keyword` | string | - | 按标题/内容关键词过滤 | -| `file_type` | string | - | 按单个文件扩展名过滤(如 `pdf`);特殊值 `manual` / `url` 命中 `type` 列 | -| `parse_status` | string | - | 按解析状态过滤:`pending` / `processing` / `completed` / `failed` | -| `source` | string | - | 按来源/渠道过滤:`web` / `api` / `browser_extension` / `feishu` / `notion` / `yuque` / `wechat` 等; 特殊值 `manual` / `url` 命中 `type` 列 | -| `start_time` | string | - | 更新时间起点,接受 RFC3339 (`2024-05-01T00:00:00+08:00`) 或 `YYYY-MM-DD HH:MM:SS` / `YYYY-MM-DD` | -| `end_time` | string | - | 更新时间终点,格式同 `start_time` | -| `folder_path` | string | - | 按文件夹路径筛选;**仅当传入该参数时启用文件夹维度**。空字符串表示知识库根目录(不含子文件夹中的文档);不传则列出全部文件夹下的文档(扁平视图) | -| `folder_recursive` | bool | false | 为 `true` 时同时返回 `folder_path` 子目录内的文档;仅在传入 `folder_path` 时生效 | - -> **文件夹筛选语义**:`folder_path` 是否出现在 query 中决定列表模式,不能仅凭空字符串区分「根目录」与「不按文件夹过滤」。集成方若需要浏览某一文件夹,应显式传 `folder_path`(根目录传 `folder_path=`);若需要全库扁平列表,则省略该参数。 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/knowledge?page=1&page_size=1&tag_id=tag-00000001' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**: - -```json -{ - "data": [ - { - "id": "9c8af585-ae15-44ce-8f73-45ad18394651", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "type": "url", - "title": "", - "description": "", - "source": "https://github.com/Tencent/WeKnora", - "channel": "web", - "tag_id": "tag-00000001", - "summary_status": "none", - "parse_status": "pending", - "enable_status": "disabled", - "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", - "file_name": "", - "folder_path": "", - "file_type": "", - "file_size": 0, - "file_hash": "", - "file_path": "", - "storage_size": 0, - "metadata": null, - "created_at": "2025-08-12T11:55:05.709266+08:00", - "updated_at": "2025-08-12T11:55:05.709266+08:00", - "processed_at": null, - "error_message": "", - "deleted_at": null - } - ], - "page": 1, - "page_size": 1, - "total": 2, - "success": true -} -``` - -## GET `/knowledge-bases/:id/knowledge/folders` - 获取文件夹目录树 - -返回由 `folder_path` 聚合而成的目录树,包含每个文件夹的直接文档数与含子目录的总数。只读,权限与列出知识相同(Viewer+ 且对 KB 有 read 权限)。 - -**响应**: - -```json -{ - "success": true, - "data": { - "root_document_count": 2, - "total_document_count": 10, - "folders": [ - { - "path": "docs", - "name": "docs", - "document_count": 0, - "total_count": 4, - "children": [ - { - "path": "docs/spec", - "name": "spec", - "document_count": 3, - "total_count": 4, - "children": [] - } - ] - } - ] - } -} -``` - -## PUT `/knowledge-bases/:id/knowledge/folders` - 重命名或移动文件夹 - -把一个文件夹及其所有子目录改到新路径。目标路径已存在时两个文件夹合并;不能移动到自身子目录下。需要 KB **创建者**或 Admin+,且对 KB 有 write 权限。 - -**请求体**: - -| 字段 | 类型 | 必填 | 说明 | -| ------ | ------ | ---- | ---------------------------- | -| `from` | string | 是 | 源文件夹路径(不能为空) | -| `to` | string | 是 | 目标文件夹路径(不能为空) | - -**响应**: - -```json -{ - "success": true, - "data": { - "moved_count": 3, - "folder_path": "handbook" - } -} -``` - -`moved_count` 为 0 表示源文件夹不存在或已是 no-op。 - -## POST `/knowledge/folder` - 批量移动知识到文件夹 - -批量修改知识条目的 `folder_path`,仅调整归类,**不会**重新解析、分块或向量化。目标路径不存在时会自动创建;空路径表示移回知识库根目录。需要 editor/admin 且为 KB 创建者或 Admin+。 - -**请求体**: - -| 字段 | 类型 | 必填 | 说明 | -| --------------- | -------- | ---- | ----------------------------------------- | -| `kb_id` | string | 是 | 知识库 ID | -| `knowledge_ids` | string[] | 是 | 知识 ID 列表(最多 200 条) | -| `folder_path` | string | 否 | 目标文件夹路径;省略或空字符串表示根目录 | - -**响应**: - -```json -{ - "success": true, - "data": { - "moved_count": 2, - "folder_path": "archive/2026" - } -} -``` - -## DELETE `/knowledge-bases/:id/knowledge` - 清空知识库下的所有知识 - -异步提交"清空任务",删除该知识库下的全部知识条目;知识库本身保留。**仅 KB 所有者(admin 且空间匹配)可操作**。 - -**请求**: - -```curl -curl --location --request DELETE 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/knowledge' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**(已入队): - -```json -{ - "success": true, - "message": "Knowledge base contents clear task submitted", - "data": { "deleted_count": 42 } -} -``` - -知识库已为空时: - -```json -{ - "success": true, - "message": "Knowledge base is already empty", - "data": { "deleted_count": 0 } -} -``` - -## GET `/knowledge/batch` - 批量获取知识 - -按 ID 列表一次性获取多条知识详情,常用于刷新页面后恢复选中列表。 - -**查询参数**: - -| 字段 | 类型 | 必填 | 说明 | -| ----------- | -------- | ---- | --------------------------------------------------------------------- | -| `ids` | string[] | 是 | 知识 ID,重复 `ids=...` 传多个 | -| `kb_id` | string | 否 | 限定知识库范围;共享知识库场景下用于按 KB 校验权限并解析有效空间 | -| `agent_id` | string | 否 | 共享 Agent ID;按 Agent 所属空间拉取,常用于共享场景刷新后的文件回填 | - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge/batch?ids=9c8af585-ae15-44ce-8f73-45ad18394651&ids=4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**: - -```json -{ - "data": [ - { - "id": "9c8af585-ae15-44ce-8f73-45ad18394651", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "type": "url", - "title": "", - "source": "https://github.com/Tencent/WeKnora", - "parse_status": "pending", - "enable_status": "disabled", - "created_at": "2025-08-12T11:55:05.709266+08:00", - "updated_at": "2025-08-12T11:55:05.709266+08:00" - }, - { - "id": "4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "type": "file", - "title": "彗星.txt", - "file_name": "彗星.txt", - "file_type": "txt", - "file_size": 7710, - "parse_status": "completed", - "enable_status": "enabled", - "created_at": "2025-08-12T11:52:36.168632+08:00", - "updated_at": "2025-08-12T11:52:53.376871+08:00" - } - ], - "success": true -} -``` - -> 上述响应字段省略了空值与一些大字段,实际返回的是完整 `Knowledge` 对象。 - -## GET `/knowledge/:id` - 获取知识详情 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**: - -```json -{ - "data": { - "id": "4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "type": "file", - "title": "彗星.txt", - "description": "彗星是由冰和尘埃构成的太阳系小天体,接近太阳时会形成彗发和彗尾。", - "source": "", - "channel": "web", - "tag_id": "tag-00000001", - "summary_status": "completed", - "parse_status": "completed", - "enable_status": "enabled", - "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", - "file_name": "彗星.txt", - "file_type": "txt", - "file_size": 7710, - "file_hash": "d69476ddbba45223a5e97e786539952c", - "file_path": "data/files/1/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5/1754970756171067621.txt", - "storage_size": 33689, - "metadata": null, - "created_at": "2025-08-12T11:52:36.168632+08:00", - "updated_at": "2025-08-12T11:52:53.376871+08:00", - "processed_at": "2025-08-12T11:52:53.376573+08:00", - "error_message": "", - "deleted_at": null - }, - "success": true -} -``` - -## PUT `/knowledge/:id` - 更新知识 - -部分更新知识条目的元信息。请求体字段均可选;**未传字段保持不变**。显式传入 `"description": ""` 可清空摘要。 - -可更新字段:`title`、`description`、`custom_metadata`。 - -**请求**: - -```curl -curl --location --request PUT 'http://localhost:8080/api/v1/knowledge/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5' \ ---header 'X-API-Key: sk-xxxxx' \ ---header 'Content-Type: application/json' \ ---data '{ - "title": "彗星 - 天文百科", - "description": "彗星条目,已校对" -}' -``` - -清空摘要示例: - -```curl -curl --location --request PUT 'http://localhost:8080/api/v1/knowledge/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5' \ ---header 'X-API-Key: sk-xxxxx' \ ---header 'Content-Type: application/json' \ ---data '{ - "description": "" -}' -``` - -**响应**: - -```json -{ - "success": true, - "message": "Knowledge updated successfully", - "data": {} -} -``` - -## DELETE `/knowledge/:id` - 删除单条知识 - -**请求**: - -```curl -curl --location --request DELETE 'http://localhost:8080/api/v1/knowledge/9c8af585-ae15-44ce-8f73-45ad18394651' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**: - -```json -{ - "success": true, - "message": "Deleted successfully" -} -``` - -## PUT `/knowledge/manual/:id` - 更新手工 Markdown 知识 - -**请求体**:同 `POST /knowledge-bases/:id/knowledge/manual`,字段全部可选。 - -**请求**: - -```curl -curl --location --request PUT 'http://localhost:8080/api/v1/knowledge/manual/5a3b2c1d-0e9f-4a8b-7c6d-5e4f3a2b1c0d' \ ---header 'X-API-Key: sk-xxxxx' \ ---header 'Content-Type: application/json' \ ---data '{ - "title": "产品使用指南 V2", - "content": "# 产品使用指南 V2\n\n## 更新内容\n\n..." -}' -``` - -**响应**: - -```json -{ - "data": { - "id": "5a3b2c1d-0e9f-4a8b-7c6d-5e4f3a2b1c0d", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "type": "manual", - "title": "产品使用指南 V2", - "parse_status": "processing", - "enable_status": "enabled", - "created_at": "2025-08-12T12:00:00.000000+08:00", - "updated_at": "2025-08-12T12:30:00.000000+08:00" - }, - "success": true -} -``` - -## POST `/knowledge/:id/reparse` - 重新解析知识 - -异步重新解析:删除现有分块/向量并按最新配置重新解析。常用于解析配置变更或上次解析失败重试的场景。 - -**请求**: - -```curl -curl --location --request POST 'http://localhost:8080/api/v1/knowledge/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5/reparse' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**: - -```json -{ - "success": true, - "message": "Knowledge reparse task submitted", - "data": { - "id": "4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "type": "file", - "title": "彗星.txt", - "parse_status": "pending", - "enable_status": "enabled", - "created_at": "2025-08-12T11:52:36.168632+08:00", - "updated_at": "2025-08-12T13:00:00.000000+08:00" - } -} -``` - -调用后 `parse_status` 会先变为 `pending`,再由后台 worker 转为 `processing` → `completed`/`failed`。 - -## POST `/knowledge/:id/cancel-parse` - 取消解析 - -中止正在进行的解析任务,常用于资源紧张时主动放弃当前文档的解析过程。 - -**行为**: - -- 将 `parse_status` 置为 `cancelled`,`error_message` 写入「用户已取消解析」,并把 `pending_subtasks_count` 清零。 -- 已写入数据库的分块 / 索引保留,可通过 `reparse` 接口在同一记录上重新触发解析。 -- 后台异步会 best-effort 从队列中删除该知识对应的下游任务(多模态、问题生成、摘要、图谱抽取、Post-Process 等),并对正在执行的 worker 发出停止信号;worker 在下一个检查点退出。 -- **可取消的状态**:`pending` / `processing` / `finalizing`。`finalizing` 表示主解析已完成、摘要 / 问题生成 / 图谱抽取等索引优化任务仍在执行;在该状态取消可以及时停止后续 LLM 消耗(图谱抽取按 chunk 调用,开销最大)。 -- 已经完成 (`completed`) 或失败 (`failed`) 的知识不允许取消;正在删除 (`deleting`) 的知识不允许取消。 -- 接口幂等:对已经 `cancelled` 的记录重复调用直接返回当前状态。 - -**请求**: - -```curl -curl --location --request POST 'http://localhost:8080/api/v1/knowledge/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5/cancel-parse' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**: - -```json -{ - "success": true, - "message": "Knowledge parse cancelled", - "data": { - "id": "4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "type": "file", - "title": "彗星.txt", - "parse_status": "cancelled", - "error_message": "用户已取消解析", - "enable_status": "disabled", - "created_at": "2025-08-12T11:52:36.168632+08:00", - "updated_at": "2025-08-12T13:05:00.000000+08:00" - } -} -``` - -## 文件下载 - -### POST `/knowledge-bases/:id/knowledge/batch-download` - 批量下载 - -`POST /api/v1/knowledge-bases/:id/knowledge/batch-download`,请求体为 `{"ids":["文档ID1","文档ID2"]}`。 - -- 权限与单文件下载一致:JWT 用户需要 Contributor 身份及知识库 Editor 权限;API Key 需要 `retrieve` 能力或完整访问权限,并受知识库白名单限制。 -- 每次最多 200 个 ID(重复 ID 只下载一次),原始文件实际读取字节合计最多 512 MiB。超限请分批下载。服务端同时最多处理 4 个批量下载请求,过多时返回 429。 -- 成功返回 `application/zip` 附件;保留文件内容、中文文件名和知识库 `folder_path`。同名文件自动追加数字,移除不安全路径和 Windows 不支持的文件名字符。 -- 手工编写的文档导出为 Markdown。没有原始文件的网页条目会被跳过;若跳过后没有任何可下载文件,返回 400。FAQ 条目通常没有原始文件,不能通过此接口导出。 -- 任一条目无权访问、不属于当前知识库或读取失败时,整个请求失败,不返回残缺 ZIP。请求取消时返回 400,而不是 500。 -- 压缩包在服务器临时目录生成后发送,请求结束或失败后清理临时文件;不包含分块、向量、标签、权限、Wiki 或图谱。 - -页面操作:进入知识库的文档页 → 点击「批量管理」→ 勾选文件,或「全选已加载」→「批量下载」。全选只包含列表已加载的文档;可先继续加载更多,再选择,单批仍受 200 项限制。没有原始文件的条目会自动跳过。ZIP 解压后可按文件夹批量上传到其他知识库。 - -**请求**: - -```curl -curl --location --request POST 'http://localhost:8080/api/v1/knowledge-bases/kb-id/knowledge/batch-download' \ ---header 'X-API-Key: sk-xxxxx' \ ---header 'Content-Type: application/json' \ ---data '{"ids":["文档ID1","文档ID2"]}' \ ---output knowledge-files.zip -``` - -### GET `/knowledge/:id/download` - 单文件下载 - -以 `attachment` 方式下载知识对应的原始文件。 - -**响应头**: - -``` -Content-Type: application/octet-stream -Content-Disposition: attachment; filename="彗星.txt" -``` - -**请求**: - -```curl -curl --location -OJ 'http://localhost:8080/api/v1/knowledge/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5/download' \ ---header 'X-API-Key: sk-xxxxx' -``` - -响应体为文件二进制流。 - -## GET `/knowledge/:id/preview` - 内联预览文件 - -返回原始文件用于浏览器**内嵌预览**: - -- `Content-Type` 按文件扩展名映射(`.pdf` → `application/pdf`,`.png` → `image/png`,`.txt`/`.md`/`.json` 等 → 对应文本 MIME 并带 `charset=utf-8`,未知扩展名回落到 `application/octet-stream`)。 -- `Content-Disposition: inline; filename="<原文件名>"`,浏览器会内嵌渲染而非下载。 -- `Cache-Control: private, max-age=3600`。 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5/preview' \ ---header 'X-API-Key: sk-xxxxx' \ --D - -``` - -**响应头**示例: - -``` -HTTP/1.1 200 OK -Content-Type: text/plain; charset=utf-8 -Content-Disposition: inline; filename="彗星.txt" -Cache-Control: private, max-age=3600 -``` - -响应体为文件内容(按 `Content-Type` 解读)。 - -## PUT `/knowledge/image/:id/:chunk_id` - 更新分块图像信息 - -为指定知识下的某个图像分块更新描述/替代文本等元信息。 - -**路径参数**: - -| 字段 | 类型 | 说明 | -| ---------- | ------ | -------- | -| `id` | string | 知识 ID | -| `chunk_id` | string | 分块 ID | - -**请求体**: - -| 字段 | 类型 | 必填 | 说明 | -| ------------ | ------ | ---- | ------------------------------------ | -| `image_info` | string | 是 | 图像信息(业务侧 JSON 字符串) | - -**请求**: - -```curl -curl --location --request PUT 'http://localhost:8080/api/v1/knowledge/image/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5/df10b37d-cd05-4b14-ba8a-e1bd0eb3bbd7' \ ---header 'X-API-Key: sk-xxxxx' \ ---header 'Content-Type: application/json' \ ---data '{ - "image_info": "{\"description\":\"产品架构图\",\"alt_text\":\"WeKnora 系统架构\"}" -}' -``` - -**响应**: - -```json -{ - "success": true, - "message": "Knowledge chunk image updated successfully" -} -``` - -## PUT `/knowledge/tags` - 批量更新知识标签 - -批量为多条知识设置/清除标签。 - -**请求体**: - -| 字段 | 类型 | 必填 | 说明 | -| --------- | -------------------------- | ---- | -------------------------------------------------------------------------- | -| `updates` | object | 是 | 知识 ID → 标签 ID 的映射;值为 `null` 表示清除该条知识的标签 | -| `kb_id` | string | 否 | 限定知识库范围;指定时按该 KB 校验编辑权限(共享 KB 场景必填) | - -未传 `kb_id` 时,服务会从 `updates` 中取首个 knowledge ID 推断其所属知识库并据此鉴权。 - -**请求**: - -```curl -curl --location --request PUT 'http://localhost:8080/api/v1/knowledge/tags' \ ---header 'X-API-Key: sk-xxxxx' \ ---header 'Content-Type: application/json' \ ---data '{ - "kb_id": "kb-00000001", - "updates": { - "4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5": "tag-00000001", - "9c8af585-ae15-44ce-8f73-45ad18394651": null - } -}' -``` - -**响应**: - -```json -{ "success": true } -``` - -## GET `/knowledge/search` - 跨知识库搜索/过滤知识 - -按关键词在当前空间(含已共享给当前空间)的知识中检索;可按文件类型过滤;指定 `agent_id` 时按共享 Agent 所配置的知识库范围检索。 - -**查询参数**: - -| 字段 | 类型 | 默认 | 说明 | -| ------------ | ------- | ---- | --------------------------------------------------------------------- | -| `keyword` | string | - | 关键词(可选) | -| `offset` | integer | 0 | 偏移量 | -| `limit` | integer | 20 | 返回条数 | -| `file_types` | string | - | 逗号分隔的扩展名列表,例如 `txt,pdf,docx` | -| `agent_id` | string | - | 共享 Agent ID;按该 Agent 的 KB 选择模式(`all`/`selected`/`none`)限定范围 | - -**请求**: - -```curl -curl --location --get 'http://localhost:8080/api/v1/knowledge/search' \ ---header 'X-API-Key: sk-xxxxx' \ ---data-urlencode 'keyword=彗星' \ ---data-urlencode 'offset=0' \ ---data-urlencode 'limit=10' \ ---data-urlencode 'file_types=txt,pdf' -``` - -**响应**: - -```json -{ - "success": true, - "data": [ - { - "id": "4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "type": "file", - "title": "彗星.txt", - "description": "彗星是由冰和尘埃构成的太阳系小天体...", - "file_name": "彗星.txt", - "file_type": "txt", - "file_size": 7710, - "parse_status": "completed", - "enable_status": "enabled", - "created_at": "2025-08-12T11:52:36.168632+08:00", - "updated_at": "2025-08-12T11:52:53.376871+08:00" - } - ], - "has_more": false -} -``` - -> 注意:与其他列表接口不同,此处的 `data` 是**数组**而非 `{data, has_more}` 嵌套对象;`has_more` 与 `data` 同级。 - -`agent_id=...&` 且该 Agent 的 KB 选择模式为 `none` 时,将直接返回 `data: []` 与 `has_more: false`。 - -## POST `/knowledge/batch-reparse` - 同一知识库内批量重新解析 - -按 ID 列表在单个知识库内批量重新解析知识(异步任务)。单次最多 200 个 ID;服务侧会校验所有 ID 存在并属于同一 `kb_id`。 - -**请求体**: - -| 字段 | 类型 | 必填 | 说明 | -| ---------------- | -------- | ---- | ------------------------------------------------ | -| `kb_id` | string | 是 | 目标知识库 ID | -| `ids` | string[] | 是 | 待重新解析的知识 ID 列表(≤ 200) | -| `process_config` | object | 否 | 本批次共用的处理配置覆盖;省略时沿用各知识原配置 | - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge/batch-reparse' \ ---header 'X-API-Key: sk-xxxxx' \ ---header 'Content-Type: application/json' \ ---data '{ - "kb_id": "kb-00000001", - "ids": [ - "4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5", - "9c8af585-ae15-44ce-8f73-45ad18394651" - ] -}' -``` - -**响应**: - -```json -{ - "success": true, - "message": "Batch reparse task submitted", - "data": { - "task_id": "a1b2c3d4", - "reparse_count": 2 - } -} -``` - -HTTP 成功表示批处理包装任务已入队。后台会尝试提交列表中的每个知识;单项提交失败时,该知识会进入 `failed` 状态并保留错误信息,批处理任务也会在运行队列中标记失败。为避免重复清理已成功提交的知识,出现部分失败后不会自动重试整个批次;可筛选失败知识后再次批量重新解析。 - -任一 ID 不属于 `kb_id` 或不存在时,返回 400 并整批拒绝。 - -## POST `/knowledge/batch-delete` - 同一知识库内批量删除 - -按 ID 列表在单个知识库内批量删除知识(异步任务)。单次最多 200 个 ID;服务侧会校验所有 ID 属于同一 `kb_id`。 - -**请求体**: - -| 字段 | 类型 | 必填 | 说明 | -| ------- | -------- | ---- | --------------------------------- | -| `kb_id` | string | 是 | 目标知识库 ID | -| `ids` | string[] | 是 | 待删除的知识 ID 列表(≤ 200) | - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge/batch-delete' \ ---header 'X-API-Key: sk-xxxxx' \ ---header 'Content-Type: application/json' \ ---data '{ - "kb_id": "kb-00000001", - "ids": [ - "4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5", - "9c8af585-ae15-44ce-8f73-45ad18394651" - ] -}' -``` - -**响应**: - -```json -{ - "success": true, - "message": "Batch delete task submitted", - "data": { - "task_id": "kg_delete_1_kb-00000001_xxxx", - "deleted_count": 2 - } -} -``` - -任一 ID 不属于 `kb_id` 或不存在时,返回 400 并整批拒绝。 - -## POST `/knowledge/move` - 迁移知识到另一知识库 - -将一条或多条**处于 `completed` 状态**的知识从源 KB 迁到目标 KB(异步)。约束: - -- 源/目标 KB 必须属于当前空间; -- 源/目标必须为同一 KB 类型且**使用相同的 Embedding 模型**; -- 源 KB ≠ 目标 KB; -- 仅 `parse_status=completed` 的知识可迁移。 - -**请求体**: - -| 字段 | 类型 | 必填 | 说明 | -| --------------- | -------- | ---- | ------------------------------------------------------------------------------- | -| `knowledge_ids` | string[] | 是 | 待迁移的知识 ID 列表(至少 1 个) | -| `source_kb_id` | string | 是 | 源知识库 ID | -| `target_kb_id` | string | 是 | 目标知识库 ID | -| `mode` | string | 是 | 迁移模式:`reuse_vectors`(复用向量数据,零成本) / `reparse`(在目标库重新解析) | - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge/move' \ ---header 'X-API-Key: sk-xxxxx' \ ---header 'Content-Type: application/json' \ ---data '{ - "knowledge_ids": ["4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5"], - "source_kb_id": "kb-00000001", - "target_kb_id": "kb-00000002", - "mode": "reuse_vectors" -}' -``` - -**响应**: - -```json -{ - "success": true, - "data": { - "task_id": "kg_move_1_kb-00000001_xxxx", - "source_kb_id": "kb-00000001", - "target_kb_id": "kb-00000002", - "knowledge_count": 1, - "message": "Knowledge move task started" - } -} -``` - -获取 `task_id` 后通过下一个接口轮询进度。 - -## GET `/knowledge/move/progress/:task_id` - 查询迁移进度 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge/move/progress/kg_move_1_kb-00000001_xxxx' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**: - -```json -{ - "success": true, - "data": { - "task_id": "kg_move_1_kb-00000001_xxxx", - "source_kb_id": "kb-00000001", - "target_kb_id": "kb-00000002", - "status": "completed", - "progress": 100, - "total": 1, - "processed": 1, - "failed": 0, - "message": "迁移完成", - "error": "", - "created_at": 1731312000, - "updated_at": 1731312045 - } -} -``` - -`status` 取值:`pending` / `processing` / `completed` / `failed`;`progress` 为 0-100 的整数百分比;`created_at` / `updated_at` 为 Unix 秒时间戳。 diff --git a/docs/api/mcp-service.md b/docs/api/mcp-service.md deleted file mode 100644 index 5e24189f..00000000 --- a/docs/api/mcp-service.md +++ /dev/null @@ -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` 不存在或已完成(超时/取消已先一步消费) | diff --git a/docs/api/memory.md b/docs/api/memory.md deleted file mode 100644 index 33fc9792..00000000 --- a/docs/api/memory.md +++ /dev/null @@ -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 ' -``` - -**响应**: - -```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 ' \ ---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`)。 diff --git a/docs/api/message.md b/docs/api/message.md deleted file mode 100644 index 00428ad9..00000000 --- a/docs/api/message.md +++ /dev/null @@ -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": "\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": "\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 -} -``` diff --git a/docs/api/model.md b/docs/api/model.md deleted file mode 100644 index a21deecd..00000000 --- a/docs/api/model.md +++ /dev/null @@ -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 | 否 | 服务商特定的额外配置 | -| custom_headers | object | 否 | 调用上游 API 时附加的自定义 HTTP 头;保留头会被忽略 | -| supports_vision | bool | 否 | 模型是否支持图像/多模态输入 | - -### EmbeddingParameters (嵌入参数) - -| 字段 | 类型 | 必填 | 说明 | -| ---------------------- | ---- | ---- | ------------------------------- | -| dimension | int | 否 | 向量维度(如 768、1024) | -| truncate_prompt_tokens | int | 否 | 截断 Token 数(0 表示不截断) | diff --git a/docs/api/organization.md b/docs/api/organization.md deleted file mode 100644 index d654a9fb..00000000 --- a/docs/api/organization.md +++ /dev/null @@ -1,1220 +0,0 @@ -# 组织管理 API - -[返回目录](./README.md) - -组织(Organization,又称"空间")是 WeKnora 的多空间协作单元。一个用户可以创建/加入多个组织,并以 owner / admin / editor / viewer 的角色参与;知识库与智能体可以共享到组织内,组织成员根据角色获得相应的访问权限。 - -本页文档覆盖以下六类接口: - -- 组织管理:组织 CRUD、邀请码、搜索、加入与离开 -- 成员管理:成员列表、角色变更、移除、邀请 -- 加入请求:申请列表、审核 -- 知识库共享:将知识库共享到组织 / 取消共享 / 修改权限 -- 智能体共享:将智能体共享到组织 / 取消共享 -- 我的共享视图:当前用户可访问的所有共享知识库 / 智能体 - -公共说明: -- 所有路径前缀为 `/api/v1` -- 鉴权头:`X-API-Key: sk-xxxxx`(或 `Authorization: Bearer ...`) -- 错误响应统一为 `{ "success": false, "error": "..." }`,HTTP 状态码遵循 RESTful 语义 -- 角色 (`OrgMemberRole`) 取值:`owner` / `admin` / `editor` / `viewer` -- 共享权限 (`permission`) 取值:`viewer` / `editor`(创建时通常只允许这两个) - -## 路由总览 - -### 组织管理 - -| 方法 | 路径 | 描述 | -| ------ | --------------------------------------------- | ----------------------------------- | -| POST | `/organizations` | 创建组织 | -| GET | `/organizations` | 获取我的组织列表(含资源数量) | -| GET | `/organizations/preview/:code` | 通过邀请码预览组织(不加入) | -| POST | `/organizations/join` | 通过邀请码加入组织 | -| POST | `/organizations/join-request` | 提交加入申请(针对需要审核的组织) | -| GET | `/organizations/search` | 搜索可加入的可被搜索的组织 | -| POST | `/organizations/join-by-id` | 通过组织 ID 加入可被搜索的组织 | -| GET | `/organizations/:id` | 获取组织详情 | -| PUT | `/organizations/:id` | 更新组织 | -| DELETE | `/organizations/:id` | 删除组织 | -| POST | `/organizations/:id/leave` | 离开组织 | -| POST | `/organizations/:id/request-upgrade` | 现有成员申请角色升级 | -| POST | `/organizations/:id/invite-code` | 重新生成邀请码 | - -### 成员管理 - -| 方法 | 路径 | 描述 | -| ------ | --------------------------------------------- | --------------------------------- | -| GET | `/organizations/:id/search-users` | 搜索可邀请的用户(仅管理员) | -| POST | `/organizations/:id/invite` | 直接添加用户为成员(仅管理员) | -| GET | `/organizations/:id/members` | 获取成员列表 | -| PUT | `/organizations/:id/members/:user_id` | 更新成员角色 | -| DELETE | `/organizations/:id/members/:user_id` | 移除成员 | - -### 加入请求 - -| 方法 | 路径 | 描述 | -| ---- | ------------------------------------------------------- | -------------------------- | -| GET | `/organizations/:id/join-requests` | 获取待审核加入申请列表 | -| PUT | `/organizations/:id/join-requests/:request_id/review` | 审核加入申请(仅管理员) | - -### 知识库共享 - -| 方法 | 路径 | 描述 | -| ------ | --------------------------------------------- | ------------------------------------- | -| POST | `/knowledge-bases/:id/shares` | 将知识库共享到组织 | -| GET | `/knowledge-bases/:id/shares` | 获取该知识库的共享列表 | -| PUT | `/knowledge-bases/:id/shares/:share_id` | 更新共享权限 | -| DELETE | `/knowledge-bases/:id/shares/:share_id` | 取消共享 | -| GET | `/organizations/:id/shares` | 获取组织下被共享进来的知识库列表 | -| GET | `/organizations/:id/shared-knowledge-bases` | 组织内全部知识库(含我共享的,空间视图) | - -### 智能体共享 - -| 方法 | 路径 | 描述 | -| ------ | --------------------------------------------- | ------------------------------------- | -| POST | `/agents/:id/shares` | 将智能体共享到组织 | -| GET | `/agents/:id/shares` | 获取该智能体的共享列表 | -| DELETE | `/agents/:id/shares/:share_id` | 取消共享 | -| GET | `/organizations/:id/agent-shares` | 获取组织下被共享进来的智能体列表 | -| GET | `/organizations/:id/shared-agents` | 组织内全部智能体(含我共享的,空间视图) | - -### 我的共享视图 - -| 方法 | 路径 | 描述 | -| ---- | ----------------------------- | --------------------------------------- | -| GET | `/shared-knowledge-bases` | 获取所有共享给我的知识库(跨组织) | -| GET | `/shared-agents` | 获取所有共享给我的智能体(跨组织) | - ---- - -## 组织管理 - -### POST `/organizations` - 创建组织 - -**请求体**: - -| 字段 | 类型 | 必填 | 说明 | -| --------------------------- | ------- | ---- | ------------------------------------------------- | -| name | string | 是 | 组织名称(1-255 字符) | -| description | string | 否 | 组织描述(最多 1000 字符) | -| avatar | string | 否 | 头像 URL(最多 512 字符) | -| invite_code_validity_days | int | 否 | 邀请码有效天数:`0`=永久,`1` / `7` / `30`,默认 7 | -| member_limit | int | 否 | 成员上限,`0`=不限,默认 50 | - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/organizations' \ ---header 'X-API-Key: sk-xxxxx' \ ---header 'Content-Type: application/json' \ ---data '{ - "name": "AI 技术团队", - "description": "专注于 AI 技术研究与知识管理", - "invite_code_validity_days": 7, - "member_limit": 50 -}' -``` - -**响应**(`201 Created`): - -```json -{ - "data": { - "id": "org-00000001", - "name": "AI 技术团队", - "description": "专注于 AI 技术研究与知识管理", - "avatar": "", - "owner_id": "user-00000001", - "invite_code": "", - "invite_code_validity_days": 7, - "require_approval": false, - "searchable": false, - "member_limit": 50, - "member_count": 1, - "share_count": 0, - "agent_share_count": 0, - "pending_join_request_count": 0, - "is_owner": true, - "my_role": "owner", - "has_pending_upgrade": false, - "created_at": "2025-08-12T10:00:00+08:00", - "updated_at": "2025-08-12T10:00:00+08:00" - }, - "success": true -} -``` - -### GET `/organizations` - 获取我的组织列表 - -返回当前用户所属的全部组织;`resource_counts` 字段附带每个空间内的知识库数与智能体数,供列表页侧栏直接渲染。 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/organizations' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**: - -```json -{ - "data": { - "organizations": [ - { - "id": "org-00000001", - "name": "AI 技术团队", - "description": "专注于 AI 技术研究与知识管理", - "owner_id": "user-00000001", - "invite_code": "ABC123XY", - "invite_code_expires_at": "2025-08-19T10:00:00+08:00", - "invite_code_validity_days": 7, - "require_approval": false, - "searchable": false, - "member_limit": 50, - "member_count": 3, - "share_count": 2, - "agent_share_count": 1, - "pending_join_request_count": 0, - "is_owner": true, - "my_role": "owner", - "has_pending_upgrade": false, - "created_at": "2025-08-12T10:00:00+08:00", - "updated_at": "2025-08-12T10:00:00+08:00" - } - ], - "total": 1, - "resource_counts": { - "knowledge_bases": { "by_organization": { "org-00000001": 5 } }, - "agents": { "by_organization": { "org-00000001": 2 } } - } - }, - "success": true -} -``` - -### GET `/organizations/preview/:code` - 通过邀请码预览组织 - -不需要事先成为成员,可用于"加入前预览"页面。`:code` 为邀请码字符串。 - -**路径参数**: - -| 字段 | 类型 | 说明 | -| ---- | ------ | ------ | -| code | string | 邀请码 | - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/organizations/preview/ABC123XY' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**: - -```json -{ - "data": { - "id": "org-00000001", - "name": "AI 技术团队", - "description": "专注于 AI 技术研究与知识管理", - "avatar": "", - "member_count": 3, - "share_count": 2, - "agent_share_count": 1, - "is_already_member": false, - "require_approval": true, - "created_at": "2025-08-12T10:00:00+08:00" - }, - "success": true -} -``` - -### POST `/organizations/join` - 通过邀请码加入组织 - -仅适用于 `require_approval: false` 的组织。需要审核的组织请改用 `/organizations/join-request`。 - -**请求体**: - -| 字段 | 类型 | 必填 | 说明 | -| ----------- | ------ | ---- | --------------------- | -| invite_code | string | 是 | 邀请码(8-32 字符) | - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/organizations/join' \ ---header 'X-API-Key: sk-xxxxx' \ ---header 'Content-Type: application/json' \ ---data '{ - "invite_code": "ABC123XY" -}' -``` - -**响应**: 返回加入后的组织信息(结构同 `GET /organizations/:id`)。 - -### POST `/organizations/join-request` - 提交加入申请 - -当组织开启审核(`require_approval: true`)时使用。 - -**请求体**: - -| 字段 | 类型 | 必填 | 说明 | -| ----------- | ------ | ---- | ------------------------------------------- | -| invite_code | string | 是 | 邀请码(8-32 字符) | -| message | string | 否 | 申请留言(最多 500 字符) | -| role | string | 否 | 期望角色:`viewer` / `editor` / `admin` | - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/organizations/join-request' \ ---header 'X-API-Key: sk-xxxxx' \ ---header 'Content-Type: application/json' \ ---data '{ - "invite_code": "ABC123XY", - "message": "希望加入团队参与知识库建设", - "role": "editor" -}' -``` - -**响应**: - -```json -{ - "data": { - "id": "jr-00000001", - "user_id": "user-00000002", - "request_type": "join", - "requested_role": "editor", - "status": "pending", - "created_at": "2025-08-14T10:00:00+08:00" - }, - "success": true -} -``` - -### GET `/organizations/search` - 搜索可加入的组织 - -返回设置了 `searchable: true` 的组织。仅返回元数据,不返回邀请码。 - -**查询参数**: - -| 字段 | 类型 | 必填 | 说明 | -| ----- | ------ | ---- | --------------------------------- | -| q | string | 否 | 搜索关键词(名称或描述模糊匹配) | -| limit | int | 否 | 返回数量(1-100,默认 20) | - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/organizations/search?q=AI&limit=10' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**: - -```json -{ - "data": [ - { - "id": "org-00000001", - "name": "AI 技术团队", - "description": "专注于 AI 技术研究与知识管理", - "avatar": "", - "member_count": 3, - "member_limit": 50, - "share_count": 2, - "agent_share_count": 1, - "is_already_member": false, - "require_approval": true - } - ], - "total": 1, - "success": true -} -``` - -### POST `/organizations/join-by-id` - 通过组织 ID 加入 - -用于"搜索可加入空间"流程,无需邀请码;目标组织必须 `searchable: true`。如果组织开启了审核,会创建加入申请;否则直接加入。 - -**请求体**: - -| 字段 | 类型 | 必填 | 说明 | -| ---------------- | ------ | ---- | ------------------------------------------ | -| organization_id | string | 是 | 目标组织 ID | -| message | string | 否 | 申请留言(最多 500 字符) | -| role | string | 否 | 期望角色:`viewer` / `editor` / `admin` | - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/organizations/join-by-id' \ ---header 'X-API-Key: sk-xxxxx' \ ---header 'Content-Type: application/json' \ ---data '{ - "organization_id": "org-00000001", - "message": "希望加入贵团队", - "role": "viewer" -}' -``` - -**响应**: 返回加入后的组织信息(结构同 `GET /organizations/:id`)。 - -### GET `/organizations/:id` - 获取组织详情 - -**路径参数**: - -| 字段 | 类型 | 说明 | -| ---- | ------ | ------- | -| id | string | 组织 ID | - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/organizations/org-00000001' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**: - -```json -{ - "data": { - "id": "org-00000001", - "name": "AI 技术团队", - "description": "专注于 AI 技术研究与知识管理", - "avatar": "", - "owner_id": "user-00000001", - "invite_code": "ABC123XY", - "invite_code_expires_at": "2025-08-19T10:00:00+08:00", - "invite_code_validity_days": 7, - "require_approval": false, - "searchable": true, - "member_limit": 50, - "member_count": 3, - "share_count": 2, - "agent_share_count": 1, - "pending_join_request_count": 1, - "is_owner": true, - "my_role": "owner", - "has_pending_upgrade": false, - "created_at": "2025-08-12T10:00:00+08:00", - "updated_at": "2025-08-12T10:00:00+08:00" - }, - "success": true -} -``` - -`invite_code` 与 `invite_code_expires_at` 仅当前用户为 owner 或 admin 时返回。 - -### PUT `/organizations/:id` - 更新组织 - -**请求体**(全部字段均为可选,传 `null` 等同于不更新): - -| 字段 | 类型 | 说明 | -| --------------------------- | ------- | --------------------------------------------- | -| name | string | 组织名称(1-255 字符) | -| description | string | 组织描述(最多 1000 字符) | -| avatar | string | 头像 URL(最多 512 字符) | -| require_approval | bool | 加入是否需要审核 | -| searchable | bool | 是否在 `/organizations/search` 中可被发现 | -| invite_code_validity_days | int | 邀请码有效天数(0=永久,1/7/30) | -| member_limit | int | 成员上限(0=不限) | - -**请求**: - -```curl -curl --location --request PUT 'http://localhost:8080/api/v1/organizations/org-00000001' \ ---header 'X-API-Key: sk-xxxxx' \ ---header 'Content-Type: application/json' \ ---data '{ - "description": "专注于 AI 技术研究与知识管理(更新)", - "require_approval": true, - "searchable": true -}' -``` - -**响应**: 返回更新后的组织信息(结构同 `GET /organizations/:id`)。 - -### DELETE `/organizations/:id` - 删除组织 - -仅 owner 可删除;删除会同时清理成员关系与共享记录。 - -**请求**: - -```curl -curl --location --request DELETE 'http://localhost:8080/api/v1/organizations/org-00000001' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**: - -```json -{ "success": true } -``` - -### POST `/organizations/:id/leave` - 离开组织 - -owner 不能离开自己的组织,需先转让所有权或删除组织。 - -**请求**: - -```curl -curl --location --request POST 'http://localhost:8080/api/v1/organizations/org-00000001/leave' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**: - -```json -{ "success": true, "message": "Left organization successfully" } -``` - -### POST `/organizations/:id/request-upgrade` - 申请角色升级 - -由已加入的成员主动发起,等待管理员审核(出现在 `/organizations/:id/join-requests` 中的 `request_type: "upgrade"`)。 - -**请求体**: - -| 字段 | 类型 | 必填 | 说明 | -| -------------- | ------ | ---- | ---------------------------------------------------- | -| requested_role | string | 是 | 期望角色:`viewer` / `editor` / `admin` | -| message | string | 否 | 申请理由(最多 500 字符) | - -**请求**: - -```curl -curl --location --request POST 'http://localhost:8080/api/v1/organizations/org-00000001/request-upgrade' \ ---header 'X-API-Key: sk-xxxxx' \ ---header 'Content-Type: application/json' \ ---data '{ - "requested_role": "admin", - "message": "需要管理员权限来管理知识库共享" -}' -``` - -**响应**: - -```json -{ - "data": { - "id": "jr-00000002", - "request_type": "upgrade", - "prev_role": "editor", - "requested_role": "admin", - "status": "pending", - "created_at": "2025-08-14T11:00:00+08:00" - }, - "success": true -} -``` - -### POST `/organizations/:id/invite-code` - 重新生成邀请码 - -仅 owner / admin 可调用,会让旧邀请码失效。 - -**请求**: - -```curl -curl --location --request POST 'http://localhost:8080/api/v1/organizations/org-00000001/invite-code' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**: - -```json -{ - "data": { "invite_code": "NEW1CODE" }, - "success": true -} -``` - ---- - -## 成员管理 - -### GET `/organizations/:id/search-users` - 搜索可邀请的用户 - -仅 owner / admin 可调用。匹配用户名或邮箱,自动排除已在该组织内的用户。 - -**查询参数**: - -| 字段 | 类型 | 必填 | 说明 | -| ----- | ------ | ---- | ----------------------------- | -| q | string | 是 | 关键词(用户名或邮箱) | -| limit | int | 否 | 返回数量上限,默认 10 | - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/organizations/org-00000001/search-users?q=zhang&limit=10' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**: - -```json -{ - "data": [ - { - "id": "user-00000002", - "username": "zhangsan", - "email": "zhangsan@example.com", - "avatar": "" - } - ], - "success": true -} -``` - -### POST `/organizations/:id/invite` - 直接邀请用户 - -仅 owner / admin 可调用,被邀请用户直接成为成员(无需审核)。 - -**请求体**: - -| 字段 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | ------------------------------------------- | -| user_id | string | 是 | 被邀请用户的 ID | -| role | string | 是 | 角色:`viewer` / `editor` / `admin` | - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/organizations/org-00000001/invite' \ ---header 'X-API-Key: sk-xxxxx' \ ---header 'Content-Type: application/json' \ ---data '{ - "user_id": "user-00000002", - "role": "editor" -}' -``` - -**响应**: - -```json -{ "success": true, "message": "Member added successfully" } -``` - -### GET `/organizations/:id/members` - 获取成员列表 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/organizations/org-00000001/members' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**: - -```json -{ - "data": { - "members": [ - { - "id": "mem-00000001", - "user_id": "user-00000001", - "username": "admin", - "email": "admin@example.com", - "avatar": "", - "role": "owner", - "tenant_id": 1, - "joined_at": "2025-08-12T10:00:00+08:00" - }, - { - "id": "mem-00000002", - "user_id": "user-00000002", - "username": "zhangsan", - "email": "zhangsan@example.com", - "avatar": "", - "role": "editor", - "tenant_id": 2, - "joined_at": "2025-08-13T09:00:00+08:00" - } - ], - "total": 2 - }, - "success": true -} -``` - -### PUT `/organizations/:id/members/:user_id` - 更新成员角色 - -**路径参数**: - -| 字段 | 类型 | 说明 | -| -------- | ------ | -------------- | -| id | string | 组织 ID | -| user_id | string | 目标成员的用户 ID | - -**请求体**: - -| 字段 | 类型 | 必填 | 说明 | -| ---- | ------ | ---- | ----------------------------------- | -| role | string | 是 | `viewer` / `editor` / `admin` | - -**请求**: - -```curl -curl --location --request PUT 'http://localhost:8080/api/v1/organizations/org-00000001/members/user-00000002' \ ---header 'X-API-Key: sk-xxxxx' \ ---header 'Content-Type: application/json' \ ---data '{ "role": "admin" }' -``` - -**响应**: - -```json -{ "success": true } -``` - -### DELETE `/organizations/:id/members/:user_id` - 移除成员 - -仅 owner / admin 可调用,不能移除 owner。 - -**请求**: - -```curl -curl --location --request DELETE 'http://localhost:8080/api/v1/organizations/org-00000001/members/user-00000002' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**: - -```json -{ "success": true } -``` - ---- - -## 加入请求 - -### GET `/organizations/:id/join-requests` - 获取待审核申请列表 - -仅 owner / admin 可调用。仅返回 `status: pending` 的记录;`request_type` 区分新加入申请(`join`)与升级申请(`upgrade`)。 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/organizations/org-00000001/join-requests' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**: - -```json -{ - "data": { - "requests": [ - { - "id": "jr-00000001", - "user_id": "user-00000003", - "username": "zhangwei", - "email": "zhangwei@example.com", - "message": "希望加入团队参与知识库建设", - "request_type": "join", - "prev_role": "", - "requested_role": "editor", - "status": "pending", - "created_at": "2025-08-14T10:00:00+08:00" - }, - { - "id": "jr-00000002", - "user_id": "user-00000002", - "username": "zhangsan", - "email": "zhangsan@example.com", - "message": "需要管理员权限来管理知识库共享", - "request_type": "upgrade", - "prev_role": "editor", - "requested_role": "admin", - "status": "pending", - "created_at": "2025-08-14T11:00:00+08:00" - } - ], - "total": 2 - }, - "success": true -} -``` - -### PUT `/organizations/:id/join-requests/:request_id/review` - 审核加入申请 - -仅 owner / admin 可调用。 - -**路径参数**: - -| 字段 | 类型 | 说明 | -| ---------- | ------ | -------- | -| id | string | 组织 ID | -| request_id | string | 申请 ID | - -**请求体**: - -| 字段 | 类型 | 必填 | 说明 | -| -------- | ------ | ---- | --------------------------------------------------------------------- | -| approved | bool | 是 | 是否通过 | -| message | string | 否 | 审核留言(最多 500 字符) | -| role | string | 否 | 通过时强制分配的角色(缺省按申请者请求的角色),仅 `viewer/editor/admin` | - -**请求**: - -```curl -curl --location --request PUT 'http://localhost:8080/api/v1/organizations/org-00000001/join-requests/jr-00000001/review' \ ---header 'X-API-Key: sk-xxxxx' \ ---header 'Content-Type: application/json' \ ---data '{ - "approved": true, - "message": "欢迎加入", - "role": "editor" -}' -``` - -**响应**: - -```json -{ "success": true, "message": "Review completed" } -``` - ---- - -## 知识库共享 - -### POST `/knowledge-bases/:id/shares` - 共享知识库到组织 - -**路径参数**: `id` = 知识库 ID - -**请求体**: - -| 字段 | 类型 | 必填 | 说明 | -| ---------------- | ------ | ---- | ------------------------------- | -| organization_id | string | 是 | 目标组织 ID | -| permission | string | 是 | 共享权限:`viewer` / `editor` | - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/shares' \ ---header 'X-API-Key: sk-xxxxx' \ ---header 'Content-Type: application/json' \ ---data '{ - "organization_id": "org-00000001", - "permission": "viewer" -}' -``` - -**响应**(`201 Created`): - -```json -{ - "data": { - "id": "kbs-00000001", - "knowledge_base_id": "kb-00000001", - "organization_id": "org-00000001", - "shared_by_user_id": "user-00000001", - "source_tenant_id": 1, - "permission": "viewer", - "created_at": "2025-08-15T10:00:00+08:00" - }, - "success": true -} -``` - -### GET `/knowledge-bases/:id/shares` - 获取知识库共享列表 - -返回该知识库被共享到的所有组织。 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/shares' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**: - -```json -{ - "data": { - "shares": [ - { - "id": "kbs-00000001", - "knowledge_base_id": "kb-00000001", - "knowledge_base_name": "技术文档库", - "knowledge_base_type": "document", - "knowledge_count": 12, - "chunk_count": 0, - "organization_id": "org-00000001", - "organization_name": "AI 技术团队", - "shared_by_user_id": "user-00000001", - "shared_by_username": "admin", - "source_tenant_id": 1, - "permission": "viewer", - "my_role_in_org": "owner", - "my_permission": "viewer", - "created_at": "2025-08-15T10:00:00+08:00" - } - ], - "total": 1 - }, - "success": true -} -``` - -### PUT `/knowledge-bases/:id/shares/:share_id` - 更新共享权限 - -**路径参数**: - -| 字段 | 类型 | 说明 | -| -------- | ------ | -------------- | -| id | string | 知识库 ID | -| share_id | string | 共享记录 ID | - -**请求体**: - -| 字段 | 类型 | 必填 | 说明 | -| ---------- | ------ | ---- | ----------------------------- | -| permission | string | 是 | 新权限:`viewer` / `editor` | - -**请求**: - -```curl -curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/shares/kbs-00000001' \ ---header 'X-API-Key: sk-xxxxx' \ ---header 'Content-Type: application/json' \ ---data '{ "permission": "editor" }' -``` - -**响应**: - -```json -{ "success": true } -``` - -### DELETE `/knowledge-bases/:id/shares/:share_id` - 取消知识库共享 - -**请求**: - -```curl -curl --location --request DELETE 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/shares/kbs-00000001' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**: - -```json -{ "success": true } -``` - -### GET `/organizations/:id/shares` - 获取组织下被共享进来的知识库 - -仅本组织成员可查看。`my_permission = min(permission, my_role_in_org)`,即当前用户的有效权限。 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/organizations/org-00000001/shares' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**: 结构同 `GET /knowledge-bases/:id/shares`。 - -### GET `/organizations/:id/shared-knowledge-bases` - 组织内知识库空间视图 - -供"切换到某个空间后"的知识库列表页使用。返回该组织中所有当前用户可见的知识库,包含: - -1. 通过 `POST /knowledge-bases/:id/shares` 直接共享进来的知识库 -2. 通过共享智能体(`agents/:id/shares`)携带进来的知识库(只读,`source_from_agent` 字段标识来源) -3. 当前用户自己共享出去的知识库(`is_mine: true`) - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/organizations/org-00000001/shared-knowledge-bases' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**: - -```json -{ - "data": [ - { - "knowledge_base": { - "id": "kb-00000001", - "name": "技术文档库", - "type": "document" - }, - "share_id": "kbs-00000001", - "organization_id": "org-00000001", - "org_name": "AI 技术团队", - "permission": "viewer", - "source_tenant_id": 1, - "shared_at": "2025-08-15T10:00:00+08:00", - "is_mine": false, - "source_from_agent": { - "agent_id": "agent-00000005", - "agent_name": "智能客服助手", - "kb_selection_mode": "selected" - } - } - ], - "total": 1, - "success": true -} -``` - -`source_from_agent` 仅在该 KB 是通过共享智能体引入时出现;直接共享的 KB 不含该字段。 - ---- - -## 智能体共享 - -### POST `/agents/:id/shares` - 共享智能体到组织 - -仅当前用户在目标组织中具有 editor 或 admin 角色时允许;智能体必须已完成配置(必填的对话模型、若启用了 knowledge_search 工具需配置重排模型等)。 - -**路径参数**: `id` = 智能体 ID - -**请求体**: - -| 字段 | 类型 | 必填 | 说明 | -| ---------------- | ------ | ---- | ------------------------------- | -| organization_id | string | 是 | 目标组织 ID | -| permission | string | 是 | 共享权限:`viewer` / `editor` | - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/agents/agent-00000001/shares' \ ---header 'X-API-Key: sk-xxxxx' \ ---header 'Content-Type: application/json' \ ---data '{ - "organization_id": "org-00000001", - "permission": "viewer" -}' -``` - -**响应**(`201 Created`): - -```json -{ - "data": { - "id": "as-00000001", - "agent_id": "agent-00000001", - "organization_id": "org-00000001", - "shared_by_user_id": "user-00000001", - "source_tenant_id": 1, - "permission": "viewer", - "created_at": "2025-08-15T11:00:00+08:00" - }, - "success": true -} -``` - -### GET `/agents/:id/shares` - 获取智能体共享列表 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/agents/agent-00000001/shares' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**: - -```json -{ - "data": { - "shares": [ - { - "id": "as-00000001", - "agent_id": "agent-00000001", - "organization_id": "org-00000001", - "organization_name": "AI 技术团队", - "shared_by_user_id": "user-00000001", - "source_tenant_id": 1, - "permission": "viewer", - "created_at": "2025-08-15T11:00:00+08:00" - } - ], - "total": 1 - }, - "success": true -} -``` - -### DELETE `/agents/:id/shares/:share_id` - 取消智能体共享 - -只有共享者本人或拥有相应权限的管理员可以取消。 - -**请求**: - -```curl -curl --location --request DELETE 'http://localhost:8080/api/v1/agents/agent-00000001/shares/as-00000001' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**: - -```json -{ "success": true, "message": "Share removed successfully" } -``` - -### GET `/organizations/:id/agent-shares` - 获取组织下被共享进来的智能体 - -仅本组织成员可查看。返回结构在 `AgentShareResponse` 基础上额外补充 `my_role_in_org` / `my_permission`,并附带智能体的能力范围摘要(`scope_kb` / `scope_web_search` / `scope_mcp` 等)。 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/organizations/org-00000001/agent-shares' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**: - -```json -{ - "data": { - "shares": [ - { - "id": "as-00000001", - "agent_id": "agent-00000001", - "agent_name": "智能客服助手", - "agent_avatar": "🤖", - "organization_id": "org-00000001", - "organization_name": "AI 技术团队", - "shared_by_user_id": "user-00000001", - "shared_by_username": "admin", - "source_tenant_id": 1, - "permission": "viewer", - "my_role_in_org": "editor", - "my_permission": "viewer", - "created_at": "2025-08-15T11:00:00+08:00", - "scope_kb": "selected", - "scope_kb_count": 2, - "scope_web_search": true, - "scope_mcp": "none" - } - ], - "total": 1 - }, - "success": true -} -``` - -### GET `/organizations/:id/shared-agents` - 组织内智能体空间视图 - -供"切换到某个空间后"的智能体列表页使用。返回该组织中所有当前用户可见的智能体,包含他人共享与本人共享(`is_mine: true`)。 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/organizations/org-00000001/shared-agents' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**: - -```json -{ - "data": [ - { - "agent": { - "id": "agent-00000001", - "name": "智能客服助手" - }, - "share_id": "as-00000001", - "organization_id": "org-00000001", - "org_name": "AI 技术团队", - "permission": "viewer", - "source_tenant_id": 1, - "shared_at": "2025-08-15T11:00:00+08:00", - "shared_by_user_id": "user-00000001", - "shared_by_username": "admin", - "disabled_by_me": false, - "is_mine": false - } - ], - "total": 1, - "success": true -} -``` - ---- - -## 我的共享视图 - -### GET `/shared-knowledge-bases` - 获取共享给我的知识库(跨组织) - -返回当前用户通过所有组织(不限制 `:id`)共享获得的知识库列表,供"全部知识库"视图使用。 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/shared-knowledge-bases' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**: - -```json -{ - "data": [ - { - "knowledge_base": { - "id": "kb-00000001", - "name": "技术文档库" - }, - "share_id": "kbs-00000001", - "organization_id": "org-00000001", - "org_name": "AI 技术团队", - "permission": "viewer", - "source_tenant_id": 1, - "shared_at": "2025-08-15T10:00:00+08:00" - } - ], - "total": 1, - "success": true -} -``` - -### GET `/shared-agents` - 获取共享给我的智能体(跨组织) - -返回当前用户通过所有组织共享获得的智能体列表,供"全部智能体"视图使用。`disabled_by_me: true` 表示当前空间已在对话下拉中隐藏该智能体。 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/shared-agents' \ ---header 'X-API-Key: sk-xxxxx' -``` - -**响应**: - -```json -{ - "data": [ - { - "agent": { - "id": "agent-00000001", - "name": "智能客服助手" - }, - "share_id": "as-00000001", - "organization_id": "org-00000001", - "org_name": "AI 技术团队", - "permission": "viewer", - "source_tenant_id": 1, - "shared_at": "2025-08-15T11:00:00+08:00", - "shared_by_user_id": "user-00000001", - "shared_by_username": "admin", - "disabled_by_me": false - } - ], - "total": 1, - "success": true -} -``` - diff --git a/docs/api/session.md b/docs/api/session.md deleted file mode 100644 index c23dc6e5..00000000 --- a/docs/api/session.md +++ /dev/null @@ -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 ' -``` - -**响应**: - -```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= -Upgrade: websocket -``` - -## POST `/sessions/:session_id/sandbox/desktop/activity` - 上报桌面活动 - -浏览器在键鼠事件时 POST。这是 RFB parser 遇到未知 opcode 时的降级续命;parser 健康时服务端忽略该请求,避免仅靠轮询延长沙箱 TTL。 diff --git a/docs/api/skill.md b/docs/api/skill.md deleted file mode 100644 index 53fbdefd..00000000 --- a/docs/api/skill.md +++ /dev/null @@ -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 ' -``` - -**响应**: - -```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 ' \ ---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 ' \ ---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 ' \ ---header 'Content-Type: application/json' \ ---data '{"sandbox_config_id":"cfg-1","name":"HTTP_PROXY","value":"http://127.0.0.1:7890"}' -``` diff --git a/docs/api/storage-backend.md b/docs/api/storage-backend.md deleted file mode 100644 index 29657e21..00000000 --- a/docs/api/storage-backend.md +++ /dev/null @@ -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 | 同名存储实例已存在 | diff --git a/docs/api/system.md b/docs/api/system.md deleted file mode 100644 index 1efe0b05..00000000 --- a/docs/api/system.md +++ /dev/null @@ -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 ' \ ---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 -} -``` - - diff --git a/docs/api/tag.md b/docs/api/tag.md deleted file mode 100644 index 53f84bc2..00000000 --- a/docs/api/tag.md +++ /dev/null @@ -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 -} -``` diff --git a/docs/api/tenant.md b/docs/api/tenant.md deleted file mode 100644 index 0a72af54..00000000 --- a/docs/api/tenant.md +++ /dev/null @@ -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: ' \ - -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 ' -``` - -**响应**: - -```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 ' \ ---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。 diff --git a/docs/api/vector-store.md b/docs/api/vector-store.md deleted file mode 100644 index c15f980f..00000000 --- a/docs/api/vector-store.md +++ /dev/null @@ -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)),列于此处仅为完整覆盖与向量存储相关的所有错误码。 diff --git a/docs/api/web-search.md b/docs/api/web-search.md deleted file mode 100644 index 6382d3ff..00000000 --- a/docs/api/web-search.md +++ /dev/null @@ -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`。 diff --git a/docs/browser-skill-integration.md b/docs/browser-skill-integration.md deleted file mode 100644 index 5231f31d..00000000 --- a/docs/browser-skill-integration.md +++ /dev/null @@ -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 中手动删除。 diff --git a/docs/browser-skill-production.md b/docs/browser-skill-production.md deleted file mode 100644 index 59e2d3c7..00000000 --- a/docs/browser-skill-production.md +++ /dev/null @@ -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= -``` - -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 延迟/失败率和重连耗时。当前测试证明功能和故障隔离,不代表已经取得某个用户规模的容量保证。 diff --git a/docs/chat-steering.md b/docs/chat-steering.md deleted file mode 100644 index f1307a78..00000000 --- a/docs/chat-steering.md +++ /dev/null @@ -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) diff --git a/docs/client-integration-upgrade-notes.md b/docs/client-integration-upgrade-notes.md deleted file mode 100644 index c39c2a1b..00000000 --- a/docs/client-integration-upgrade-notes.md +++ /dev/null @@ -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. diff --git a/docs/cloud-image/README.md b/docs/cloud-image/README.md deleted file mode 100644 index fb3f709c..00000000 --- a/docs/cloud-image/README.md +++ /dev/null @@ -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 | _欢迎贡献_ | ⏳ | - -> 各平台文档结构尽量保持一致:实例规格建议 → 制作镜像操作 → 共享/公开方式 → 该平台独有的注意事项。 diff --git a/docs/cloud-image/tencent-lighthouse.md b/docs/cloud-image/tencent-lighthouse.md deleted file mode 100644 index 8c921655..00000000 --- a/docs/cloud-image/tencent-lighthouse.md +++ /dev/null @@ -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 单独配置,不要把证书烤进镜像 diff --git a/docs/code-slimming-audit.md b/docs/code-slimming-audit.md deleted file mode 100644 index 033c42d1..00000000 --- a/docs/code-slimming-audit.md +++ /dev/null @@ -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 的重复身份校验,沿现有授权边界确定共享范围。涉及聊天、任务重试、权限或共享状态的改动应单独成批,以可验证的行为等价为边界。 diff --git a/docs/dev/opensearch-integration-test.md b/docs/dev/opensearch-integration-test.md deleted file mode 100644 index 8b31ac81..00000000 --- a/docs/dev/opensearch-integration-test.md +++ /dev/null @@ -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__768` + alias, plus `weknora__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). diff --git a/docs/embed-secure-mode.md b/docs/embed-secure-mode.md deleted file mode 100644 index 9272feb4..00000000 --- a/docs/embed-secure-mode.md +++ /dev/null @@ -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": "", "expiresIn": 1800 }` - -**调 exchange 的约定**: - -```http -POST https:///api/v1/embed//exchange -Authorization: Embed <发布 Token em_…> -Origin: https://<你的业务站点> ← 须与渠道白名单一致,否则 403 -``` - -> 服务端 `fetch` 默认不带 `Origin`,需要**手动设置**与白名单匹配的 `Origin` 头。 - -### 第 3 步:粘贴安全模式 Widget 代码 - -把 `data-token-endpoint` 改成上一步的真实 URL。完整示例在管理端「安全模式」Tab 可复制。 - -## 服务端示例 - -以下 ``、`` 替换为实际值;发布 Token 放环境变量 `WEKNORA_PUBLISH_TOKEN`,**不要**写进前端。 - -### Node.js(Express) - -```javascript -const WEKNORA_BASE = 'https://'; -const 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:///api/v1/embed//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` diff --git a/docs/embed-subdomain.md b/docs/embed-subdomain.md deleted file mode 100644 index e3d346ef..00000000 --- a/docs/embed-subdomain.md +++ /dev/null @@ -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 -┌─────────────────┐ ┌──────────────────────────┐ -│