docs: sync website-docs, homepage and changelog for v0.8.2 (#3632)

* docs: sync website-docs with changes since v0.8.0

Audit every change between v0.8.0 and the v0.8.2 release against the
documentation site, adding what users and operators need and correcting
statements that no longer match the code.

- Add local browser (BrowserSkill), built-in MCP Server endpoints, the
  toolbox, conversation steer/fork/rewind and reasoning effort, the
  artifacts library, sandbox terminal and desktop, the Lite host sandbox,
  the rebuilt model catalog (including a protocol-compat field reference),
  Confluence and DingTalk Docs sources, Bocha/Serply search, per-channel IM
  locale, whitelist-only outbound, admin user creation, new configuration
  variables and migrations 000091-000110.
- Fix wrong API examples and parameters (model type values, knowledge
  search params, FAQ match_count cap, Notion credentials), tenant deletion
  semantics, default timeouts, parser engine claims, removed tables and
  commands, stale navigation paths, and route locations after the router
  split into routes_*.go.
- Add screenshots for the new pages and refresh outdated ones.

* fix(frontend): link the protocol-compat field to its documentation

The model editor told users to read catalog/compat.go on the backend, a
path that no longer exists after the model catalog refactor. The hint now
says when the override is needed and links to the field reference in
website-docs/03-features/06-models.md; the config examples and the API
type comment point to the same place.

* feat(website): showcase v0.8.2 on the homepage

- Add a v0.8.2 section for the local browser (BrowserSkill), the built-in
  MCP Server and conversation control, and turn the v0.8.0 release block
  into a standing skills & sandbox topic with the sandbox desktop and
  terminal.
- Replace the three-up galleries with a feature list beside one large
  screenshot: every item's text stays visible, clicking an item or one of
  its views switches the image with a cross-fade, and the list plays itself
  while on screen until the visitor picks something.
- Add Confluence, DingTalk, BrowserSkill and more model vendors to the
  integrations, bump the header badge to v0.8.2 and link the changelog.
- check-site reports missing docs screenshots as pending instead of
  failing, since the Screenshot component renders a placeholder for them.

* docs(changelog): add v0.8.2 release notes

* docs(website): add per-version release notes pages

Add a "版本发布" docs section with one page per release, starting with
v0.8.2 and a backfilled v0.8.0. Each page walks through the highlights
with the existing product screenshots, the other improvements and fixes,
and an upgrade checklist with the actions each breaking change needs.

The sidebar orders these pages by version, newest first; the docs header
gains a 版本 entry, and the homepage's v0.8.2 section now links to the
release notes page instead of the raw CHANGELOG.

* feat(website): let the site image listen on a configurable port

The Docker image hard-coded `listen 80`, so running it with host
networking or on a platform that assigns the container port required
editing the Nginx config and rebuilding. The image now renders its
config from the official nginx template directory at startup and reads
the listen port from `PORT` (default 80); deploy/nginx.conf stays a plain
config for static deployments.

test-docker starts a second container with PORT=8080 and checks the
rendered config and that the site answers on that port; the README
documents the variable.

* fix(website): namespace the nginx listen port variable

* fix(website): support bash-wrapped container startup

* fix(website): align nginx startup with frontend entrypoint

* fix(website): pin nginx runtime for older host compatibility

* fix(website): bake the configured nginx port into the image
main
lyingbug 2026-09-24 11:26:34 +08:00 committed by GitHub
parent 608027179f
commit be46eabaf2
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
127 changed files with 2699 additions and 1006 deletions

View File

@ -2,13 +2,79 @@
All notable changes to this project will be documented in this file.
## [Unreleased]
## [0.8.2] - 2026-09-23
### New Features
- **NEW**: **Local Browser (BrowserSkill)** — agents in smart-reasoning chats can drive the user's own Chrome or Edge through the open-source [BrowserSkill](https://github.com/Tencent/BrowserSkill) extension (v0.3.1+). Pair once from Toolbox → Browser Connection, turn on "Local Browser" in the composer, and the new `local_browser` tool opens pages, clicks, fills forms and reads content in a dedicated task window. The chat shows a live (picture-in-picture) task preview with pause / resume / end controls; logins and CAPTCHAs are handed to the user through `request_help`, and interrupted tasks can be resumed. The app image bundles the `bsk` daemon, the matching extension ZIP and licenses; multi-replica deployments set `BROWSERSKILL_INTERNAL_URL` / `BROWSERSKILL_CLUSTER_SECRET` (#3180, #3193, #3206, #3563).
- **NEW**: **Built-in MCP Server** — each workspace can publish MCP endpoints at `/mcp/<endpoint_id>` (Streamable HTTP) from Settings → Integrations → MCP Server, with its own token, knowledge-base scope, per-minute rate limit (default 60) and tool groups: retrieval & reading, `ask` (runs the endpoint's default agent), Wiki, and write tools (off by default). The page generates `mcpServers` config for Cursor / VS Code / Claude Desktop and a one-line Claude Code command; tokens can be rotated. Endpoints are managed through `/api/v1/mcp-endpoints` (API key capability `manage_channels`). The Python `mcp-server/` is now deprecated (#3371).
- **NEW**: **Toolbox** — skills, MCP services and the browser connection move from Settings into a sidebar Toolbox (old settings links redirect); the sidebar shows the browser connection status.
- **NEW**: **Conversation control** — append requirements to a running agent turn (queued until the step ends, or injected immediately) (#3123); fork a conversation from any earlier question (#3304); rewind in place, resetting the sandbox workspace to the matching checkpoint (#3469); choose the reasoning effort per session.
- **NEW**: **Artifacts library** — a sidebar "Artifacts" page lists every generated file across conversations with type filters, search, date grouping and version history, backed by a `message_artifacts` table; generated files can be deleted (#3384, #3447).
- **NEW**: **Sandbox terminal & graphical desktop** — the sandbox panel beside the chat gains an interactive terminal (Cube / E2B) that reconnects to running shells (#3110, #3128) and a browser-based XFCE desktop for sandboxes built from a desktop template (`desktop_enabled`) (#3245). Shell and skill-install commands stream their output live; idle terminal/desktop sessions disconnect after `terminal_idle_disconnect_sec` (default 900 s).
- **NEW**: **Lite host sandbox & project folders** — the desktop app (macOS) runs sessions without a pinned sandbox inside an OS sandbox (Seatbelt): no network, writes limited to the chosen project folder, `.git` read-only, credential directories blocked. New chats can bind a host project directory or use a dated temporary workspace (#3472, #3549, #3554).
- **NEW**: **Model catalog** — model integration is rebuilt on protocol, vendor and catalog layers (#3470, #3589): 27 built-in vendors, a generated catalog that fills context window, max output, reasoning levels and vision support, a "resolved call" panel in the model editor, per-model protocol override and protocol-compat JSON, `GET/POST /models/catalog/resolve`, and a deployment overlay file (`config/models.json`, `MODELS_CONFIG`). Speech-to-text now covers every vendor that documents it (#3503).
- **NEW**: **Confluence & DingTalk Docs data sources** — Confluence Cloud and Server/Data Center spaces sync published pages incrementally with deletion protection (#3287); DingTalk Docs sync with localized setup (#2313). IMA sync traverses subfolders.
- **NEW**: **Bocha and Serply web search** providers (#3036); `country` / `freshness` filters work with Brave and Serply.
- **NEW**: **Japanese UI** (`ja-JP`), selectable at runtime or via `DEFAULT_LOCALE` (#3080).
- **NEW**: **Per-channel IM reply language** — each IM channel can set its reply locale; unset channels follow `WEKNORA_LANGUAGE` (#3455).
- **NEW**: **Knowledge base workflow** — batch download of original files as a ZIP (#3300); configurable sorting for document and resource lists (#3318); documents that stop making progress are flagged as queued or stalled with a `TASK_STALLED` code (#3557); per-upload option to skip summary generation; knowledge base descriptions generated from document profiles (#3370); an upload panel with overall progress, cancel and retry (#3399); FAQ list filter by enabled status (#3157); activity records show the API key name (#3405).
- **NEW**: **Whitelist-only outbound mode** — `SSRF_DNS_WHITELIST_ONLY=true` refuses any host outside `SSRF_WHITELIST` before DNS resolution, closing DNS-based exfiltration from offline deployments (#3393).
- **NEW**: **Admin user creation UI** — system administrators create accounts from Settings with a one-time password and a copyable account summary (#3034, #3039).
- **NEW**: **CLI setup page** under Integrations with a three-step guide (#3081).
### Improvements
- **IMPROVED**: **Agent knowledge-retrieval tools consolidated** — `knowledge_search` and `grep_chunks` are replaced by a single `search_knowledge` tool (`query`, `mode` = `hybrid` | `semantic` | `keyword`, optional `knowledge_base_ids`, `limit` default 10 / max 30); keyword mode is served by the keyword index (BM25 / engine keyword retrieval) instead of an unindexed regular-expression scan of the chunks table. `list_knowledge_chunks`, `get_document_info` and `wiki_read_source_doc` are replaced by `read_document` (`id` = a `dN` document or `cN` chunk handle, `offset` / `limit` paging, in-document `query` with optional `regex`, `context` neighbours around a chunk), which always returns the document metadata header together with the chunks. New `list_documents` (`knowledge_base_id`, `keyword`, `page`, `page_size`) pages through one knowledge base. `wiki_search` takes a single `query` (a case-insensitive regular expression, as before) plus optional `regex`, `knowledge_base_ids` and `limit`; the old `queries` / `knowledge_base_id` parameters are still accepted. `query_knowledge_graph` is only offered when a graph-enabled knowledge base is in scope. New agents default to `search_knowledge`, `read_document`, `list_documents` and `search_conversations`. The built-in MCP server keeps its tool names: `search_knowledge` gains `mode` and `limit`, `grep_chunks` keeps its regular-expression contract on index-backed retrieval and gains `limit`, `read_document` gains `query`, and `wiki_search` gains `regex`.
- **IMPROVED**: **Retrieval tool compatibility fixes** — `search_knowledge` no longer refuses a mode that some bases cannot serve: FAQ and vector-only bases answer `keyword` requests semantically and keyword-only bases answer `semantic` requests by keyword, with `requested_mode` / `mode_fallbacks` in the result and `<mode_fallback>` in the model rendering, which now shows the mode actually used instead of always `semantic`. `read_document` and `list_documents` are offered on wiki-only scopes (chunks are always stored) without widening RAG agents' derived KB filter; `list_documents` applies the @file / @tag scope before paging so totals and pages only count readable documents; chunk context is resolved by chunk index so parent, summary and image chunks no longer shift the neighbourhood. `wiki_search` (agent and MCP) keeps its regular-expression semantics by default and only falls back to a literal match for text that is not a valid expression; MCP `grep_chunks` keeps grep semantics by fetching candidates with the pattern's literal terms and verifying each chunk against the pattern.
- **IMPROVED**: **Backward-compatible tool aliasing** — old tool names stored in agent configurations, presets and API calls are mapped to their successors at run time (`legacyToolSuccessors` / `NormalizeAllowedTools`); no data migration is needed, and stored chat history that references the old tool names still renders.
- **IMPROVED**: **Agent context** — history is sized by the model's context window with calibrated token estimates (#3413); compaction checkpoints persist across turns (#3407); `search_knowledge` reranks with document titles and allows a keyword retry after a rerank rejection; `read_document` queries are keyword-based and bounded.
- **IMPROVED**: **MCP client** — tool catalogs are persisted per service and caller with a guided two-step setup and AI-drafted usage notes (#3118); tools can be enabled or disabled individually (#2989); agents discover and call MCP tools on demand through `discover_mcp_tools` / `call_mcp_tool` instead of loading every tool; `advanced_config.timeout` extends the call window; multi-line SSE events are assembled correctly.
- **IMPROVED**: **Skills** — outdated sandbox skills upgrade without rolling back the catalog or taking the skill offline (#3406); runtime prerequisites are verified after install and installs accept extra guidance; manifests with a UTF-8 BOM load.
- **IMPROVED**: **Chat UX** — rebuilt Markdown editor for saving answers to a knowledge base (#3467); in-progress status and API-session owner badges in the sidebar; full dates on older message timestamps (#3576); truncated answers are marked instead of silently cut; stored streams replay one segment at a time; the chat stream recovers from an expired access token (#3028).
- **IMPROVED**: **Wiki** — whole-page rewrites continue when cut by the completion budget and are refused if still incomplete (#3582); same-title items reuse the existing page across types (#3547); cited chunks include image captions (#3292); ambiguous single-Han auto-links are skipped (#2860); taxonomy embeddings are batched.
- **IMPROVED**: **Retrieval & graph** — Milvus supports multilingual BM25 (#3235); keyword-only BM25 scores are bounded before rerank (#3343); Neo4j node search caps seeds and rows (#3550); entity extraction gets a larger output budget (#2859) and uses OCR text of scanned pages (#3092).
- **IMPROVED**: **Parsing** — PaddleOCR-VL request timeout is configurable via `WEKNORA_PADDLEOCR_VL_TIMEOUT` (#3537); timed-out converter process groups are killed (#2990); PDFs stay on the builtin parser even when anydoc is linked; inline HTML tables no longer produce oversized chunks (#3404); the OCR prompt no longer includes the knowledge base's image-caption instructions (#3291).
- **IMPROVED**: **Performance** — faster chunk ingestion and batch updates (#3369); fewer redundant sandbox remote calls.
- **IMPROVED**: **Storage** — OBS uses virtual-hosted addressing (#3273); object-storage transfers may exceed 30 seconds (#3368); the KS3 client keeps the SSRF redirect policy.
- **IMPROVED**: **Frontend** — style consistency pass with shared shells, tokens and unified confirmations (#3376); list title icons and resource cards refined; embedded pages enforce host origin allowlists.
### Bug Fixes
- **FIXED**: Documents no longer get stranded in `processing` or `deleting`: pipeline errors and panics fail the row, never-run stages are not reported as failed, stranded Wiki queues release their documents, and housekeeping recovers stuck deletions (#3445, #3367).
- **FIXED**: Cross-workspace access paths in shared spaces are closed (#3408, #3416); path traversal in local prefixes, task IDs and Wiki sort is rejected.
- **FIXED**: Wiki tasks of soft-deleted tenants stop issuing model requests (#3602); deleting a knowledge base cleans up its Wiki data (#3109).
- **FIXED**: The agent ends the turn when the completion cap truncates an answer (#3449); failed tool executions are reported as `tool_result` rather than `error`; MCP answers no longer cite unrelated knowledge-base sources (#3144); `@Skill` / `@MCP` pickers list only the resources of the agent that will run (#3475).
- **FIXED**: Updating an agent's config no longer erases its avatar, and driver errors stay server-side (#3230).
- **FIXED**: Remote embedders, rerankers and four vendor chat request shapes now match the vendors' documentation (#3484, #3488, #3489, #3500, #3513).
- **FIXED**: Queue claims order by failure count so retries cannot starve new work (#3444).
- **FIXED**: Invalid QA queries are rejected before the session lookup (#3477); suggested follow-ups no longer echo the current question (#2582); images from organization-shared knowledge bases load through the message file proxy (#3069).
- **FIXED**: Long-term memory ranks recalled items by the query and preserves extraction progress (#3224).
- **FIXED**: IM replies finalize when agent QA returns; Yunzhijia recovers stale WebSocket connections; Feishu keeps images in post messages and keeps streams alive during long answers; clearing an IM channel's knowledge base is persisted.
- **FIXED**: Multipart upload temp files are cleaned up; XMind files are accepted before parser discovery; the upload timeout scales with payload size; a non-ASCII base64 image no longer fails the whole parse.
### Breaking Changes
- **BREAKING**: **DingTalk channels support Stream mode only.** Migration `000096` switches existing webhook channels to `websocket`; enable Stream for the app in the DingTalk developer console.
- **BREAKING**: **Sandbox commands run as `root` by default** (previously uid 1000) (#3067). Each session owns its sandbox, so isolation stays at the container boundary.
- **BREAKING**: MCP service updates that include `usage_instructions` must send non-blank text of at most 16,000 characters; omitting the field keeps the existing instructions.
- **BREAKING**: `.env.example` no longer ships default `JWT_SECRET` / `SYSTEM_AES_KEY` values and adds `SYSTEM_SIGNING_KEY`. New deployments must generate them; **existing deployments must keep their current `SYSTEM_AES_KEY`**, or stored credentials cannot be decrypted. An unset `JWT_SECRET` falls back to a random per-process value, so logins do not survive restarts and replicas must share it.
- **BREAKING**: Organization invites resolve an exact workspace ID (`/organizations/{id}/search-tenants`); searching workspaces by name is removed.
- **BREAKING**: Go SDK `UpdateAgentRequest.Avatar` is now `*string`: `nil` keeps the avatar, an empty string clears it.
### Infrastructure & Build
- **BUILD**: Migrations `000091`–`000110` (MCP tool toggles and catalogs, browser authorization, memory consistency and vector search, DingTalk Stream-only, session fork and snapshot leases, ParadeDB `pg_search` 0.22.6, chunk index diet, knowledge profiles, MCP endpoints, message artifacts, skill served version, context checkpoints, message index, session sandbox tenant and host workspace dir, IM channel locale); SQLite migrations `000013`–`000030`. Migration `000106` builds an index `CONCURRENTLY`; if interrupted, drop the invalid index and rerun.
- **BUILD**: ParadeDB image upgraded to run on CPUs without AVX2; the MinIO image is pulled from `quay.io`.
- **BUILD**: The frontend image builds in a multi-stage Dockerfile without host npm (#3074); the app image bundles BrowserSkill (`scripts/build_browserskill.sh`, pinned by `scripts/browserskill-release.json`); sandbox image targets `sandbox`, `cube`, `desktop` and `desktop-cube`.
- **BUILD**: Model catalog generation and checks (`make model-catalog-generate`, `model-catalog-check`, `model-catalog-diff`); per-vendor golden request tests.
- **BUILD**: The GPL document converter and vendored archives are removed; third-party license sources are bundled; Helm exposes `global.maxFileSizeMB`.
### Documentation
- **DOC**: The official site and documentation are unified under `website-docs/` — a product homepage plus the docs, built and deployed together as static files or a Docker image (#3297). Valid content from the old `docs/` is migrated and the outdated pages are removed (#3580).
- **DOC**: Documentation synced for v0.8.2: local browser, built-in MCP Server, toolbox, conversation control, artifacts, sandbox terminal/desktop and Lite host sandbox, model catalog and protocol-compat fields, Confluence / DingTalk sources, new configuration variables, and migrations through `000110`.
- **DOC**: Removed unsupported Homebrew installation guidance and the claim that MySQL is a supported `DB_DRIVER`.
## [0.8.0] - 2026-09-03

View File

@ -98,7 +98,8 @@ builtin_models: []
# context_window: 200000 # optional; omit to use the 200K default
# # Optional catalog overrides for chat models. `api` forces the wire
# # protocol; `compat` is the flat protocol object documented in
# # internal/models/catalog/compat.go; `thinking_levels` maps the
# # website-docs/03-features/06-models.md (协议兼容覆盖 compat JSON);
# # `thinking_levels` maps the
# # off/auto/minimal/low/medium/high/xhigh/max ladder to vendor values.
# # spec:
# # api: openai-completions

View File

@ -11,7 +11,7 @@
"'icon' is an inline <svg ...> string or an .svg path under this file's own",
"directory — no absolute paths, no escaping it, 256 KB max: icons are served",
"as a data: URI to everyone who can open the model pages.",
"Per-model 'compat' keys depend on the protocol; see internal/models/catalog/compat.go."
"Per-model 'compat' keys depend on the protocol; see website-docs/03-features/06-models.md (协议兼容覆盖 compat JSON)."
],
"providers": {
"openai": {

View File

@ -33,8 +33,8 @@ export interface ModelCapabilities {
}
// Per-row override of a catalog entry. Mirrors internal/types.ModelSpecOverride.
// compat is the flat, protocol-specific object documented in
// internal/models/catalog/compat.go (free-form JSON).
// compat is the flat, protocol-specific object defined in
// internal/models/api/*_settings.go (free-form JSON).
export interface ModelSpecOverride {
api?: string;
reasoning?: boolean;

View File

@ -589,7 +589,13 @@
:placeholder="$t('model.editor.advanced.compat.placeholder')" class="compat-textarea"
:status="specCompatError ? 'error' : undefined" />
<p v-if="specCompatError" class="form-desc form-desc--error">{{ $t('model.editor.advanced.compat.invalid') }}: {{ specCompatError }}</p>
<p v-else class="form-desc">{{ $t('model.editor.advanced.compat.desc') }}</p>
<p v-else class="form-desc">
{{ $t('model.editor.advanced.compat.desc') }}
<a :href="COMPAT_DOC_URL" target="_blank" rel="noopener noreferrer" class="compat-doc-link">
{{ $t('model.editor.advanced.compat.docLink') }}
<t-icon name="jump" size="12px" />
</a>
</p>
</div>
</template>
</template>
@ -696,6 +702,10 @@ const PROTOCOL_OPTIONS = [
'google-generative-ai',
] as const
/** Field reference for parameters.spec.compat, per protocol and model type. */
const COMPAT_DOC_URL =
'https://github.com/Tencent/WeKnora/blob/main/website-docs/03-features/06-models.md#协议兼容覆盖-compat-json'
/** Legacy thinking_control values still honoured by catalog.Resolve. */
const LEGACY_THINKING_CONTROL_VALUES = ['none', 'enable_thinking', 'thinking_type', 'chat_template_kwargs'] as const
@ -2176,17 +2186,18 @@ const handleCancel = () => {
<style lang="less" scoped>
.provider-doc-link {
margin-top: 6px;
}
a {
display: inline-flex;
align-items: center;
gap: 3px;
color: var(--td-text-color-link);
text-decoration: none;
.provider-doc-link a,
.compat-doc-link {
display: inline-flex;
align-items: center;
gap: 3px;
color: var(--td-text-color-link);
text-decoration: none;
&:hover {
text-decoration: underline;
}
&:hover {
text-decoration: underline;
}
}

View File

@ -4736,7 +4736,8 @@ export default {
compat: {
label: 'Protocol compat override (JSON)',
placeholder: "{'{'} \"max_tokens_field\": \"max_tokens\" {'}'}",
desc: 'Compat switches merged over the catalog defaults for the resolved protocol; see catalog/compat.go on the backend. Leave empty for no override.',
desc: 'Only needed when the endpoint differs from the catalog defaults; include just the fields to change. Leave empty for no override.',
docLink: 'Field reference',
invalid: 'Invalid JSON',
mustBeObject: 'Must be a JSON object',
},

View File

@ -4736,7 +4736,8 @@ export default {
compat: {
label: 'プロトコル互換上書き(JSON)',
placeholder: "{'{'} \"max_tokens_field\": \"max_tokens\" {'}'}",
desc: '解決されたプロトコルのカタログ既定値に上書きマージされる互換スイッチ。バックエンドの catalog/compat.go を参照。空欄で上書きなし。',
desc: 'エンドポイントの挙動がカタログ既定値と異なる場合のみ、変更するフィールドだけを記入します。空欄で上書きなし。',
docLink: 'フィールドの説明',
invalid: 'JSON が不正です',
mustBeObject: 'JSON オブジェクトが必要です',
},

View File

@ -2864,7 +2864,8 @@ export default {
compat: {
label: '프로토콜 호환 재정의(JSON)',
placeholder: "{'{'} \"max_tokens_field\": \"max_tokens\" {'}'}",
desc: '해석된 프로토콜의 카탈로그 기본값 위에 병합되는 호환 스위치입니다. 백엔드 catalog/compat.go 참조. 비워 두면 재정의하지 않습니다.',
desc: '엔드포인트 동작이 카탈로그 기본값과 다를 때만 변경할 필드만 입력합니다. 비워 두면 재정의하지 않습니다.',
docLink: '필드 설명 보기',
invalid: '잘못된 JSON',
mustBeObject: 'JSON 객체여야 합니다',
},

View File

@ -2864,7 +2864,8 @@ export default {
compat: {
label: 'Переопределение совместимости протокола (JSON)',
placeholder: "{'{'} \"max_tokens_field\": \"max_tokens\" {'}'}",
desc: 'Переключатели совместимости, накладываемые на значения каталога для определённого протокола; см. catalog/compat.go на бэкенде. Пусто — без переопределения.',
desc: 'Заполняйте, только если эндпоинт расходится со значениями каталога, и указывайте лишь изменяемые поля. Пусто — без переопределения.',
docLink: 'Описание полей',
invalid: 'Некорректный JSON',
mustBeObject: 'Должен быть JSON-объект',
},

View File

@ -2866,7 +2866,8 @@ export default {
compat: {
label: '协议兼容覆盖(JSON)',
placeholder: "{'{'} \"max_tokens_field\": \"max_tokens\" {'}'}",
desc: '按协议合并到目录默认值的兼容开关,字段见后端 catalog/compat.go。留空表示不覆盖。',
desc: '只在接口与目录默认值不一致时填写,只写需要改的字段。留空表示不覆盖。',
docLink: '查看字段说明',
invalid: 'JSON 格式不正确',
mustBeObject: '必须是 JSON 对象',
},

View File

@ -7,13 +7,15 @@ import { repoVersionLabel } from './version'
const root = resolve(import.meta.dirname, '..')
const sections: { dir: string; label: string }[] = [
const sections: { dir: string; label: string; newestFirst?: boolean }[] = [
{ dir: '01-getting-started', label: '快速开始' },
{ dir: '02-architecture', label: '架构' },
{ dir: '03-features', label: '功能模块' },
{ dir: '04-api', label: 'API 参考' },
{ dir: '05-clients', label: '客户端' },
{ dir: '06-development', label: '开发指南' },
// 每个版本一页(v0.8.2.md),最新版本排在最前
{ dir: '07-releases', label: '版本发布', newestFirst: true },
]
/** 侧边栏条目文字:取正文一级标题,去掉冗余前后缀 */
@ -27,10 +29,19 @@ function itemText(dir: string, file: string): string {
.trim()
}
function itemsOf(dir: string): DefaultTheme.SidebarItem[] {
return readdirSync(resolve(root, dir))
.filter((f) => f.endsWith('.md'))
.sort()
/** 版本号按数字比较,v0.10.0 排在 v0.9.0 之后 */
function compareVersions(a: string, b: string): number {
const parts = (f: string) => f.replace(/^v|\.md$/g, '').split('.').map(Number)
const [x, y] = [parts(a), parts(b)]
for (let i = 0; i < Math.max(x.length, y.length); i++) {
if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) - (y[i] ?? 0)
}
return 0
}
function itemsOf(dir: string, newestFirst = false): DefaultTheme.SidebarItem[] {
const files = readdirSync(resolve(root, dir)).filter((f) => f.endsWith('.md'))
return (newestFirst ? files.sort(compareVersions).reverse() : files.sort())
.map((f) => ({
text: itemText(dir, f),
link: `/${dir}/${f.replace(/\.md$/, '')}`,
@ -40,7 +51,7 @@ function itemsOf(dir: string): DefaultTheme.SidebarItem[] {
const sidebar: DefaultTheme.SidebarItem[] = sections.map((s) => ({
text: s.label,
collapsed: false,
items: itemsOf(s.dir),
items: itemsOf(s.dir, s.newestFirst),
}))
/** 本地搜索默认按空白分词,中文整段会被当作一个词,这里退化为字粒度切分 */

View File

@ -12,6 +12,7 @@ const docsNavigation = [
{ label: 'API', href: '/docs/04-api/01-api-overview', section: '/docs/04-api/' },
{ label: '客户端', href: '/docs/05-clients/01-frontend', section: '/docs/05-clients/' },
{ label: '开发', href: '/docs/06-development/01-dev-guide', section: '/docs/06-development/' },
{ label: '版本', href: '/docs/07-releases/v0.8.2', section: '/docs/07-releases/' },
]
const open = ref(false)
watch(() => route.path, () => open.value = false)

View File

@ -1,6 +1,6 @@
# WeKnora 产品介绍
WeKnora(维娜拉)是腾讯开源的知识库问答系统,支持导入 PDF、Word、网页以及飞书、Notion、语雀等平台的资料。用户可以围绕这些资料提问,并通过回答中的引用查看原文。
WeKnora(维娜拉)是腾讯开源的知识库问答系统,支持导入 PDF、Word、网页以及飞书、Notion、Confluence、语雀、钉钉等平台的资料。用户可以围绕这些资料提问,并通过回答中的引用查看原文。
系统采用检索增强生成(RAG):先解析文档并建立索引,再根据问题检索相关片段,由大模型生成回答。
@ -17,7 +17,7 @@ WeKnora(维娜拉)是腾讯开源的知识库问答系统,支持导入 PDF
| --- | --- |
| 文档格式繁杂,PDF/扫描件/表格难以结构化 | 文档处理流程支持 PDF 版式分析、扫描件 OCR、Office 转换、网页抓取与图片描述,可选 OpenDataLoader/Docling 混合解析 |
| 单一向量检索召回不稳 | 向量 + 关键词(BM25)混合检索,RRF 融合,Rerank 重排,可选知识图谱(GraphRAG)与 Wiki 导航 |
| 模型绑定单一厂商 | 模型抽象层:Ollama 本地模型与 OpenAI 兼容远程接口均可,LLM / Embedding / Rerank / VLM / ASR 分类管理(见 `internal/types/model.go`) |
| 模型绑定单一厂商 | 模型抽象层:Ollama 本地模型与数十家内置厂商(OpenAI 兼容、Anthropic Messages、Gemini 原生等协议)均可,LLM / Embedding / Rerank / VLM / ASR 分类管理,厂商与模型目录见[模型管理](../03-features/06-models.md) |
| 数据安全与私有化 | 全栈可私有部署;敏感凭证(API Key 等)以 AES-256 落盘加密(`SYSTEM_AES_KEY`);多租户隔离 + RBAC 角色鉴权 |
| 多步骤任务与工具调用 | 内置 Agent(ReAct 多步推理)、MCP 工具接入、Agent Skills 沙箱执行、Web 搜索(SearXNG 等)、数据分析(对 CSV/Excel 执行 SQL) |
| 团队协作 | 租户(工作空间)+ 成员角色 + 组织(Organization)跨租户知识库共享 + 邀请机制 |
@ -47,7 +47,7 @@ WeKnora(维娜拉)是腾讯开源的知识库问答系统,支持导入 PDF
| FAQ | 维护标准问、相似问、反例问和答案的问答条目,详见[FAQ 能力](../03-features/17-faq.md) |
| Wiki 页面 WikiPage | 从文档生成的主题页面,带来源引用和页面链接,支持编辑与版本管理 |
| 知识图谱 Entity / Relationship | 文档中的实体与关系,保存在 Neo4j,用于补充关联内容检索 |
| 数据源 DataSource | 持续同步外部资料的连接。支持飞书、Lark、GitLab、IMA、Notion、语雀和 RSS,详见[数据源导入](../03-features/10-datasource.md) |
| 数据源 DataSource | 持续同步外部资料的连接。支持飞书/Lark(知识库与云盘)、Notion、Confluence、语雀、钉钉文档、腾讯 IMA、GitLab 和 RSS,详见[数据源导入](../03-features/10-datasource.md) |
| 检索配置 RetrievalConfig | 控制候选数量、匹配阈值、融合权重和重排结果,详见[检索引擎](../03-features/05-retrieval-engines.md) |
### 对话与智能体
@ -107,14 +107,15 @@ flowchart TB
## 功能清单
- **文档接入**:文件上传(PDF/Word/PPT/Excel/Markdown/HTML/图片/音频等)、URL 抓取、手写 Markdown、整目录上传、飞书 / Lark / Notion / 语雀 / RSS 定时同步。
- **文档接入**:文件上传(PDF/Word/PPT/Excel/Markdown/HTML/EPUB/XMind/图片/音频等)、URL 抓取、手写 Markdown、整目录上传、飞书 / Lark / Notion / Confluence / 语雀 / 钉钉 / IMA / GitLab / RSS 定时同步。
- **文档理解**:版式分析、扫描件 OCR、表格抽取、图片多模态描述(VLM)、音频转写(ASR)、按文件类型选择解析引擎(`ParserEngineRules`,可接 MinerU / OpenDataLoader)。
- **索引管道**:可配置分块(含父子分块与自适应策略)、向量索引、关键词全文索引、FAQ 索引、Wiki 生成、知识图谱抽取、预生成问题(question generation)。
- **检索**:向量 + BM25 混合检索、RRF 融合、Rerank 重排、查询改写与扩展、意图识别(greeting/chitchat/web_search 等,见 `config/prompt_templates/intent_prompts.yaml`)。
- **问答与 Agent**:流式 SSE 问答、多轮上下文压缩、引用溯源;ReAct Agent(工具:`search_knowledge`、`read_document`、`list_documents`、`wiki_search`、`data_analysis` 等)、MCP 外部工具、Agent Skills(Docker、Cube 或 E2B 沙箱执行脚本)、Web 搜索。
- **多租户与安全**:RBAC 角色鉴权(默认开启,`WEKNORA_TENANT_ENABLE_RBAC`)、审计日志(默认保留 90 天)、邀请制注册(`auth.registration_mode=invite_only`,也可用旧变量 `DISABLE_REGISTRATION=true`)、OIDC 单点登录、SSRF 防护、敏感字段 AES-256 加密。
- **对话体验**:回答进行中追加要求、从任意历史提问分叉或原地回滚(带沙箱工作区检查点)、按会话调整思考强度,「产物」页跨会话汇总智能体生成的文件,详见[会话体验](../03-features/18-chat-experience.md)。
- **多租户与安全**:RBAC 角色鉴权(默认开启,`WEKNORA_TENANT_ENABLE_RBAC`)、审计日志(默认保留 90 天)、邀请制注册(`auth.registration_mode=invite_only`,也可用旧变量 `DISABLE_REGISTRATION=true`)、OIDC 单点登录、SSRF 防护(可选仅白名单出站 `SSRF_DNS_WHITELIST_ONLY`)、敏感字段 AES-256 加密。界面提供简体中文、英文、日文、韩文和俄文。
- **可观测性**:Langfuse 全链路追踪(LLM/Embedding/Rerank/VLM/ASR 调用与 token 统计)、健康检查、Swagger API 文档(`GIN_MODE=debug` 时)。
- **生态**:REST API(`/api/v1`)+ API Key、独立 MCP Server(把 WeKnora 作为工具暴露给其他 Agent)、CLI(`cli/`)、微信小程序(`miniprogram/`)、浏览器插件渠道。
- **生态**:REST API(`/api/v1`)+ API Key、内置 MCP Server(按空间创建端点,把 WeKnora 作为工具暴露给其他 Agent,见[MCP 集成](../03-features/08-mcp.md))、CLI(`cli/`)、微信小程序(`miniprogram/`)、浏览器插件渠道、[本机浏览器](../05-clients/09-local-browser.md)(智能体通过 Chrome/Edge 扩展操作用户浏览器)。Lite 桌面版(macOS)可在本机沙箱中执行智能体命令。
## 系统组件一览
@ -133,7 +134,7 @@ flowchart TB
| 可选:minio | MinIO | profile `minio` | 9000 / 9001 | S3 兼容对象存储(`STORAGE_TYPE=minio`) |
| 可选:searxng | SearXNG | profile `searxng` | 8888 | 自建 Web 搜索引擎 |
| 可选:langfuse 栈 | Langfuse 3 + ClickHouse + MinIO | profile `langfuse` | 3000 | LLM 可观测性 |
| 可选:mcp | Python | `mcp-server/`,profile `full` | 8082 | 将 WeKnora API 封装为 MCP Server |
| 可选:mcp(已弃用) | Python | `mcp-server/`,profile `full` | 8082 | 旧版独立 MCP Server;新部署使用 app 内置的 MCP Server 端点 |
| 可选:odl-hybrid | Docling | profile `odl-hybrid` | 5002 | OpenDataLoader PDF 混合解析后端 |
```mermaid
@ -144,14 +145,15 @@ flowchart LR
APP -- "gRPC :50051" --> DR["docreader (Python 文档解析)"]
APP --> PG[("ParadeDB / PostgreSQL :5432 元数据 + 混合检索")]
APP --> RD[("Redis :6379 流管理 + Asynq 队列")]
APP -. "docker run 按需" .-> SB["sandbox (Skills 沙箱)"]
APP -. "按需创建" .-> SB["sandbox (Docker / E2B / Cube 会话沙箱)"]
APP -. "可选" .-> VDB[("Qdrant / Milvus / ES / OpenSearch / Doris ...")]
APP -. "可选" .-> NEO[("Neo4j 知识图谱")]
APP -. "可选" .-> OSS[("MinIO / COS / S3 / OSS / OBS / TOS 对象存储")]
APP -. "可选" .-> SX["SearXNG Web 搜索 :8888"]
APP -. "可选" .-> LF["Langfuse 可观测 :3000"]
APP --> LLM["Ollama 本地模型 / OpenAI 兼容远程模型"]
MCPS["mcp-server :8082"] -- "REST" --> APP
MCPC["MCP 客户端 (Claude / Cursor 等)"] -- "/mcp/:endpoint_id" --> APP
MCPS["mcp-server :8082(已弃用)"] -. "REST" .-> APP
```
## 下一步

View File

@ -59,6 +59,8 @@ docker compose up -d
docker compose ps # 等所有服务变成 healthy/running
```
`.env.example` 中的 `JWT_SECRET`、`SYSTEM_AES_KEY` 默认留空,需要在首次部署时生成一次并妥善保存:`JWT_SECRET` 可用 `openssl rand -hex 32`,`SYSTEM_AES_KEY` 必须是 32 字节,可用 `openssl rand -hex 16`。升级已有部署时请沿用原来的 `SYSTEM_AES_KEY`,否则已加密的凭据无法解密。各密钥的作用见[配置详解](./04-configuration.md)。
停止用 `docker compose down`(加 `-v` 会连数据卷一起删,慎用)。仓库里的 `make start-all` 是同一条命令的封装(`scripts/start_all.sh`,额外做 Ollama 检查、`.env` 兜底、沙箱镜像预拉取),两者选一即可。
启动后在浏览器打开 `http://localhost` 就是前端(端口由 `FRONTEND_PORT` 决定,默认 80),首次访问会落到注册页。前端 Nginx 把 `/api/` 反代到后端,所以接口调用同样走 `http://localhost/api/v1`;后端 `8080` 端口也直接映射到宿主机,`curl http://localhost:8080/health` 可用于确认后端就绪。
@ -130,10 +132,10 @@ make dev-logs / dev-status / dev-stop / dev-restart
| Dockerfile | 产物镜像 | 要点 |
| --- | --- | --- |
| `docker/Dockerfile.app` | `wechatopenai/weknora-app` | 两阶段:`golang:1.26-bookworm` 编译(`make build-prod`,默认 `WITH_ANYDOC=1` 链接进程内 office 解析引擎,注入版本信息,预下载 DuckDB 扩展 `cmd/download/duckdb`)→ `debian:12.12-slim` 运行层(含 `migrate` 迁移工具、python3/node/uvx(供 stdio MCP 与 Skills 使用)、ffmpeg(ASR)、gosu 降权)。入口 `scripts/docker-entrypoint.sh`:修复挂载目录属主;若挂载了 docker.sock,按 socket GID 把 appuser 加入对应组(compose `group_add` 在 gosu 后无效),再以 appuser 运行 `./WeKnora`。`EXPOSE 8080` |
| `docker/Dockerfile.app` | `wechatopenai/weknora-app` | 三阶段:先构建 BrowserSkill 的 `bsk` 与配套 Chrome 扩展(装入 `/opt/weknora/browserskill/`,见[本机浏览器](../05-clients/09-local-browser.md));再用 `golang:1.26-bookworm` 编译(`make build-prod`,默认 `WITH_ANYDOC=1` 链接进程内 office 解析引擎,注入版本信息,预下载 DuckDB 扩展 `cmd/download/duckdb`)→ `debian:12.12-slim` 运行层(含 `migrate` 迁移工具、python3/node/uvx(供 stdio MCP 使用)、ffmpeg(ASR)、gosu 降权,以及第三方许可证文本)。入口 `scripts/docker-entrypoint.sh`:修复挂载目录属主;若挂载了 docker.sock,按 socket GID 把 appuser 加入对应组(compose `group_add` 在 gosu 后无效),再以 appuser 运行 `./WeKnora`。`EXPOSE 8080` |
| `docker/Dockerfile.docreader` | `wechatopenai/weknora-docreader` | Python 3.10 + uv 依赖锁定;生成 protobuf;运行层安装 LibreOffice、OpenJDK 17、antiword、Playwright(webkit)与 `grpc_health_probe`。轻量版不含 PaddleOCR。`EXPOSE 50051`。支持 `APT_MIRROR` 构建参数 |
| `docker/Dockerfile.odl-hybrid` | `weknora-odl-hybrid:local` | 安装 `opendataloader-pdf[hybrid]`(Docling),监听 5002,默认 `--no-ocr`;仅本地构建不发布 |
| `docker/Dockerfile.sandbox` | `wechatopenai/weknora-sandbox` | Python 3.12-slim + Node 20 + jq,默认 `root` 执行,保留 `user`(UID 1000) 供显式选择,Agent Skills 会话沙箱镜像 |
| `docker/Dockerfile.sandbox` | `wechatopenai/weknora-sandbox` | Agent 会话沙箱镜像。基础环境为 Python 3.12-slim + Node 20 + uv/pnpm,默认 `root` 执行,保留 `user`(UID 1000) 供显式选择。默认构建目标 `sandbox` 供 Docker 后端使用;另有 `cube`(含 Cube envd)、`desktop` / `desktop-cube`(带图形桌面)等目标,见[沙箱部署](../06-development/04-sandbox-deployment.md) |
| `frontend/Dockerfile` | `wechatopenai/weknora-ui` | 两阶段:digest 锁定的 `node:24-bookworm-slim`(`$BUILDPLATFORM`,避免多架构 CI 用 QEMU 跑 Vite)内 `npm ci` + `npm run build`(`VITE_IS_DOCKER` / `VITE_FRONTEND_COMMIT`),可选 `NPM_REGISTRY` / `NODE_MAX_OLD_SPACE_SIZE`;运行层为按 digest 固定的 `nginx:1.30.3-alpine`(兼容 CentOS 7 旧内核)。无需宿主机预构建 `dist/` |
从源码构建全部镜像:
@ -173,14 +175,14 @@ make docker-build-frontend
| `scripts/build_images.sh` | 构建镜像并注入版本(git tag / commit / build time),支持跨架构 |
| `scripts/build_frontend_dist.sh` | 宿主机构建前端静态产物 `frontend/dist`(Lite / 桌面打包等非 Docker 场景;UI 镜像改由 Dockerfile 多阶段构建) |
| `scripts/migrate.sh` | golang-migrate 封装 |
| `scripts/docker-entrypoint.sh` | app 容器入口(属主修复 + 内置 Skills 合并 + docker.sock GID 补组 + gosu 降权) |
| `scripts/docker-entrypoint.sh` | app 容器入口(属主修复 + docker.sock GID 补组 + gosu 降权) |
| `scripts/package-lite.sh` / `package-mac-app.sh` | Lite tarball / macOS .app 打包 |
## 六、Helm 部署(helm/)
`helm/Chart.yaml`:apiVersion v2,chart 名 `weknora`,appVersion 跟随版本(如 v0.8.0),要求 Kubernetes >= 1.25.0。
Chart 内包含五个组件:`app`(`wechatopenai/weknora-app`)、`frontend`(`wechatopenai/weknora-ui`)、`docreader`、`postgresql`(ParadeDB 镜像)、`redis`(`redis:7-alpine`),并可选启用 `minio` 与 `neo4j`。
Chart 内包含五个组件:`app`(`wechatopenai/weknora-app`)、`frontend`(`wechatopenai/weknora-ui`)、`docreader`、`postgresql`(ParadeDB 镜像,chart 默认 `paradedb/paradedb:v0.18.9-pg17`,与 Compose 的版本不同)、`redis`(`redis:7-alpine`),并可选启用 `minio` 与 `neo4j`。
`helm/values.yaml` 关键配置:
@ -200,6 +202,8 @@ redis:
persistence: { enabled: true, size: 1Gi }
dataFiles:
persistence: { enabled: true, size: 10Gi }
global:
maxFileSizeMB: 50 # 上传大小上限,同时作用于 frontend / app / docreader
secrets: # 必填项,或用 existingSecret 引用已有 Secret
dbPassword: ""
redisPassword: ""
@ -207,6 +211,8 @@ secrets: # 必填项,或用 existingSecret 引用
systemAesKey: "" # 32 字节 AES-256 主密钥
```
`global.maxFileSizeMB` 与 Compose 的 `MAX_FILE_SIZE_MB` 含义相同,chart 会把它写入 frontend(Nginx 请求体上限)、app(上传限制)与 docreader(gRPC 消息上限)三处。可选的 MinIO 镜像为 `quay.io/minio/minio`。
```bash
helm install weknora ./helm -n weknora --create-namespace \
--set secrets.dbPassword=xxx --set secrets.redisPassword=xxx \
@ -215,7 +221,7 @@ helm install weknora ./helm -n weknora --create-namespace \
## 七、桌面端(Lite 模式 / 桌面应用)
桌面端面向本机与低资源环境,底层都是同一套 Lite 运行时(单进程 + SQLite + 内存队列),只是分发与启动方式不同:**单二进制**(命令行启动,也可作为后台服务)、**桌面应用**(图形界面,双击启动)。两者能力范围一致。
桌面端面向本机与低资源环境,底层都是同一套 Lite 运行时(单进程 + SQLite + 内存队列),只是分发与启动方式不同:**单二进制**(命令行启动,也可作为后台服务)、**桌面应用**(图形界面,双击启动)。知识库与问答能力一致;免注册登录、本机沙箱与绑定本机项目目录只在桌面应用中提供。
### Lite 运行时(零外部依赖) {#_7-1-lite-运行时-零外部依赖}
@ -226,15 +232,15 @@ Lite 模式通过编译期 `EDITION=lite` 与运行期 `.env.lite` 环境实现
- **队列/流**:`STREAM_MANAGER_TYPE=memory`(`internal/stream/factory.go`),不需要 Redis,Asynq 分布式队列在 Lite 模式下为内存/no-op;
- **前端**:`make build-lite` 会把 `frontend/dist` 复制为仓库根的 `web/`,二进制直接内嵌托管静态资源(`WEKNORA_WEB_DIR` 可指定目录,router 的 `serveFrontendStatic` 提供服务);
- **文档解析**:仍可选连本地 docreader(`DOCREADER_ADDR=127.0.0.1:50051`);
- **沙箱**:Lite 启动时不预置后端;可在设置页按空间统一配置 Docker、CubeSandbox 或 E2B。
- **沙箱**:单二进制启动时不预置后端,可在设置页按空间配置 Docker、CubeSandbox 或 E2B;桌面应用的会话在未指定远程沙箱时使用本机操作系统沙箱,见[桌面客户端](../05-clients/05-desktop.md)。
```bash
cp .env.lite.example .env.lite # 修改 SYSTEM_AES_KEY / JWT_SECRET
cp .env.lite.example .env.lite # 填写 SYSTEM_AES_KEY(openssl rand -hex 16)与 JWT_SECRET
make run-lite # 构建并以 .env.lite 环境启动 ./WeKnora-lite
make package-lite # 打包发行 tarball(scripts/package-lite.sh)
```
Lite 还提供 `POST /auth/auto-setup` 一键生成本地账号(仅 lite edition 开放,见 `internal/handler/auth.go`),桌面应用据此实现免注册启动。
单二进制通过浏览器访问时,与标准版一样需要注册和登录。桌面应用启动时通过原生桥接取得每进程随机凭据,调用 `POST /auth/auto-setup` 自动创建本地账号并登录;该接口不接受匿名 HTTP 请求。
### 桌面应用(cmd/desktop,Wails v2) {#_7-2-桌面应用-cmd-desktop-wails-v2}
@ -262,7 +268,7 @@ make build && ./WeKnora # 或 make build-prod
cd frontend && npm ci && npm run dev # 开发;npm run build 产出 dist/
# docreader
cd docreader && uv sync --locked && bash scripts/generate_proto.sh && python -m docreader.server # 具体入口见 docreader/
cd docreader && uv sync --locked && bash scripts/generate_proto.sh && uv run -m docreader.main # 与镜像 CMD 一致
```
配置文件查找顺序(`internal/config/config.go` 的 `LoadConfig`):当前目录 → `./config` → `$HOME/.appname` → `/etc/appname/`,文件名 `config.yaml`。

View File

@ -24,7 +24,7 @@
- 用户名 2–50 个字符;密码为 8–32 位,至少包含字母和数字。启用复杂密码策略后,还须同时包含大小写字母和特殊字符,界面与 API 使用同一策略;
- 团队部署可关闭公开注册,之后通过邀请链接添加成员。可设置 `DISABLE_REGISTRATION=true`(启动时把注册模式强制为 `invite_only`),或由系统管理员在「设置 → 系统」将 `auth.registration_mode` 改成 `invite_only`(立即生效,不用重启);
- 如果部署把默认空间策略设成了 `tenantless`(`auth.default_tenant_mode`),注册后**不会**自动建空间,而是被引导到 `/onboarding/workspace`,需要先自建或接受邀请加入一个空间才能继续;
- 桌面版 / Lite 版免注册,启动即自动创建本地账号。
- 桌面应用免注册,启动即自动创建本地账号并登录;Lite 单二进制在浏览器中访问时仍需注册和登录。
::: tip 空间与平台权限
空间 Owner 管理所在空间的成员、模型和知识库。全局系统设置、平台任务队列及跨空间审计需要系统管理员身份,两类权限独立授予。

View File

@ -5,7 +5,7 @@ WeKnora 的配置由四层组成,**优先级从低到高**:
| 层 | 位置 | 用途 |
| --- | --- | --- |
| 主配置文件 | `config/config.yaml` | 结构化的默认值,随镜像分发 |
| 模板 / 预设 | `config/prompt_templates/*.yaml`、`builtin_agents.yaml`、`agent_type_presets.yaml`、`builtin_models.yaml` | 提示词、内置 Agent、内置模型 |
| 模板 / 预设 | `config/prompt_templates/*.yaml`、`builtin_agents.yaml`、`agent_type_presets.yaml`、`builtin_models.yaml`、`models.json` | 提示词、内置 Agent、内置模型、模型厂商目录叠加 |
| 环境变量 | `.env` / 容器 environment | 部署级覆盖,改完需重启 |
| 运行时系统设置 | 数据库 `system_settings` 表,界面在「设置 → 系统」 | 支持的设置可在线修改,优先于环境变量,多数立即生效 |
@ -143,12 +143,13 @@ flowchart LR
| `LOG_LEVEL` / `LOG_PATH` / `LOG_FORMAT` | debug / 空 / 空 | 日志级别、文件路径(空则仅 stdout)、自定义格式 |
| `LLM_DEBUG_LOG` | false | true 时在 LOG_PATH 同目录写 `llm_debug.log` |
| `TZ` | Asia/Shanghai | 时区 |
| `WEKNORA_LANGUAGE` | 空 | 文档处理语言(问题/摘要生成)。优先级:本变量 > 请求的 `Accept-Language` > 内置 `zh-CN`。文档处理语言可独立于界面语言设置,例如使用英文界面处理韩文文档 |
| `DEFAULT_LOCALE` | 空 | 前端界面默认语言(frontend 容器读取):`zh-CN` / `en-US` / `ru-RU` / `ko-KR` / `ja-JP`,非法值忽略。仅影响未手动切换过语言的用户,优先级:用户已选语言 > 本变量 > `zh-CN`;改完重启 frontend 容器即可,无需重建镜像 |
| `WEKNORA_LANGUAGE` | 空 | 文档处理语言(问题/摘要生成)。优先级:本变量 > 请求的 `Accept-Language` > 内置 `zh-CN`。文档处理语言可独立于界面语言设置,例如使用英文界面处理韩文文档。未设置回复语言的 IM 渠道也以本变量(未设置时为 `zh-CN`)作为默认回复语言 |
| `AUTO_MIGRATE` | true | 启动时自动执行数据库迁移 |
| `AUTO_RECOVER_DIRTY` | true | 自动修复 golang-migrate 的 dirty 状态(上次迁移中断留下的)。手工排查迁移问题时应临时设为 false,否则启动会自动改写迁移版本记录,见[数据库与迁移](../06-development/02-database-schema.md) |
| `WEKNORA_TRUSTED_PROXIES` | 空 | gin 信任代理 CIDR(逗号分隔) |
| `MAX_SKILL_BUNDLE_SIZE_MB` | 256 MiB(默认不小于 MAX_FILE_SIZE_MB,上限 512 MiB) | 技能 ZIP 上传与来源下载上限;反向代理请求体限制也需足够大 |
| `MAX_FILE_SIZE_MB` | 50 | 上传文件大小限制(app/frontend/docreader 三处共用) |
| `MAX_FILE_SIZE_MB` | 50 | 上传文件大小限制(app/frontend/docreader 三处共用);Helm 部署使用 `global.maxFileSizeMB` |
| `CONCURRENCY_POOL_SIZE` | 5 | 通用并发池 |
| `APP_EXTERNAL_URL` / `FRONTEND_BASE_URL` | 空 | IM 渠道图片/文件外链的外部可达 URL / 前端外部 origin |
| `RESOURCE_URL_MODE` | handle | API 响应里文件引用的默认形式:`handle` 返回内部 `resource://`,`public` 返回可直接加载的限时外链。单次请求可用 `?resource_urls=` 覆盖,详见 [API 总览](../04-api/01-api-overview.md) |
@ -195,7 +196,7 @@ flowchart LR
| 名称 | 默认值 | 说明 |
| --- | --- | --- |
| `STORAGE_TYPE` | local | `local` / `minio` / `cos` / `tos` / `s3` / `obs` / `oss` |
| `STORAGE_ALLOW_LIST` | 空 | 允许用户选择的存储类型白名单(逗号分隔) |
| `STORAGE_ALLOW_LIST` | 空 | 允许用户选择的存储类型白名单(逗号分隔),可选值 `local`、`minio`、`cos`、`tos`、`s3`、`oss`、`ks3`、`obs` |
| `LOCAL_STORAGE_BASE_DIR` | /data/files | 本地存储根目录 |
| `MINIO_ENDPOINT/ACCESS_KEY_ID/SECRET_ACCESS_KEY/BUCKET_NAME/USE_SSL` | minio:9000 / minioadmin / minioadmin / 空 / false | MinIO |
| `COS_SECRET_ID/SECRET_KEY/REGION/BUCKET_NAME/APP_ID/PATH_PREFIX` | 空 | 腾讯云 COS(另有 TEMP_BUCKET/TEMP_REGION) |
@ -212,6 +213,7 @@ AWS S3 的 `S3_ACCESS_KEY` / `S3_SECRET_KEY` 可以**同时留空**,此时走
| `BATCH_EMBED_SIZE` | 空 | 批量 embedding 大小 |
| `VLM_HTTP_TIMEOUT_SECONDS` | 180 | VLM 单次请求超时 |
| `BUILTIN_MODELS_CONFIG` | config/builtin_models.yaml | 内置模型声明文件路径(见下文) |
| `MODELS_CONFIG` | config/models.json | 模型厂商目录的部署叠加文件路径(补充厂商、覆盖地址或模型参数),格式见[模型管理](../03-features/06-models.md) |
| `WEKNORA_LLM_STREAM_RAW_DUMP` / `_DIR` | 空 | LLM 流原始转储(排障用) |
向量模型名不由环境变量决定。在模型记录里把 `type=Embedding`、`source=local` 的 `name` 设为 Ollama 模型名(CLI 示例 `nomic-embed-text`,维度 768;快速开始用 `bge-m3`,维度 1024)。名为空时本地 embedder 回退到 `nomic-embed-text`。`EMBEDDING_MODEL_NAME` 只在 `builtin_models.yaml` 引用 `${EMBEDDING_MODEL_NAME}` 时生效(见下文「config/builtin_models.yaml.example:声明式内置模型」与仓库 `config/builtin_models.yaml.example`)。安装文档的 8GB 起点不含 Ollama 权重;Neo4j 默认关闭(`neo4j` profile)。
@ -220,8 +222,9 @@ AWS S3 的 `S3_ACCESS_KEY` / `S3_SECRET_KEY` 可以**同时留空**,此时走
| 名称 | 默认值 | 说明 |
| --- | --- | --- |
| `JWT_SECRET` | 空 | JWT 签名密钥(必填) |
| `SYSTEM_AES_KEY` | 空 | 敏感字段落盘加密的 AES-256 主密钥,**必须 32 字节**;丢失则已加密数据(租户 API Key、模型 key、向量库凭证等)不可恢复。v0.4.0 起取代 `TENANT_AES_KEY`/`CRYPTO_MASTER_KEY`/`CRYPTO_SALT` |
| `JWT_SECRET` | 空 | JWT 签名密钥(必填,可用 `openssl rand -hex 32` 生成)。留空或使用示例值时每次启动随机生成,重启后已登录用户需重新登录;多副本必须配置相同的值 |
| `SYSTEM_AES_KEY` | 空 | 敏感字段落盘加密的 AES-256 主密钥,**必须 32 字节**(可用 `openssl rand -hex 16` 生成);丢失则已加密数据(租户 API Key、模型 key、向量库凭证等)不可恢复,升级时沿用原值。v0.4.0 起取代 `TENANT_AES_KEY`/`CRYPTO_MASTER_KEY`/`CRYPTO_SALT` |
| `SYSTEM_SIGNING_KEY` | 空(回退到 `SYSTEM_AES_KEY`) | 嵌入会话与预签名文件链接的签名密钥(可用 `openssl rand -hex 32` 生成)。未设置时使用 `SYSTEM_AES_KEY`;两者都缺失、长度不足 16 或为示例值时无法签发签名链接与嵌入会话。更换后已签发的链接失效;多副本须使用同一个值 |
| `DISABLE_REGISTRATION` | false | true 时强制 `registration_mode=invite_only` |
| `WEKNORA_AUTH_DEFAULT_TENANT_MODE` | create_personal | 注册后建空间策略(`create_personal` / `tenantless`) |
| `WEKNORA_TENANT_ENABLE_RBAC` | (默认 true) | 空间角色强制鉴权开关 |
@ -238,7 +241,7 @@ AWS S3 的 `S3_ACCESS_KEY` / `S3_SECRET_KEY` 可以**同时留空**,此时走
| `WEKNORA_BOOTSTRAP_SYSTEM_ADMIN_EMAIL` | 空 | 引导第一个系统管理员。**不会创建用户**:该邮箱需先自行注册,下次启动时若部署内还没有任何系统管理员,才把它提升;已有管理员后本变量不再生效。详见[租户、用户与认证授权](../03-features/01-tenant-auth.md) |
| `OIDC_AUTH_ENABLE` 及 `OIDC_AUTH_*` / `OIDC_USER_INFO_MAPPING_*` | false / 空 | OIDC 单点登录全套配置 |
| `SSRF_WHITELIST` / `SSRF_WHITELIST_EXTRA` | 空 / `searxng,qdrant,milvus,weaviate,doris-fe,doris-be,minio`(仅 app) | 出站请求 SSRF 白名单。`SSRF_WHITELIST` 为 app 与 docreader 共用;compose 只给 app 的 `SSRF_WHITELIST_EXTRA` 设了默认值,docreader 的同名变量默认为空 |
| `SSRF_DNS_WHITELIST_ONLY` | false | 仅允许白名单出站。开启后,不在白名单的主机在 **DNS 查询前**即被拒绝,URL 校验处连 IP 直连也一并拒绝;域名只按名字匹配,写在白名单里的 CIDR 不再对域名生效。取值按布尔解析(`1/t/true` 开、`0/f/false` 关),**非空且无法解析的取值按「开」处理**。开启前的准备见下文 |
| `SSRF_DNS_WHITELIST_ONLY` | false | 仅允许白名单出站(app 与 docreader 均读取)。开启后,不在白名单的主机在 **DNS 查询前**即被拒绝,URL 校验处不在白名单的 IP 直连也一并拒绝;域名只按名字匹配,写在白名单里的 CIDR 不再对域名生效。取值按布尔解析(`1/t/true` 开、`0/f/false` 关),**非空且无法解析的取值按「开」处理**。开启前的准备见下文 |
| `IMAGE_HOST_KEEP_URL` | 空 | 保留原始 URL 的图片域名白名单 |
#### 开启 `SSRF_DNS_WHITELIST_ONLY` 之前
@ -256,6 +259,16 @@ AWS S3 的 `S3_ACCESS_KEY` / `S3_SECRET_KEY` 可以**同时留空**,此时走
2. **Langfuse 的 OTLP 导出器**自带 HTTP 客户端,完全不走本机制。`LANGFUSE_HOST` 默认是 SaaS 地址,离线部署请关闭追踪或改成内网地址。
3. **`HTTP(S)_PROXY`**:拨号器对代理主机的放行条件是「拨号地址与代理 URL 的 host 完全相等」。相等时代理主机即使不在白名单也会被解析和连接;不相等时(例如代理 URL 没写端口)会被当成非白名单直接拒绝。离线部署请 unset 代理,或把代理主机一并写进白名单。
### 镜像构建参数(从源码构建时)
以下变量只在 `docker compose build` / `make docker-build-frontend` 构建 frontend 镜像时使用,拉取官方镜像部署时无需设置。其他构建参数(Go 代理、apt 镜像源等)见 `.env.example` A1 节。
| 名称 | 默认值 | 说明 |
| --- | --- | --- |
| `VITE_FRONTEND_COMMIT` | unknown | 写入「系统信息」页的前端短 commit。`make docker-build-frontend` 与 `start_all.sh --no-pull` 会从 git 自动填充;直接 `docker compose build` 时需自行导出 |
| `NPM_REGISTRY` | 空(默认源) | 构建阶段使用的 npm registry,国内可设 `https://registry.npmmirror.com` |
| `NODE_MAX_OLD_SPACE_SIZE` | 4096 | Vite 构建的 Node 堆上限(MB),Docker Desktop 内存较小时可降到 2048 |
### Docreader 解析(docreader 容器)
| 名称 | 默认值 | 说明 |
@ -274,7 +287,7 @@ AWS S3 的 `S3_ACCESS_KEY` / `S3_SECRET_KEY` 可以**同时留空**,此时走
| 名称 | 默认值 | 说明 |
| --- | --- | --- |
| Sandbox 配置 | 设置页按空间维护 | 后端、凭据、模板、超时和私网访问策略按空间保存 |
| `WEKNORA_SANDBOX_DOCKER_ENABLED` | false | Docker 沙箱后端回退开关。系统管理员也可在「设置 → 系统设置」打开(DB 优先,立即生效)。默认关闭,因为本机 `docker.sock` 等同宿主机 root |
| `WEKNORA_SANDBOX_DOCKER_ENABLED` | false | Docker 沙箱后端回退开关。系统管理员也可在「设置 → 系统设置 → 网络安全」打开(DB 优先,立即生效)。默认关闭,因为本机 `docker.sock` 等同宿主机 root |
| `WEKNORA_AGENT_LLM_TIMEOUT` | 120s | Agent 单次 LLM 调用超时(Go duration 或纯数字秒) |
| `WEKNORA_AGENT_TOOL_APPROVAL_TIMEOUT` / `_FAIL_OPEN` | 600s / fail-close | MCP 工具人工审批等待与失败策略 |
| `WEKNORA_CHAT_ATTACHMENT_TTL_HOURS` / `_WAIT_TIMEOUT_SEC` / `_OCR_CONCURRENCY` / `_OCR_MAX_PAGES` | 24 / 60 / 8 / 8 | 聊天附件解析保留时长、等待超时与 OCR 并发/页数上限 |
@ -284,6 +297,20 @@ AWS S3 的 `S3_ACCESS_KEY` / `S3_SECRET_KEY` 可以**同时留空**,此时走
沙箱后端、网络策略、脚本开关与个人环境变量使用空间配置/API 管理,见[技能与沙箱](../03-features/22-skills-sandbox.md)。长期记忆与自动标签均默认关闭,分别使用租户 memory_config 和知识库 auto_tag_config,不用全局环境变量替代各空间配置。
### 本机浏览器(BrowserSkill,可选)
用户通过 Chrome 扩展把本机浏览器连接到 WeKnora。Docker app 镜像已内置 `bsk` 与配套扩展,默认根据用户当前访问的页面地址生成连接地址,通常无需配置。
| 名称 | 默认值 | 说明 |
| --- | --- | --- |
| `BROWSERSKILL_BINARY` | Docker 镜像内 `/opt/weknora/browserskill/bsk` | `bsk` 可执行文件绝对路径;原生部署需自行构建并配置,显式设为空可关闭本功能 |
| `BROWSERSKILL_EXTENSION_PATH` | Docker 镜像内已预设 | 供用户在「工具箱 → 浏览器连接」的「手动安装(备用)」下载的扩展 ZIP 路径 |
| `BROWSERSKILL_PUBLIC_URL` | 空(按页面地址生成) | 仅在网关使用独立域名或路径时覆盖;远程部署必须使用 `wss://` |
| `BROWSERSKILL_MAX_CONNECTIONS` | 32 | 单个应用实例同时在线的浏览器设备上限 |
| `BROWSERSKILL_INTERNAL_URL` / `BROWSERSKILL_CLUSTER_SECRET` | 空 | 多副本部署:每个节点填写其他节点可直连的地址(不要用负载均衡地址),所有副本使用相同的随机密钥(至少 32 字符) |
部署方式与限制见[本机浏览器](../05-clients/09-local-browser.md)。
### 可观测性(Langfuse)
`LANGFUSE_PUBLIC_KEY` + `LANGFUSE_SECRET_KEY` 同时设置即自动启用;`LANGFUSE_HOST`(默认 `https://cloud.langfuse.com`,自建栈填 `http://langfuse-web:3000`)、`LANGFUSE_ENABLED`、`LANGFUSE_RELEASE`、`LANGFUSE_ENVIRONMENT`、`LANGFUSE_SAMPLE_RATE`、`LANGFUSE_FLUSH_AT/FLUSH_INTERVAL/QUEUE_SIZE/REQUEST_TIMEOUT/DEBUG` 为调优项;`--profile langfuse` 自建栈另有 `LANGFUSE_SALT`、`LANGFUSE_ENCRYPTION_KEY`、`LANGFUSE_NEXTAUTH_SECRET`、`LANGFUSE_INIT_*`(首启自动建组织/项目/管理员)等,见 `.env.example` I1/I2 节。
@ -296,7 +323,7 @@ AWS S3 的 `S3_ACCESS_KEY` / `S3_SECRET_KEY` 可以**同时留空**,此时走
| 名称 | 默认值 | 说明 |
| --- | --- | --- |
| `SEARXNG_PORT` | 8888 | 宿主机端口 |
| `SEARXNG_PORT` | 8888 | 宿主机端口。不要与 `APP_PORT`(默认 8080)相同,否则 `localhost` 上的请求可能先命中 SearXNG,登录接口返回 HTML 404 |
| `SEARXNG_BIND` | 127.0.0.1 | **默认只监听本机**。WeKnora 打包的配置关掉了 SearXNG 自身的限流(否则后端会被节流),所以不应直接暴露到 LAN;确实要开放请显式改成 `0.0.0.0` 并自行加固 |
| `SEARXNG_SECRET` | 空 | 入口脚本用它替换 `settings.yml` 里的 `secret_key`,对外开放时必须设 |

View File

@ -21,6 +21,11 @@ docker compose logs --tail=200 postgres redis
| 升级后提示权限不足 | 核对当前空间角色、资源归属与 API Key 能力范围;见[认证与授权](../03-features/01-tenant-auth.md)。平台管理员与空间 Owner 不是同一个概念 |
| Agent 提示模型未就绪 | 确认该智能体引用的模型仍存在且配置完整,执行模型连通性测试;见[模型管理](../03-features/06-models.md) |
| 私网数据源、模型或向量库连接被拒绝 | 检查 SSRF 校验和端口策略;按[配置参考](04-configuration.md)仅放行需要的目标 |
| 报错提示「仅允许白名单出站」 | 部署开启了 `SSRF_DNS_WHITELIST_ONLY`,不在白名单的主机在 DNS 解析前即被拒绝。把目标主机加入 `SSRF_WHITELIST` 或 `SSRF_WHITELIST_EXTRA` 后重建 app / docreader 容器,见[配置详解](04-configuration.md) |
| 登录接口返回 HTML 404 | 检查 `SEARXNG_PORT` 是否与 `APP_PORT`(默认 8080)相同。Linux 上 SearXNG 绑定 `127.0.0.1:8080` 后,`localhost:8080` 的请求会先到 SearXNG。保持 SearXNG 使用 8888 或其他空闲端口 |
| 拉取 MinIO 镜像提示 `pull access denied` | MinIO 已不再向 Docker Hub 发布镜像。当前 Compose 与 Helm 使用 `quay.io/minio/minio`;自定义编排文件需同步修改镜像地址 |
| 升级后嵌入页面或签名链接失效 | 签名密钥取 `SYSTEM_SIGNING_KEY`,未设置时回退到 `SYSTEM_AES_KEY`;示例密钥和长度不足 16 的密钥不能签名。v0.8.2 更换了嵌入会话的签名算法,升级前签发的嵌入会话全部失效,访客需重新进入;多副本部署须使用同一个密钥 |
| 升级后钉钉机器人不再回复 | v0.8.2 起钉钉只支持 Stream 模式,升级迁移会把 `webhook` 渠道改为 `websocket`。需在钉钉开发者后台为该应用开启 Stream 模式,见[IM 集成](../03-features/12-im-integration.md) |
| 后台队列持续积压 | 结合最老任务等待时间、活跃 worker 和下游配额定位;提高 worker 数不会增加模型供应商配额,见[容量估算](../02-architecture/05-async-tasks.md#capacity-planning) |
| 技能已加入目录却不可执行 | 目录收录和沙箱安装是两步;检查安装记录、智能体的沙箱选择与技能范围,见[技能目录与沙箱](../03-features/22-skills-sandbox.md) |
| 升级后找不到 Local 沙箱 | `local` 后端已移除,重新配置 Docker、CubeSandbox 或 E2B;见[沙箱部署与排障](../06-development/04-sandbox-deployment.md) |
@ -76,6 +81,16 @@ make migrate-up
这里的 98 是示例,必须换成实际确认的版本,不能机械地把报错数字减一。初始迁移失败还需单独检查初始化状态。恢复后重启 app,确认系统信息不再显示错误,并验证受影响的功能。
### 并发建索引中断
迁移 `000106` 用 `CREATE INDEX CONCURRENTLY` 为 `messages` 建索引,构建期间不阻塞写入。若构建被中断(进程重启、超时、磁盘不足),会留下一个 INVALID 的 `idx_messages_session_created_id`,`IF NOT EXISTS` 不会重建它。先确认并删除该索引,再按上文恢复迁移状态后重跑:
```sql
SELECT indexrelid::regclass, indisvalid FROM pg_index
WHERE indexrelid = 'idx_messages_session_created_id'::regclass;
DROP INDEX CONCURRENTLY IF EXISTS idx_messages_session_created_id;
```
### 磁盘不足与 Schema 差异
索引构建需要额外临时空间。遇到 `No space left on device`,检查数据库数据卷及临时目录容量,清理空间后再按实际迁移状态恢复。

View File

@ -32,14 +32,14 @@ WeKnora 采用"主服务 + 前端 + 文档解析微服务"的三进程核心架
| `dex` | `dex` / `full` | OIDC 测试用 IdP(配合 `OIDC_AUTH_ENABLE`) |
| `langfuse-*`(web/worker/clickhouse/minio/db-init) | `langfuse` | 自建 LLM 可观测栈,复用 WeKnora 的 postgres(新建 `langfuse` 库)与 redis(DB 1) |
此外,Go 后端还可直连未在 compose 内的外部引擎:Elasticsearch v7/v8、OpenSearch、腾讯云 VectorDB、火山 VikingDB,以及 8 种对象存储(local/MinIO/COS/TOS/S3/OSS/KS3/OBS)。
此外,Go 后端还可直连未在 compose 内的外部引擎:Elasticsearch v7/v8、OpenSearch、腾讯云 VectorDB,以及 8 种对象存储(local/MinIO/COS/TOS/S3/OSS/KS3/OBS)。
### 部署形态 {#_1-3-部署形态}
除标准 Docker Compose 部署外,仓库还支持:
- **Lite 模式**:`DB_DRIVER=sqlite`(内置 sqlite-vec 向量扩展)+ 不配置 `REDIS_ADDR`(Asynq 退化为进程内 `SyncTaskExecutor`),单二进制运行,前端静态资源内嵌(`handler.Edition == "lite"` 时由 Go 进程直接托管);
- **桌面版**:`cmd/desktop` 基于 Wails v2 打包为桌面应用;
- **桌面版**:`cmd/desktop` 基于 Wails v2 打包为桌面应用,会话可在本机操作系统沙箱中执行(目前仅 macOS,基于 Seatbelt);
- **Kubernetes**:`helm/` Chart;**裸机**:`deploy/` systemd 单元。
## 技术栈清单 {#_2-技术栈清单}
@ -79,9 +79,11 @@ WeKnora 采用"主服务 + 前端 + 文档解析微服务"的三进程核心架
| `app` → `postgres` | PostgreSQL wire(GORM/pgx) | 业务数据 + BM25 + pgvector |
| `app` ↔ `redis` | RESP(支持 TLS) | ① Asynq 任务队列(文档解析/富化/Wiki/记忆等任务);② SSE 流断线续传的 Stream Manager(`STREAM_MANAGER_TYPE`);③ `system_settings` 变更 Pub/Sub;④ Embed 渠道限流;⑤ 分布式 per-model 并发信号量 |
| `app` → `neo4j` | Bolt(`bolt://neo4j:7687`) | GraphRAG 实体/关系存取 |
| `app` → `searxng` / Web 搜索 provider | HTTP | SSRF 白名单校验(`SSRF_WHITELIST_EXTRA` 默认放行 compose 内 `searxng,qdrant,milvus,weaviate,doris-fe,doris-be`) |
| `app` → `searxng` / Web 搜索 provider | HTTP | SSRF 白名单校验(`SSRF_WHITELIST_EXTRA` 默认放行 compose 内 `searxng,qdrant,milvus,weaviate,doris-fe,doris-be,minio`;开启 `SSRF_DNS_WHITELIST_ONLY` 后只允许白名单出站) |
| `app` → 向量库/对象存储/LLM 提供商 | 各自 SDK(HTTP/gRPC/MySQL 协议) | Doris 走 MySQL 协议 + Stream Load HTTP |
| `app` → 沙箱后端 | Docker Engine API / Cube/E2B 控制面与数据面 | 会话执行、技能安装与文件产物;按空间沙箱配置选择 |
| MCP 客户端 → `app` | Streamable HTTP(`/mcp/:endpoint_id`,每个端点独立 Bearer Token) | 内置 MCP Server,把空间的知识库检索等能力暴露给外部 MCP 客户端,见 [MCP 集成](../03-features/08-mcp.md) |
| Chrome 扩展 ↔ `app` | WebSocket(`/api/v1/local-browser/extension`,远程部署须 WSS) | 本机浏览器能力:app 进程托管 BrowserSkill 守护进程,扩展在用户浏览器中执行网页任务,见[本机浏览器](../05-clients/09-local-browser.md) |
| `app` ↔ IM 平台 | HTTP webhook / 长连接 SDK | 微信、企业微信、飞书、钉钉、Slack、Telegram、QQ、Mattermost、云之家(`internal/im/`) |
## 总体架构图 {#_4-总体架构图}
@ -92,7 +94,8 @@ graph LR
Browser["浏览器 (Vue3 SPA)"]
Mini["微信小程序 (miniprogram/)"]
CLI["CLI / Go SDK (cli/, client/)"]
MCPC["MCP 客户端 (mcp-server/)"]
MCPC["MCP 客户端 (内置端点 / mcp-server/)"]
EXTN["Chrome 扩展 (本机浏览器)"]
IM["IM 平台 (微信/飞书/钉钉/Slack...)"]
end
@ -118,7 +121,8 @@ graph LR
Browser -->|"HTTP / SSE"| FE
Mini -->|"HTTP"| APP
CLI -->|"HTTP"| APP
MCPC -->|"HTTP (X-API-Key)"| APP
MCPC -->|"Streamable HTTP / HTTP (X-API-Key)"| APP
EXTN -->|"WebSocket"| APP
IM -->|"webhook / SDK 长连接"| APP
FE -->|"反向代理 /api"| APP
APP -->|"gRPC ReadStream"| DR
@ -183,12 +187,12 @@ sequenceDiagram
| `internal/` | Go 后端全部业务代码(分层结构见后端设计篇):`handler`、`application/service`、`application/repository`、`container`(DI)、`router`、`middleware`、`types`、`agent`、`im`、`mcp`、`stream`、`sandbox` 等 |
| `frontend/` | Vue3 + Vite + TDesign 的 Web 前端,构建产物由 NGINX 或 Lite 模式内嵌托管 |
| `docreader/` | Python gRPC 文档解析微服务:`main.py` 服务端入口、`parser/` 25+ 解析器、`splitter/` 分割器、`proto/` 协议定义、独立 `Dockerfile.docreader` 构建 |
| `cli/` | `weknora` 命令行工具(约 30 个子命令:部署、日志、备份、诊断等) |
| `cli/` | `weknora` 命令行工具:知识库、文档、检索、会话、智能体、模型、MCP、技能等资源操作,以及 `doctor` 诊断,见 [CLI](../05-clients/02-cli.md) |
| `client/` | Go SDK:以 HTTP 客户端形式封装 WeKnora API,供二次开发集成 |
| `mcp-server/` | Python 实现的 MCP Server(`weknora_mcp_server.py`),把 WeKnora API 暴露为 MCP 工具给 Claude 等 MCP 客户端 |
| `miniprogram/` | 微信小程序客户端(WXML/WXSS/JS) |
| `migrations/` | golang-migrate 数据库迁移:`versioned/`(Postgres 主线 `NNNNNN_*.up/down.sql`)、`sqlite/`(Lite 模式)、`paradedb/`、`mysql/` |
| `config/` | 运行配置:`config.yaml` 主配置、`builtin_agents.yaml` 内置 Agent、`agent_type_presets.yaml` Agent 预设、`builtin_models.yaml.example` 声明式内置模型、`prompt_templates/` 提示词模板 |
| `config/` | 运行配置:`config.yaml` 主配置、`builtin_agents.yaml` 内置 Agent、`agent_type_presets.yaml` Agent 预设、`builtin_models.yaml.example` 声明式内置模型、`models.json.example` 模型厂商目录叠加、`prompt_templates/` 提示词模板 |
| `docker/` | 各镜像 Dockerfile(app/docreader/sandbox/odl-hybrid)与 searxng 配置 |
| `deploy/` | 裸机部署资源(systemd 服务单元等) |
| `helm/` | Kubernetes Helm Chart(Chart.yaml / values.yaml / templates/) |
@ -197,7 +201,7 @@ sequenceDiagram
| `scripts/` | 构建/启动/迁移辅助脚本(如 `start_all.sh`;`build_frontend_dist.sh` 供 Lite / 桌面打包,UI 镜像由 `frontend/Dockerfile` 多阶段构建) |
| `tests/`、`testdata/` | 集成测试与测试数据 |
| `misc/` | 杂项(如 `dex-config.yaml` OIDC 测试配置) |
| `packages/` | 预留的本地包目录 |
| `packages/` | 独立发布的集成包,如 DeepSeek Harness 插件 `packages/dsh-weknora`,见 [DeepSeek Harness](../05-clients/08-deepseek-harness.md) |
| `docs/` | 停止维护的旧文档;暂存 Swagger 生成包、发布资源和历史图片 |
> 说明:Go 模块路径为 `github.com/Tencent/WeKnora`;根目录还包含 `docker-compose.yml`(生产编排)与 `docker-compose.dev.yml`(开发编排)、`Makefile`、`VERSION` 等。

View File

@ -10,6 +10,7 @@ Go 后端以 Handler、Service、Repository 和基础设施分层组织请求处
| --- | --- | --- |
| Router / Middleware | `internal/router/`、`internal/middleware/` | 路由注册、认证、RBAC、限流、日志、错误信封 |
| Handler | `internal/handler/`(会话相关在 `internal/handler/session/`) | 解析请求参数(DTO 在 `internal/handler/dto/`)、调用 Service、写响应;不含业务逻辑 |
| 访问控制 | `internal/application/access/` | 与 Gin 无关的共享授权规则:知识库三层访问解析、组织共享权限、共享 Agent 的知识库范围、文件与消息产物授权、跨库克隆/移动授权 |
| Service | `internal/application/service/`(约 160+ 文件) | 业务编排:知识库/知识/分块、会话与 `chat_pipeline/` 流水线、Agent、租户与成员、模型、数据源同步、Wiki、审计等 |
| Repository | `internal/application/repository/`(约 60 文件) | 数据访问,统一使用 **GORM**(`type knowledgeRepository struct { db *gorm.DB }`,操作走 `r.db.WithContext(ctx)`);检索引擎的仓储实现按引擎分包于 `repository/retriever/{postgres,elasticsearch,qdrant,milvus,weaviate,doris,opensearch,tencentvectordb,sqlite,neo4j}` |
| 领域模型 | `internal/types/` | GORM 实体、枚举、context key、接口定义(`types/interfaces`) |
@ -138,13 +139,13 @@ flowchart TD
`internal/router/router.go` 的 `NewRouter(params RouterParams)`(`RouterParams` 为 `dig.In` 结构体)按以下顺序装配,**顺序即安全语义**:
1. `gin.New()` + `SetTrustedProxies`(`WEKNORA_TRUSTED_PROXIES`,默认仅信任回环与私网段,防止伪造 `X-Forwarded-For` 绕过按 IP 限流);
1. `gin.New()` + `MultipartFormCleanup`(请求结束后删除 multipart 解析落盘的临时文件)+ `SetTrustedProxies`(`WEKNORA_TRUSTED_PROXIES`,默认仅信任回环与私网段,防止伪造 `X-Forwarded-For` 绕过按 IP 限流);
2. 全局中间件:`cors` → `RequestID` → `Language` → `Logger` → `Recovery` → `ErrorHandler`;
3. 免认证端点:`GET /health`;非 release 模式挂载 `/swagger/*any`;
4. Embed 页面 `frame-ancestors` CSP 中间件;Lite 版内嵌前端静态资源(`handler.Edition == "lite"`);
5. **认证之前**注册的公开路由:IM 平台回调(`/api/v1/im`,各平台自带签名验证)、Web Embed 公开路由(`/api/v1/embed/:channel_id`,`middleware.EmbedAuth` publish-token 鉴权 + Redis 限流)、短时效能力 URL(resource grants);
5. **认证之前**注册的公开路由:IM 平台回调(`/api/v1/im`,各平台自带签名验证)、Web Embed 公开路由(`/api/v1/embed/:channel_id`,`middleware.EmbedAuth` publish-token 鉴权 + Redis 限流)、内置 MCP Server(`/mcp/:endpoint_id`,`middleware.MCPEndpointAuth` 按端点 Bearer Token 鉴权)、短时效能力 URL(resource grants)、沙箱终端/桌面 WebSocket(浏览器无法在握手时带认证头,改用经认证 POST 换取的短时 ticket)、本机浏览器扩展连接(`/api/v1/local-browser/*`);
6. `middleware.Auth(...)` 全局认证;随后是需认证的文件代理路由、免认证但签名校验的 presigned 文件路由、Langfuse trace 中间件、`AuditServiceProvider`;
7. `v1 := r.Group("/api/v1")`:先 `v1.Use(rbacGuards.apiKeyAuthorizer.Middleware())`(API Key 网关,JWT 会话直接放行),再依次调用 30 个 `RegisterXxxRoutes(v1, handler, rbacGuards)`;
7. `v1 := r.Group("/api/v1")`:先 `v1.Use(rbacGuards.apiKeyAuthorizer.Middleware())`(API Key 网关,JWT 会话直接放行),再依次调用 30 余个 `RegisterXxxRoutes(v1, handler, rbacGuards)`;
8. 收尾自检:`rbacGuards.assertAPIKeyPoliciesMatchRoutes(r)` —— 若声明的 API Key 策略指向不存在的路由模板(路径漂移/拼写错误),**启动即 panic**,避免上线一条永远 403 的死策略。
### 路由分组一览 {#_4-2-路由分组一览}
@ -157,12 +158,13 @@ flowchart TD
| `/knowledge`、`/chunks` | RegisterKnowledgeRoutes / RegisterChunkRoutes | `ingest` |
| `/sessions`、`/knowledge-chat`、`/agent-chat`、`/knowledge-search`、`/messages` | RegisterSessionRoutes / RegisterChatRoutes 等 | `chat` / `retrieve` |
| `/models`、`/evaluation` | RegisterModelRoutes / RegisterEvaluationRoutes | `manage_models` / `run_evaluations` |
| `/sandbox-configs`、`/me/env-vars`、`/me/browser` | RegisterSandboxConfigRoutes / RegisterMyEnvVarRoutes 等 | `full_access`;`/me/*` 仅 JWT 用户本人 |
| `/system`、`/system/admin` | RegisterSystemRoutes / RegisterSystemAdminRoutes | admin 组强制 `g.SystemAdmin()` |
| `/mcp-services`、`/agent`、`/web-search`、`/web-search-providers` | 对应 Register 函数 | `manage_mcp_services` / `manage_web_search` |
| `/vector-stores`、`/storage-backends` | RegisterVectorStoreRoutes / RegisterStorageBackendRoutes | `manage_vector_stores` / `manage_storage_backends` |
| `/agents`、`/agents/:id/shares|embed-channels|im-channels` | RegisterCustomAgentRoutes 等 | `full_access` / `manage_channels` |
| `/organizations`、`/user/favorites`、`/skills` | 对应 Register 函数 | `manage_spaces` 等 |
| `/im-channels`、`/embed-channels`、`/wechat` | RegisterIMChannelRoutes / RegisterEmbedChannelRoutes | `manage_channels` |
| `/im-channels`、`/embed-channels`、`/mcp-endpoints`、`/wechat` | RegisterIMChannelRoutes / RegisterEmbedChannelRoutes / RegisterMCPEndpointRoutes | `manage_channels` |
| `/datasource`、`/knowledgebase/:kb_id/wiki`、`/chunker/preview` | RegisterDataSourceRoutes / RegisterWikiPageRoutes / RegisterChunkerDebugRoutes | `manage_datasources` / `ingest` |
### rbacGuards:集中式权限矩阵 {#_4-3-rbacguards-集中式权限矩阵}
@ -188,13 +190,16 @@ kb.PUT("/:id", g.OwnedKBOrAdmin(), handler.UpdateKnowledgeBase)
| 中间件 | 文件 | 职责与关键逻辑 |
| --- | --- | --- |
| `cors.New`(gin-contrib) | router.go | 允许 `Authorization`、`X-API-Key`、`X-Tenant-ID`、`X-Embed-Session` 等头;MaxAge 12h |
| `MultipartFormCleanup()` | multipart_cleanup.go | 请求结束(含失败与 panic 恢复)后删除 multipart 表单写入系统临时目录的文件,避免容器 `/tmp` 持续增长 |
| `cors.New`(gin-contrib) | router.go | 允许 `Authorization`、`X-API-Key`、`X-Tenant-ID`、`X-Embed-Session`、`X-WeKnora-Desktop-Token` 及 MCP Streamable HTTP 所需的 `MCP-Protocol-Version`/`Mcp-Session-Id` 等头;MaxAge 12h |
| `RequestID()` | logger.go | 复用请求头 `X-Request-ID` 或生成 UUID,写入 gin context 与 `Request.Context()`,贯穿日志/追踪 |
| `Language()` | language.go | 决定文档处理语言:`WEKNORA_LANGUAGE` 环境变量 > `Accept-Language` 首个标签 > 默认 `zh-CN` |
| `Logger()` | logger.go | 请求/响应全量日志;正则脱敏密码/令牌字段、截断 base64 图片 data URL、SSE 响应标记跳过、单条上限 10KB |
| `Recovery()` | recovery.go | panic 捕获 + 堆栈记录 + 500 响应 |
| `ErrorHandler()` | error_handler.go | 读取 `c.Errors` 末位错误:`*errors.AppError` 按其 `HTTPCode` 返回 `{success:false, error:{code,message,details}}` 统一信封;其余 500 |
| `EmbedAuth(...)` | embed_auth.go | 仅挂在 `/api/v1/embed/:channel_id` 公开组:校验 publish token,注入 Embed 渠道上下文;Redis 三级限流(每 IP/分钟、渠道全局/分钟、渠道/日) |
| `MCPEndpointAuth(...)` | mcp_endpoint_auth.go | 仅挂在 `/mcp/:endpoint_id`:校验端点 Bearer Token,注入端点所属空间、机器主体与由工具白名单和知识库范围派生的 API Key 式权限范围 |
| `AttachAuthenticatedUser(...)` | ws_auth.go | 沙箱终端等 WebSocket 路由:用短时 ticket 解析出的用户建立与 `Auth` 相同的认证会话,成员与角色仍从数据库解析 |
| `PublicAuthRateLimit()` | auth_public_ratelimit.go | 免认证的邀请查询/受邀注册路由:**进程内存**滑动窗口,60s/30 次/IP,后台每 2 分钟清理过期桶,超限返回 429 |
| `Auth(...)` | auth.go | 核心认证,三态:① JWT(`Authorization: Bearer`,`userService.ValidateToken`);② API Key(`X-API-Key`,`AuthenticateAPIKey`);③ `noAuthAPI` 白名单。支持 `X-Tenant-ID` 切换租户(`IsTenantAccessible` 三层校验:自有租户/跨租户超管/active membership),`resolveTenantRole` 解析租户内角色。写入 context:`TenantIDContextKey`、`TenantInfoContextKey`、`UserContextKey`、`UserIDContextKey`、`TenantRoleContextKey`、`SystemAdminContextKey`、`PrincipalContextKey` 等 |
| `langfuse.GinMiddleware()` | tracing/langfuse | LLM 可观测 trace;未配置 LANGFUSE_* 时为 no-op |
@ -202,7 +207,7 @@ kb.PUT("/:id", g.OwnedKBOrAdmin(), handler.UpdateKnowledgeBase)
| `APIKeyRouteAuthorizer.Middleware()` | api_key_gate.go | API Key 主体的路由级网关:查 `(method, fullPath)` 策略表,校验 `PlatformOnly` / `RequireFullAccess` / `Capabilities`;未声明路由默认拒绝;JWT 用户直接透传 |
| `RequireRole(min)` 等 | rbac.go | 租户内角色下限校验(owner=40 > admin=30 > contributor=20 > viewer=10);`RequireOwnershipOrRole(min, creatorLookup)` 允许资源创建者越过角色下限;API Key 主体短路(其授权归 APIKeyGate);跨租户超管临时获得 Admin;拒绝时调用 `AuditService.LogDenied` |
| `RequireCrossTenantAccess()` / `RequirePathTenantMatch()` | access.go | 平台级操作网关与 URL 租户一致性校验 |
| `RequireKBAccess(resolver, perm, ...)` | kb_access.go | KB 三层访问解析(自有 → 组织共享 → 共享 Agent 只读),并**改写** `Request.Context()` 中的 `TenantIDContextKey` 为 KB 源租户,使下游检索自动落到正确租户的数据 |
| `RequireKBAccess(resolver, perm, ...)` | kb_access.go | 适配 `internal/application/access` 的 KB 三层访问解析(自有 → 组织共享 → 共享 Agent 只读),并**改写** `Request.Context()` 中的 `TenantIDContextKey` 为 KB 源租户,使下游检索自动落到正确租户的数据 |
| `asynqdl.Middleware()` | asynqdl/ | 非 HTTP:Asynq 任务重试预算耗尽时写入 `task_dead_letters` 表,可挂 `OnDeadLetter` 回调联动业务状态(如标记知识解析失败) |
## 领域模型总览(internal/types) {#_6-领域模型总览-internal-types}
@ -298,7 +303,7 @@ erDiagram
string id PK
uint64 tenant_id FK
string type "Embedding/Rerank/KnowledgeQA/VLLM/ASR"
string source "18+ 提供商"
string source "local / remote / 厂商标识"
json parameters "APIKey AES 加密"
}
```
@ -347,7 +352,7 @@ type AppError struct {
| `utils/crypto.go` | `EncryptAESGCM` / `DecryptAESGCM`(`enc:v1:` 前缀,幂等) | 上文所有敏感字段静态加密的底层实现 |
| `utils/security.go` | `SanitizeHTML`、`ValidateFilePath`、`SanitizeForLog` | XSS 清洗、目录穿越防护、日志脱敏 |
| `utils/inject.go` | `ValidateSQL`(基于 `pganalyze/pg_query_go`) | Agent 数据分析生成 SQL 的白名单表校验与注入模式检测 |
| `utils/presign.go` | `GeneratePresignURL` / `ValidatePresignURL` | HMAC-SHA256 预签名文件 URL(默认 2h,IM 内嵌图片使用) |
| `utils/presign.go` | `SignFileURL` / `VerifyFileURLSig`、`SystemHMACKey` | HMAC-SHA256 预签名文件 URL(默认 2h,IM 内嵌图片使用);签名密钥取 `SYSTEM_SIGNING_KEY`,未设置时回退 `SYSTEM_AES_KEY` |
| `utils/oidc_state.go` | `GenerateState` / `ValidateState` | OIDC 授权 state 的 HMAC 签名与 10 分钟 TTL(防 CSRF) |
| `utils/log_sanitize.go` | `CompactImageDataURLForLog` | 截断超长图片 data URL,防日志爆炸 |
| `utils/storage_error.go` | `SanitizeStorageConnectivityError` | 把存储连接错误转为用户友好提示并隐藏内部主机名 |

View File

@ -78,7 +78,7 @@ kb.POST("/manual", g.OwnedKBOrAdmin(), g.KBAccessWrite("id"), handler.CreateManu
`internal/application/service/knowledge_util.go` 里的 `supportedImportFileExtensions` 是**所有导入路径的唯一事实来源**——直接上传、文件 URL 下载、以及 worker 下载完成后的复检都查同一张表:
```
pdf txt docx doc epub html htm mhtml md markdown
pdf txt docx doc epub html htm mhtml md markdown xmind
png jpg jpeg gif csv xlsx xls pptx ppt json
mp3 wav m4a flac ogg
```
@ -127,7 +127,7 @@ if exists {
}
```
命中时不重复入库,返回已有 Knowledge 并附带 `DuplicateFileError`(前端据此提示"文件已存在")。`FileType` 参与判定:重复只在**同一文件类型内**成立,因此内容完全相同的 `notes.md` 与 `notes.txt` 会作为两条独立知识共存(`CheckKnowledgeExists` 在哈希与「文件名 + 大小」两条分支上都追加了 `LOWER(file_type)` 条件)。
命中时不重复入库,返回已有 Knowledge 并附带 `DuplicateFileError`(前端据此提示"文件已存在")。`parse_status` 为 `failed` 或 `deleting` 的行不参与查重,因此删除尚未完成或卡在删除中的文件可以重新上传。`FileType` 参与判定:重复只在**同一文件类型内**成立,因此内容完全相同的 `notes.md` 与 `notes.txt` 会作为两条独立知识共存(`CheckKnowledgeExists` 在哈希与「文件名 + 大小」两条分支上都追加了 `LOWER(file_type)` 条件)。
### 初始状态 {#_2-5-初始状态}
@ -200,7 +200,7 @@ type FileService interface {
```go
opts := []asynq.Option{
asynq.Queue(types.QueueDefault),
asynq.Timeout(config.DocumentProcessTimeout(cfg)), // 默认 30 分钟
asynq.Timeout(config.DocumentProcessTimeout(cfg)), // 默认 2 小时
asynq.MaxRetry(3), // 失败最多重试 3 次
}
task := asynq.NewTask(types.TypeDocumentProcess, payloadBytes, opts...)
@ -216,16 +216,21 @@ info, err := s.task.Enqueue(task)
| 队列常量 | 名称 | 用途 |
|----------|------|------|
| `QueueDefault` | `default` | 核心文档处理(解析/分块/嵌入/索引) |
| `QueueChatAttachment` | `chat_attachment` | 会话临时文档解析 |
| `QueuePostProcess` | `postprocess` | 后处理编排任务 |
| `QueueSummary` | `summary` | 摘要 / 问题生成类 LLM 任务 |
| `QueueSummary` | `summary` | 摘要、表格摘要、自动标签、知识库描述 |
| `QueueMultimodal` | `multimodal` | 图片 OCR / VLM Caption |
| `QueueMaintenance` | `low` | 维护类任务(FAQ 批量导入等) |
| `QueueQuestion` | `question` | 问题生成 |
| `QueueGraph` | `graph` | 图谱抽取 |
| `QueueWiki` | `wiki` | Wiki 生成与收尾 |
| `QueueMaintenance` | `low` | 维护类任务(FAQ 批量导入、知识库复制/删除、批量删除/重解析、移动等) |
默认并发数(`internal/types/task.go`):核心池 `DefaultCoreWorkerConcurrency = 8`、后处理池 `2`、富化池 `12`、维护池 `4`。
另有 `sync`(数据源同步)与 `memory`(个人记忆抽取)队列。默认并发数(`internal/types/task.go`):核心池 `DefaultCoreWorkerConcurrency = 8`、后处理池 `2`、富化池 `12`、维护池 `4`、弹性共享池 `6`、Wiki 池 `8`,完整拓扑见[异步任务系统](05-async-tasks.md#_4-1-六个独立-worker-pool)。
### 失败重试语义 {#_4-3-失败重试语义}
- `TypeDocumentProcess`:`MaxRetry(3)` → 初始 + 3 次重试共 4 次尝试;每次尝试受 `DocumentProcessTimeout`(默认 30 分钟)约束。
- `TypeDocumentProcess`:`MaxRetry(3)` → 初始 + 3 次重试共 4 次尝试;每次尝试受 `DocumentProcessTimeout`(默认 2 小时,环境变量 `WEKNORA_DOCUMENT_PROCESS_TIMEOUT`)约束,其中单次 docreader 调用另受 `WEKNORA_DOCREADER_CALL_TIMEOUT`(默认 30 分钟)约束。
- 处理函数内的 panic 会被转换为错误交给重试与死信流程,最后一次失败时文档标为 `failed`;Lite 模式的执行器同样捕获 panic,不会导致进程退出。
- Payload 携带 `Attempt`(重新解析时取历史最大 attempt+1);Span Tracker 用 attempt 隔离每轮处理的进度树,新 attempt 会"取代"(supersede)旧任务的收尾动作。
- 处理函数区分"是否最后一次 asynq 尝试"(`isLastRetry`):非最后一次的失败直接返回错误让 asynq 重试,最后一次才把 `ParseStatus` 落为 `failed` 并写 `ErrorMessage`。
@ -265,13 +270,13 @@ Worker 消费 `TypeDocumentProcess` 后按五个规范化阶段推进,每个
4. `resolveDocReader` 返回 `interfaces.DocReader`:
- **builtin**:通过 gRPC(`docparser/grpc_parser.go`)或 HTTP(`http_parser.go`)调用 Python **docreader** 服务;
- **simple**:Go 原生解析 md/txt/csv/json/图片/音频(`builtin_converter.go`,CSV→Markdown 表格、JSON→递归分割的代码块,图片/音频转占位引用);
- **anydoc**:Go 进程内解析 docx/doc/pptx/ppt/xlsx/xls/odf/rtf/epub/csv/pdf(`anydoc_reader.go`),底层是通过 cgo 链接的 anydoc Rust 库。office 文档的嵌入图按文档模型插回 Markdown 原位;无文字层的扫描件 PDF 在 DocReader 可用时回退到 builtin 整页渲染。仅在带 `anydoc` 构建标签的二进制中可用,其余构建里该引擎在引擎列表中显示为不可用;
- **anydoc**:Go 进程内解析 docx/doc/pptx/ppt/xlsx/xls/odf/rtf/epub/csv/pdf(`anydoc_reader.go`),底层是通过 cgo 链接的 anydoc Rust 库。office 文档的嵌入图按文档模型插回 Markdown 原位;无文字层的扫描件 PDF 在 DocReader 可用时回退到 builtin 整页渲染。链接了 anydoc 时,未配置规则的复杂格式默认走 anydoc,但 PDF 默认仍走 builtin。仅在带 `anydoc` 构建标签的二进制中可用,其余构建里该引擎在引擎列表中显示为不可用;
- **weknoracloud / mineru / mineru_cloud / paddleocr_vl / paddleocr_vl_cloud**:HTTP 转换器(`engines.go` 注册,按 `mineru_endpoint`、`mineru_api_key`、`paddleocr_vl_endpoint` 等配置判定可用性)。
引擎目录集中在 `internal/infrastructure/docparser/engines.go`:每个引擎同时声明元数据(名称、描述、文件类型、可用性探针)与 `NewReader` 工厂,`docparser.NewReader` 按名字分发,未注册的名字(如只存在于 docreader 的 `markitdown`)落到 docreader 客户端。
5. 文件模式:从 `FileService.GetFile(payload.FilePath)` 读回字节填入 `ReadRequest.FileContent`。
**docreader 服务侧**(`docreader/`,Python gRPC):proto 定义 `docreader/proto/docreader.proto`,服务方法 `Read` / `ReadStream`(流式:首帧 meta + 每图一帧,避免大扫描件 PDF 触发 gRPC 消息上限)/ `ListEngines`。内置 parser 覆盖 docx/doc/pdf/md/xlsx/xls/epub/html/htm/mhtml/图片/网页(`WebParser` 处理 URL),并可选注册 `markitdown`(微软 MarkItDown)与 `opendataloader`(PDF 版面分析,需 Java 11+)引擎,Go 侧通过 `ListEngines` 自发现远程引擎。返回统一为 `ReadResult{MarkdownContent, ImageRefs, Metadata, IsAudio, AudioData}` —— **解析产物统一是 Markdown 文本 + 图片字节**,图片持久化由 Go 侧负责。
**docreader 服务侧**(`docreader/`,Python gRPC):proto 定义 `docreader/proto/docreader.proto`,服务方法 `Read` / `ReadStream`(流式:首帧 meta + 每图一帧,避免大扫描件 PDF 触发 gRPC 消息上限)/ `ListEngines`。内置 parser 覆盖 docx/doc/pdf/md/xlsx/xls/pptx/ppt/epub/html/htm/mhtml/xmind/图片/网页(`WebParser` 处理 URL),另注册 `markitdown`(微软 MarkItDown)与 `opendataloader`(PDF 版面分析,需 Java 11+)引擎;引擎列表由 Go 侧 `engine_registry.go` 维护,Go App 不再调用 `ListEngines`。返回统一为 `ReadResult{MarkdownContent, ImageRefs, Metadata, IsAudio, AudioData}` —— **解析产物统一是 Markdown 文本 + 图片字节**,图片持久化由 Go 侧负责。
### ASR 转写(音频文件) {#_6-2-asr-转写-音频文件}
@ -315,9 +320,9 @@ if eff.ChunkingConfig.EnableParentChild {
`processChunks` 是核心装配函数:
1. **父块**(父子分块模式):为每个 parent 建 `ChunkTypeParentText` 记录,串好 `PreChunkID/NextChunkID` 链表;父块**只入 DB、不进向量索引**(检索命中子块后回捞父块内容)。
2. **文本块**:每个 `ParsedChunk` 建 `ChunkTypeText` 记录,携带 `StartAt/EndAt`(原文 rune 偏移,可用于还原/高亮)与内存态 `ContextHeader`(标题面包屑,不落库);父子模式下写 `ParentChunkID`。
2. **文本块**:每个 `ParsedChunk` 建 `ChunkTypeText` 记录,携带 `StartAt/EndAt`(原文 rune 偏移,可用于还原/高亮)与 `ContextHeader`(标题面包屑,存入 `chunks.context_header`,接口响应不返回);父子模式下写 `ParentChunkID`。分块前,各解析引擎输出的内联 HTML 表格统一转换为 Markdown 表格(`NormalizeHTMLTables`)。
3. `chunkService.CreateChunks(ctx, insertChunks)` 批量写库;失败则 `ParseStatus=failed` + `failStage(StageChunking)`。
4. **向量化与索引**(`kb.NeedsEmbeddingModel()` 时):
4. **向量化与索引**(`kb.NeedsEmbeddingModel()` 时)。Embedding 模型或知识库绑定的向量存储无法解析时(模型被删、凭据失效等),本次尝试直接失败并在 `error_message` 记录原因,不会停留在 `processing`:
```go
indexContent := titlePrefix + chunk.EmbeddingContent() // 标题 + 面包屑 + 内容
@ -329,7 +334,7 @@ err = retrieveEngine.BatchIndex(ctx, embeddingModel, indexInfoList)
```
索引失败时执行**补偿回滚**:删除已写入的 chunks(`DeleteChunksByKnowledgeID`)并清向量索引(`DeleteByKnowledgeIDList`),置 `failed`,保证不留半成品。
5. **图片多模态任务扇出**:`enableMultimodel && len(storedImages) > 0` 时,`enqueueImageMultimodalTasks` 为**每张图片**入队一个 `TypeImageMultimodal` 任务(`QueueMultimodal`),payload 含 `ImageURL/EnableOCR/EnableCaption/Attempt/ImageIndex`。
5. **图片多模态任务扇出**:`enableMultimodel && len(storedImages) > 0` 时,`enqueueImageMultimodalTasks` 为**每张图片**入队一个 `TypeImageMultimodal` 任务(`QueueMultimodal`),payload 含 `ImageURL/EnableOCR/EnableCaption/Attempt/ImageIndex`。个别图片入队失败时立即释放对应的计数;全部入队失败时直接进入后处理,避免文档卡在 `processing`。
6. `finalizeIndexedKnowledgeState`:若还有多模态/后处理要跑则保持 `processing`,否则直接 `completed`;同时置 `EnableStatus="enabled"`(此刻文档即可被检索)并累计租户存储用量。
### 后处理编排(knowledge_post_process.go,Stage: postprocess) {#_6-6-后处理编排-knowledge-post-process-go-stage-postprocess}
@ -337,18 +342,20 @@ err = retrieveEngine.BatchIndex(ctx, embeddingModel, indexInfoList)
多模态全部完成(或无多模态)后入队 `TypeKnowledgePostProcess`。该任务是**富化子任务的编排器**,用原子计数器保证终态收敛:
```go
willSpawnSummary := len(textChunks) > 0
willSpawnQuestion := willSpawnSummary && kb.NeedsEmbeddingModel() && eff.QuestionGenerationConfig.Enabled
willSpawnSummary := eff.SummaryEnabled && len(textChunks) > 0 // 单次上传可关闭摘要
willSpawnQuestion := len(textChunks) > 0 && kb.NeedsEmbeddingModel() && eff.QuestionGenerationConfig.Enabled
willSpawnWiki := kb.IndexingStrategy.WikiEnabled && len(textChunks) > 0
willSpawnGraph := eff.GraphEnabled && len(textChunks) > 0
// questionGenChunkBatchSize = 20:问题生成按每 20 个 chunk 一批
expectedSubtasks = summary(0/1) + questionBatchCount + wiki(0/1) + graphChunkCount
graphChunks := selectGraphChunks(textChunks) // 见下文
// questionGenChunkBatchSize = 20:问题生成按每 20 个 chunk 一批(跳过只有图片链接的 chunk)
expectedSubtasks = summary(0/1) + questionBatchCount + wiki(0/1) + len(graphChunks)(图谱开启时)
// 原子地把 parse_status 从 processing 提升为 finalizing,并写入 pending_subtasks_count
promoted, err := s.knowledgeRepo.SetFinalizing(ctx, payload.KnowledgeID, expectedSubtasks)
```
- `expectedSubtasks == 0` 走快速路径直接 `completed`。
- 图谱抽取的输入(`selectGraphChunks`):有正文的文本块;只有图片链接的文本块(如扫描件 PDF 页)改用其 `image_ocr` 子块;`image_caption` 子块不参与,避免与 OCR 重复。
- `processing → finalizing` 的状态写入失败时任务返回错误交给 asynq 重试,不会误报成功而让文档停在 `processing`。
- 每个子任务终态退出时调用 `FinalizeSubtask` 原子递减 `pending_subtasks_count`,减到 0 时自动升级为 `completed`。
- **短缺协调**:若实际入队数少于计划数(如某队列入队失败),立即补偿递减差额,防止永远卡在 `finalizing`。
- `finalizeSubtaskDetached`(`knowledge.go`):递减动作使用 `context.WithoutCancel` + 10 秒超时的**脱离上下文**执行,避免 worker 优雅退出时 ctx 取消导致计数丢失、知识永久滞留 `finalizing`。
@ -357,7 +364,7 @@ promoted, err := s.knowledgeRepo.SetFinalizing(ctx, payload.KnowledgeID, expecte
| 任务 | 队列 | 粒度 | 说明 |
|------|------|------|------|
| `TypeSummaryGeneration` | `summary` | 每知识 1 个 | 生成文档摘要,`summary_status` 独立状态机 |
| `TypeSummaryGeneration` | `summary` | 每知识 1 个 | 生成文档摘要,`summary_status` 独立状态机;上传时 `process_config.summary_enabled=false` 则不生成 |
| `TypeQuestionGeneration` | question 队列 | 每 20 个 chunk 一批 | 为 chunk 生成检索问题 |
| `TypeChunkExtract` | graph 队列 | 每 chunk 1 个 | 实体/关系抽取写入图引擎 |
| `TypeWikiIngest` | wiki 队列 | 防抖批量 | 生成/更新 Wiki 页面 |
@ -402,7 +409,7 @@ promoted, err := s.knowledgeRepo.SetFinalizing(ctx, payload.KnowledgeID, expecte
| `finalizing` | 主流程完成,等待富化子任务(`pending_subtasks_count > 0`) |
| `completed` | 全部完成 |
| `failed` | 处理失败(`ErrorMessage` 记录原因) |
| `deleting` | 删除中(防并发标记) |
| `deleting` | 删除中(防并发标记;不计入知识库文档数,也不参与重复文件判定) |
| `cancelled` | 用户取消解析 |
辅助状态:`EnableStatus ∈ {enabled, disabled}`(是否可检索,索引成功即 enabled,不等富化);`SummaryStatus ∈ {none, pending, processing, completed, failed}`。
@ -425,6 +432,7 @@ stateDiagram-v2
failed --> deleting: DeleteKnowledge
processing --> failed: housekeeping 判定卡死<br/>心跳超时且无排队任务
finalizing --> failed: housekeeping 判定卡死
deleting --> failed: housekeeping 判定删除任务丢失
deleting --> [*]: 清理完成后删除 DB 行
```
@ -461,6 +469,10 @@ task stuck in processing at docreader stage: no progress since 2026-09-22T09:37:
**Sweep B —— 摘要卡死恢复**:`summary_status = 'processing' AND updated_at < 1 小时前` → 置 `failed`。
**Sweep C —— 删除卡死恢复**:`parse_status = 'deleting'` 且超过阈值、队列中也没有覆盖它的 `knowledge:list_delete` 任务时,置为 `failed` 并写明原因,文档重新出现在列表中,用户可以再次删除。探测队列失败时顺延到下一轮,Lite 模式没有排队任务,按实际情况直接恢复。
**Wiki 队列兜底**:只因 Wiki 持久队列未消费而停在 `finalizing` 的文档,巡检会为对应知识库重新触发一次 Wiki 生成(同一知识库每个阈值周期最多一次)。Wiki 任务触发时若发现知识库已关闭 Wiki、没有合成模型或模型已删除,会清空尚未认领的 Wiki 操作并释放对应文档,使其正常结束 `finalizing`。
## 删除清理链路(knowledge_delete.go) {#_9-删除清理链路-knowledge-delete-go}
`DeleteKnowledge(ctx, id)` 的顺序经过精心设计(**先删行、后删文件**,失败可重试):
@ -538,7 +550,7 @@ type FAQChunkMetadata struct {
| 环节 | 源码位置 |
|------|----------|
| HTTP 入口 | `internal/handler/knowledge.go`、`internal/router/router.go` |
| HTTP 入口 | `internal/handler/knowledge.go`、`internal/router/routes_knowledge.go` |
| 创建与入队 | `internal/application/service/knowledge_create.go`、`knowledge_task_options.go` |
| 文件存储 | `internal/application/service/file/`(`factory.go`、各后端实现) |
| 解析基础设施 | `internal/infrastructure/docparser/`、`docreader/`(Python 服务) |

View File

@ -9,10 +9,10 @@ WeKnora 的问答链路是一条**事件驱动的插件管线(Event-Driven Plu
```mermaid
flowchart TD
subgraph HTTP["HTTP 层 (internal/handler/session)"]
A1["POST /sessions/:id/knowledge-qa"]
A2["POST /sessions/:id/agent-qa"]
A3["GET /sessions/continue-stream/:id"]
A4["POST /sessions/:id/stop"]
A1["POST /knowledge-chat/:session_id"]
A2["POST /agent-chat/:session_id"]
A3["GET /sessions/continue-stream/:session_id"]
A4["POST /sessions/:session_id/stop"]
end
subgraph Setup["SSE 装配 (qa.go executeQA / setupSSEStream)"]
@ -25,6 +25,7 @@ flowchart TD
subgraph Pipeline["事件驱动 Pipeline (session_knowledge_qa.go)"]
C0["LOAD_HISTORY"]
CM["MEMORY_RECALL 长期记忆召回"]
C1["QUERY_UNDERSTAND 改写+意图+实体"]
C2["CHUNK_SEARCH_PARALLEL 并行检索"]
C3["CHUNK_RERANK 重排+Wiki加权"]
@ -45,7 +46,7 @@ flowchart TD
A1 --> Setup
A2 --> Setup
Setup --> C0 --> C1 --> C2 --> C3 --> C4 --> C5 --> C6 --> C7 --> C8 --> C9
Setup --> C0 --> CM --> C1 --> C2 --> C3 --> C4 --> C5 --> C6 --> C7 --> C8 --> C9
C9 --> D1 --> D2 --> D3 --> D4
A3 --> D3
A4 --> D3
@ -86,10 +87,12 @@ must(container.Invoke(chatpipeline.NewPluginChatCompletionStream)) // CHAT_COMPL
must(container.Invoke(chatpipeline.NewPluginFilterTopK)) // FILTER_TOP_K
must(container.Invoke(chatpipeline.NewPluginQueryUnderstand)) // QUERY_UNDERSTAND(链外层)
must(container.Invoke(chatpipeline.NewPluginLoadHistory)) // LOAD_HISTORY
must(container.Invoke(chatpipeline.NewPluginMemoryRecall)) // MEMORY_RECALL
must(container.Invoke(chatpipeline.NewPluginExtractEntity)) // QUERY_UNDERSTAND(链内层)
must(container.Invoke(chatpipeline.NewPluginSearchEntity)) // ENTITY_SEARCH
must(container.Invoke(chatpipeline.NewPluginSearchParallel)) // CHUNK_SEARCH_PARALLEL
must(container.Invoke(chatpipeline.NewPluginWikiBoost)) // CHUNK_RERANK(链内层)
must(container.Invoke(chatpipeline.NewPluginWikiBoost)) // CHUNK_RERANK(链中层)
must(container.Invoke(chatpipeline.NewPluginMemoryAffinity)) // CHUNK_RERANK(链最内层)
```
事件与插件的完整映射(含同事件链序):
@ -97,11 +100,12 @@ must(container.Invoke(chatpipeline.NewPluginWikiBoost)) // CHUNK_RERA
| EventType | 插件(按链序) | 源文件 |
|-----------|---------------|--------|
| `load_history` | PluginLoadHistory | `load_history.go` |
| `memory_recall` | PluginMemoryRecall | `memory_recall.go` |
| `query_understand` | PluginQueryUnderstand → PluginExtractEntity | `query_understand.go`、`extract_entity.go` |
| `chunk_search` | PluginSearch | `search.go`、`query_expansion.go` |
| `chunk_search_parallel` | PluginSearchParallel(内部组合 PluginSearch + PluginSearchEntity) | `search_parallel.go` |
| `entity_search` | PluginSearchEntity | `search_entity.go` |
| `chunk_rerank` | PluginRerank → PluginWikiBoost | `rerank.go`、`wiki_boost.go` |
| `chunk_rerank` | PluginRerank → PluginWikiBoost → PluginMemoryAffinity | `rerank.go`、`wiki_boost.go`、`memory_affinity.go` |
| `web_fetch` | PluginWebFetch | `web_fetch.go` |
| `chunk_merge` | PluginMerge | `merge.go`、`merge_overlap.go`、`merge_expand.go`、`merge_faq.go`、`merge_history.go` |
| `data_analysis` | PluginDataAnalysis | `data_analysis.go` |
@ -128,15 +132,17 @@ must(container.Invoke(chatpipeline.NewPluginWikiBoost)) // CHUNK_RERA
// 纯聊天(无 KB 且未开 Web 搜索)
pipeline = types.NewPipelineBuilder().
AddIf(hasHistory, types.LOAD_HISTORY).
Add(types.MEMORY_RECALL).
Add(types.CHAT_COMPLETION_STREAM).Build()
// RAG
pipeline = types.NewPipelineBuilder().
AddIf(hasHistory, types.LOAD_HISTORY).
Add(types.MEMORY_RECALL).
Add(types.QUERY_UNDERSTAND).
Add(types.CHUNK_SEARCH_PARALLEL).
Add(types.CHUNK_RERANK).
AddIf(req.WebSearchEnabled, types.WEB_FETCH).
AddIf(webSearchEnabled, types.WEB_FETCH).
Add(types.CHUNK_MERGE).
Add(types.FILTER_TOP_K).
AddIf(chatManage.DataAnalysisEnabled, types.DATA_ANALYSIS).
@ -168,6 +174,10 @@ pipeline = types.NewPipelineBuilder().
注意:历史 user 消息回放的是原始 `Content` 而非 `RenderedContent`(避免旧版上下文封套混入当前协议),历史引用单独经 `merge_history.go` 注入。
### MEMORY_RECALL — 召回长期记忆 {#_3-1a-memory-recall}
`memory_recall.go`。空间启用长期记忆时,按当前问题召回调用者的记忆写入 `chatManage.MemoryPrompt`,并发出 `memory_recalled` 事件,供前端展示本轮用到的记忆。该阶段不调用模型,失败不阻断问答。记忆的开关与管理见[跨会话长期记忆](../03-features/23-memory.md)。
### QUERY_UNDERSTAND — 查询改写 + 意图识别(+ 实体抽取) {#_3-2-query-understand-—-查询改写-意图识别-实体抽取}
同一事件上串联两个插件:
@ -216,7 +226,9 @@ pipeline = types.NewPipelineBuilder().
5. **FAQ 加权**:`FAQPriorityEnabled` 且 `FAQScoreBoost > 1.0` 时,FAQ chunk 分数乘以 boost(上限 1.0),记 `Metadata["faq_boosted"]`。
6. **MMR 多样性选择** `applyMMR`(λ=0.7,k=`RerankTopK`):`mmr = 0.7*relevance - 0.3*max_jaccard_redundancy`,用 `searchutil.TokenizeSimple` + `Jaccard` 并行预计算 token 集合,迭代贪心选出 `RerankResult`。
**PluginWikiBoost**(`wiki_boost.go`)注册在同事件链内层,OnEvent 先 `next()`(等重排完成)再后置处理:若 `RerankResult` 中存在 `wiki_page` 类型 chunk 且检索目标中确有开启 Wiki 的 KB,则分数乘 `wikiBoostFactor = 1.3` 并稳定重排序——Wiki 页面是 LLM 预综合的知识,优先于原始 chunk。
**PluginMemoryAffinity**(`memory_affinity.go`)注册在链的最内层,同样先 `next()` 再后置处理:对该调用者过往回答中至少引用过 2 次的文档,按使用次数对数增长加权,最高 ×1.15,只用于在相近候选之间打破平局。随后才轮到 WikiBoost 的后置加权。
**PluginWikiBoost**(`wiki_boost.go`)注册在同事件链中层,OnEvent 先 `next()`(等重排完成)再后置处理:若 `RerankResult` 中存在 `wiki_page` 类型 chunk 且检索目标中确有开启 Wiki 的 KB,则分数乘 `wikiBoostFactor = 1.3` 并稳定重排序——Wiki 页面是 LLM 预综合的知识,优先于原始 chunk。
### WEB_FETCH — 网页全文抓取 {#_3-5-web-fetch-—-网页全文抓取}
@ -274,6 +286,7 @@ pipeline = types.NewPipelineBuilder().
- `ResponseTypeThinking` → 经 `modelcontext.StreamDecoder`(同一个解码器既还原 res:// 资源别名,也展开 ref 引用标签)后以 `EventAgentThought` 发出;
- `ResponseTypeAnswer` → 同样解码后以 `EventAgentFinalAnswer` 发出。带 `Done` 的终态回答**只转发一次**:部分厂商会先按 `finish_reason` 发一次完成、再按流结束哨兵发一次,重复转发会让答案事件排到会话 complete 事件之后;
- **截断**:`finish_reason` 为 `length` / `max_tokens` / `max_output_tokens`(不区分大小写)时,答案事件带 `truncated`,前端在回答旁提示内容被截断;若截断前没有产出任何文本,则以一段固定提示作为回答,建议缩小问题或调大 `max_completion_tokens`。检索无结果时的模型兜底回答(`handleFallbackResponse`)同样处理;
- `ResponseTypeError` → `EventError`;
- 通道关闭或 ctx 取消时 `flushDecoders` 冲刷解码器缓存的尾部字节(跨 chunk 的别名不丢失)再关闭 thinking 流。
@ -283,8 +296,9 @@ pipeline = types.NewPipelineBuilder().
```mermaid
flowchart TD
Q["用户查询 POST knowledge-qa"] --> P0["LOAD_HISTORY 按 RequestID 配对历史"]
P0 --> P1["QUERY_UNDERSTAND"]
Q["用户查询 POST knowledge-chat"] --> P0["LOAD_HISTORY 按 RequestID 配对历史"]
P0 --> PM["MEMORY_RECALL 注入长期记忆"]
PM --> P1["QUERY_UNDERSTAND"]
P1 --> P1a["LLM 改写 + 意图分类 + 图片描述"]
P1a --> INT{"NeedsRetrieval 判定"}
P1 --> P1b["ExtractEntity 图谱实体抽取 NEO4J_ENABLE"]
@ -305,7 +319,8 @@ flowchart TD
P3a --> P3b["Rerank 模型打分, 阈值过滤/降级/top1 兜底"]
P3b --> P3c["复合分 0.6 model + 0.3 base + 0.1 source"]
P3c --> P3d["FAQ boost + MMR lambda 0.7"]
P3d --> P3e["WikiBoost x1.3 后置加权"]
P3d --> P3m["MemoryAffinity 常用文档 最多 x1.15"]
P3m --> P3e["WikiBoost x1.3 后置加权"]
P3e --> P4["WEB_FETCH 前 N 网页抓全文"]
P4 --> P5["CHUNK_MERGE 八步融合"]
P5 --> P5a["历史引用注入 + 父子块解析"]
@ -324,7 +339,8 @@ flowchart TD
### Session Service(`session.go`) {#_5-1-session-service-session-go}
- CRUD 全套:`CreateSession` / `GetSession`(租户+共享范围)/ `GetOwnedSession`(严格属主,用于 stop 等破坏性操作)/ 分页列表 / `SetSessionPinned` / `UpdateSessionLastRequestState`(记忆输入栏状态:Agent/模型/KB/Web 搜索选择,纯 UI 用)/ 单删、批删、清空。
- CRUD 全套:`CreateSession` / `GetSession`(租户+共享范围)/ `GetOwnedSession`(严格属主,用于 stop 等破坏性操作)/ 分页列表 / `SetSessionPinned` / `UpdateSessionLastRequestState`(记忆输入栏状态:Agent/模型/KB/Web 搜索/思考强度等选择,纯 UI 用)/ 单删、批删、清空。
- **分叉与回退**:`session_fork.go` 把历史复制到新会话(记录 `parent_session_id` / `forked_from_message_id`),`session_rewind.go` 原地删除回退点之后的消息;两者都借助每轮结束时写入的沙箱工作区 git 检查点(`workspace_checkpointer.go`)恢复 `/workspace`,接口见[会话与聊天 API](../04-api/02-api-chat.md)。
- **标题生成**:`GenerateTitleAsync` 在 SSE 装配阶段异步触发(会话无标题时),用 `generate_session_title.yaml` 模板调用对话同款模型,结果经 `EventSessionTitle` 事件流出(SSE `response_type=session_title`),HTTP 层在 complete 后最多再等 3 秒接收标题事件。
### Message Service(`message.go`) {#_5-2-message-service-message-go}
@ -371,26 +387,32 @@ type StreamResponse struct {
}
```
`response_type` 完整清单(`internal/types/chat.go`,另有 handler 层使用的 `stop`):
`response_type` 完整清单(`internal/types/chat.go`,另有 handler 层使用的 `stop`;`steer` 只存在于服务端的排队子列表,不会出现在 SSE 中):
| response_type | 含义 |
|---------------|------|
| `agent_query` | 查询已受理,携带 `session_id` / `assistant_message_id`(客户端由此拿到续传所需的 message_id) |
| `thinking` | 思考过程增量(reasoning_content) |
| `answer` | 回答文本增量 |
| `answer` | 回答文本增量;因模型单次输出上限截断时带 `data.truncated: true` |
| `references` | 知识引用列表(`knowledge_references` 字段) |
| `tool_call` / `tool_result` | Agent/进度工具调用与结果(RAG 管线的 `knowledge_search`、`query_understand` 进度也走这两类) |
| `tool_call` / `tool_result` | Agent/进度工具调用与结果(RAG 管线的 `knowledge_search`、`query_understand` 进度也走这两类);工具执行失败也以 `tool_result` 返回,`data.success=false` |
| `command_output` / `install_output` | 命令执行 / 技能安装过程中的增量输出,只更新进行中的工具卡片 |
| `reflection` | Agent 反思 |
| `session_title` | 异步生成的会话标题 |
| `error` | 错误(`Done=true` 表示终局错误) |
| `error` | 整轮执行失败(`Done=true` 表示终局错误);单个工具失败不走此类型 |
| `complete` | 流结束标记(前端以此收尾,不再依赖空 answer+done) |
| `tool_approval_required` / `tool_approval_resolved` | 危险 MCP 工具审批请求/结果 |
| `mcp_oauth_required` / `mcp_oauth_resolved` | MCP OAuth 授权请求/结果 |
| `memory_recalled` | 本轮注入的长期记忆 |
| `artifacts_pending` | 回答已结束、沙箱产物仍在持久化,文件列表随 `complete` 下发 |
| `user_message_injected` | 运行中追加的消息已送达智能体并写入历史 |
| `context_compacted` | 智能体上下文发生压缩 |
| `install_prompt` | 技能安装记录的首条事件(安装指令) |
| `stop` | 用户停止通知(handler 层构造) |
### 断线续传(continue-stream)与停止 {#_6-4-断线续传-continue-stream-与停止}
**续传**:`GET /sessions/continue-stream/:session_id?message_id=...`(`stream.go` ContinueStream)。校验会话与消息后,从 offset 0 `GetEvents` **重放全部历史事件**;若已含 `complete` 直接收尾,否则继续 100ms 轮询推送新事件直到 complete——由于生成 goroutine 与 SSE 连接完全解耦(事件写在 StreamManager),刷新页面/网络闪断都不会中断生成。
**续传**:`GET /sessions/continue-stream/:session_id?message_id=...`(`stream.go` ContinueStream)。校验会话与消息后,从 offset 0 `GetEvents` **重放全部历史事件**(`continue_stream_coalesce.go` 把同一事件 ID 下连续的未完成 answer/thinking/reflection 增量合并为一帧再发送,避免长回答重放成数万帧);若已含 `complete` 直接收尾,否则继续 100ms 轮询推送新事件直到 complete——由于生成 goroutine 与 SSE 连接完全解耦(事件写在 StreamManager),刷新页面/网络闪断都不会中断生成。
**停止**:`POST /sessions/:id/stop`(严格属主校验)向 StreamManager 追加 `stop` 事件;两条路径消费它:SSE 轮询循环检测到即向 EventBus 发 `EventStop`;独立的 `startStopWatcher`(300ms 轮询,与客户端连接无关,2 小时兜底超时)保证客户端已断开时 stop 依然能取消生成。`setupStopEventHandler` 收到 `EventStop` 后 `cancel()` asyncCtx,并用 `context.WithoutCancel` 保存已流出的部分内容。
@ -406,7 +428,7 @@ sequenceDiagram
participant P as Pipeline KnowledgeQAByEvent
participant L as LLM ChatStream
C->>H: POST /sessions/:id/knowledge-qa
C->>H: POST /knowledge-chat/:session_id
H->>H: 创建 user+assistant Message
H->>M: AppendEvent agent_query
H->>B: 创建 EventBus + asyncCtx
@ -502,6 +524,7 @@ FAQ 在管线侧的配套策略(Agent 配置 `FAQPriorityEnabled` / `FAQScoreB
| `generate_session_title.yaml` | — | 会话标题异步生成(`session.go GenerateTitle`) |
| `keywords_extraction.yaml` | `PromptTemplates.KeywordsExtraction` | 关键词提取模板(租户模板 API 暴露) |
| `generate_questions.yaml` / `generate_summary.yaml` | — | 入库富化(问题生成/摘要,见文档入库文档) |
| `generate_kb_description.yaml` | `Conversation.GenerateKBDescriptionPrompt` | 根据文档画像生成知识库描述 |
| `graph_extraction.yaml` | `ExtractManager.ExtractEntity/ExtractGraph` | 查询实体抽取(`extract_entity.go`)与图谱构建 |
| `agent_system_prompt.yaml` | — | Agent 模式 system prompt(见 Agent 文档) |

View File

@ -7,7 +7,7 @@
WeKnora 有两种任务执行模式,通过部署形态选择:
- **asynq 模式(标准部署)**:任务经 `asynq.Client` 序列化为 JSON payload 写入 Redis 队列,由多个独立的 `asynq.Server`(worker pool)消费。`internal/router/task.go` 中 `RunAsynqServer()` 构建统一的 `asynq.ServeMux` 并在 6 个 pool 上运行。
- **Lite 模式(单机 / macOS App,无 Redis)**:`internal/router/sync_task.go` 的 `SyncTaskExecutor` 实现同一个 `interfaces.TaskEnqueuer` 接口,`Enqueue` 直接把任务派发到 goroutine 执行,支持 `ProcessIn`(延迟)与 `MaxRetry` 选项;重试为线性退避(`attempt * 5s`,上限 30s)。
- **Lite 模式(单机 / macOS App,无 Redis)**:`internal/router/sync_task.go` 的 `SyncTaskExecutor` 实现同一个 `interfaces.TaskEnqueuer` 接口,`Enqueue` 直接把任务派发到 goroutine 执行,支持 `ProcessIn`(延迟)与 `MaxRetry` 选项;重试为线性退避(`attempt * 5s`,上限 30s)。handler 内的 panic 会被捕获并按失败处理,不会导致进程退出。
```go
// internal/router/sync_task.go
@ -168,19 +168,21 @@ flowchart LR
subgraph MW["ServeMux 中间件链 (安装顺序)"]
M1["1. asynqdl 死信中间件<br/>(最先安装, 看到原始错误)"]
M2["2. backgroundTaskMiddleware<br/>(标记后台任务, 模型并发治理)"]
M3["3. langfuse.AsynqMiddleware<br/>(trace 续接 + SPAN 包裹)"]
M1b["2. asynqdl.RecoverMiddleware<br/>(panic 转为任务错误)"]
M2["3. backgroundTaskMiddleware<br/>(标记后台任务, 模型并发治理)"]
M3["4. langfuse.AsynqMiddleware<br/>(trace 续接 + SPAN 包裹)"]
end
Workers --> MW --> H["业务 Handler<br/>(KnowledgeService.ProcessDocument 等)"]
```
### 中间件治理 {#_4-3-中间件治理}
`RunAsynqServer`(`internal/router/task.go`)在同一个 mux 上按顺序安装三个中间件:
`RunAsynqServer`(`internal/router/task.go`)在同一个 mux 上按顺序安装四个中间件:
1. **`asynqdl.MiddlewareWithCallback`(死信)** — 必须最先安装,以便看到 handler 返回的原始错误(后续中间件可能转换错误)。见[失败重试与死信处理](#_7-失败重试与死信处理)。
2. **`backgroundTaskMiddleware`** — 对每个任务 context 打 `types.WithBackgroundTask` 标记,使 per-model 聊天并发治理器(chat concurrency governor)对 ingestion/enrichment 的 LLM 调用限流,但不影响交互式用户聊天。
3. **`langfuse.AsynqMiddleware`** — Langfuse 关闭时为直通;开启时续接上游 HTTP trace 或新开独立 trace,将 handler 执行包成 SPAN。
2. **`asynqdl.RecoverMiddleware`** — 把 handler 的 panic 转为普通任务错误。asynq 自身只在所有中间件之外恢复 panic,不经过它时死信回调看不到错误,最后一次尝试的文档会一直停在 `processing`。
3. **`backgroundTaskMiddleware`** — 对每个任务 context 打 `types.WithBackgroundTask` 标记,使 per-model 聊天并发治理器(chat concurrency governor)对 ingestion/enrichment 的 LLM 调用限流,但不影响交互式用户聊天。
4. **`langfuse.AsynqMiddleware`** — Langfuse 关闭时为直通;开启时续接上游 HTTP trace 或新开独立 trace,将 handler 执行包成 SPAN。
### 重试退避策略 {#_4-4-重试退避策略}
@ -255,7 +257,8 @@ stateDiagram-v2
- 取消流程分三阶段(`cancelMatchingTasks`):① 先删干净排队态;② 快照 active 任务后调用 `Inspector.CancelProcessing` 发信号,并在 1s 的 settle 窗口内轮询(25ms 间隔)删除因 `context.Canceled` 转入 retry 的记录(`deleteCancelledTransitions`);③ 再扫一遍排队态,兜住取消期间新入队的下游任务。
- `CancelTasksForKnowledgeBase`:KB 删除后的孤儿任务清理;`kb:delete` 与 `index:delete` 明确排除(它们携带快照、负责真正的存储清理,删掉会泄漏资源)。clone/move 的语义 KB 字段(`source_id`/`target_id`/`source_kb_id`/`target_kb_id`)也参与匹配。
- 一切均为 best-effort:Redis 抖动时记 Warn 日志并吞掉,取消 API 依然返回成功。
- `HasQueuedTasksForKnowledge`:只读探测,housekeeping 清扫用它区分"积压但未孤儿"的行,避免误标 failed。
- `HasQueuedTasksForKnowledge`:只读探测,housekeeping 清扫用它区分"积压但未孤儿"的行,避免误标 failed。`HasQueuedDeleteTasksForKnowledge` 专门匹配 `knowledge:list_delete` 的批量 payload,供删除卡死恢复使用。
- `QueuedKnowledgeIDs`:一次扫描全部队列,返回仍被排队任务引用的知识 ID 集合;知识列表接口据此给出 `stall_state`(`queued` / `stalled`),结果缓存 60 秒并在并发请求间共享,扫描失败不缓存。
### 运维面板(SystemAdmin Runtime Dashboard) {#_6-2-运维面板-systemadmin-runtime-dashboard}
@ -264,7 +267,7 @@ stateDiagram-v2
- 任务动作由 `runtimeTaskActions` 状态检查约束:`cancel`(pending/active/scheduled/retry 且可取消类型)、`run_now`(scheduled/retry/archived,asynq 保留重试计数)、`delete`(仅 archived);另有 `PurgeArchivedRuntimeTasks` 一键清空单队列 archived 集合。
- `WorkerServerStats()`:读取 asynq server 心跳(并发、活跃 worker 数、状态、队列权重),跨副本聚合后区分"配置的单实例容量"与"实际集群容量"。
对应 HTTP API(`internal/router/router.go`,SystemAdmin + 平台 API Key capability 门控):
对应 HTTP API(`internal/router/routes_auth_tenant.go`,SystemAdmin + 平台 API Key capability 门控):
| 方法 | 路径 | 说明 |
| --- | --- | --- |
@ -280,14 +283,15 @@ stateDiagram-v2
- 只在**最后一次尝试**失败时(`isFinalAttempt`:`retried >= max_retry`)写一行 `task_dead_letters`,避免瞬时抖动每次都产生一行。
- `buildDeadLetter` 用宽容的 `payloadProbe` 从任意 payload 提取 `tenant_id` / `knowledge_base_id` / `kb_id` / `knowledge_id` / `source_kb_id`,`inferScope` 按"爆炸半径"推断 scope(`knowledge_base` > `knowledge` > `tenant` > `unknown`)。payload 原样保留(可用于将来重放),`last_error` 截断到 8KB。
- 插入是 best-effort:DB 失败只记日志,原始任务错误始终原样向 asynq 上抛(进入 archived)。
- `OnDeadLetter` 回调(`internal/router/task.go` 的 `newDeadLetterKnowledgeFailer`):`document:process` / `knowledge:post_process` / `manual:process` 耗尽重试时,单条 UPDATE 把知识行 `parse_status=failed` + `error_message` 一并写入(避免半更新),并调用 `SpanTracker.FinalizeAttempt` 关闭对应 attempt 的根 span,让时间线不再显示"进行中"。`knowledge:list_delete` 有专门分支 `markKnowledgeListDeleteFailed`。`image:multimodal` 不标记父知识失败(finalize-on-last-attempt 已保证进度)。回调用 `context.Background()` 执行且 panic 被捕获,绝不改变原始任务错误。
- `OnDeadLetter` 回调(`internal/router/task.go` 的 `newDeadLetterKnowledgeFailer`):`document:process` / `knowledge:post_process` / `manual:process` 耗尽重试时,仅当知识行仍处于 `pending` / `processing` / `finalizing` 且租户、知识库与 payload 一致时,以一次条件更新把 `parse_status=failed` + `error_message` 一并写入(避免半更新,也不会覆盖已取消或删除的行;以 `SkipRetry` 结束的任务不触发),并调用 `SpanTracker.FinalizeAttempt` 关闭对应 attempt 的根 span,让时间线不再显示"进行中"。`knowledge:list_delete` 有专门分支 `markKnowledgeListDeleteFailed`。`image:multimodal` 不标记父知识失败(finalize-on-last-attempt 已保证进度)。回调用 `context.Background()` 执行且 panic 被捕获,绝不改变原始任务错误。
### 持久化任务队列与服务级死信(`internal/application/repository/task_queue.go`) {#_7-2-持久化任务队列与服务级死信-internal-application-repository-task-queue-go}
`task_pending_ops` 表是 Redis list 队列的持久化替代(重启不丢、无 TTL 驱逐),队列身份是 `(task_type, scope, scope_id)` 三元组,目前主要消费者是 Wiki ingest:
- `Enqueue` / `EnqueueIfKnowledgeBaseActive`:后者在事务中用 Postgres `SHARE` 行锁校验 KB 仍存活,防止 KB 软删后仍写入新的持久化工作。
- `ClaimBatch`:按 `dedup_key`(=文档)**整组**原子认领。核心不变量:同一文档的多个 op(如 ingest 后跟 retract)绝不拆到两个并发批次;有新鲜 claim(`claimed_at >= staleBefore`)的 key 整体跳过,晚到的兄弟 op 等待持有者完成或 claim 过期。Postgres 上用每个 key 的 anchor 行 `FOR UPDATE SKIP LOCKED` 保证并发认领者拿到**不相交**的 key 集;SQLite(Lite/测试)依赖单写者引擎。
- `Enqueue` / `EnqueueIfKnowledgeBaseActive`:后者在事务中用 Postgres `SHARE` 行锁校验 KB 仍存活、且所属租户未被软删除,防止 KB 或租户删除后仍写入新的持久化工作。
- **已删除租户**:租户删除只做软删除,其知识库与 `task_pending_ops` 行仍在。服务启动恢复时会清理已软删除租户的待处理行;Wiki ingest / finalize 任务在调用模型前检查租户是否存活,租户已删除则丢弃该知识库的队列,不再产生模型请求。
- `ClaimBatch`:按 `dedup_key`(=文档)**整组**原子认领。核心不变量:同一文档的多个 op(如 ingest 后跟 retract)绝不拆到两个并发批次;有新鲜 claim(`claimed_at >= staleBefore`)的 key 整体跳过,晚到的兄弟 op 等待持有者完成或 claim 过期。Postgres 上用每个 key 的 anchor 行 `FOR UPDATE SKIP LOCKED` 保证并发认领者拿到**不相交**的 key 集;SQLite(Lite/测试)依赖单写者引擎。认领顺序为 `fail_count` 升序、同失败次数内按入队先后:反复失败的文档不会一直排在队首,新文档不会被饿死(Lite 模式的 `PeekBatch` 同序)。
- `IncrFailCount`(`UPDATE ... RETURNING` 单往返原子自增)配合服务侧上限(wiki 的 `wikiMaxFailRetries`):超限后该 op 从 `task_pending_ops` 移入 `task_dead_letters`(`internal/application/service/wiki_ingest.go` 直接 `deadLetterRepo.Insert`)。
- `ReleaseByIDs` / `DeleteByIDs` / `DeleteByScope` / `DeleteByDedupKey` / `PendingCount` 提供释放、消费确认、KB 生命周期清理与积压观测。
@ -295,7 +299,18 @@ stateDiagram-v2
### 兜底:housekeeping 清扫 {#_7-3-兜底-housekeeping-清扫}
`internal/application/service/knowledge_housekeeping.go`:cron 每 5 分钟(`0 */5 * * * *`)扫描卡在 `pending`/`processing`/`finalizing` 超过 stale 阈值的知识行并标记 failed。这是 asynq 重试、死信回调、multimodal finalize 之外的最后防线(worker 被 kill 在 handler 中间、defer 没跑到等场景)。清扫结合 span 心跳、`updated_at` 与 `TaskInspector.HasQueuedTasksForKnowledge`,避免误杀"积压但未孤儿"的行。可用 `WEKNORA_HOUSEKEEPING_ENABLED=false` 关闭。
`internal/application/service/knowledge_housekeeping.go`:cron 每 5 分钟(`0 */5 * * * *`)运行一轮,是 asynq 重试、死信回调、multimodal finalize 之外的最后防线(worker 被 kill 在 handler 中间、defer 没跑到等场景)。可用 `WEKNORA_HOUSEKEEPING_ENABLED=false` 关闭。
阈值为 `max(1h, WEKNORA_DOCUMENT_PROCESS_TIMEOUT) + 10min`。每轮包含:
| 清扫 | 对象 | 处理 |
| --- | --- | --- |
| 解析卡死 | `pending` / `processing` / `finalizing` 超过阈值,span 心跳也超过阈值,且 asynq 队列和 Wiki 持久队列中都没有相关任务 | 置 `failed`,`error_message` 写明停在哪个阶段及最后进展时间;最新一次 attempt 中未结束的 span 以 `TASK_STALLED` 关闭(卡住的阶段为 `failed`,其余为 `cancelled`) |
| 摘要卡死 | `summary_status = processing` 超过 1 小时 | `summary_status` 置 `failed` |
| 删除卡死 | `deleting` 超过阈值,且队列中没有覆盖它的删除任务 | 置 `failed` 并写明原因,文档重新可见、可再次删除;队列探测失败则顺延 |
| Wiki 队列重新触发 | 只因 Wiki 持久队列未消费而停在 `finalizing` 的文档 | 为对应知识库重新入队 Wiki 触发任务,每个知识库每个阈值周期最多一次 |
持续出现"tasks still queued (backpressure, not stuck)"日志说明瓶颈在队列容量,应调大对应 worker pool 并发,而不是怀疑巡检误判。
## 事件总线(`internal/event`) {#_8-事件总线-internal-event}

View File

@ -10,7 +10,7 @@
| 把知识库共享给另一个团队 | 建组织 → 把两个空间都加进去 → 在知识库上「共享到组织」 |
| 接入 API | 空间设置 → API Key,按需勾选能力(检索 / 问答 / 入库 / 管理),必要时限定可访问的知识库 |
| 管理整个部署(全局设置、任务队列、跨空间审计) | 需要**系统管理员**身份,与空间 Owner 独立授予,见[平台管理与系统管理员](20-platform-admin.md) |
| 删除整个空间 | 空间设置里由 **Owner** 触发(`DELETE /tenants/:id`);会一并删除该空间的知识库、Agent、会话与成员关系,不可撤销 |
| 删除整个空间 | 空间设置里由 **Owner** 触发(`DELETE /tenants/:id`);空间与全部成员关系被软删除,成员立即失去访问,界面上无法恢复 |
<Screenshot
src="/screenshots/settings-members.png"
@ -37,7 +37,7 @@ Viewer 可浏览和提问,Contributor 可创建知识库与上传文档,Admi
## 管理空间与平台权限
删除空间由 Owner 执行,会删除该空间的知识库、智能体、会话和成员关系。全局设置、平台任务队列及跨空间审计由系统管理员管理,详见[平台管理与系统管理员](20-platform-admin.md)。
删除空间由 Owner 执行。空间记录与成员关系会被软删除,所有成员随即失去访问;空间内的知识库、模型等数据不会被立即物理清除,但自 v0.8.2 起,已删除空间排队中的 Wiki 任务不再调用模型。全局设置、平台任务队列及跨空间审计由系统管理员管理,详见[平台管理与系统管理员](20-platform-admin.md)。
## 概念总览
@ -120,7 +120,7 @@ type registerByInviteRequest struct {
Token string `binding:"required"`
Email string `binding:"required,email"` // 注册者自填,与 token 不绑定
Username string `binding:"required"`
Password string `binding:"required,min=6"`
Password string `binding:"required"` // 另经统一密码策略校验(8–32 位,含字母和数字)
}
```
@ -159,7 +159,7 @@ Handler:`internal/handler/tenant_member.go`、`tenant_invitation.go`。`/tenan
`internal/handler/tenant_invite_link.go`。与定向邀请同表存储:`InviteeUserID` 为空即共享链接(多人可用,`AcceptedCount` 计数),非空即定向邀请。
- `POST /tenants/:id/invite-links`(Owner):`{role, message}` → 返回 `invite_url`(`{FrontendBaseURL}/register?token=...`,`FrontendBaseURL` 取 YAML `frontend_base_url` → 环境变量 `FRONTEND_BASE_URL` → 相对路径兜底);
- `GET /tenants/:id/invite-links`(Viewer)列出;`DELETE /tenants/:id/invite-links/:inv_id`(Owner)撤销。
- 邀请链接与定向邀请同表,列出用 `GET /tenants/:id/invitations`(Viewer),撤销用 `DELETE /tenants/:id/invitations/:inv_id`(Owner)。
链接持续有效直到过期或撤销,配合 [邀请注册(register-by-invite)](#_2-3-邀请注册-register-by-invite) 的 `register-by-invite` 打通 invite-only 模式下的开户闭环。
@ -174,21 +174,13 @@ Handler:`internal/handler/tenant_member.go`、`tenant_invitation.go`。`/tenan
- `Searchable=true` 的组织可被 `SearchSearchableOrganizations` 发现;
- 邀请码与待审批数仅对"组织 admin 或 owner 租户"可见(`internal/handler/organization.go` 中 `isAdmin || isOwner` 判定)。
#### 邀请搜索:按空间(租户)而非按用户 {#_8-2-邀请搜索-按空间-租户-而非按用户}
#### 邀请候选:按空间 ID 精确解析 {#_8-2-邀请搜索-按空间-租户-而非按用户}
组织邀请以工作空间为目标。`GET /organizations/:id/search-tenants` 按空间名称匹配,仅组织 admin 可调用。一个用户可能属于多个空间,搜索结果因此返回空间候选项:
组织邀请以工作空间为目标。`GET /organizations/:id/search-tenants?q=<空间 ID>` 仅组织 admin 可调用,自 v0.8.2 起只按**精确的空间 ID** 解析候选,不再跨空间按名称搜索(避免借此枚举其他空间的名称):`q` 不是有效 ID、空间已在组织内或不存在时返回空列表,否则返回唯一的 `{tenant_id, tenant_name}`。被邀请方可在自己的空间设置中查到空间 ID 并告知组织管理员;也可以继续使用组织邀请码或邀请链接加入。
```go
// SearchTenantsForInvite:
// 1. 校验调用者租户是组织 admin
// 2. 排除已在组织内的租户 (existingTenantIDs)
// 3. tenantService.SearchTenants 按名称搜索(pageSize = limit*2,limit 上限 50)
// 4. 插入序去重,丢弃解析不到名称的 defunct 租户,截断到 limit
```
旧端点 `GET /organizations/:id/search-users` 保留为兼容别名,行为与 `search-tenants` 相同。
旧端点 `GET /organizations/:id/search-users` 保留为兼容 shim,直接委托给 `SearchTenantsForInvite`(响应已是新的 tenant-candidate 形状,标记 `@Deprecated`)。
`POST /organizations/:id/invite`(仅组织 admin)直接添加成员:优先走 `tenant_id`(可选 `representative_user_id`,若代表用户不属于目标租户则告警并丢弃该字段,不硬失败);兼容旧 SDK 的 `user_id` 路径(反查该用户租户)。
`POST /organizations/:id/invite`(仅组织 admin)直接添加成员:优先走 `tenant_id`,兼容旧 SDK 的 `user_id` 路径(反查该用户的默认空间)。直接添加不再附带代表用户(`representative_user_id` 被忽略);组织成员列表只向调用者自己的空间返回代表用户的邮箱。
#### KB 共享模型与权限计算 {#_8-3-kb-共享模型与权限计算}
@ -216,6 +208,8 @@ type KnowledgeBaseShare struct {
路由上的 `share_id` 必须属于路径中的 KB / Agent,否则返回 404。
**接收方对共享 KB 配置的限制**:只有 KB 所在空间可以调用 `POST /initialization/initialize/:kbId`;其他空间修改 KB 配置(`PUT /initialization/config/:kbId`)需要 admin 级共享,且不能改动存储绑定;接收方读取配置时只看到凭据是否已配置,看不到模型 Base URL、存储桶位置等细节,KB 详情也不再返回旧版内联的存储/VLM 凭据。
**共享何时失效**:共享只在组织未删除、且来源租户仍是组织成员时生效。来源租户退出或被移除时,它共享进该组织的 KB 与 Agent 会被一并撤销;查询侧也会按来源租户的成员关系过滤,旧版本遗留的共享同样不再生效。
**有效权限 = 多层交集(取最小)**:
@ -238,7 +232,8 @@ func applyTenantRoleCap(p types.OrgMemberRole, callerTenantRole types.TenantRole
- 内置智能体不能共享:每个空间都有同 ID 的内置智能体,共享后接收方无法区分。未指定来源空间的对话请求总是先使用自己空间的智能体。
- 共享 Agent 会把它的 KB 范围以只读方式开放给组织成员,因此共享人必须有权直接共享这些 KB,即 KB 创建者或租户 Admin+。`kb_selection_mode: all` 会自动包含之后新建的 KB,只有 Admin+ 可以共享。已共享的 Agent 被编辑时,新加入范围的 KB 适用同一规则。
- 共享运行时,Agent 未设置 MCP 选择模式按「不使用」处理,与共享范围里的展示一致。
- 共享运行时,Agent 未设置 MCP 选择模式按「不使用」处理,与共享范围里的展示一致;快速问答模式下联网搜索需 Agent 本身开启,请求中的 `summary_model_id` 被忽略。
- 接收方看到的共享 Agent 不含系统提示词与创建者用户 ID,能力与知识库范围仍可见。
- 启用了技能的 Agent 共享后,技能在来源空间的沙箱中运行,并带上管理员为技能配置的环境变量(如 API Key);成员可以让智能体读出这些值。共享设置页会对此给出提示。
```mermaid
@ -327,7 +322,7 @@ flowchart LR
#### KB 访问守卫(跨租户共享通道) {#_6-5-kb-访问守卫-跨租户共享通道}
`middleware/kb_access.go`(由 `rbac.go` 的 `KBAccess*` 系列包装)统一了三条访问路径:
`middleware/kb_access.go`(由 `rbac.go` 的 `KBAccess*` 系列包装,判定规则位于 `internal/application/access`)统一了三条访问路径:
```text
1. 自有 KB → 等效 Admin 级完全访问
@ -425,7 +420,7 @@ requireTenantAPIKeyKnowledgeBases(ctx, "kb-1", "kb-2") // → forbidden
授权/Token 端点可显式配置;即使二者已填写,只要 issuer 或 jwks_uri 不完整,仍需通过 discovery 补齐验证信息。缺少可靠的验证配置时不能仅解析 id_token 的载荷就登录。
路由(`internal/router/router.go`):
路由(`internal/router/routes_auth_tenant.go`):
```go
r.GET("/auth/oidc/config", handler.GetOIDCConfig) // 前端探测是否启用

View File

@ -7,20 +7,23 @@
<Screenshot
src="/screenshots/kb-document-list.png"
caption="知识库文档列表:解析状态、标签与批量操作"
hint="展示文档列表页,包含解析状态列、标签列、顶部筛选栏与勾选后出现的批量操作栏。" />
hint="展示文档列表页,包含解析状态列、标签列、顶部筛选栏与排序按钮,以及勾选后出现的批量操作栏(含标签、移动、批量下载)。" />
## 管理操作入口 {#_0-日常会用到的操作}
| 操作 | 界面入口 |
| --- | --- |
| 建库、改分块大小与索引开关 | 知识库编辑弹窗的「分块」「索引策略」页签 |
| 上传文件、导入网页或编写 Markdown | 文档列表页的上传区,或「新建」下拉 |
| 上传文件、导入网页或编写 Markdown | 文档列表页的上传区,或「新建」下拉;上传进度在右下角的上传任务面板查看 |
| 调整文档列表顺序 | 文档列表工具栏的「排序」:更新时间、上传/创建时间(默认最新上传在前)或文件名称 |
| 查看解析进度或排查卡住的文档 | 文档卡片上的状态,或打开文档的解析时间线(见 [查看解析进度](#查看解析进度)) |
| 用文件夹整理文档 | 文档列表左侧的文件夹树;上传整个目录会保留目录结构(见 [文件夹树](#_3-4-文件夹树)) |
| 给文档打标签(一篇可多个) | 单篇在详情里改;多篇勾选后用批量操作栏的「标签」(见 [标签(KnowledgeTag)](#_3-5-标签-knowledgetag)) |
| 检查解析结果、改错字 | 打开文档 → 分块列表 → 直接编辑分块(见 [分块编辑与版本历史](#_3-6-分块编辑与版本历史)) |
| 补充部门、密级等自定义字段 | 文档详情里的自定义元数据(见 [模型要点](#_3-1-模型要点)) |
| 查看操作记录 | 知识库设置 → 活动(见 [知识库活动流(KB Activity)](#_6-知识库活动流-kb-activity)) |
| 复制知识库或跨库移动文档 | 知识库列表的复制,或文档批量操作里的移动(见 [知识库复制与知识移动](#_4-知识库复制与知识移动)) |
| 批量下载原始文件 | 勾选文档后,批量操作栏的「批量下载」(见 [批量下载](#批量下载原始文件)) |
<Screenshot
src="/screenshots/kb-settings.png"
@ -31,7 +34,25 @@
创建知识库时选择内容类型、模型与索引方式,再上传文件、导入网页或编写 Markdown。普通资料使用文档库,标准问答使用 [FAQ 库](17-faq.md)。向量存储创建后不可更改,应在建库前确定。
上传确认页可设置标签和本批文件的解析选项。单次处理选项优先于知识库配置,知识库配置再优先于空间默认值。上传后可在列表查看解析进度;已有文档需要重新解析才能使用修改后的分块参数。
上传确认页可设置标签和本批文件的解析选项,包括是否生成文档摘要(默认开启;关闭后解析、索引及其他处理照常执行)。单次处理选项优先于知识库配置,知识库配置再优先于空间默认值。已有文档需要重新解析才能使用修改后的分块参数。
批量上传时,页面右下角的上传任务面板汇总所有文件:最多同时传输 3 个,显示已传字节、剩余时间以及可检索、处理中、失败和已存在的数量。单个文件可以取消或重试,全部上传完成后可以离开页面,解析会在后台继续。大文件的上传超时按文件大小自动延长。
<Screenshot
src="/screenshots/kb-upload-tasks.png"
caption="上传任务面板:批量上传的整体进度与逐个文件状态"
hint="展示右下角浮动面板:顶部进度环与「正在上传 x/y」标题、剩余时间、可检索/处理中/失败/已存在的分段进度条,以及文件列表中的取消、重试按钮。" />
### 查看解析进度
文档列表和卡片显示每篇文档的解析状态。超过 20 分钟没有进展时,状态会变为「排队中」或「疑似卡住」:前者表示仍有任务在队列中等待,通常无需处理;后者表示已无任务推进该文档,可以打开解析时间线查看停在哪个阶段,或停止解析后重试。长时间无进展的文档会被系统自动标记为失败,错误码为 `TASK_STALLED`。
解析时间线按阶段展示耗时与结果。失败时,顶部错误卡片说明出错的阶段和原因,并提供重试入口。
<Screenshot
src="/screenshots/kb-parse-timeline.png"
caption="解析时间线:各阶段耗时、失败原因与卡住提示"
hint="展示文档解析时间线抽屉:阶段瀑布图(文档解析/分块/向量化/多模态/后处理)、失败时的错误卡片(阶段名、错误码、后端原因与重试按钮),以及「已 N 分钟没有进展」的提示条和停止解析按钮。" />
## 整理文件夹与标签
@ -61,9 +82,15 @@
复制知识库可复用已有配置与内容。跨库移动时,可选择复用向量或重新解析:复用要求两库绑定同一向量存储,重新解析允许使用目标库的存储和处理配置。移动为异步任务,可查询进度。
### 批量下载原始文件
勾选文档后点击「批量下载」,所选文件的原始文件会打包为 ZIP,并保留知识库中的文件夹结构,解压后可按文件夹重新上传。每批最多 200 个文档、原始文件合计不超过 512 MiB;网页导入等没有原始文件的条目会被跳过。「全选已加载」只包含当前已加载的文档。批量下载与单个文件下载的权限相同,需要 Contributor 及以上且对知识库有编辑权限。
## 查看活动与用量
知识库设置的「活动」记录配置、文档、分块、共享和 Wiki 变更。该入口面向符合资源管理权限的登录用户,API Key 不可访问。
知识库设置的「活动」记录配置、文档、分块、共享和 Wiki 变更。该入口面向符合资源管理权限的登录用户,API Key 不可访问。通过 API Key 发起的操作会在操作人下方额外显示 Key 名称。
通过组织共享以只读(Viewer)权限访问的知识库,界面不显示上传、编辑、删除和设置入口。
存储配额按工作空间计算,涵盖文件、文本、向量和索引。创建知识库与上传前会检查配额,删除内容后回收对应用量。
@ -184,7 +211,7 @@ graph TB
#### KB 计算字段 {#_1-7-kb-计算字段}
列表 / 详情响应附带:`knowledge_count`、`chunk_count`、`is_processing`(FAQ 库)、`processing_count`(文档库处理中知识数)、`share_count`(共享到的组织数)、`creator_name`、`is_pinned` / `pinned_at`(当前用户置顶状态)。
列表 / 详情响应附带:`knowledge_count`(不含删除中的文档,与文档列表一致)、`chunk_count`、`is_processing`(FAQ 库)、`processing_count`(文档库处理中知识数)、`share_count`(共享到的组织数)、`creator_name`、`is_pinned` / `pinned_at`(当前用户置顶状态)。
另有一个存储字段 `is_temporary`:标记**临时(ephemeral)知识库**,正常的知识库列表里不展示。它由系统内部使用,典型场景是联网搜索把抓回来的网页缓存成可检索内容。手工建库不会产生临时库。
@ -231,7 +258,7 @@ graph TB
实现中,`Knowledge.CustomMetadataText()` 按键排序生成 `键: 值` 文本,供摘要生成和文档级模型上下文使用。字段由迁移 `000078` 引入。
摄入渠道常量:`web`、`api`、`browser_extension`、`wechat`、`wecom`、`feishu`、`dingtalk`、`slack`、`im`、`notion`、`yuque`、`rss`。
摄入渠道常量:`web`、`api`、`browser_extension`、`wechat`、`wecom`、`feishu`、`feishu_drive`、`lark_drive`、`dingtalk`、`slack`、`im`、`notion`、`confluence`、`yuque`、`rss`、`ima`。
解析状态机:
@ -240,14 +267,20 @@ stateDiagram-v2
[*] --> pending: 创建知识入队
pending --> processing: Worker 领取 (DocReader 解析 / 分块 / 嵌入)
processing --> finalizing: 主解析完成, 富化子任务进行中 (pending_subtasks_count > 0)
processing --> failed: 解析失败
processing --> completed: 无富化子任务
processing --> failed: 解析失败或巡检判定卡住
processing --> cancelled: 用户取消
finalizing --> completed: 最后一个子任务完成 (计数原子递减到 0)
finalizing --> failed: 子任务失败
finalizing --> completed: 最后一个子任务结束 (计数原子递减到 0)
finalizing --> failed: 巡检判定卡住
completed --> deleting: 删除中 (阻止异步任务冲突)
failed --> deleting: 删除
deleting --> failed: 删除任务丢失, 巡检恢复
completed --> pending: reparse 重新解析
failed --> pending: reparse 重新解析
```
单个富化子任务(摘要、问题生成、图谱、Wiki)失败不会让文档变为 `failed`,文档在子任务全部结束后进入 `completed`。卡在 `pending`、`processing`、`finalizing` 或 `deleting` 的文档由后台巡检回收,见[异步任务系统](../02-architecture/05-async-tasks.md#_7-3-兜底-housekeeping-清扫)。
摘要独立状态:`summary_status ∈ {none, pending, processing, completed, failed}`。
#### 知识路由 {#_3-2-知识路由}
@ -257,7 +290,9 @@ stateDiagram-v2
| POST | `/knowledge-bases/:id/knowledge/file` | 上传文件 | OwnedKBOrAdmin + KBAccessWrite |
| POST | `/knowledge-bases/:id/knowledge/url` | URL 导入 | 同上 |
| POST | `/knowledge-bases/:id/knowledge/manual` | 手动 Markdown 知识 | 同上 |
| GET | `/knowledge-bases/:id/knowledge` | 列表(分页 + 过滤) | Viewer+ + KBAccessRead |
| GET | `/knowledge-bases/:id/knowledge` | 列表(分页 + 过滤 + 排序) | Viewer+ + KBAccessRead |
| POST | `/knowledge-bases/:id/knowledge/batch-download` | 批量下载原始文件(ZIP) | Contributor+ + KBAccessWrite |
| GET / PUT | `/knowledge-bases/:id/knowledge/folders` | 文件夹树 / 重命名或移动文件夹 | Viewer+ + KBAccessRead / OwnedKBOrAdmin + KBAccessWrite |
| DELETE | `/knowledge-bases/:id/knowledge` | 清空 KB 内容 | Admin + KBAccessWrite |
| GET | `/knowledge/:id`、`/knowledge/batch` | 详情 / 批量获取 | Viewer+ |
| GET | `/knowledge/:id/stages`、`/knowledge/:id/spans` | 处理阶段 / 跨度 | Viewer+ |
@ -268,6 +303,7 @@ stateDiagram-v2
| GET | `/knowledge/:id/preview` | 预览文件 | Viewer+ + KBAccessRead |
| PUT | `/knowledge/tags` | 批量更新标签 | Contributor+ / `ingest` |
| POST | `/knowledge/batch-reparse`、`/knowledge/batch-delete` | 批量重解析 / 删除 | Contributor+ / `ingest` |
| POST | `/knowledge/folder` | 把文档归入文件夹 | Contributor+ / `ingest` |
| POST | `/knowledge/move` | 移动知识 | Contributor+ / `ingest` |
| GET | `/knowledge/move/progress/:task_id` | 移动进度 | Viewer+ |
@ -277,13 +313,14 @@ stateDiagram-v2
| 参数 | 说明 |
| --- | --- |
| `page` / `page_size` | 分页(默认按 `updated_at DESC` 排序) |
| `page` / `page_size` | 分页(默认 1 / 20) |
| `sort_by` / `sort_order` | 排序:`updated_at` / `created_at` / `file_name`,`asc` / `desc`;默认 `created_at desc` |
| `keyword` | 按文件名 / 标题搜索 |
| `file_type` | 文件类型过滤(`pdf` / `manual` / `url` …) |
| `parse_status` | 解析状态过滤 |
| `source` | 摄入渠道过滤(`api` / `web` / `feishu` …) |
| `tag_id` | 标签过滤,逗号分隔多个(**OR 语义**) |
| `updated_from` / `updated_to` | 更新时间范围(RFC3339) |
| `tag_ids` | 标签过滤,逗号分隔多个(**OR 语义**) |
| `start_time` / `end_time` | 更新时间范围(RFC3339) |
| `folder_path` | 按文件夹筛选。**是否传这个参数决定列表模式**:不传是全库扁平视图,传空字符串是知识库根目录(不含子目录) |
| `folder_recursive` | 配合 `folder_path` 使用,为 `true` 时连子目录里的文档一起返回 |
@ -345,7 +382,7 @@ type KnowledgeTagRelation struct { KnowledgeID, TagID string } // 多对多
| 字段 / 表 | 作用 |
| --- | --- |
| `chunks.source_content` | 解析器原始输出,**不可变**。历史行在首次手工编辑时从 `content` 惰性回填 |
| `chunks.source_content` | 解析器原始输出,**不可变**。新建分块时不写入,首次手工编辑时从 `content` 惰性回填 |
| `chunks.content` | 当前生效内容(检索、引用展示都用它) |
| `chunks.content_revision` | 每次编辑或回滚 +1,用作乐观锁 |
| `chunks.index_status` | `ready` / `processing` / `failed`,标识当前内容是否已反映到检索存储 |
@ -378,13 +415,13 @@ type KnowledgeTagRelation struct { KnowledgeID, TagID string } // 多对多
| 控制 | 实现 | 目的 |
| --- | --- | --- |
| 强制 `Content-Type: application/octet-stream` | 响应头固定 | 阻止浏览器把 HTML/SVG 当页面执行(防存储型 XSS) |
| 按扩展名设置 `Content-Type` | PDF、图片、文本等按类型内联预览;HTML、SVG、XML、JS、CSS 等可被浏览器执行的类型强制为 `application/octet-stream` | 阻止浏览器把上传内容当页面执行(防存储型 XSS) |
| `X-Content-Type-Options: nosniff` | 响应头 | 禁止 MIME 嗅探绕过 |
| `Content-Disposition: attachment; filename=...` | 响应头 | 强制下载而非内联渲染 |
| `Content-Disposition` | 可执行类型为 `attachment`,其余为 `inline` | 危险类型只能下载,不能内联渲染 |
| 路径校验 | `ValidateKBScopedStoragePath()` | 文件路径必须落在该 KB 的授权存储范围内(防路径穿越 / 越权读取) |
| 大小限制 | GetFile 响应体限制 | 防止超大文件拖垮预览 |
测试用例明确验证:即使文件内容是 `<script>alert(1)</script>`,也只会作为二进制附件传输。下载端点(`/knowledge/:id/download`)要求更高的 Contributor+ 且走 KBAccessWrite 门禁。
测试用例明确验证:HTML 文件即使内容是 `<script>alert(1)</script>`,也只会作为二进制附件传输。下载端点(`/knowledge/:id/download` 与批量下载 `/knowledge-bases/:id/knowledge/batch-download`)要求更高的 Contributor+ 且走 KBAccessWrite 门禁。
预览返回的是原始文件本身,通过只读共享(组织共享的 viewer、经共享智能体可见)访问时同样可以预览。「只有 Editor 及以上才能下载」是产品上的便利性限制,不是访问控制边界:能读到一个 KB 的人,就能拿到其中的原文件。
@ -450,6 +487,7 @@ nil & nil → true (同为 env-store)
| POST/GET | `/knowledge-bases/:id/hybrid-search` | HybridSearch | Viewer+ + KBAccessRead |
| POST | `/knowledge-bases/copy` | CopyKnowledgeBase | Contributor+ / `manage_kbs` |
| POST | `/knowledge-bases/:id/duplicate` | DuplicateKnowledgeBase | Contributor+ / `manage_kbs` + KBAccessRead |
| POST | `/knowledge-bases/:id/profile/generate` | GenerateKnowledgeBaseProfile | OwnedKBOrAdmin + KBAccessWrite / `manage_kbs` |
| GET | `/knowledge-bases/copy/progress/:task_id` | GetKBCloneProgress | Viewer+ / `retrieve` 或 `manage_kbs` |
| GET | `/knowledge-bases/:id/move-targets` | ListMoveTargets | Viewer+ + KBAccessRead |
| GET | `/knowledge-bases/:id/activity` | ListKnowledgeBaseActivity | OwnedKBOrAdmin + KBAccessRead(仅 JWT) |
@ -475,11 +513,12 @@ nil & nil → true (同为 env-store)
→ 图谱提取 (graph_enabled + ExtractConfig)
→ Wiki 生成 (wiki_enabled + WikiConfig)
→ 问题生成 (QuestionGenerationConfig.enabled)
→ 文档摘要 (process_config.summary_enabled,默认开启)
→ parse_status=finalizing, pending_subtasks_count=N
→ 每个富化子任务完成后原子递减;归零 → parse_status=completed
```
**配置合并优先级**(`EffectiveProcessConfig`):`Knowledge.ProcessOverrides`(单次上传覆盖,存于知识 metadata 的 `KnowledgeProcessOverrides`,可覆盖 parser 规则 / 分块 / VLM / ASR / 问题生成 / 图谱开关等)> KB 配置 > 租户默认。
**配置合并优先级**(`EffectiveProcessConfig`):`Knowledge.ProcessOverrides`(单次上传覆盖,存于知识 metadata 的 `KnowledgeProcessOverrides`,可覆盖 parser 规则 / 分块 / VLM / ASR / 问题生成 / 图谱开关 / 摘要开关等)> KB 配置 > 租户默认。
Chunk 类型(`internal/types/chunk.go`):`text`、`parent_text`、`image_ocr`、`image_caption`、`summary`、`entity`、`relationship`、`faq`、`web_search`、`table_summary`、`table_column`、`wiki_page`;chunk 支持 `is_enabled` 开关与 `flags` 位标志(bit0 = 可推荐)。
@ -513,5 +552,5 @@ Chunk 类型(`internal/types/chunk.go`):`text`、`parent_text`、`image_oc
| 知识创建 / 处理管线 | `internal/application/service/knowledge_create.go`、`knowledge_process.go`、`knowledge_process_config.go` |
| 复制与移动 | `internal/application/service/knowledge_clone_move.go` |
| 活动流 | `internal/application/service/kb_activity.go` |
| 路由与门禁 | `internal/router/router.go`、`internal/router/rbac.go` |
| 路由与门禁 | `internal/router/routes_knowledge.go`、`internal/router/rbac.go` |
| 关键测试佐证 | `internal/handler/knowledge_preview_security_test.go`、`knowledge_move_gate_test.go`、`knowledgebase_copy_preflight_test.go` |

View File

@ -115,8 +115,8 @@ sequenceDiagram
| 引擎 | 文件类型 | 说明 |
| --- | --- | --- |
| `builtin` | `docx`(Docx2Parser)、`doc`(DocParser)、`pdf`(PDFParser)、`md`/`markdown`(MarkdownParser)、`xlsx`/`xls`(ExcelParser)、`epub`(EPUBParser)、`html`/`htm`(HTMLParser)、`mhtml`(MHTMLParser)、`jpg`/`jpeg`/`png`/`gif`/`bmp`/`tiff`/`webp`(ImageParser) | 内置解析引擎 |
| `markitdown` | `md`、`markdown`、`pdf`、`docx`、`doc`、`pptx`、`ppt`、`xlsx`、`xls`、`csv`(全部 MarkitdownParser) | 微软 MarkItDown 库。**PPT/PPTX 只有该引擎支持** |
| `builtin` | `docx`(Docx2Parser)、`doc`(DocParser)、`pdf`(PDFParser)、`md`/`markdown`(MarkdownParser)、`xlsx`/`xls`(ExcelParser)、`pptx`/`ppt`(MarkitdownParser)、`epub`(EPUBParser)、`html`/`htm`(HTMLParser)、`mhtml`(MHTMLParser)、`xmind`(XMindParser)、`jpg`/`jpeg`/`png`/`gif`/`bmp`/`tiff`/`webp`(ImageParser) | 内置解析引擎;PPT/PPTX 复用 MarkItDown 解析器 |
| `markitdown` | `md`、`markdown`、`pdf`、`docx`、`doc`、`pptx`、`ppt`、`xlsx`、`xls`、`csv`(全部 MarkitdownParser) | 微软 MarkItDown 库 |
| `opendataloader` | `pdf`(OpenDataLoaderParser) | OpenDataLoader PDF 版面分析,需 Java 11+;`check_available` 探测 java、Python 包及 hybrid 服务健康 |
调度规则(`get_parser_class`):请求指定的引擎若不支持该文件类型,**自动回退 `builtin` 引擎**;builtin 也没有则抛 `ValueError("Unsupported file type")`。
@ -178,7 +178,7 @@ sequenceDiagram
2. `_parse_with_antiword`:`antiword` 命令行纯文本提取(通过 `SandboxExecutor` 执行,强制注入代理环境变量,默认 `http://128.0.0.1:1` 的"黑洞代理"阻断子进程意外外联);
3. `_parse_with_textract`:**已禁用**(textract 存在 SSRF 漏洞,代码保留但注释掉)。
**依赖**:LibreOffice(soffice)、antiword(镜像内已装);查找路径支持 `LIBREOFFICE_PATH`/`ANTIWORD_PATH` 环境变量。**局限**:无 LibreOffice 时退化为 antiword 纯文本(无图片、无表格结构)。
**依赖**:LibreOffice(soffice)、antiword(镜像内已装);查找路径支持 `LIBREOFFICE_PATH`/`ANTIWORD_PATH` 环境变量。外部命令默认 60 秒超时;超时后会终止整个进程组(包括 soffice 派生的子进程),避免残留进程占住 docreader worker。**局限**:无 LibreOffice 时退化为 antiword 纯文本(无图片、无表格结构)。
#### docx2_parser.py 与 docx_parser.py 的区别 {#_3-3-docx2-parser-py-与-docx-parser-py-的区别}
@ -223,7 +223,7 @@ PPT 系列**没有独立解析器**,由 `MarkitdownParser` 处理,这两个
`PipelineParser.create(MarkdownTableFormatter, MarkdownImageBase64)`:
- **`MarkdownTableFormatter`**:编码自动检测(`endecode.decode_bytes`:utf-8 → gb18030 → gb2312 → gbk → big5 → ascii → latin-1)后规范化表格——统一 `| cell |` 间距与对齐标记,`normalize_spurious_table_prefixes` 修 MarkItDown 产出的假空行/分隔行前缀,并给无表头的 Word 表格补 `| --- |` GFM 分隔行。
- **`MarkdownImageBase64`**:把 `![alt](data:image/xxx;base64,...)` 内嵌图抽出为 `images/<uuid>.<ext>` 引用 + `Document.images` 数据(MIME 子类型支持 `x-emf` 这类带连字符的格式)。
- **`MarkdownImageBase64`**:把 `![alt](data:image/xxx;base64,...)` 内嵌图抽出为 `images/<uuid>.<ext>` 引用 + `Document.images` 数据(MIME 子类型支持 `x-emf` 这类带连字符的格式)。无法解码的图片(如 base64 后紧跟中文图片标题)会被跳过并记录日志,不会导致整篇文档解析失败。
该解析器也是 MarkitdownParser / WebParser 流水线的公共后处理阶段。
@ -249,6 +249,10 @@ PPT 系列**没有独立解析器**,由 `MarkitdownParser` 处理,这两个
- HTML → Markdown 复用 `MHTMLParser.html_to_markdown()`,但传入 `extract_images=False`(本地 HTML 文件没有 MIME 附件可抽)、`strip_internal_links=False`(保留站内链接)、`fallback_to_raw_html=False`(转换不出内容时返回空而不是塞一整块 ```` ```html ````);
- 正文中通过 `<img src="http://...">` 引用的远程图片由 Go 侧补齐:`internal/infrastructure/docparser/image_resolver.go` 会带 SSRF 校验下载这些远程图片并转存到对象存储,再重写引用,使其与本地上传的图片走同一套 OCR / caption 流程。
#### xmind_parser.py — XMindParser(.xmind 思维导图)
读取 XMind 压缩包中的 `content.json`(新版)或 `content.xml`(旧版),单个内容文件上限 32 MiB。每个画布输出为一个 `# 画布标题` 小节,主题层级转为缩进的 Markdown 列表,纯文本备注以引用块附在对应主题下,多个画布之间用 `---` 分隔。不提取图片;没有可渲染主题时解析失败。
#### epub_parser.py — EPUBParser(.epub 电子书) {#_3-11-epub-parser-py-—-epubparser-epub-电子书}
主路径用 **ebooklib**(经临时文件读入):提取 DC 元数据(title/author/publisher/language/description/date/isbn),优先按 TOC 顺序逐章处理(每章取首个 h1/h2 作章题,输出 `## 章题` + markdownify 转换的正文),`ITEM_IMAGE` 全部抽为 `images/<uuid>.<ext>` 并按路径多变体别名回写 `<img src>`;EPUB 内部链接(章节间跳转、`#fragment`)unwrap 只留文本。ebooklib 失败时回退 **ZIP 直读**:按 `chapter(\d+)` 排序 html/xhtml 文件逐个转换。metadata 含 `chapter_count`/`image_count`。
@ -286,6 +290,8 @@ flowchart TD
H -- "epub" --> EP["EPUBParser (ebooklib → ZIP 回退)"]
H -- "html / htm" --> HT["HTMLParser (BeautifulSoup + markdownify)"]
H -- "mhtml" --> MH["MHTMLParser"]
H -- "pptx / ppt" --> PT["MarkitdownParser (LibreOffice 归一化 + 媒体补图)"]
H -- "xmind" --> XM["XMindParser (主题大纲 + 备注)"]
H -- "jpg/png/gif/bmp/tiff/webp" --> IM["ImageParser (整图内联, 不做 OCR)"]
H -- "其他" --> ERR["ValueError: Unsupported file type"]
```
@ -301,7 +307,9 @@ docreader 侧的图片契约非常简单:每个解析器把图片以 `Document
- unary `Read`:`_resolve_images()` 把全部图片 base64 解码为 `ImageRef.image_data` **内联字节**一次性返回(`image_dir_path` 恒为空——历史上"写共享卷目录"的模式已废弃,注释明确 *"The Go App is solely responsible for persisting images to the configured storage backend (local/minio/cos/tos)"*);
- streaming `ReadStream`:`_iter_image_refs()` 逐张 yield,边发边 `pop` 释放内存。
Go 侧接手后(`internal/infrastructure/docparser/image_resolver.go`):将 inline bytes 上传对象存储、把 markdown 中的 `images/...` 引用重写为存储 URL;随后 `internal/application/service/image_multimodal.go` 依据 metadata 的 `image_source_type` 决策——`scanned_pdf` 的整页图走 OCR(带专用 `ocr_prompt`),普通插图走 VLM caption。**docreader 内没有任何 VLM 调用**;`models/read_config.py` 中的 `vlm_config`/`storage_config` 字段只是为了老构造函数签名兼容而保留的空壳("Legacy config kept for backward compatibility")。
Go 侧接手后(`internal/infrastructure/docparser/image_resolver.go`):将 inline bytes 上传对象存储、把 markdown 中的 `images/...` 引用重写为存储 URL;随后 `internal/application/service/image_multimodal.go` 依据 metadata 的 `image_source_type` 决策——`scanned_pdf` 的整页图走 OCR(带专用 `ocr_prompt`),普通插图走 VLM caption。知识库配置的图片解析自定义指令(`vlm_config.custom_instructions`)只追加到 caption 提示词,不进入 OCR 提示词,以免干扰 OCR 的输出约定(如无文字图片应回复 `No text content`)。
各解析引擎输出中的内联 HTML `<table>`(常见于 MinerU、PaddleOCR-VL 与 VLM OCR)会在分块前统一转换为 Markdown 表格;含合并单元格等无法转换的表格保留 HTML,但每行单独成行,保证分块器能在行边界切分。**docreader 内没有任何 VLM 调用**;`models/read_config.py` 中的 `vlm_config`/`storage_config` 字段只是为了老构造函数签名兼容而保留的空壳("Legacy config kept for backward compatibility")。
---
@ -358,6 +366,18 @@ gRPC 响应中不再返回 chunks(`ReadResponse` 没有 chunk 字段);`Exc
| `DOCREADER_PDF_RENDER_VECTOR_FIGURES` | true | 将矢量图表区域渲染为 JPEG |
| `DOCREADER_PDF_WORD_GAP_WIDTH_RATIO` / `_MARGIN_COL_WIDTH_RATIO` / `_MIN_HEADING_LINE_CHARS` 等 | 0.4 / 0.12 / 8 | 版面重建微调参数(详见源码常量区) |
#### Go 侧解析超时
以下环境变量作用于 Go 主服务,而不是 docreader 容器:
| 环境变量 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `WEKNORA_DOCUMENT_PROCESS_TIMEOUT` | Go duration | `2h` | 单个文档处理任务的总超时 |
| `WEKNORA_DOCREADER_CALL_TIMEOUT` | Go duration | `30m` | 单次 docreader 调用超时,须小于文档处理超时 |
| `WEKNORA_PADDLEOCR_VL_TIMEOUT` | Go duration | `1000s` | 自建 PaddleOCR-VL 引擎的 HTTP 请求超时;空值、无效值或非正数使用默认值 |
处理大文件时从内到外逐级留出余量,例如 PaddleOCR-VL `90m`、docreader `100m`、文档处理 `2h`。
#### 安全与其他 {#_6-3-安全与其他}
| 环境变量 | 说明 |
@ -365,6 +385,7 @@ gRPC 响应中不再返回 chunks(`ReadResponse` 没有 chunk 字段);`Exc
| `GRPC_AUTH_TOKEN` | 设置后启用 token 认证(metadata `authorization: Bearer <token>`) |
| `GRPC_TLS_ENABLED` / `GRPC_TLS_CERT` / `GRPC_TLS_KEY` / `GRPC_TLS_CA` / `GRPC_MTLS_REQUIRE_CLIENT_CERT` | TLS / mTLS,配置无效时拒绝启动 |
| `SSRF_WHITELIST` / `SSRF_WHITELIST_EXTRA` | SSRF 白名单(逗号分隔,支持 `*.suffix` 与 CIDR) |
| `SSRF_DNS_WHITELIST_ONLY` | 设为 `true` 时只允许访问白名单中的主机名,不在白名单内的主机在 DNS 解析前即被拒绝;与 Go 主服务使用同一开关 |
| `LOG_LEVEL` | 日志级别(默认 INFO;日志格式含 request_id 与耗时,见 `utils/request.py`) |
| `LIBREOFFICE_PATH` / `ANTIWORD_PATH` | soffice / antiword 可执行文件路径覆盖 |
@ -393,7 +414,7 @@ Python 依赖(`pyproject.toml` + `uv.lock` 锁定):`grpcio`、`pypdfium2`
- **单实例纵向调优**:CPU 富余时调大 `DOCREADER_PDF_RENDER_PARALLELISM`(单文档渲染提速近线性)与 `DOCREADER_GRPC_MAX_WORKERS`(非 PDF 格式可真并发);内存受限时优先保证 Go 侧走 `ReadStream`(默认行为)。
- **大文件**:`MAX_FILE_SIZE_MB` 需 Go 客户端与 docreader **两端同步调整**;扫描件页图大小受 `DOCREADER_PDF_RENDER_MAX_EDGE`/`_DPI`/`_JPEG_QUALITY` 三个旋钮控制。
- **JVM/浏览器类负载隔离**:OpenDataLoader 每次解析拉起 JVM、WebParser 每次拉起 WebKit,均为重进程;`DOCREADER_ODL_MAX_WORKERS`、`DOCREADER_MARKITDOWN_MAX_WORKERS` 默认 1 是保守值,资源充足可放宽或设 ≤0 关闭限流。ODL hybrid 服务(`Dockerfile.odl-hybrid`)应独立部署并配置 `DOCREADER_ODL_HYBRID_URL`。
- **超时保护**:Go 侧务必配置 `docreader_call_timeout`(`internal/config/config.go`),否则挂死的 docreader 会长时间占用入库 worker。
- **超时保护**:Go 侧的 `WEKNORA_DOCREADER_CALL_TIMEOUT`(配置文件 `docreader_call_timeout`,默认 30 分钟)限制单次 docreader 调用,防止挂死的 docreader 长时间占用入库 worker;大文件解析需要更久时,同步调大文档处理超时(见 [Go 侧解析超时](#go-侧解析超时))。
- **安全基线**:生产环境开启 `GRPC_AUTH_TOKEN`(≥16 字节)+ `GRPC_TLS_ENABLED`;不设置时服务会以明文 + 无鉴权模式启动并打印 WARNING。
---
@ -421,7 +442,7 @@ docker build -f docker/Dockerfile.app --build-arg WITH_ANYDOC=0 -t weknora-app .
# 或在 .env 里设 WITH_ANYDOC=0 再 docker compose build
```
显式解析规则优先。未配置规则时,已链接 anydoc 且它支持的复杂格式默认优先走 anydoc;简单格式继续用 Go SimpleFormatReader。未链接 anydoc 的 PPT/PPTX 默认回退 markitdown。需要固定引擎时,可在知识库解析设置中显式指定,而不依赖部署的编译选项。
显式解析规则优先。未配置规则时,已链接 anydoc 且它支持的复杂格式默认优先走 anydoc;PDF 除外,默认仍走 builtin(anydoc 只抽取 PDF 文字层,会丢失图片、表格和版面,而 builtin 能逐页识别扫描页并交给 OCR)。简单格式继续用 Go SimpleFormatReader。未链接 anydoc 的 PPT/PPTX 默认回退 markitdown。需要固定引擎时,可在知识库解析设置中显式指定(包括把 `pdf` 指定给 anydoc),而不依赖部署的编译选项。
#### 能力边界 {#_8-2-能力边界}
@ -444,7 +465,7 @@ docker build -f docker/Dockerfile.app --build-arg WITH_ANYDOC=0 -t weknora-app .
### 附:关键事实速查
- **对外接口**:仅 gRPC,端口 `50051`(`DOCREADER_GRPC_PORT`/`PORT`),RPC:`Read` / `ReadStream` / `ListEngines` + 标准 Health 服务。
- **docreader 直接支持的文件格式全集**:`pdf`、`docx`、`doc`、`xlsx`、`xls`(markitdown 引擎额外含 `pptx`、`ppt`、`csv`)、`md`/`markdown`、`epub`、`html`/`htm`、`mhtml`、图片 `jpg/jpeg/png/gif/bmp/tiff/webp`,以及 URL 网页抓取;`txt`/`csv`/`json`/图片/音频在主链路中由 Go 侧 `SimpleFormatReader` 原生处理,不经过本服务。
- **docreader 直接支持的文件格式全集**:`pdf`、`docx`、`doc`、`xlsx`、`xls`、`pptx`、`ppt`、`xmind`(markitdown 引擎额外含 `csv`)、`md`/`markdown`、`epub`、`html`/`htm`、`mhtml`、图片 `jpg/jpeg/png/gif/bmp/tiff/webp`,以及 URL 网页抓取;`txt`/`csv`/`json`/图片/音频在主链路中由 Go 侧 `SimpleFormatReader` 原生处理,不经过本服务。
- **OCR / VLM**:docreader 内部零 OCR、零 VLM;扫描页与插图作为图片回传,OCR(PaddleOCR-VL)与 caption 由 Go App 完成。
- **图片回传**:inline bytes(`ImageRef.image_data`),持久化到 local/minio/cos/tos 由 Go 负责。
- **分块**:生产路径在 Go 侧 chunker;Python `TextSplitter`(512/80)仅为 sidecar 保留并与 Go 对齐。

View File

@ -206,14 +206,17 @@ flowchart TD
```go
var protectedPatterns = []*regexp.Regexp{
regexp.MustCompile(`(?s)\$\$.*?\$\$`), // LaTeX 块级公式
regexp.MustCompile(`!\[[^\]]*\]\([^)]+\)`), // Markdown 图片
regexp.MustCompile(`\[[^\]]*\]\([^)]+\)`), // Markdown 链接
/* 表头+分隔行 */ /* 表格数据行 */ // Markdown 表格
regexp.MustCompile("(?s)```(?:\\w+)?[\\r\\n].*?```"), // fenced 代码块
regexp.MustCompile(`(?s)\$\$.*?\$\$`), // LaTeX 块级公式
regexp.MustCompile(`!\[[^\]\n]{0,200}\]\([^)\n]{1,500}\)`), // Markdown 图片(单行、限长)
regexp.MustCompile(`\[[^\]\n]{1,200}\]\([^)\n]{1,500}\)`), // Markdown 链接(单行、限长)
/* 表头+分隔行 */ /* 表格数据行 */ // Markdown 表格
regexp.MustCompile("(?s)```(?:\\w+)?[\\r\\n].*?```"), // fenced 代码块
regexp.MustCompile("`[^`\\r\\n]+`"), // 行内代码
}
```
图片和链接的匹配限定在单行内,链接文字不超过 200 字符、地址不超过 500 字符(与 CommonMark 不允许跨空行的规则一致)。这样 OCR 残留的孤立 `[` 不会与远处的 `](` 配对,把整段正文误当作一个不可切分的保护区。
超过 `maxProtectedSize = 7500` rune 的保护区(超大表格/代码块)会被强制在换行或空格处切开,避免超出 embedding API 限制。
**Step 2 — 递归分隔**(`splitBySeparators`):按 `Separators` 优先级切(默认 `\n\n` → `\n` → `。`),仍超 `ChunkSize` 的片段递归应用下一级分隔符(与 Python `_split` 语义一致,分隔符保留在片段中)。
@ -228,8 +231,6 @@ var protectedPatterns = []*regexp.Regexp{
- 受保护区间(代码块、行内代码 `` ` ` ``、公式、表格、图片/链接)内部的分隔符不作为边界;边界之后若只剩空白也不成立;
- 窗口内找不到合法语义边界时不保留重叠,避免从词的中间截断。
行内代码 `` `foo` `` 在这一版加入了受保护正则列表,防止在反引号内部切开。
#### 表格处理:表头追踪(header_tracker.go) {#_3-4-表格处理-表头追踪-header-tracker-go}
大 Markdown 表格被切成多块后,后续块会丢失列名上下文。`headerTracker`(移植自 `docreader/splitter/header_hook.py`)解决这一问题:
@ -239,7 +240,7 @@ var protectedPatterns = []*regexp.Regexp{
- 空表头(MarkItDown 常见的 `||` + `|---|---|`)用第一行数据行补全列名(`pendingExtend`);
- 表格边界感知:块尾 `\n\n` 后出现新表行、或新行列数与表头不一致时,结束旧表头并强制落块(`headerEndedThisUnit`),防止上一张表的表头污染下一张表。
另外,OCR 引擎(PaddleOCR-VL 等)输出的内联 HTML 表格在解析阶段就被 `docparser/html_table_normalizer.go` 的 `normalizeHTMLTables` 转成 GFM Markdown 表格(含 rowspan/colspan 的只剥离表现属性),从而进入上述保护与表头追踪逻辑,不会被 chunker 切碎。
另外,所有解析引擎(MinerU、PaddleOCR-VL、VLM OCR 等)以及手工 Markdown 中的内联 HTML 表格,都会在分块前由 `docparser/html_table_normalizer.go` 的 `NormalizeHTMLTables` 转成 GFM Markdown 表格,从而进入上述保护与表头追踪逻辑。含真实合并单元格(`rowspan`/`colspan` 大于 1)或其他无法转换的表格保留 HTML,但每个 `<tr>` 单独成行并在前后留空行,分块器可以在行边界切分,而不是在 7500 字符上限处硬切。
#### 图片处理 {#_3-5-图片处理}
@ -369,7 +370,7 @@ processDocument
保护措施(常量):输入上限 `previewMaxChars = 64k` rune(返回 413)、返回块数上限 `previewMaxChunks = 500`(统计仍按全量算)、超时 `previewTimeout = 5s`(splitter 不接受 context,超时后 handler 返回 504 但工作 goroutine 会自然跑完,64k 上限是主要防护)。诊断信息由 `chunker.SplitWithDiagnostics` 产出,其 JSON 形状是公开 API 的一部分。
路由注册(`internal/router/router.go`):
路由注册(`internal/router/routes_knowledge.go`):
```go
g.apiKeyRoute(r, http.MethodPost, "/chunker/preview",

View File

@ -23,7 +23,7 @@
| Elasticsearch v7 | `elasticsearch_v7` | 不支持(Support 仅 keywords) | match(BM25) | BM25 | ES analyzer | — | — | 中 | 存量 ES 7,仅作关键词引擎,需与其他向量引擎组合 |
| OpenSearch | `opensearch` | k-NN 插件 knn(HNSW) | match(BM25) | BM25 | OS analyzer | knn_vector 声明式 mapping + 指纹校验 | k-NN 原生 | 中 | 需审计/别名/reindex 的生产 ES 系方案;版本 2.11+/3.x |
| Qdrant | `qdrant` | 原生 HNSW Cosine | 全文索引 MatchText(token OR) | 无打分(Scroll 命中即回,靠 RRF rank) | 多语言 tokenizer | 每维一个 collection | score_threshold 原生 | 中 | 纯向量为主、需 payload 过滤的场景 |
| Milvus | `milvus` | HNSW(IP/COSINE/) | BM25 Function 稀疏向量 | BM25 | Milvus analyzer | 每维一个 collection | 应用侧 | 中高 | 大规模向量、需要原生 BM25 混检 |
| Milvus | `milvus` | HNSW(IP/COSINE/L2) | BM25 Function 稀疏向量 | BM25 | Milvus analyzer | 每维一个 collection | 应用侧 | 中高 | 大规模向量、需要原生 BM25 混检 |
| Weaviate | `weaviate` | nearVector(certainty) | 原生 BM25 | BM25 | Weaviate tokenizer | 动态 Class | certainty 原生 | 中 | GraphQL 生态、需副本/分片配置 |
| Doris | `doris` | ANN HNSW inner_product/cosine | 倒排索引 MATCH_ANY | 倒排命中 | 建表声明 chinese parser | 每维一张表 | SQL 内 | 高 | 已有 Doris 数仓,检索与分析一体 |
| 腾讯云 VectorDB | `tencent_vectordb` | HNSW COSINE | 稀疏向量 BM25(SPARSE_INVERTED) | BM25 | SDK SparseEncoder | 每维一个 collection | 应用侧 | 低(云托管) | 腾讯云托管、免运维 |
@ -138,7 +138,7 @@ flowchart TD
`internal/application/repository/retriever/elasticsearch/v8/repository.go`。typed client,单索引(`ELASTICSEARCH_INDEX`,默认 `WeKnora`),文档含 `dense_vector` embedding 字段。
- **向量检索**:`script_score` 查询,脚本 `cosineSimilarity(params.query_vector, 'embedding')`(Lucene 禁止负最终分,实际值域 [0,1]),threshold 过滤在应用侧。
- **向量检索**:`script_score` 查询,脚本 `Math.max(cosineSimilarity(params.query_vector, 'embedding'), 0.0)`,threshold 过滤在应用侧。Lucene 拒绝负的最终分数,未截断时只要有一个向量与查询方向相反,整个检索请求就会返回 400;截断到 0 后值域为 [0,1],这类文档排在最后,也会被任何正阈值过滤掉。
- **关键词检索**:`match` 查询 content 字段(BM25)。
- **过滤**:bool filter(KB/knowledge/tag ID terms;`is_enabled` 用 must_not 反向匹配,历史无该字段的数据视为启用);启动时探测 mapping 决定 ID 字段是否需要 `.keyword` 后缀。
- **建索引**:Bulk API 批量写入,空向量拒绝。
@ -165,6 +165,7 @@ flowchart TD
- **向量检索**:`Query` API,score 为归一化向量点积(≈cosine,IR embedding 下 [0,1]),threshold 由 score_threshold 下推。
- **关键词检索**:`tokenizeQuery` 本地分词后对每个 token 构造 `MatchText(content, token)` 的 **should(OR)过滤**,用 `Scroll` 遍历所有匹配维度的 collection 取回;无 BM25 打分(命中即回,分数由上层 RRF 的 rank 决定)。
- **过滤**:`getBaseFilter` 用 `MatchKeywords` 精确过滤 KB/knowledge/tag/is_enabled。
- **写入与删除**:字符串 payload 中的非法 UTF-8 与 NUL 字符在写入前清理;删除时对应维度的 collection 尚不存在(首次写入前先删旧向量,或 Qdrant 被清空后)按"无可删"处理,不再阻断随后的写入;启停与标签批量更新逐 collection 执行,任一失败都会返回错误,而不是只记日志。
- 配置:`QDRANT_HOST` / `QDRANT_PORT` / `QDRANT_API_KEY` / `QDRANT_USE_TLS`。
#### Milvus {#_2-7-milvus}
@ -173,7 +174,7 @@ flowchart TD
- **集合管理**:每维度一个 collection(`{MILVUS_COLLECTION|weknora_embeddings}_{dim}`)。schema 含稠密向量 `embedding`(HNSW 索引,M=16 efConstruction=128,metric 由 `MILVUS_METRIC_TYPE` 决定:IP 默认 / COSINE / L2)与稀疏向量 `content_sparse` —— 通过 **内建 BM25 Function**(`entity.FunctionTypeBM25`)由 content 自动生成,配 `AutoIndex(BM25)`。新建 Collection 的 `content` 使用 Milvus 多语言分析器:英文 `english`、中文 `chinese`(内置 Jieba)、未知语言 `default`(ICU),并以 `language` 字段选择分析器。
- **向量检索**:`Search` + `WithANNSField(embedding)`,COSINE 模式原始值域 [-1,1],是唯一需要 `(score+1)/2` 归一化的引擎。
- **关键词检索**:对 `content_sparse` 做 BM25 稀疏向量检索(Milvus 2.5+ 原生全文检索),查询时根据问题文本的语言传入 `analyzer_name`。
- **关键词检索**:对 `content_sparse` 做 BM25 稀疏向量检索(Milvus 2.5+ 原生全文检索),查询时根据问题文本的语言传入 `analyzer_name`。返回 Milvus 给出的真实 BM25 分数;跨多个维度 collection 检索时先按分数合并排序,再截取 TopK。
- **过滤**:`filter.go` 构造布尔表达式(kb/knowledge/tag/is_enabled)。
- **启停同步**:`BatchUpdateChunkEnabledStatus` 逐 collection 更新,失败用 `errors.Join` 聚合后**返回错误**而不是只打 warn——主库里已停用的分块绝不能因为索引更新静默失败而继续可被检索到。
- 配置:`MILVUS_ADDRESS` / `MILVUS_USERNAME` / `MILVUS_PASSWORD` / `MILVUS_DB_NAME` / `MILVUS_METRIC_TYPE`(改后需重建 collection)。旧 Collection 的 schema 不能直接改成多语言分析器;可运行 `go run ./cmd/milvus-migrate --source <旧前缀> --target <新前缀>` 复用已有稠密向量并沿用源 Collection 的 metric,确认检索正常后把 `MILVUS_COLLECTION` 改为新前缀。
@ -210,7 +211,7 @@ flowchart TD
#### Neo4j — 图谱检索(不在 Registry 体系内) {#_2-11-neo4j-—-图谱检索-不在-registry-体系内}
`internal/application/repository/retriever/neo4j/repository.go` 实现的是 `RetrieveGraphRepository`(`SearchNode(ctx, NameSpace, entities)`),不是向量/关键词引擎:按 `NameSpace{KnowledgeBase, Knowledge}` 检索实体节点与关系,服务于 chat pipeline 的 `ENTITY_SEARCH` 阶段(GraphRAG)。由 `NEO4J_ENABLE=true` + `NEO4J_URI`/`NEO4J_USERNAME`/`NEO4J_PASSWORD` 启用。
`internal/application/repository/retriever/neo4j/repository.go` 实现的是 `RetrieveGraphRepository`(`SearchNode(ctx, NameSpace, entities)`),不是向量/关键词引擎:按 `NameSpace{KnowledgeBase, Knowledge}` 检索实体节点与关系,服务于 chat pipeline 的 `ENTITY_SEARCH` 阶段(GraphRAG)。由 `NEO4J_ENABLE=true` + `NEO4J_URI`/`NEO4J_USERNAME`/`NEO4J_PASSWORD` 启用。单次查询最多从 200 个种子实体展开、最多返回 2000 行,详见[知识图谱](09-knowledge-graph.md)。
### Embedding 维度管理 {#_4-embedding-维度管理}
@ -225,6 +226,8 @@ WeKnora 允许不同 KB 使用不同 embedding 模型(维度各异),各引
| Elasticsearch | 单索引 `dense_vector` mapping(`ELASTICSEARCH_INDEX`),维度在 mapping 中固定 |
| OpenSearch | 按维度创建 `{OPENSEARCH_INDEX}_{dim}` 别名及物理索引;另有无维度的关键词索引 |
查询向量生成后会与模型配置的维度比对。不一致时(如模型服务更换了输出维度)直接返回错误码 2201,详情包含模型名、期望维度与实际维度,提示检查 Embedding 模型配置并重建索引;不会继续发往向量库后得到含糊的失败或空结果。
检索侧的一致性由 `validateSameEmbeddingModel`(`knowledgebase_search_shared.go`)保证:一次多库检索中的所有 KB 必须共享同一 embedding 模型身份(`model.Name + BaseURL`,跨租户可等价),否则拒绝——避免跨向量空间的分数不可比。查询向量按模型身份分组只计算一次(`ResolveEmbeddingModelKeys` + `GetQueryEmbedding`),随 `params.QueryEmbedding` 传播到所有 store 组,杜绝重复 embedding API 调用。
### 混合检索打分与归一化 {#_5-混合检索打分与归一化}
@ -255,7 +258,7 @@ rrfScore = vectorWeight/(rrfK + vectorRank) + keywordWeight/(rrfK + keywordRank)
- rank 为各路结果的 1-indexed 排名(各引擎已按分排序返回);
- `rrfK`、`vectorWeight`、`keywordWeight` 来自租户 `RetrievalConfig`(`GetEffectiveRRFK` / `GetEffectiveRRFWeights` 提供缺省);
- 单路结果时不走 RRF,`deduplicateByScore` 保留每 chunk 最高原始分(对 FAQ 的 embedding 相似度语义很重要,如 `FAQDirectAnswerThreshold` 直接比对该分数)。
- 单路结果时不走 RRF,`deduplicateByScore` 保留每 chunk 最高原始分。只有向量结果时保持原始相似度(对 FAQ 的 embedding 相似度语义很重要,如 `FAQDirectAnswerThreshold` 直接比对该分数);只有关键词结果时,若最高分超过 1,则全部除以最高分折算到 [0,1],保持相对顺序,避免无上界的 BM25 分数让后续复合打分饱和。检索 trace 中仍记录原始 BM25 分数。
融合之后的复合打分(rerank 模型分 0.6 + 检索基础分 0.3 + 来源权重 0.1、MMR、FAQ/Wiki 加权)发生在 chat pipeline 的 `CHUNK_RERANK` 阶段,见[检索问答流程的重排阶段](../02-architecture/04-rag-pipeline.md#_3-4-chunk-rerank-—-重排、复合打分、mmr、wiki-加权)。

View File

@ -5,7 +5,7 @@
<Screenshot
src="/screenshots/settings-models.png"
caption="模型设置:按类型管理已添加的模型"
hint="展示模型列表(名称、类型、来源、默认标记)与「添加模型」表单,含连通性测试结果。" />
hint="展示模型列表(名称、类型、厂商图标与名称、默认标记)与「添加模型」入口。" />
添加模型时应检查连接配置和索引兼容性:
@ -26,13 +26,241 @@
## 添加与验证连接
在模型设置中选择类型和提供商,填写实际模型名称、服务地址与凭据,测试通过后保存。向量模型需要匹配索引维度;对话与视觉模型的上下文窗口应使用服务实际支持的大小,以便正确触发历史压缩。
添加模型时先选类型和来源:「API」接入远程服务,「Ollama」使用本地模型(重排模型不支持 Ollama)。远程模型按以下步骤配置:
修改连接地址时,测试可复用已保存凭据。模型调试器会实际发起请求,显示耗时、脱敏请求和响应结果,可用于检查向量维度、重排得分或流式输出。
1. **选择服务商**。列表只显示支持当前模型类型的厂商,选中后可跳转到该厂商或该模型的文档页。没有对应厂商时选「自定义(OpenAI 兼容接口)」。
2. **填写模型名称**。可从厂商内置的模型目录中选择,选项上标出上下文窗口、向量维度、推理和视觉能力;也可以直接输入目录里没有的模型名。选中目录中的模型时,会自动填入尚未填写的上下文窗口、最大输出 tokens、视觉支持和向量维度。
3. **填写 Base URL 与 API Key**,以及该厂商要求的额外字段(见[厂商额外字段](#厂商额外字段))。需要经企业网关访问时,可添加自定义请求头。
4. **核对「实际调用方式」**。对话与视觉模型会实时显示请求协议、能力来源(内置模型档案或厂商通用默认)、请求地址、思考开关传参、可选思考强度、上下文窗口和最大输出 tokens,用于在保存前确认配置会被怎样调用。
5. **测试连接后保存**。测试使用表单中当前填写的配置,不需要先保存;编辑已有模型时,API Key 使用已单独保存的值。测试后修改了配置,需要重新测试。
<Screenshot
src="/screenshots/model-editor-catalog.png"
caption="添加模型:从厂商目录选择模型并查看实际调用方式"
hint="打开「添加模型」抽屉,类型选对话、来源选 API,服务商选一个国内厂商(如阿里云 DashScope),展开模型名称下拉以显示上下文窗口 / 推理 / 视觉标记,同时露出下方「实际调用方式」面板(请求协议、能力来源、可选思考强度)和底部「测试连接」按钮。" />
「高级选项」中还可以设置:
| 选项 | 适用类型 | 说明 |
| --- | --- | --- |
| 向量维度 / 自定义输出维度 | 向量 | 维度需与索引一致。只有确认模型支持指定维度时才开启「自定义输出维度」 |
| 上下文窗口 | 对话、视觉 | 留空使用默认 200000。按厂商文档填写真实值;填得过大会导致智能体历史压缩不触发,上游直接拒绝请求 |
| 支持视觉/多模态 | 对话 | 模型是否接受图片输入 |
| 最大输出 tokens | 对话、视觉 | 单次回复的输出上限,留空沿用目录中该模型的默认值 |
| 后台并发上限 | 对话、视觉、向量 | 限制文档入库、富化等后台任务对该模型的并发数;0 或留空使用全局默认,不影响交互式对话 |
| 高级 → 协议覆盖 | 对话、视觉 | 强制使用某种请求协议,一般保持「自动」 |
| 高级 → 远端模型名 | 远程模型 | 实际发送给厂商的模型 ID,与模型名称不同时填写 |
| 高级 → 协议兼容覆盖(JSON) | 远程模型 | 修正个别接口与目录默认值不一致的请求字段,如 `{"max_tokens_field": "max_tokens"}`;留空表示不覆盖。写法与字段见[协议兼容覆盖](#协议兼容覆盖-compat-json) |
旧版本保存的对话模型如果带有 `thinking_control` 设置,高级区域会额外显示「思考参数格式(旧配置)」,改为「遵循目录默认」后由模型目录决定思考参数的写法。
模型目录决定对话模型能否思考以及可选的思考强度(关闭、自动、极低、低、中、高、极高、最大中的一部分)。智能体或对话中选择的强度不被模型支持时,会调整到最接近的可用等级。
### 协议兼容覆盖 compat JSON
同样是「OpenAI 兼容」接口,各家对请求字段的要求并不一致:有的只认 `max_tokens`,有的用不同字段开关思考,推理模型可能拒绝 `temperature`。内置厂商和已收录模型的这些差异已写在模型目录里,通常不需要填写这一项。该选项位于远程模型(WeKnora 云服务除外)的「高级选项 → 高级」中,以下情况才需要手动覆盖:
- 自建推理服务(vLLM、SGLang 等)或中转网关,接口行为和厂商默认值不一致;
- 厂商新发布的模型尚未收录,「实际调用方式」面板显示「厂商通用默认(未收录此模型)」,且调用报错;
- 厂商调整了接口,需要在升级前临时修正。
#### 填写规则
1. **先看协议**。对话、视觉模型的字段取决于「实际调用方式」面板里的「请求协议」,只接受该协议的字段;如果改了「协议覆盖」,JSON 也要改成新协议的字段。向量、重排、语音模型各用一组字段,与协议无关。
2. **只写要改的键**。没写的键继续沿用目录默认值。`extra_body` 等对象按键合并,数组整个替换。
3. **保存时校验**。输入必须是 JSON 对象。键名拼错、取值类型不对或枚举值不存在时,保存会失败并提示原因,不会等到对话时才报错。
4. **改完测试**。「测试连接」使用当前表单中的配置,无需先保存。
这里的覆盖优先级高于厂商默认值和模型目录;旧配置中的「思考参数格式」和「远端模型名」仍然最后生效。模型目录标注为不支持思考的模型,思考相关字段会被忽略。
`extra_body` 只补充 WeKnora 没有写入的字段,不能覆盖 `model`、`messages`、`max_tokens` 这类由 WeKnora 生成的字段。
#### 常见场景
| 现象 | 填写 |
| --- | --- |
| 报错不认识 `max_completion_tokens` | `{"max_tokens_field": "max_tokens"}` |
| 推理模型拒绝 `temperature` / `top_p` | `{"supports_temperature": false}` |
| 接口只接受固定温度(例如 1) | `{"fixed_temperature": 1}` |
| vLLM / SGLang 部署的 Qwen3 等混合思考模型无法关闭或开启思考 | `{"thinking_format": "chat-template-kwargs"}` |
| 网关不支持流式返回用量,流式请求报错 | `{"supports_usage_in_streaming": false}` |
| 网关拒绝带图片的消息结构 | `{"supports_multi_content": false}`(只发送文字,图片会被丢弃) |
| 需要附带厂商私有参数,如阿里云联网搜索 | `{"extra_body": {"enable_search": true}}` |
| 多轮对话回传思考内容时报错 | `{"replay_reasoning_content": false}` |
| 自建向量服务一次请求只接受 16 条 | `{"max_batch_size": 16}` |
| 向量或重排服务响应慢,需要更长的超时 | `{"request_timeout_seconds": 120}` |
| 自建重排服务返回的是未归一化分数(logit) | `{"score_scale": "logit"}` |
#### 字段参考
下表的「协议默认」是没有任何厂商、目录或覆盖时的取值;具体厂商的实际值以「实际调用方式」面板为准。
**OpenAI Chat Completions(`openai-completions`)**:绝大多数「OpenAI 兼容」厂商、自建服务和网关使用此协议。
| 字段 | 类型 | 协议默认 | 说明 |
| --- | --- | --- | --- |
| `max_tokens_field` | string | `max_completion_tokens` | 输出上限的字段名:`max_tokens` 或 `max_completion_tokens`,只发其中一个 |
| `thinking_format` | string | `none` | 思考开关的写法:`none` 不发;`openai` 只发 `reasoning_effort`;`thinking-type` 发 `{"thinking": {"type": ...}}`;`enable-thinking` 发 `enable_thinking`(配合预算字段);`chat-template-kwargs` 发 `chat_template_kwargs.enable_thinking`(vLLM / SGLang);`openrouter` 发 `{"reasoning": ...}` |
| `thinking_enabled_value` | string | `enabled` | `thinking-type` 写法开启思考时的 `type` 值(如 MiniMax 用 `adaptive`) |
| `thinking_always_send` | bool | false | 未指定思考偏好时也发送开关 |
| `thinking_disable_on_non_stream` | bool | false | 非流式调用时强制关闭思考(部分模型只允许在流式下思考) |
| `thinking_budget_field` | string | 空 | 思考预算的字段名,如 `thinking_budget`;空则不发 |
| `thinking_budget_excludes_effort` | bool | false | 厂商不允许预算和 `reasoning_effort` 同时出现时置 true,只保留思考强度 |
| `supports_reasoning_effort` | bool | false | 是否额外发送思考强度 |
| `reasoning_effort_field` | string | `reasoning_effort` | 思考强度的字段名 |
| `supports_developer_role` | bool | false | 推理模型的系统提示改用 `developer` 角色 |
| `supports_store` | bool | false | 发送 `store: false`,要求服务端不保留对话 |
| `supports_usage_in_streaming` | bool | true | 流式请求携带 `stream_options.include_usage` 以统计用量 |
| `supports_temperature` | bool | true | false 时不发送任何采样参数(温度、top_p、惩罚项) |
| `fixed_temperature` | number | 无 | 固定发送的温度值 |
| `supports_seed` | bool | true | 是否发送 `seed` |
| `tool_choice_modes` | string[] | `none`、`auto`、`required`、`function` | 允许的 `tool_choice` 取值 |
| `supports_parallel_tool_calls` | bool | true | 是否发送 `parallel_tool_calls` |
| `supports_response_format` | bool | true | 需要 JSON 输出时是否发送 `response_format` |
| `supports_multi_content` | bool | true | false 时图文混排的消息只保留文字部分 |
| `replay_reasoning_content` | bool | true | 多轮对话中把之前的思考内容回传给模型 |
| `reasoning_fields` | string[] | `reasoning_content`、`reasoning`、`reasoning_text` | 从响应中读取思考文本的字段,按顺序取第一个 |
| `tool_call_extra_fields` | string[] | 空 | 工具调用中需要原样回传的额外字段(如经 OpenAI 兼容口调用 Gemini 时的 `extra_content`) |
| `prompt_cache_key` | bool | false | 发送 `prompt_cache_key`,让同一会话命中提示缓存 |
| `cache_control_format` | string | 空 | 设为 `anthropic` 时按 Anthropic 格式插入缓存断点 |
| `prompt_cache_accounting` | bool | false | 厂商会返回缓存命中用量,用于统计 |
| `extra_body` | object | 空 | 附加到每次请求的字段 |
**OpenAI Responses(`openai-responses`)**:OpenAI 官方接口(`api.openai.com`)默认使用。
| 字段 | 类型 | 协议默认 | 说明 |
| --- | --- | --- | --- |
| `supports_developer_role` | bool | true | 系统提示使用 `developer` 角色 |
| `supports_max_output_tokens` | bool | true | 是否发送 `max_output_tokens` |
| `supports_reasoning_summary` | bool | true | 是否请求思考摘要 |
| `supports_encrypted_reasoning` | bool | true | 是否请求并回传加密的思考内容 |
| `supports_store` | bool | true | 发送 `store: false` |
| `supports_temperature` | bool | true | false 时不发送采样参数 |
| `prompt_cache_key` | bool | true | 发送提示缓存键 |
| `supports_long_cache_retention` | bool | true | 允许 24 小时的长缓存 |
| `supports_parallel_tool_calls` | bool | true | 是否发送 `parallel_tool_calls` |
| `extra_body` | object | 空 | 附加到每次请求的字段 |
**Anthropic Messages(`anthropic-messages`)**:Anthropic,以及 `base_url` 以 `/anthropic` 结尾的兼容接口。
| 字段 | 类型 | 协议默认 | 说明 |
| --- | --- | --- | --- |
| `thinking_mode` | string | `budget` | `budget` 按预算开启思考;`adaptive` 由模型自行决定,强度通过 `output_config.effort` 传递 |
| `supports_effort` | bool | false | 是否发送思考强度 |
| `thinking_budgets` | object | minimal 1024、low 2048、medium 8192、high 16384、xhigh 32768、max 63999 | 各思考强度对应的 `budget_tokens`,键为 `minimal`/`low`/`medium`/`high`/`xhigh`/`max` |
| `default_max_tokens` | int | 4096 | 未设置输出上限时使用的 `max_tokens`(该协议必填) |
| `supports_temperature` | bool | true | 是否发送温度 |
| `temperature_with_thinking` | bool | false | 开启思考时是否仍发送温度 |
| `supports_top_p` | bool | true | 是否发送 `top_p` |
| `supports_cache_control` | bool | true | 是否插入缓存断点 |
| `supports_cache_control_on_tools` | bool | true | 是否在工具定义上插入缓存断点 |
| `long_cache_ttl` | string | `1h` | 长缓存的有效期 |
| `version` | string | `2023-06-01` | `anthropic-version` 请求头 |
| `beta_headers` | string[] | 空 | 附加的 `anthropic-beta` 请求头 |
| `interleaved_thinking_beta` | string | `interleaved-thinking-2025-05-14` | 同时使用思考和工具时附加的 beta 标识;空字符串表示不发送 |
| `prompt_cache_accounting` | bool | true | 厂商会返回缓存命中用量 |
| `extra_body` | object | 空 | 附加到每次请求的字段 |
**Gemini(`google-generative-ai`)**:Gemini 原生接口。
| 字段 | 类型 | 协议默认 | 说明 |
| --- | --- | --- | --- |
| `thinking_mode` | string | `budget` | `budget` 发送 `thinkingBudget`(Gemini 2.5);`level` 发送 `thinkingLevel`(Gemini 3 起);`none` 不发送思考配置 |
| `thinking_budgets` | object | minimal 128、low 2048、medium 8192、high 24576、xhigh 32768、max 32768 | 各思考强度对应的 `thinkingBudget` |
| `include_thoughts` | bool | true | 是否返回思考内容 |
| `supports_seed` | bool | true | 是否发送 `seed` |
| `supports_penalty` | bool | true | 是否发送频率 / 存在惩罚 |
| `extra_generation_config` | object | 空 | 附加到 `generationConfig` 的字段 |
| `prompt_cache_accounting` | bool | true | 厂商会返回缓存命中用量 |
| `api_version_prefix` | string | `/v1beta` | `base_url` 只填主机时追加的版本路径 |
**向量模型**
| 字段 | 类型 | 协议默认 | 说明 |
| --- | --- | --- | --- |
| `api` | string | 厂商默认 | 向量协议:`openai-embeddings`、`dashscope-embeddings`、`ark-embeddings`、`google-embeddings` |
| `path` | string | 空 | 追加在 `base_url` 之后的路径 |
| `send_encoding_format` | bool | false | 是否发送 `encoding_format: "float"` |
| `dimensions_field` | string | 空 | 指定输出维度的字段名;仅在开启「自定义输出维度」时发送 |
| `truncate_field` / `truncate_value` | string | 空 | 输入过长时由服务端截断的开关字段与取值 |
| `input_type_field` | string | 空 | 区分「文档」和「查询」的字段名 |
| `input_type_values` | object | 空 | `document`、`query` 两种输入分别对应的取值 |
| `max_batch_size` | int | 0(不限) | 单次请求的最大条数,超出自动分批 |
| `max_input_chars` | int | 0(不限) | 单条输入的最大字符数 |
| `accepts_truncate_prompt_tokens` | bool | false | 服务是否支持 vLLM 的 `truncate_prompt_tokens` |
| `request_timeout_seconds` | int | 60 | 单次请求超时(秒) |
| `extra_body` | object | 空 | 附加到每次请求的字段 |
**重排模型**
| 字段 | 类型 | 协议默认 | 说明 |
| --- | --- | --- | --- |
| `path` | string | 空 | 追加在 `base_url` 之后的路径 |
| `send_top_n` | bool | false | 是否发送 `top_n`(不发时返回全部文档) |
| `send_return_documents` | bool | false | 是否要求服务端回传文档原文 |
| `score_scale` | string | `probability` | 分数含义:`probability`(0~1)或 `logit`(未归一化)。填错会让相关度阈值失效 |
| `truncate` | string | 空 | 服务端截断设置(如 NIM 的 `END`) |
| `max_documents` / `max_query_chars` / `max_document_chars` / `max_request_chars` | int | 0(不限) | 单次请求的文档数、查询长度、单篇长度与总长度上限,超出自动分批 |
| `max_concurrency` | int | 0(使用默认) | 分批后同时发出的请求数 |
| `accepts_truncate_prompt_tokens` | bool | false | 服务是否支持 vLLM 的 `truncate_prompt_tokens` |
| `request_timeout_seconds` | int | 0(不单独限制) | 单次请求超时(秒) |
| `extra_body` | object | 空 | 附加到每次请求的字段 |
**语音识别模型**
| 字段 | 类型 | 协议默认 | 说明 |
| --- | --- | --- | --- |
| `api` | string | 厂商默认 | `openai-transcriptions`(上传音频文件)或 `openai-chat-audio`(在对话请求中携带音频) |
| `path` | string | `/audio/transcriptions` | 追加在 `base_url` 之后的路径 |
| `response_format` | string | 空 | 发送的 `response_format`,需要分段结果时填 `verbose_json` |
| `language_param` | string | 空 | 语言提示的位置:`form`、`header`、`asr_options`;空则不发送 |
| `max_file_bytes` / `max_encoded_bytes` | int | 0(不限) | 音频文件与 base64 编码后的大小上限 |
| `formats` | string[] | 空(不限) | 接受的音频扩展名(不带点) |
| `request_timeout_seconds` | int | 300 | 单次请求超时(秒) |
## 内置厂商
内置 27 个厂商,另可通过 Ollama 接入本地模型。各厂商支持的模型类型如下(✓ 表示支持):
| 厂商 | ID | 对话 | 向量 | 重排 | 视觉 | 语音 |
| --- | --- | :-: | :-: | :-: | :-: | :-: |
| 自定义(OpenAI 兼容接口) | `generic` | ✓ | ✓ | ✓ | ✓ | ✓ |
| WeKnora 云服务 | `weknoracloud` | ✓ | ✓ | ✓ | ✓ | |
| 阿里云 DashScope | `aliyun` | ✓ | ✓ | ✓ | ✓ | ✓ |
| 智谱 BigModel | `zhipu` | ✓ | ✓ | ✓ | ✓ | ✓ |
| 火山引擎 | `volcengine` | ✓ | ✓ | ✓ | ✓ | |
| 腾讯混元 | `hunyuan` | ✓ | ✓ | | | |
| 硅基流动 | `siliconflow` | ✓ | ✓ | ✓ | ✓ | ✓ |
| MiniMax | `minimax` | ✓ | | | | ✓ |
| 月之暗面 Moonshot | `moonshot` | ✓ | | | ✓ | |
| 小米 MiMo | `mimo` | ✓ | | | | ✓ |
| 魔搭 ModelScope | `modelscope` | ✓ | ✓ | | ✓ | |
| 百度千帆 | `qianfan` | ✓ | ✓ | ✓ | ✓ | |
| 七牛云 | `qiniu` | ✓ | | | | |
| 美团 LongCat | `longcat` | ✓ | | | | |
| 腾讯云 LKEAP | `lkeap` | ✓ | | ✓ | | |
| DeepSeek | `deepseek` | ✓ | | | | |
| OpenAI | `openai` | ✓ | ✓ | | ✓ | ✓ |
| Azure OpenAI | `azure_openai` | ✓ | ✓ | | ✓ | |
| Anthropic | `anthropic` | ✓ | | | | |
| Google Gemini | `gemini` | ✓ | ✓ | | | |
| OpenRouter | `openrouter` | ✓ | ✓ | ✓ | ✓ | ✓ |
| LiteLLM | `litellm` | ✓ | ✓ | ✓ | ✓ | ✓ |
| Requesty | `requesty` | ✓ | ✓ | | ✓ | ✓ |
| Jina | `jina` | | ✓ | ✓ | | |
| NVIDIA | `nvidia` | ✓ | ✓ | ✓ | ✓ | |
| Novita AI | `novita` | ✓ | ✓ | ✓ | ✓ | |
| GPUStack | `gpustack` | ✓ | ✓ | ✓ | ✓ | ✓ |
表中的「视觉」指可在视觉模型类型下选择该厂商;对话模型本身是否接受图片,以模型目录和「支持视觉/多模态」开关为准。WeKnora 云服务需先在设置中保存云服务凭证,模型名称可选 `chat`、`embedding`、`rerank`、`vlm`。
厂商列表、默认地址和模型目录由服务端下发(`GET /api/v1/models/providers`),运维可以通过[部署叠加](#部署叠加-config-models-json)修改或新增厂商。
## 查看引用与调整配置
知识库和智能体保存对模型的引用。删除模型前需检查依赖详情;内置模型由 YAML 配置管理,应在配置文件中维护。调用量和缓存使用情况可结合[可观测性与审计](16-observability.md)查看。
知识库和智能体保存对模型的引用。删除模型前需检查依赖详情;内置模型由 YAML 配置管理,应在配置文件中维护。
模型调试器会对已保存的模型实际发起请求,显示耗时、脱敏请求和响应结果,可用于检查向量维度、重排得分或流式输出。能思考的对话模型可在调试器中选择思考强度,结果中会显示实际的请求协议和思考开关传参。调用量和缓存使用情况可结合[可观测性与审计](16-observability.md)查看。
## 配置与调用参考
@ -58,7 +286,7 @@ const (
| `VLLM` | `vllm` | `internal/models/vlm` | `Predict(imgBytes, prompt)` | 视觉语言模型(VLM),文档图片理解 / 多模态解析 |
| `ASR` | `asr` | `internal/models/asr` | `Transcribe(audioBytes, fileName)` 返回文本;模型提供时附带分段时间戳(如 OpenAI `whisper-1`) | 音频转写(自动语音识别) |
前后端类型映射见 `internal/handler/model.go` 的 `modelTypeToFrontend()`(`KnowledgeQA -> chat` 等)。
前后端类型映射见 `internal/handler/model_catalog.go` 的 `modelTypeToFrontend()`(`KnowledgeQA -> chat` 等)。创建模型的 REST 接口按原样保存 `type`,调用方应传后端取值(`KnowledgeQA` 等);`model_type` 查询参数则两种写法都接受。
模型来源(`ModelSource`)核心取值为两个:`local`(本地 Ollama 拉起)与 `remote`(远程 API);其余历史值(`aliyun`、`zhipu`、`openai` 等)为兼容保留,路由行为等同 `remote` + 对应 provider。
@ -68,48 +296,66 @@ const (
| 名称 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `base_url` | string | 空(可用 Provider 的 `DefaultURLs`) | 模型 API 地址,创建/更新时经过 SSRF 校验(`ValidateURLForSSRF`) |
| `api_key` | string | 空 | API 密钥,**AES-256-GCM 加密落库**(`ModelParameters.Value/Scan`),仅通过 `PUT /models/:id/credentials` 子资源修改 |
| `base_url` | string | 空(使用厂商默认地址) | 模型 API 地址,创建/更新时经过 SSRF 校验(`ValidateURLForSSRF`) |
| `api_key` | string | 空 | API 密钥,**AES-256-GCM 加密落库**(`ModelParameters.Value/Scan`)。创建时可随请求提交;之后只能通过 `PUT /models/:id/credentials` 子资源修改 |
| `interface_type` | string | 空(VLM:local 默认 `ollama`,remote 默认 `openai`) | 接口协议类型 |
| `embedding_parameters.dimension` | int | 0 | 向量维度 |
| `embedding_parameters.truncate_prompt_tokens` | int | 0 | 服务端截断 token 数。这是 vLLM 的扩展参数,只发给 `generic`、`gpustack`(为 0 时沿用历史值 511);托管厂商的文档里没有它,一律不发 |
| `embedding_parameters.supports_dimension_override` | bool | false | 是否在请求里指定向量维度。字段名由厂商决定(OpenAI 系 `dimensions`、Gemini `outputDimensionality`、百炼多模态 `parameters.dimension`);厂商文档里没有该参数的模型(NVIDIA NIM、混元、Novita、ada-002 等)即使勾选也不发 |
| `parameter_size` | string | 空 | Ollama 模型参数规模(如 "7B"),后端维护、前端不可改 |
| `provider` | string | 空(按 BaseURL 自动检测) | 厂商标识 |
| `extra_config` | map[string]string | nil | 厂商专属配置(由厂商定义的 `extraFields` 驱动,如 Azure 的 `api_version`);保留键 `api`(强制协议)、`remote_model_name`、`thinking_control`(旧版) |
| `provider` | string | 空(按 BaseURL 自动检测) | 厂商 ID,取值见[内置厂商](#内置厂商) |
| `extra_config` | map[string]string | nil | 厂商额外字段(见下节);保留键 `api`(强制对话协议)、`remote_model_name`(远端模型名)、`thinking_control`(旧版思考参数格式) |
| `spec` | object | nil | 单行目录覆盖:`api`、`reasoning`、`input`、`context_window`、`max_output_tokens`、`thinking_levels`、`compat`(协议相关的扁平 JSON) |
| `custom_headers` | map[string]string | nil | 附加自定义 HTTP 请求头(类似 OpenAI SDK `extra_headers`;`Authorization`、`api-key` 等保留头在运行期被忽略) |
| `supports_vision` | bool | false | Chat 模型是否接受图片多模态输入 |
| `context_window` | int | 0(回落到 200000) | 对话/VLM 上下文窗口(token)。智能体压缩历史按此上限工作;留空使用默认 200K。应填写服务实际支持的窗口大小,过高会导致压缩无法及时触发 |
| `supports_vision` | bool | false | 对话模型是否接受图片多模态输入 |
| `context_window` | int | 0(回落到 200000) | 对话/VLM 上下文窗口(token)。智能体按此上限加载与压缩历史;应填写服务实际支持的窗口大小,过高会导致压缩无法及时触发 |
| `max_output_tokens` | int | 0(沿用目录默认) | 对话/VLM 单次回复的输出上限 |
| `max_concurrency` | int | 0(回落到全局 `model.max_concurrency`) | 该模型后台任务并发上限(仅 chat/vlm/embedding 生效) |
| `app_id` / `app_secret` | string | 空 | WeKnoraCloud 专用凭证,`app_secret` AES 加密存储 |
| `app_id` / `app_secret` | string | 空 | WeKnora 云服务凭证;LKEAP / 火山引擎重排的第二段密钥也存于 `app_secret`。`app_secret` AES 加密存储 |
模型级字段还包括 `name`(运行期实际调用的模型名)、`display_name`、`type`、`source`、`is_default`(同一 `(tenant_id, type)` 桶内唯一默认)、`is_builtin`、`managed_by`、`status`(`active` / `downloading` / `download_failed`)。
#### 管理 API(`internal/router/router.go`)
远程对话和视觉模型的查询响应附带 `capabilities`(协议、是否可思考、可选思考等级、上下文窗口等),由服务端按目录解析得出。
### 厂商额外字段
厂商在定义中声明额外字段,编辑器据此动态渲染,值存入 `extra_config`(标记为密钥的字段不回显,只返回是否已配置):
| 厂商 | 字段 | 适用类型 | 说明 |
| --- | --- | --- | --- |
| Azure OpenAI | `api_version` | 全部 | 留空走 `/openai/v1` 数据面;填写版本号(如 `2025-04-01-preview`)则走旧的 `/openai/deployments/{部署名}` 路径 |
| 腾讯云 LKEAP | SecretKey(必填,按密钥加密保存)、`region`(默认 `ap-guangzhou`) | 重排 | 重排接口使用 TC3 签名,API Key 一栏填 SecretId |
| 火山引擎 | SecretKey(必填,按密钥加密保存)、`region`(默认 `cn-beijing`)、`instruction` | 重排 | 重排接口使用 AK/SK 签名,API Key 一栏填 Access Key ID;`instruction` 默认为控制台原文 |
| 自定义、GPUStack、LiteLLM | `score_scale` | 重排 | 「Rerank 分数标度」:`probability`(0~1 相关度,BGE 一类)或 `logit`(无界分数,Qwen3-Reranker 一类,会换算到 0~1 后再与重排阈值比较)。按端点后实际部署的模型选择 |
| 自定义、GPUStack | `truncate_prompt_tokens` | 重排 | vLLM 扩展参数,默认不发送;只在后端因文档过长报错时填写 |
#### 管理 API(`internal/router/routes_infra.go`)
| 方法 & 路径 | 说明 |
|-------------|------|
| `GET /models/providers` | 按 `model_type` 查询支持的厂商列表(`ListModelProviders`) |
| `GET /models/providers` | 按 `model_type` 查询支持的厂商定义(含图标、默认地址、额外字段、模型目录) |
| `GET` / `POST /models/catalog/resolve` | 解析一行配置的实际调用方式(协议、思考等级、上下文),即编辑器中的「实际调用方式」 |
| `POST /models` / `GET /models` / `GET /models/:id` / `PUT /models/:id` / `DELETE /models/:id` | 模型 CRUD |
| `PUT /models/:id/credentials`、`DELETE /models/:id/credentials/:field` | 凭证子资源;`PUT /models/:id` 请求体中的 `api_key` 会被强制忽略并告警 |
| `POST /models/:id/debug` | 模型调试(见下文) |
| `GET /models/weknoracloud/status` | WeKnoraCloud 凭证状态 |
| `GET /models/weknoracloud/status` | WeKnora 云服务凭证状态 |
完整请求与响应见 [API 参考:模型与初始化](../04-api/02-api-model-system.md)。
### 模型健康检查 / 连通性测试
两套机制,均在服务端持有凭证、不回传明文密钥:
1. **测试连接**(`internal/handler/initialization.go`,供模型创建/编辑表单的 "Test connection" 按钮):
1. **测试连接**(`internal/handler/initialization.go`,供模型编辑器的「测试连接」按钮):
- `POST /initialization/remote/check` — Chat 模型(`CheckRemoteModel` / `checkChatModelConnection`)
- `POST /initialization/embedding/test` — Embedding(`TestEmbeddingModel`)
- `POST /initialization/rerank/check` — Rerank(`CheckRerankModel`)
- `POST /initialization/asr/check` — ASR(`CheckASRModel`)
- `POST /initialization/multimodal/test` — VLM 多模态解析(`TestMultimodalFunction`)
请求体 `ModelTestRequest` 可携带 `modelId`:`fillSecretsFromStoredModel` 会把请求中缺失的 `APIKey` / `AppSecret` 从已存模型(解密后)补齐,实现"改 BaseURL 用旧密钥一键验证",前端无需也无法拿到明文密钥。`buildTestModel` 把请求转换为**不落库**的临时 `*types.Model`,与生产路径共享同一套 `ConfigFromModel` 映射。
请求体 `ModelTestRequest` 可携带 `modelId`:`fillSecretsFromStoredModel` 会把请求中缺失的 `APIKey` / `AppSecret`、`extraConfig` 与 `spec` 从已存模型(解密后)补齐,实现"改 BaseURL 用旧密钥一键验证",前端无需也无法拿到明文密钥。`buildTestModel` 把请求转换为**不落库**的临时 `*types.Model`,与生产路径共享同一套 `ConfigFromModel` 映射。
2. **模型调试器**(`POST /models/:id/debug`,`ModelHandler.DebugModel`):对已保存模型按类型发起真实调用并返回完整归一化响应——Chat 走流式并聚合 `stream_events` / thinking 观测项;Embedding 返回向量与维度;Rerank 返回打分结果;VLM / ASR 接受上传文件。响应含 `elapsed_ms`、脱敏后的请求预览(`redactedDebugConfig` 隐去 secret/token/api_key 类字段)与 `observations`。
2. **模型调试器**(`POST /models/:id/debug`,`ModelHandler.DebugModel`):对已保存模型按类型发起真实调用并返回完整归一化响应——Chat 走流式,可指定思考强度(`options.reasoning_effort`),并聚合协议、思考开关传参等观测项;Embedding 返回向量与维度;Rerank 返回打分结果;VLM / ASR 接受上传文件。响应含 `elapsed_ms`、脱敏后的请求预览与 `observations`。
### 内置模型机制
@ -123,6 +369,7 @@ const (
- 管理员在运行时接管某行(`managed_by` 置空)后,YAML 加载器会跳过该行("preserving runtime override")。
- `is_default: true` 条目会先清掉同 `(tenant_id, type)` 桶内其他默认,保持与 API 路径一致的唯一默认不变式。
- 校验规则:id 非空且 ≤64 字符(`ModelIDMaxLen`)、type 必须是 `KnowledgeQA | Embedding | Rerank | VLLM | ASR`、status 合法或为空;YAML 解析失败时中止对账(不执行漂移清理)。
- `parameters` 与 REST 接口使用同一套目录校验(`runtime.ValidateRow`):无法解析的行(未知协议、拼错的 compat 键、非法思考等级)只输出 WARN,不阻塞启动。
YAML 示例(摘自 `builtin_models.yaml.example`):
@ -137,6 +384,7 @@ builtin_models:
base_url: ${LLM_BASE_URL}
api_key: ${LLM_API_KEY}
provider: ${LLM_PROVIDER}
context_window: 200000 # 可选;省略时使用默认 200K
```
#### 本地模型下载(Ollama)
@ -155,9 +403,31 @@ builtin_models:
> 注意:`cmd/download/duckdb/duckdb.go` 与模型无关——它在构建镜像时预下载 DuckDB 的 `spatial`、`excel` 扩展,供数据分析工具使用。模型权重下载只发生在 Ollama 路径。
### 部署叠加 `config/models.json` {#部署叠加-config-models-json}
不改代码也能加厂商、改地址、补模型:复制 `config/models.json.example` 到 `config/models.json`(或用 `MODELS_CONFIG` 指定路径)。`providers` 按厂商 ID 键入,已知 ID 打补丁,新 ID 声明新厂商。
| 字段 | 说明 |
| --- | --- |
| `name` / `names` / `description` / `descriptions` / `website` | 展示名称、按语言的名称与描述、官网 |
| `api` | 默认对话协议(`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai`) |
| `base_url` / `base_urls` | 默认地址;`base_urls` 按 `chat`、`embedding`、`rerank`、`vlm`、`asr` 分别指定 |
| `api_key` | 部署级密钥,模型行未保存密钥时使用;支持 `${ENV}` / `$ENV` 插值,未设置的变量展开为空 |
| `auth` / `requires_auth` | 鉴权方式(`bearer`、`api-key`、`x-api-key`、`x-goog-api-key`、`none`)与是否必须填写密钥 |
| `headers` | 附加请求头 |
| `model_types` / `url_patterns` | 新厂商支持的模型类型;未填 provider 的旧行按 URL 子串识别厂商 |
| `compat` / `thinking_levels` | 厂商级协议兼容开关与思考等级映射 |
| `models` | 按 ID upsert:已存在的 ID 只覆盖写出来的字段,未写的 `reasoning`、`thinking_levels`、`compat`、`input` 保持原样;新 ID 整条新建 |
| `model_overrides` | 按 ID 修补已有条目(如 `context_window`、`max_output_tokens`) |
| `icon` | 内联 `<svg …>` 字符串,或相对于叠加文件所在目录的 `.svg` 路径;不接受绝对路径、不能越出该目录、不超过 256 KB(图标会以 data URI 下发给所有能打开模型页的人) |
叠加在启动时整体校验后生效:出现未知键、非法鉴权方式或无法解析的模型条目时,整份叠加都不生效,启动日志输出 `Load models catalog overlay failed`,服务继续使用内置目录。目前不监听文件变更,修改后需重启服务。运行时不会从外部拉取模型数据,字段名、思考格式这类行为事实由人维护。
叠加只改变厂商定义和模型目录;每个模型仍单独保存自己的 URL、API Key、额外字段和 `spec`,不会修改已有模型的 ID 或引用关系。
### 模型用量统计
- **Token 用量**:`types.TokenUsage`(`internal/types/chat.go`)记录 `prompt_tokens / completion_tokens / total_tokens` 及 prompt cache 细分(`cache_read_tokens / cache_write_tokens / cache_miss_tokens / cache_status`)。每个 Chat 实现通过 `internal/models/chat/usage.go` 的 `logUsage` 输出统一的结构化日志行:
- **Token 用量**:`types.TokenUsage`(`internal/types/chat.go`)记录 `prompt_tokens / completion_tokens / total_tokens` 及 prompt cache 细分(`cache_read_tokens / cache_write_tokens / cache_miss_tokens / cache_status`)。所有协议客户端通过 `internal/models/api/usage_log.go` 的 `LogUsage` 输出统一的结构化日志行:
```go
logger.Infof(ctx,
@ -168,141 +438,82 @@ builtin_models:
其中 `purpose` 来自 `types.WithLLMCallMetadata`(如 `document_summary`、`entity_extraction`),可按用途聚合。
- **链路追踪**:启用 Langfuse 时,每类模型都有 `langfuse_wrapper.go` 装饰器把调用(含 usage)上报为 trace/span。
- **流式响应**:usage 随最后的 `StreamResponse` 事件返回(模型调试器会将其聚合进 `usage` 字段)。
- **并发水位**:如上节所述,`GET /system/admin/runtime/queues` 暴露每模型实时 `active / waiting / limit`。
- **并发水位**:`GET /system/admin/runtime/queues` 暴露每模型实时 `active / waiting / limit`(见下文[并发与限流](#并发与限流-limiter))。
## 模型调用与实现参考
### 厂商目录(catalog)
### 分层结构
模型接入按数据、厂商、运行时、协议分工:
模型接入按协议、厂商、目录、运行时分工:
| 层 | 位置 | 职责 |
|----|------|------|
| 协议层 | `internal/models/api/<protocol>` | 一个 wire 协议一个包。对话:`openaicompletions`、`openairesponses`、`anthropicmessages`、`googlegenai`;重排:`cohererank`、`dashscoperank`、`nimrerank`;向量:`openaiembeddings`、`dashscopeembeddings`、`arkembeddings`、`googleembeddings`;语音:`openaitranscriptions`。各自持有请求/响应结构与解析,不依赖厂商注册表或模型目录 |
| 厂商层 | `internal/models/providers/<id>.go` | 一个厂商一份定义,同时声明 Chat、Embedding、Rerank、ASR;图标放 `providers/assets/`,在 `builtin.go` 显式注册 |
| 目录层 | `internal/models/catalog` | 加载统一生成的目录,管理部署叠加与原子替换 |
| 运行时 | `internal/models/runtime` | 合并单个模型配置、选择协议、组装该模型的认证和端点,隔离旧字段推断 |
| 协议层 | `internal/models/api/<protocol>` | 一个 wire 协议一个包。对话:`openaicompletions`、`openairesponses`、`anthropicmessages`、`googlegenai`;重排:`cohererank`、`dashscoperank`、`nimrerank`、`tencentlkeap`、`volcengineknowledge`;向量:`openaiembeddings`、`dashscopeembeddings`、`arkembeddings`、`googleembeddings`;语音:`openaitranscriptions`、`openaichataudio`。各自持有请求/响应结构与解析,不依赖厂商定义或模型目录 |
| 厂商层 | `internal/models/providers/<id>.go` | 一个厂商一份定义,声明支持的模型类型、各类型默认地址、鉴权方式、额外字段、协议兼容默认值与特殊端点钩子;图标放 `providers/assets/`,在 `builtin.go` 的 `Builtins()` 显式列出 |
| 目录层 | `internal/models/catalog` | 加载生成的模型目录 `catalog/data/models.generated.json`,按类型和模型名查询条目;不含厂商行为 |
| 运行时 | `internal/models/runtime` | 组合厂商定义与目录、应用部署叠加(`overlay.go`),合并单个模型配置、选择协议、组装认证和端点,隔离旧字段推断 |
`runtime.Resolve(Ref{Provider, Model, BaseURL, Extra, Override})` 的合并顺序从低到高:
`runtime.Resolve(Ref{Provider, Model, BaseURL, ModelType, Extra, Override})` 的合并顺序从低到高:
1. 协议默认值(`DefaultOpenAICompletions()` 等);
2. 厂商级 `Compat`(`providers/<id>.go` 里声明,例如 DeepSeek 的 `max_tokens_field: max_tokens`);
3. `catalog/data/models.generated.json` 里匹配到的条目(精确 id → `aliases` → `match` 通配,最长字面前缀优先);
4. 部署叠加 `config/models.json`(见下);
5. 模型行上的 `parameters.spec`(UI「高级」里的协议覆盖与 compat JSON);
6. `extra_config.api` 强制协议、`extra_config.thinking_control` 旧版思考编码、`extra_config.remote_model_name`。
2. 厂商级 `Compat`(`providers/<id>.go` 里声明,例如 DeepSeek 的 `max_tokens_field: max_tokens`;部署叠加的厂商级 `compat` 也在这一层);
3. 目录中匹配到的条目(精确 id → `aliases` → `match` 通配,最长字面前缀优先;部署叠加的 `models` / `model_overrides` 已合入目录);
4. 模型行上的 `parameters.spec`(编辑器「高级」里的协议覆盖与 compat JSON);
5. `extra_config.api` 强制协议、`extra_config.thinking_control` 旧版思考编码、`extra_config.remote_model_name`。
厂商参数依据厂商文档维护,每个 `providers/<id>.go` 的包注释列出依据与文档链接,目录条目的 `source` 字段记录来源。对应的出站 JSON 由各协议包的 golden 测试钉死(如 `openaicompletions/golden_test.go`)。
厂商参数依据厂商文档维护,每个 `providers/<id>.go` 的注释列出依据与文档链接,目录条目的 `source` 字段记录来源。对应的出站 JSON 由各协议包的 golden 测试钉死(如 `openaicompletions/golden_test.go`)。
#### 关键 compat 字段(OpenAI Chat Completions 方言)
各协议的 compat 字段、协议默认值与常见用法见[协议兼容覆盖](#协议兼容覆盖-compat-json);结构定义在 `internal/models/api/compat_settings.go`(对话协议)以及同目录的 `embeddings_settings.go`、`rerank_settings.go`、`transcriptions_settings.go`。
| 字段 | 含义 | 典型厂商 |
|------|------|----------|
| `max_tokens_field` | `max_tokens` 或 `max_completion_tokens`,二者只发一个 | DeepSeek / 智谱 / 硅基流动 用 `max_tokens`;OpenAI / 火山 用 `max_completion_tokens` |
| `thinking_format` | `openai`(`reasoning_effort`)、`thinking-type`(`thinking.type`)、`enable-thinking`(`enable_thinking` + `thinking_budget`)、`chat-template-kwargs`(vLLM)、`openrouter`(`reasoning`)、`none` | 见各厂商 |
| `supports_reasoning_effort` | 是否额外发 `reasoning_effort` | DeepSeek、智谱、火山、OpenAI |
| `thinking_always_send` / `thinking_disable_on_non_stream` | 每次请求都钉开关;非流式强制关 | 百炼混合思考模型 |
| `thinking_budget_excludes_effort` | 厂商禁止 `thinking_budget` 与 `reasoning_effort` 同发,发了报错;置真时按档位优先、丢掉预算 | 百炼 qwen3.8 系列 |
| `supports_temperature` / `fixed_temperature` | 推理模型拒绝采样参数;Moonshot v1 固定 1 | GPT-5 / o 系列、Kimi K2.5+ |
| `tool_choice_modes` | 允许的 `tool_choice` 取值 | DeepSeek 思考模式不支持 `required` |
| `replay_reasoning_content` | 多轮回传 `reasoning_content` | DeepSeek、MiMo、Kimi |
| `prompt_cache_key` / `cache_control_format` | OpenAI 缓存路由 / Anthropic 式断点 | OpenAI、OpenRouter、百炼 |
思考强度在内部统一为 `off / auto / minimal / low / medium / high / xhigh / max`,每个模型的 `thinking_levels` 把统一等级映射到厂商取值(`null` 表示不支持,`"off": null` 表示无法关闭思考,如 DeepSeek Reasoner、QwQ、Kimi K3)。请求的等级不受支持时,先向上、再向下取最近的已支持等级。
思考强度在内部统一为 `off / auto / minimal / low / medium / high / xhigh / max`,每个模型的 `thinking_levels` 把统一等级映射到厂商取值(`null` 表示不支持,`"off": null` 表示无法关闭思考,如 DeepSeek Reasoner、QwQ、Kimi K3),不支持的等级按 PI 的规则就近钳位。
#### 协议选择
#### 内置厂商
`GET /api/v1/models/providers?model_type=chat` 返回全部厂商定义(图标 data URI、默认地址、额外字段、内置模型与思考能力),前端完全据此动态渲染,没有本地厂商表。目前内置 27 个厂商:`generic`、`weknoracloud`、`aliyun`、`zhipu`、`volcengine`、`hunyuan`、`siliconflow`、`deepseek`、`minimax`、`moonshot`、`mimo`、`modelscope`、`qianfan`、`qiniu`、`longcat`、`lkeap`、`openai`、`azure_openai`、`anthropic`、`gemini`、`openrouter`、`litellm`、`requesty`、`jina`、`nvidia`、`novita`、`gpustack`;Ollama 走 `source=local` 独立路径。
协议选择:Anthropic 走 Messages 协议;Gemini 默认走原生 `generateContent`(`base_url` 指向 `/v1beta/openai` 则保持 OpenAI 兼容);OpenAI 在 `api.openai.com` 上走 Responses 协议,中转/代理保持 Chat Completions;任何厂商 `base_url` 以 `/anthropic` 结尾时自动切到 Messages 协议(MiniMax、智谱、Kimi 的 Anthropic 兼容口)。单行 `spec.api` 的明确选择优先于 URL 和厂商推断;兼容旧配置的 `extra_config.api` 仍具有最高优先级。`extra_config.api` 可强制指定对话协议,只对 chat / VLM 行生效;embedding 行的协议覆盖写在 `spec.compat` 的 `"api"` 里,取值是向量协议(`openai-embeddings`、`dashscope-embeddings`、`ark-embeddings`、`google-embeddings`)。
Anthropic 走 Messages 协议;Gemini 默认走原生 `generateContent`(`base_url` 指向 `/v1beta/openai` 则保持 OpenAI 兼容);OpenAI 在 `api.openai.com` 上走 Responses 协议,中转/代理保持 Chat Completions;任何厂商 `base_url` 以 `/anthropic` 结尾时自动切到 Messages 协议(MiniMax、智谱、Kimi 的 Anthropic 兼容口)。单行 `spec.api` 的明确选择优先于 URL 和厂商推断;兼容旧配置的 `extra_config.api` 仍具有最高优先级。`extra_config.api` 可强制指定对话协议,只对 chat / VLM 行生效;embedding 行的协议覆盖写在 `spec.compat` 的 `"api"` 里,取值是向量协议(`openai-embeddings`、`dashscope-embeddings`、`ark-embeddings`、`google-embeddings`)。
目录条目按模型类型查找:embedding 行只匹配 embedding 条目,不会被同名前缀的对话通配(如百炼的 `qwen3*`、OpenAI 的 `gpt-5*`)套上对话的 compat。目录里还没有的新 id、带日期的快照照常按厂商默认解析。
#### 新增厂商
同一厂商的多种能力在一份定义中声明;共用协议不需要复制实现:
1. 新建 `internal/models/providers/<id>.go`,声明名称、能力、各类型默认地址、认证方式、协议默认值及特殊端点钩子,写明官方文档依据;
2. 在 `internal/models/catalog/data/seed.json` 的对应厂商中维护模型元数据;在 `internal/models/catalog/data/overrides.json` 中维护协议、思考映射与 compat 修正。模型键包含类型与 id / match,同名 Chat 和 Embedding 可以共存;
3. 将图标放入 `providers/assets/<id>.svg` 并引用,在 `providers/builtin.go` 的 `Builtins()` 列表加入定义,由 runtime 按厂商 ID 组合模型目录;
4. 执行 `make model-catalog-generate` 生成统一目录。生成文件不直接手改;已有协议可以复用,新协议才增加 `api/<protocol>` 包。
然后跑一条命令,目录层的守护测试会自动覆盖新厂商,无需为它单独写用例:
```bash
make model-catalog-check
```
它先检查生成数据是否过期,再运行模型模块全部测试:`providers` 的注册与图标检查;`runtime` 的解析与叠加;`parity` 包的**不变量**(每个模型条目的字段合法性、compat 键名可解码、上下文与最大输出自洽)和**逐模型出站请求检查**(每个对话模型在思考开 / 关两种情况下,只能出现一个输出上限字段;不支持采样参数的模型不得带 temperature;始终思考的模型不得收到关闭开关等)。新加的厂商和模型一旦违反这些规则,测试直接失败。
前端不需要任何改动:厂商下拉、图标、额外字段、内置模型列表都由 `GET /api/v1/models/providers` 动态渲染。
写入侧也有一道闸:`runtime.ValidateRow` 会在创建 / 更新模型(REST)和加载 `config/builtin_models.yaml`(启动)时解析这行配置(全部模型类型),未知协议、拼错的 compat 键、非法的思考档位在写入时就被拒绝(YAML 行只打 WARN 不阻塞启动,避免一次重启把线上模型下线)。
#### 厂商更新了模型怎么办
新增厂商、维护模型目录与厂商行为的开发流程见[扩展点指南](../06-development/03-extension-points.md#_4-新增模型-provider-internal-models-provider)。
分两种情况:
### 从 v0.8.0 升级的行为变化
**只是新增 / 调整模型元数据**(新模型 id、上下文窗口、价格)。先拿差异报告,再人工核对厂商文档更新 `internal/models/catalog/data/seed.json`,再运行 `make model-catalog-generate`:
老库里的模型行**不需要任何迁移**:`parameters` 列只增加了可选的 `spec` 字段,v0.8.0 的全部 `provider` 取值仍然注册,`extra_config` 的历史键(`thinking_control` 的每个取值、`remote_model_name`、`api_version`、`secret_key`、`region`、`instruction`、`truncate_prompt_tokens`)语义不变,目录里已没有的模型 id(自定义微调、已退役型号)照常解析并保留思考开关。这些由 `internal/models/runtime/legacy_rows_test.go` 与 `internal/types/legacy_persisted_json_test.go` 钉住。
```bash
make model-catalog-diff # 全部厂商
make model-catalog-diff VENDOR=deepseek # 只看一家
```
以下既有模型行的运行时行为会变,升级时需要知会使用者。
报告对比 [models.dev](https://models.dev/api.json) 的公开元数据:`+` 是上游有而我们没有的模型,`~` 是数值差异,`?` 是上游没收录的条目(国内厂商和别名经常如此,不代表错)。脚本只读不写,也从不在运行时调用——**字段名、思考格式这类行为事实不会被自动同步**,必须以厂商文档为准手工维护,这是刻意的取舍:models.dev 不携带这些信息,自动同步会让线上请求悄悄改变行为。
对话模型(逐厂商断言见 `internal/models/parity/parity_test.go`):
**厂商改了接口行为**(换了输出上限字段、新增 effort 取值、思考开关格式变化)。改 `providers/<id>.go` 或 `catalog/data/overrides.json` 中对应模型的 `compat`,再生成目录,并同步更新包注释里的文档链接;`internal/models/api/openaicompletions/golden_test.go` 之类的快照测试会把出站 JSON 钉死,改动必须先改测试预期,评审时一眼能看到行为变化。
1. **`extra_config.api` 变成保留键**。它现在是协议选择器(`openai-completions` / `openai-responses` / `anthropic-messages` / `google-generative-ai` / `ollama`),取值非法会在创建、更新模型时返回 400。只有手工调 REST 或写 YAML 造出来的行会受影响,升级前删掉或改成合法取值。
2. **Azure OpenAI 未填 `api_version` 的行改走 `/openai/v1` GA 数据面**,不再是 `/openai/deployments/{model}/...?api-version=2024-10-21`。要保留旧路径,在额外字段里显式填一个 `api_version`。
3. **`api.openai.com` 的一方流量改走 Responses 协议**。各类中转 / 网关仍走 Chat Completions。
4. **7 家厂商的输出上限字段按文档纠正**:hunyuan、modelscope、qiniu、requesty、longcat、novita 由 `max_completion_tokens` 改回 `max_tokens`,moonshot 反向改为 `max_completion_tokens`。aliyun 保持 `max_completion_tokens`。
**紧急情况不必等发版**:用下面的部署叠加在配置里先改,验证无误后再补回代码。
重排模型(逐厂商出站请求见 `internal/models/rerank/wire_test.go`):
#### 部署叠加 `config/models.json`
1. **OpenAI 不再出现在重排的厂商列表里**。OpenAI 没有 rerank 接口;架在 OpenAI 风格地址后面、自带 rerank 的中转请建成 `generic` 行。已有的行照常解析。
2. **火山引擎重排每次最多 200 条**(原实现按 50 条切分),默认指令改为控制台原文 `Whether the document answers the query or matches the content retrieval intent`。已在额外字段里保存了指令的行不受影响。
不改代码也能加厂商、改地址、补模型:复制 `config/models.json.example` 到 `config/models.json`(或用 `MODELS_CONFIG` 指定路径),采用按厂商组织的部署覆盖结构:`providers` 按厂商 id 键入,已知 id 打补丁,新 id 声明新厂商;支持 `base_url` / `base_urls`、`api_key`(`${ENV}` 插值)、`headers`、`compat`、`thinking_levels`、`models`(按 id upsert:已存在的 id 只覆盖你写出来的字段,没写的 `reasoning`、`thinking_levels`、`compat`、`input` 保持原样;新 id 则整条新建)、`model_overrides`、`icon`(内联 `<svg …>` 字符串,或相对于叠加文件所在目录的 `.svg` 路径——不接受绝对路径、不能越出该目录、必须是 256 KB 以内的 SVG,因为图标会以 data URI 下发给所有能打开模型页的人)。未知键在启动时报错。运行时不会自动从外部拉取模型数据:字段名、思考格式这类行为事实必须由人维护。
向量模型(逐厂商出站请求见 `internal/models/embedding/wire_test.go`):
#### 升级到目录化实现的注意事项
老库里的模型行**不需要任何迁移**:`parameters` 列只增加了可选的 `spec` 字段,旧的 26 个 `provider` 取值全部仍然注册,`extra_config` 的历史键(`thinking_control` 的每个取值、`remote_model_name`、`api_version`、`secret_key`、`region`、`instruction`、`truncate_prompt_tokens`)语义不变,目录里已没有的模型 id(自定义微调、已退役型号)照常解析并保留思考开关。这些由 `internal/models/runtime/legacy_rows_test.go` 与 `internal/types/legacy_persisted_json_test.go` 钉住。
但有四处**既有模型行的运行时行为会变**,升级时需要知会使用者:
1. **`extra_config.api` 变成保留键**。它现在是协议选择器(`openai-completions` / `openai-responses` / `anthropic-messages` / `google-generative-ai` / `ollama`),取值非法会在创建、更新模型时返回 400。WeKnora 自身从未写过这个键,只有手工调 REST 或写 YAML 造出来的行会受影响——升级前删掉或改成合法取值。这里刻意选择报错而不是忽略:静默忽略会让人以为切换生效了。
2. **Azure OpenAI 未填 `api_version` 的行改走 `/openai/v1` GA 数据面**,不再是 `/openai/deployments/{model}/...?api-version=2024-10-21`。旧默认版本根本不支持它同时声称的 `reasoning_effort` 与 `max_completion_tokens`,属于自相矛盾。要保留旧路径,在额外字段里显式填一个 `api_version`。
3. **`api.openai.com` 的一方流量改走 Responses 协议**(`PreferAPI` 只对官方域生效)。各类中转 / 网关仍走 Chat Completions,`parity` 包里有断言钉住这一点。
4. **7 家厂商的输出上限字段按文档纠正**:hunyuan、modelscope、qiniu、requesty、longcat、novita 由 `max_completion_tokens` 改回 `max_tokens`,moonshot 反向改为 `max_completion_tokens`。每一处在 `internal/models/parity/parity_test.go` 里都记了变更理由与厂商文档。aliyun 保持 `max_completion_tokens` 不变:兼容模式两个字段都收,但 DashScope 的参数表已经把 `max_tokens` 标为即将废弃并指名了继任者。
Rerank 行(逐厂商的出站请求由 `internal/models/rerank/wire_test.go` 钉住,含火山与 LKEAP 两个签名 SDK 客户端):
1. **OpenAI 不再出现在 rerank 的厂商列表里**。OpenAI 的 API 没有 rerank 接口,在这里建的行只会 404;架在 OpenAI 风格地址后面、自带 rerank 的中转请建成 generic 行。已有的行照常解析。
2. **火山 rerank 每次最多 200 条**(文档:datas「数组长度不超过 200」),旧实现按自己定的 50 条切分。
3. **火山 rerank 的默认指令改为控制台原文** `Whether the document answers the query or matches the content retrieval intent`,文档要求「如需对齐控制台效果,请使用相同指令」;旧默认值把 Document / Query 写成了大写。已在额外字段里保存了指令的行不受影响。
Embedding 行也有几处按厂商文档纠正的行为变化(逐厂商的出站请求由 `internal/models/embedding/wire_test.go` 钉住):
1. **托管厂商不再收到 `truncate_prompt_tokens`**。此前所有 OpenAI 兼容厂商都被塞了一个 511,它只是 vLLM 的扩展参数;`generic`、`gpustack` 照旧发送。
2. **NVIDIA NIM 的检索查询改用 `input_type: query`**。文档侧照旧是 `passage`,已有索引不受影响;这一标记在一次检索重构里丢失过,现在由 `types.WithEmbedQuery` 在三处查询入口设置。超长输入改为 `truncate: END` 截断而不是报错;`dimensions` 不再发送(NIM 没有这个参数)。目录里已被 NVIDIA 标记下线的 `nv-embed-v1`、`llama-3.2-nemoretriever-300m-embed-v1`、`baai/bge-m3` 已移除。
3. **阿里云按模型分流**:文本模型走 `/compatible-mode/v1/embeddings`,`qwen3-vl-embedding`、`qwen2.5-vl-embedding`、`tongyi-embedding-vision*`、`multimodal-embedding*` 走原生多模态接口。`base_url` 只填主机、国际站或业务空间域名时保留该主机,不再被替换成北京默认地址。
4. **火山方舟的文本向量接口已归档下线**,当前只有多模态接口。沿用老的 `doubao-embedding-text*` / `doubao-embedding-large-text*` 的行改发到它们归档文档里的 `/api/v3/embeddings`;此前它们被发往多模态接口。
5. **Gemini 的缩维放进 `embedContentConfig.outputDimensionality`**。请求顶层的同名字段已被文档标为 deprecated;旧实现发的是顶层 `output_dimensionality`。
1. **托管厂商不再收到 `truncate_prompt_tokens`**,`generic`、`gpustack` 照旧发送。
2. **NVIDIA NIM 的检索查询改用 `input_type: query`**(文档侧仍是 `passage`,已有索引不受影响),超长输入按 `truncate: END` 截断,不再发送 `dimensions`;目录移除了 NVIDIA 已下线的 `nv-embed-v1`、`llama-3.2-nemoretriever-300m-embed-v1`、`baai/bge-m3`。
3. **阿里云按模型分流**:文本模型走 `/compatible-mode/v1/embeddings`,`qwen3-vl-embedding`、`qwen2.5-vl-embedding`、`tongyi-embedding-vision*`、`multimodal-embedding*` 走原生多模态接口。`base_url` 只填主机、国际站或业务空间域名时保留该主机。
4. **火山方舟的文本向量接口已归档下线**。沿用 `doubao-embedding-text*` / `doubao-embedding-large-text*` 的行改发到归档文档里的 `/api/v3/embeddings`,其余走多模态接口。
5. **Gemini 的缩维放进 `embedContentConfig.outputDimensionality`**,不再发请求顶层的 `output_dimensionality`。
6. **SiliconFlow 每次最多 32 条、百炼 `text-embedding-v1/v2` 最多 25 条**,超出时自动拆批;v1/v2 固定 1536 维,不发 `dimensions`。
7. **OpenAI 兼容回复里没有 `index` 时按顺序取**(和旧实现一致);有 `index` 就按它放回,重复或缺位报错。
8. **Jina 的 `task`、Gemini 的 `taskType`、OpenRouter 的 `input_type`、火山的 `instructions`、百炼原生接口的 `text_type` / `instruct` 都不发**。它们会改变文档侧向量,开启后同一个知识库里新旧向量不在同一空间;需要按行显式开启的设计另见 Tencent/WeKnora#1401。
7. **Jina 的 `task`、Gemini 的 `taskType`、OpenRouter 的 `input_type`、火山的 `instructions`、百炼原生接口的 `text_type` / `instruct` 都不发**,以免同一知识库里新旧向量不在同一空间。
ASR 行的变化(逐厂商的出站表单由 `internal/models/asr/wire_test.go` 钉住):
语音模型(逐厂商出站表单见 `internal/models/asr/wire_test.go`):
1. **不再一律发 `response_format=verbose_json`**。OpenAI 文档写明 gpt-4o-transcribe / gpt-4o-mini-transcribe「only supported format is json」,旧实现发给它们必然 400;GPUStack 的音频后端 vox-box 在 FunASR 模型(SenseVoice、Paraformer)上对 `verbose_json` 返回裸字符串,旧实现解不开。现在只有文档写明支持的模型声明它(OpenAI `whisper-1`),其余走默认 json,Langfuse 里的音频时长因此只在返回分段的模型上有。需要分段的自建行可以在 `spec.compat` 里写 `{"response_format": "verbose_json"}`。
2. **按厂商文档的上限和格式在上传前拒绝**:文件大小(OpenAI / 智谱 / OpenRouter 25 MB、Requesty 32 MB、SiliconFlow / MiniMax 50 MB;阿里与小米按整段 `data:` URI 计 10 MB),以及文档给出封闭格式清单的厂商(智谱、小米只收 wav/mp3,OpenAI、Requesty、MiniMax 各有列表)。
3. **回复里没有 `text` 字段即报错**,不再当成「未检测到语音」入库;静音音频返回的是空字符串 `text`,照常处理。
4. ASR 行现在带上 provider 走目录解析,go-openai 依赖随之移除。provider 没有声明 ASR 的行:显式填了该厂商的直接报错;没填、靠 URL 识别到的,按 OpenAI 形状打到它的 URL(与旧实现一致),不走该厂商的 Endpoint 钩子。
5. **支持 ASR 的厂商按文档补齐**。OpenAI 形状(multipart `file` + `model`):openai、siliconflow、gpustack、generic、智谱(`glm-asr-2512`,单文件 ≤30 秒)、MiniMax(`asr-1.0`,路径是 `/v1/speech_to_text`)、OpenRouter、Requesty、LiteLLM。经 chat completions 的 `input_audio`(base64 data URI,编码后 ≤10 MB):阿里云 `qwen3-asr-flash`、小米 `mimo-v2.5-asr`。
6. **知识库的「音频语言提示」终于发出去了**(此前从未接线)。位置按厂商文档:OpenAI / Requesty / OpenRouter / GPUStack / generic 是 `language` 表单字段,MiniMax 是 `language` 请求头,阿里与小米是 `asr_options.language`;智谱、SiliconFlow、LiteLLM 文档没有这个参数,不发。填 `auto` 等同留空。
7. **音频时长从回包里读**:MiniMax 的 `duration`、OpenAI 系与阿里的 `usage.seconds`,Langfuse 不再只靠 `verbose_json` 的分段。
1. **不再一律发 `response_format=verbose_json`**。只有文档写明支持的模型(OpenAI `whisper-1`)返回分段;需要分段的自建行可在 `spec.compat` 里写 `{"response_format": "verbose_json"}`。
2. **上传前按厂商文档检查大小与格式**:OpenAI / 智谱 / OpenRouter 25 MB、Requesty 32 MB、SiliconFlow / MiniMax 50 MB;阿里云与小米按 base64 编码后的 `data:` URI 计 10 MB。智谱、小米只收 wav/mp3。
3. **回复里没有 `text` 字段即报错**;静音音频返回空字符串 `text`,照常处理。
4. **新增支持语音的厂商**:OpenAI 兼容形状(multipart 上传)的 openai、siliconflow、gpustack、generic、智谱(`glm-asr-2512`,单文件 ≤30 秒)、MiniMax(`asr-1.0`)、OpenRouter、Requesty、LiteLLM;经对话接口传音频的阿里云 `qwen3-asr-flash`、小米 `mimo-v2.5-asr`。阿里云的其他语音模型名会被拒绝并说明原因。
5. **知识库的「音频语言提示」会发给支持的厂商**(OpenAI / Requesty / OpenRouter / GPUStack / generic / MiniMax / 阿里云 / 小米);智谱、SiliconFlow、LiteLLM 不支持该参数,不发。填 `auto` 等同留空。
阿里只有 `qwen3-asr-flash` 能直接带音频调用;其余 ASR 模型名由一条兜底条目拒绝并说明原因。
查过但没有接的:火山豆包语音(独立域名与密钥,当前文档的请求体只收音频 URL)、千帆(`vop_asr` 挂在应用实例下要 `app_id`;短语音接口 ≤60 秒且只收 pcm/wav/amr/m4a)、七牛(只收音频 URL)、Novita(GLM-ASR 自有接口,≤30 秒)、腾讯云 ASR(与混元不是同一套鉴权)、NVIDIA 托管 Riva(gRPC)、Gemini(没有专用转写接口,只能让对话模型听音频)、Azure(见下)。阿里 Paraformer / Fun-ASR / `*-filetrans` 是异步任务,同样要公网 URL。
Azure OpenAI 仍不声明 ASR:音频转写只出现在 v1 **preview** 参考里(`/openai/v1/audio/transcriptions?api-version=preview`),v1 GA 参考没有;未填 `api_version` 的行会被钩子发到不带版本的 v1 路径,能否调通没有核实。
以下服务暂未接入语音转写:火山豆包语音、千帆、七牛、Novita、腾讯云 ASR、NVIDIA Riva、Gemini、Azure OpenAI(音频转写只在 v1 preview 接口中提供)。
### 模型调用链
@ -334,7 +545,7 @@ c, err = wrapChatLangfuse(c, err)
return wrapChatConcurrency(c, config.MaxConcurrency, err)
```
### 并发与限流(limiter)
### 并发与限流(limiter) {#并发与限流-limiter}
`internal/models/limiter` 提供**按模型 ID 的分布式后台并发闸门**,核心设计(`limiter.go` 包注释):共享的稀缺资源是模型厂商的请求预算,因此在模型客户端层(唯一能看到所有任务类型的位置)限流,而不是在 asynq 队列层。
@ -348,7 +559,4 @@ return wrapChatConcurrency(c, config.MaxConcurrency, err)
仓库根目录的 `rerank_server_demo.py` 是一个**自托管 Rerank 服务的最小参考实现**:FastAPI + HuggingFace `AutoModelForSequenceClassification`,暴露 `POST /rerank`,请求体 `{query, documents}`,返回 `{"results": [{index, document: {text}, score}]}`。
示例服务返回 `score` 字段,可用于验证客户端兼容性。`RankResult.UnmarshalJSON` 优先读取 `relevance_score`,缺失时读取 `score`;`DocumentInfo.UnmarshalJSON` 同时接受字符串和 `{text}` 对象。遵循此协议的私有重排服务可通过 `generic` provider 接入。
重构后的配置边界:每个模型仍单独保存 URL、API Key、额外参数和 `spec`,不新增连接实体,不修改模型 ID 或历史引用。部署覆盖每次从内置定义重新构建;通过 `runtime.Initialize` / `runtime.Reload` 校验后整体发布,失败保留旧版本。暂不监听文件变更,修改部署文件后仍需重启服务。
示例服务返回 `score` 字段,可用于验证客户端兼容性。`cohererank` 协议(`internal/models/api/cohererank`)优先读取 `relevance_score`,缺失时读取 `score`;`document` 同时接受字符串和 `{text}` 对象。遵循此协议的私有重排服务可通过 `generic` provider 接入。

View File

@ -34,9 +34,11 @@
初次使用可直接选择内置智能体。快速问答适用于文档查询;数据分析智能体面向 CSV 和 Excel;Wiki 智能体用于浏览和维护 Wiki 内容。
智能体配置的思考强度(`reasoning_effort`)是默认值,对话时可在输入框临时调整;智能推理回答生成期间还可以继续补充要求。见[会话与对话体验](18-chat-experience.md)。
## 设置资料和工具范围
智能体可以使用全部、指定或禁用的知识库及技能范围。对话中的提及用于选择本轮资料或提示优先技能,不能绕过已有授权。联网搜索同时受智能体配置和本轮请求开关约束。
智能体可以使用全部、指定或禁用的知识库及技能范围。对话中的提及用于选择本轮资料或提示优先技能,不能绕过已有授权;输入框的 @技能、@MCP 菜单只列出本轮实际运行的智能体可用的资源,使用共享智能体时列出来源空间的技能和该智能体显式选择的 MCP 服务。联网搜索同时受智能体配置和本轮请求开关约束。
通过组织共享智能体后,接收方在授权范围内使用来源空间的模型与资料。共享智能体为只读,接收方不能修改其配置。接收方使用时:
@ -55,7 +57,7 @@ MCP 服务需要 OAuth 授权时,可在当前对话中完成授权,成功后
## 使用技能、附件和记忆
绑定沙箱后,智能推理可读取附件、运行脚本并生成文件。可下载的产物应写入 `/workspace/output`,回答完成后可在会话中预览和下载。安装与变量配置见[技能目录与沙箱](22-skills-sandbox.md),附件操作见[会话与对话体验](18-chat-experience.md)。
绑定沙箱后,智能推理可读取附件、运行脚本并生成文件。可下载的产物应写入 `/workspace/output`,回答完成后可在会话中预览和下载。每轮回答结束后,系统为 `/workspace` 记录一个 git 检查点,分叉和回滚会话时据此恢复对应轮次的工作区;桌面版直接使用本机目录的会话不记录检查点,分叉和回滚只作用于对话。安装与变量配置见[技能目录与沙箱](22-skills-sandbox.md),附件操作见[会话与对话体验](18-chat-experience.md)。
长期记忆按空间和调用者隔离,智能体可单独关闭记忆读写;完整说明见[跨会话长期记忆](23-memory.md)。
@ -92,9 +94,9 @@ smart-reasoning 下还可选**类型预设**(`Config.AgentType`,定义在 `c
| 基础 | `agent_type` | smart-reasoning 下的预设类别,空/未知视为 custom |
| 基础 | `system_prompt` / `system_prompt_id` | 直接正文优先;自定义 Agent 的模板引用由 `ResolveCustomAgentPrompts` 在请求时解析 |
| 基础 | `context_template` / `context_template_id` | 普通模式下检索片段的拼装模板 |
| 模型 | `model_id`、`rerank_model_id`、`temperature`、`max_completion_tokens`、`thinking`、`citation_enabled` | temperature<0 → 0.7;max_completion_tokens=0 使用运行时默认:quick-answer 2048、smart-reasoning 4096、绑定沙箱的 smart-reasoning 24576;thinking 未设时固定为 false;citation 未设时视为 true |
| Agent | `max_iterations` | 默认 10(服务层上限 100) |
| Agent | `llm_call_timeout` | 单次 LLM 调用秒数,0 用全局默认(120s) |
| 模型 | `model_id`、`rerank_model_id`、`temperature`、`max_completion_tokens`、`thinking`、`reasoning_effort`、`citation_enabled` | temperature<0 → 0.7;max_completion_tokens=0 使用运行时默认:quick-answer 2048、smart-reasoning 4096、绑定沙箱的 smart-reasoning 24576;绑定沙箱时显式值低于 8192 按 8192 执行;`reasoning_effort` 取 `off`/`auto`/`minimal`/`low`/`medium`/`high`/`xhigh`/`max`,设置后优先于 `thinking`(`thinking: true` 等同 `auto`),模型不支持的档位在调用时自动就近调整;两者都未设时不开启思考;单次对话可用请求字段 `reasoning_effort` 临时覆盖;citation 未设时视为 true |
| Agent | `max_iterations` | 默认 10,负数表示不限轮数(服务层上限 100) |
| Agent | `llm_call_timeout` | 单次模型流式调用允许连续无输出的秒数,0 用默认 120s;总时长由模型传输层控制 |
| Agent | `allowed_tools` | 工具白名单;空回退 DefaultAllowedTools |
| MCP | `mcp_selection_mode`(all/selected/none)、`mcp_services`、`mcp_auth_wait_timeout` | OAuth 等待秒数 <=0 用 Gate 默认 |
| 技能 | `skills_selection_mode`(all/selected/none)、`selected_skills`、`sandbox_config_id` | 选择空间沙箱及其已安装技能,见[技能目录与沙箱](22-skills-sandbox.md) |
@ -103,7 +105,7 @@ smart-reasoning 下还可选**类型预设**(`Config.AgentType`,定义在 `c
| 多模态 | `image_upload_enabled`、`vlm_model_id`、`audio_upload_enabled`、`asr_model_id`、`image_storage_provider` | VLM 也用于 MCP 工具返回图片的描述 |
| 文件 | `supported_file_types`、`chat_parser_engine_rules`、`attachment_image_understanding`、`attachment_ocr_max_pages`、`attachment_parse_wait_timeout_sec` | 数据分析型 Agent 常限定 csv/xlsx |
| FAQ | `faq_priority_enabled`、`faq_direct_answer_threshold`、`faq_score_boost` | — |
| Web | `web_search_enabled`、`web_search_max_results`、`web_search_provider_id`、`web_fetch_enabled`、`web_fetch_top_n` | max_results 默认 5 |
| Web | `web_search_enabled`、`web_search_max_results`、`web_search_provider_id`、`web_fetch_enabled`、`web_fetch_top_n` | max_results 默认 5;`web_fetch_*` 只作用于 quick-answer 管道,智能推理由模型自行调用 `web_fetch` |
| 多轮 | `multi_turn_enabled`、`history_turns` | history_turns 默认 5,只约束普通模式(KnowledgeQA);smart-reasoning 强制 multi_turn,历史按上下文窗口加载,不读 history_turns |
| 检索 | `embedding_top_k`(10)、`keyword_threshold`(0.3)、`vector_threshold`(0.5)、`rerank_top_k`(5)、`rerank_threshold` | 括号内为默认值 |
| 高级 | `enable_query_expansion`、`enable_rewrite`、`rewrite_prompt_*`、`query_understand_model_id`、`fallback_strategy`(默认 model)、`fallback_response`、`fallback_prompt`、`intent_prompts`、`data_analysis_enabled` | 主要作用于 quick-answer 管道 |
@ -133,13 +135,14 @@ Handler 层(`internal/handler/custom_agent.go`)提供 `CreateAgent`、`GetAg
| `builtin-smart-reasoning` | 智能推理 | `smart-reasoning` / `rag-qa` | `max_iterations: 50`;工具:search_knowledge、read_document、list_documents、query_knowledge_graph;web 搜索开;多轮(历史按上下文窗口加载) |
| `builtin-data-analyst` | 数据分析师 | `smart-reasoning` / `data-analysis` | 模板 `data_analyst`;temperature 0.3;`max_iterations: 30`;工具仅 data_schema + data_analysis;限定 csv/xlsx;关闭 web 搜索;多轮(历史按上下文窗口加载) |
| `builtin-wiki-researcher` | 维基问答 | `smart-reasoning` / `wiki-qa` | 模板 `wiki_researcher`;`max_iterations: 30`;工具:wiki_search、wiki_read_page、read_document、wiki_flag_issue(只读 + 报障);关闭 web 搜索 |
| `builtin-wiki-fixer` | 维基修订 | `smart-reasoning` / `custom` | 模板 `wiki_fixer`;`retain_retrieval_history: true`(修订需要跨轮记住页面内容);工具含全部 wiki 写操作(wiki_write_page、wiki_replace_text、wiki_rename_page、wiki_delete_page、wiki_read_issue、wiki_update_issue 等 9 个);`kb_selection_mode: selected` |
| `builtin-wiki-fixer` | 维基修订 | `smart-reasoning` / `custom` | 模板 `wiki_fixer`;`retain_retrieval_history: true`(修订需要跨轮记住页面内容);工具共 9 个:wiki_search、wiki_read_page、read_document、wiki_write_page、wiki_replace_text、wiki_rename_page、wiki_delete_page、wiki_read_issue、wiki_update_issue(不含 wiki_flag_issue);`kb_selection_mode: selected` |
| `builtin-skill-installer` | 技能安装器 | `smart-reasoning` / `custom` | 模板 `skill_installer`;temperature 0.2;`max_completion_tokens: 24576`;`max_iterations: 30`;工具:shell_exec、write_skill_file、edit_skill_file;`kb_selection_mode: none`;由沙箱配置的技能上传流程调用 |
补充两点(来自 `internal/types/custom_agent.go`):
补充说明(来自 `internal/types/custom_agent.go`):
- `builtin-wiki-fixer` 不显示在用户可见的 Agent 列表(`builtinAgentIDsOrdered` 排除了它)——它是 Wiki 编辑器程序化调用的内部 Agent,但仍可经 `GetAgentByID` 使用;
- `builtin-wiki-fixer` 与 `builtin-skill-installer` 不显示在用户可见的 Agent 列表(`builtinAgentIDsOrdered` 排除了它们)——前者由 Wiki 编辑器、后者由技能上传流程程序化调用,但仍可经 `GetAgentByID` 使用;
- `builtinAgentIDsOrdered` 中还保留了 `builtin-deep-researcher`、`builtin-knowledge-graph-expert`、`builtin-document-assistant` 等 ID 常量位次,但当前 YAML 未定义这些条目,注册表以 YAML 为准;
- `builtin_agents.yaml` 里每个条目都带 `reflection_enabled`(数据分析师为 `true`,其余 `false`),但**后端目前不消费这个字段**——`internal/` 下既没有对应的结构体字段也没有引用,只有 YAML 与前端类型定义里存在。也就是说它当前不影响 Agent 的实际行为,看到它为 `true` 不要以为多了一轮反思。
- `builtin_agents.yaml` 里除快速问答外的条目都带 `reflection_enabled`(数据分析师为 `true`,其余 `false`),但**后端目前不消费这个字段**——`internal/` 下既没有对应的结构体字段也没有引用,只有 YAML 与前端类型定义里存在。也就是说它当前不影响 Agent 的实际行为,看到它为 `true` 不要以为多了一轮反思。
顺带一提,`internal/agent/prompts_wiki.go` 中的 `WikiSummaryPrompt`、`WikiKnowledgeExtractPrompt`、`WikiTaxonomyPlanPrompt` 等常量属于 **Wiki ingest 管道**(文档入库时 LLM 生成 wiki 页面/目录规划)使用的提示词,与 wiki 类 Agent 的运行时工具互补:前者生产 Wiki 内容,后者消费与维护。
@ -151,25 +154,27 @@ Handler 层(`internal/handler/custom_agent.go`)提供 `CreateAgent`、`GetAg
两组配置各自独立开关,`mode` 决定问题从哪来:
| mode | 来源 |
| --- | --- |
| `curated` | 只用人工写死的 `items` |
| `knowledge` | 从知识库内容里取 |
| `generated` | 让模型生成 |
| `hybrid`(默认) | 上述几种混合 |
| mode | 来源 | 适用 |
| --- | --- | --- |
| `curated` | 只用人工填写的 `items` | 开场问题 |
| `knowledge` | 从知识库内容里取 | 开场问题、追问 |
| `generated` | 让模型根据对话生成 | 追问 |
| `hybrid`(默认) | 上述来源混合 | 开场问题、追问 |
| 配置 | 默认 | 说明 |
| --- | --- | --- |
| `starters.enabled` / `mode` / `items` / `count` | — / `hybrid` / 空 / 6 | 开场问题 |
| `follow_ups.enabled` / `mode` / `count` | — / `hybrid` / 3 | 追问建议 |
| `starters.enabled` / `mode` / `items` / `count` | 开 / `hybrid` / 空 / 6 | 开场问题;`count` 取 1–8 |
| `follow_ups.enabled` / `mode` / `count` | 关 / `hybrid` / 3 | 追问建议;`count` 取 1–5 |
| `follow_ups.model_id` | 空(用会话模型) | 生成追问用的模型,可指定小模型省成本 |
| `follow_ups.categories` | 空 | 限定问题类型:`clarify`(澄清)/ `deepen`(深入)/ `action`(行动) |
| `follow_ups.max_context_turns` | 2 | 生成时回看几轮对话 |
| `follow_ups.additional_instruction` | 空 | 追加到生成提示词的业务约束 |
| `follow_ups.suppress_on_fallback` | — | 回答走了兜底策略时不出建议 |
| `follow_ups.suppress_when_answer_asks_question` | — | 回答本身在反问用户时不出建议(避免两个问题打架) |
| `follow_ups.knowledge_fallback` | — | 生成失败时回退到知识库来源 |
| `follow_ups.allow_regenerate` | — | 是否允许用户手动换一批 |
| `follow_ups.categories` | 三类全选 | 限定问题类型:`clarify`(澄清)/ `deepen`(深入)/ `action`(行动) |
| `follow_ups.max_context_turns` | 2 | 生成时回看几轮对话,取 1–5 |
| `follow_ups.additional_instruction` | 空 | 追加到生成提示词的业务约束,最多 2000 字符 |
| `follow_ups.suppress_on_fallback` | 开 | 回答走了兜底策略时不出建议 |
| `follow_ups.suppress_when_answer_asks_question` | 开 | 回答本身在反问用户时不出建议(避免两个问题打架) |
| `follow_ups.knowledge_fallback` | 开 | 生成失败时回退到知识库来源 |
| `follow_ups.allow_regenerate` | 关 | 是否允许用户手动换一批 |
与用户刚问的问题相同的追问(忽略大小写、空白和常见标点)会被剔除,知识库来源的候选会补足数量。用户点选来自知识库的建议问题后,智能推理模式会先检索该问题的来源知识库或文档再回答。
#### 生成、缓存与埋点
@ -198,7 +203,7 @@ Handler 层(`internal/handler/custom_agent.go`)提供 `CreateAgent`、`GetAg
| 会话问答入口 | `internal/application/service/session_agent_qa.go` | 从 `CustomAgent` 构建运行时 `AgentConfig` 并执行 |
| 历史重建 | `internal/application/service/agent_history.go` | 从 DB 重建多轮 LLM 上下文(`LoadAgentHistory`) |
`AgentEngine` 的结构体定义(`internal/agent/engine.go`):
`AgentEngine` 的结构体定义(`internal/agent/engine.go`,节选):
```go
type AgentEngine struct {
@ -206,20 +211,19 @@ type AgentEngine struct {
toolRegistry *agenttools.ToolRegistry
chatModel chat.Chat
eventBus *event.EventBus
knowledgeBasesInfo []*KnowledgeBaseInfo // Detailed knowledge base information for prompt
selectedDocs []*SelectedDocumentInfo // User-selected documents (via @ mention)
pinnedMCPServices []*PinnedMCPServiceInfo // User @mentioned MCP services for this turn
pinnedSkills []*PinnedSkillInfo // User @mentioned skills for this turn
sessionID string
systemPromptTemplate string
skillsManager *skills.Manager // Skills manager for Progressive Disclosure (optional)
appConfig *appconfig.Config
imageDescriber ImageDescriberFunc // VLM function for describing images in tool results
tokenEstimator *agenttoken.Estimator // Token estimator for context window management
compactor *compaction.Compactor // Structured conversation compaction
lastUsage types.TokenUsage // Token usage from the most recent LLM call
lastSentMsgCount int
modelContext *modelcontext.Registry // single request-local boundary for every model handle
knowledgeBasesInfo []*KnowledgeBaseInfo // Detailed knowledge base information for prompt
selectedDocs []*SelectedDocumentInfo // User-selected documents (via @ mention)
pinnedMCPServices []*PinnedMCPServiceInfo // User @mentioned MCP services for this turn
pinnedSkills []*PinnedSkillInfo // User @mentioned skills for this turn
questionOrigin *QuestionOriginInfo // Source of a picked suggested question, if any
memoryPrompt string // Long-term memory envelope appended to the system prompt
skillsManager *skills.Manager // Skills manager for Progressive Disclosure (optional)
tokenEstimator *agenttoken.Estimator // Token estimator for context window management, calibrated
compactor *compaction.Compactor // Summarizes older history to fit the context window (nil = disabled)
checkpointSink types.ContextCheckpointSink // persists compactions that end on a stored turn
modelContext *modelcontext.Registry // single request-local boundary for every model handle
steerSink types.SteerSink // lets users append messages into the running turn
// ... 其余为估算校准、溢出恢复等运行期状态
}
```
@ -250,10 +254,10 @@ flowchart TB
end
subgraph Tools["工具集"]
KB["KB 检索工具<br/>search_knowledge / read_document / list_documents"]
WIKI["Wiki 工具 x10"]
WIKI["Wiki 工具 x9"]
WEB["web_search / web_fetch"]
DATA["data_schema / data_analysis(DuckDB)"]
SKILL["read_file / shell_exec"]
SKILL["read_file / shell_exec / 沙箱文件工具"]
MCP["MCP 目录与按需加载工具"]
end
GATE["approval.Gate<br/>(HITL 审批 / OAuth)"]
@ -317,10 +321,10 @@ if !state.IsComplete && ctx.Err() == nil {
一次迭代 `runReActIteration` 内部依次是四个阶段:
**① Think(思考)**:先做上下文窗口管理(见[记忆与上下文压缩](#_4-记忆与上下文压缩)),然后 `callLLMWithRetry`(`internal/agent/think.go`):
**① Think(思考)**:先做上下文窗口管理(见[记忆与上下文压缩](#_4-记忆与上下文压缩)),再把用户在运行中追加的 `inject` 消息写入历史并接到消息列表末尾(见[向运行中的回答追加消息](../04-api/02-api-chat.md#steer)),然后 `callLLMWithRetry`(`internal/agent/think.go`):
- `agenttools.SanitizeMessages` 修复连续同角色、孤儿 tool result 等问题;
- 流式调用 LLM(`streamThinkingToEventBus`),单次调用超时 `defaultLLMCallTimeout = 120s`(可用 `AgentConfig.LLMCallTimeout` 覆盖);
- 流式调用 LLM(`streamThinkingToEventBus`),连续 `defaultLLMStallTimeout = 120s` 没有任何输出才取消(可用 `AgentConfig.LLMCallTimeout` 覆盖),持续输出的长轮次不受总时长限制,总时长由模型传输层兜底;
- 瞬时错误(429/5xx/timeout/overloaded 等,见 `transientErrorMarkers`)最多重试 `maxLLMRetries = 2` 次,退避 1s、2s;
- 若重试仍失败但此前已有工具结果,走**优雅降级**:`streamFinalAnswerToEventBus` 基于既有工具结果合成最终答案,`state.IsComplete = true`。
@ -330,16 +334,18 @@ if !state.IsComplete && ctx.Err() == nil {
- `finish_reason == "content_filter"` 且无工具调用 → 终止,答案为被过滤的内容或固定的道歉话术;
- 自然停止(`isNaturalStopFinishReason`:`stop` / `end_turn` / `stop_sequence`)且无工具调用 → **Agent 结束**,纯文本回复即最终答案(**没有专门的 final_answer 工具**;历史数据中遗留的 `final_answer` 工具调用会在重放时被 `filterNonTerminalToolCalls` 过滤掉);
- 自然停止但内容为空 → 追加一条 nudge 用户消息 `"Please provide your complete answer now as plain text."` 重试,最多 `maxEmptyResponseRetries = 2` 次(返回 `iterOutcomeContinue`,不消耗轮次);重试耗尽用固定 fallback 文案终止。
- 自然停止但内容为空 → 追加一条 nudge 用户消息 `"Please provide your complete answer now as plain text."` 重试,最多 `maxEmptyResponseRetries = 2` 次(返回 `iterOutcomeContinue`,不消耗轮次);重试期间不发出终态答案事件,重试耗尽才以固定 fallback 文案作为唯一的最终答案;
- 因输出上限截断(`finish_reason` 为 `length` / `max_tokens` / `max_output_tokens`)且有正文、无工具调用 → 交付截断前的正文并结束本轮,答案事件与 `AgentStep` 带 `truncated` 标记;截断时没有正文(只有思考内容)则按空回复重试;连续 `maxConsecutiveLengthRounds = 3` 轮截断(通常截在工具调用参数里)时停止,没有正文则返回固定提示,建议缩小问题或调大 `max_completion_tokens`;
- 即将自然停止时若有用户追加的 `inject` 消息,本轮回复作为中间回答保留,智能体读取追加内容后继续;此时已到迭代上限也允许多跑一轮(`maxSteerOverruns = 1`)。
另有一个**卡死检测**在 Analyze 之前:若连续 `maxRepeatedResponseRounds = 2` 轮返回完全相同内容且无工具调用(通常是未处理的 finish reason 导致),强制终止并把该内容作为最终答案。
另有一个**卡死检测**在 Analyze 之前:若连续 `maxRepeatedResponseRounds = 2` 轮返回完全相同内容(包括连续为空)且无工具调用(通常是未处理的 finish reason 导致),强制终止并把该内容作为最终答案,内容为空时使用固定 fallback 文案。
**③ Act(行动)**:`executeToolCalls`(`internal/agent/act.go`)执行本轮所有工具调用:
- `AgentConfig.ParallelToolCalls == true` 且调用数 ≥ 2 时用 `errgroup` **并行执行**(best-effort,单个失败不取消兄弟任务),结果按原顺序回填;
- 每个调用先 `NormalizeToolCallID`,然后解析 JSON 参数——解析失败会先经 `RepairJSON` 修复再试;仍失败则返回带提示的错误结果(`"[Analyze the error above and try a different approach.]"`),让模型换路子而不是让整轮失败;
- 单个工具执行超时 `defaultToolExecTimeout = 60s`;`ToolExecContext` 中额外携带不带该超时的 `ApprovalCtx`,供 MCP 人工审批/OAuth 等合法长等待使用;
- 发射 `EventAgentToolCall`(含中文 display name 的 hint,如 `搜索网页("...")`)、`EventAgentToolResult`、`EventAgentTool` 事件。
- 单个工具执行超时 `defaultToolExecTimeout = 60s`;`shell_exec` 为 `shellExecToolTimeout = 10m5s`(略长于命令自身 600s 上限,以便返回结构化超时结果),`local_browser` 的人工接管步骤使用单独的等待时长;`ToolExecContext` 中额外携带不带该超时的 `ApprovalCtx`,供 MCP 人工审批/OAuth 等合法长等待使用;
- 发射 `EventAgentToolCall`(含中文 display name 的 hint,如 `搜索网页("...")`)、`EventAgentToolResult`、`EventAgentTool` 事件。工具执行失败同样以 `tool_result` 发给客户端(`success: false` 与 `error`),不再作为 `error` 事件,智能体会根据错误继续处理。
**④ Observe(观察)**:`appendToolResults`(`internal/agent/observe.go`)按 OpenAI 协议把本轮追加进消息数组:一条带 `tool_calls` 的 assistant 消息 + 每个结果一条 `role:"tool"` 消息(内容经 `modelContext.ModelToolResultForTool` 别名化)。若本轮任一成功的工具结果里含 Markdown 图片,还会向 system 消息追加一次 `## Retrieved Image Output Requirement` 要求(`internal/agent/image_requirement.go`),强制最终答案原样携带相关图片。随后 `state.CurrentRound++` 进入下一轮。
@ -349,16 +355,17 @@ if !state.IsComplete && ctx.Err() == nil {
| --- | --- | --- |
| 自然停止 | finish_reason ∈ {stop, end_turn, stop_sequence} 且无工具调用、内容非空 | 该轮纯文本回复 |
| 空回复耗尽 | 自然停止但内容为空,nudge 重试 2 次仍空 | 固定 fallback 文案 |
| 输出截断 | 因输出上限截断且有正文、无工具调用 | 截断前的正文(带 `truncated` 标记) |
| 连续截断 | 连续 3 轮在输出上限处截断 | 最后一段正文或固定提示 |
| 内容过滤 | finish_reason == content_filter 且无工具调用 | 被过滤内容或安全提示 |
| 卡死检测 | 连续 2 轮相同内容且无工具调用 | 重复的内容本身 |
| 用户取消 / 超时 | ctx.Done();若已有工具结果则抢救合成 | 合成答案或保留部分步骤 |
| LLM 不可恢复失败 | 重试耗尽;有工具结果 → 降级合成,否则报错 | 合成答案 / 错误事件 |
| 达到最大迭代 | `CurrentRound == MaxIterations` | `handleMaxIterations` → `streamFinalAnswerToEventBus` 合成 |
| 达到最大迭代 | `CurrentRound == MaxIterations`(`max_iterations` 为负数时不限轮数) | `handleMaxIterations` → `streamFinalAnswerToEventBus` 合成 |
最大迭代次数的多层默认值:
- 引擎级默认 `DefaultAgentMaxIterations = 20`(`internal/agent/const.go`);
- 服务层 `ValidateConfig`:`<= 0` 时兜底为 5,硬上限 `MAX_ITERATIONS = 100`(`internal/application/service/agent_service.go`);
- 服务层 `ValidateConfig`:`0` 时兜底为 5,负数表示不限轮数,硬上限 `MAX_ITERATIONS = 100`(`internal/application/service/agent_service.go`);
- `CustomAgent.EnsureDefaults`:未配置时为 10(`internal/types/custom_agent.go`);
- 内置 Agent:智能推理 50、数据分析师 30、Wiki 问答/修订 30(`config/builtin_agents.yaml`)。
@ -375,13 +382,14 @@ flowchart TD
CHECK -- "是" --> CANCEL{"ctx 已取消?"}
CANCEL -- "是,且已有工具结果" --> SALVAGE["抢救合成最终答案"] --> DONE
CANCEL -- "否" --> CTXMGMT["上下文窗口管理:<br/>按窗口保留预算压缩,必要时裁短工具结果"]
CTXMGMT --> THINK["Think:流式调用 LLM<br/>(120s 超时,瞬时错误重试 2 次)"]
CTXMGMT --> THINK["Think:注入追加消息后流式调用 LLM<br/>(120s 无输出超时,瞬时错误重试 2 次)"]
THINK -- "失败且有工具结果" --> SALVAGE
THINK --> STUCK{"连续 2 轮相同内容<br/>且无工具调用?"}
STUCK -- "是" --> DONE
STUCK -- "否" --> ANALYZE{"analyzeResponse 判定"}
ANALYZE -- "content_filter" --> DONE
ANALYZE -- "自然停止且内容非空" --> FINAL["纯文本回复 = 最终答案"] --> DONE
ANALYZE -- "输出上限截断且有正文" --> FINAL
ANALYZE -- "自然停止但内容为空" --> EMPTY{"空回复重试 <= 2?"}
EMPTY -- "是" --> NUDGE["追加 nudge 用户消息<br/>(iterOutcomeContinue,不消耗轮次)"] --> THINK
EMPTY -- "否" --> FALLBACK["固定 fallback 文案"] --> DONE
@ -400,24 +408,24 @@ flowchart TD
| --- | --- | --- |
| `thinking` | `thought`\*、`next_thought_needed`\*、`thought_number`\*、`total_thoughts`\*、`is_revision`、`revises_thought`、`branch_from_thought`、`branch_id`、`needs_more_thoughts` | Sequential Thinking:记录/修订/分支思考步骤;返回思考进度(含 `incomplete_steps`),提示禁止在思考里出现工具名和最终答案 |
| `todo_write` | `task`、`steps[]`\*(`id`/`description`/`status`:pending/in_progress/completed) | 创建/更新检索类任务计划,仅限检索任务(总结交给 thinking);返回格式化计划,`display_type: "plan"` |
| `search_knowledge` | `query`\*(一条自然语言问题或短语;keyword 模式下写精确词)、`mode`(`hybrid` 默认 / `semantic` / `keyword`)、`knowledge_base_ids[]`(`bN`)、`limit`(默认 10,上限 30) | 唯一的知识库检索入口:`hybrid` 走向量 + 关键词的 RRF 融合,`semantic` 只走向量,`keyword` 由关键词索引(BM25 / 引擎关键词检索)提供,不再对 chunks 表做无索引的正则扫描;默认 vector 阈值 0.6、keyword 阈值 0.5,阈值过滤在 RRF 之前由各引擎完成;有 rerank 模型时重排(`rerankThreshold()` 优先取全局配置),候选超过 `limit` 时做 MMR(λ=0.7)去冗;结果带 `cN`/`dN` 短 ID,会话内已见 chunk 去重压缩;所选 KB 没有对应索引时按库降级而不是报错:`keyword` 遇到 FAQ 库或纯向量库改走语义检索,`semantic` 遇到纯关键词库改走关键词检索,结果里以 `requested_mode` 和 `mode_fallbacks` 标明哪些库降级及原因;只有作用域内没有任何分块索引(如全是仅 Wiki 的库)时才报错 |
| `read_document` | `id`\*(`dN` 文档句柄或 `cN` 分块句柄)、`offset`(阅读顺序中的位置,从 0 开始,不是 chunk 下标;翻页用返回的 `next_offset`)、`limit`(默认 20,上限 100)、`query`(文档内查找,默认字面量、大小写不敏感)、`regex`(把 `query` 当 POSIX 正则)、`context`(`cN` 前后各带几个相邻分块,上限 5) | 始终先返回文档元数据头(标题、类型、parse_status、分块数、metadata),再按需返回分块:`dN` 从 `offset` 起分页遍历;`cN` 读取该分块并可带前后 `context`(邻居按 chunk_index 顺序取,不受父分块、摘要、图片分块占用的下标影响);带 `query` 时即使 `id` 是 `cN` 也在其所属文档内查找;`query` 返回命中分块及前后各一块上下文(最多 20 处命中);FAQ 条目按同样方式读取;校验 KB 在 searchTargets 内及 @mention 范围 |
| `list_documents` | `knowledge_base_id`\*(`bN`)、`keyword`(标题子串过滤)、`page`(默认 1)、`page_size`(默认 20,上限 100) | 分页列出单个知识库的文档,返回可直接交给 `read_document` 的 `dN` 句柄 |
| `search_knowledge` | `query`\*(一条自然语言问题或短语;keyword 模式下写精确词)、`mode`(`hybrid` 默认 / `semantic` / `keyword`)、`knowledge_base_ids[]`(`bN`,最多 10 个)、`limit`(默认 10,上限 30) | 唯一的知识库检索入口:`hybrid` 走向量 + 关键词的 RRF 融合,`semantic` 只走向量,`keyword` 由关键词索引(BM25 / 引擎关键词检索)提供,不再对 chunks 表做无索引的正则扫描;召回阈值与候选池取全局 `conversation.vector_threshold` / `keyword_threshold` / `embedding_top_k`(随附 `config.yaml` 为 0.2 / 0.3 / 30,未配置时回退 0.6 / 0.5 / 30),不读智能体自身的阈值;有 rerank 模型时重排(打分文本为「文档标题 + 分块正文」,FAQ 除外;阈值默认 0.3,全部未过阈值时保留得分 ≥ 0.15 的最佳候选),结果再做 MMR(λ=0.7)去冗;重排全部拒绝时结果带 `rerank_rejected` 并提示换 `keyword` 查标识符类词;结果带 `cN`/`dN` 短 ID,同一次调用内去重,同一文档的元数据头只输出一次;所选 KB 没有对应索引时按库降级而不是报错:`keyword` 遇到 FAQ 库或纯向量库改走语义检索,`semantic` 遇到纯关键词库改走关键词检索,结果里以 `requested_mode` 和 `mode_fallbacks` 标明哪些库降级及原因;只有作用域内没有任何分块索引(如全是仅 Wiki 的库)时才报错 |
| `read_document` | `id`\*(`dN` 文档句柄或 `cN` 分块句柄)、`offset`(阅读顺序中的位置,从 0 开始,不是 chunk 下标;翻页用返回的 `next_offset`)、`limit`(默认 20,上限 100)、`query`(文档内查找:按空白拆成多个词,分块须包含全部词,顺序不限、大小写不敏感)、`regex`(把整个 `query` 当一条正则,大小写不敏感)、`context`(`cN` 前后各带几个相邻分块,上限 5) | 始终先返回文档元数据头(标题、类型、parse_status、分块数、metadata),再按需返回分块:`dN` 从 `offset` 起分页遍历;`cN` 读取该分块并可带前后 `context`(邻居按 chunk_index 顺序取,不受父分块、摘要、图片分块占用的下标影响);带 `query` 时即使 `id` 是 `cN` 也在其所属文档内查找,返回命中分块及前后各一块上下文(最多 20 处命中),无命中时附提示;单页或单次查找结果不超过工具输出预算的 80%,超出部分用 `next_offset` 续读;FAQ 条目按同样方式读取;校验 KB 在 searchTargets 内及 @mention 范围 |
| `list_documents` | `knowledge_base_id`\*(`bN`)、`keyword`(按标题或文件名子串过滤)、`page`(默认 1)、`page_size`(默认 20,上限 100) | 分页列出单个知识库的文档,返回可直接交给 `read_document` 的 `dN` 句柄 |
| `query_knowledge_graph` | `knowledge_base_ids[]`\*(1–10 个 `bN`)、`query`\* | 并发查询各 KB 知识图谱的实体与关系;只有当作用域内存在启用图谱的 KB 时才会提供给模型(`agent_service.go` 装配白名单时移除),能力要求 `all_of: [graph]` |
| `database_query` | SQL(SELECT-only) | 只读查询白名单表(`knowledge_bases`/`knowledges`/`chunks`),自动注入 tenant_id 过滤与 `deleted_at IS NULL`;SQL 参数在 UI/Langfuse 中脱敏 |
| `database_query` | `sql`\*(仅 SELECT) | 只读查询白名单表(`knowledge_bases`/`knowledges`/`chunks`),自动注入 tenant_id 过滤与 `deleted_at IS NULL`;SQL 参数在 UI/Langfuse 中脱敏 |
| `data_schema` | `knowledge_id`\*(`dN`) | 读取 CSV/Excel 文件的 `table_summary` + `table_column` 类型分块,返回列信息与行数;并告知模型该文档在 `data_analysis` 中固定以表名 `dataset` 访问 |
| `data_analysis` | `knowledge_id`\*、`sql`\* | 把 CSV/Excel 载入 DuckDB 后执行 SQL。文档由 `knowledge_id` 选定,SQL 中固定以表名 `dataset` 引用它(每次查询在独立连接上建临时视图映射到物理表,模型永远不需要在 SQL 里写文档 ID);多 Sheet Excel 合并为一张表并暴露 `__sheet_name` 列;自动纠正列名大小写/空格差异;会话结束 Cleanup 时 DROP 所建表 |
| `web_search` | `query`\*,可选 `count`、`country`、`freshness`、`content` | 联网搜索,直接返回提供商的标题、摘要和 `wN` 页面短 ID;按任务需要选择知识库或联网检索,Agent 搜索不再自动进行 RAG 压缩;Brave 支持地区/时效过滤,`content=true` 并行抓取前 3 条正文并返回完整正文地址 |
| `web_fetch` | `items[]`\*(每项 `url`\*=`wN` 或 HTTP(S) URL,可选 `offset`、`limit`) | 并发抓取最多 8 个网页(SSRF 安全客户端 + DNS pinning,必要时 chromedp 渲染),直接返回 Markdown 或支持的文本正文;60s 超时。按字符分页,使用 `next_offset` 续读;完整正文保存在 `full_output_path`,可用 `read_file` 跨轮按行读取;逐 URL 返回 `success`/`failed`/`skipped` 状态与可重试错误码,部分失败不影响其它页面 |
| `read_file` | `path`、offset、limit、max_bytes;网页可带 line_offset | 读取工作区文本、skill:// 资源和 web:// 网页快照,按结果续读 |
| `shell_exec` | `command`;skill_name、work_dir、timeout_sec、max_output_bytes、max_stderr_bytes、env | 在当前会话沙箱运行命令,指定技能时解析技能目录和变量 |
| `list_sandbox_files` | 路径等 | 浏览沙箱文件和可用产物 |
| `write_sandbox_file` | path、content、mode | 写入或追加工作区文件 |
| `edit_sandbox_file` | path、edits | 基于原版本批量精确替换 |
| `search_memory` | query、limit | 按当前调用者作用域查长期记忆 |
| `search_conversations` | 查询与范围 | 检索当前调用者可用的历史对话 |
| `wiki_search` | `query`\*(大小写不敏感的 POSIX 正则,如 `stardust\|skyvault`;不是合法正则的文本如 `C++` 按字面匹配)、`regex`(`false` 强制字面匹配,`true` 要求合法正则)、`knowledge_base_ids[]`(`bN`)、`limit`(每个 KB 默认 10,上限 50);旧参数 `queries[]`、`knowledge_base_id` 仍接受 | 在 Wiki 页面(标题/slug/别名/摘要/内容)上搜索,返回带 `bN` 标记的页面 slug 与摘要;已见 slug 去重 |
| `wiki_read_page` | `slugs[]`\*、`knowledge_base_id` | 按 slug 读取 Wiki 页面全文、元数据、出入链(链接附摘要,已见的省略);`index` slug 返回按类型分组的目录概览(每类 top 20) |
| `web_search` | `query`\*,可选 `count`(不超过配置上限,最多 20)、`country`(两位国家码或 `ALL`)、`freshness`(`pd`/`pw`/`pm`/`py`,Brave 另支持日期区间)、`content` | 联网搜索,直接返回提供商的标题、摘要和 `wN` 页面短 ID;按任务需要选择知识库或联网检索,Agent 搜索不再自动进行 RAG 压缩;`country`/`freshness` 仅 Brave 与 Serply 支持,其他提供商传入时报错;`content=true` 在 15 秒内并行抓取前 3 条结果、各取 5000 字符正文摘录 |
| `web_fetch` | `items[]`\*(每项 `url`\*=`wN` 或 HTTP(S) URL,可选 `offset`、`limit`;`limit` 按字符计,默认且最多 8000,多项共享输出预算) | 并发抓取最多 8 个网页(SSRF 安全客户端 + DNS pinning,必要时 chromedp 渲染),直接返回 Markdown 或支持的文本正文;60s 超时。按字符分页,使用 `next_offset` 续读;完整正文保存在 `full_output_path`(`web://` 地址,仅同一会话可读),可用 `read_file` 跨轮按行读取;逐 URL 返回 `success`/`failed`/`skipped` 状态与可重试错误码(如快照已过期的 `snapshot_expired`),部分失败不影响其它页面 |
| `read_file` | `path`\*、`offset`(从 1 开始的行号)、`limit`(默认 2000 行)、`max_bytes`(上限 64 KiB,网页快照 50 KiB);网页可带 `line_offset` | 读取工作区文本、skill:// 资源和 web:// 网页快照,按结果续读 |
| `shell_exec` | `command`\*;可选 `skill_name`、`work_dir`、`timeout_sec`、`stdin`(≤ 64 KiB)、`max_output_bytes`(默认 16 KiB,上限 64 KiB)、`max_stderr_bytes`(默认 8 KiB,上限 16 KiB)、`env` | 在当前会话沙箱运行命令,默认工作目录 `/workspace`;指定技能时解析技能目录和变量 |
| `list_sandbox_files` | `path`、`max_entries`(默认 200,上限 500) | 浏览沙箱文件和可用产物;仅在未注册 `shell_exec` 时提供 |
| `write_sandbox_file` | `path`\*、`content`\*、`mode`(`overwrite` 默认 / `append`) | 写入或追加工作区文件,不能写 `/workspace/input` |
| `edit_sandbox_file` | `path`\*、`edits`\*(每项 `old_string`\*、`new_string`\*、`replace_all`) | 基于原版本批量精确替换 |
| `search_memory` | `query`\*、`limit`(默认 10,上限 20) | 按当前调用者作用域查长期记忆 |
| `search_conversations` | `query`\*、`limit`(默认 5,上限 8) | 检索当前调用者的历史对话;范围由调用者身份决定,不接受范围参数 |
| `wiki_search` | `query`\*(大小写不敏感的 POSIX 正则,如 `stardust\|skyvault`;不是合法正则的文本如 `C++` 按字面匹配)、`regex`(`false` 强制字面匹配,`true` 要求合法正则)、`knowledge_base_ids[]`(`bN`)、`limit`(每个 KB 默认 10,上限 50);旧参数 `queries[]`、`knowledge_base_id` 仍接受 | 在 Wiki 页面(标题/slug/别名/摘要/内容)上搜索,返回带 `bN` 标记的页面 slug 与摘要;之前已返回过的页面仍列出,但省略摘要 |
| `wiki_read_page` | `slugs[]`\* | 按 slug 读取 Wiki 页面全文、元数据、出入链(链接附摘要,已见的省略);知识库按 slug 自动路由;`index` slug 返回按类型分组的目录概览(每类 top 20) |
| `wiki_write_page` | `slug`\*、`title`\*、`summary`\*、`content`\*、`page_type`\*、`aliases[]`、`source_refs[]` | 新建或整页覆盖 Wiki 页面;写入前规范化并校验 slug;自动处理出链 |
| `wiki_replace_text` | `slug`\*、`old_text`\*、`new_text`\*、`source_refs[]` | 精确文本替换,适合小修订 |
| `wiki_rename_page` | `slug`\*、`new_slug`\* | 重命名 slug 并级联更新所有引用它的页面链接 |
@ -425,14 +433,16 @@ flowchart TD
| `wiki_flag_issue` | `slug`\*、`issue_type`\*(mixed_entities/contradictory_facts/out_of_date/other)、`description`\*、`suspected_knowledge_ids[]` | 标记页面事实错误/实体混淆等问题,记录 issue 供人工或自动维护 |
| `wiki_read_issue` | `issue_id` / `slug` | 查看某条 issue 详情或列出某页面的 pending issue |
| `wiki_update_issue` | `issue_id`\*、`status`\*(resolved/ignored/pending) | 更新 issue 状态 |
| `discover_mcp_tools` / `call_mcp_tool` | 发现模式、服务 ID / 工具引用与参数 | 查询目录、读取完整定义并按需调用,见 [MCP 工具目录](08-mcp.md#mcp-tool-directory) |
| `discover_mcp_tools` / `call_mcp_tool` | 发现:`mode`\*(`list_servers`/`list_tools`/`describe`/`search`)、`server_id`、`tool_name`、`query`、`cursor`、`limit`(1–50)、`refresh`;调用:`tool_ref`\*、`arguments`\* | 查询目录、读取完整定义并按需调用,见 [MCP 工具目录](08-mcp.md#mcp-tool-directory) |
| `mcp_...`(动态,含稳定哈希后缀) | 由 MCP 服务的 InputSchema 决定 | 读取定义后发布的外部函数;描述标明服务和原始工具名,执行时重新校验权限,可挂人工审批与会话内 OAuth |
| `local_browser` | `method`\*(`observe`、`snapshot`、`navigate`、`click`、`fill`、`tab_*`、`evaluate`、`request_help` 等),其余字段随 method 而定 | 操作用户已连接的本机浏览器;仅在请求开启 `local_browser_enabled` 且部署启用浏览器接入时注册,见[本机浏览器](../05-clients/09-local-browser.md) |
| `write_skill_file` / `edit_skill_file` | 写:`path`\*、`content`\*(≤ 256 KiB);改:`path`\*、`old_string`\*、`new_string`\*、`replace_all` | 仅内置技能安装器在安装模式下使用,只能改动正在安装的技能目录 |
默认工具白名单 `DefaultAllowedTools()`(新建 Agent 的默认值,也是旧 Agent 未配置 `allowed_tools` 时的回退):`search_knowledge`、`read_document`、`list_documents`、`search_conversations`(`search_memory` 与 `web_search` 一样不在此列表里,由记忆 / 联网开关在注册工具时注入或剔除)。
默认工具白名单 `DefaultAllowedTools()`(Agent 未配置 `allowed_tools` 时的回退):`search_knowledge`、`read_document`、`list_documents`、`search_conversations`。`web_search` / `web_fetch` 与 `search_memory` 不由白名单决定:注册时先从白名单中剔除,再分别按联网开关、记忆开关(空间、用户、智能体三方都允许)注入。
**旧工具名的兼容**:`knowledge_search`、`grep_chunks` 已合并为 `search_knowledge`;`list_knowledge_chunks`、`get_document_info`、`wiki_read_source_doc` 已合并为 `read_document`。`definitions.go` 的 `legacyToolSuccessors` 记录这组映射,`NormalizeAllowedTools` 在注册工具时把已保存 Agent 配置、预设与 API 调用里的旧名字自动改写为新工具,无需数据迁移;历史消息中记录的旧工具名仍能正常渲染。
**文档阅读工具的可用范围**:`read_document`、`list_documents` 读取的是落库的分块,所有知识库无论索引策略都会写入分块,因此仅 Wiki 的知识库上它们照样注册(`agent_service.go` 的 `documentToolSet`),供 Wiki 智能体回读原文;`search_knowledge` 仍要求向量或关键词索引。能力表里这两个工具标为 `Auxiliary`:它们能用于仅 Wiki 的库,但不会把仅 Wiki 的库拉进 RAG 智能体「全部知识库」的范围,派生 KB 过滤器时只有在没有其他知识库工具时才计入。`list_documents` 的 @文件 / @标签 范围在分页之前生效:标签下推到数据库过滤条件,指定文档直接按 ID 读取,`total_docs` 与 `next_page` 只统计范围内的文档。
**文档阅读工具的可用范围**:`read_document`、`list_documents` 读取的是落库的分块,所有知识库无论索引策略都会写入分块,因此只要作用域内有向量/关键词库或 Wiki 库就会注册(`agent_service.go` 的 `documentToolSet`),供 Wiki 智能体回读原文;`search_knowledge` 仍要求向量或关键词索引。能力表里这两个工具标为 `Auxiliary`:它们能用于仅 Wiki 的库,但不会把仅 Wiki 的库拉进 RAG 智能体「全部知识库」的范围,派生 KB 过滤器时只有在没有其他知识库工具时才计入。`list_documents` 的 @文件 / @标签 范围在分页之前生效:标签下推到数据库过滤条件,指定文档直接按 ID 读取,`total_docs` 与 `next_page` 只统计范围内的文档。
**推荐的检索工作流**:`search_knowledge`(按问题选择 `mode`:默认 `hybrid`,精确词 / 报错信息 / 标识符用 `keyword`,改写或概念性问题用 `semantic`)→ `read_document`(按 `dN` 分页阅读上下文,或用 `query` 在文档内定位)→ 在答案里以 `cN` 句柄引用。Wiki 知识库则是 `wiki_search` → `wiki_read_page` → `read_document` 回读原始来源。
@ -443,8 +453,8 @@ flowchart TD
- **注册**:`RegisterTool` 采用 **first-wins** 策略——同名工具后注册者被拒绝,防止 MCP 服务通过名字碰撞劫持内置工具(对应安全公告 GHSA-67q9-58vj-32qx);
- **定义导出**:`GetFunctionDefinitions` 按工具名排序,保证发给 LLM 的 tools 载荷跨请求字节级一致,以命中依赖前缀匹配的 provider prompt cache(如 Qwen 显式缓存);
- **执行管线**:`ExecuteTool` = `CastParams`(把 `"true"` 转 `true` 等 LLM 常见类型偏差)→ `ValidateParams`(按 JSON Schema 预校验,省一次无效执行 + LLM 往返)→ `tool.Execute` → 输出截断;
- **输出截断**:`TruncateToolOutput`(`truncate.go`)默认上限 `DefaultMaxToolOutput = 16000` **rune**(可由 `AgentConfig.MaxToolOutputChars` 覆盖),超限保留头 70% + 尾 30%,中间插入截断标记,防止大结果污染上下文;
- **错误提示**:失败结果统一追加 `"[Analyze the error above and try a different approach.]"`,引导 LLM 换策略;
- **输出截断**:`TruncateToolOutput`(`truncate.go`)默认上限 `DefaultMaxToolOutput = 24000` **rune**(可由 `AgentConfig.MaxToolOutputChars` 覆盖,`shell_exec`、`discover_mcp_tools` 等工具可声明更高的自身上限),超限保留头 70% + 尾 30%,中间插入截断标记,防止大结果污染上下文;
- **错误提示**:工具参数 JSON 无法解析时,返回结果追加 `"[Analyze the error above and try a different approach.]"`,引导 LLM 换策略;其他失败直接返回工具自身的错误信息;
- **清理**:`Cleanup` 遍历实现 `types.Cleanable` 的工具释放资源。
#### 能力(capabilities)机制与按配置启停 {#_3-3-能力-capabilities-机制与按配置启停}
@ -456,11 +466,10 @@ var ToolCapabilityRequirements = map[string]ToolRequirement{
"thinking": {},
"todo_write": {},
"search_knowledge": {AnyOf: []KBCapability{CapVector, CapKeyword}, ConsumesFiles: true},
"read_document": {AnyOf: []KBCapability{CapVector, CapKeyword}, ConsumesFiles: true},
"list_documents": {AnyOf: []KBCapability{CapVector, CapKeyword}, ConsumesFiles: true},
"read_document": documentReaderRequirement, // AnyOf vector/keyword/wiki,Auxiliary
"query_knowledge_graph": {AllOf: []KBCapability{CapGraph}, ConsumesFiles: true},
// 旧名 knowledge_search / grep_chunks / list_knowledge_chunks / get_document_info / wiki_read_source_doc
// 保留同样的声明,以便旧配置在归一化之前也能通过能力校验
"list_documents": documentReaderRequirement,
// 旧名保留各自原有的声明(wiki_read_source_doc 同 read_document),以便旧配置在归一化之前也能通过能力校验
// ...
"wiki_search": {AllOf: []KBCapability{CapWiki}},
// ...
@ -474,13 +483,13 @@ var ToolCapabilityRequirements = map[string]ToolRequirement{
- `KBSatisfiesToolRequirements`:后端最后防线——绕过前端的客户端也无法把不兼容 KB 塞给工具;
- `ToolsConsumeFiles`:决定聊天输入框是否展示 `@file` 列表。
**运行时启停逻辑**(`agent_service.go` 的 `registerTools`)遵循"**只过滤、不注入**"原则:
**运行时启停逻辑**(`agent_service.go` 的 `registerTools`):
1. 起点是 `config.AllowedTools`(用户可编辑的白名单,preset 只做初始填充);为空回退 `DefaultAllowedTools()`;
1. 起点是 `config.AllowedTools`(用户可编辑的白名单,preset 只做初始填充),先经 `NormalizeAllowedTools` 把旧工具名改写为新名;为空回退 `DefaultAllowedTools()`;共享智能体的只读调用、或作用域内没有可写 Wiki 库时,移除 Wiki 写工具(`wiki_write_page`、`wiki_replace_text`、`wiki_rename_page`、`wiki_delete_page`、`wiki_flag_issue`、`wiki_update_issue`);
2. 若本轮**没有任何知识检索 scope**(Pure Agent 模式),过滤掉全部 KB/Wiki/数据工具;若同时未开 Web 搜索,连 `todo_write` 也一并去掉;
3. `WebSearchEnabled` 时自动追加 `web_search` + `web_fetch`;
4. **硬安全网**:扫描 `SearchTargets` 中各 KB 的真实能力——没有 wiki KB 就丢弃全部 wiki 工具;没有 vector/keyword KB 就丢弃全部 RAG 工具(防止配置陈旧:先勾了 wiki 工具、后换成非 wiki KB);
5. 去重后逐个实例化并注册;MCP 工具按 `MCPSelectionMode`(all/selected/none)另行注册;沙箱 shell/文件工具按会话能力注册,`read_file` 再叠加技能和网页数据源;旧技能工具名仅作兼容识别,不再注册。
3. 按运行时开关注入:开启联网搜索时追加 `web_search` + `web_fetch`,记忆可用时追加 `search_memory`(白名单里写了也会先剔除);
4. **硬安全网**:扫描 `SearchTargets` 中各 KB 的真实能力——没有 wiki KB 就丢弃全部 wiki 工具;没有 vector/keyword KB 就丢弃 `search_knowledge`、`query_knowledge_graph`、`database_query`,此时若也没有 wiki KB 还会丢弃 `read_document`、`list_documents`;没有启用图谱的 KB 就丢弃 `query_knowledge_graph`(防止配置陈旧:先勾了 wiki 工具、后换成非 wiki KB);
5. 去重后逐个实例化并注册;MCP 工具按 `MCPSelectionMode`(all/selected/none)另行注册;沙箱 shell/文件工具按会话能力注册(有 `shell_exec` 时不再注册 `list_sandbox_files`),`read_file` 再叠加技能和网页数据源;`local_browser` 与技能安装器的文件工具走各自的注册条件;旧技能工具名仅作兼容识别,不再注册。
### 记忆与上下文压缩 {#_4-记忆与上下文压缩}
@ -491,7 +500,7 @@ var ToolCapabilityRequirements = map[string]ToolRequirement{
- 上下文预算:`AgentConfig.MaxContextTokens`,`buildAgentConfig` 未设置时兜底 `types.DefaultMaxContextTokens = 200000`;
- `token.Estimator`(`internal/agent/token/estimator.go`)用 tiktoken 的 **cl100k_base** 编码估算,常量 `perMessageOverhead = 3`、`perConversationTail = 3`;编码失败时退化为 `len(s)/4` 近似;
- **权威值优先**:真正的 token 数以模型 API 返回的 `Usage` 为准。引擎的 `estimateCurrentTokens` 用上一轮 API 报告的 `lastUsage.TotalTokens` 作基线,只对新增消息(assistant 回复 + tool 结果)做 BPE 增量估算;首轮无 Usage 时才全量估算。
- **估算校准**:cl100k 不是各家模型的分词器,中文在 cl100k 下约每字 1 token,而 Qwen、DeepSeek 约 0.6,英文与 JSON 则基本一致。估算器因此带一个校准系数(`Estimator.SetScale`,限制在 0.5–1.5),只作用于文本,每条消息的固定开销和图片的固定估值不乘。系数由引擎在同一轮对话的相邻两次请求之间测量:两次请求的工具定义、system prompt 和已有消息都相同,模型报告的 prompt token 增量只对应新追加的消息(上一次回复、工具结果、追加消息),用它除以这些消息的估算即得对话内容的系数,不受各家渲染工具定义方式的影响。中间发生过压缩或工具结果裁剪、样本含图片、比值不可信(< 0.3 或 > 3)、或累计样本不足 256 估算 token 时不计入。测得的系数随本轮 usage 存为 `context_token_scale`(即使模型没有报告 total token 也会保存);本轮没测到系数(例如一次请求就结束、不调工具)时,沿用本轮开始时的系数,使最新一轮总带着最新的系数;下一轮 `LoadAgentHistory` 取最近一条带系数的消息,按它给历史计价并把系数交给引擎作为起点。加载器、首轮压缩判断和压缩器(保留原文预算、摘要输入上限)共用同一个估算器,因此同一把尺子:只校准压缩判断而不校准加载会让加载器先丢轮次,这一点由 `agent_history_cadence_test.go` 覆盖。首轮压缩判断仍只计消息、不计工具定义。
- **估算校准**:cl100k 不是各家模型的分词器,中文在 cl100k 下约每字 1 token,而 Qwen、DeepSeek 约 0.6,英文与 JSON 则基本一致。估算器因此带一个校准系数(`Estimator.SetScale`,限制在 0.5–1.5),只作用于文本,每条消息的固定开销和图片的固定估值不乘。系数由引擎在同一轮对话的相邻两次请求之间测量:两次请求的工具定义、system prompt 和已有消息都相同,模型报告的 prompt token 增量只对应新追加的消息(上一次回复、工具结果、追加消息),用它除以这些消息的估算即得对话内容的系数,不受各家渲染工具定义方式的影响。中间发生过压缩或工具结果裁剪、样本含图片、比值不可信(< 0.3 或 > 3)、或累计样本不足 256 估算 token 时不计入。测得的系数随本轮 usage 存为 `context_token_scale`(即使模型没有报告 total token 也会保存);本轮没测到系数(例如一次请求就结束、不调工具)时,沿用本轮开始时的系数,使最新一轮总带着最新的系数;下一轮 `LoadAgentHistory` 取最近一条带系数的消息,按它给历史计价并把系数交给引擎作为起点。加载器、首轮压缩判断和压缩器(保留原文预算、摘要输入上限)共用同一个估算器,因此同一把尺子:只校准压缩判断而不校准加载会让加载器先丢轮次。首轮压缩判断仍只计消息、不计工具定义。
#### 上下文压缩与溢出恢复 {#_4-2-上下文压缩与溢出恢复}
@ -507,7 +516,7 @@ var ToolCapabilityRequirements = map[string]ToolRequirement{
若压缩后仍超预算,最后才裁短工具结果,工具结果预算取窗口的 20%,限制在 8192–32768 Token。没有可压缩内容或释放空间不足 5% 时,记下当前消息数量,避免在同一上下文大小反复花费模型调用。成功压缩会清除旧 usage 基线,并发出 context_compacted 事件,包含前后 Token/消息数、原因、split_turn 与 degraded。
**压缩点持久化**。当摘要的历史部分恰好结束在某个已落库轮次的末尾时,引擎把这段摘要作为压缩点(`messages.context_checkpoint`)写回该轮的 assistant 消息,下一轮直接从它开始,不再对同一段历史重复摘要。历史消息在重建时带上所属轮次的 assistant 消息 ID(`chat.Message.TurnID`,不上线),据此判断切点是否落在轮次边界。以下情况不写压缩点:切点落在某个已落库轮次内部(例如停在追加消息处);摘要只覆盖当前轮。历史摘要回退成原始归档时仍然写入,并标记 `degraded`:不写的话,摘要器持续失败时每一轮都会重新加载同一段历史、再压缩、再失败;写入后下一次压缩会把它当作上一次的摘要交给模型重新整理。切分轮前半段的摘要不写入压缩点,因为该轮下次会被完整重放。压缩因释放不足 5% 被放弃时,本轮上下文保持不变,但只要历史部分给出了压缩点,照样写入,避免下一轮重复摘要同一段历史。写入只更新这一列,未匹配到该会话的 assistant 行时视为失败;失败时仅记日志,不影响本轮。历史的反向分页和按会话取最新压缩点都走索引 `idx_messages_session_created_id (session_id, created_at DESC, id DESC)`:取压缩点时从最新一条往回扫,遇到第一个压缩点即停。该索引用 `CREATE INDEX CONCURRENTLY` 创建,不阻塞 messages 的写入;迁移文件因此只能包含这一条语句(多条语句会被当作一个隐式事务执行,`CONCURRENTLY` 不能在事务中运行)。压缩点存在被覆盖的那一轮上,所以会话分叉复制该轮时会一起复制,删除该轮时压缩点也随之失效。
**压缩点持久化**。当摘要的历史部分恰好结束在某个已落库轮次的末尾时,引擎把这段摘要作为压缩点(`messages.context_checkpoint`)写回该轮的 assistant 消息,下一轮直接从它开始,不再对同一段历史重复摘要。历史消息在重建时带上所属轮次的 assistant 消息 ID(`chat.Message.TurnID`,不上线),据此判断切点是否落在轮次边界。以下情况不写压缩点:切点落在某个已落库轮次内部(例如停在追加消息处);摘要只覆盖当前轮。历史摘要回退成原始归档时仍然写入,并标记 `degraded`:不写的话,摘要器持续失败时每一轮都会重新加载同一段历史、再压缩、再失败;写入后下一次压缩会把它当作上一次的摘要交给模型重新整理。切分轮前半段的摘要不写入压缩点,因为该轮下次会被完整重放。压缩因释放不足 5% 被放弃时,本轮上下文保持不变,但只要历史部分给出了压缩点,照样写入,避免下一轮重复摘要同一段历史。写入只更新这一列,未匹配到该会话的 assistant 行时视为失败;失败时仅记日志,不影响本轮。历史的反向分页和按会话取最新压缩点都走索引 `idx_messages_session_created_id (session_id, created_at DESC, id DESC)`:取压缩点时从最新一条往回扫,遇到第一个压缩点即停。该索引(迁移 000106)用 `CREATE INDEX CONCURRENTLY` 创建,升级时不阻塞 messages 的写入;创建中断会留下 INVALID 索引,需删除后重跑迁移。压缩点存在被覆盖的那一轮上,所以会话分叉复制该轮时会一起复制,回滚或删除该轮时压缩点也随之失效。
提供商报告上下文超限(错误或响应截断判据)时,还可强制压缩并重试一次。仅因生成耗尽 completion 预算的截断不应误判成上下文超限。具体提供商错误识别见 `internal/agent/compaction/overflow.go`。
@ -515,12 +524,12 @@ var ToolCapabilityRequirements = map[string]ToolRequirement{
跨轮历史由 `LoadAgentHistory`(`internal/application/service/agent_history.go`)每轮从 messages 表重建(DB 是唯一事实来源,无 Redis/内存缓存):
- 历史按 Token 预算加载,不按轮数,`history_turns` 在 Agent 模式下不生效。预算是整个上下文窗口(`agent.HistoryTokenBudget`),刻意大于压缩阈值:加载器放不下的轮既不重放也不进摘要,等于丢失;若预算只到阈值,加载器会先裁掉旧轮,请求可能再也越不过阈值,压缩与压缩点都不会发生,会话退化成滑动窗口。预算到窗口时,超出阈值的部分交给首轮压缩摘要并写入压缩点,下一轮从新压缩点开始,历史随之回落;会话再次填满时才再压缩(`agent_history_cadence_test.go` 逐轮模拟验证:压缩点之后的轮不会缺失,压缩不会连续两轮发生);
- 历史按 Token 预算加载,不按轮数,`history_turns` 在 Agent 模式下不生效。预算是整个上下文窗口(`agent.HistoryTokenBudget`),刻意大于压缩阈值:加载器放不下的轮既不重放也不进摘要,等于丢失;若预算只到阈值,加载器会先裁掉旧轮,请求可能再也越不过阈值,压缩与压缩点都不会发生,会话退化成滑动窗口。预算到窗口时,超出阈值的部分交给首轮压缩摘要并写入压缩点,下一轮从新压缩点开始,历史随之回落;会话再次填满时才再压缩,压缩点之后的轮不会缺失,压缩也不会连续两轮发生;
- 会话中存在压缩点(见[上下文压缩与溢出恢复](#_4-2-上下文压缩与溢出恢复))时,取最新的一个:它所在的轮及更早的轮由一条摘要消息代替,放在历史最前面,之后的轮原样重放。压缩点所在轮未被读到时(预算先装满),按 assistant 行的 `(created_at, id)` 顺序判断哪些轮在它之后。压缩点查询失败时退回无压缩点的历史;
- 按 `(created_at, id)` 从新到旧分页读取(每页 200 行,单次最多 5000 行),按 `RequestID` 配对 user/assistant,只保留 assistant 已完成(`IsCompleted`)的完整轮。读到压缩点或预算装满即停止,长会话不会整段读出。读取未到会话开头且最旧一行不是 user 消息时,该行所在的轮缺少原始问题,会被舍弃;
- 从最新的轮往前放入预算,遇到第一个放不下的轮即停止,保证保留的轮连续。最新一轮即使单独超出预算也会保留,由压缩负责切分。每轮按引擎实际发送的内容计价并返回(`agent.HistoryAsSent`):未开启 `RetainRetrievalHistory` 时,历史中的 KB/Wiki 结果只以一行占位发送,也只按一行计入预算、只以一行留在内存里(`search_knowledge` 等结果入库时已压成一行,差异主要在按全文存储的 `wiki_read_page` / `wiki_search`)。每轮回放完就释放对应的数据库行,分页读取时同时驻留的约为一页数据库行加上要发送的历史;
- 每轮展开为:user 消息(含图片 caption 与附件 prompt;忽略 `RenderedContent` 快照,避免将旧渲染协议带入上下文)→ 每个含工具调用的 `AgentStep` 展开为 assistant(with tool_calls) + 若干 tool 消息 → 末尾一条规范化最终答案 assistant 消息(剥离 `<think>` 块);
- 历史中的 tool 消息内容用 `CompactToolOutputForHistory`(`internal/agent/tools/persist.go`)压缩:带 `display_type` 的大载荷(如 `knowledge_chunks_list` 的 chunks、`grep_results` 的 chunk_results)替换为一行摘要(如 `"Listed 20/87 chunks from X (content omitted from history)"`)。
- 历史中的 tool 消息内容用 `CompactToolOutputForHistory`(`internal/agent/tools/persist.go`)压缩:带 `display_type` 的大载荷替换为一行摘要,如 `search_knowledge` 结果变为 `"Knowledge search returned N result(s) (details omitted from history)"`,`read_document` 的分块列表变为 `"Listed 20/87 chunks from X (content omitted from history)"`;`shell_exec`、`read_file` 等沙箱工具的结果按原结构重建而非压成一行。
进入引擎后,`buildMessagesWithLLMContext` 还会做**历史 KB 结果脱敏**(`redactHistoryKBResults`):除非 Agent 开启 `RetainRetrievalHistory`,历史轮次中 KB 类工具(`search_knowledge`、`read_document`、`list_documents`、`query_knowledge_graph`、`wiki_search`、`wiki_read_page`,以及历史里可能残留的旧名 `knowledge_search`、`grep_chunks`、`list_knowledge_chunks`、`get_document_info`、`wiki_read_source_doc`)的结果一律替换为 `"[Previous retrieval result omitted — knowledge base may have changed. Please perform a fresh search.]"`,强制模型对可能已变更的知识库做新鲜检索。
@ -528,7 +537,7 @@ var ToolCapabilityRequirements = map[string]ToolRequirement{
### 技能(Skills)系统 {#_5-技能-skills-系统}
使用步骤、安装来源、沙箱连接、网络策略和环境变量见[技能目录与沙箱](22-skills-sandbox.md)。技能依赖智能体选择的空间沙箱配置,生产对话不加载宿主机 `skills/preloaded`。
使用步骤、安装来源、沙箱连接、网络策略和环境变量见[技能目录与沙箱](22-skills-sandbox.md)。技能依赖智能体选择的空间沙箱配置。
#### 渐进加载和作用域 {#_5-1-渐进加载和作用域}
@ -536,7 +545,7 @@ var ToolCapabilityRequirements = map[string]ToolRequirement{
`skills_selection_mode` 为 all/selected/none;selected 由 selected_skills 指定。运行时仅暴露所选沙箱中已安装且可用的技能。`@技能` 只把已授权的提及记录为本轮优先项,不收窄原白名单,也不会授权一个原本不可用的技能。
统一入口为 `read_file` 和 `shell_exec(skill_name=..., command=...)`;旧 `read_skill`、`execute_skill_script` 不再注册。技能文件 URI 不是 shell 路径;执行包内脚本使用读取结果给出的目录或 `$WEKNORA_SKILL_DIR`。未选择空间沙箱配置时,脚本执行不可用。
统一入口为 `read_file` 和 `shell_exec(skill_name=..., command=...)`;旧 `read_skill`、`execute_skill_script` 不再注册。技能文件 URI 不是 shell 路径;执行包内脚本使用读取结果给出的目录或 `$WEKNORA_SKILL_DIR`。未选择空间沙箱配置时,脚本执行不可用;macOS 上的 Lite 桌面版改用[本机沙箱](22-skills-sandbox.md#lite-host)。
#### 会话环境与文件 {#_5-2-会话环境与文件}
@ -609,7 +618,7 @@ MCP 工具审批由 `internal/agent/approval/gate.go` 实现。
#### 两条问答路径 {#_9-1-两条问答路径}
路由层(`internal/router/router.go`)注册了两个入口:
路由层(`internal/router/routes_chat.go`)注册了两个入口:
```go
knowledgeChat.POST("/:session_id", handler.KnowledgeQA) // /knowledge-chat/:session_id
@ -653,14 +662,15 @@ const (
| 常量 | 值 | 位置 |
| --- | --- | --- |
| `DefaultAgentMaxIterations` | 20 | `internal/agent/const.go` |
| `MAX_ITERATIONS`(服务层上限) | 100 | `internal/application/service/agent_service.go` |
| `defaultLLMCallTimeout` | 120s | `internal/agent/const.go` |
| `defaultLLMStallTimeout` | 120s(连续无输出的上限,非总时长) | `internal/agent/const.go` |
| `defaultToolExecTimeout` | 60s | `internal/agent/const.go` |
| `shellExecToolTimeout` | 10m5s | `internal/agent/const.go` |
| `maxLLMRetries` | 2 | `internal/agent/const.go` |
| `maxEmptyResponseRetries` | 2 | `internal/agent/const.go` |
| `maxRepeatedResponseRounds` | 2 | `internal/agent/const.go` |
| `DefaultMaxToolOutput` | 16000 rune(头 70% / 尾 30%) | `internal/agent/tools/truncate.go` |
| `maxConsecutiveLengthRounds` | 3 | `internal/agent/const.go` |
| `DefaultMaxToolOutput` | 24000 rune(头 70% / 尾 30%) | `internal/agent/tools/truncate.go` |
| `DefaultMaxContextTokens` | 200000 | `internal/types/agent.go` |
| `DefaultReserveTokens` | 16384(输出预算较大时增加) | `internal/agent/compaction/settings.go` |
| `DefaultKeepRecentTokens` | 20000(小窗口下调) | `internal/agent/compaction/settings.go` |

View File

@ -2,12 +2,12 @@
MCP 用于智能体与外部工具之间的连接。WeKnora 支持接入外部 MCP 服务,也提供独立 MCP Server 供其他客户端调用:
1. **WeKnora 作为 MCP 客户端**:在「MCP 服务」设置中接入任意外部 MCP server(SSE / Streamable HTTP),其工具通过目录按需加载到 Agent 的工具箱,供 Agent 在对话中调用。支持 API Key / Bearer / OAuth 2.0(含动态客户端注册与 PKCE)三种认证策略、按工具粒度的人工审批,以及会话内(in-conversation)OAuth 授权。
2. **WeKnora 作为 MCP Server**:在「发布与集成 → MCP Server」中为当前空间创建一个或多个 MCP 端点,每个端点有独立的令牌、知识库范围和工具清单,Claude Desktop、Cursor、Claude Code、VS Code Copilot 等 MCP 客户端通过 Streamable HTTP 直接连接,无需额外部署进程。仓库 `mcp-server/` 目录下的 Python 服务是旧方案,已标记弃用。
1. **WeKnora 作为 MCP 客户端**:在「工具箱 → MCP服务」中接入任意外部 MCP server(SSE / Streamable HTTP),其工具通过目录按需加载,供 Agent 在对话中调用。支持 API Key / Bearer / OAuth 2.0(含动态客户端注册与 PKCE)三种认证策略、按工具粒度的启停与人工审批,以及会话内(in-conversation)OAuth 授权。
2. **WeKnora 作为 MCP Server**:在「设置 → 发布集成 → MCP Server」中为当前空间创建一个或多个 MCP 端点,每个端点有独立的令牌、知识库范围和工具清单,Claude Desktop、Cursor、Claude Code、VS Code Copilot 等 MCP 客户端通过 Streamable HTTP 直接连接,无需额外部署进程。仓库 `mcp-server/` 目录下的 Python 服务是旧方案,已标记弃用。
接入外部服务可扩展 WeKnora 智能体的工具;运行 WeKnora MCP Server 可让外部客户端使用知识库检索、问答和管理能力。
在「设置 → MCP 服务」新建服务,选择传输和认证方式,测试连接后在智能体中选择所需工具。需要控制写入或外发操作时,可为相应工具开启人工审批,调用前会显示确认卡片。
空间 Admin 在侧边栏「工具箱 → MCP服务」新建服务(旧的「设置 → MCP 服务」链接会自动跳转到这里),填好连接后同步工具并写使用说明,再在智能体中选择所需服务。需要控制写入或外发操作时,可为相应工具开启人工审批,调用前会显示确认卡片。
<Screenshot
src="/screenshots/mcp-services.png"
@ -20,16 +20,24 @@ MCP 用于智能体与外部工具之间的连接。WeKnora 支持接入外部 M
## 接入外部工具
在 MCP 服务设置中添加服务地址,选择 SSE 或 Streamable HTTP 传输,并配置认证。测试连接后查看发现的工具,在智能体配置中选择需要的服务或工具。
新建服务分两步:
OAuth 服务按调用者分别授权。工具需要审批时,在对话中检查参数并确认;单独停用某个工具后,运行时不会执行该工具。WeKnora 的 MCP 客户端不支持 stdio 传输。
1. **连接配置**:填写名称和服务 URL,选择 SSE 或 Streamable HTTP 传输,并配置认证(无 / 自定义 Header、API Key / Token、OAuth 2.0)和超时、重试。也可以用「从代码导入」粘贴标准 `mcpServers` JSON 自动填表;只含 `command` / `args` 的 stdio 配置不支持。保存后可测试连接;OAuth 服务点「去授权」时会先自动保存,再按当前用户发起授权。
2. **工具与用途说明**:连接并拉取 Tools,系统会保存完整的工具描述和参数定义;再填写「使用说明」,说明服务用途、适用场景和关键约束。已同步工具后可点「AI 生成」,根据已启用的工具生成一段精简说明,检查后保存。工具列表中可逐个设置「启用工具」和「调用需审批」,修改即时生效,刷新目录不会覆盖这些设置。
模型先读取服务的使用说明,再按需加载具体工具,所以使用说明直接影响 Agent 能否选对服务。OAuth 服务按调用者分别授权。工具需要审批时,在对话中检查参数并确认;单独停用某个工具后,运行时不会执行该工具。WeKnora 的 MCP 客户端不支持 stdio 传输。
## 供外部客户端调用
在「设置 → 发布与集成 → MCP Server」新建端点:填写名称、选择可访问的知识库(留空为全部)、勾选要暴露的工具,需要问答时再指定默认 Agent。创建后会一次性展示令牌和地址 `/mcp/<endpoint_id>`,页面同时给出 Cursor / VS Code / Claude Desktop 的 `mcpServers` 配置、Claude Code 的一行命令,以及仅支持 stdio 的客户端通过 `mcp-remote` 桥接的写法。
在「设置 → 发布集成 → MCP Server」新建端点:填写名称、选择可访问的知识库(留空为全部)、勾选要暴露的工具,并按需指定 `ask` 使用的默认 Agent(留空时使用内置快速问答)和每分钟调用上限(默认 60 次)。创建后会一次性展示令牌和地址 `/mcp/<endpoint_id>`,页面同时给出 Cursor / VS Code / Claude Desktop 的 `mcpServers` 配置、Claude Code 的一行命令,以及仅支持 stdio 的客户端通过 `mcp-remote` 桥接的写法。
使用自定义反向代理时,除 `/api/` 外,还需将 `/mcp/` 原路径转发到 WeKnora 后端,保留 `Authorization` 和 MCP 协议头,并关闭响应缓冲、为长连接设置足够的读写超时。仓库自带的 Nginx、Vite 开发及预览配置已包含该代理,可直接使用网站域名连接,无需另行暴露后端 8080 端口。
<Screenshot
src="/screenshots/mcp-server-endpoint.png"
caption="发布集成 → MCP Server:端点创建完成后的地址、令牌与客户端配置"
hint="新建端点后的结果页:一次性令牌与 /mcp/<endpoint_id> 地址、Cursor / Claude Desktop 的 mcpServers 配置与 Claude Code 命令;背景可见端点的知识库范围与四组工具勾选。" />
一个空间可以创建多个端点。例如给客服团队一个只开检索和问答、只看两个知识库的端点,给内容团队另一个开了写入工具的端点。令牌可随时轮换,端点可随时停用,删除端点后使用它的客户端立即断开。
端点暴露的工具按四组勾选,默认只开只读工具:
@ -37,7 +45,7 @@ OAuth 服务按调用者分别授权。工具需要审批时,在对话中检
| 组 | 工具 | 说明 |
|---|---|---|
| 检索与阅读 | `list_knowledge_bases`、`search_knowledge`、`grep_chunks`、`list_documents`、`read_document` | 知识库参数同时接受 ID 或名称;`search_knowledge` 用 `mode`(hybrid / semantic / keyword)选择检索方式并可设 `limit`(默认 10,上限 30);`grep_chunks` 保持大小写不敏感的正则语义:从模式里提取字面词作为关键词索引的检索词(没有关键词索引的库改用语义索引取候选),再逐条用正则校验,返回的分块都匹配该模式;不含任何字面词的模式(如 `^\d+$`)会被拒绝;`read_document` 按 `offset` / `limit` 翻页,或用 `query` 在文档内查找短语 |
| 问答 | `ask` | 只运行端点配置的默认 Agent(客户端不能自选 Agent),服务端自动建会话,返回带引用的完整回答和 `session_id`,续聊时传回即可;不开启联网搜索 |
| 问答 | `ask` | 只运行端点配置的默认 Agent(客户端不能自选 Agent;未配置时使用内置快速问答),服务端自动建会话,返回带引用的完整回答和 `session_id`,续聊时传回即可;不开启联网搜索 |
| Wiki | `wiki_search`、`wiki_read_page`、`wiki_index` | 只对开启了 Wiki 的知识库生效;`wiki_search` 的 `query` 保持原有的正则语义(大小写不敏感),不是合法正则的文本按字面匹配;`regex=false` 强制字面匹配,`regex=true` 要求合法正则 |
| 写入 | `add_document`、`update_document`、`delete_document` | 默认关闭;支持 Markdown 文本或 URL 导入 |
@ -141,7 +149,7 @@ type MCPService struct {
> 注意:类型系统中仍保留 `MCPTransportStdio` 及 `StdioConfig`(`command` + `args`)字段,`mcp_tool.go` 中也有 stdio 的连接释放分支,但运行时创建 stdio 客户端的入口全部被拦截,实际可用的只有 SSE 与 Streamable HTTP。
高级配置 `MCPAdvancedConfig`(默认值来自 `types.GetDefaultAdvancedConfig()`):`timeout` 30 秒、`retry_count` 3、`retry_delay` 1 秒。`timeout` 同时作用于 HTTP client 超时和 initialize 握手超时(`manager.go` 中 initialize 超时上限 60 秒)。
高级配置 `MCPAdvancedConfig`(默认值来自 `types.GetDefaultAdvancedConfig()`):`timeout` 30 秒、`retry_count` 3、`retry_delay` 1 秒。`timeout` 同时作用于 HTTP client 超时和 initialize 握手超时(`manager.go` 中 initialize 超时上限 60 秒)。Agent 单次工具调用默认有 60 秒窗口;服务的 `timeout` 大于 60 秒时会相应延长该服务的 CallTool 窗口,小于 60 秒则不缩短(`internal/agent/tools/mcp_tool.go` 的 `callToolTimeout`)。
#### 认证策略 {#_1-3-认证策略}
@ -388,9 +396,9 @@ flowchart LR
#### 数据模型与管理 API
`mcp_endpoints` 表(PostgreSQL 迁移 `000102_mcp_endpoints`,SQLite `000022_mcp_endpoints`)每行一个端点:`tenant_id`、`name`、`enabled`、`token_hash`(SHA-256)、`token_hint`(前缀展示用)、`knowledge_base_ids`(空数组表示空间内全部)、`tools`(白名单)、`default_agent_id`、`rate_limit_per_minute`、`last_used_at`。类型定义在 `internal/types/mcp_endpoint.go`,工具目录在 `internal/types/mcp_endpoint_tools.go`。
`mcp_endpoints` 表(PostgreSQL 迁移 `000102_mcp_endpoints`,SQLite `000022_mcp_endpoints`)每行一个端点:`tenant_id`、`name`、`description`、`enabled`、`token_hash`(SHA-256)、`token_hint`(前缀展示用)、`knowledge_base_ids`(空数组表示空间内全部)、`tools`(白名单)、`default_agent_id`(空为内置快速问答)、`rate_limit_per_minute`(默认 60,上限 6000)、`last_used_at`。类型定义在 `internal/types/mcp_endpoint.go`,工具目录在 `internal/types/mcp_endpoint_tools.go`。
管理接口挂在 `/api/v1/mcp-endpoints`,读取需 Viewer,变更需 Admin,API Key 需要 `manage_channels` 能力:
管理接口挂在 `/api/v1/mcp-endpoints`,读取需 Viewer,变更需 Admin,API Key 需要 `manage_channels` 能力(字段与示例见[MCP API](../04-api/02-api-agent-mcp.md#mcp-server-端点)):
| 方法 | 路径 | 说明 |
|---|---|---|
@ -571,11 +579,11 @@ SSE 与 HTTP 传输由 `MCPAuthMiddleware`(ASGI 中间件)统一鉴权:客
| 工具名 | 参数 | 说明 |
|---|---|---|
| `create_knowledge_from_file` | `kb_id`\*, `file_path`\*, `enable_multimodel`(true) | 从服务器本地文件导入知识;路径经 `upload_paths.resolve_upload_file_path` 校验(见 2.6) |
| `create_knowledge_from_file` | `kb_id`\*, `file_path`\*, `enable_multimodel`(true), `file_name` | 从服务器本地文件导入知识;`file_name` 可写成 `docs/spec/design.pdf` 这类带目录的名称,放入知识库对应文件夹;路径经 `upload_paths.resolve_upload_file_path` 校验(见 2.6) |
| `create_knowledge_from_url` | `kb_id`\*, `url`\*, `enable_multimodel`(true) | 从网页 URL 导入知识 |
| `create_knowledge_from_text` | kb_id、title、content 必填;tag_ids、status | 从 Markdown 建手工知识;status 默认 publish,draft 只保存 |
| `update_knowledge_from_text` | knowledge_id、content 必填;title、status | 更新手工 Markdown;title 空保留原标题,publish 重新索引,draft 保存草稿 |
| `list_knowledge` | `kb_id`\*, `page`(1), `page_size`(20) | 分页列出知识条目 |
| `list_knowledge` | `kb_id`\*, `page`(1), `page_size`(20), `folder_path`, `folder_scope` | 分页列出知识条目;`folder_path` 按文件夹过滤(`""` 为根目录) |
| `get_knowledge` | `knowledge_id`\* | 知识详情 |
| `delete_knowledge` | `knowledge_id`\* | 删除知识 |
@ -660,7 +668,7 @@ stdio 传输(Claude Desktop 的 `claude_desktop_config.json`):
远程部署(Docker / `--transport http`)时,客户端连接 `http://<host>:8000/mcp` 并携带 `Authorization: Bearer <MCP_SERVER_AUTH_TOKEN>`。
顺带一提:WeKnora 主程序(第一部分)也可以作为 MCP 客户端接入这个 mcp-server——在「MCP 服务」中新建 Streamable HTTP 服务指向 `/mcp` 端点、认证方式选 Bearer 即可,从而让 WeKnora Agent 操作另一套 WeKnora 实例。
顺带一提:WeKnora 主程序(第一部分)也可以作为 MCP 客户端接入这个 mcp-server——在「工具箱 → MCP服务」中新建 Streamable HTTP 服务指向 `/mcp` 端点,认证方式选「API Key / Token」,请求头名称填 `Authorization`,密钥值填 `Bearer <MCP_SERVER_AUTH_TOKEN>` 即可,从而让 WeKnora Agent 操作另一套 WeKnora 实例。
#### 文件上传路径安全(upload_paths.py) {#_2-6-文件上传路径安全-upload-paths-py}

View File

@ -38,7 +38,7 @@ func (kb *KnowledgeBase) IsGraphEnabled() bool {
}
```
- `IndexingStrategy.GraphEnabled`(`internal/types/indexing_strategy.go`):知识库索引策略里的图谱开关,默认 `false`;旧字段 `ExtractConfig.Enabled` 会在读取时向 `IndexingStrategy.GraphEnabled` 单向同步(`knowledgebase.go` 635 行附近的 legacy sync)。
- `IndexingStrategy.GraphEnabled`(`internal/types/indexing_strategy.go`):知识库索引策略里的图谱开关,默认 `false`;旧字段 `ExtractConfig.Enabled` 会在读取时向 `IndexingStrategy.GraphEnabled` 单向同步(`knowledgebase.go` 中的 legacy sync)。
- `ExtractConfig`(`internal/types/knowledgebase.go`)承载抽取的 few-shot 配置:
| 名称 | 类型 | 默认值 | 说明 |
@ -50,7 +50,7 @@ func (kb *KnowledgeBase) IsGraphEnabled() bool {
| `relations` | []*GraphRelation | nil | 示例关系(node1 / node2 / type) |
| `custom_instructions` | string | 空 | 领域自定义抽取指令(追加进系统提示,结构化输出协议仍由系统控制) |
配置向导辅助 API(`internal/handler/initialization.go`,路由 `internal/router/router.go` 914-916 行):
配置向导辅助 API(`internal/handler/initialization.go`,路由注册于 `internal/router/routes_infra.go`,需 Admin;API Key 需 `manage_models` 能力):
- `POST /initialization/extract/text-relation`(`ExtractTextRelations`):对一段文本(≤5000 字符)按选定标签试跑关系抽取,用于预览效果;
- `POST /initialization/extract/fabri-text` / `fabri-tag`(`FabriText` / `FabriTag`):让 LLM 生成示例文本 / 推荐标签,帮助用户快速搭建 `ExtractConfig`。
@ -59,7 +59,11 @@ func (kb *KnowledgeBase) IsGraphEnabled() bool {
### 触发与任务编排
文档解析完成后,`internal/application/service/knowledge_post_process.go` 在增强扇出阶段对每个文本 chunk 计数(`eff.GraphEnabled` 时 `graphChunkCount = len(textChunks)`),并调用 `internal/application/service/extract.go` 的 `NewChunkExtractTask` 逐 chunk 入队:
文档解析完成后,`internal/application/service/knowledge_post_process.go` 在增强扇出阶段用 `selectGraphChunks` 选出抽取输入(`eff.GraphEnabled` 时 `graphChunkCount = len(graphChunks)`),并调用 `internal/application/service/extract.go` 的 `NewChunkExtractTask` 逐 chunk 入队。选取规则:
- 有正文的文本 chunk 参与抽取;只含图片链接的文本 chunk 跳过;
- 父文本 chunk 没有正文时(典型如扫描件 PDF 的页面图),改用它的 `image_ocr` 子 chunk,让 OCR 出的文字也能进入图谱;
- `image_caption` 子 chunk 不参与,避免与 OCR 内容重复。
```go
func NewChunkExtractTask(...) (bool, error) {
@ -82,7 +86,7 @@ func NewChunkExtractTask(...) (bool, error) {
1. 加载 chunk、知识库与文件级 `ProcessOverrides`,用 `ResolveProcessConfig` 求出生效的 `ExtractConfig`(未启用则跳过)。
2. 组装结构化提示模板:系统协议部分来自 `config.ExtractManager.ExtractGraph`(`config/config.yaml` 的 `extract.extract_graph`,一个包含实体抽取 + 属性丰富 + 关系抽取步骤的多步指令),叠加知识库的 `custom_instructions`、`tags` 与 `ExtractConfig` 的 few-shot 示例(`Text/Nodes/Relations`)。
3. `chatpipeline.NewExtractor(chatModel, template).Extract(ctx, chunk.Content)` 调用 Chat 模型(`temperature 0.3`、`max_tokens 4096`、关闭 thinking),由 `Formater.ParseGraph` 解析为 `types.GraphData`(`internal/types/extract_graph.go`):
3. `chatpipeline.NewExtractor(chatModel, template).Extract(ctx, chunk.Content)` 调用 Chat 模型(`temperature 0.3`、`max_tokens 8192`、关闭 thinking;输出上限足以容纳较多节点与关系,避免 JSON 被截断),由 `Formater.ParseGraph` 解析为 `types.GraphData`(`internal/types/extract_graph.go`):
```go
type GraphNode struct {
@ -114,13 +118,16 @@ SET node.chunks = apoc.coll.union(node.chunks, row.chunks)
```
- 删除知识 / 知识库时(`knowledge_delete.go`、`knowledgebase.go`)调用 `DelGraph`,用 `apoc.periodic.iterate` 按 1000 批并行删边删点。
- `SearchNode` 的查询有两道上限,防止一个很短或很常见的实体名拉回整张图:
- 只有至少有一条关系的实体才能作为展开起点,最多 200 个种子实体;排序为名称完全匹配优先,其次名称较短者,再按字母序;
- 返回的(实体, 关系)行最多 2000 条,并沿用同样的排序,截断时保留排名靠前的种子的邻域。触达行数上限时记录 Warn 日志,提示结果已被截断。
## 检索时的图谱增强(GraphRAG)
传统聊天管线(`internal/application/service/chat_pipeline`)中有两个插件:
1. **PluginExtractEntity**(`extract_entity.go`,挂在 `QUERY_UNDERSTAND` 事件):`NEO4J_ENABLE=true` 时,先筛出 `ExtractConfig.Enabled` 的知识库(存入 `chatManage.EntityKBIDs` / `EntityKnowledge`),再用 `ExtractManager.ExtractEntity` 模板 + Chat 模型从**用户查询**里抽取实体名,存入 `chatManage.Entity`。
2. **PluginSearchEntity**(`search_entity.go`,挂在 `ENTITY_SEARCH` 事件):对每个启用图谱的知识库 / 文件并行调用 `graphRepo.SearchNode`——Cypher 用 `n.name CONTAINS nodeText` 模糊匹配实体并返回一跳邻居与关系,合并为 `chatManage.GraphResult`;随后 `filterSeenChunk` 取出图谱节点携带的 `chunks`(去掉向量检索已命中的),从 `chunkRepo` 拉取原文并转换为 `SearchResult` 并入候选集,实现"实体 → 关联 chunk"的图谱补充召回。
2. **PluginSearchEntity**(`search_entity.go`,挂在 `ENTITY_SEARCH` 事件):对每个启用图谱的知识库 / 文件并行调用 `graphRepo.SearchNode`——Cypher 用 `n.name CONTAINS nodeText` 模糊匹配实体并返回一跳邻居与关系,合并为 `chatManage.GraphResult`(查询上限见下文);随后 `filterSeenChunk` 取出图谱节点携带的 `chunks`(去掉向量检索已命中的),从 `chunkRepo` 拉取原文并转换为 `SearchResult` 并入候选集,实现"实体 → 关联 chunk"的图谱补充召回。
Agent 模式则提供 `query_knowledge_graph` 工具(`internal/agent/tools/query_knowledge_graph.go`):校验各知识库是否配置了图谱(`ExtractConfig.Nodes/Relations` 非空),并发对多库执行检索、按 chunk 去重排序,输出中附带各库的图谱配置状态(实体类型 / 关系类型清单);未配置图谱的库回落为普通混合检索结果。该工具的能力要求是 `all_of: [graph]`,并且只有当 Agent 作用域内存在启用图谱的知识库时才会提供给模型——`agent_service.go` 装配工具白名单时会把它从没有图谱库的作用域中移除,避免模型反复调用一个只能返回退化结果的工具。
@ -132,7 +139,7 @@ Agent 模式则提供 `query_knowledge_graph` 工具(`internal/agent/tools/que
flowchart TD
A["文档解析完成<br/>(knowledge_post_process)"] --> B{"kb.IsGraphEnabled() 且<br/>NEO4J_ENABLE=true?"}
B -->|"否"| Z["跳过图谱抽取"]
B -->|"是"| C["逐文本 chunk 入队<br/>asynq QueueGraph / TypeChunkExtract<br/>(MaxRetry=3, Timeout=30m)"]
B -->|"是"| C["selectGraphChunks 选输入<br/>逐 chunk 入队<br/>asynq QueueGraph / TypeChunkExtract<br/>(MaxRetry=3, Timeout=30m)"]
C --> D["ChunkExtractService.Handle"]
D --> E["组装结构化提示:<br/>ExtractManager.ExtractGraph 协议<br/>+ ExtractConfig few-shot (text/nodes/relations)<br/>+ tags + custom_instructions"]
E --> F["Chat 模型抽取<br/>(temp 0.3, 关闭 thinking)"]
@ -151,7 +158,7 @@ flowchart TD
U1 -->|"否"| SKIP["跳过, 走常规检索"]
U1 -->|"是"| U2["LLM 从查询抽取实体名<br/>(ExtractManager.ExtractEntity 模板)"]
U2 --> S["ENTITY_SEARCH:<br/>PluginSearchEntity"]
S --> S1["按知识库/文件并行<br/>Neo4j SearchNode<br/>(name CONTAINS entity, 返回一跳邻居)"]
S --> S1["按知识库/文件并行<br/>Neo4j SearchNode<br/>(name CONTAINS entity, 返回一跳邻居,<br/>种子 ≤200, 行 ≤2000)"]
S1 --> S2["合并 GraphResult<br/>(nodes + relations)"]
S2 --> S3["filterSeenChunk:<br/>取节点 chunks, 去掉已命中的"]
S3 --> S4["chunkRepo 拉取原文<br/>转为 SearchResult 并入候选集"]

View File

@ -1,6 +1,6 @@
# 数据源导入(Data Source)
数据源将飞书、Notion、语雀等平台的内容持续同步到知识库。连接建立后,可按计划获取新增与修改;来源删除的内容按同步配置处理。
数据源将飞书、Notion、Confluence、语雀等平台的内容持续同步到知识库。连接建立后,可按计划获取新增与修改;来源删除的内容按同步配置处理。
数据源在知识库中配置。打开目标知识库的编辑设置,进入「数据源」页签,新建连接并填写凭据,然后选择同步范围与周期。首次同步获取完整内容,后续同步根据连接器能力增量更新。
@ -22,7 +22,19 @@
## 选择连接器
飞书、Lark、Notion 和语雀用于同步协作文档,GitLab 用于同步仓库中的文档目录,IMA 用于同步可访问的知识库与笔记,RSS 用于订阅文章。各连接器支持的格式、认证与删除检测见参考部分。
| 连接器 | 类型标识 | 同步对象 |
| --- | --- | --- |
| 飞书 / Lark 知识库 | `feishu` / `lark` | Wiki 空间与节点 |
| 飞书云盘 / Lark Drive | `feishu_drive` / `lark_drive` | 指定云盘文件夹,见[飞书云盘接入](24-feishu-drive.md) |
| Notion | `notion` | 页面与数据库 |
| Confluence | `confluence` | Server / Data Center 或 Cloud 空间中的页面 |
| 语雀 | `yuque` | 知识库文档 |
| 钉钉文档 | `dingtalk` | 知识库、文件夹与在线文档 |
| 腾讯 IMA | `ima` | 知识库中的文件与笔记 |
| GitLab | `gitlab` | 仓库指定分支/标签下的目录 |
| RSS / Atom | `rss` | 订阅源文章 |
各连接器支持的格式、认证与删除检测见参考部分。
## 检查变更与失败
@ -36,7 +48,7 @@
| | Feishu / Lark | Notion | Yuque(语雀) | RSS / Atom |
| --- | --- | --- | --- | --- |
| 源码目录 | `internal/datasource/connector/feishu/` | `connector/notion/` | `connector/yuque/` | `connector/rss/` |
| 源码目录 | `internal/datasource/connector/feishu/wiki/`(共享 `feishu/core/`) | `connector/notion/` | `connector/yuque/` | `connector/rss/` |
| 类型标识 | `feishu` / `lark` | `notion` | `yuque` | `rss` |
| 认证方式 | 企业自建应用 `app_id` + `app_secret`(tenant_access_token) | Internal Integration Token(`api_key`) | 个人/团队 Token(`api_token`,`X-Auth-Token` 头) | 无认证或自定义请求头(`auth_headers`) |
| 凭据字段 | `app_id`、`app_secret`、`base_url`(可选覆盖) | `api_key`(`base_url` 走 Settings) | `api_token`、`base_url`(私有化部署可选) | `auth_headers`(可选,属凭据);`feed_urls` 属 Settings |
@ -48,21 +60,21 @@
| 限流应对 | 429 读 `Retry-After` + 指数退避(2s/4s/8s,最多 3 次重试);5xx 重试 | — | 每次 `GetDocDetail` 间隔 300ms(个人 token 约 100 req/5min) | — |
| 部分失败 | 单文档失败生成带错误 metadata 的占位条目,继续同步 | 单页失败记日志跳过 | 单文档失败生成占位条目 | 单 feed 失败 → `PartialFetchError`;全部失败才算 fail |
#### Feishu / Lark(`connector/feishu/`)
#### Feishu / Lark(`connector/feishu/wiki/`)
云盘应用权限、文件夹授权、资源选择和 `FEISHU_DOCX_PARSE_MODE` 取舍见[飞书云盘接入](24-feishu-drive.md)。默认 export 与 blocks 模式的图片、附件语义不同;开启同步删除时会删除当前数据源对应的知识条目。
飞书与 Lark(国际版 open.larksuite.com)是部署在两朵隔离云上的同一产品,Wiki/docx/drive API 完全一致,因此**共用同一份连接器代码**,由 `region.go` 中的 `Region` 结构选择云端(`RegionFeishu` / `RegionLark`,分别对应类型 `feishu` / `lark`、API 域名 `open.feishu.cn` / `open.larksuite.com`)。`base_url` 凭据字段可显式覆盖(兼容历史上把 feishu 连接器指向 larksuite 的存量数据源)。
飞书与 Lark(国际版 open.larksuite.com)是部署在两朵隔离云上的同一产品,Wiki/docx/drive API 完全一致,因此**共用同一份连接器代码**,由 `feishu/core/region.go` 中的 `Region` 结构选择云端(`RegionFeishu` / `RegionLark`,分别对应类型 `feishu` / `lark`、API 域名 `open.feishu.cn` / `open.larksuite.com`)。`base_url` 凭据字段可显式覆盖(兼容历史上把 feishu 连接器指向 larksuite 的存量数据源)。
- **认证**(`client.go`):`POST /open-apis/auth/v3/tenant_access_token/internal` 换取 tenant_access_token,带互斥锁缓存与过期刷新。
- **认证**(`core/client.go`):`POST /open-apis/auth/v3/tenant_access_token/internal` 换取 tenant_access_token,带互斥锁缓存与过期刷新。
- **资源列举**(`ListResources`):三级懒加载——`parentID==""` 列 Wiki 空间;`parentID==spaceID` 列空间顶层节点;`parentID=="spaceID:nodeToken"` 列该节点子节点。早期版本会预先递归整棵树,大 Wiki 会超时(issue #1672),现在递归只发生在同步时。`ResolveResourceAncestors` 通过 `GetWikiNode` 的 `parent_node_token` 逐级上溯,O(depth) 回显深层勾选。
- **内容抓取**(`fetchNodeContent`)按 `obj_type` 分派:
- `docx`/`doc` → 异步导出 API(`POST /drive/v1/export_tasks`)导出 `.docx`;
- `sheet`/`bitable` → 导出 `.xlsx`;
- `file` → drive 原文件下载(PDF/Word/图片等);
- `mindnote`/`slides` → **跳过**(无内容读取 API),并通过 `fetchTally` 统计输出 `discovered/fetched/failed/skipped_unsupported by_type` 摘要日志,解释"发现 13 篇为何只同步了 3 篇"(issue #2136)。
- **增量逻辑**:游标 `feishuCursor.SpaceNodeTimes`(`resourceID → nodeToken → editTime`)。变更判定用 `obj_edit_time`(文档内容编辑时间),而**不是** `node_edit_time`(只反映改标题/挪位置)。抓取失败的节点**不推进游标**(保留旧 editTime,下次必然 prev != current 而重试),避免瞬时导出失败导致文档被永久跳过。
- **FetchStream**:统一全量/增量路径(cursor==nil 即全量),每处理 `feishuStreamCheckpointInterval = 50` 个节点、或距上次 checkpoint 超过 `feishuStreamCheckpointMaxInterval = 30s` 就落盘一次游标——后者兜底"少量文档但每篇导出都极慢(被限流)"导致 2 小时超时前从未 checkpoint 的场景。
- **增量逻辑**:游标 `FeishuCursor.SpaceNodeTimes`(`resourceID → nodeToken → editTime`)。变更判定用 `obj_edit_time`(文档内容编辑时间),而**不是** `node_edit_time`(只反映改标题/挪位置)。抓取失败的节点**不推进游标**(保留旧 editTime,下次必然 prev != current 而重试),避免瞬时导出失败导致文档被永久跳过。
- **FetchStream**:统一全量/增量路径(cursor==nil 即全量),每处理 `FeishuStreamCheckpointInterval = 50` 个节点、或距上次 checkpoint 超过 `FeishuStreamCheckpointMaxInterval = 30s` 就落盘一次游标——后者兜底"少量文档但每篇导出都极慢(被限流)"导致 2 小时超时前从未 checkpoint 的场景。
- **错误分类**(`feishuFailure`):把原始错误归类为稳定 i18n code(`feishu_auth_or_permission` / `feishu_rate_limited` / `feishu_timeout` / `feishu_server_unavailable` / `feishu_api_error`(+code) / `sync_failed`),前端本地化展示;原始 status/body/log_id 只留在服务端日志。
#### GitLab(`connector/gitlab/`)
@ -71,7 +83,7 @@
`config.settings.projects` 为非空数组,每项包含字符串 project_id、可选 ref 和 paths。ref 留空使用默认分支;paths 留空选整个仓库,目录使用相对路径与正斜杠。先验证凭据并浏览资源,再保存定时同步。
流式同步支持恢复检查点;增量通过仓库提交差异更新文件,源端删除按 sync_deletions 处理。选择的仓库文件仍经过 WeKnora 文件类型、大小与解析引擎校验,并非所有代码或二进制文件都可直接入库。
流式同步支持恢复检查点;增量通过仓库提交差异更新文件,源端删除按 sync_deletions 处理。选择的仓库文件仍经过 WeKnora 文件类型、大小与解析引擎校验,并非所有代码或二进制文件都可直接入库。不同路径下内容完全相同的文件(如各子目录的 README 模板)会作为独立知识保留,重复判定只在同一数据源、同一文件路径内生效。
```json
{"credentials":{"base_url":"https://gitlab.example.com","access_token":"<token>"},"settings":{"projects":[{"project_id":"123","ref":"main","paths":["docs"]}]}}
@ -79,7 +91,7 @@
#### 腾讯 IMA(`connector/ima/`)
填写 credentials.client_id 和 api_key;base_url 可选,默认 `https://ima.qq.com`。资源树列出该凭据可见的 IMA 知识库与目录,选择结果保存为 config.resource_ids。源端授权失败或资源不可见时,先检查 IMA 凭据及知识库访问权。
填写 credentials.client_id 和 api_key;base_url 可选,默认 `https://ima.qq.com`。资源列表是该凭据可见的 IMA 知识库(扁平列表,不展开目录),选择结果保存为 config.resource_ids;同步时递归遍历所选知识库中的全部子文件夹。源端授权失败或资源不可见时,先检查 IMA 凭据及知识库访问权。
可下载文件进入文档解析,网页类按 URL 获取;笔记通过 note OpenAPI 读取正文。AI 会话和视频解析没有可用正文读取入口,会被跳过。支持全量与增量同步:按知识库、父目录和标题建立稳定身份,同名文件替换后 media_id 改变会触发更新;完整列举成功后才检测删除。
@ -97,6 +109,35 @@
- **增量逻辑**:首次同步(游标为空)直接委托 `FetchAll` 并用返回条目的 `UpdatedAt` 构建游标;后续同步 `discoverAllResources` 用 Search API + BFS 圈定选中根下的全部后代,逐页比对 `last_edited_time`。数据库走 `fetchDatabaseIncremental`:任一记录变更就整表重建。
- **删除与取消勾选的区分**:源端消失的页面报 `IsDeleted`;仍可见但因用户取消勾选祖先而不再可达的页面进入 excluded 集合,**不会**被误报为删除。`computeExcludedSet` 同时保证"用户从未见过的新页面"不被排除——选中的父节点仍会自动带上新子页面。
#### Confluence(`connector/confluence/`)
支持 Confluence Server / Data Center 与 Confluence Cloud,均使用 HTTP Basic 认证。
| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `edition` | 否 | `server`(默认,Server / Data Center)或 `cloud` |
| `base_url` | 是 | Confluence 地址,缺少协议时补 `https://`;Cloud 填 `https://<站点>.atlassian.net` 时自动补 `/wiki` |
| `username` | 是 | Server/DC 用户名;Cloud 为 Atlassian 账号邮箱 |
| `password` | Server/DC 必填 | Server/DC 账号密码 |
| `api_token` | Cloud 必填 | 在 Atlassian 账号的 API tokens 页面创建 |
`edition`、`base_url`、`username` 不属于密钥,界面会同时写入 Settings 以便编辑时回显;`password` / `api_token` 只存加密凭据。
<Screenshot
src="/screenshots/datasource-confluence.png"
caption="Confluence 数据源:版本选择与凭据填写"
hint="数据源编辑弹窗选中 Confluence,展示「Confluence 版本」下拉(Server / Data Center、Cloud)、地址、用户名与 Cloud API 令牌字段,以及测试连接后的空间选择列表。" />
- **范围**:资源列表是凭据可见的空间(扁平列表),至少选择一个空间;同步空间内全部已发布页面,不导入附件和博客文章。
- **内容**:取页面渲染后的 HTML 转为 Markdown(每页一个 `.md` 条目),正文为空时仅保留标题。条目 metadata 带 `space_key`、`space_name`、`page_id`,有作者时带 `creator`。
- **增量**:按页面版本号比对,版本未变的页面跳过。实现了流式同步,每页入库后保存游标;全量同步的中途游标同时保留上次的页面基线,任务重试可续传,也能继续对账删除。
- **删除保护**:所选空间不可访问、页面列表为空而上次有内容,或本次消失的页面不少于 20 个且占上次页面数 80% 以上时,整次同步报错,不执行删除。开启同步删除后,其余情况下消失的页面按删除处理。
- **错误**:单页失败生成带错误信息的占位条目并继续;错误码为 `confluence_auth_or_permission`、`confluence_not_found`、`confluence_rate_limited`、`confluence_server_unavailable`、`confluence_api_error`、`confluence_sync_failed`,原始响应只记服务端日志。
```json
{"credentials":{"edition":"cloud","base_url":"https://team.atlassian.net","username":"me@example.com","api_token":"<token>"},"resource_ids":["<space-id>"]}
```
#### Yuque 语雀(`connector/yuque/`)
- **认证**:个人 Token(语雀设置 → Token)或团队 Token,凭据字段 `api_token`(请求头 `X-Auth-Token`)+ 可选 `base_url`(企业私有化域名,缺 scheme 自动补 `https://`)。
@ -123,7 +164,7 @@
### 数据源生命周期与 REST API
路由注册在 `internal/router/router.go` 的 `RegisterDataSourceRoutes`(读操作 Viewer+,写操作 Admin+):
路由注册在 `internal/router/routes_infra.go` 的 `RegisterDataSourceRoutes`(列表、详情、同步日志为 Viewer+,其余操作 Admin+;API Key 需 `manage_datasources` 或 full-access):
| 方法与路径 | 权限 | 说明 |
| --- | --- | --- |
@ -137,8 +178,8 @@
| `PUT /api/v1/datasource/:id/credentials` | Admin | 原子替换凭据(见[凭据加密存储](#凭据加密存储)) |
| `DELETE /api/v1/datasource/:id/credentials/:field` | Admin | 清空凭据(field 只接受 `credentials`) |
| `POST /api/v1/datasource/:id/validate` | Admin | 对已存数据源做连接测试;失败置 `status=error`,成功清除 error 状态 |
| `GET /api/v1/datasource/:id/resources?parent_id=` | Viewer | 列出外部系统可选资源(parent_id 支持懒加载展开) |
| `POST /api/v1/datasource/:id/resource-ancestors` | Viewer | 解析选中资源的祖先链(编辑时回显深层勾选) |
| `GET /api/v1/datasource/:id/resources?parent_id=` | Admin | 列出外部系统可选资源(parent_id 支持懒加载展开) |
| `POST /api/v1/datasource/:id/resource-ancestors` | Admin | 解析选中资源的祖先链(编辑时回显深层勾选) |
| `POST /api/v1/datasource/:id/sync` | Admin | 手动触发同步(创建 SyncLog + 入队 Asynq 任务) |
| `POST /api/v1/datasource/:id/pause` / `resume` | Admin | 暂停/恢复(同时移除/重挂 cron) |
| `GET /api/v1/datasource/:id/logs`、`GET /api/v1/datasource/logs/:log_id` | Viewer | 同步历史 |
@ -179,7 +220,7 @@ flowchart LR
- **防御性取消**:数据源或知识库已被删除时,把 SyncLog 置为 `canceled` 并返回 nil(不再重试)。
- **两条抓取路径**:连接器实现了 `StreamingConnector` 走 `processSyncStreaming`(流式);否则按 `ForceFull || SyncMode==full` 走 `FetchAll`,或带上 `ParseSyncCursor()` 的游标走 `FetchIncremental`(批量)。
- **流式路径的游标策略**(`streamStartCursor`):用户触发的全量同步在**首次尝试**时丢弃游标全量抓取;Asynq **重试**(attempt > 0)以及所有增量同步都从最后一个 checkpoint 续传。
- **流式路径的游标策略**(`streamStartCursor`):用户触发的全量同步在**首次尝试**时丢弃游标全量抓取;Asynq **重试**(attempt > 0)以及所有增量同步都从最后一个 checkpoint 续传。实现了 `FullStreamingConnector` 的连接器(目前为 Confluence)在全量同步时改走 `FetchFullStream`:重新抓取全部条目,同时保留旧游标作为删除对账基线。
- **入库核心 `applyFetchedItem` → `ingestItem`**:
- `IsDeleted=true` 且 `sync_deletions=true` 时,按租户、知识库、数据源 ID 和 external_id 查找并真实删除对应知识;关闭同步删除则保留已有知识。删除能力还取决于连接器是否提供可靠的删除检测;
- 有 `Content` 字节 → 包装成 `multipart.FileHeader` 走 `KnowledgeService.CreateKnowledgeFromFile`(完整文档解析流水线);只有 `URL` → 走 `CreateKnowledgeFromURL` 由 WeKnora 下载解析;
@ -209,7 +250,7 @@ sequenceDiagram
Q-->>S: ProcessSync(payload)
S->>DB: 加载 DataSource / SyncLog / 校验 KB 存在
S->>S: ParseConfig() 解密凭据
alt "StreamingConnector(Feishu/Lark/GitLab)"
alt "StreamingConnector(Feishu/Lark、GitLab、Confluence)"
S->>C: FetchStream(config, cursor, handler)
loop "遍历 Wiki 节点"
C->>EXT: ListWikiNodesRecursive / ExportAndDownload
@ -220,7 +261,7 @@ sequenceDiagram
S->>DB: 持久化 LastSyncCursor + SyncLog 进度
end
C-->>S: 最终 cursor
else "批量连接器(Notion/Yuque/RSS)"
else "批量连接器(Notion/Yuque/钉钉/IMA/RSS)"
S->>C: FetchAll 或 FetchIncremental(cursor)
C->>EXT: 列表 + 拉取变更内容
EXT-->>C: 文档 / Markdown
@ -323,26 +364,27 @@ type StreamingConnector interface {
}
```
任务超时后可从最近的 checkpoint 继续处理。Asynq 同步任务超时为 2 小时,流式路径按条目推进,避免缓存全部文件正文。Feishu/Lark 和 GitLab 连接器均实现了 `StreamingConnector`。钉钉目前走 batch `FetchAll`/`FetchIncremental`/`FetchAllFromCursor`,超大知识库建议使用增量模式以免一次装入全部 Markdown。
任务超时后可从最近的 checkpoint 继续处理。Asynq 同步任务超时为 2 小时,流式路径按条目推进,避免缓存全部文件正文。Feishu/Lark(知识库与云盘)、GitLab 和 Confluence 连接器实现了 `StreamingConnector`;Confluence 另实现 `FullStreamingConnector`,全量同步也能对账删除。钉钉目前走 batch `FetchAll`/`FetchIncremental`/`FetchAllFromCursor`,超大知识库建议使用增量模式以免一次装入全部 Markdown。
#### ConnectorRegistry:注册与查找
`ConnectorRegistry` 是简单的 `map[string]Connector` 注册表。实际注册发生在 `internal/container/container.go` 的 `initConnectorRegistry()`:
```go
registry.Register(feishuConnector.NewConnector(feishuConnector.RegionFeishu)) // feishu
registry.Register(feishuConnector.NewConnector(feishuConnector.RegionLark)) // lark(国际版,同一实现不同 Region)
registry.Register(drive.NewDriveConnector(core.RegionFeishuDrive)) // feishu_drive
registry.Register(drive.NewDriveConnector(core.RegionLarkDrive)) // lark_drive
registry.Register(notionConnector.NewConnector()) // notion
registry.Register(yuqueConnector.NewConnector()) // yuque
registry.Register(dingtalkConnector.NewConnector()) // dingtalk
registry.Register(imaConnector.NewConnector()) // ima
registry.Register(rssConnector.NewConnector()) // rss
registry.Register(gitlabConnector.NewConnector()) // gitlab
registry.Register(wiki.NewConnector(core.RegionFeishu)) // feishu
registry.Register(wiki.NewConnector(core.RegionLark)) // lark(国际版,同一实现不同 Region)
registry.Register(drive.NewDriveConnector(core.RegionFeishuDrive)) // feishu_drive
registry.Register(drive.NewDriveConnector(core.RegionLarkDrive)) // lark_drive
registry.Register(notionConnector.NewConnector()) // notion
registry.Register(confluenceConnector.NewConnector()) // confluence
registry.Register(yuqueConnector.NewConnector()) // yuque
registry.Register(dingtalkConnector.NewConnector()) // dingtalk
registry.Register(imaConnector.NewConnector()) // ima
registry.Register(rssConnector.NewConnector()) // rss
registry.Register(gitlabConnector.NewConnector()) // gitlab
```
> 注意:`connector.go` 中的 `ConnectorMetadataRegistry` 仍包含尚未实现的连接器(Confluence、GitHub、Google Drive、OneDrive、Web Crawler、Slack、IMAP 等)。当前实际注册可用的类型为:`feishu`、`lark`、`feishu_drive`、`lark_drive`、`notion`、`yuque`、`dingtalk`、`ima`、`rss`、`gitlab`。未注册类型在创建数据源时会被 `connectorRegistry.Get()` 以 `ErrConnectorNotFound` 拒绝。
> 注意:`connector.go` 中的 `ConnectorMetadataRegistry` 仍包含尚未实现的连接器(GitHub、Google Drive、OneDrive、Web Crawler、Slack、IMAP 等)。当前实际注册可用的类型为:`feishu`、`lark`、`feishu_drive`、`lark_drive`、`notion`、`confluence`、`yuque`、`dingtalk`、`ima`、`rss`、`gitlab`。未注册类型在创建数据源时会被 `connectorRegistry.Get()` 以 `ErrConnectorNotFound` 拒绝。
### 数据模型(internal/types/datasource.go)

View File

@ -6,7 +6,7 @@
## 支持的搜索引擎
引擎在 `internal/container/container.go` 中注册:
引擎在 `internal/container/container.go` 的 `registerWebSearchProviders` 中注册:
```go
registry.Register("duckduckgo", infra_web_search.NewDuckDuckGoProvider)
@ -18,10 +18,11 @@ registry.Register("baidu", infra_web_search.NewBaiduProvider)
registry.Register("searxng", infra_web_search.NewSearxngProvider)
registry.Register("keenable", infra_web_search.NewKeenableProvider)
registry.Register("zhipu", infra_web_search.NewZhipuProvider)
registry.Register("metaso", infra_web_search.NewMetasoProvider)
registry.Register("exa", infra_web_search.NewExaProvider)
registry.Register("metaso", infra_web_search.NewMetasoProvider)
registry.Register("bocha", infra_web_search.NewBochaProvider)
registry.Register("brave", infra_web_search.NewBraveProvider)
registry.Register("serply", infra_web_search.NewSerplyProvider)
```
| 引擎 | 源码文件 | 是否需要 API Key | 端点 | 备注 |
@ -41,14 +42,14 @@ registry.Register("brave", infra_web_search.NewBraveProvider)
| Brave Search | `brave.go` | 是 | `https://api.search.brave.com/res/v1/web/search` | 支持按次传 country/freshness |
| Serply | `serply.go` | 是 | `https://api.serply.io/v1/search` | Google 结果;支持按次传 country/freshness(仅 pd/pw/pm/py) |
在「设置 → 网络搜索」选择提供商、填写 API Key 并测试,然后在智能体中选择该配置。当前注册 14 个引擎;实际结果数仍受智能体最大结果数约束。
当前共注册 14 个引擎。
| 提供商附加配置 | 值 |
| --- | --- |
| Metaso scope | webpage(默认)、document、scholar、podcast、video、image |
| Exa include_text | 字符串布尔值,例如 `"true"`;默认不取正文 |
| Bocha freshness | noLimit(默认)、oneDay、oneWeek、oneMonth、oneYear |
| Bocha summary | 字符串布尔值,决定是否请求摘要 |
| Bocha summary | 默认请求摘要;设为 `"false"` 时关闭 |
| Brave 按次过滤 | country/freshness 是 web_search 工具参数,见下文;与 Bocha 固定配置的字段取值不同 |
| Serply 按次过滤 | 同 Brave;country 映射为 Google 的 gl,freshness 只接受 pd/pw/pm/py,不支持日期区间 |
@ -66,7 +67,7 @@ registry.Register("brave", infra_web_search.NewBraveProvider)
| `proxy_url` | string | 空 | 可选出站 HTTP/HTTPS 代理(仅隧道流量,不替换 API 端点),同样过 SSRF 校验 |
| `extra_config` | map[string]string | nil | 提供商特定参数,如 Metaso scope、Exa include_text、Bocha freshness/summary |
CRUD 路由(`RegisterWebSearchProviderRoutes`,`internal/router/router.go`):`/web-search-providers` 下的增删改查、`POST /test`(用存量凭证探测外部服务,Admin 权限)、`POST /:id/test`、`PUT /:id/credentials`;另有 `GET /web-search/providers` 返回可用引擎类型目录。
CRUD 路由(`RegisterWebSearchProviderRoutes`,`internal/router/routes_infra.go`):`/web-search-providers` 下的增删改查、`POST /test`(用未保存的参数试连)、`POST /:id/test`(测试已保存配置)、`PUT /:id/credentials` 与 `DELETE /:id/credentials/:field`,测试与写操作均需 Admin;另有 `GET /web-search/providers` 返回可用引擎类型目录。完整接口见[基础设施 API](../04-api/02-api-infra.md)。
## Agent 搜索与读页
@ -103,11 +104,8 @@ flowchart TD
- `count` 指定结果数量,范围是 1 到当前 Agent 配置的最大结果数(最多 20);省略时沿用现有 Agent 默认值。
- `country` / `freshness` 通过 Brave 与 Serply 提供商生效。地区接受两字母代码或 `ALL`,时效接受 `pd` / `pw` / `pm` / `py` 或 `YYYY-MM-DDtoYYYY-MM-DD`。省略 `country` 时不向 Brave 传该参数(Brave 自身默认 US);显式 `ALL` 表示全球结果。Serply 的 `country` 映射为 Google 的 `gl`(省略或 `ALL` 时不传 `gl`,由 Google 决定地区),`freshness` 只接受 `pd` / `pw` / `pm` / `py`。其它提供商暂不支持这些过滤,显式传入时返回错误,不会静默忽略。参数取值参见 [Brave 官方 API 文档](https://api-dashboard.search.brave.com/api-reference/web/search/get)。
- 在联网搜索设置中新建 Brave Search 配置并填写 API Key,可使用现有代理配置;API Key 沿用加密存储和独立凭据接口。
- `content` 默认关闭。设为 `true` 时,并行抓取前 3 条结果的正文(整批 15 秒预算,每页最多 5,000 字符摘录);其余结果保留搜索摘要,需用 `web_fetch` 继续读页。抓取失败仍保留摘要;完整正文地址通过 `full_output_path` 返回。搜索和独立 `web_fetch` 共用本轮快照,短超时不会取消正在进行的共享抓取。
- Brave 的相对 `age` 原样保留,避免把“2 days ago”伪造为精确发布日期。
- 保留现有多搜索引擎、租户配置、代理、黑名单与日期能力,provider 仍由 Agent 运行配置解析。
- 去除空查询、无效 URL、重复结果;最大结果数来自 Agent 配置,上限 20。
- Agent 搜索不再调用 `CompressWithRAG`,不创建临时知识库,不依赖嵌入/重排模型或 Redis 临时状态。聊天快速回答管线的 RAG 压缩配置仍由原管线处理。
- 模型输出包含标题、域名、可用日期与 wN 页面 ID。摘要与 provider content 标为未经页面验证的搜索证据;每段最多 1,500 字符,整批证据预算 16,000 字符。
@ -137,27 +135,13 @@ flowchart TD
共享抓取器的快速回答路径继续使用 `NewPipelineFetcher`:15 秒超时、100 KiB 下载上限、HTTP-only 与原纯文本抽取。
### 行为调整与回归验证
| 行为 | 调整前 WeKnora Agent | 调整后 |
| --- | --- | --- |
| 搜索前置 | 强制两个 KB 工具,即使未注册 | 根据任务与可用来源选择 |
| 搜索附带处理 | 可自动入临时 KB 做 RAG | 直接返回搜索证据,按需读页 |
| 读页参数 | 强制 url + prompt | url,按需 offset/limit |
| 正文分析 | 每页再调用模型摘要 | 主 Agent 直接读 Markdown |
| 截断 | 每页/整批限额,后续页面可能空白,无续读 | 每页保留份额、完整正文存储、跨轮按行续读 |
| 失败 | 整批失败强制停止搜索 | 保留已有证据,合理重试或换源 |
保留多搜索引擎、wN 引用、批量调用、租户开关与 SSRF 防护;通过 Brave 适配器支持 country/freshness,不支持过滤的提供商返回明确错误。显式 `content=true` 与独立 `web_fetch` 都可读页。
正文提取使用 Go Readability / Markdown 库。本地 HTML 回归样例覆盖完整文章的相邻段落、结构化内容、链接目录及代码缩进,检查正文结构和链接保留情况,避免二次裁剪丢失段落。运行 `go test ./internal/infrastructure/web_fetch -run TestMarkdownExtractionFixtures` 可验证。
## docker/searxng 的角色
SearXNG 是自托管的元搜索引擎(聚合上游多个引擎),WeKnora 把它作为**免 API Key 的默认可选搜索后端**打包在 `docker-compose.yml` 的 `searxng` / `full` profile 中:
- `docker/searxng/settings.yml`:关键定制包括 `search.formats` 开启 `json`(WeKnora 后端走 `/search?format=json`)、`server.limiter: false`(关闭 IP 限流,否则后端会被节流;若公开部署需重新开启并配置放行名单)、`secret_key` 由入口脚本以 `SEARXNG_SECRET` 环境变量替换。
- `searxng-init` 辅助容器先把模板复制进独立 volume,避免 SearXNG 入口脚本原地 sed 修改把解析后的密钥写回仓库工作区。
- 宿主机端口由 `SEARXNG_PORT`(默认 8888)和 `SEARXNG_BIND`(默认 `127.0.0.1`)控制。不要把 `SEARXNG_PORT` 设成与 `APP_PORT`(默认 8080)相同:Linux 上两者同时发布同一端口时,访问 `localhost:8080` 可能先命中 SearXNG,登录接口会返回 SearXNG 的 HTML 404。
- 应用容器默认把 `searxng` 主机名并入 SSRF 白名单:`SSRF_WHITELIST_EXTRA=searxng,qdrant,...`,因此租户配置 `base_url: http://searxng:8080` 开箱即用。
- 客户端超时 12s(`defaultSearxngTimeout`),略高于 SearXNG 的 `outgoing.max_request_timeout: 10.0`,让上游慢引擎表现为 SearXNG 侧错误而非客户端取消。`ValidateSearxngBaseURL` 在"保存"与"使用"两处共享,保证配置校验一致。
@ -171,6 +155,8 @@ SearXNG 是自托管的元搜索引擎(聚合上游多个引擎),WeKnora
- 重定向逐跳经 `ssrfSafeRedirect` 复验 `ValidateURLForSSRF`,超过最大跳数直接失败;
- 显式 `proxy_url` 需通过 SSRF 校验,未配置时回落 `ProxyFromEnvironment`。
开启 `SSRF_DNS_WHITELIST_ONLY` 后,搜索服务域名、SearXNG 主机名,以及 `web_fetch` 要读取的网页域名都必须写入 `SSRF_WHITELIST`,否则在 DNS 查询前即被拒绝,详见[配置参考](../01-getting-started/04-configuration.md)。
### 接口抽象
搜索能力由两层接口定义(`internal/types/interfaces/web_search.go`):

View File

@ -2,7 +2,7 @@
IM 集成将智能体接入企业微信、飞书、钉钉、Slack、Telegram 等聊天平台。用户可在平台中向机器人提问,由 WeKnora 根据绑定的智能体配置执行检索和回答。
在「设置 → IM 集成」新建渠道,选择平台、填写应用凭据并绑定智能体后启用。Webhook 模式需要在平台后台填写回调地址;长连接模式无需为接收消息配置公网回调地址。
在「设置 → IM 集成」新建渠道,选择平台、填写应用凭据并绑定智能体后启用。Webhook 模式需要在平台后台填写回调地址;长连接模式无需为接收消息配置公网回调地址。每个渠道可单独设置「回复语言」,固定智能体在该渠道的回复语言;留空时使用部署默认语言。
<Screenshot
src="/screenshots/im-channels.png"
@ -22,7 +22,7 @@ IM 集成将智能体接入企业微信、飞书、钉钉、Slack、Telegram 等
| Lark `lark` | 同飞书(同一适配器,`RegionLark` 指向 open.larksuite.com) | 是 | 是 | 是 | 同飞书 |
| Slack `slack` | **websocket**(Socket Mode)/ webhook(Events API) | 是 | 是 | 是(`thread_ts`) | websocket:`app_token` + `bot_token`;webhook:`bot_token` + `signing_secret` |
| Telegram `telegram` | **websocket**(长轮询 getUpdates)/ webhook | 是(消息编辑) | 是 | 是(Forum Topics 的 `message_thread_id`) | `bot_token`;webhook 另有 `secret_token` |
| 钉钉 `dingtalk` | **websocket**(Stream 模式)/ webhook | 是(AI 卡片) | 是 | 否 | `client_id`、`client_secret`、`card_template_id` |
| 钉钉 `dingtalk` | **websocket**(Stream 模式,v0.8.2 起仅支持此模式;升级迁移 000096 会把 webhook 渠道改为 websocket,需在钉钉开发者后台开启 Stream) | 是(AI 卡片) | 是 | 否 | `client_id`、`client_secret`、`card_template_id` |
| Mattermost `mattermost` | **webhook**(仅支持 Outgoing Webhook + REST API) | 是 | 是 | 是(`root_id`) | `site_url`、`bot_token`、`outgoing_token`(必填)、`bot_user_id`、`post_to_main` |
| 微信 `wechat`(iLink 机器人) | **longpoll**(强制;创建时后端强制 `mode=longpoll`、`output_mode=full`) | 否(仅整段输出) | 是 | 否 | `bot_token`、`ilink_bot_id`(均必填) |
| QQ 机器人 `qqbot` | **websocket**(仅支持) | 否 | 否 | 否 | `app_id`、`client_secret`、`api_base_url`、`gateway_url` |
@ -103,6 +103,7 @@ flowchart LR
| `AgentID` | 绑定的自定义智能体;回答走该 Agent 的配置(模型、知识库、Skills、MCP、联网搜索) |
| `Platform` / `Mode` | 平台与接入模式。默认值:mattermost/yunzhijia → `webhook`,wechat → `longpoll`(且强制 `output_mode=full`),其余 → `websocket` |
| `OutputMode` | `stream`(默认,流式)或 `full`(等完整答案后一次性回复) |
| `Locale` | 回复语言:`zh-CN` / `en-US` / `ja-JP` / `ko-KR` / `ru-RU`,其他值返回 400。留空(默认)使用 `WEKNORA_LANGUAGE`,未设置时为 `zh-CN`。IM 回调请求头里的 `Accept-Language` 来自平台而非提问者,因此不参与决定回复语言 |
| `KnowledgeBaseID` | 可选"文件知识库"。无论是否配置,文件/图片都会下载后供 QA 理解;配置后会额外在后台入库(见下文) |
| `SessionMode` | `user`(默认,按 平台+用户+群 维度映射会话)或 `thread`(按 平台+线程+群 维度,每个顶层消息开新会话) |
| `BotIdentity` | 由平台+模式+凭据推导的机器人唯一标识(`computeBotIdentity`,如 `feishu:<app_id>`、`telegram:<botID>`、`wecom:ws:<bot_id>`),数据库唯一索引防止同一个机器人被配置到两个渠道(`checkDuplicateBot` 返回 `duplicate_bot:` 前缀错误 → HTTP 409) |
@ -110,16 +111,17 @@ flowchart LR
`ChannelSession`(表 `im_channel_sessions`)把 `(platform, user_id, chat_id, thread_id, tenant_id)` 映射到 WeKnora `session_id`,实现 IM 侧的对话连续性。若底层 Session 被从 Web UI 删除,`HandleMessage` 会检测 `ErrSessionNotFound`,软删陈旧映射并自动重建(修复 #1046、#1499 中"机器人永久失联"的问题)。
#### 渠道管理 API(internal/handler/im.go + router.go)
#### 渠道管理 API(internal/handler/im.go + routes_agent.go)
| 方法与路径 | 说明 |
| --- | --- |
| `POST /api/v1/agents/:id/im-channels` | 为 Agent 创建渠道(校验 platform 合法性、填充默认 mode/output_mode) |
| `GET /api/v1/agents/:id/im-channels` | 列出 Agent 的渠道(不含凭据) |
| `GET /api/v1/im-channels` | 租户内跨 Agent 渠道总览 |
| `PUT /api/v1/im-channels/:id` | 更新(name/mode/output_mode/knowledge_base_id/credentials/enabled/agent_id) |
| `PUT /api/v1/im-channels/:id` | 局部更新(name/mode/output_mode/locale/session_mode/knowledge_base_id/credentials/enabled/agent_id);`knowledge_base_id` 传空字符串即解除文件知识库 |
| `DELETE /api/v1/im-channels/:id` | 删除 |
| `POST /api/v1/im-channels/:id/toggle` | 启用/停用 |
| `POST /api/v1/wechat/qrcode`、`POST /api/v1/wechat/qrcode/status` | 微信(iLink)扫码绑定:生成二维码并轮询状态 |
| `GET / POST /api/v1/im/callback/:channel_id` | **平台回调地址**(webhook 模式下配置到各平台后台;走平台自身签名校验,不需要 WeKnora API Key) |
Webhook 模式的接入方式就是把 `https://<你的域名>/api/v1/im/callback/<channel_id>` 填到平台的事件订阅/回调地址处;WeKnora 会先响应平台的 URL 验证挑战(`HandleURLVerification`,如飞书的 challenge 回显、企微的 echostr 解密),之后每个回调都过 `VerifyCallback` 签名校验。WebSocket/长连接模式则无需公网回调地址,由 WeKnora 主动连接平台网关。
@ -138,6 +140,7 @@ credentials.api_base_url 可覆盖 API origin,并同时用作长连接 SDK 的
- **多实例 leader 选举**(`service.go`):websocket/longpoll 渠道在多实例部署(有 Redis)时,通过 `SETNX im:ws:leader:<channelID>`(TTL 15s,每 5s 续期)保证**只有一个实例**维持长连接;非 leader 实例每 10s 重试抢锁,leader 宕机后自动接管。longpoll 渠道停止后保留锁至过期,等 TTL 自然过期,避免新旧实例短暂双写。续期失败(丢失 leader 身份)时走 `handleWSLeadershipLoss`:先停掉本实例的适配器,再把渠道放回抢锁重试循环——重试前会重新读一次数据库中的渠道行,因此期间被删除、禁用或改配置的渠道不会被旧运行时复活。
- **连接保活**(`supervisor.go` 的 `RunSupervised`):部分 SDK(钉钉、飞书)的内部重连可能出现连接对象存在但无法接收消息的状态,Supervisor 每 6 小时(`defaultRecycleInterval`)主动重建连接,连接失败按 5s 退避重试,把最坏停摆时间限制在回收间隔内。
- **云之家长连接**(`yunzhijia/websocket.go`):每 15s 发送心跳,45s 内收不到任何数据即判定连接失效并重连;单条连接最长保持 6 小时后主动重建。重连按 1s、2s、5s、10s、30s、60s 退避。
### 多实例部署要点
@ -191,7 +194,7 @@ sequenceDiagram
S->>A: UpdateStreamContent(思考块 + 工具状态行 + 已生成答案)
A->>P: 更新流式卡片 / 编辑消息
end
QA-->>S: EventAgentComplete (最终答案 + 引用)
QA-->>S: EventAgentComplete (最终答案 + 引用),或 AgentQA 返回
S->>A: FinalizeStream(仅保留答案, 剥离 think/工具过程) → EndStream
S->>DB: 回填 assistant message (内容/引用/AgentSteps)
end
@ -205,6 +208,7 @@ sequenceDiagram
- **会话解析**:`user` 模式按用户维度共享会话,标题形如"张三 · 群聊 1a2b3c4d";`thread` 模式每个顶层消息/话题一个会话(Slack thread、飞书话题群、Telegram Forum Topic、Mattermost root_id)。首条消息会异步生成会话标题(`GenerateTitleAsync`)。
- **身份注入**(`withIMIdentity`):IM 回调走平台签名而非 WeKnora 登录态,因此注入合成身份 `system-<tenantID>` + `PrincipalIMUser`(`tenantID:channelID:platform:userID`)+ Viewer 角色,使组织共享知识库等依赖 UserID 的逻辑正常工作;同时标记 `MCPOAuthNonInteractive`(见[MCP OAuth 授权通知](#mcp-oauth-授权通知-身份绑定))。
- **流式渲染**(`handleMessageStream` + `think.go` + `tool_display.go`):订阅 EventBus 的 `EventAgentThought`(思考)、`EventAgentToolCall`/`EventAgentToolResult`(工具状态行,内部工具经 `isToolVisibleToUser` 过滤;快速问答只显示 `query_understand`/`knowledge_search` 两个 RAG 流水线工具)、`EventAgentFinalAnswer`(答案分片)、`EventAgentReferences`(引用)、`EventAgentComplete`。Agent 模式下"乐观答案"在后续又发起工具调用时会被**撤回**进思考块(`retractAgentLiveAnswer`,与 Web 端 superseded preamble 一致)。每 300ms 把缓冲内容整段推送(`UpdateStreamContent` 为替换语义);`holdbackCutoff` 会扣住跨分片边界的不完整 `provider://` URL、Markdown 图片、XML 标签,避免闪烁半截内容。最终 `FinalizeStream` 只保留答案文本(`StripThinkBlocks`),并把 `<kb/>`、`<web/>` 引用标签与 `<image>` XML 清洗掉、`provider://` 存储 URL 重写为可访问链接(`cleanIMContent` / `rewriteStorageURLs`)。
- **流式收尾**:Agent 模式下,收到 `EventAgentComplete` 或 AgentQA 调用返回(以先到者为准)都会结束流式回复,避免卡片停在「生成中」;完成事件之后产生的错误仍会收集并附在最终回复中。快速问答(KnowledgeQA)的答案流是异步的,以流结束为准。飞书流式卡片在长时间问答期间保持活跃,不会被过期清理提前回收。
- **非流式路径**:渠道 `output_mode=full`、适配器不支持 `StreamSender`、或 `StartStream` 失败时,走 `runQA` 聚合完整答案后 `SendReply` 一次性发送。
- **引用消息**(`Quote`,目前由 WeCom 长连接适配器等填充):文本引用以 `<quoted_message>` 包裹注入 LLM 上下文(上限 500 rune,区分"引用了机器人自己的回复");引用图片/文件/视频等非文本消息时,注入的是"明确告知用户无法查看该内容"的指令,避免模型猜测无法读取的内容。
@ -265,4 +269,4 @@ imService.RegisterAdapterFactory("yunzhijia", yunzhijia.NewFactory())
- 核心框架与编排:`internal/im/`(`adapter.go`、`service.go`、`supervisor.go`、`command*.go`、`qaqueue.go`、`session/stream/think/tool_display` 等)
- 各平台适配器:`internal/im/{wecom,feishu,dingtalk,slack,telegram,mattermost,wechat,qqbot,yunzhijia}/`
- HTTP 接口层:`internal/handler/im.go`
- 路由:`internal/router/router.go` 的 `RegisterIMRoutes` / `RegisterIMChannelRoutes`
- 路由:`internal/router/routes_agent.go` 的 `RegisterIMRoutes` / `RegisterIMChannelRoutes`

View File

@ -203,7 +203,7 @@ type EmbedChannel struct {
| `name` | string | — | 渠道显示名称 |
| `enabled` | bool | `true` | 渠道开关,关闭后所有公开接口拒绝访问 |
| `agent_id` | string | `builtin-quick-answer` | 绑定的 Agent,决定知识库范围与对话能力 |
| `allowed_origins` | string[] | — | **必填至少一项,填写嵌入宿主 A,不是 WeKnora 地址 B**。支持三种形式:完整 `http(s)://` Origin、子域名通配 `*.example.com`、全通配 `*`(仅开发模式允许,生产环境拒绝) |
| `allowed_origins` | string[] | — | **必填至少一项,填写嵌入宿主 A,不是 WeKnora 地址 B**。支持三种形式:完整 `http(s)://` Origin(不含路径、查询参数)、子域名通配 `*.example.com`(只匹配子域,不含 `example.com` 本身;未写端口时匹配任意端口)、全通配 `*`(`GIN_MODE=release` 时拒绝保存,仅供开发) |
| `welcome_message` | string | 空 | 打开挂件时的欢迎语 |
| `rate_limit_per_minute` | int | `30` | 单 IP 每分钟请求上限 |
| `rate_limit_per_day` | int | `10000` | 渠道级每日请求总量上限 |
@ -220,7 +220,7 @@ type EmbedChannel struct {
### 管理 API(需登录鉴权)
由 `RegisterEmbedChannelRoutes`(`internal/router/router.go`)注册,支持 API Key 的 `ManageChannels` 能力:
由 `RegisterEmbedChannelRoutes`(`internal/router/routes_agent.go`)注册,支持 API Key 的 `ManageChannels` 能力:
| 方法 | 路径 | 权限 | 说明 |
| --- | --- | --- | --- |
@ -320,7 +320,8 @@ sequenceDiagram
| 匿名会话/Token | `internal/application/service/embed_session.go` |
| Webhook 分发 | `internal/application/service/embed_webhook.go` |
| 鉴权中间件 | `internal/middleware/embed_auth.go` |
| 路由注册 | `internal/router/router.go`(`RegisterEmbedPublicRoutes` / `RegisterEmbedChannelRoutes`) |
| 路由注册 | `internal/router/routes_agent.go`(`RegisterEmbedPublicRoutes` / `RegisterEmbedChannelRoutes` / 嵌入页 CSP 策略) |
| 宿主来源规则 | `internal/embedpolicy/origin.go` |
| 挂件加载器(SDK) | `frontend/public/weknora-widget.js` |
| 嵌入页 SPA 入口 | `frontend/src/embed-main.ts`、`frontend/src/composables/useEmbedBridge.ts`、`useEmbedChatSession.ts` |
| 数据库迁移 | `migrations/versioned/000060_embed_channels.up.sql` |

View File

@ -27,11 +27,11 @@ Wiki 生成会增加模型调用,用量取决于文档规模和抽取密度。
在 Wiki 页面中编辑正文后,可查看版本历史并比较改动。历史记录区分自动生成、智能体、人工编辑和回滚来源。回滚会以所选历史内容创建新版本,版本号继续递增。
系统优先清理自动生成的旧版本:达到 50 个历史版本后清理可裁剪快照,达到 200 个时按硬上限清理全部来源。需要长期保存的内容应另行归档。
系统优先清理自动生成的旧版本:达到 50 个历史版本后清理可裁剪快照,达到 200 个时按硬上限清理全部来源。需要长期保存的内容应另行归档。升级前写入的版本或已被清理的版本没有快照:选中这类版本时历史面板显示提示而不是差异;对比基线缺失时直接展示所选版本的全文。其他版本的比较和回滚不受影响。
## 查看变更与生成状态
页面创建、更新、删除和批量生成的操作记录统一显示在「知识库 → 设置 → 活动」。文档处理期间可查看索引状态;服务重启后,系统会恢复持久化的待处理 Wiki 任务。接口兼容与恢复机制见参考部分。
页面创建、更新、删除和批量生成的操作记录统一显示在「知识库 → 设置 → 活动」。文档处理期间可查看索引状态;服务重启后,系统会恢复持久化的待处理 Wiki 任务。删除知识库时,其 Wiki 页面、目录、问题和版本历史一并清理。接口兼容与恢复机制见参考部分。
## 版本与运行参考
@ -90,9 +90,17 @@ Wiki 曾经维护一份独立的操作日志(`wiki_log_entries` 表 + `GET /wi
`internal/container/recover_pending_wiki_tasks.go` 在服务启动时闭合 Lite 模式(进程内 `SyncTaskExecutor`)或 Redis 入队中断留下的缺口:
1. 扫描持久化的 `task_pending_ops` 表中 `scope = knowledge_base` 且 `task_type ∈ {wiki:ingest, wiki:finalize}` 的待处理组合;
2. 清理已删除 KB 的残留行(fail-closed);
2. 清理已删除 KB 或所属租户已被删除的残留行(fail-closed);
3. 对每个活跃 KB 重新入队触发任务:`wiki:ingest` 不带 TaskID(允许多批并发),`wiki:finalize` 使用 `"wiki-finalize-" + KB_ID` 去重(同一 KB 只保留一个 finalize)。重复入队无害——ingest 认领互不相交的行,finalize 在 lane 内合并。
运行期间的其他保护:
- **租户已删除**:ingest / finalize 任务在调用模型前检查租户是否存活,租户已删除则丢弃该知识库的队列,不再产生模型请求;
- **Wiki 无法运行**:触发时发现知识库已关闭 Wiki、没有合成模型或模型已被删除,会清空尚未认领的 ingest 操作并释放对应文档,文档不会一直停在「索引中」;
- **触发任务丢失**:只有持久化操作、没有触发任务的知识库由后台巡检重新触发,每个知识库每个巡检阈值周期最多一次;
- **瞬时错误重试**:模型调用遇到 408/429/5xx、超时、连接重置,或带有限流字样(如「调用频率超限」、`rate limit`)的 403 时按指数退避重试;鉴权类 403 不重试;
- **失败次数优先级**:认领待处理文档时优先处理失败次数少的文档,反复失败的文档不会阻塞新文档。
## 页面与接口参考
### 页面模型与层级
@ -119,7 +127,8 @@ migration `000061_wiki_page_hierarchy.up.sql` 引入独立的 `wiki_folders` 表
- `WikiFolder` 以 `ParentID`(空串代表根)+ 物化 `Path`(`/` 连接的名称链)组织树;空文件夹可独立存在,用户可以先搭好骨架;
- `WikiPage.FolderID` 是页面归属的**唯一事实来源**(FK → `wiki_folders.id`,空串表示 wiki 根);
- 页面上的 `CategoryPath` / `WikiPath` / `Depth` / `SortOrder` 是从 folder 链派生的**缓存投影**;
- 目录最深 3 级(常量 `WikiCategoryMaxDepth = 3`),`CleanWikiCategoryPath()` 会规范化全角分隔符(`/`、`|` → `/`)并剔除类型标签。
- 模型生成的分类路径最深 3 级(常量 `WikiCategoryMaxDepth = 3`),`CleanWikiCategoryPath()` 会规范化全角分隔符(`/`、`|` → `/`)并剔除「实体」「概念」等类型标签;
- 页面放入用户建立的文件夹时,文件夹路径原样作为分类路径,名为「概念」「Concepts」等的文件夹不会被当作类型标签剔除。
#### 关键字段
@ -130,7 +139,7 @@ migration `000061_wiki_page_hierarchy.up.sql` 引入独立的 `wiki_folders` 表
### 发布与访问
所有 Wiki 路由挂在 `/api/v1/knowledgebase/:kb_id/wiki` 之下(`internal/router/router.go`),**没有免登录的公开访问模式**,读写均受 RBAC 与 KB 访问控制约束:
所有 Wiki 路由挂在 `/api/v1/knowledgebase/:kb_id/wiki` 之下(`internal/router/routes_knowledge.go`),**没有免登录的公开访问模式**,读写均受 RBAC 与 KB 访问控制约束:
#### 读接口(Viewer + KBAccessRead)
@ -211,7 +220,14 @@ TypeWikiFinalize = "wiki:finalize"
辅助提示词:
- `WikiTaxonomyPlanPrompt`:为同一批次的所有实体/概念统一规划目录路径(最多 2 级、优先复用已有文件夹),保证目录树连贯;
- `WikiDeduplicationPrompt`:判断新抽取项是否与既有页面同指一物,核心原则是 **"related ≠ same"**(相关不等于相同),返回 `{ merges: { "entity/new": "entity/existing" } }`。
- `WikiDeduplicationPrompt`:判断新抽取项是否与既有页面同指一物,核心原则是 **"related ≠ same"**(相关不等于相同),返回 `{ merges: { "entity/new": "entity/existing" } }`。名称与别名双向比对(名称对别名、别名对别名),但共享的别名或缩写本身不足以判定为同一事物。
去重与写入的其他规则:
- **同名跨类型复用**:重新解析时模型可能把同一事物先判为 `concept/X`、后判为 `entity/X`。没有同类型页面时,标题归一化后相同的另一类型页面会被直接更新,而不是再建一个孪生页面;
- **引用图片带说明**:Reduce 阶段读取被引用分块时,会把图片的 caption / OCR 文本内联进分块内容,模型能判断图片是否与页面相关;
- **整页重写被截断**:整页重写因输出长度上限被截断时,最多续写 3 轮并无缝拼接;仍未写完则放弃本次写入并记录警告,不会把半页内容写回页面;
- **单个汉字不自动加链接**:标题只有一个汉字的页面仍可存在,但不会在其他页面正文中自动为该字添加链接,避免把「风沙」「核心」等词误链接。
#### 抽取粒度
@ -234,6 +250,8 @@ TypeWikiFinalize = "wiki:finalize"
| `IngestReduceParallel` | 10 | Reduce 阶段(每 slug 写页面)并发数 |
| `IngestMaxInflight` | 4 | 同一 KB 最大并发批次(保证跨 KB 公平) |
目录规划阶段计算文件夹与条目的 embedding 时,和其他 embedding 调用一样按 `BATCH_EMBED_SIZE` 分批请求,不会因单次输入过多被模型服务拒绝。
#### 生成流程图
```mermaid
@ -278,10 +296,10 @@ flowchart TD
| 数据结构 | `internal/types/wiki_page.go` |
| HTTP Handler | `internal/handler/wiki_page.go` |
| 生成管道 | `internal/application/service/wiki_ingest.go`、`wiki_ingest_batch.go`、`wiki_ingest_cite.go`、`wiki_ingest_dedup.go`、`wiki_ingest_taxonomy.go` |
| 页面服务 | `internal/application/service/wiki_page.go`、`wiki_linkify.go`、`wiki_lint.go`、`wiki_slug_alias.go`、`wiki_slug_handles.go` |
| 页面服务 | `internal/application/service/wiki_page.go`、`wiki_linkify.go`、`wiki_lint.go`、`wiki_slug_handles.go` |
| LLM 提示词 | `internal/agent/prompts_wiki.go` |
| Agent 工具 | `internal/agent/tools/wiki_*.go`(注册于 `internal/agent/tools/definitions.go`) |
| 失败恢复 | `internal/container/recover_pending_wiki_tasks.go` |
| 路由 | `internal/router/router.go`(行为测试见 `internal/router/router_wiki_test.go`) |
| 路由 | `internal/router/routes_knowledge.go` 的 `RegisterWikiPageRoutes`(行为测试见 `internal/router/router_wiki_test.go`) |
| 数据库迁移 | `migrations/versioned/000037_wiki_and_indexing.up.sql`、`000061_wiki_page_hierarchy.up.sql`、`000077_remove_wiki_log.up.sql` |
| 前端 | `frontend/src/views/knowledge/wiki/WikiBrowser.vue`、`frontend/src/api/wiki/`、`frontend/src/utils/wikiToolReferences.ts` |

View File

@ -10,12 +10,12 @@
## 运行一次评估
1. 准备符合下方格式的 Parquet 数据集,或使用内置 `default` 数据集。
1. 使用内置样例数据集,或按下方格式准备 Parquet 文件并替换服务工作目录下 `dataset/samples/` 中的同名文件(容器内为 `/app/dataset/samples/`)。
2. 选择参考知识库、对话模型和重排模型,通过 `POST /api/v1/evaluation` 创建任务。参考知识库用于复制配置,评估会使用单独的知识库。
3. 记录返回的任务 ID,通过 `GET /api/v1/evaluation?task_id=...` 查询状态和进度。
4. 任务成功后比较检索与生成指标;失败时先检查任务错误,再调整配置并重新运行。
创建任务需要 Admin 权限,查询结果需要 Viewer 权限;API Key 还需评估能力或 full-access。
创建任务需要 Admin 权限,查询结果需要 Viewer 权限;API Key 还需 `run_evaluations` 能力或 full-access。
## 数据集格式
@ -59,18 +59,18 @@ type QAPair struct {
}
```
自定义数据集只需按上述 Schema 生成同名 Parquet 文件。加载时服务会打印统计信息(问题数、语料数、平均相关段落数、答案覆盖率等)。
服务始终从 `./dataset/samples/` 读取这 5 个文件,`dataset_id` 目前只用于组成任务 ID,不会切换到其他目录。使用自定义数据集时,按上述 Schema 生成同名 Parquet 文件替换该目录内容(Docker 部署可挂载到 `/app/dataset/samples/`)。加载时服务会打印统计信息(问题数、语料数、平均相关段落数、答案覆盖率等)。
## 结果查询
`GET /api/v1/evaluation?task_id=evaluation-{tenant}-{dataset}`,返回 `EvaluationDetail`:
`GET /api/v1/evaluation?task_id=<创建时返回的任务 ID>`,返回 `EvaluationDetail`:
```json
{
"success": true,
"data": {
"task": {
"id": "evaluation-1-default",
"id": "evaluation_1_1758600000000_1a2b3c4d_default",
"dataset_id": "default",
"status": 2,
"total": 100,
@ -147,7 +147,7 @@ BLEU 核心(`metric/bleu.go`):修正 n-gram 精度的加权几何平均乘
### API
`internal/router/router.go`:
`internal/router/routes_infra.go`:
```go
evaluationRoutes := g.apiKeyGroup(r.Group("/evaluation"), apiKeyRunEvaluations(apiKeyFullAccess()))
@ -159,7 +159,7 @@ evaluationRoutes := g.apiKeyGroup(r.Group("/evaluation"), apiKeyRunEvaluations(a
| 方法 | 路径 | 权限 | 说明 |
| --- | --- | --- | --- |
| POST | `/api/v1/evaluation` | Admin(API Key 需 `RunEvaluations` 能力) | 创建评估任务,立即返回任务信息 |
| POST | `/api/v1/evaluation` | Admin(API Key 需 `run_evaluations` 能力或 full-access) | 创建评估任务,立即返回任务信息 |
| GET | `/api/v1/evaluation?task_id=...` | Viewer | 查询任务状态、进度与指标结果 |
#### 创建评估任务
@ -177,12 +177,12 @@ type EvaluationRequest struct {
| 参数 | 必填 | 默认行为 |
| --- | --- | --- |
| `dataset_id` | 否 | 缺省使用内置 `default` 数据集(`dataset/samples/`) |
| `dataset_id` | 否 | 缺省为 `default`;仅用于任务 ID,数据始终读取 `dataset/samples/` |
| `knowledge_base_id` | 否 | 未提供则新建评估专用知识库;提供则复制其配置创建评估 KB |
| `chat_id` | 否 | 缺省自动选择默认 Chat 模型 |
| `rerank_id` | 否 | 缺省自动选择默认 Rerank 模型 |
任务 ID 格式为 `evaluation-{tenantID}-{datasetID}`。任务对象(`internal/types/evaluation.go`):
任务 ID 由 `utils.GenerateTaskID` 生成,格式为 `evaluation_{tenantID}_{毫秒时间戳}_{8 位随机串}_{datasetID}`,每次创建都不同,应以创建响应中的 ID 查询。任务对象(`internal/types/evaluation.go`):
```go
type EvaluationTask struct {
@ -259,7 +259,7 @@ type MetricInput struct {
flowchart TD
A["POST /api/v1/evaluation<br/>(dataset_id, knowledge_base_id, chat_id, rerank_id)"] --> B["创建评估专用知识库<br/>(新建或克隆参考 KB 配置)"]
B --> C["装配 ChatManage 评估参数<br/>(阈值 / TopK / Summary 配置)"]
C --> D["注册任务到内存存储<br/>ID = evaluation-{tenant}-{dataset}, 状态 Pending"]
C --> D["注册任务到内存存储<br/>ID = evaluation_{tenant}_{时间戳}_{随机串}_{dataset}, 状态 Pending"]
D --> E["立即返回任务信息"]
D --> F["goroutine 后台执行, 状态 Running"]
F --> G["加载 Parquet 数据集<br/>queries / corpus / qrels / answers / qas"]
@ -282,7 +282,7 @@ flowchart TD
| 评估服务 | `internal/application/service/evaluation.go` |
| 指标注册与汇聚 | `internal/application/service/metric_hook.go` |
| 指标实现 | `internal/application/service/metric/`(`precision.go`、`recall.go`、`ndcg.go`、`mrr.go`、`map.go`、`bleu.go`、`rouge.go`、`rouge_score.go`、`common.go`) |
| 数据集加载 | `internal/application/service/dataset.go`、`internal/handler/dataset.go` |
| 数据集加载 | `internal/application/service/dataset.go` |
| 类型定义 | `internal/types/evaluation.go`、`internal/types/dataset.go` |
| 内置样例数据集 | `dataset/samples/`(Parquet 文件) |
| 路由注册 | `internal/router/router.go` 的 `RegisterEvaluationRoutes` |
| 路由注册 | `internal/router/routes_infra.go` 的 `RegisterEvaluationRoutes` |

View File

@ -106,7 +106,7 @@ return &lumberjack.Logger{
#### 导出器(`exporter.go`) {#_3-2-导出器-exporter-go}
OTLP/HTTP exporter,`Authorization: Basic base64(public:secret)`;`x-langfuse-ingestion-version: 4` 是 Langfuse v3/LiteFuse OTel 直写路径的必需门槛头(缺失会返回 400),`x-langfuse-sdk-name/version` 为兼容标记。`Manager`(`manager.go`)持有独立的 `TracerProvider`(`service.name=weknora` resource),不调用 `otel.SetTextMapPropagator` 等全局 OTel 变更,避免影响进程内其他 OTel 埋点;W3C `TraceContext` propagator 为包级私有值。
OTLP/HTTP exporter,`Authorization: Basic base64(public:secret)`;该 exporter 使用自己的 HTTP 客户端,不经过 SSRF 防护,开启 `SSRF_DNS_WHITELIST_ONLY` 后也不受白名单约束;`x-langfuse-ingestion-version: 4` 是 Langfuse v3/LiteFuse OTel 直写路径的必需门槛头(缺失会返回 400),`x-langfuse-sdk-name/version` 为兼容标记。`Manager`(`manager.go`)持有独立的 `TracerProvider`(`service.name=weknora` resource),不调用 `otel.SetTextMapPropagator` 等全局 OTel 变更,避免影响进程内其他 OTel 埋点;W3C `TraceContext` propagator 为包级私有值。
#### 观测模型与埋点点位 {#_3-3-观测模型与埋点点位}
@ -144,7 +144,7 @@ cache_reported 与 cache_status 区分 hit、miss、unreported、unsupported,
Prompt 组装将稳定说明放在前部,动态会话内容放在后部;支持的提供商使用 cache marker。命中仍取决于提供商协议、模型及请求前缀,不保证每次请求都有缓存。排查时先对比调用用途、前缀指纹与模型,再看上报状态。
沙箱调用也有 Langfuse span,可把实例操作和工具执行耗时串到当前 trace,区分等待沙箱与等待模型。追踪开关未启用时不会向 Langfuse 导出。
沙箱调用也有 Langfuse span,可把实例操作和工具执行耗时串到当前 trace,区分等待沙箱与等待模型。沙箱后台维护(如会话回收)只在已有父 trace 时记录子 span,不会单独生成 trace;技能安装、删除与维护任务会自行开启 trace。追踪开关未启用时不会向 Langfuse 导出。
### 审计日志 {#_4-审计日志}
@ -172,7 +172,7 @@ Prompt 组装将稳定说明放在前部,动态会话内容放在后部;支
| RBAC / 成员 | `rbac.member_added`、`rbac.member_removed`、`rbac.member_role_changed`、`rbac.member_left`、`rbac.access_denied`、`rbac.invitation_sent`、`rbac.invitation_accepted`、`rbac.invitation_declined`、`rbac.invitation_revoked`、`rbac.invitation_expired` |
| 向量库 | `vector_store.created`、`vector_store.updated`、`vector_store.deleted` |
| OpenSearch 派生资源 | `opensearch.index_created`、`opensearch.index_deleted`、`opensearch.reindex_executed` |
| 系统管理(tenant_id=0) | `system.setting_changed`、`system.admin_promoted`、`system.admin_revoked`、`system.user_password_reset`、`system.api_key_created`、`system.api_key_revoked` |
| 系统管理(tenant_id=0) | `system.setting_changed`、`system.admin_promoted`、`system.admin_revoked`、`system.user_created`、`system.user_password_reset`、`system.api_key_created`、`system.api_key_revoked` |
| 运行时队列操作(tenant_id=0) | `system.queue_task_retried`、`system.queue_task_deleted`、`system.queue_task_run_now`、`system.queue_task_cancelled`、`system.queue_archived_purged` |
| 知识库 | `kb.created`、`kb.updated`、`kb.deleted`、`kb.duplicated`、`kb.clone_started`、`kb.clone_completed`、`kb.clone_failed`、`kb.share_added`、`kb.share_permission_changed`、`kb.share_removed` |
| 知识 | `knowledge.created`、`knowledge.updated`、`knowledge.deleted`、`knowledge.batch_deleted`、`knowledge.reparse_started`、`knowledge.parse_canceled`、`knowledge.move_started`、`knowledge.move_completed`、`knowledge.move_failed` |
@ -217,9 +217,10 @@ Prompt 组装将稳定说明放在前部,动态会话内容放在后部;支
该文件提供的是**模型引用(usage-by-reference)查询**,即回答"哪些资源正在使用某个模型",用于删除模型前的依赖保护,而非 token 用量计费:
- `scopeKnowledgeBasesByModelID`:匹配 `knowledge_bases` 中任一模型绑定字段 —— `embedding_model_id`、`summary_model_id`、`image_processing_config.model_id`、`vlm_config.model_id`、`asr_config.model_id`、`wiki_config.synthesis_model_id`(Postgres 用 `->>` JSON 操作符,SQLite 用 `json_extract`,双方言等价)。
- `scopeKnowledgeBasesByModelID`:匹配 `knowledge_bases` 中任一模型绑定字段 —— `embedding_model_id`、`summary_model_id`、`image_processing_config.model_id`、`vlm_config.model_id`、`asr_config.model_id`、`wiki_config.synthesis_model_id`、`auto_tag_config.model_id`(Postgres 用 `->>` JSON 操作符,SQLite 用 `json_extract`,双方言等价)。
- `scopeCustomAgentsByModelID`:匹配 `custom_agents.config` 中的 `model_id`、`rerank_model_id`、`vlm_model_id`、`asr_model_id`、`query_understand_model_id`、`question_suggestions.follow_ups.model_id`。
- 消费方:`knowledgebase.go` / `custom_agent.go` 仓储的 `ListModelUsages` 复用上述 scope,返回租户内活动对象的最小投影(`id`、`name`、合并后的 `bindings`),条数上限为 `ModelUsageListLimit`(50)。`internal/application/service/model.go` 的删除守卫以 `CountByModelID` 得到的 `knowledge_base_total` / `agent_total` 为是否拦截的依据,并在 HTTP 400 的 `error.details` 中同时返回截断列表和总数。
- 空间长期记忆配置:`memory_config` 的 `extract_model_id` 与 `embedding_model_id` 也算引用,出现在 `long_term_memory.bindings` 中。
- 消费方:`knowledgebase.go` / `custom_agent.go` 仓储的 `ListModelUsages` 复用上述 scope,返回租户内活动对象的最小投影(`id`、`name`、合并后的 `bindings`),条数上限为 `ModelUsageListLimit`(50)。`internal/application/service/model.go` 的删除守卫以 `knowledge_base_total` / `agent_total` 与长期记忆绑定为是否拦截的依据,并在 HTTP 400 的 `error.details` 中同时返回截断列表、总数和 `long_term_memory`。
token 级别的模型用量则由 Langfuse Generation 的 `usage_details`(`TokenUsage`:input/output/total/cache_*)上报,在 Langfuse UI 中按模型 / 用户(`tenant:<id>`)/ 会话聚合查看。

View File

@ -38,7 +38,7 @@ type FAQBatchUpsertPayload struct {
Entries []FAQEntryPayload `json:"entries" binding:"required"` // 也可经 EntriesURL 从对象存储拉取
Mode string `json:"mode" binding:"oneof=append replace"`
KnowledgeID string `json:"knowledge_id"`
TaskID string `json:"task_id"` // 可选,不传自动生成 UUID
TaskID string `json:"task_id"` // 可选,不传自动生成;自定义值仅允许 [A-Za-z0-9_-],≤128 字符
DryRun bool `json:"dry_run"` // 仅验证不落库
}
```
@ -153,11 +153,11 @@ type FAQEntry struct {
### API 端点 {#_2-api-端点}
`internal/handler/faq.go`(路由注册于 `internal/router/router.go`,KB 门禁与知识库一致:读走 KBAccessRead,写走 KBAccessWrite;API Key 需 `ingest` / `retrieve` 能力):
`internal/handler/faq.go`(路由注册于 `internal/router/routes_knowledge.go`,KB 门禁与知识库一致:读走 KBAccessRead,写走 KBAccessWrite;API Key 需 `ingest` / `retrieve` 能力):
| 方法 | 路径 | 功能 |
| --- | --- | --- |
| GET | `/knowledge-bases/:id/faq/entries` | 条目列表(分页 / 标签 / 关键词) |
| GET | `/knowledge-bases/:id/faq/entries` | 条目列表(分页 / 标签 / 关键词 / 启用状态) |
| GET | `/knowledge-bases/:id/faq/entries/:entry_id` | 单条详情 |
| POST | `/knowledge-bases/:id/faq/entry` | 同步创建单条 |
| PUT | `/knowledge-bases/:id/faq/entries/:entry_id` | 更新单条(增量索引) |
@ -171,7 +171,7 @@ type FAQEntry struct {
| GET | `/faq/import/progress/:task_id` | 导入任务进度 |
| PUT | `/knowledge-bases/:id/faq/import/last-result/display` | 导入结果面板显示状态(open/close) |
列表查询参数:`page` / `page_size`、`tag_id`(单标签)或 `tag_ids`(逗号分隔,OR 语义)、`keyword` + `search_field`(`standard_question` / `similar_questions` / `answers`,缺省搜全部)、`sort_order`(`asc`,默认倒序)。
列表查询参数:`page` / `page_size`、`tag_id`(标签 seq_id,兼容旧版单标签)或 `tag_ids`(标签 UUID,逗号分隔,OR 语义)、`keyword` + `search_field`(`standard_question` / `similar_questions` / `answers`,缺省搜全部)、`sort_order`(`asc`,默认按更新时间倒序)、`is_enabled`(`true` / `false` 按启用状态筛选,不传返回全部)。
**写入校验**(`sanitizeFAQEntryPayload` + `checkFAQQuestionDuplicate`):标准问必填;答案至少一个;`answer_strategy` 只能是 `all` / `random`(默认 `all`);相似问 / 反例 / 答案去空白去重;并做四级重复检查——相似问 vs 标准问、相似问互查、反例 vs 标准问及相似问、DB 内跨条目冲突(返回详细冲突信息)。

View File

@ -1,6 +1,6 @@
# 会话与对话体验
在会话中,可以围绕知识库或上传的附件提问,查看回答来源,并预览智能体生成的文件。问题大纲和历史搜索用于回顾已有对话,Markdown 导出用于保存完整问答记录。
在会话中,可以围绕知识库或上传的附件提问,查看回答来源,并预览智能体生成的文件。回答生成期间可以继续补充要求;对已有对话可以从任意一条消息分叉或回滚。提问目录和历史搜索用于回顾对话,复制为 Markdown 用于保存完整问答记录。
## 查看回答与来源
@ -13,7 +13,38 @@
caption="对话页:回答、引用角标与右侧引用面板"
hint="展示一轮带引用的回答、展开的引用面板(含来源标题与片段),以及顶部会话操作栏。" />
检索完成后,等待模型返回内容的阶段显示“正在生成回答”;没有执行检索的问答显示“准备中”。等待超过 60 秒时,界面会更新为长时间等待提示。这一提示反映当前等待状态,回答和工具执行结果以实际返回内容为准。
快速问答完成检索后,等待模型返回内容的阶段显示“正在连接模型并生成回答…”;没有执行检索的问答显示“正在准备回答…”。等待超过 60 秒时,提示变为“模型响应较慢,仍在等待…”。这一提示反映当前等待状态,回答和工具执行结果以实际返回内容为准。
回答达到模型单次输出上限而被截断时,回答工具栏会出现提示图标,说明以上为截断前已生成的内容。需要完整回答时,可缩小问题范围,或在智能体配置中调大最大输出长度。
## 调整思考强度
所选模型支持分档思考时,输入框底部模型选择旁会显示「思考强度」,可在关闭、自动、极低、低、中、高、极高、最大中选择该模型支持的档位。默认沿用智能体配置;改选后只对当前会话生效,不修改智能体,重新打开会话时会恢复上次的选择。切换到不支持该档位的模型时,选择自动失效。
## 在回答过程中补充要求
智能推理模式生成回答时,可以直接在输入框继续输入:
| 操作 | 效果 |
| --- | --- |
| Enter 或点击发送 | 排队,当前回答结束后作为下一轮问题发送 |
| ⌘ Enter(Mac)或 Alt + Enter | 立即补充到当前任务,智能体在下一步读取并调整 |
排队中的消息显示在输入框上方,可点击「补充当前任务」改为立即补充,或点击「移除」撤回;已被智能体接收的消息无法撤回。输入为空时,发送按钮用于停止生成;停止后,排队中的消息会一并丢弃。追加消息不能带附件或图片,可以使用 @ 提及。每轮最多排队 10 条。快速问答不支持追加,回答结束前需要等待。
<Screenshot
src="/screenshots/chat-steer-queue.png"
caption="回答生成期间,输入框上方的排队消息"
hint="智能推理回答进行中,输入框上方显示一至两条排队消息,每条带「补充当前任务」和「移除」按钮;输入框内有正在输入的文字,发送按钮提示“完成后发送 · Enter”。" />
## 分叉与回滚
用户消息下方和回答工具栏提供两个操作,回答生成期间均不可用:
- **分叉**:以当前对话为基础新建会话,原会话保持不变。从用户消息分叉时,复制该问题之前的对话,并把问题填回输入框,可修改后重新发送;从回答分叉时,复制到这条回答为止的对话。新会话标题为“原标题(分支)”,侧栏以分叉图标标记。
- **回滚**:在当前会话中删除所选消息之后的对话,操作不可撤销。从用户消息回滚时,该问题本身也会删除并填回输入框。被删除轮次生成的文件、追问建议和历史搜索索引同时清理。
智能体绑定沙箱时,系统在每轮回答结束后记录工作区检查点。分叉会带上分叉点对应的工作区文件;无法带上时(如沙箱已回收或更换),分叉仍会成功,新会话使用全新的沙箱。回滚会把工作区一并退回到保留的最后一轮;当前沙箱找不到对应检查点时,为避免文件与对话不一致,回滚会被拒绝。没有沙箱,或使用桌面版本机目录作为工作区时,只回滚对话,不改动文件。
## 使用临时附件提问
@ -27,21 +58,37 @@
## 预览和下载生成文件
绑定沙箱的智能体可以处理附件并生成文件。回答完成后,本轮生成的文件显示在回答下方,也可在会话文件面板中集中查看。支持的文件类型可以直接预览,其余文件可下载后打开。
绑定沙箱的智能体可以处理附件并生成文件。回答完成后,点击回答工具栏的「查看本次生成的文件」,或对话页右上角的沙箱按钮,在「沙箱可视化」面板的「产物」页签中查看;该页签可切换本轮或全部文件,并按文件名搜索。支持的文件类型可以直接预览,其余文件可下载后打开。
侧栏的「产物」页汇总当前用户各网页会话中生成的文件,可按文档、表格、演示文稿、图片、网页、数据分类筛选或按文件名搜索,并可预览、下载、跳转到所在会话。同一会话中同名路径的文件多次生成时只显示最新一版,并标出版本数。部署未启用沙箱能力时不显示该页。
<Screenshot
src="/screenshots/artifacts-library.png"
caption="「产物」页:汇总各会话生成的文件"
hint="侧栏选中「产物」,页面顶部为类型页签(全部/文档/表格/演示文稿/图片/网页/数据)和文件名搜索框,列表按今天/昨天/最近 7 天分组,至少一行显示“N 个版本”,行内可见预览、下载、删除操作。" />
需要让智能体生成可下载文件时,产物应保存到 `/workspace/output`,系统会在回答结束时收集并持久化。上传的附件暂存于 `/workspace/input`,脚本和中间文件可放在 `/workspace` 的其他目录。输入附件和输出文件分别管理,删除输入附件不会自动删除已收集的输出文件。
不再需要的文件可以在会话文件面板或「产物」页删除。删除会回收存储中的字节,无法恢复,因此会先确认;只有会话归属人能删除,通过共享智能体获得的只读访问只能下载。会话文件面板按每次生成分别列出,删除的是点击的那一版;「产物」页一行代表一个文件(带版本数),删除会连同该文件在这个会话中的所有历史版本。同一份文件如果已被存入知识库或被后续回答重新引用,那些位置不受影响。删除后沙箱里的同名文件也不会被重新收录。
不再需要的文件可以在「产物」页签或「产物」页删除。删除会回收存储中的字节,无法恢复,因此会先确认;只有会话归属人能删除,通过共享智能体获得的只读访问只能下载。「产物」页签按每次生成分别列出,删除的是点击的那一版;「产物」页一行代表一个文件,删除会连同该文件在这个会话中的所有历史版本。同一份文件如果已被存入知识库、被后续回答重新引用或随会话分叉复制,那些位置不受影响。删除后沙箱里的同名文件也不会被重新收录。
文件读取、脚本执行和目录约定见[技能与沙箱](22-skills-sandbox.md);列表、下载与删除接口见[会话与聊天 API](../04-api/02-api-chat.md)。
## 把回答存入知识库
回答工具栏的「添加到知识库」会在右侧抽屉打开 Markdown 编辑器,预填问题与回答,引用的文档统一列在末尾的“参考来源”下。选择目标知识库(仅文档型知识库)后,可暂存草稿或发布入库;发布后开始索引。编辑器支持编辑、分屏、预览三种视图和全屏,工具栏提供常用格式与插入表格、代码块、图片等操作,Cmd/Ctrl + S 暂存,Cmd/Ctrl + Enter 发布。
<Screenshot
src="/screenshots/chat-save-answer-editor.png"
caption="把回答存入知识库的 Markdown 编辑器"
hint="对话页右侧抽屉处于分屏视图:顶部为标题输入框与目标知识库选择器,中部左侧 Markdown 源码、右侧预览,底部显示“当前状态:草稿”、字数统计和「暂存草稿」「发布入库」按钮。" />
## 回顾和导出对话
长对话中的问题大纲可直接定位到某次提问,时间分隔用于区分不同日期的消息。侧栏标记仍在执行的会话,并显示 API 会话的来源和归属。
长对话右侧的提问目录可直接定位到某次提问,悬停时显示轮次、问题和回答摘要。消息之间在日期变化或间隔 5 分钟以上时插入时间分隔;用户消息下方显示发送时间,今天的消息只显示时刻,更早的消息带日期。侧栏以旋转图标标记本浏览器中仍在生成的会话,并为 API 会话标出调用方。
会话操作栏支持导出 Markdown,内容包括会话标题、ID、导出时间和逐轮问答。导出在浏览器中完成,可用于归档或分享对话记录。
会话操作菜单的「复制为 Markdown」把完整对话复制到剪贴板,内容包括会话标题、ID、导出时间和逐轮问答(含附件与引用列表)。复制在浏览器中完成,可用于归档或分享对话记录。
启用聊天历史索引后,可以跨会话搜索已有消息。空间管理员在“设置 → 聊天历史”配置索引开关与保留策略。
侧栏「搜索」可跨会话查找历史消息。空间管理员在「系统设置 → 空间 → 消息管理」启用消息索引并选择 Embedding 模型后,搜索会同时使用语义匹配;未启用时按关键词匹配。
## 查看渠道会话
@ -51,7 +98,7 @@ IM、网页嵌入和 API 调用产生的会话,分别按 IM 身份、访客或
## 使用跨会话记忆
空间启用长期记忆后,可以在个人记忆管理中维护表达偏好、确认待确认条目,并在后续会话中使用。记忆按空间和调用者身份隔离。
空间管理员在「系统设置 → 空间 → 长期记忆」启用后,成员可以在「系统设置 → 账户 → 我的记忆」维护表达偏好、确认待确认条目,并在后续会话中使用。记忆按空间和调用者身份隔离。
关闭个人记忆会暂停使用,删除或清空则用于移除数据。自动提取、主题管理和立即整理的说明见[长期记忆](23-memory.md)。
@ -82,6 +129,17 @@ IM、网页嵌入和 API 调用产生的会话,分别按 IM 身份、访客或
完整参数和权限见[会话与聊天 API](../04-api/02-api-chat.md)。
### 会话操作接口
| 操作 | 方法与路径 |
| --- | --- |
| 分叉 | `POST /api/v1/sessions/:session_id/fork` |
| 回滚 | `POST /api/v1/sessions/:session_id/rewind` |
| 运行中追加消息 | `POST /api/v1/sessions/:session_id/steer`,另有列出、撤回、改为立即补充 |
| 本轮思考强度 | 聊天请求的 `reasoning_effort` 字段 |
请求体、返回码与限制见[会话与聊天 API](../04-api/02-api-chat.md)。
### 引用和历史查询
智能体的 `citation_enabled` 控制回答正文中的引用角标,省略时默认开启;引用面板不受该字段影响。
@ -93,7 +151,9 @@ IM、网页嵌入和 API 调用产生的会话,分别按 IM 身份、访客或
## 实现参考
- `frontend/src/views/chat/components/`:回答、进度与工具过程展示。
- `frontend/src/utils/sessionMarkdown.ts`:Markdown 导出。
- `frontend/src/utils/sessionMarkdown.ts`:复制为 Markdown。
- `internal/application/service/session.go`:会话列表与渠道访问规则。
- `internal/application/service/session_fork.go`、`session_rewind.go`、`workspace_checkpointer.go`:分叉、回滚与工作区检查点。
- `internal/handler/session/steer.go`:运行中追加消息。
- `internal/application/service/temporary_document.go`:临时附件解析、到期与清理。
- 临时附件存储在 `temporary_documents` 表,表结构见[数据库与迁移](../06-development/02-database-schema.md)。

View File

@ -17,13 +17,34 @@
空间 Admin 可在「设置 → 存储」注册和管理实例:
1. 新建后端,选 provider(`local` / `minio` / `cos` / `oss` / `s3` / `tos` / `obs` 等,与[文档入库流程](../02-architecture/03-document-pipeline.md)里的存储 provider 一致),填连接参数;
1. 新建后端,选 provider(`local` / `minio` / `cos` / `tos` / `s3` / `oss` / `ks3` / `obs`,与[文档入库流程](../02-architecture/03-document-pipeline.md)里的存储 provider 一致),填连接参数(见下表)。可选列表受环境变量 `STORAGE_ALLOW_LIST` 限制,留空表示全部可选;
2. **测试连接**:测试会实际读写存储,验证端点、存储桶和凭据;
3. 将实例设为空间默认。新建知识库未指定实例时使用该默认值;
4. 需要单独指定时,在知识库编辑弹窗的「存储」页签选择实例。
知识库为空时可修改存储后端;已有文件时,界面会禁用选择并提示迁移。文件路径依赖入库时的后端,直接更换会影响原文件访问。需要更换时,应新建知识库并迁移内容。
## 连接参数 {#连接参数}
各 provider 共用一组配置字段,`access_key_id` / `secret_access_key` 加密保存,接口响应中掩码显示。
| 名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `endpoint` | string | 空 | 服务地址。`minio`(`mode=remote`)、`tos`、`s3`、`oss`、`ks3`、`obs` 必填;`cos` 不需要。保存时做 SSRF 校验,内网地址需加入 `SSRF_WHITELIST` |
| `region` | string | 空 | 地域。`cos`、`tos`、`s3`、`oss`、`ks3`、`obs` 必填 |
| `access_key_id` / `secret_access_key` | string | 空 | 访问密钥;COS 对应 SecretId / SecretKey。`local` 与 `mode=docker` 的 MinIO 不需要 |
| `bucket_name` | string | 空 | 存储桶,除 `local` 外必填 |
| `path_prefix` | string | 空 | 对象键前缀,必须是相对路径,不能以 `/` 开头或包含 `..` |
| `mode` | string | `remote` | 仅 MinIO:`docker` 使用部署自带的 MinIO(地址与密钥读取 `MINIO_ENDPOINT` 等环境变量),`remote` 连接外部 MinIO |
| `use_ssl` | bool | false | MinIO、S3、OBS 是否使用 HTTPS |
| `force_path_style` | bool | false | 仅 S3:使用 path-style 寻址,多数 S3 兼容服务需要开启 |
| `app_id` | string | 空 | 仅 COS:腾讯云 AppID |
| `temp_bucket_name` / `temp_region` | string | 空 | 仅 COS、TOS、OSS:临时文件使用的存储桶与地域;OSS 另需 `use_temp_bucket=true` 启用 |
- **OBS**:endpoint 为域名时使用虚拟主机寻址(`<bucket>.<endpoint>`),华为云自 2023-12-30 起拒绝域名 endpoint 的 path-style 请求;endpoint 为 IP 时仍用 path-style。未配置代理域名时,文件 URL 形如 `<scheme>://<bucket>.<endpoint-host>/<key>`。
- **传输超时**:S3、COS、KS3、OBS、OSS 的单次上传/下载不再受 30 秒整体超时限制,改为单次传输最长 30 分钟;建连、TLS 握手和等待响应头仍有各自的超时,对端失联时会较快失败。
- **KS3 重定向**:跟随重定向时逐跳做 SSRF 校验,不再把请求签名转发到重定向目标主机。
## 与向量存储的区别
文件存储和向量存储分别管理原文件与检索索引:
@ -39,7 +60,7 @@
| 方法 | 路径 | 权限 |
| --- | --- | --- |
| GET | `/storage-backends/types` | Viewer+,返回支持的 provider 及其字段定义 |
| GET | `/storage-backends/types` | Viewer+,返回 `STORAGE_ALLOW_LIST` 允许的 provider 名称列表 |
| GET | `/storage-backends`、`/storage-backends/:id` | Viewer+ |
| POST | `/storage-backends` | Admin+ |
| PUT / DELETE | `/storage-backends/:id` | Admin+ |
@ -58,8 +79,8 @@ API Key 需要 `manage_storage_backends` 能力或 full-access。
| `name` | 空间内唯一(软删除下的部分唯一索引) |
| `provider` | 存储类型 |
| `config` | JSONB,含加密后的密钥 |
| `source` | `user`(界面注册)/ 其它(系统生成) |
| `status` | `active` / 停用 |
| `source` | `user`(界面或 API 注册)/ `env`(由环境变量配置生成) |
| `status` | `active` / `disabled` |
| `legacy_alias` | 见下 |
`legacy_alias` 用于兼容环境变量配置的历史存储。升级时创建别名记录,使已有文件路径继续可解析,无需搬迁数据。同一空间、同一 provider 只允许一条别名记录,手动注册的实例独立保存。

View File

@ -48,9 +48,14 @@
### 创建用户
系统管理员可在系统设置中创建本地账号,填写用户名、邮箱,并选择自动生成密码或指定符合策略的密码。空间分配遵循 `auth.default_tenant_mode`:`create_personal` 创建个人空间,`tenantless` 等待用户加入空间。
自 v0.8.2 起,系统管理员可在「设置 → 系统设置 → 账户与访问」中点击「创建用户」开通本地账号:填写用户名(2–50 字符)和邮箱,保持「自动生成随机密码」开启,或关闭后手动填写符合密码策略的密码。适用于关闭公开注册后由管理员统一开户的场景。空间分配遵循 `auth.default_tenant_mode`:`create_personal` 创建个人空间,`tenantless` 等待用户加入空间。
自动生成的密码仅在本次创建结果显示,应当场复制完整账号信息;关闭结果后不能再次查询明文。重复身份返回已有用户,不改密码;邮箱和用户名分别指向不同用户时拒绝创建。接口见[系统 API](../04-api/02-api-system.md)。
<Screenshot
src="/screenshots/system-admin-create-user.png"
caption="系统管理员创建用户:填写账号信息与一次性密码展示"
hint="「设置 → 系统设置 → 账户与访问」下打开「创建用户」对话框,展示用户名、邮箱与「自动生成随机密码」开关;可另附创建成功后显示一次性密码和「复制账号信息」按钮的结果页。" />
自动生成的密码仅在本次创建结果显示,应当场复制完整账号信息;确认前对话框不能关闭,关闭后不能再次查询明文。每次创建都会写入系统审计日志(`system.user_created`)。重复身份返回已有用户,不改密码;邮箱和用户名分别指向不同用户时拒绝创建。接口见[系统 API](../04-api/02-api-system.md)。
创建用户与首个管理员引导是不同操作:bootstrap 仍只提升已存在用户,不负责创建账号。

View File

@ -80,6 +80,7 @@ API 默认返回 `resource://`,客户端通过鉴权代理获取文件。需
| 加了 `resource_urls=public` 返回 403 | 用的是限定知识库的 API Key | 改用 `handle` 模式,或使用已获授权的 full-access Key |
| 嵌入挂件里图片不显示,但网页端正常 | 挂件走的是渠道代理,与主站凭证不同 | 确认挂件页面带着有效 Embed token;`resource_urls=public` 对嵌入渠道无效 |
| 共享回答里的图片 403/404 | 消息上下文缺失、资源未绑定或共享已撤销 | 使用消息级代理并检查当前共享权限;不要拼属主租户的 /files 地址 |
| 升级或更换密钥后已发出的链接失效 | 签名密钥(`SYSTEM_SIGNING_KEY`,或回退使用的 `SYSTEM_AES_KEY`)变化后旧签名无法校验 | 重新获取链接;多副本部署确认所有实例使用同一密钥 |
| 外链过一段时间失效 | 外链是限时的(grant 2 小时 / MinIO 预签名 24 小时) | 不要缓存外链本身,需要时重新取;同一文件在有效期内会复用同一链接 |
| 网页端图片 404,日志显示租户不匹配 | 跨租户共享库的图存在属主租户下 | 该场景应走 `/api/v1/knowledge-bases/:id/files`,确认前端拿到的是 KB 维度的代理地址 |
@ -90,7 +91,7 @@ API 默认返回 `resource://`,客户端通过鉴权代理获取文件。需
| `APP_EXTERNAL_URL` | IM 渠道图片外链的外部可达地址;`resource://` 改写成 `<APP_EXTERNAL_URL>/r/<token>` 的前提 |
| `RESOURCE_URL_MODE` | API 响应里文件引用的默认形式(`handle` / `public`) |
| `MINIO_ENDPOINT` 等存储 endpoint | 设为公网地址时,外链可由存储预签名提供,不必依赖 `APP_EXTERNAL_URL` |
| `SYSTEM_AES_KEY` | 建议配置:可复用 grant 行、稳定直链 URL,并降低读接口的写入压力 |
| `SYSTEM_SIGNING_KEY`(未设置时回退 `SYSTEM_AES_KEY`) | 签名密钥。`/api/v1/files/presigned` 预签名链接依赖它;同时用于在有效期内复用 `/r/<token>` grant、稳定直链 URL,并降低读接口的写入压力。未配置、长度不足 16 或为示例值时无法签发预签名链接;更换后已签发的链接失效 |
## 相关文档 {#_5-相关章节}

View File

@ -6,11 +6,11 @@
1. 空间 Admin/Owner 在「设置 → 沙箱配置」创建配置,选择 Docker、CubeSandbox 或 E2B,填写连接信息。
2. 按向导连接集群、选择模板;需要验证完整链路时运行「完整验证」。完整验证会实际创建沙箱、执行探针并清理。
3. 在「设置 → 技能管理」添加 ZIP 或来源链接,再选择要安装的沙箱。目录收录成功只表示安装包已保存;安装状态就绪后才能执行。
4. 打开智能体编辑器的「技能与沙箱」,选择沙箱,设置技能范围为全部、指定技能或禁用。技能执行用于智能推理模式。
5. 进入对话提问,或用 `@技能` 提示智能体优先使用该技能。需要文件时上传附件,生成的交付文件在对话的文件面板预览、下载。
3. 在侧边栏「工具箱 → 技能管理」添加 ZIP 或来源链接,再选择要安装的沙箱(旧的「设置 → 技能管理」链接会自动跳转到这里)。目录收录成功只表示安装包已保存;安装状态就绪后才能执行。
4. 打开智能体编辑器的「技能」分区,选择沙箱,设置技能范围为全部、指定技能或禁用。技能执行用于智能推理模式。
5. 进入对话提问,或用 `@技能` 提示智能体优先使用该技能。需要文件时上传附件,生成的交付文件在对话右侧「沙箱可视化」面板的「产物」标签中预览、下载。
`@技能` 不会取消智能体对其他已授权技能的访问。未选沙箱、空间关闭脚本或所需后端能力不可用时,执行工具不会注册;提示词无法绕过这些条件。
`@技能` 不会取消智能体对其他已授权技能的访问。未选沙箱(macOS 上的 Lite 桌面版会改用[本机沙箱](#lite-host))、空间关闭脚本或所需后端能力不可用时,执行工具不会注册;提示词无法绕过这些条件。
<Screenshot
src="/screenshots/skill-catalog.png"
@ -24,7 +24,8 @@
| --- | --- |
| 添加到目录 | 保存包、名称、版本和说明,不执行安装 |
| 安装 | 在所选沙箱构建运行环境、安装依赖并校验可加载性,成功后发布新快照 |
| 重试 | 复用已保存的包再次安装;相同包已正常就绪时可跳过 |
| 重试 | 复用该沙箱已保存的包再次安装,可附带安装说明;相同包已正常就绪时可跳过 |
| 升级 | 目录重新登记新版本后,旧版本安装会标记为可升级;升级把目录中的新版本装到所选沙箱 |
| 停止安装 | 中止进行中的安装,状态变为 failed,之后可重试或卸载 |
| 停用 | 保留安装记录,只让智能体不再选用该技能 |
| 从沙箱卸载 | 更新该沙箱的技能镜像,保留目录中的安装包,便于其他沙箱继续安装 |
@ -32,6 +33,10 @@
安装页面显示百分比、阶段和日志,详细运行过程可在安装记录中查看。关闭进度抽屉或断开进度流不会停止安装。没有实时进度时可刷新技能状态;详细事件日志过期不代表技能安装包已丢失。
安装由内置安装智能体完成:它读取 `SKILL.md` 安装依赖,并核对技能需要的外部命令行工具等运行前提。缺少必需命令或存在未解决的前提(例如需要另行部署的服务)时,安装判为失败并给出原因,不会仅因为没有依赖清单就标记就绪。安装进行中,管理员可以在「安装过程」里补充安装说明,例如需要安装的 CLI、安装文档或环境限制;安装结束后也可以携带说明重新安装。
升级或重试失败时,沙箱继续提供上一个就绪版本,智能体仍可使用;新版本安装成功后才替换。
`skill_rollout` 控制镜像更新:默认 `next_turn` 在已有会话的下一轮重建沙箱;`new_session` 仅让之后创建沙箱的会话使用新镜像。沙箱重建会丢失旧实例临时运行状态,需交付的文件应写入 `/workspace/output` 并由系统收集。
### 支持的来源
@ -57,9 +62,9 @@
| Docker | 镜像;可选 daemon 地址、TLS 证书目录、CPU/内存/PID 限制、网络模式、runtime、空闲 TTL | 一个会话一个长驻容器 |
| CubeSandbox | 控制面地址、数据面代理、沙箱域名、模板;按集群配置 API Key | 会话级远端沙箱 |
| E2B | API Key、模板;自托管时补 API 地址、沙箱域名和数据面代理 | E2B Cloud 或 E2B 兼容控制面 |
| host | 不用填写。仅 Lite 桌面版,当前仅 macOS | 未选远程沙箱时,在用户选定的本机目录内执行,越界由操作系统拦截 |
| host | 不用填写。仅 Lite 桌面版,当前仅 macOS | 智能体未选沙箱配置时,在本机项目目录内执行,越界由操作系统拦截 |
`local` 宿主机进程后端已移除:它在本机裸跑,没有任何隔离。Lite 的 `host` 不属于上述空间命名配置,也不是 `local` 的替代项。`host` 由操作系统强制隔离,工作区是真实主机路径,没有 `/workspace`。用户在新对话页选择项目;不选则使用自动会话目录。配了 Docker、E2B 或 Cube 的智能体仍走远程沙箱。当前配置的完整字段见[沙箱与技能 API](../04-api/02-api-sandbox-skills.md)。
`local` 宿主机进程后端已移除:它在本机裸跑,没有任何隔离。Lite 的 `host` 不属于上述空间命名配置,也不是 `local` 的替代项。当前配置的完整字段见[沙箱与技能 API](../04-api/02-api-sandbox-skills.md)。
Docker 后端默认关闭。系统管理员在「系统设置 → 网络安全」启用,或用 `WEKNORA_SANDBOX_DOCKER_ENABLED=true` 作为未落库时的回退。本机连接还需要把实际 Docker socket 挂给 app;这授予 app 控制宿主机 Docker 的能力。远端 TCP daemon 要配置 TLS 证书目录,其中包括 `ca.pem`、`cert.pem`、`key.pem`。Docker 网络仅接受 `bridge` 或 `none`,可选 `runsc` 等已安装 OCI runtime。
@ -79,9 +84,18 @@ Cube/E2B 的 `config.network` 同时用于对话沙箱、技能安装和完整
已有实例不会因为修改策略自动获得新配置,应在新建/重建沙箱后验证。修改后端身份或删除配置前,系统会查询运行中/暂停的实例和关联智能体;存在占用时拒绝操作,设置页会展示占用信息。
### Lite 本机沙箱(host) {#lite-host}
自 v0.8.2 起,[Lite 桌面版](../05-clients/05-desktop.md)在 macOS 上用系统 Seatbelt 隔离运行智能体的命令和文件工具。智能体选了 Docker、E2B 或 Cube 配置时仍走远程沙箱;没有选沙箱配置时才使用本机沙箱。Windows 和 Linux 暂不提供该能力,此时未选配置的智能体不能执行命令。
- **工作目录**:在新对话页点「选择项目」,通过系统目录选择框选定项目文件夹,对话标题栏会显示项目名。不选时显示「临时工作区」,自动在 `~/Documents/WeKnoraLite/<日期>/session-*` 下创建会话目录。不能选择主目录本身、包含主目录的目录或 `~/Library` 下的目录。
- **路径**:工作区是真实的本机路径,没有 `/workspace`、`/workspace/input` 和 `/workspace/output`。智能体直接在项目中修改文件,这些文件不会进入对话的产物列表;删除对话也不会删除本机目录。
- **限制**:命令默认不能联网,只能写入项目目录,项目内的 `.git` 为只读。主目录中除常用开发工具链(如 `.nvm`、`.pyenv`、`.cargo`)外的内容不可读,`.ssh`、`.aws`、钥匙串等凭据位置始终不可读。
- **回退**:对话回退不会还原本机项目文件,需要时请自行用 Git 管理。
## 环境变量与凭据
个人变量入口在个人资料的环境变量设置;空间级技能变量在技能管理中配置。列表只显示变量声明、是否设置和来源,不回显秘密值。
个人变量入口在「设置 → 沙箱密钥」;空间级技能变量在「工具箱 → 技能管理」的技能卡上配置。列表只显示变量声明、是否设置和来源,不回显秘密值。
| 层级 | 作用 |
| --- | --- |
@ -104,13 +118,33 @@ Cube/E2B 的 `config.network` 同时用于对话沙箱、技能安装和完整
src="/screenshots/skill-sandbox-chat.png"
caption="沙箱生成 Word 文件后,在对话中预览并下载" />
命令执行期间,对话中的工具卡片会实时显示输出末尾几行,便于判断长命令的进度;这些中间输出不会写入模型上下文。
### 沙箱可视化面板
使用远程沙箱的对话,右侧「沙箱可视化」面板有三个标签页:
| 标签页 | 内容 | 可用条件 |
| --- | --- | --- |
| 产物 | 本轮或全部轮次生成的可下载文件,可按文件名搜索 | 所有远程沙箱 |
| 终端 | 连接本会话沙箱的交互式 Shell(xterm),刷新页面后可重新接上仍在运行的终端 | Cube、E2B;Docker 不支持 |
| 桌面 | 通过浏览器操作沙箱内的 XFCE 图形桌面,每个会话同时只允许一个连接 | Cube、E2B 的桌面模板,且配置开启 `desktop_enabled` |
打开面板不会创建或唤醒沙箱:沙箱正在运行时终端和桌面会直接连上;沙箱已暂停或尚未创建时,需要点「启动终端」「连接桌面」或「创建并启动」,唤醒或新建的沙箱会按空间配置计费。终端或桌面长时间无操作会自动断开,沙箱随后按提供商 TTL 暂停;断开时间由沙箱配置的「终端 / 桌面空闲断开(秒)」控制,默认 900 秒,范围 60 秒到 24 小时。技能更新触发沙箱重建后,原终端和桌面上未保存的内容会丢失。
<Screenshot
src="/screenshots/sandbox-panel-terminal.png"
caption="沙箱可视化面板:在对话旁查看产物、使用终端和桌面"
hint="展示一个使用 Cube 或 E2B 沙箱的对话,右侧「沙箱可视化」面板切换到「终端」标签,终端内有带颜色的 user@host 提示符和一条命令输出;面板顶部可见「产物 / 终端 / 桌面」三个标签。" />
## 部署与排障
Docker socket/TLS、模板版本、远端网关、多副本 Redis、技能快照磁盘占用和桌面中继要求见[沙箱部署与排障](../06-development/04-sandbox-deployment.md)。
Docker socket/TLS、模板版本、远端网关、多副本 Redis、技能快照磁盘占用、终端与桌面中继以及 Lite 本机沙箱的构建要求见[沙箱部署与排障](../06-development/04-sandbox-deployment.md)。
## 实现参考
- `internal/handler/sandbox_config.go`、`sandbox_skill.go`、`skill_catalog.go`、`me_env_var.go`
- `internal/application/service/tenant_skill_install.go`、`user_env_resolver.go`
- `internal/application/service/tenant_skill_install.go`、`tenant_skill_runtime_verify.go`、`tenant_skill_steer.go`、`user_env_resolver.go`
- `internal/types/tenant.go`、`sandbox_network_policy.go`
- `internal/sandbox/remote_client.go`、`docker_remote_client.go`、`gateway_transport.go`
- `internal/sandbox/remote_client.go`、`docker_remote_client.go`、`gateway_transport.go`、`terminal.go`
- `internal/localsandbox/`(Lite 本机沙箱:`core/policy_builder.go`、`seatbelt/`、`adapter/`)

View File

@ -22,7 +22,7 @@
| 操作 | 用途 |
| --- | --- |
| 新增 / 编辑 | 直接维护个人资料、偏好、事实、事项或兴趣;手工编辑不再由后台抽取覆盖 |
| 确认待确认项 | 推断条目从 pending 变为可用;未确认不会注入提示词 |
| 确认待确认项 | 推断条目从 pending 变为可用;未确认不会注入提示词。若推断用于修改已有记忆,确认前旧条目继续生效,确认时一并替换;推断已失效时确认会失败,需刷新列表 |
| 拒绝 / 删除 | 撤销错误或不再需要的记忆,拒绝留下抑制记录,减少重复提取 |
| 主题提升 | 把反复讨论的主题立即变为长期关注,也可停止跟踪主题 |
| 文档偏好 | 查看反复引用的文档,移除不再需要的个性化检索偏好 |
@ -33,9 +33,9 @@
## 对回答和检索的影响
系统将资料、偏好和兴趣作为受长度限制的常驻上下文,按当前问题召回相关事实和事项。智能推理还可主动搜索记忆与历史对话。记忆仅影响问题理解和资料选择,不扩展知识库访问权限。
系统将资料、偏好和兴趣作为受长度限制的常驻上下文,按当前问题召回相关事实和事项。配置向量模型后,语义召回在该身份的全部记忆中按与问题的相关度排序,不受条目重要度影响;PostgreSQL 启用 pgvector 时在数据库内排序,其余环境在服务内计算。智能推理还可主动搜索记忆与历史对话。记忆仅影响问题理解和资料选择,不扩展知识库访问权限。
开启检索个性化后,系统用主题帮助理解问题,并用反复引用的文档辅助排序。对话时间线会显示记忆相关步骤。后台任务通过游标及待处理会话记录续接,避免短时间连续发问导致提取遗漏。
开启检索个性化后,系统用主题帮助理解问题,并用反复引用的文档辅助排序。对话时间线会显示记忆相关步骤。后台任务按会话记录提取游标和待处理状态,短时间连续发问、批次截断或服务重启都不会遗漏消息。某段消息的模型输出持续无法解析时,最多重试三轮后跳过该段并继续处理后续消息,跳过的消息不会自动补提取。
## 排查记忆未生效的问题 {#排查}
@ -51,18 +51,19 @@
空间管理员可通过设置页维护记忆开关、提取模式和模型。配置保存在 `memory_config`,通过 `GET/PUT /tenants/kv/memory-config` 读取和更新,完整字段见[记忆 API](../04-api/02-api-memory.md)。
| 字段 | 说明 |
| --- | --- |
| `enabled` | 空间开关,默认 false |
| `write_mode` | `explicit_only` / `auto` |
| `extract_model_id` | 抽取模型,空值沿用对话模型 |
| `extract_delay_seconds` | 回答完成后延迟提取,合并短时间内的多轮消息 |
| `extract_min_interval_seconds` | 同一人的提取最短间隔,控制调用频率 |
| `extract_instructions` | 空间自己的提取规则 |
| `max_items` | 每个身份的活跃记忆上限,0 使用默认 200 |
| `interest_threshold` | 主题重复出现后形成关注的门槛,默认 3 |
| `embedding_model_id` / `vector_recall` | 选择记忆召回的向量模型并开启语义召回;无模型时用词法匹配 |
| `retrieval_conditioning` | 允许记忆影响问题理解和文档排序 |
| 名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `enabled` | bool | `false` | 空间开关 |
| `write_mode` | string | `explicit_only` | `explicit_only` / `auto`,其他值按 `explicit_only` 处理 |
| `extract_model_id` | string | 空 | 抽取模型,空值沿用对话模型 |
| `extract_delay_seconds` | int | `90` | 回答完成后延迟提取,合并短时间内的多轮消息;范围 5–3600 |
| `extract_min_interval_seconds` | int | `300` | 同一人两次提取的最短间隔,控制调用频率,间隔内的消息顺延处理;最大 86400 |
| `extract_instructions` | string | 空 | 空间自己的提取规则,最多 1000 字 |
| `max_items` | int | `200` | 每个身份的活跃记忆上限,最大 2000;0 使用默认值 |
| `interest_threshold` | int | `3` | 主题在多少个会话中出现后形成关注,最大 20 |
| `embedding_model_id` | string | 空 | 记忆召回使用的向量模型;为空时只做词法匹配 |
| `vector_recall` | bool | 省略即开启 | 配置了向量模型时是否启用语义召回 |
| `retrieval_conditioning` | bool | 省略即开启 | 允许记忆影响问题理解和文档排序 |
提取模型用于后台归纳,向量模型用于匹配当前问题。记忆功能会增加对应的模型调用;模型被记忆配置引用时,删除模型会显示依赖详情。

View File

@ -1,6 +1,6 @@
# API 总览
WeKnora HTTP API 使用 `/api/v1` 前缀,支持 JWT、API Key 和 Embed token 认证。调用各资源接口前,需按客户端类型选择凭证,并遵循统一的响应、错误处理、分页和流式事件约定。
WeKnora HTTP API 使用 `/api/v1` 前缀,支持 JWT、API Key 和 Embed token 认证;内置 MCP Server 端点另用端点令牌认证。调用各资源接口前,需按客户端类型选择凭证,并遵循统一的响应、错误处理、分页和流式事件约定。
## Base URL 与版本前缀
@ -23,7 +23,7 @@ BASE=http://localhost:8080
Authorization: Bearer <access_token>
```
- 通过 `POST /api/v1/auth/login`(或 register / auto-setup / OIDC)获得 `token` 与 `refresh_token`;`POST /api/v1/auth/refresh` 换发新 token。
- 通过 `POST /api/v1/auth/login`(或 register / OIDC;原生桌面应用使用 auto-setup)获得 `token` 与 `refresh_token`;`POST /api/v1/auth/refresh` 换发新 token。
- 可选请求头 `X-Tenant-ID: <tenant_id>`:在 JWT 指向的空间之外切换目标空间(须为该空间活跃成员,或具备 `CanAccessAllTenants` 跨空间超管属性)。畸形或 `0` 值直接返回 400。
- 若 JWT 未解析出任何空间且接口非“无空间可用”白名单(如 `/auth/me`、`/me/invitations` 等),返回 409 `{"code":"TENANT_REQUIRED"}`。
@ -53,6 +53,16 @@ Authorization: Embed <publish_token 或 session_token>
- `POST /embed/:channel_id/exchange` 用 publish token 换取短时效 session token;会话级操作还需 `X-Embed-Session: <sig>`(创建会话时返回的签名句柄)。
- IM 回调路由(`/api/v1/im/callback/:channel_id`)注册在全局认证中间件之前,使用各 IM 平台自身的签名验证。
### MCP 端点令牌(内置 MCP Server)
`/mcp/:endpoint_id`(不带 `/api/v1` 前缀)是空间对外暴露的 MCP Streamable HTTP 端点,由 `internal/middleware/mcp_endpoint_auth.go` 校验:
```
Authorization: Bearer <endpoint_token>
```
令牌在「设置 → 发布集成 → MCP Server」创建端点时一次性展示,可轮换。请求以端点所属空间的机器主体执行,权限限定在端点勾选的工具和知识库范围内。端点管理接口为 `/api/v1/mcp-endpoints`(Viewer+ 读取、Admin+ 变更,API Key 需 `manage_channels`),用法见 [MCP 集成](../03-features/08-mcp.md)。
### 认证流程图
```mermaid
@ -166,16 +176,17 @@ X-Accel-Buffering: no
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 请求 ID |
| `response_type` | string | `answer` / `references` / `thinking` / `tool_call` / `tool_result` / `reflection` / `session_title` / `agent_query` / `tool_approval_required` / `tool_approval_resolved` / `mcp_oauth_required` / `mcp_oauth_resolved` / `error` / `complete` |
| `response_type` | string | `answer` / `references` / `thinking` / `tool_call` / `tool_result` / `command_output` / `reflection` / `session_title` / `agent_query` / `artifacts_pending` / `memory_recalled` / `user_message_injected` / `context_compacted` / `tool_approval_required` / `tool_approval_resolved` / `mcp_oauth_required` / `mcp_oauth_resolved` / `error` / `complete`;技能安装记录流另有 `install_prompt` / `install_output` |
| `content` | string | 增量文本 |
| `done` | bool | 该类型事件是否结束 |
| `knowledge_references` | []SearchResult | `references` 事件携带的引用 |
| `tool_calls` | []LLMToolCall | 工具调用事件 |
| `data` | object | 事件附加元数据(如工具结果的 `success`、回答的 `truncated`) |
| `session_id` / `assistant_message_id` | string | `agent_query` 事件携带 |
| `usage` | TokenUsage | `prompt_tokens/completion_tokens/total_tokens/cache_*` |
| `finish_reason` | string | 结束原因 |
流以 `response_type:"complete"`(`done:true`)终止;出错时以 `response_type:"error"`(`done:true`)终止。`continue-stream` 采用重放 + 100ms 轮询追增量的续传语义(`?message_id=` 必填)。
流以 `response_type:"complete"`(`done:true`)终止;出错时以 `response_type:"error"`(`done:true`)终止。工具执行失败以 `tool_result`(`data.success=false`)返回,`error` 只表示整轮失败;回答因输出上限被截断时,`answer` 事件带 `data.truncated=true`。`continue-stream` 采用重放 + 100ms 轮询追增量的续传语义(`?message_id=` 必填)。
## 文件引用形式(resource_urls)
@ -225,6 +236,8 @@ X-Accel-Buffering: no
| 系统与平台管理 | [02-api-system.md](./02-api-system.md) | `/system`、`/system/admin` |
| 基础设施与数据源 | [02-api-infra.md](./02-api-infra.md) | `/vector-stores`、`/storage-backends`、`/web-search-providers`、`/datasource` |
| Agent 与 MCP | [02-api-agent-mcp.md](./02-api-agent-mcp.md) | `/agents`、`/mcp-services`、`/agent`、`/user/favorites` |
| 内置 MCP Server | [MCP 集成](../03-features/08-mcp.md) | `/mcp-endpoints`、`/mcp/:endpoint_id` |
| 本机浏览器 | [本机浏览器](../05-clients/09-local-browser.md) | `/me/browser`、`/local-browser` |
| 沙箱、技能与个人变量 | [02-api-sandbox-skills.md](./02-api-sandbox-skills.md) | `/sandbox-configs`、`/skills`、`/me/env-vars` |
| 长期记忆 | [02-api-memory.md](./02-api-memory.md) | `/memory`、`/tenants/kv/memory-config` |
| IM、Embed 与文件服务 | [02-api-channels.md](./02-api-channels.md) | `/im`、`/im-channels`、`/wechat`、`/embed-channels`、`/embed`、`/files`、`/r/:token` |

View File

@ -126,17 +126,16 @@ curl "$BASE/api/v1/agents/agent-1/suggested-questions?limit=6" -H "X-API-Key: $A
| --- | --- | --- | --- |
| `name` | string | 是 | 名称 |
| `description` | string | 否 | 旧版描述,兼容保留;管理界面统一编辑 `usage_instructions` |
| `usage_instructions` | string | 配置完成时必填 | 服务用途、适用场景和关键约束;第一步仅保存连接时可省略 |
| `usage_instructions` | string | 否 | 服务用途、适用场景和关键约束,模型据此判断何时使用该服务;管理界面在第二步要求填写 |
| `enabled` | bool | 否 | 启用 |
| `transport_type` | string | 是 | `sse` / `http-streamable` / `stdio` |
| `transport_type` | string | 是 | `sse` / `http-streamable`;`stdio` 出于安全原因被拒绝 |
| `url` | *string | 否 | 服务 URL(SSE/HTTP) |
| `headers` | map[string]string | 否 | HTTP 头 |
| `auth_config` | object | 否 | `auth_type`(`api_key/bearer/oauth`)、`api_key_header`、`custom_headers`、`scopes`、`auth_server_metadata_url`(密钥走 credentials 子资源) |
| `advanced_config` | object | 否 | 超时/重试 |
| `stdio_config` | object | 否 | stdio 命令与参数 |
| `env_vars` | map[string]string | 否 | 环境变量 |
| `advanced_config` | object | 否 | `{timeout,retry_count,retry_delay}`,默认 30 秒 / 3 次 / 1 秒;`timeout` 大于 60 秒时也会延长 Agent 单次调用该服务工具的等待窗口 |
| `stdio_config` / `env_vars` | object | 否 | 仅为兼容旧数据保留;stdio 已禁用,不生效 |
响应:200 `{"success":true,"data":{MCPServiceResponse}}`(含 `credentials:{api_key:{configured},token:{configured}}`)
响应:200 `{"success":true,"data":{MCPServiceResponse}}`(含 `credentials:{api_key:{configured},token:{configured}}`;已同步工具目录的服务还带 `catalog:{tool_count,stale,synced_at}`)
```bash
curl -X POST $BASE/api/v1/mcp-services -H "Authorization: Bearer $TOKEN" \
@ -147,6 +146,13 @@ curl -X POST $BASE/api/v1/mcp-services -H "Authorization: Bearer $TOKEN" \
用途:MCP 服务列表。权限:Viewer+。响应:200 `{"success":true,"data":[MCPServiceResponse]}`
| 查询参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `agent_id` | string | 否 | 与 `agent_source_tenant_id` 同时传入时,列出该共享智能体可 @ 的 MCP 服务 |
| `agent_source_tenant_id` | int | 否 | 共享智能体的来源空间 ID,与对话请求的同名参数一致 |
两个参数都传时走共享智能体路径:只返回该智能体在来源空间以 `selected` 模式指定且已启用的服务(`all`/`none` 模式返回空列表),且每项只含 ID、名称、说明、使用说明、传输类型、启用状态和工具目录摘要,不含 URL、请求头、认证配置等连接细节;调用者无权使用该智能体时返回 403。只传其一或都不传时,列出调用者自己空间的服务。
```bash
curl $BASE/api/v1/mcp-services -H "Authorization: Bearer $TOKEN"
```
@ -320,6 +326,40 @@ curl $BASE/api/v1/mcp-services/mcp-1/oauth/status -H "Authorization: Bearer $TOK
curl -X DELETE $BASE/api/v1/mcp-services/mcp-1/oauth/token -H "Authorization: Bearer $TOKEN"
```
## MCP Server 端点(/api/v1/mcp-endpoints) {#mcp-server-端点}
管理当前空间对外发布的 MCP 端点,外部 MCP 客户端连接 `/mcp/:endpoint_id`。读:Viewer+;写:Admin+。API key:`manage_channels`/full。Handler: `internal/handler/mcp_endpoint.go`。用途与工具说明见[MCP 集成](../03-features/08-mcp.md#供外部客户端调用)。
| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/mcp-endpoints` | 端点列表(不含令牌) |
| GET | `/mcp-endpoints/tools` | 工具目录:`{groups,tools:[{name,group,destructive}],default_tools}` |
| POST | `/mcp-endpoints` | 创建;201,响应含一次性 `token` |
| GET | `/mcp-endpoints/:endpoint_id` | 详情 |
| PUT | `/mcp-endpoints/:endpoint_id` | 部分更新,省略的字段保持原值 |
| DELETE | `/mcp-endpoints/:endpoint_id` | 删除,使用该端点的客户端立即失效 |
| POST | `/mcp-endpoints/:endpoint_id/rotate-token` | 轮换令牌,响应含新 `token`,旧令牌立即失效 |
请求字段(创建和更新相同,均可选):
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `name` | string | 名称,创建时必填 |
| `description` | string | 说明 |
| `enabled` | bool | 默认 true;停用后连接返回 403 |
| `knowledge_base_ids` | string[] | 可访问的知识库,空数组表示空间内全部 |
| `tools` | string[] | 暴露的工具,至少一个;创建时省略则使用 `default_tools`(全部只读工具) |
| `default_agent_id` | string | `ask` 使用的 Agent,空为内置快速问答;内部内置 Agent 不可选 |
| `rate_limit_per_minute` | int | 每分钟工具调用上限,0 或省略为 60,最大 6000 |
响应 `data` 为 `{id,tenant_id,name,description,enabled,token_hint,knowledge_base_ids,tools,default_agent_id,rate_limit_per_minute,path,last_used_at,created_at,updated_at}`,创建和轮换时额外带 `token`。使用受限 API Key 调用时,端点的知识库和工具所需能力不能超出该 Key 的范围,否则 403。
```bash
curl -X POST $BASE/api/v1/mcp-endpoints -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"name":"产品文档助手","knowledge_base_ids":["kb-1"],"tools":["search_knowledge","read_document","ask"]}'
```
## Agent 运行时交互(/api/v1/agent)
对话中的人工审批与 OAuth 恢复;权限均 Viewer+(发起会话的人才有上下文),API key 默认拒绝。
@ -369,7 +409,7 @@ curl -X POST $BASE/api/v1/agent/mcp-oauth-resolutions/p-1/cancel -H "Authorizati
## 技能、沙箱与个人变量
`GET /api/v1/skills?sandbox_config_id=...` 返回指定配置下可用技能的名称/说明及 skills_available。目录收录、安装、模板、进度、文件与个人变量的完整接口见[沙箱与技能 API](02-api-sandbox-skills.md)。
`GET /api/v1/skills?sandbox_config_id=...` 返回指定配置下可用技能的名称/说明及 skills_available;传 `agent_id` + `agent_source_tenant_id` 时按共享智能体的来源空间和其沙箱配置返回,详见[沙箱与技能 API](02-api-sandbox-skills.md#沙箱内技能)。目录收录、安装、模板、进度、文件与个人变量的完整接口见[沙箱与技能 API](02-api-sandbox-skills.md)。
智能体 config 增加 `sandbox_config_id`;与 skills_selection_mode、selected_skills 一起决定可用技能。shell/文件工具按后端能力注册,旧 read_skill / execute_skill_script 不再注册。
@ -414,4 +454,4 @@ curl -X DELETE $BASE/api/v1/user/favorites/kb/kb-1 -H "Authorization: Bearer $TO
## 实现参考
路由注册:`internal/router/router.go` 的 `RegisterCustomAgentRoutes`、`RegisterMCPServiceRoutes`、`RegisterSkillRoutes`、`RegisterUserFavoriteRoutes`。Handler:`internal/handler/custom_agent.go`、`internal/handler/mcp_service.go`、`internal/handler/mcp_credentials.go`、`internal/handler/mcp_oauth.go`、`internal/handler/skill_handler.go`、`internal/handler/user_resource_favorite.go`。
路由注册:由 `internal/router/router.go` 调用,`RegisterCustomAgentRoutes`、`RegisterSkillRoutes`、`RegisterUserFavoriteRoutes` 定义在 `routes_agent.go`,`RegisterMCPServiceRoutes`(含 MCP OAuth 与 `/agent` 运行时交互)在 `routes_infra.go`,`RegisterMCPEndpointRoutes` 与公开的 `/mcp/:endpoint_id` 在 `routes_mcp_endpoint.go`。Handler:`internal/handler/custom_agent.go`、`internal/handler/mcp_service.go`、`internal/handler/mcp_credentials.go`、`internal/handler/mcp_oauth.go`、`internal/handler/mcp_endpoint.go`、`internal/handler/skill_handler.go`、`internal/handler/user_resource_favorite.go`。

View File

@ -12,10 +12,11 @@
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `username` | string | 是(`binding:"required"`) | 用户名 |
| `email` | string | 是(`binding:"required"`) | 邮箱 |
| `password` | string | 是(`binding:"required"`) | 密码 |
| `tenant_provisioning` | string | 否 | 空间开通策略 |
| `username` | string | 是 | 用户名,2–50 字符 |
| `email` | string | 是 | 邮箱 |
| `password` | string | 是 | 密码(8–32 位,字母+数字;复杂模式另需大小写和特殊字符) |
是否自动创建个人空间由服务端的 `auth.default_tenant_mode` 决定,请求体不能指定。`invite_only` 模式下返回 403。
响应:201 `{"success":true,"message":"...","user":{User}}`
@ -288,4 +289,4 @@ curl -X POST $BASE/api/v1/me/invitations/12/decline -H "Authorization: Bearer $T
## 实现参考
路由注册:`internal/router/router.go` 的 `RegisterAuthRoutes` 与 `RegisterMyInvitationRoutes`。Handler:`internal/handler/auth.go`、`internal/handler/auth_register_by_invite.go`、`internal/handler/tenant_invitation.go`。
路由注册:`internal/router/routes_auth_tenant.go` 的 `RegisterAuthRoutes` 与 `RegisterMyInvitationRoutes`。Handler:`internal/handler/auth.go`、`internal/handler/auth_register_by_invite.go`、`internal/handler/tenant_invitation.go`。

View File

@ -28,9 +28,11 @@ API key:`manage_channels`/full。IM 渠道携带外部 bot 凭证:列表 Vie
| --- | --- | --- | --- |
| `platform` | string | 是 | `wecom/feishu/lark/slack/telegram/dingtalk/mattermost/wechat/qqbot/yunzhijia` |
| `name` | string | 否 | 显示名 |
| `mode` | string | 否 | `websocket`(默认)/`webhook`/`longpoll`(wechat 强制 longpoll) |
| `mode` | string | 否 | `websocket`(默认;mattermost/yunzhijia 默认 `webhook`)/`webhook`/`longpoll`(wechat 强制 longpoll) |
| `output_mode` | string | 否 | `stream`(默认)/`full`(wechat 强制 full) |
| `knowledge_base_id` | string | 否 | 关联 KB |
| `locale` | string | 否 | 回复语言:`zh-CN`/`en-US`/`ja-JP`/`ko-KR`/`ru-RU`;空(默认)使用部署默认语言(`WEKNORA_LANGUAGE`,未设置为 `zh-CN`);其他值 400 |
| `session_mode` | string | 否 | `user`(默认)/`thread` |
| `knowledge_base_id` | string | 否 | 附件额外入库的 KB,须属于本空间,否则 400 |
| `credentials` | object | 否 | 平台凭证 |
| `enabled` | bool | 否 | 默认 true |
@ -38,7 +40,7 @@ API key:`manage_channels`/full。IM 渠道携带外部 bot 凭证:列表 Vie
```bash
curl -X POST $BASE/api/v1/agents/agent-1/im-channels -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"platform":"feishu","name":"飞书客服"}'
-H 'Content-Type: application/json' -d '{"platform":"feishu","name":"飞书客服","locale":"en-US"}'
```
### GET /api/v1/agents/:id/im-channels
@ -63,7 +65,7 @@ curl $BASE/api/v1/im-channels -H "Authorization: Bearer $TOKEN"
### PUT /api/v1/im-channels/:id
用途:更新渠道(局部更新:`name/mode/output_mode/knowledge_base_id/credentials/enabled/agent_id` 均可选)。权限:Admin+。
用途:更新渠道(局部更新:`name/mode/output_mode/locale/session_mode/knowledge_base_id/credentials/enabled/agent_id` 均可选;`knowledge_base_id` 传空字符串解除关联,`locale` 传空字符串恢复默认语言)。权限:Admin+。
响应:200 `{"data":{IMChannel}}`
@ -225,6 +227,22 @@ curl -X POST $BASE/api/v1/embed-channels/ec-1/preview-session -H "Authorization:
curl $BASE/api/v1/embed-channels/ec-1/stats -H "Authorization: Bearer $TOKEN"
```
## Embed 嵌入页框架策略
### GET /api/v1/embed-frame-policy
用途:供 Nginx `auth_request` 子请求在返回 `/embed/:channel_id` 页面前获取该渠道的 `Content-Security-Policy: frame-ancestors`。免 token,只返回策略头,不返回渠道配置;响应 `Cache-Control: no-store`。
| 请求头 | 必填 | 说明 |
| --- | --- | --- |
| `X-Embed-Page-URI` | 是 | 嵌入页的相对 URI,如 `/embed/<channel_id>` |
响应:204 并带 CSP 头;渠道不存在、已停用、路径非法或白名单为空时 403。
```bash
curl -i $BASE/api/v1/embed-frame-policy -H "X-Embed-Page-URI: /embed/ec-1"
```
## Embed 公开路由(/api/v1/embed/:channel_id,EmbedAuth)
认证:`Authorization: Embed <publish_token|session_token>`;会话级操作附加 `X-Embed-Session: <sig>`。限流与 Origin 校验见总览。Handler: `internal/handler/embed_channel.go`;中间件:`internal/middleware/embed_auth.go`
@ -391,7 +409,7 @@ curl "$BASE/api/v1/embed/ec-1/files?file_path=local://1/exports/chart.png" \
## 文件服务
实现于 `internal/router/router.go`(非 handler 包)。
实现于 `internal/router/files.go`(非 handler 包)。
### GET /files
@ -448,4 +466,4 @@ curl $BASE/r/abc123 -o file.png
## 实现参考
路由注册:`internal/router/router.go` 的 `RegisterIMRoutes`、`RegisterIMChannelRoutes`、`RegisterEmbedChannelRoutes`、`RegisterEmbedPublicRoutes`、`serveFilesWithResources`、`servePresignedFiles`、`servePresignedPreview`、`serveResourceGrants`。Handler:`internal/handler/im.go`、`internal/handler/wechat_qrcode.go`、`internal/handler/embed_channel.go`。
路由注册:`internal/router/routes_agent.go` 的 `RegisterIMRoutes`、`RegisterIMChannelRoutes`、`RegisterEmbedChannelRoutes`、`RegisterEmbedPublicRoutes`;`internal/router/files.go` 的 `serveFilesWithResources`、`servePresignedFiles`、`servePresignedPreview`、`serveResourceGrants`。Handler:`internal/handler/im.go`、`internal/handler/wechat_qrcode.go`、`internal/handler/embed_channel.go`。

View File

@ -14,6 +14,7 @@
| --- | --- | --- | --- |
| `title` | string | 否 | 标题 |
| `description` | string | 否 | 描述 |
| `project_dir` | string | 否 | 仅桌面版:把会话绑定到用户已批准的本机项目目录(绝对路径,须与批准列表完全一致),否则返回 400 |
响应:201 `{"success":true,"data":{Session}}`(`id,title,description,tenant_id,user_id,is_pinned,last_request_state,created_at,...`)
@ -121,6 +122,96 @@ curl -X POST $BASE/api/v1/sessions/s-1/stop -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"message_id":"m-1"}'
```
停止时,尚未送达智能体的追加消息(见下文[向运行中的回答追加消息](#steer))会一并丢弃,不会自动开始新一轮。
### POST /api/v1/sessions/:session_id/fork
用途:从某条历史消息分叉出新会话,源会话保持不变。只有会话归属人可以分叉。Handler: `internal/handler/session/fork.go`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `message_id` | string | 是 | 分叉点。用户消息:复制它之前的历史,客户端通常把该问题预填到输入框;助手消息:复制到这条回答为止的历史 |
| `title` | string | 否 | 新会话标题,默认“源标题(分支)” |
复制的消息保留原时间线和生成文件;新会话记录 `parent_session_id` 与 `forked_from_message_id`。源会话绑定沙箱时,系统会给沙箱做快照,新会话首次使用沙箱时从分叉点对应轮次的工作区状态启动。无法携带工作区时分叉仍然成功,但返回 `degraded: true` 和原因:
| `reason` | 含义 |
| --- | --- |
| `NO_CHECKPOINT` | 分叉点之前的轮次没有工作区检查点 |
| `SANDBOX_REPLACED` | 检查点属于会话已更换的旧沙箱 |
| `SANDBOX_GONE` | 源会话当前没有可快照的沙箱 |
| `SNAPSHOT_UNSUPPORTED` | 沙箱后端不支持快照或快照失败 |
响应:200 `{"success":true,"data":{"session_id":"新会话 ID","degraded":false}}`。源会话正在生成、或分叉点是未完成的回答时返回 409(`code: FORK_SOURCE_BUSY`);会话或消息不存在返回 404;分叉点不是用户或助手消息返回 400。
```bash
curl -X POST $BASE/api/v1/sessions/s-1/fork -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"message_id":"m-3"}'
```
### POST /api/v1/sessions/:session_id/rewind
用途:把当前会话原地回退到某条消息。只有会话归属人可以回退。Handler: `internal/handler/session/rewind.go`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `message_id` | string | 是 | 回退点。用户消息:删除它本身及之后的消息;助手消息:保留这条回答,删除之后的消息 |
被删除消息的生成文件、追问建议和聊天历史索引会一并清理。会话绑定沙箱时,系统同时把 `/workspace` 重置到保留历史中最后一轮的检查点;工作区重置失败时整个操作失败,消息不会被删除。
响应:200 `{"success":true,"data":{"deleted_messages":N,"workspace_reset":true,"reason":""}}`。`workspace_reset` 为 false 时,`reason` 说明只回退了对话的原因:`NO_SANDBOX`(会话未绑定沙箱)或 `NO_CHECKPOINT`(保留的历史没有检查点)。
| 状态码 | `code` | 含义 |
| --- | --- | --- |
| 409 | `REWIND_SOURCE_BUSY` | 会话正在生成,或回退点是未完成的回答 |
| 409 | `REWIND_NO_CHECKPOINT` | 沙箱仍在,但保留的历史找不到可用检查点;为避免文件领先于对话而拒绝 |
| 409 | `REWIND_SANDBOX_REPLACED` | 检查点属于已更换的旧沙箱 |
| 404 | — | 会话或消息不存在 |
| 500 | — | 工作区重置失败,可重试 |
```bash
curl -X POST $BASE/api/v1/sessions/s-1/rewind -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"message_id":"m-3"}'
```
### 向运行中的回答追加消息(steer) {#steer}
智能推理模式的回答生成期间,同一会话再次调用 `agent-chat` 会返回 409。此时可用以下接口把新消息排入当前轮。只有会话归属人可调用;快速问答没有可注入的执行循环,不支持追加。Handler: `internal/handler/session/steer.go`
| 方法 | 路径 | 用途 |
| --- | --- | --- |
| POST | `/api/v1/sessions/:session_id/steer` | 追加一条消息 |
| GET | `/api/v1/sessions/:id/steer` | 列出当前轮尚未送达的排队消息,用于刷新页面后恢复队列;返回 `assistant_message_id` 与 `items[]`(`steer_id`、`content`、`delivery`、`mentioned_items`),无运行中的轮次时 `items` 为空 |
| DELETE | `/api/v1/sessions/:id/steer/:steer_id` | 撤回一条排队消息 |
| POST | `/api/v1/sessions/:session_id/steer/:steer_id/inject` | 把一条 `after` 消息改为 `inject` |
POST 请求体:
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `query` | string | 是 | 消息内容,最多 10000 字符 |
| `delivery` | string | 否 | `after`(默认):当前轮结束后作为下一轮问题发出;`inject`:在当前轮下一次迭代边界(包括即将给出最终回答前)送达智能体,智能体据此调整后继续 |
| `mentioned_items` | []object | 否 | @提及项,格式同聊天请求 |
| `steer_id` | string | 否 | 客户端生成的 UUID,用于重试去重;同一 ID 对应不同内容返回 409 |
| `expected_assistant_message_id` | string | 否 | 客户端看到的运行中助手消息 ID;运行已切换时返回 409,客户端应重试 |
| `channel` | string | 否 | 来源渠道 |
响应中的 `status`:
| `status` | 含义 |
| --- | --- |
| `queued` | 已排队,返回 `steer_id`、`delivery` 与 `assistant_message_id` |
| `new_run` | 当前没有运行中的轮次,客户端应改为正常调用 `agent-chat` 发送 |
| `already_injected` | 该消息已经送达智能体(重试、撤回或改为注入时可能出现),无法撤回 |
| `deleted` / `gone` | 仅 DELETE:已撤回(`removed` 表示是否确实删除了一条)/ 当前没有运行中的轮次 |
每轮最多同时排队 10 条未送达消息,超出返回 400。当前轮正常结束后,第一条未送达的消息由服务端直接作为下一轮的问题启动,其余消息按原投递方式转入该轮;这一轮没有对应的 `agent-chat` 连接,可用 `GET /steer` 返回的 `assistant_message_id` 调用 continue-stream 接收。用户停止生成时,未送达的消息全部丢弃。已送达的消息写入会话历史,并通过 `user_message_injected` 事件通知客户端。查询运行状态失败时返回 503,可重试。
```bash
curl -X POST $BASE/api/v1/sessions/s-1/steer -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"query":"只看 2024 年的数据","delivery":"inject"}'
```
### POST /api/v1/sessions/:session_id/pin 与 DELETE /api/v1/sessions/:id/pin
用途:置顶 / 取消置顶会话。无请求体。Handler: `internal/handler/session/handler.go`
@ -140,7 +231,7 @@ curl -X DELETE $BASE/api/v1/sessions/s-1/pin -H "Authorization: Bearer $TOKEN"
| --- | --- | --- | --- |
| `message_id` | string | 是 | 要续传的助手消息 ID |
响应:200 SSE(`text/event-stream`,事件格式见总览“流式接口协议”)。
响应:200 SSE(`text/event-stream`,事件格式见总览“流式接口协议”)。重放已存储的事件时,同一事件 ID 下连续的未完成 `answer`/`thinking`/`reflection` 增量会合并为一帧,按事件 ID 累积内容的客户端得到的文本不变;实时推送部分不合并。
```bash
curl -N "$BASE/api/v1/sessions/continue-stream/s-1?message_id=m-1" -H "Authorization: Bearer $TOKEN"
@ -279,12 +370,15 @@ Handler: `internal/handler/session/qa.go`。API key:聊天需 `chat`/full;`k
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `query` | string | 是(`binding:"required"`) | 用户问题 |
| `query` | string | 是(`binding:"required"`) | 用户问题;为空、仅含空白、含控制字符或非法 UTF-8 时返回 400 |
| `knowledge_base_ids` | []string | 否 | 检索的 KB |
| `knowledge_ids` | []string | 否 | 限定知识文件 |
| `agent_enabled` | bool | 否 | 是否启用 Agent 模式 |
| `agent_id` | string | 否 | 自定义 Agent ID |
| `agent_source_tenant_id` | uint64 | 否 | 共享智能体的来源空间,同名共享智能体来自多个空间时用于区分 |
| `reasoning_effort` | string | 否 | 本轮思考强度:`off`、`auto`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`(`none`/`false` 视为 `off`,`true`/`on` 视为 `auto`);省略时沿用智能体配置。只作用于本轮,不修改智能体;模型不支持所选档位时自动调整到相近档位。非法值返回 400 |
| `web_search_enabled` | bool | 否 | 联网搜索;只在智能体本身开启联网搜索时生效 |
| `local_browser_enabled` | bool | 否 | 本轮允许使用已连接的本机浏览器;只能用于智能推理智能体的 `agent-chat`,否则返回 400。见[本机浏览器](../05-clients/09-local-browser.md) |
| `summary_model_id` | string | 否 | 总结模型;使用共享智能体时忽略,始终使用智能体配置的模型 |
| `mcp_service_ids` | []string | 否 | @提及的 MCP 服务 |
| `skill_names` | []string | 否 | @提及的技能 |
@ -296,8 +390,11 @@ Handler: `internal/handler/session/qa.go`。API key:聊天需 `chat`/full;`k
| `attachment_ids` | []string | 否 | 已上传的会话附件 ID |
| `channel` | string | 否 | 来源渠道 |
| `suggestion_attribution` | object | 否 | 点击建议的归因信息 |
| `question_origin` | object | 否 | 用户点选的建议问题来自哪里:`knowledge_base_id`、可选 `knowledge_id`。仅智能推理模式使用,智能体会先检索该来源;来源不在本轮检索范围内时忽略,不会扩大范围 |
响应:200 SSE 流,`event: message` + `data: StreamResponse`(见总览),以 `complete` 事件结束。
所选 `reasoning_effort` 会写入会话的 `last_request_state.reasoning_effort`,重新打开会话时前端据此恢复。
响应:200 SSE 流,`event: message` + `data: StreamResponse`(见总览),以 `complete` 事件结束。回答因模型单次输出上限被截断时,`answer` 事件带 `data.truncated: true`,截断前已生成的内容照常保留。
```bash
curl -N -X POST $BASE/api/v1/knowledge-chat/s-1 -H "X-API-Key: $API_KEY" \
@ -309,6 +406,10 @@ curl -N -X POST $BASE/api/v1/knowledge-chat/s-1 -H "X-API-Key: $API_KEY" \
用途:Agent 问答(SSE 流式,含 `thinking/tool_call/tool_result/tool_approval_required/mcp_oauth_required` 等事件)。请求体同上。
- 工具执行失败以 `tool_result` 事件返回(`data.success: false`,`data.error` 为原因),智能体会继续处理;`error` 事件只表示整轮执行失败。
- 智能体中途接收追加消息时发出 `user_message_injected`;命令执行过程中以 `command_output` 更新工具卡片输出。
- 同一会话已有智能推理回答在生成时返回 409,此时应改用 [steer 接口](#steer)追加消息。
```bash
curl -N -X POST $BASE/api/v1/agent-chat/s-1 -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"query":"分析上季度数据","agent_id":"agent-1"}'
@ -419,8 +520,6 @@ curl "$BASE/api/v1/sessions/session-1/messages/message-1/artifacts/0/download" \
删除后该文件在列表接口和产物库中都不再出现,但它在消息中的**位置会被保留**:`index` 就是下载地址,如果后面的文件依次前移,已有的下载链接就会指向错的文件。同一原因,沙箱里的同名文件不会在下一轮采集时被重新收录 —— 它的 mtime 并没有因为用户删除而改变。
只有当没有其他持有者仍然引用该对象时才会真正删除字节:同一份文件如果被存入知识库、或被后续回答重新引用,都会各自持有一份引用,删除其中一处不会动到底层数据。
| 参数 | 说明 |
| --- | --- |
| `all_versions` | 连同本会话中同一 `source_path` 的所有历史版本一并删除。布尔值,默认 `false` |
@ -464,4 +563,4 @@ curl -X DELETE "$BASE/api/v1/artifacts?session_id=session-1&message_id=message-1
## 实现参考
路由注册:`internal/router/router.go` 的 `RegisterSessionRoutes`、`RegisterChatRoutes`、`RegisterMessageRoutes`。Handler:`internal/handler/session/`(handler.go、qa.go、stream.go、title.go、temporary_document.go)、`internal/handler/message.go`、`internal/handler/message_suggestion.go`。
路由注册:`internal/router/routes_chat.go` 的 `RegisterSessionRoutes`、`RegisterChatRoutes`、`RegisterMessageRoutes`(由 `internal/router/router.go` 调用)。Handler:`internal/handler/session/`(handler.go、qa.go、stream.go、title.go、temporary_document.go、fork.go、rewind.go、steer.go、artifact_*.go)、`internal/handler/message.go`、`internal/handler/message_suggestion.go`。

View File

@ -182,7 +182,9 @@ curl -X PUT $BASE/api/v1/knowledge-bases/kb-1/tags/t-1 -H "Authorization: Bearer
### DELETE /api/v1/knowledge-bases/:id/tags/:tag_id
用途:删除标签。查询参数:`force`(bool,强制删除)、`content_only`(bool,仅删内容保留标签)。请求体(可选):`{"exclude_ids":[int64]}`。
用途:删除标签。查询参数:`force`(bool,强制删除被引用的标签)、`content_only`(bool,仅删除标签下的内容、保留标签)。请求体(可选):`{"exclude_ids":[int64]}`,列出删除时保留的 FAQ 条目 seq_id。
请求体格式不合法或 ID 非正整数返回 400;ID 不存在返回 404;ID 不属于当前知识库的 FAQ 条目返回 403。
响应:200 `{"success":true}`
@ -208,6 +210,8 @@ curl -X DELETE "$BASE/api/v1/knowledge-bases/kb-1/tags/t-1?force=true" -H "Autho
| `chunking_config.enable_parent_child` | bool | 否 | 按父子分块试切,返回的是子块(与检索粒度一致) |
| `chunking_config.parent_chunk_size` / `child_chunk_size` | int | 否 | 父/子块大小,缺省 4096 / 384 |
样例文本中的内联 HTML `<table>` 会先转换为 Markdown 表格,与入库时的处理一致。
响应:200 `{"success":true,"data":{"selected_tier","tier_chain","rejected","profile","chunks":[...],"stats":{count,avg_chars,min_chars,max_chars,stddev_chars,truncated_to}}}`;文本超长 413;分块超时(5s)504。
```bash

View File

@ -18,11 +18,12 @@
| `keyword` | string | 否 | 关键字 |
| `search_field` | string | 否 | `standard_question`/`similar_questions`/`answers`(默认全字段) |
| `sort_order` | string | 否 | `asc`(默认按更新时间倒序) |
| `is_enabled` | bool | 否 | 按启用状态筛选:`true` 仅启用、`false` 仅停用,不传返回全部;其他取值返回 400 |
响应:200 `{"success":true,"data":{分页 FAQEntry 列表}}`
```bash
curl "$BASE/api/v1/knowledge-bases/kb-1/faq/entries?page=1" -H "Authorization: Bearer $TOKEN"
curl "$BASE/api/v1/knowledge-bases/kb-1/faq/entries?page=1&is_enabled=false" -H "Authorization: Bearer $TOKEN"
```
### GET /api/v1/knowledge-bases/:id/faq/entries/export
@ -54,7 +55,7 @@ curl $BASE/api/v1/knowledge-bases/kb-1/faq/entries/12 -H "Authorization: Bearer
| `entries` | []FAQEntryPayload | 是(`binding:"required"`) | 批量条目 |
| `mode` | string | 是(`binding:"oneof=append replace"`) | 追加或替换 |
| `knowledge_id` | string | 否 | FAQ 知识实体 ID |
| `task_id` | string | 否 | 自定义任务 ID |
| `task_id` | string | 否 | 自定义任务 ID,仅允许字母、数字、`_`、`-`,最长 128 字符,否则返回 400 |
| `dry_run` | bool | 否 | 仅校验不落库 |
响应:200 `{"success":true,"data":{"task_id"}}`
@ -156,8 +157,8 @@ curl -X DELETE $BASE/api/v1/knowledge-bases/kb-1/faq/entries -H "Authorization:
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `query_text` | string | 是(`binding:"required"`) | 查询 |
| `vector_threshold` | float64 | 否 | 向量阈值 |
| `match_count` | int | 否 | 默认 10,上限 200 |
| `vector_threshold` | float64 | 否 | 向量阈值,默认 0.7 |
| `match_count` | int | 否 | 默认 10,上限 50 |
| `first_priority_tag_ids` / `second_priority_tag_ids` | []int64 | 否 | 标签优先级过滤 |
| `only_recommended` | bool | 否 | 仅推荐条目 |
@ -206,7 +207,7 @@ curl $BASE/api/v1/faq/import/progress/task-1 -H "X-API-Key: $API_KEY"
| `folder_id` | string | 否 | 精确目录过滤(空串=根) |
| `category_depth` | int | 否 | 目录深度 |
| `page` / `page_size` | int | 否 | 分页(默认 1/20) |
| `sort_by` / `sort_order` | string | 否 | 排序(默认 `updated_at` desc) |
| `sort_by` / `sort_order` | string | 否 | 排序字段:`title`、`created_at`、`updated_at`、`page_type`、`wiki_path`、`sort_order`、`depth`,其他值按 `updated_at`;默认 `updated_at` desc |
响应:200 `WikiPageListResponse`
@ -263,7 +264,7 @@ curl -X PUT $BASE/api/v1/knowledgebase/kb-1/wiki/pages/overview -H "Authorizatio
| 查询参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `version` | int | 否 | 传入时返回**该版本全文**(用于 diff),无效或 < 1 返回 400,找不到返回 404 |
| `version` | int | 否 | 传入时返回**该版本全文**(用于 diff),无效或 < 1 返回 400,找不到返回 404(升级前写入的版本或已被保留策略清理的快照都没有全文,属正常情况) |
| `limit` | int | 否 | 默认 50,上限 200;仅列表模式生效 |
| `offset` | int | 否 | 分页偏移 |
@ -458,4 +459,4 @@ curl -X PUT $BASE/api/v1/knowledgebase/kb-1/wiki/issues/i-1/status -H "Authoriza
## 实现参考
路由注册:`internal/router/router.go` 的 `RegisterFAQRoutes` 与 `RegisterWikiPageRoutes`。Handler:`internal/handler/faq.go`、`internal/handler/wiki_page.go`。
路由注册:`internal/router/routes_knowledge.go` 的 `RegisterFAQRoutes` 与 `RegisterWikiPageRoutes`。Handler:`internal/handler/faq.go`、`internal/handler/wiki_page.go`。

View File

@ -101,13 +101,13 @@ curl -X POST $BASE/api/v1/vector-stores/vs-1/test -H "Authorization: Bearer $TOK
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string | 是(`binding:"required"`) | 名称 |
| `provider` | string | 是(`binding:"required"`) | 提供方(minio/cos/tos/s3/oss/ks3/obs…) |
| `config` | object | 否 | 提供方配置(响应中凭证掩码) |
| `status` | string | 否 | 状态 |
| `provider` | string | 是(`binding:"required"`) | 提供方:`local`/`minio`/`cos`/`tos`/`s3`/`oss`/`ks3`/`obs`,受 `STORAGE_ALLOW_LIST` 限制 |
| `config` | object | 否 | 提供方配置,字段见[存储后端](../03-features/19-storage-backends.md#连接参数)(响应中凭证掩码) |
| `status` | string | 否 | `active`(默认)/`disabled` |
### GET /api/v1/storage-backends/types
用途:允许的存储类型。权限:Viewer+。响应:200 `{"success":true,"data":[...]}`
用途:`STORAGE_ALLOW_LIST` 允许的 provider 名称列表(未设置时返回全部)。权限:Viewer+。响应:200 `{"success":true,"data":["local","minio",...]}`
```bash
curl $BASE/api/v1/storage-backends/types -H "Authorization: Bearer $TOKEN"
@ -300,7 +300,7 @@ curl -X POST $BASE/api/v1/web-search-providers/wsp-1/test -H "Authorization: Bea
外部内容连接器(Feishu/Notion/语雀等),同步任务会写入 KB。Handler: `internal/handler/datasource.go`。本组多数响应为原始对象/数组(无 `success` 包装)。
当前已注册类型为 feishu、lark、gitlab、ima、notion、yuque、rss。GitLab/IMA 的 credentials、资源选择与同步限制见[数据源导入](../03-features/10-datasource.md)。sync_deletions 开启后会真实删除该数据源归属下的已删除知识;source_created_at/source_updated_at 保存在知识 metadata 中。
当前已注册类型为 feishu、lark、feishu_drive、lark_drive、notion、confluence、yuque、dingtalk、ima、rss、gitlab。各连接器的 credentials、资源选择与同步限制见[数据源导入](../03-features/10-datasource.md)。sync_deletions 开启后会真实删除该数据源归属下的已删除知识;source_created_at/source_updated_at 保存在知识 metadata 中。
### GET /api/v1/datasource/types
@ -325,7 +325,7 @@ curl $BASE/api/v1/datasource/types -H "Authorization: Bearer $TOKEN"
```bash
curl -X POST $BASE/api/v1/datasource/validate-credentials -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"type":"notion","credentials":{"token":"secret"}}'
-H 'Content-Type: application/json' -d '{"type":"notion","credentials":{"api_key":"ntn_xxx"}}'
```
### POST /api/v1/datasource
@ -397,7 +397,7 @@ curl -X DELETE $BASE/api/v1/datasource/ds-1 -H "Authorization: Bearer $TOKEN"
```bash
curl -X PUT $BASE/api/v1/datasource/ds-1/credentials -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"credentials":{"token":"secret"}}'
-H 'Content-Type: application/json' -d '{"credentials":{"api_key":"ntn_xxx"}}'
```
### DELETE /api/v1/datasource/:id/credentials/:field
@ -475,4 +475,4 @@ curl $BASE/api/v1/datasource/logs/log-1 -H "Authorization: Bearer $TOKEN"
## 实现参考
路由注册:`internal/router/router.go` 的 `RegisterVectorStoreRoutes`、`RegisterStorageBackendRoutes`、`RegisterWebSearchRoutes`、`RegisterWebSearchProviderRoutes`、`RegisterDataSourceRoutes`。Handler:`internal/handler/vectorstore.go`、`internal/handler/storagebackend.go`、`internal/handler/web_search.go`、`internal/handler/web_search_provider.go`、`internal/handler/web_search_provider_credentials.go`、`internal/handler/datasource.go`、`internal/handler/datasource_credentials.go`。
路由注册:`internal/router/routes_infra.go` 的 `RegisterVectorStoreRoutes`、`RegisterStorageBackendRoutes`、`RegisterWebSearchRoutes`、`RegisterWebSearchProviderRoutes`、`RegisterDataSourceRoutes`。Handler:`internal/handler/vectorstore.go`、`internal/handler/storagebackend.go`、`internal/handler/web_search.go`、`internal/handler/web_search_provider.go`、`internal/handler/web_search_provider_credentials.go`、`internal/handler/datasource.go`、`internal/handler/datasource_credentials.go`。

View File

@ -25,6 +25,8 @@
| `storage_provider_config` | object | 否 | 存储配置 |
| `vector_store_id` | string | 否 | 向量库绑定(非法返回 code 2200/2201) |
| `faq_config` / `wiki_config` / `extract_config` / `indexing_strategy` | object | 否 | 类型相关配置 |
| `summary_model_id` | string | 否 | 摘要模型,也是自动标签和 AI 描述的默认模型 |
| `auto_tag_config` / `profile_config` | object | 否 | 自动标签、AI 知识库描述(仅 document 类型,见下文) |
响应:201 `{"success":true,"data":{KnowledgeBase}}`
@ -33,18 +35,30 @@ curl -X POST $BASE/api/v1/knowledge-bases -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"name":"产品文档","type":"document"}'
```
### 文档自动标签配置
### 自动标签与 AI 描述配置
创建知识库时 `auto_tag_config`、`profile_config` 位于顶层;更新时放在 `config.auto_tag_config`、`config.profile_config`。两者仅 document 知识库支持,默认 enabled=false。`profile_config` 开启后,文档新增/删除/摘要更新会自动刷新 `generated_profile`(AI 知识库描述,见下文 `profile/generate`)。
创建知识库时 `auto_tag_config`、`profile_config` 位于顶层;更新时放在 `config.auto_tag_config`、`config.profile_config`。两者仅 document 知识库支持,默认 enabled=false。
| 字段 | 默认 | 说明 |
| --- | --- | --- |
| enabled | false | 解析后异步从已有标签中选择 |
| model_id | 空 | 回退知识库 summary_model_id |
| max_tags | 3 | 最多 10 个 |
| skip_if_tagged | true | 已有标签则跳过;false 允许补充标签 |
`auto_tag_config`(自动标签):
开启后对新解析/重新解析的文档生效,不自动扫描全部旧文档。无候选标签或无可用模型时不阻断入库。更新示例:
| 字段 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `enabled` | bool | false | 解析后异步从已有标签中选择 |
| `model_id` | string | 空 | 为空时使用知识库 `summary_model_id` |
| `max_tags` | int | 3 | 每篇最多关联数量,上限 10 |
| `skip_if_tagged` | bool | true | 已有标签则跳过;false 允许补充标签 |
开启后对新解析/重新解析的文档生效,不自动扫描全部旧文档。无候选标签或无可用模型时不阻断入库。
`profile_config`(AI 知识库描述):
| 字段 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `enabled` | bool | false | 开启后,文档新增、删除、移动或摘要更新会自动刷新 `generated_profile` |
| `model_id` | string | 空 | 为空时使用知识库 `summary_model_id` |
| `custom_instructions` | string | 空 | 追加到生成提示词的补充要求 |
`generated_profile` 为只读字段,由系统写入,不覆盖手写 `description`;也可通过下文的 `profile/generate` 立即生成。更新示例:
```bash
curl -X PUT "$BASE/api/v1/knowledge-bases/kb-1" \
@ -86,7 +100,7 @@ curl $BASE/api/v1/knowledge-bases/kb-1 -H "Authorization: Bearer $TOKEN"
| --- | --- | --- | --- |
| `name` | string | 是(`binding:"required"`) | 名称 |
| `description` | string | 否 | 描述 |
| `config` | object | 否 | 局部配置更新(分块/图像/wiki/索引策略) |
| `config` | object | 否 | 局部配置更新:`chunking_config`、`image_processing_config`、`faq_config`、`wiki_config`、`auto_tag_config`、`profile_config`、`indexing_strategy` |
响应:200 `{"success":true,"data":{KnowledgeBase}}`
@ -201,7 +215,7 @@ curl $BASE/api/v1/knowledge-bases/kb-1/move-targets -H "Authorization: Bearer $T
### GET /api/v1/knowledge-bases/:id/files
用途:KB 范围文件代理(渲染共享 KB 内容中的图片;上下文 tenant 已被重写为 KB 属主)。权限:Viewer+,KB read;KB 受限 key 拒绝,全空间 `retrieve`/full key 放行。注册于 `serveKBScopedFiles`(`internal/router/router.go`)。
用途:KB 范围文件代理(渲染共享 KB 内容中的图片;上下文 tenant 已被重写为 KB 属主)。权限:Viewer+,KB read;KB 受限 key 拒绝,全空间 `retrieve`/full key 放行。注册于 `serveKBScopedFiles`(`internal/router/files.go`)。
| 查询参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
@ -230,9 +244,21 @@ multipart/form-data 字段:
| `enable_multimodel` | bool | 否 | 多模态处理开关 |
| `tag_ids` | string | 否 | 逗号分隔标签 ID |
| `channel` | string | 否 | 摄取渠道 |
| `process_config` | JSON 字符串 | 否 | 解析配置覆盖(KnowledgeProcessOverrides) |
| `process_config` | JSON 字符串 | 否 | 解析配置覆盖(KnowledgeProcessOverrides),见下表 |
响应:200 `{"success":true,"data":{Knowledge}}`;重复文件返回 409 且 `data` 为已存在的 Knowledge。
`process_config` 常用字段(均可选,省略时沿用知识库配置):
| 字段 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `summary_enabled` | bool | true | 是否为本次导入的文档生成摘要;关闭后解析、索引及其他处理照常执行 |
| `parser_engine_rules` | []object | 知识库配置 | 按文件类型指定解析引擎 |
| `parser_engine_overrides` | map[string]string | 空 | 引擎参数,如 `pdf_force_scanned` |
| `chunking_config` | object | 知识库配置 | 分块参数 |
| `enable_multimodel` / `vlm_config` / `asr_config` | - | 知识库配置 | 多模态与语音识别 |
| `question_generation_config` | object | 知识库配置 | 问题生成 |
| `graph_enabled` / `extract_config` | - | 知识库配置 | 图谱抽取 |
响应:200 `{"success":true,"data":{Knowledge}}`;重复文件返回 409 且 `data` 为已存在的 Knowledge。正在删除或解析失败的同名文件不计为重复。
```bash
curl -X POST $BASE/api/v1/knowledge-bases/kb-1/knowledge/file \
@ -292,10 +318,12 @@ curl -X POST $BASE/api/v1/knowledge-bases/kb-1/knowledge/manual -H "Authorizatio
| `parse_status` | string | 否 | `pending/processing/completed/failed` |
| `source` | string | 否 | 渠道或 `manual`/`url` |
| `start_time` / `end_time` | string | 否 | RFC3339,按 `updated_at` 过滤 |
| `folder_path` | string | 否 | 按文件夹筛选;空字符串表示知识库根目录,不传则不按文件夹过滤 |
| `folder_recursive` | bool | 否 | 与 `folder_path` 配合,为 `true` 时包含子文件夹中的文档 |
| `sort_by` | string | 否 | 排序字段:`updated_at`、`created_at` 或 `file_name`;默认 `created_at` |
| `sort_order` | string | 否 | 排序方向:`asc` 或 `desc`;默认 `desc` |
未传排序参数时,接口保持原有的 `created_at desc` 行为。显式使用 `updated_at` 时,重新解析、编辑或状态变化会影响顺序;使用 `file_name` 时按展示文件名忽略大小写排序,文件名为空会依次回退到标题和来源。所有排序都会使用知识 ID 作为稳定的次级排序条件,避免相同排序值下翻页结果漂移。
未传排序参数时按 `created_at desc` 排序,取值不在上述范围内返回 400。使用 `updated_at` 时,重新解析、编辑或状态变化会影响顺序;使用 `file_name` 时按展示文件名忽略大小写排序,文件名为空会依次回退到标题和来源。相同排序值按知识 ID 排序,保证翻页结果稳定。
响应:200 `{"success":true,"data":[Knowledge],"total","page","page_size"}`
@ -303,6 +331,30 @@ curl -X POST $BASE/api/v1/knowledge-bases/kb-1/knowledge/manual -H "Authorizatio
curl "$BASE/api/v1/knowledge-bases/kb-1/knowledge?page=1&parse_status=completed" -H "X-API-Key: $API_KEY"
```
### POST /api/v1/knowledge-bases/:id/knowledge/batch-download
用途:把同一知识库中的多个文档原始文件打包为 ZIP 下载。权限与单文件下载相同:Contributor+ 且 KB write(组织共享 Viewer 不可下载);API key `retrieve`/full。
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `ids` | []string | 是 | 知识 ID 列表,1~200 个 |
行为:
- 原始文件合计不超过 512 MiB,超出返回 400;
- 没有原始文件的条目(如网页导入)会被跳过;所选条目都没有原始文件时返回 400;
- ZIP 内保留知识库文件夹结构,重名文件自动加序号;
- 任一 ID 不存在或不属于该知识库返回 404,读取失败返回 500,不会生成缺文件的压缩包;
- 同一实例同时最多处理 4 个批量下载,超出返回 429。
响应:200 `application/zip` 文件流,文件名形如 `knowledge-files-20260923-150405.zip`。
```bash
curl -X POST $BASE/api/v1/knowledge-bases/kb-1/knowledge/batch-download \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"ids":["k-1","k-2"]}' -o knowledge-files.zip
```
### GET /api/v1/knowledge-bases/:id/knowledge/folders
用途:获取知识库的文件夹目录树。整目录上传时目录结构会被保留(migration `000079` 起存在 `knowledges.folder_path` 列,历史 `file_name` 中的路径已回填到该字段)。权限:Viewer+ + KBAccessRead。
@ -491,17 +543,17 @@ curl -X PUT $BASE/api/v1/knowledge/image/k-1/c-1 -H "Authorization: Bearer $TOKE
| 查询参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `q` | string | 否 | 关键字(为空且 `recent=true` 返回最近文件) |
| `file_type` / `file_types` | string | 否 | 类型过滤(后者逗号分隔) |
| `page` / `page_size` | int | 否 | 分页 |
| `recent` | bool | 否 | 最近文件模式 |
| `keyword` / `query` | string | 条件必填 | 关键字(两者等价);为空时必须传 `recent=true`,否则返回 400 |
| `file_types` | string | 否 | 逗号分隔的扩展名过滤,如 `csv,xlsx` |
| `offset` / `limit` | int | 否 | 分页;`limit` 默认 20,范围 1~100 |
| `recent` | bool | 否 | 关键字为空时返回最近文件 |
| `agent_id` | string | 否 | 共享 Agent 范围 |
| `agent_source_tenant_id` | uint64 | 否 | 共享 Agent 的来源空间选择器,与共享关系校验 |
响应:200 `{"success":true,"data":[Knowledge]}`
响应:200 `{"success":true,"data":[Knowledge],"has_more":bool,"total":N}`
```bash
curl "$BASE/api/v1/knowledge/search?q=报告&recent=false" -H "Authorization: Bearer $TOKEN"
curl "$BASE/api/v1/knowledge/search?keyword=报告&limit=20" -H "Authorization: Bearer $TOKEN"
```
### GET /api/v1/knowledge/move/progress/:task_id

View File

@ -41,7 +41,7 @@ curl -X PUT "$BASE/api/v1/memory/settings" \
| POST | `/memory/items` | `{kind,content,importance}`;200 `{success,data:MemoryItem}` |
| PUT | `/memory/items/:id` | `{content,importance}`;200 `{success,data:MemoryItem}` |
| DELETE | `/memory/items/:id` | 200 `{"success":true}` |
| POST | `/memory/items/:id/confirm` | 200 `{success,data:MemoryItem}` |
| POST | `/memory/items/:id/confirm` | 200 `{success,data:MemoryItem}`;推断已失效或其依据已被修改时返回 409 |
| POST | `/memory/items/:id/reject` | 200 `{"success":true}` |
| DELETE | `/memory/items` | 清空当前身份;200 `{success,removed}` |
@ -49,6 +49,8 @@ curl -X PUT "$BASE/api/v1/memory/settings" \
MemoryItem 包括 `id`、`kind`、`content`、`topic`、`importance`、`origin`、`status`、`source_session_id`、`source_message_id`、`expires_at`、`superseded_by` 和创建/修改时间。pending 不参与提示词;编辑后按手工维护处理。
用于修改已有记忆的 pending 推断,确认前旧条目继续生效;确认会在同一事务中激活推断并替换旧条目。已失效、已到期或所依据内容已被修改/删除的推断不能确认,返回 409,客户端应刷新列表。内容几乎全是凭据等敏感信息时,新增或编辑返回 400。
```bash
curl -X POST "$BASE/api/v1/memory/items" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
@ -93,4 +95,4 @@ curl "$BASE/api/v1/memory/export" -H "Authorization: Bearer $TOKEN" \
curl -X POST "$BASE/api/v1/memory/consolidate" -H "Authorization: Bearer $TOKEN"
```
参数无效返回 400;找不到当前身份的条目返回 404;认证/权限不满足返回 401/403。接口没有管理员读取他人记忆的 subject 参数。实现:`internal/handler/memory.go`、`internal/router/routes_memory.go`。
参数无效、内容为敏感信息或记忆未开启时返回 400;找不到当前身份的条目返回 404;确认冲突返回 409;认证/权限不满足返回 401/403。接口没有管理员读取他人记忆的 subject 参数。实现:`internal/handler/memory.go`、`internal/router/routes_memory.go`。

View File

@ -10,7 +10,7 @@ API key:`manage_models` 或 full-access。
### GET /api/v1/models/providers
用途:厂商目录(前端据此动态渲染厂商下拉、图标、额外字段与模型选择)。权限:Viewer+。查询参数:`model_type`(可选:`chat/embedding/rerank/vllm/asr`)。Handler: `internal/handler/model_catalog.go`
用途:厂商目录(前端据此动态渲染厂商下拉、图标、额外字段与模型选择)。权限:Viewer+。查询参数:`model_type`(可选:`chat/embedding/rerank/vllm/asr`,也接受 `KnowledgeQA` 等后端取值;未知取值返回 400),指定后只返回支持该类型的厂商及该类型的模型。Handler: `internal/handler/model_catalog.go`
响应:200 `{"success":true,"data":[ModelProviderDTO]}`,每项:
@ -19,20 +19,28 @@ API key:`manage_models` 或 full-access。
| `value` / `label` / `labels` / `description` / `descriptions` / `website` | 厂商 id、品牌名、按语言的名称与描述 |
| `icon` | `data:image/svg+xml;base64,...`,可直接用于 `<img src>` |
| `api` / `auth` / `requiresAuth` | 默认协议(`openai-completions` 等)、鉴权方式、是否需要密钥 |
| `defaultUrls` / `modelTypes` | 按模型类型的默认地址与支持的类型 |
| `extraFields` | 厂商额外配置字段定义(`key,label,type,required,default,options,model_types,secret`),值存入 `parameters.extra_config` |
| `models` | 内置模型目录(`id,name,type,api,reasoning,input,context_window,max_output_tokens,dimension,thinking_levels,cost`) |
| `defaultUrls` / `modelTypes` | 按模型类型的默认地址与支持的类型。`defaultUrls` 仅对 Admin+(或 full-access / `manage_tenant_settings` API key)返回,其他调用方为空 |
| `extraFields` | 厂商额外配置字段定义(`key,label,labels,type,required,default,placeholder,options,model_types,secret`),值存入 `parameters.extra_config` |
| `credentialLabels` | 部分模型类型下凭证输入框的名称与提示(如火山引擎、LKEAP 重排的 API Key 一栏实为 Access Key ID / SecretId) |
| `models` | 内置模型目录(`id,name,type,api,reasoning,input,context_window,max_output_tokens,dimension,thinking_levels,cost,source`),`source` 为该模型参数所依据的厂商文档链接 |
| `thinking` | 厂商级思考编码摘要(`format`、`levels`) |
| `order` | 列表排序值 |
```bash
curl "$BASE/api/v1/models/providers?model_type=chat" -H "Authorization: Bearer $TOKEN"
```
### GET /api/v1/models/catalog/resolve
### GET|POST /api/v1/models/catalog/resolve
用途:按厂商、模型名、`base_url` 与 `extra_config` 解析有效接入配置(协议、思考等级、上下文),供模型编辑器实时展示。权限:Viewer+。查询参数:`provider`(必填)、`model`、`base_url`、`model_type`、`api`、`thinking_control`、`remote_model_name`。
用途:按厂商、模型名、`base_url` 与 `extra_config` 解析有效接入配置(协议、思考等级、上下文),供模型编辑器实时展示。权限:Viewer+。
响应:200 `{"success":true,"data":{provider,api,base_url,remote_model,cataloged,model,capabilities}}`,其中 `capabilities` 为 `{provider,api,cataloged,reasoning,thinking_levels,thinking_format,input,context_window,max_output_tokens,max_tokens_field}`。同一结构也随对话/视觉模型的 `ModelResponse.capabilities` 返回。
参数(GET 用查询参数,POST 用 JSON 请求体,字段相同):`provider`(厂商 ID)、`model`、`base_url`、`model_type`(默认 `chat`)、`api`、`thinking_control`、`remote_model_name`,以及该厂商声明的非密钥额外字段(如 Azure 的 `api_version`)。POST 请求体还可带 `spec` 对象(与模型 `parameters.spec` 相同),用于预览单行目录覆盖。密钥类字段一律不接受。
响应:200 `{"success":true,"data":{provider,api,remote_model,cataloged,model,capabilities,base_url,url}}`,其中 `capabilities` 为 `{provider,api,cataloged,reasoning,thinking_levels,thinking_format,input,context_window,max_output_tokens,max_tokens_field}`。`base_url` 与 `url`(实际请求地址,仅自行计算地址的厂商返回,如 Azure)只对 Admin+(或 full-access / `manage_tenant_settings` API key)返回。无法解析时返回 400。同一 `capabilities` 结构也随远程对话/视觉模型的 `ModelResponse.capabilities` 返回。
```bash
curl "$BASE/api/v1/models/catalog/resolve?provider=deepseek&model=deepseek-v4-pro" -H "Authorization: Bearer $TOKEN"
```
### POST /api/v1/models
@ -42,16 +50,18 @@ curl "$BASE/api/v1/models/providers?model_type=chat" -H "Authorization: Bearer $
| --- | --- | --- | --- |
| `name` | string | 是(`binding:"required"`) | 模型名 |
| `display_name` | string | 否 | 显示名 |
| `type` | string | 是(`binding:"required"`) | 模型类型 |
| `source` | string | 是(`binding:"required"`) | 来源(local/remote…) |
| `type` | string | 是(`binding:"required"`) | 模型类型:`KnowledgeQA` / `Embedding` / `Rerank` / `VLLM` / `ASR`(按原样保存,不接受 `chat` 等前端写法) |
| `source` | string | 是(`binding:"required"`) | 来源(`local` / `remote`) |
| `description` | string | 否 | 描述 |
| `parameters` | object | 是(`binding:"required"`) | 连接参数(base_url 等;密钥经 credentials 子资源管理) |
| `parameters` | object | 是(`binding:"required"`) | 连接参数(`base_url`、`provider`、`extra_config`、`spec`、`context_window` 等,字段见[模型管理](../03-features/06-models.md#模型配置字段))。创建时可直接带 `api_key` / `app_secret`,之后经 credentials 子资源修改 |
响应:201 `{"success":true,"data":{ModelResponse}}`(`id,name,type,source,parameters,is_default,is_builtin,status,credentials,...`)
`parameters` 会按模型目录校验(未知协议、错误的 compat 键、非法思考等级返回 400),`base_url` 经过 SSRF 校验。
响应:201 `{"success":true,"data":{ModelResponse}}`(`id,name,type,source,parameters,is_default,is_builtin,status,credentials,capabilities,...`;响应不含密钥)
```bash
curl -X POST $BASE/api/v1/models -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"name":"gpt-4o-mini","type":"chat","source":"remote","parameters":{"base_url":"https://api.openai.com/v1"}}'
-d '{"name":"gpt-5.5","type":"KnowledgeQA","source":"remote","parameters":{"provider":"openai","base_url":"https://api.openai.com/v1","api_key":"sk-..."}}'
```
### GET /api/v1/models
@ -76,7 +86,7 @@ curl $BASE/api/v1/models/m-1 -H "Authorization: Bearer $TOKEN"
### POST /api/v1/models/:id/debug
用途:调试已保存模型(发起真实上游调用,产生费用)。权限:Admin+。form-data 字段:`input`(≤64KB)、`options`(JSON 编码调试选项)、`documents`(JSON 数组,≤100 条)、`file`(可选)。
用途:调试已保存模型(发起真实上游调用,产生费用)。权限:Admin+。form-data 字段:`input`(≤64KB)、`options`(JSON 编码调试选项:`system_prompt`、`temperature`(0~2)、`top_p`、`max_tokens`(1~8192)、`thinking`、`reasoning_effort`(`off/auto/minimal/low/medium/high/xhigh/max`,设置后覆盖 `thinking`))、`documents`(JSON 数组,≤100 条)、`file`(可选)。
响应:200 `{"success":true,"data":{"ok",elapsed_ms,request,raw_response,observations,error}}`
@ -310,9 +320,10 @@ curl $BASE/api/v1/initialization/ollama/download/tasks -H "Authorization: Bearer
| `modelName` | string | 是 | 模型名 |
| `baseUrl` / `apiKey` / `appSecret` | string | 否 | 连接参数 |
| `provider` / `interfaceType` | string | 否 | 厂商/接口类型 |
| `dimension` | int | 否 | embedding 维度 |
| `dimension` / `supportsDimensionOverride` | int / bool | 否 | embedding 维度;是否在请求中指定维度 |
| `customHeaders` / `extraConfig` | map | 否 | 扩展 |
| `modelId` | string | 否 | 从已存模型取密钥 |
| `spec` | object | 否 | 单行目录覆盖,与模型 `parameters.spec` 相同 |
| `modelId` | string | 否 | 已存模型 ID:请求中缺失的密钥、`extraConfig` 与 `spec` 从该模型补齐 |
| 端点 | 用途 | 响应 data |
| --- | --- | --- |
@ -403,4 +414,4 @@ curl "$BASE/api/v1/evaluation?task_id=task-1" -H "Authorization: Bearer $TOKEN"
## 实现参考
路由注册:`internal/router/router.go` 的 `RegisterModelRoutes`、`RegisterInitializationRoutes`、`RegisterEvaluationRoutes`、`RegisterWeKnoraCloudRoutes`。Handler:`internal/handler/model.go`、`internal/handler/model_credentials.go`、`internal/handler/initialization.go`、`internal/handler/evaluation.go`、`internal/handler/weknoracloud.go`。
路由注册:`internal/router/router.go` 调用 `RegisterModelRoutes`、`RegisterInitializationRoutes`、`RegisterEvaluationRoutes`、`RegisterWeKnoraCloudRoutes`(定义在 `internal/router/routes_infra.go`)。Handler:`internal/handler/model.go`、`internal/handler/model_catalog.go`、`internal/handler/model_credentials.go`、`internal/handler/initialization.go`、`internal/handler/evaluation.go`、`internal/handler/weknoracloud.go`。

View File

@ -176,25 +176,24 @@ curl -X POST $BASE/api/v1/organizations/org-1/invite-code -H "Authorization: Bea
### GET /api/v1/organizations/:id/search-tenants
用途:搜索可邀请的空间(返回按空间分组的候选)。权限:Admin+。
用途:按空间 ID 解析可邀请的空间。权限:Admin+,且调用者空间须为组织 admin。自 v0.8.2 起只接受完整的空间 ID,不再按空间名称跨空间搜索,`limit` 参数已移除。
| 查询参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `q` | string | 是 | 空间名关键字 |
| `limit` | int | 否 | 默认 10,上限 50 |
| `q` | string | 是 | 完整的空间 ID |
响应:200 `{"success":true,"data":[{"tenant_id","tenant_name"}]}`
响应:200 `{"success":true,"data":[{"tenant_id","tenant_name"}]}`。`q` 不是有效 ID、空间不存在或已是组织成员时返回空数组,否则返回唯一候选。
```bash
curl "$BASE/api/v1/organizations/org-1/search-tenants?q=demo" -H "Authorization: Bearer $TOKEN"
curl "$BASE/api/v1/organizations/org-1/search-tenants?q=10002" -H "Authorization: Bearer $TOKEN"
```
### GET /api/v1/organizations/:id/search-users
用途:已废弃别名,行为同 `search-tenants`(返回空间分组结果)。权限:Admin+。参数同上。
用途:已废弃别名,行为同 `search-tenants`。权限:Admin+。参数同上。
```bash
curl "$BASE/api/v1/organizations/org-1/search-users?q=demo" -H "Authorization: Bearer $TOKEN"
curl "$BASE/api/v1/organizations/org-1/search-users?q=10002" -H "Authorization: Bearer $TOKEN"
```
### POST /api/v1/organizations/:id/invite
@ -449,4 +448,4 @@ curl -X POST $BASE/api/v1/shared-agents/disabled -H "Authorization: Bearer $TOKE
## 实现参考
路由注册:`internal/router/router.go` 的 `RegisterOrganizationRoutes`。Handler:`internal/handler/organization.go`。
路由注册:`internal/router/routes_agent.go` 的 `RegisterOrganizationRoutes`。Handler:`internal/handler/organization.go`。

View File

@ -1,6 +1,6 @@
# API 参考:沙箱、技能与个人变量
管理沙箱配置、技能目录、安装任务和个人环境变量。路径均以 `/api/v1` 为前缀;示例中的 `$BASE` 为服务地址,`$TOKEN` 为当前用户的 Bearer token。界面操作步骤见[技能目录与沙箱](../03-features/22-skills-sandbox.md)。
管理沙箱配置、技能目录、安装任务、会话交互终端和个人环境变量。路径均以 `/api/v1` 为前缀;示例中的 `$BASE` 为服务地址,`$TOKEN` 为当前用户的 Bearer token。界面操作步骤见[技能目录与沙箱](../03-features/22-skills-sandbox.md)。
## 权限
@ -9,7 +9,8 @@
| 沙箱配置列表/详情 | Viewer+;API Key 必须 full-access | Admin+;API Key 必须 full-access |
| 沙箱实例清单、已安装技能及文件 | Admin+ | Admin+;API Key 必须 full-access |
| 技能目录列表 | Viewer+,JWT | 目录增删、安装、包文件浏览需 Admin+;写组的 API Key 必须 full-access |
| `/skills` 可用技能 | Viewer+,JWT | 只读,查询参数 sandbox_config_id |
| `/skills` 可用技能 | Viewer+,JWT | 只读,查询参数 sandbox_config_id;共享智能体另传 agent_id、agent_source_tenant_id |
| 会话交互终端 | 会话属主,仅登录 JWT | 取票据后建立 WebSocket |
| `/me/env-vars*` | 已登录的当前调用者 | 仅修改自己,服务端推导身份;无额外管理员门槛,使用 Bearer JWT |
跨空间 ID 不授予访问权。个人变量接口不能替代空间技能管理接口。
@ -25,7 +26,7 @@
| DELETE | `/sandbox-configs/:id` | 可选 `force=true`;200 `{success:true}` |
| GET | `/sandbox-configs/:id/sandboxes` | 200 `{success,data:SandboxInventory}`,包含占用和关联智能体 |
| PUT | `/sandbox-configs/workspace-policy` | `{"scripts_disabled":true}`;返回 success/workspace_scripts_disabled |
| POST | `/sandbox-configs/templates/query` | `{config,config_id?,ensure_standard?,replace_standard?}`;查询远端模板,可创建/替换标准模板 |
| POST | `/sandbox-configs/templates/query` | `{config,config_id?,ensure_standard?,replace_standard?,ensure_desktop?,replace_desktop?}`;查询远端模板,可创建/替换标准模板或桌面模板,replace 需要 config_id |
ConfigResponse 为 `{id,name,description,sandbox_type,config,created_at,updated_at}`,凭据脱敏。编辑时以保存的配置为基础更新;脱敏占位值保留旧凭据,`skill_image` 由安装服务维护,客户端不能替换。
@ -33,8 +34,10 @@ ConfigResponse 为 `{id,name,description,sandbox_type,config,created_at,updated_
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `sandbox_type` | string | docker/cube/e2b;local 已移除 |
| `sandbox_type` | string | docker/cube/e2b;local 已移除;Lite 桌面的 host 不能保存为配置 |
| `default_timeout_sec` | int | 执行超时,0 使用内置默认 |
| `terminal_idle_disconnect_sec` | int | 终端/桌面无操作多久断开,0 为默认 900 秒,生效范围 60 秒–24 小时 |
| `desktop_enabled` | bool | 声明所选模板是 Cube/E2B 桌面模板;已安装技能后不能切换 |
| `allow_private_endpoints` | bool | 允许私网集群地址,不放行 link-local/云元数据 |
| `env_vars` | map[string]string | 该沙箱配置的环境,值加密保存 |
| `skill_rollout` | string | next_turn(默认)/new_session |
@ -103,7 +106,7 @@ curl -X POST "$BASE/api/v1/system/sandbox-check" \
| 方法 | 路径 | 请求 / 响应 |
| --- | --- | --- |
| GET | `/skills/catalog` | 200 `{success,data:[CatalogItem]}` |
| GET | `/skills/catalog` | 200 `{success,data:[CatalogItem]}`;CatalogItem 含 `installations:[{sandbox_config_id,status,enabled,version,bundle_sha256,served?,...}]` |
| POST | `/skills/catalog` | multipart `file` 或 JSON `{"source":"@owner/slug"}`;201 `{success,data:{id,name,version,description}}` |
| POST | `/skills/catalog/:id/install` | `{"sandbox_config_ids":["cfg-1","cfg-2"]}`;202 `{success,data:{installs,errors?}}` |
| GET | `/skills/catalog/:id/files` | 200 `{success,data:[FileEntry]}` |
@ -131,8 +134,10 @@ curl -X POST "$BASE/api/v1/skills/catalog/catalog-1/install" \
| GET | 空 | `{success,data:[SkillResponse]}` |
| POST | 空 | ZIP file 或 source JSON 安装;202 `{success,data:{skill_id}}` |
| GET | `/:skillId` | `{success,data:SkillResponse}` |
| POST | `/:skillId/reinstall` | 复用包重装;202 `{success,data:{skill_id}}` |
| POST | `/:skillId/reinstall` | 复用包重装,可选 `{"instructions":"..."}`(≤10000 字符)作为安装说明;202 `{success,data:{skill_id}}` |
| POST | `/:skillId/stop` | 停止安装;200 返回技能状态,已 failed 可重复调用,其他非 installing 状态拒绝 |
| GET | `/:skillId/guidance` | 当前安装运行的说明:`{success,data:{accepting,messages:[{id,content,status}]}}` |
| POST | `/:skillId/guidance` | 安装进行中追加说明 `{expected_message_id,steer_id,content}`:`expected_message_id` 取 SkillResponse 的 `install_message_id`,`steer_id` 为客户端生成的 UUID(重试不会重复追加),`content` 1–10000 字符;202 `{success:true}`,安装已换轮次返回 409 |
| PATCH | `/:skillId` | `enabled?`、`envs?`;省略不修改 |
| DELETE | `/:skillId` | 从此沙箱卸载,保留目录包 |
| GET | `/:skillId/files` | 文件清单 |
@ -140,7 +145,7 @@ curl -X POST "$BASE/api/v1/skills/catalog/catalog-1/install" \
| GET | `/:skillId/install-events` | SSE 安装进度 |
| GET | `/:skillId/transcript` | SSE 安装过程事件 |
SkillResponse 包括 id/name/version/description/enabled/status/error/bundle_sha256/installed_snapshot_id/install_session_id/install_message_id/created_at/updated_at,以及 `envs:[{name,description,required,is_set}]`。文件响应可为 UTF-8 文本、小图片的 base64 或二进制元数据,不能假定所有文件都有文本内容。
SkillResponse 包括 id/name/version/description/enabled/status/error/bundle_sha256/installed_snapshot_id/install_session_id/install_message_id/created_at/updated_at,以及 `envs:[{name,description,required,is_set}]`。升级或重装进行中、或失败后,`served:{version}` 标明沙箱仍在提供的上一个就绪版本;智能体可用技能以该版本为准。文件响应可为 UTF-8 文本、小图片的 base64 或二进制元数据,不能假定所有文件都有文本内容。
PATCH 的 envs 只更新已声明变量;未声明名称忽略,空字符串清除值、保留声明。
@ -157,6 +162,45 @@ curl -N "$BASE/api/v1/sandbox-configs/cfg-1/skills/skill-1/install-events" \
`GET /skills?sandbox_config_id=cfg-1` 返回可用于智能体的技能元数据 `{success,data:[{name,description}],skills_available}`,与管理员看到的全部安装记录不同。
同时传 `agent_id` 和 `agent_source_tenant_id`(共享智能体的来源空间 ID)时,列出该共享智能体可 @ 的技能:沙箱配置取自智能体本身,忽略查询中的 `sandbox_config_id`;智能体技能范围为 `selected` 时只返回指定技能,禁用时返回空列表且 `skills_available:false`。调用者无权使用该智能体时返回 403。
## 会话交互终端
对话侧栏的终端通过 WebSocket 连接本会话的远程沙箱,仅 Cube/E2B 支持。路由由 `internal/router/routes_chat.go` 注册,尚未进入 Swagger;桌面接口见[会话 API](02-api-chat.md#sandbox-desktop),代理要求见[沙箱部署](../06-development/04-sandbox-deployment.md#交互终端与图形桌面)。
### POST /api/v1/sessions/:session_id/sandbox/terminal-ticket
签发两分钟有效的握手票据。需要会话属主的登录 Bearer access token,API Key 不能调用。
```bash
curl -X POST "$BASE/api/v1/sessions/$SESSION_ID/sandbox/terminal-ticket" \
-H "Authorization: Bearer $TOKEN"
```
响应:200 `{"success":true,"data":{"ticket":"<ticket>","expires_in":120}}`。
### GET /api/v1/sessions/:id/sandbox/terminal
WebSocket 握手,不走普通认证中间件:
| 查询参数 | 必填 | 说明 |
| --- | --- | --- |
| `ticket` | 是 | 上一步取得的票据,绑定用户、空间、会话和签发时的 access token |
| `provision` | 否 | `1` 表示允许创建或唤醒沙箱(可能计费);省略时只连接正在运行的沙箱 |
| `agent_id` / `agent_source_tenant_id` | 否 | 与 `provision=1` 一起使用,指定按哪个智能体(含共享智能体)的沙箱配置创建 |
| `cols` / `rows` | 否 | 初始终端尺寸 |
| `pty_id` | 否 | 重新接上之前 `ready` 帧返回的 Shell 进程 |
连接后,二进制帧双向传输终端输入输出;文本帧为 JSON 控制消息:服务端发送 `ready`(含 `pty_id`、`backend`)、`exited`(含 `exit_code`)和 `error`,客户端可发送 `{"type":"resize","cols":..,"rows":..}`。错误码包括 `SANDBOX_NOT_BOUND`、`SANDBOX_PAUSED`、`TERMINAL_UNSUPPORTED`、`IDLE_DISCONNECTED`、`AUTH_REVOKED`、`INTERNAL`。每个会话最多同时 5 个终端,超出返回 429。
## Lite 本机项目目录
仅 Lite 桌面版提供,其他部署返回 404。它在运行 Lite 的电脑上弹出系统目录选择框,用户选定的目录会加入已批准列表;随后创建会话时把返回的 `dir` 作为 `project_dir` 传入,即可让该会话在[本机沙箱](../03-features/22-skills-sandbox.md#lite-host)中使用这个目录。`project_dir` 字段见[会话 API](02-api-chat.md)。
| 方法 | 路径 | 请求 / 响应 |
| --- | --- | --- |
| POST | `/system/host-project-dir` | 无请求体;200 `{"code":0,"msg":"success","data":{"dir":"/Users/me/project"}}`,取消选择时 `dir` 为空。仅接受登录 JWT,Viewer+,API Key 被拒绝 |
## 个人环境变量
调用者身份由当前认证上下文确定,不接收 user_id。个人接口返回变量名、来源及更新时间,不返回明文。
@ -181,4 +225,4 @@ curl -X DELETE "$BASE/api/v1/me/env-vars/skill" \
-d '{"skill_id":"skill-1","name":"API_TOKEN"}'
```
覆盖顺序为个人技能值 > 个人沙箱值 > 空间技能值。写入个人值不会更改管理员配置。实现参考:`internal/router/routes_infra.go`、`routes_agent.go`、`routes_auth_tenant.go`,以及 `internal/handler/sandbox_config.go`、`sandbox_skill.go`、`skill_catalog.go`、`me_env_var.go`。
覆盖顺序为个人技能值 > 个人沙箱值 > 空间技能值。写入个人值不会更改管理员配置。实现参考:`internal/router/routes_infra.go`、`routes_agent.go`、`routes_auth_tenant.go`,以及 `internal/handler/sandbox_config.go`、`sandbox_skill.go`、`skill_catalog.go`、`me_env_var.go`、`host_project_picker.go`。

View File

@ -16,6 +16,14 @@ Viewer+;API Key 可读。返回 `{code:0,data:{edition,capabilities}}`,每
curl "$BASE/api/v1/system/capabilities" -H "Authorization: Bearer $TOKEN"
```
`capabilities` 中的 `settings.sandbox.host` 表示当前部署能否使用本机操作系统沙箱,目前仅 macOS 原生桌面应用可能为 supported。
### POST /api/v1/system/host-project-dir
用途:在运行 WeKnora 的本机弹出系统文件夹选择框,供新会话绑定本机项目目录(v0.8.2 起,仅原生桌面应用)。权限:Viewer+,仅 JWT,API Key 一律拒绝。无请求体。
响应:200 `{"code":0,"msg":"success","data":{"dir":"/Users/me/project"}}`,用户取消选择时 `dir` 为空字符串;非桌面部署返回 404。
### GET /api/v1/system/info
用途:系统版本与引擎信息。权限:Viewer+。

View File

@ -90,7 +90,7 @@ curl -X PUT $BASE/api/v1/tenants/1 -H "Authorization: Bearer $TOKEN" \
### DELETE /api/v1/tenants/:id
用途:删除空间。权限:Owner;平台 key 需 `system_tenants_manage`。Handler: `internal/handler/tenant.go`
用途:删除空间。权限:Owner;平台 key 需 `system_tenants_manage`。空间记录与全部成员关系被软删除,成员随即失去访问;空间内的知识库、模型等数据不会被立即物理清除,已删除空间排队中的 Wiki 任务不再调用模型。Handler: `internal/handler/tenant.go`
响应:200 `{"success":true,"message":"Workspace deleted successfully"}`
@ -382,4 +382,4 @@ curl $BASE/api/v1/knowledge-bases/kb-1/activity -H "Authorization: Bearer $TOKEN
## 实现参考
路由注册:`internal/router/router.go` 的 `RegisterTenantRoutes`。Handler:`internal/handler/tenant.go`、`internal/handler/tenant_member.go`、`internal/handler/tenant_invitation.go`、`internal/handler/tenant_invite_link.go`、`internal/handler/audit_log.go`。
路由注册:`internal/router/routes_auth_tenant.go` 的 `RegisterTenantRoutes`。Handler:`internal/handler/tenant.go`、`internal/handler/tenant_member.go`、`internal/handler/tenant_invitation.go`、`internal/handler/tenant_invite_link.go`、`internal/handler/audit_log.go`。

View File

@ -116,13 +116,15 @@ flowchart TB
| 路径 | 名称 | 组件 | 功能 |
| --- | --- | --- | --- |
| `/platform/knowledge-bases` | `knowledgeBaseList` | `src/views/knowledge/KnowledgeBaseList.vue` | 知识库列表:空间侧栏(全部/我的/按组织/收藏/最近)、卡片列表、创建入口 |
| `/platform/knowledge-bases/:kbId` | `knowledgeBaseDetail` | `src/views/knowledge/KnowledgeBase.vue` | 知识库详情:文档列表、上传、解析状态、会话入口、Wiki 等 |
| `/platform/agents` | `agentList` | `src/views/agent/AgentList.vue` | 智能体(Agent)列表与管理,编辑走 `AgentEditorModal.vue` |
| `/platform/knowledge-bases` | `knowledgeBaseList` | `src/views/knowledge/KnowledgeBaseList.vue` | 知识库列表:空间侧栏(全部/我的/按组织/收藏/最近)、卡片列表、创建入口;支持按更新时间 / 创建时间 / 名称排序(`components/ResourceSortControl.vue`,智能体列表同样适用) |
| `/platform/knowledge-bases/:kbId` | `knowledgeBaseDetail` | `src/views/knowledge/KnowledgeBase.vue` | 知识库详情:文档列表(可按更新时间 / 创建时间 / 文件名排序,排序在服务端完成,默认创建时间倒序)、上传、解析状态、会话入口、Wiki 等 |
| `/platform/agents` | `agentList` | `src/views/agent/AgentList.vue` | 智能体(Agent)列表与管理,编辑走 `AgentEditorModal.vue`;需部署能力 `agents` |
| `/platform/toolbox/:section?` | `toolbox` | `src/views/toolbox/Toolbox.vue` | 工具箱:`skills`(技能)、`mcp`(MCP 服务)、`browserconnection`(浏览器连接)三个标签页,见下方「工具箱」 |
| `/platform/artifacts` | `artifactLibrary` | `src/views/artifacts/ArtifactLibrary.vue` | 产物库:汇总智能体在各会话中生成的文件;需部署能力 `settings.sandbox` |
| `/platform/creatChat` | `globalCreatChat` | `src/views/creatChat/creatChat.vue` | 新建对话页:推荐问题、选择知识库/Agent/模型后发起会话 |
| `/platform/knowledge-bases/:kbId/creatChat` | `kbCreatChat` | `src/views/creatChat/creatChat.vue` | 从某个知识库上下文发起新对话(同一组件) |
| `/platform/chat/:chatid` | `chat` | `src/views/chat/index.vue` | 会话页:消息流(SSE 流式渲染、骨架屏、虚拟滚动)、引用面板、附件预览 |
| `/platform/organizations` | `organizationList` | `src/views/organization/OrganizationList.vue` | 组织列表:创建/加入组织、成员与共享资源管理(配合 `OrganizationSettingsModal.vue`) |
| `/platform/organizations` | `organizationList` | `src/views/organization/OrganizationList.vue` | 组织列表:创建/加入组织、成员与共享资源管理(配合 `OrganizationSettingsModal.vue`);需部署能力 `organizations`,Lite 版始终隐藏。添加成员时按完整空间 ID 精确查找,不再按空间名模糊搜索 |
| `/platform/settings` | `settings` | `src/views/settings/Settings.vue` | 设置中心(全屏模态形态),分区见下方「设置中心的分区与可见性」 |
| `/platform/tenant` | — | 重定向 | 兼容旧路径 → `/platform/settings` |
| `/platform/knowledge-search` | — | 重定向 | 旧全局搜索路径 → 知识库列表并通过 `?cmdk=` 打开全局命令面板(⌘K) |
@ -140,19 +142,41 @@ flowchart TB
| 分组 | 分区(`section` 值) |
| --- | --- |
| 账户 | `general`(个人偏好)、`userprofile` |
| 空间 | `tenant`(空间信息)、`members`(成员)、`chathistory` |
| 账户 | `general`(个人偏好)、`userprofile`、`mymemory`(个人记忆)、`envvars`(个人变量) |
| 空间 | `tenant`(空间信息)、`members`(成员)、`chathistory`、`memory`(空间记忆) |
| 模型与运行 | `models`、`ollama`、`weknoracloud` |
| 发布与集成 | `integration-im`、`integration-embed`、`integration-api`、`integration-chrome`、`integration-claw` |
| 数据与扩展 | `vectorstore`、`parser`、`storage`、`websearch`、`mcp` |
| 发布集成 | `integration-im`、`integration-embed`、`integration-api`、`integration-mcpserver`、`integration-cli`、`integration-chrome`、`integration-claw` |
| 数据与扩展 | `vectorstore`、`parser`、`storage`、`sandbox`、`websearch` |
| 系统管理 | `system-global`、`runtime-queues`、`platform-api-keys`、`system-audit-log` |
| 平台 | `system`(版本信息) |
可见性由两套规则决定,且**前端只做收敛展示,后端路由守卫才是权威**:
发布集成的标签页由 `frontend/src/config/integrations.ts` 的 `INTEGRATION_TABS` / `INTEGRATION_PREVIEW_ITEMS` 注册,分区值统一为 `integration-<tab>`;旧的 `/platform/integrations?tab=<tab>` 会被归一成对应分区。
- **空间角色门槛**:`frontend/src/config/settingsAccess.ts` 的 `SETTINGS_SECTION_MIN_ROLE` 给每个分区规定最低角色。`general` / `models` / `system` / `userprofile` / `tenant` / `members` 是 `viewer` 起(只读可见),其余(`ollama`、`weknoracloud`、`websearch`、`chathistory`、`vectorstore`、`parser`、`storage`、`mcp`)要求 `admin`。另有 `SETTINGS_MANAGEMENT_SHORTCUT_MIN_ROLE`:头像菜单里那些标着「管理」的快捷入口门槛更高(成员管理要 `owner`,模型管理要 `admin`),避免把只读页面伪装成管理入口。
自 v0.8.2 起,技能、MCP 服务与浏览器连接不再是设置分区,而是移到[工具箱](#工具箱)。旧书签 `/platform/settings?section=skills|mcp|browserconnection` 会被路由守卫重定向到 `/platform/toolbox/<section>`(`skills` 会保留 `sandboxId` 参数)。
可见性由三套规则决定,且**前端只做收敛展示,后端路由守卫才是权威**:
- **空间角色门槛**:`frontend/src/config/settingsAccess.ts` 的 `SETTINGS_SECTION_MIN_ROLE` 给每个分区规定最低角色。`general` / `models` / `system` / `userprofile` / `tenant` / `members` / `mymemory` / `envvars` 是 `viewer` 起(只读可见),`ollama`、`weknoracloud`、`websearch`、`chathistory`、`memory`、`vectorstore`、`parser`、`storage`、`sandbox` 要求 `admin`;发布集成中的 `integration-api` 要求 `owner`(`INTEGRATION_TAB_MIN_ROLE`)。另有 `SETTINGS_MANAGEMENT_SHORTCUT_MIN_ROLE`:头像菜单里那些标着「管理」的快捷入口门槛更高(成员管理要 `owner`,模型管理要 `admin`),避免把只读页面伪装成管理入口。
- **部署能力**:`frontend/src/config/deploymentCapabilities.ts` 的 `SETTINGS_SECTION_CAPABILITY` / `INTEGRATION_TAB_CAPABILITY` 把分区映射到 `GET /api/v1/system/capabilities` 返回的能力键(如 `settings.sandbox`、`integrations.mcpserver`),能力明确为 `supported: false` 时隐藏入口,见下方「设置导航与部署能力」。
- **系统管理员白名单**:`SYSTEM_ADMIN_SETTINGS_SECTIONS`(`system-global`、`runtime-queues`、`platform-api-keys`、`system-audit-log`)只对系统管理员显示,与空间角色无关,详见[租户、用户与认证授权](../03-features/01-tenant-auth.md)的「系统管理员与平台控制台」。
### 工具箱
左侧菜单的「工具箱」(`/platform/toolbox/:section?`,`src/views/toolbox/Toolbox.vue`)集中管理智能体可用的工具,标签页定义在 `frontend/src/config/toolbox.ts` 的 `TOOLBOX_ITEMS`:
| 标签页(`section`) | 内容 | 可见条件 |
| --- | --- | --- |
| `skills` | 技能管理(复用 `SkillSettings.vue`),可带 `?sandboxId=` 定位沙箱配置 | `admin` 起,且部署支持 `settings.sandbox` |
| `mcp` | MCP 服务(复用 `McpSettings.vue`) | `admin` 起,且部署支持 `settings.mcp` |
| `browserconnection` | 浏览器连接(复用 `BrowserConnectionSettings.vue`),标签上显示连接状态 | `viewer` 起 |
标签页沿用原设置分区的角色与部署能力门槛(`canAccessToolboxSection`);当前空间没有任何可见标签页时显示空状态。侧栏菜单项悬停时会预览可用工具,浏览器连接状态也会显示在侧栏。浏览器连接的用法见[本地浏览器](09-local-browser.md)。
<Screenshot
src="/screenshots/toolbox.png"
caption="工具箱:在一个页面管理技能、MCP 服务和浏览器连接"
hint="展示左侧菜单「工具箱」入口(含悬停预览的工具图标),以及工具箱页面顶部三个标签页(技能 / MCP 服务 / 浏览器连接,含数量与连接状态),当前停留在技能标签页。" />
### 知识库编辑弹窗的分区
不少配置**不在设置中心,而在知识库编辑弹窗里**(`KnowledgeBaseEditorModal.vue`),因为它们是按库生效的。侧栏分区按五组组织,其中三个只在「编辑已有知识库」时出现:
@ -162,7 +186,7 @@ flowchart TB
| 基础 | `basic`、`models` | 名称、类型、对话/向量/摘要模型 |
| 处理 | `parser`、`multimodal`、`asr`、`chunking` | 解析引擎与首行表头、图片理解、语音转写、分块参数 |
| 数据 | `vectorStore`、`storage`、`faq` | `faq` 仅 FAQ 类型库;`vectorStore` 绑定后不可改 |
| 集成 | `datasource` | **仅编辑模式**,飞书 / Notion / 语雀 / RSS 同步配在这里,不在全局设置里 |
| 集成 | `datasource` | **仅编辑模式**,飞书 / Lark(知识库与云盘)、Notion、Confluence、语雀、钉钉文档、腾讯 IMA、RSS / Atom、GitLab 等同步配在这里,不在全局设置里(连接器定义见 `views/knowledge/settings/DataSourceEditorDialog.vue`) |
| 管理 | `graph`、`advanced`、`share`、`activity` | 知识图谱、高级项、共享到组织、活动流;后两个仅编辑模式 |
### 全局命令面板(⌘K / Ctrl+K)
@ -178,11 +202,13 @@ flowchart TB
`router.beforeEach` 中实现了一条完整的鉴权链(`frontend/src/router/index.ts`):
1. **OIDC 回调放行**:URL hash 含 `oidc_result=` / `oidc_error=` 时直接放行,交由 `App.vue` 消费;
2. **Lite / 桌面端深链恢复**:Lite 模式硬刷新落在默认首页时,从 `sessionStorage` 恢复上次访问的 `/platform` 子路径;
3. **会话恢复**:未登录时先用 `localStorage` 中的 `weknora_token` 调 `getCurrentUser()` 恢复会话(同时刷新 memberships,避免角色变更滞后);
4. **Lite 自动登录**:恢复失败则尝试一次 `autoSetup()`(单机版免登录),失败会在 `localStorage` 打标避免重复尝试;
5. **租户门槛**:已登录但无有效租户 → 跳 `/onboarding/workspace`;
6. **SystemAdmin 门槛**:`requiresSystemAdmin` 路由对非系统管理员跳回知识库列表(仅 UI 层拦截,服务端另有强校验)。
2. **工具箱旧书签**:`/platform/settings?section=skills|mcp|browserconnection` 重定向到 `/platform/toolbox/<section>`;
3. **Lite / 桌面端深链恢复**:Lite 模式硬刷新落在默认首页时,从 `sessionStorage` 恢复上次访问的 `/platform` 子路径(不恢复到组织页);
4. **会话恢复**:未登录时先用 `localStorage` 中的 `weknora_token` 调 `getCurrentUser()` 恢复会话(同时刷新 memberships,避免角色变更滞后);
5. **桌面端自动登录**:恢复失败则尝试一次 `autoSetup()`。自 v0.8.2 起它只在原生桌面端生效:先经 Wails 绑定 `GetAutoSetupToken()` 取得本进程的随机凭据,再以 `X-WeKnora-Desktop-Token` 请求头调用 `POST /api/v1/auth/auto-setup`;浏览器中打开的 Lite 版没有该绑定,直接走普通注册 / 登录。失败会在 `localStorage` 打标避免重复尝试;
6. **租户门槛**:已登录但无有效租户 → 跳 `/onboarding/workspace`;
7. **部署能力门槛**:路由 `meta.requiredCapability`(如 `agents`、`organizations`、`settings.sandbox`)不被当前部署支持时,提示后跳回知识库列表;能力探测失败时放行,由后端接口兜底;
8. **SystemAdmin 门槛**:`requiresSystemAdmin` 路由对非系统管理员跳回知识库列表(仅 UI 层拦截,服务端另有强校验)。
## 状态管理(Pinia)
@ -203,25 +229,34 @@ flowchart TB
| `stores/ui.ts` | `useUIStore` | 全局 UI 状态:设置模态、知识库编辑模态、手工文档编辑器、侧栏折叠等开关与参数 |
| `stores/uploadConfirm.ts` | 上传确认 store | 上传/URL 导入/手工录入/重新解析前的处理参数确认对话框状态 |
| `stores/versionedRequest.ts` | 纯函数模块 | `createVersionedRequestCoordinator`:带版本号的缓存请求协调器,防止旧响应覆盖新写入(配套 `versionedRequest.test.ts`) |
| `stores/deploymentCapabilities.ts` | `useDeploymentCapabilitiesStore` | 部署能力快照(`GET /api/v1/system/capabilities`),供路由守卫、侧栏、设置和工具箱判断入口是否显示 |
| `stores/modelProviders.ts` | `useModelProvidersStore` | 模型厂商目录缓存(`GET /api/v1/models/providers`,按模型类型加载),模型编辑器与模型卡片统一从这里读厂商信息 |
| `stores/uploadTasks.ts`(+ `uploadQueue.ts` / `uploadTasksCore.ts` / `uploadTasksState.ts`) | `useUploadTasksStore` | 知识文件上传队列:限并发传输、取消 / 重试、轮询解析进度,驱动浮动的上传进度面板;离开知识库页面后上传继续 |
| `stores/browserConnection.ts` | `useBrowserConnectionStore` | 本地浏览器连接状态,供工具箱标签与侧栏状态显示 |
| `stores/sessionActivity.ts` | `useSessionActivityStore` | 侧栏会话的进行中状态 |
## API 封装(frontend/src/api/)
### 请求基座
- **axios 实例**:`frontend/src/utils/request.ts` 创建统一实例(`baseURL` 来自 `frontend/src/utils/api-base.ts` 的 `getApiBaseUrl()`,尊重 Vite `BASE_URL` 以支持子路径反代部署;超时 30s)。
- **axios 实例**:`frontend/src/utils/request.ts` 创建统一实例(`baseURL` 来自 `frontend/src/utils/api-base.ts` 的 `getApiBaseUrl()`,尊重 Vite `BASE_URL` 以支持子路径反代部署;普通请求超时 30s)。文件上传(`postUpload`)按载荷大小计算超时(`utils/requestTimeouts.ts` 的 `uploadTimeoutMs`,下限 5 分钟,按约 10MB/分钟放大),调大 `MAX_FILE_SIZE_MB` 后大文件不会被 30s 默认值中断;调用方显式传入的 `timeout` 优先。
- **请求拦截器**:自动附加 `Authorization: Bearer <weknora_token>`(Embed 渠道的 `Embed ` token 不被覆盖)、`Accept-Language`(当前 i18n 语言)、`X-Request-ID`(随机串)、`X-Tenant-ID`(跨空间访问,始终携带激活空间 id 以避免切空间后 header 丢失)。
- **响应拦截器**:2xx 解包返回 `data`;401 触发单飞(single-flight)refresh token 刷新,失败队列重放;公开端点(`/auth/login`、`/auth/auto-setup`、`/auth/invitations/lookup`、`/api/v1/embed/` 等 `PUBLIC_AUTH_PATHS`)的 401 直接抛给页面而不跳登录;Embed 页面永不重定向到 `/login`。
- **SSE 流式**:`frontend/src/api/chat/streame.ts` 基于 `@microsoft/fetch-event-source` 封装 `useStream()`,支持流式输出、加载态、错误态与请求调试元数据;上层由 `frontend/src/composables/useChatStreamHandler.ts` 组织为聊天消息流。
- **响应拦截器**:2xx 解包返回 `data`;401 触发单飞(single-flight)refresh token 刷新,失败队列重放;公开端点(`/auth/login`、`/auth/register`、`/auth/oidc/`、`/auth/auto-setup`、`/auth/invitations/lookup`、`/api/v1/embed/`,即 `PUBLIC_AUTH_PATHS`)的 401 直接抛给页面而不跳登录;Embed 页面永不重定向到 `/login`。
- **HTTP 状态码(`$httpStatus`)**:`get` / `post` / `put` / `patch` / `del` / `postUpload` 的返回类型为 `WithStatus<T>`,JSON 对象或数组响应上挂有不可枚举的 `$httpStatus` 属性,可用来区分成功形状相同的结果(例如系统管理员创建用户:201 表示新建,200 表示幂等重试)。它不出现在对象展开、`JSON.stringify` 与 `Object.keys` 中;Blob、字符串与 SSE 响应不带该属性。
- **SSE 流式**:`frontend/src/api/chat/streame.ts` 基于 `@microsoft/fetch-event-source` 封装 `useStream()`,支持流式输出、加载态、错误态与请求调试元数据;上层由 `frontend/src/composables/useChatStreamHandler.ts` 组织为聊天消息流。聊天流握手返回 401 时,会与 axios 共用 `utils/authRefresh.ts` 的单飞刷新,拿到新 token 后原样重放一次请求,因此 access token 过期不会打断正在发起的对话。
### 模块清单
| 模块 | 职责 |
| --- | --- |
| `api/auth/` | 登录、注册、OIDC、`autoSetup`(Lite 免登录)、`getCurrentUser` 会话恢复 |
| `api/auth/` | 登录、注册、OIDC、`autoSetup`(仅原生桌面端,携带 Wails 提供的 `X-WeKnora-Desktop-Token`)、`getCurrentUser` 会话恢复 |
| `api/tenant/`(`index` / `members` / `invitations` / `audit-log`) | 租户(工作空间)信息、成员管理、邀请、审计日志 |
| `api/organization/` | 组织 CRUD、成员、共享知识库/Agent、加入申请 |
| `api/knowledge-base/` | 知识库 CRUD 与文件/知识条目管理 |
| `api/chat/`(`index` / `streame` / `temporary-attachments`) | 会话 CRUD、标题生成、SSE 流式问答、临时附件 |
| `api/chat/`(`index` / `streame` / `steer` / `temporary-attachments`) | 会话 CRUD、标题生成、SSE 流式问答、向运行中的智能体轮次追加消息(`steer`)、临时附件 |
| `api/artifacts.ts` | 产物库列表与删除(`/api/v1/artifacts`) |
| `api/memory.ts` / `api/env-vars.ts` | 空间 / 个人记忆,个人变量 |
| `api/mcp-endpoint.ts` | 内置 MCP Server 端点管理(发布集成 → MCP Server) |
| `api/chat-history.ts` | 聊天历史记录 |
| `api/agent/` | 自定义 Agent CRUD、类型预设、占位符(含内建 Quick Answer / Smart Reasoning id) |
| `api/model/` | 模型配置管理 |
@ -285,7 +320,7 @@ RAG 流水线的可视化进度(`views/chat/components/RagPipelineProgress.vue
- **双入口构建**:`rollupOptions.input` 同时构建 `index.html`(主 SPA)与 `embed.html`(嵌入页);开发环境用自定义插件 `embedHtmlDevFallback()` 把 `/embed/:channelId` 请求改写到 `/embed.html`,与 nginx 行为对齐。
- **代码分包**:`manualChunks` 将 mermaid/dagre/cytoscape、marked/katex、highlight.js 分别拆为 `vendor-mermaid`、`vendor-markdown`、`vendor-highlight`;embed 入口通过 `modulePreload.resolveDependencies` 过滤重型聊天 chunk,保证嵌入页首屏只加载 token 交换所需代码。
- **版本注入**:`__FRONTEND_VERSION__`(package.json version)与 `__FRONTEND_COMMIT__`(`VITE_FRONTEND_COMMIT` / `GITHUB_SHA` / `git rev-parse`)编译期注入。
- **开发代理**:dev server(端口 5173)与 preview(端口 4173)都把 `/api`、`/files` 代理到 `VITE_DEV_PROXY_TARGET`(或 `FRONTEND_BACKEND_URL`,默认 `http://localhost:8080`)。
- **开发代理**:dev server(端口 5173)与 preview(端口 4173)都把 `/api`、`/files`、`/mcp/` 代理到 `VITE_DEV_PROXY_TARGET`(或 `FRONTEND_BACKEND_URL`,默认 `http://localhost:8080`)。`/api` 开启 WebSocket 转发(沙箱终端等),超时放宽到 180s;`/mcp/` 为内置 MCP Server 的 Streamable HTTP 长连接,超时 1 小时。
- **别名**:`@` → `frontend/src`;并对 `@vue-office/pptx` 做入口文件探测修正。
- 常用脚本:`npm run dev` / `npm run build` / `npm run preview`(用生产构建产物本地起服务,最接近发布镜像的验证环境)/ `npm run type-check` / `npm run test`(tsx --test)。
@ -293,36 +328,55 @@ RAG 流水线的可视化进度(`views/chat/components/RagPipelineProgress.vue
`frontend/Dockerfile`:
- 两阶段构建:digest 锁定的 `node:24-bookworm-slim` 以 `$BUILDPLATFORM` 执行 `npm ci` + `npm run build`(`VITE_IS_DOCKER=true`,`VITE_FRONTEND_COMMIT` 可经 build-arg 注入且须放在 `npm ci` 之后以免打断依赖层缓存;可选 `NPM_REGISTRY` / `NODE_MAX_OLD_SPACE_SIZE`),再拷贝到运行层;
- 自 v0.8.2 起为两阶段构建:digest 锁定的 `node:24-bookworm-slim` 以 `$BUILDPLATFORM` 执行 `npm ci` + `npm run build`,再把 `dist/` 拷贝到运行层。构建时不再需要宿主机安装 Node / npm,也无需预先生成 `dist/`(`scripts/build_frontend_dist.sh` 仍供 Lite / 桌面打包使用);
- 运行层基础镜像固定为 digest 锁定的 `nginx:1.30.3-alpine`(注释明确禁止改回浮动 tag——更新的 Alpine 3.24+ 在 CentOS 7 旧内核上无法启动,曾导致 v0.7.0 故障);
- 无需在宿主机预构建 `dist/`(`scripts/build_frontend_dist.sh` 仍供 Lite / 桌面打包使用);
- `nginx.conf` 作为模板放入 `/etc/nginx/templates/default.conf.template`,暴露 80 端口,入口为 `docker-entrypoint.sh`。
- `nginx.conf` 作为模板放入 `/etc/nginx/templates/default.conf.template`;`/api/`、`/mcp/` 与技能上传共用的代理参数在 `nginx-api-proxy.conf`(原样拷贝为 `/etc/nginx/api-proxy.conf`),http 级片段在 `nginx-http.conf`(去掉查询串的 `api_no_query` 日志格式)。暴露 80 端口,入口为 `docker-entrypoint.sh`。
镜像构建参数:
| 名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `NPM_REGISTRY` | build-arg | 空 | `npm ci` 使用的镜像源,空则用 npm 默认源 |
| `NODE_MAX_OLD_SPACE_SIZE` | build-arg | `4096` | 构建阶段 Node 堆上限(MB),避免 Vite 构建 OOM |
| `VITE_FRONTEND_COMMIT` | build-arg | `unknown` | 注入页面的前端 commit;在 `npm ci` 之后声明,改动它不会使依赖层缓存失效 |
`frontend/docker-entrypoint.sh`(运行时配置注入):
1. 生成 `/usr/share/nginx/html/config.js`,把 `MAX_FILE_SIZE_MB`(默认 50)与 `DEFAULT_LOCALE`(可选,默认空)写入 `window.__RUNTIME_CONFIG__` 供前端运行时读取;entrypoint 仅允许 `zh-CN|en-US|ru-RU|ko-KR|ja-JP`,非法值会被丢弃;
2. 用 `envsubst` 渲染 nginx 模板,可配置环境变量:`MAX_FILE_SIZE_MB`、`DEFAULT_LOCALE`、`APP_HOST`(默认 `app`)、`APP_PORT`(默认 `8080`)、`APP_SCHEME`(默认 `http`,远程 HTTPS 后端可设 `https`);
1. 生成 `/usr/share/nginx/html/config.js`,把 `MAX_FILE_SIZE_MB`、`MAX_SKILL_BUNDLE_SIZE_MB` 与 `DEFAULT_LOCALE` 写入 `window.__RUNTIME_CONFIG__` 供前端运行时读取;
2. 用 `envsubst` 渲染 nginx 模板;
3. 前台启动 nginx。
| 名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `MAX_FILE_SIZE_MB` | 整数(MB) | `50` | 全站请求体上限与前端上传大小上限 |
| `MAX_SKILL_BUNDLE_SIZE_MB` | 整数(MB) | `256` | 只作用于技能 ZIP 上传路由;小于 `MAX_FILE_SIZE_MB` 时抬到该值,最大 512 |
| `DEFAULT_LOCALE` | 字符串 | 空 | 默认界面语言,仅允许 `zh-CN` / `en-US` / `ru-RU` / `ko-KR` / `ja-JP`,其他值被丢弃 |
| `APP_HOST` | 字符串 | `app` | 后端主机名 |
| `APP_PORT` | 整数 | `8080` | 后端端口 |
| `APP_SCHEME` | 字符串 | `http` | 后端协议,远程 HTTPS 后端可设 `https` |
`frontend/nginx.conf` 关键行为:
- **SPA fallback**:`/` 下 `try_files ... /index.html`,且 `index.html` 设置 `no-cache`(避免升级后用户拿到旧版本);带 hash 的 `/assets/*` 设置一年 immutable 缓存;
- **API 代理**:`/api/` 与 `/files` 反代到 `${APP_SCHEME}://${APP_HOST}:${APP_PORT}`,`/api/` 针对 SSE 关闭 `proxy_buffering` / 缓存 / 分块编码,读写超时放宽到 3600s,并配置 3 次 upstream 重试;
- **内置 MCP Server `/mcp/`**:原路径反代到后端,代理参数与 `/api/` 相同,外部 MCP 客户端可直接用网站域名连接 `/mcp/<endpoint_id>`;
- **WebSocket 通道**:`/api/v1/sessions/<id>/sandbox/(terminal|desktop)`(沙箱终端与图形桌面)和 `/api/v1/local-browser/extension`(BrowserSkill 浏览器扩展接入)单独开启 Upgrade,访问日志去掉查询串以免记录握手票据;集群内部路径 `/api/v1/local-browser/internal` 直接返回 404;
- **技能包上传**:`/api/v1/skills/catalog` 与 `/api/v1/sandbox-configs/<id>/skills` 两条集合路由单独使用 `MAX_SKILL_BUNDLE_SIZE`,其他上传端点仍受 `MAX_FILE_SIZE` 限制;
- **资源短链 `/r/`**:`location ^~ /r/` 同样反代到后端。IM 渠道把 `resource://` 图片改写成 `<APP_EXTERNAL_URL>/r/<token>`,缺这段配置时请求会落进 SPA fallback,IM 侧图片显示为空白(详见 [IM 集成](../03-features/12-im-integration.md));
- **嵌入页**:`/embed/*` fallback 到 `embed.html`(独立 location,不继承主站的 `X-Frame-Options: SAMEORIGIN`,因此可被第三方 iframe 加载);`/weknora-widget.js` 是给第三方站点的静态加载器;文件头部另附可选的独立 embed 子域 server 块示例;
- **嵌入页**:`/embed/*` 返回 `embed.html`(独立 location,不继承主站的 `X-Frame-Options: SAMEORIGIN`)。nginx 先经内部子请求 `/_embed-frame-policy` 向后端 `GET /api/v1/embed-frame-policy` 查询该渠道允许的宿主来源,并把返回的 `Content-Security-Policy` 加到响应上;渠道不存在、已停用、没有允许的宿主来源或后端不可达时拒绝加载。自定义反向代理需要保留这一步,否则宿主来源白名单不生效。`/weknora-widget.js` 是给第三方站点的静态加载器;文件头部另附可选的独立 embed 子域 server 块示例;
- 启用 gzip(注释记录了实测收益:低带宽下首屏从 25s 降到 3-5s)及一组安全响应头(`X-Frame-Options`、`X-Content-Type-Options`、`Referrer-Policy` 等,在各 location 内重复声明以规避 nginx `add_header` 不继承的问题)。
## 桌面端(Wails)关联
`frontend/src/wailsjs/` 是 Wails 框架自动生成的绑定代码(文件头标注 "automatically generated. DO NOT EDIT"):
- `wailsjs/go/main/App.d.ts` / `App.js`:Go 侧 `App` 结构体方法的 JS 绑定,包括 `CheckForUpdates` / `AutoCheckForUpdates`(桌面更新检查)、`GetAPIBaseURL` / `GetAPILanBaseURL`、桌面内置 HTTP 服务的端口与对外监听设置(`GetDesktopHTTPPortSetting`、`SetDesktopHTTPBindPublicSetting` 等);
- `wailsjs/go/main/App.d.ts` / `App.js`:Go 侧 `App` 结构体方法的 JS 绑定,包括 `CheckForUpdates` / `AutoCheckForUpdates`(桌面更新检查)、`GetAPIBaseURL` / `GetAPILanBaseURL`、桌面内置 HTTP 服务的端口与对外监听设置(`GetDesktopHTTPPortSetting`、`SetDesktopHTTPBindPublicSetting` 等),以及 `GetAutoSetupToken`(返回桌面进程启动时生成的随机凭据,前端据此调用 `auto-setup` 免登录,见上文导航守卫);
- `wailsjs/runtime/`:Wails runtime API(窗口控制等),前端在浏览器环境下调用会被 try/catch 安静降级(如 `useTheme.ts`)。
桌面应用的窗口内容就是这份前端代码,Lite 模式(`autoSetup` 免登录 + 深链恢复)与 `--wails-draggable` 标记的可拖拽标题区都是为桌面形态准备的适配。
桌面应用的窗口内容就是这份前端代码,桌面端自动登录、深链恢复与 `--wails-draggable` 标记的可拖拽标题区都是为桌面形态准备的适配。
## 设置导航与部署能力
设置入口按任务分组,发布与集成中包含 CLI 等接入页;技能目录、沙箱配置、个人变量与空间/个人记忆提供各自的管理界面。导航应复用 `frontend/src/config/integrations.ts` 等现有注册信息,新增入口需同时检查侧栏分组。
设置入口按任务分组,发布集成中包含 IM、网页嵌入、API、MCP Server、CLI、Chrome 插件、Claw Skill 等接入页;沙箱配置、个人变量与空间 / 个人记忆在设置中心各有管理界面;技能、MCP 服务与浏览器连接在工具箱。新增入口应复用 `frontend/src/config/integrations.ts`、`frontend/src/config/toolbox.ts`、`frontend/src/config/settingsAccess.ts` 等现有注册信息,并同时检查侧栏分组。
`GET /api/v1/system/capabilities` 返回 edition 及能力 supported/reason。前端据实际部署能力隐藏或禁用入口,例如 Docker 沙箱默认受平台开关控制;前端可见性只改善操作体验,后端路由继续执行角色与能力检查。接口见[系统 API](../04-api/02-api-system.md)。
`GET /api/v1/system/capabilities` 返回 edition 及能力 supported/reason。前端据实际部署能力隐藏或禁用入口(路由守卫、左侧菜单、设置分区、工具箱标签页都读同一份快照):能力探测失败或旧版后端缺少某个键时默认保持可见;`organizations` 在 Lite 版始终隐藏;`settings.sandbox.docker` / `settings.sandbox.host` 只有后端明确返回 `supported: true` 才显示。前端可见性只改善操作体验,后端路由继续执行角色与能力检查。接口见[系统 API](../04-api/02-api-system.md)。

View File

@ -4,7 +4,18 @@ WeKnora CLI(命令名 `weknora`)用于管理知识库与文档、执行检
源码位于 `cli/`,是独立的 Go module(`github.com/Tencent/WeKnora/cli`),源码构建需要 Go 1.26+。命令入口为 `cli/cmd/root.go`。
在控制台「设置 → 发布与集成 → CLI」可查看安装步骤,并复制当前部署的连接命令。服务地址保留反向代理路径前缀,末尾无需 `/api/v1`。连接后运行 `weknora doctor` 和 `weknora kb list`,确认服务与凭证可用。
自 v0.8.2 起,控制台「设置 → 发布集成 → CLI」提供接入引导页,按当前部署生成可复制的命令:
1. **安装**:从源码构建(需要 Git 与 Go 1.26+,示例适用于 macOS / Linux);
2. **连接**:`weknora profile add weknora --host '<当前服务地址>' --use && weknora auth login`,创建并启用名为 `weknora` 的 profile 后用邮箱和密码登录。服务地址保留反向代理路径前缀,末尾无需 `/api/v1`;已有同名 profile 时请换一个名称;
3. **验证**:运行 `weknora doctor` 和 `weknora kb list`,确认服务与凭证可用。
页面右侧另给出常用命令(上传、检索、问答、列出智能体)和 MCP 客户端配置示例(`"args": ["--profile", "weknora", "mcp", "serve"]`)。
<Screenshot
src="/screenshots/integration-cli.png"
caption="设置 → 发布集成 → CLI:安装、连接与验证命令"
hint="展示设置中心左侧「发布集成」分组选中 CLI,右侧快速开始的三个步骤(安装 CLI / 连接当前服务 / 验证连接,连接命令中已填入当前服务地址),以及常用命令与 MCP 客户端配置示例。" />
## 总体架构
@ -48,7 +59,7 @@ flowchart TB
### 从源码构建(当前受支持的安装方式)
`cli/README.md` 明确说明:**从源码构建是目前受支持的安装方式**;预编译二进制、`go install`、CLI 的 Homebrew formula 计划随正式 tag 发布一同提供。
目前受支持的安装方式是从源码构建,尚未提供预编译二进制或 `go install` 安装方式。
```bash
git clone https://github.com/Tencent/WeKnora.git
@ -496,7 +507,7 @@ WEKNORA_E2E_HOST=https://kb.example.com WEKNORA_E2E_TOKEN=eyJ... \
---
## 分钟上手 {#_5-分钟上手}
## 快速上手 {#_5-分钟上手}
```bash
# 1. 注册服务器为 profile 并激活

View File

@ -104,6 +104,9 @@ kb, err := apiClient.GetKnowledgeBase(ctx, kbID)
| `Login` | 邮箱密码登录,返回 JWT access/refresh token |
| `GetCurrentUser` | 获取当前登录主体与租户信息(`GET /api/v1/auth/me`) |
| `RefreshToken` | 用 refresh token 换取新 access token |
| `SwitchTenant` | 切换到指定空间并重新签发 token 对,同时记为下次登录的默认空间(`POST /api/v1/auth/switch-tenant`) |
| `ChangePassword` | 修改当前用户密码;成功后服务端吊销该用户所有会话,调用方应丢弃本地 token |
| `GetAuthConfig` | 读取公开认证配置:注册模式、是否启用复杂密码(`GET /api/v1/auth/config`,无需认证) |
### 知识库 KnowledgeBase — `client/knowledgebase.go`
@ -131,10 +134,12 @@ kb, err := apiClient.GetKnowledgeBase(ctx, kbID)
| `GetKnowledge` | 获取知识详情 |
| `GetKnowledgeBatch` | 批量获取知识 |
| `ListKnowledge` | 分页列出知识 |
| `ListKnowledgeWithFilter` | 带过滤条件列出知识 |
| `ListKnowledgeWithFilter` | 带过滤条件列出知识(`KnowledgeListFilter`:标签、关键词、文件类型、解析状态、来源、时间范围、文件夹) |
| `DeleteKnowledge` | 删除知识 |
| `DownloadKnowledgeFile` | 下载知识原始文件到本地路径 |
| `OpenKnowledgeFile` | 以流方式打开知识原始文件(返回文件名 + `io.ReadCloser`) |
| `DownloadKnowledgeFiles` / `OpenKnowledgeFilesArchive` | 把同一知识库内多个文档的原始文件打包为 ZIP 下载到本地 / 以流方式读取(`POST /api/v1/knowledge-bases/{id}/knowledge/batch-download`;单次最多 200 个 ID、合计 512 MiB;需要 Contributor 及该知识库写权限);走流式 HTTP 客户端,不受 30 秒默认超时限制 |
| `ListKnowledgeFolders` / `MoveKnowledgeToFolder` / `RenameKnowledgeFolder` | 知识库文件夹树、把文档移入文件夹(`FolderPath` 为空表示移回根目录)、重命名文件夹及其全部子路径 |
| `UpdateKnowledge` | 更新知识 |
| `ReparseKnowledge` | 重新解析知识 |
| `CancelKnowledgeParse` | 取消解析任务 |
@ -148,6 +153,8 @@ kb, err := apiClient.GetKnowledgeBase(ctx, kbID)
| `PreviewKnowledgeFile` | 预览知识文件(返回原始 `*http.Response`) |
| `BatchUpdateKnowledgeTags` | 批量更新知识标签 |
服务端的知识列表接口自 v0.8.2 起支持 `sort_by`(`updated_at` / `created_at` / `file_name`)与 `sort_order`(`asc` / `desc`)参数,默认仍为 `created_at desc`;`KnowledgeListFilter` 暂未提供对应字段,需要自定义排序时可用 `Raw` 调用,参数说明见[知识 API](../04-api/02-api-knowledge.md)。
### 分块 Chunk — `client/chunk.go`
| 方法 | 说明 |
@ -210,6 +217,11 @@ kb, err := apiClient.GetKnowledgeBase(ctx, kbID)
| `GetAgentPlaceholders` | 获取 Agent 配置占位符 |
| `GetSuggestedQuestions` | 获取 Agent 建议问题 |
v0.8.2 起的两处请求字段变化:
- `UpdateAgentRequest.Avatar` 由 `string` 改为 `*string`:为 `nil` 时不下发该字段,保留原头像;指向空字符串表示清除头像。升级 SDK 后需调整赋值代码(例如 `Avatar: &avatar`)。
- 推荐问题 `SuggestedQuestion` 新增 `KnowledgeID`(来源文档)。用户点选推荐问题提问时,可在 `KnowledgeQARequest` / `AgentQARequest` 的 `QuestionOrigin`(`KnowledgeBaseID`、`KnowledgeID`)中回传来源,服务端会在回答前优先检索该来源;它只作为提示,不会扩大请求本身的检索范围。
### 模型 Model — `client/model.go`
| 方法 | 说明 |
@ -248,13 +260,15 @@ kb, err := apiClient.GetKnowledgeBase(ctx, kbID)
| `CreateOrganization` / `ListMyOrganizations` / `GetOrganization` / `UpdateOrganization` / `DeleteOrganization` | 组织 CRUD |
| `SearchOrganizations` / `PreviewOrganizationByInviteCode` | 搜索/邀请码预览组织 |
| `JoinOrganizationByInviteCode` / `SubmitJoinRequest` / `JoinByOrganizationID` / `LeaveOrganization` / `RequestRoleUpgrade` | 加入/退出/升级角色 |
| `GenerateInviteCode` / `SearchUsersForInvite` / `InviteMember` | 邀请成员 |
| `GenerateInviteCode` / `SearchUsersForInvite` / `InviteMember` | 邀请成员(`SearchUsersForInvite` 的限制见下方说明) |
| `ListOrgMembers` / `UpdateMemberRole` / `RemoveMember` | 成员管理 |
| `ListJoinRequests` / `ReviewJoinRequest` | 加入申请审批 |
| `ShareKnowledgeBase` / `ListKBShares` / `UpdateSharePermission` / `RemoveKBShare` | 知识库共享 |
| `ShareAgent` / `ListAgentShares` / `RemoveAgentShare` | Agent 共享 |
| `ListOrgShares` / `ListOrgAgentShares` / `ListSharedKnowledgeBases` / `ListSharedAgents` | 共享资源查询 |
自 v0.8.2 起,服务端邀请候选只按**完整空间 ID** 精确解析(`GET /api/v1/organizations/{id}/search-tenants?q=<空间ID>`),不再按空间名、用户名或邮箱搜索。`SearchUsersForInvite` 调用的是已废弃的 `search-users` 别名,并以 `keyword` 参数传值,服务端读取的是 `q`,因此该方法目前拿不到候选。需要查找候选时,请用 `Raw` 直接调用 `search-tenants`。
### FAQ — `client/faq.go`
| 方法 | 说明 |
@ -289,8 +303,12 @@ kb, err := apiClient.GetKnowledgeBase(ctx, kbID)
| `CreateMCPService` / `ListMCPServices` / `GetMCPService` / `UpdateMCPService` / `DeleteMCPService` | MCP 服务 CRUD |
| `TestMCPService` | 连通性测试 |
| `GetMCPServiceTools` / `GetMCPServiceResources` | 列出 MCP 工具/资源 |
| `GetMCPMetadata` | 读取已保存的工具目录,不连接上游;从未同步过返回 `nil`,`Stale=true` 表示保存的连接与当前配置不一致 |
| `RefreshMCPMetadata` | 连接上游并整体替换已保存的工具目录;OAuth 服务按调用者保存快照(Viewer+),静态认证服务写空间级快照(需 Admin 或可管理 MCP 服务的 API Key) |
| `ResolveToolApproval` | 处理工具调用审批 |
`MCPService` 列表项带 `Catalog`(工具数、是否过期、同步时间)和 `UsageInstructions` 字段。
### MCP 端点(WeKnora 作为 MCP Server)— `client/mcp_endpoint.go`
| 方法 | 说明 |
@ -314,6 +332,7 @@ kb, err := apiClient.GetKnowledgeBase(ctx, kbID)
| 方法 | 说明 |
|---|---|
| `GetSystemInfo` | 获取系统信息(版本等) |
| `GetDeploymentCapabilities` | 获取部署能力快照(`GET /api/v1/system/capabilities`,edition 与各能力的 supported / reason) |
| `ListParserEngines` / `CheckParserEngines` | 文档解析引擎列表/检测 |
| `ReconnectDocReader` | 重连 DocReader 服务 |
| `GetStorageEngineStatus` / `CheckStorageEngine` | 存储引擎状态/检测 |
@ -327,7 +346,7 @@ kb, err := apiClient.GetKnowledgeBase(ctx, kbID)
| `GetWebSearchProviders` | 列出可用 Web 搜索提供商 | `client/web_search.go` |
| `Raw` | 原始 HTTP 逃生舱(Experimental) | `client/client.go` |
合计约 170 个公开方法,覆盖约 20 类资源。
合计 220 余个公开方法,覆盖 20 余类资源。
### 记忆、沙箱技能与个人变量

View File

@ -7,24 +7,25 @@
## 后端地址与认证配置
小程序**不在代码中硬编码后端地址**,一切连接信息由用户在「Settings」页填写,存储于 `wx.setStorageSync` 的本地存储键 `weknora_settings` 中,结构包含三个字段:
小程序**不在代码中硬编码后端地址**,一切连接信息由用户在「设置」页填写,存储于 `wx.setStorageSync` 的本地存储键 `weknora_settings` 中,结构包含四个字段:
```js
{
baseUrl: "http://localhost:8080", // app.js onLaunch 写入的默认值
apiKey: "",
selectedKnowledgeBaseId: ""
selectedKnowledgeBaseId: "",
locale: "zh" // 界面语言:zh | en
}
```
- **默认值**:`miniprogram/app.js` 在 `onLaunch` 中若发现本地无设置,会写入默认 `baseUrl: "http://localhost:8080"`、空 `apiKey`。默认值仅便于本地开发,实际使用必须在 Settings 页改为真实地址。
- **读写与规范化**:`miniprogram/utils/config.js` 提供 `getSettings()` / `saveSettings()`,并通过 `normalizeBaseUrl()` 去除首尾空白与末尾 `/`。
- **默认值**:`miniprogram/app.js` 在 `onLaunch` 中若发现本地无设置,会写入默认 `baseUrl: "http://localhost:8080"`、空 `apiKey` 与 `locale: "zh"`。默认值仅便于本地开发,实际使用必须在设置页改为真实地址。
- **读写与规范化**:`miniprogram/utils/config.js` 提供 `getSettings()` / `saveSettings()`,通过 `normalizeBaseUrl()` 去除首尾空白与末尾 `/`,通过 `normalizeLocale()` 把非 `en` 的值一律归为 `zh`。
- **认证方式为 API Key**:`miniprogram/utils/request.js` 中所有请求统一携带请求头:
- `X-API-Key: <用户填写的 API Key>`(来自 WeKnora 租户设置页,形如 `sk-...`);
- `X-API-Key: <用户填写的 API Key>`(在 WeKnora「设置 → 发布集成 → API 集成」获取,形如 `sk-...`);
- `X-Request-ID: mp-<时间戳>-<随机串>`(便于服务端追踪);
- `Content-Type: application/json`。
- **前置校验**:`baseUrl` 或 `apiKey` 任一缺失时,请求会直接以错误 Promise 拒绝("Please configure the WeKnora API base URL / API key first.");`pages/index/index.js` 的 `onShow` 也会据此显示引导用户去 Settings 页的提示。
- **AppID 配置**:微信小程序 AppID 不放在共享的 `project.config.json` 中,而是复制 `miniprogram/project.private.config.json.example` 为 `project.private.config.json` 并填入真实 AppID(示例文件内容为 `{"appid": "your-wechat-mini-program-appid"}`)。
- **前置校验**:`baseUrl` 或 `apiKey` 任一缺失时,请求会直接以错误 Promise 拒绝,提示按当前语言显示(如「请先配置 WeKnora API 地址。」/「请先配置 WeKnora API Key。」);`pages/index/index.js` 的 `onShow` 也会据此显示引导用户去设置页的提示。
- **AppID 配置**:复制 `miniprogram/project.private.config.json.example` 为 `project.private.config.json` 并填入自己的 AppID(示例文件内容为 `{"appid": "your-wechat-mini-program-appid"}`)。注意:当前共享的 `project.config.json` 中带有一个 `appid` 字段,使用自己的小程序时以私有配置覆盖它。
调用到的后端接口(均定义在 `miniprogram/utils/request.js`):
@ -37,17 +38,17 @@
## 中英文与本地设置
设置页可选择中文或 English,默认中文;locale 以 zh/en 保存在本地设置。切换后页面文案、导航标题和底部 tab 标签立即更新,重启仍保留选择。词条集中在 `utils/i18n.js`,新增页面应复用该模块。
自 v0.8.2 起,设置页可选择「中文」或「English」,默认中文;选择以 `locale`(`zh` / `en`)保存在本地设置,重启后保留。切换后页面文案、导航栏标题(`wx.setNavigationBarTitle`)和底部 tab 文案(`wx.setTabBarItem`)立即更新;底部 tab 同时带有图标(`assets/tab/*.png`)。词条集中在 `utils/i18n.js`,新增页面应复用该模块。
在微信开发者工具中复制 project.private.config.json.example 为 project.private.config.json 并填写自己的 AppID;共享 project.config.json 不固定 AppID。聊天客户端目前解析请求完成后的 SSE 文本并累计 answer 片段,不代表小程序已实现逐块实时传输。正式发布需把 API 域名加入 request 合法域名。
聊天页目前在请求完成后解析整段 SSE 文本并累计 `answer` 片段,不做逐块实时渲染。正式发布需把 API 域名加入 request 合法域名。
## 构建与发布流程
小程序无需编译步骤(原生开发、无构建工具链),直接用微信开发者工具(WeChat DevTools)打开即可:
1. **导入项目**:在微信开发者工具中选择「导入项目」,目录指向仓库的 `miniprogram/`。工具会读取 `project.config.json`(项目名 "WeKnora Mini Program")。
2. **配置 AppID**:复制 `miniprogram/project.private.config.json.example` 为 `project.private.config.json`,将 `appid` 替换为实际小程序 AppID。共享的 `project.config.json` 不保存 AppID;`project.private.config.json` 属于个人私有配置,不应提交。
3. **配置后端连接**:运行后进入 **Settings** tab,填写 API Base URL(如 `https://weknora.example.com`)与从 WeKnora 租户设置页获取的 API Key,保存。
2. **配置 AppID**:复制 `miniprogram/project.private.config.json.example` 为 `project.private.config.json`,将 `appid` 替换为实际小程序 AppID。`project.private.config.json` 属于个人私有配置,已被 `.gitignore` 忽略,不应提交。
3. **配置后端连接**:运行后进入「设置」tab,填写 API Base URL(如 `https://weknora.example.com`)与 WeKnora API Key(「设置 → 发布集成 → API 集成」中获取),按需切换界面语言,保存。
4. **本地调试注意**:`project.config.json` 开启了 `urlCheck: true`,开发者工具默认会拦截 `localhost` 等非合法域名请求。本地测试可在 DevTools 中勾选「不校验合法域名」,或通过 HTTPS 开发域名暴露 WeKnora 服务。
5. **发布**:正式发布前,需在微信公众平台的小程序管理后台,把 WeKnora API 域名(必须为 HTTPS)加入 request 合法域名(request 域名白名单);随后在开发者工具中点击「上传」提交代码,再在管理后台提交审核并发布。
@ -60,7 +61,11 @@ cd miniprogram
npm test # 实际执行 node --test ../tests/miniprogram/*.test.js
```
即使用 Node.js 内置 test runner 运行仓库 `tests/miniprogram/miniprogram.test.js` 中的单元测试(覆盖 `utils/` 下的纯函数逻辑),无需安装任何依赖。
即使用 Node.js 内置 test runner 运行仓库 `tests/miniprogram/miniprogram.test.js` 中的单元测试(覆盖 SSE 解析、地址规范化、中英文切换、请求头与请求体、知识库页加载逻辑),无需安装任何依赖。
### 基础库兼容
页面与 `utils/` 代码不使用可选链 `?.` 和空值合并 `??`:部分基础库版本不支持这两种语法,会导致页面白屏(v0.8.2 修复了知识库页因此空白的问题)。WXML 中的文案绑定也保持扁平字段,便于在各版本基础库中渲染。修改代码时请保持这一约束。
## 实现参考
@ -72,25 +77,26 @@ npm test # 实际执行 node --test ../tests/miniprogram/*.test.js
- `miniprogram/app.json` — 标准小程序全局配置(`pages`、`window`、`tabBar`);
- `miniprogram/app.wxss` — 全局样式;页面均为 `js / wxml / wxss / json` 四件套;
- `miniprogram/package.json` — 包名 `weknora-miniprogram`(version `0.1.0`),`description` 为 "WeChat Mini Program plugin for WeKnora",**没有 `dependencies`**,仅有一个测试脚本(见下文「测试」);
- `miniprogram/project.config.json` — `compileType: "miniprogram"`,`libVersion: "latest"`(基础库使用最新版),编译选项开启 `es6`、`enhance`、`postcss`、`minified`,并开启 `urlCheck: true`(合法域名校验)。该文件不包含 `appid` 字段,AppID 通过私有配置文件提供(见「构建与发布」)。
- `miniprogram/project.config.json` — `compileType: "miniprogram"`,`libVersion: "latest"`(基础库使用最新版),编译选项开启 `es6`、`enhance`、`postcss`、`minified`、`minifyWXSS`、`minifyWXML`,并开启 `urlCheck: true`(合法域名校验)。该文件目前带有 `appid` 字段,自己的 AppID 通过私有配置文件提供(见「构建与发布流程」)。
全局窗口样式:导航栏标题 `WeKnora`,背景色 `#0d3b2a`(深绿),文字白色。
### 页面清单
`miniprogram/app.json` 中注册了 3 个页面,且三者同时构成底部 `tabBar`(选中色 `#07c05f`):
`miniprogram/app.json` 中注册了 3 个页面,且三者同时构成底部 `tabBar`(选中色 `#07c05f`,每项带普通 / 选中两套图标)。tab 文案默认为中文,运行时按语言切换:
| 页面路径 | 名称(tabBar 文案) | 功能 |
| 页面路径 | tabBar 文案(中文 / English) | 功能 |
| --- | --- | --- |
| `pages/index/index` | Knowledge(知识库) | 首页。检测是否已配置 baseUrl / API Key,未配置时提示并可一键跳转 Settings;调用 `GET /api/v1/knowledge-bases` 加载知识库列表,通过 `picker` 或列表点选知识库(选择结果持久化到本地存储);输入网页 URL 后调用 `POST /api/v1/knowledge-bases/{id}/knowledge/url` 将该 URL 导入选中知识库(`enable_multimodel` 固定为 `false`) |
| `pages/chat/chat` | Chat(问答) | 知识问答页。首次提问时通过 `POST /api/v1/sessions` 懒创建会话(携带选中的 `knowledge_base_id`),随后调用 `POST /api/v1/knowledge-chat/{sessionId}` 提问;返回体为 SSE 文本,客户端用 `utils/sse.js` 解析并拼接 `response_type === "answer"` 的分片后整体展示(解析失败则回退展示原始响应) |
| `pages/settings/settings` | Settings(设置) | 连接配置页。填写 API Base URL 与 API Key(密码输入框),保存到本地存储 `weknora_settings` |
| `pages/index/index` | 知识库 / Knowledge | 首页。检测是否已配置 baseUrl / API Key,未配置时提示并可一键跳转设置页;调用 `GET /api/v1/knowledge-bases` 加载知识库列表,通过 `picker` 或列表点选知识库(选择结果持久化到本地存储);输入网页 URL 后调用 `POST /api/v1/knowledge-bases/{id}/knowledge/url` 将该 URL 导入选中知识库(`enable_multimodel` 固定为 `false`) |
| `pages/chat/chat` | 问答 / Chat | 知识问答页。首次提问时通过 `POST /api/v1/sessions` 懒创建会话(携带选中的 `knowledge_base_id`),随后调用 `POST /api/v1/knowledge-chat/{sessionId}` 提问;返回体为 SSE 文本,客户端用 `utils/sse.js` 解析并拼接 `response_type === "answer"` 的分片后整体展示(解析失败则回退展示原始响应) |
| `pages/settings/settings` | 设置 / Settings | 连接配置页。填写 API Base URL 与 API Key(密码输入框),选择界面语言,保存到本地存储 `weknora_settings` |
### utils/ 工具模块
| 文件 | 职责 |
| --- | --- |
| `miniprogram/utils/config.js` | 设置的持久化层:定义存储键 `STORAGE_KEY = "weknora_settings"`,提供 `getSettings()`、`saveSettings()`(合并式更新)与 `normalizeBaseUrl()`(trim 并去除末尾斜杠) |
| `miniprogram/utils/config.js` | 设置的持久化层:定义存储键 `STORAGE_KEY = "weknora_settings"`,提供 `getSettings()`、`saveSettings()`(合并式更新)、`normalizeBaseUrl()`(trim 并去除末尾斜杠)与 `normalizeLocale()` |
| `miniprogram/utils/i18n.js` | 中英文词条表与 `t()`、`getLocale()` / `setLocale()`、`applyTabBar()`(更新底部 tab 文案与图标)、`applyNavTitle()`(更新导航栏标题) |
| `miniprogram/utils/request.js` | 基于 `wx.request` 的 Promise 化 HTTP 封装:拼接 `baseUrl + path`、注入 `X-API-Key` / `X-Request-ID` 头、统一 2xx 判定与错误消息提取(优先 `error.message`,其次 `message`,兜底 `HTTP <status>`);并导出上表 4 个业务 API 函数 |
| `miniprogram/utils/sse.js` | Server-Sent Events 文本解析器:`parseSSE(raw)` 按空行切分事件块、解析 `event:` / `data:` 行;`collectAnswerFromSSE(raw)` 将各事件的 `data` 按 JSON 解析并累加 `response_type === "answer"` 的 `content`,得到最终答案文本。注意小程序端**不做流式渲染**,而是等 `wx.request` 拿到完整 SSE 文本后一次性解析展示 |
@ -98,9 +104,9 @@ npm test # 实际执行 node --test ../tests/miniprogram/*.test.js
```mermaid
flowchart LR
S["Settings 页<br/>(baseUrl + API Key)"] -->|"wx.setStorageSync(weknora_settings)"| C["utils/config.js"]
K["Knowledge 页<br/>(pages/index)"] -->|"listKnowledgeBases / createKnowledgeFromURL"| R["utils/request.js<br/>(X-API-Key 头)"]
Q["Chat 页<br/>(pages/chat)"] -->|"createSession / knowledgeChat"| R
S["设置页<br/>(baseUrl + API Key + 语言)"] -->|"wx.setStorageSync(weknora_settings)"| C["utils/config.js"]
K["知识库页<br/>(pages/index)"] -->|"listKnowledgeBases / createKnowledgeFromURL"| R["utils/request.js<br/>(X-API-Key 头)"]
Q["问答页<br/>(pages/chat)"] -->|"createSession / knowledgeChat"| R
R -->|"wx.request"| B["WeKnora 后端<br/>/api/v1/*"]
B -->|"SSE 文本"| P["utils/sse.js<br/>collectAnswerFromSSE"]
P --> Q

View File

@ -4,7 +4,7 @@
桌面应用目前没有随 Release 提供安装包,需按[安装部署](../01-getting-started/02-installation.md)自行构建。
:::
WeKnora Lite 桌面应用基于 [Wails v2](https://wails.io),在桌面进程中运行 Go 后端,使用 SQLite 和本地文件存储。启动后可管理知识库并进行检索问答,无需 Docker 或外部数据库。源码位于 `cmd/desktop/`,基础能力与[单二进制 Lite](../01-getting-started/02-installation.md)一致。
WeKnora Lite 桌面应用基于 [Wails v2](https://wails.io),在桌面进程中运行 Go 后端,使用 SQLite 和本地文件存储。启动后可管理知识库并进行检索问答,无需 Docker 或外部数据库。源码位于 `cmd/desktop/`,基础能力与[单二进制 Lite](../01-getting-started/02-installation.md)一致;桌面版另外提供免登录启动,以及在 macOS 上运行智能体命令的[本机沙箱](../03-features/22-skills-sandbox.md#lite-host)。
## 总体架构 {#_1-总体架构}
@ -52,10 +52,11 @@ flowchart LR
| `cmd/desktop/main.go` | 主入口(`//go:build !bindings`):启动内嵌 Gin 后端、构建 macOS 菜单、配置 Wails 窗口与反向代理、注入 DomReady JS |
| `cmd/desktop/main_bindings.go` | 绑定生成入口(`//go:build bindings`):`wails build` 生成前端绑定阶段用 `-tags bindings` 单独编译,只 `Bind` 不启动 Gin/数据库 |
| `cmd/desktop/app.go` | `App` 结构体与全部 Wails 绑定方法 |
| `cmd/desktop/prefs.go` | 桌面偏好设置的读写(`desktop-prefs.json`) |
| `cmd/desktop/prefs.go` | 桌面偏好设置的读写(`desktop-prefs.json`),含本机沙箱的已批准项目目录 |
| `cmd/desktop/signing_key.go` | 首次启动生成并持久化签名密钥 |
| `cmd/desktop/update.go` | 基于 GitHub Releases 的检查更新 / 下载 / 安装重启逻辑 |
| `cmd/desktop/wails.json` | Wails 构建配置 |
| `cmd/desktop/build/` | 打包资源:`appicon.png`(应用图标)、`darwin/Info.plist`(macOS bundle 模板) |
| `cmd/desktop/build/` | 打包资源:`appicon.png`(应用图标)、`darwin/Info.plist`(macOS bundle 模板)、`windows/installer/project.nsi`(Windows NSIS 安装器模板) |
## 窗口配置与前端注入 {#_3-窗口配置与前端注入}
@ -87,6 +88,11 @@ flowchart LR
| `GetDesktopListenPublicActive` | `(): Promise<boolean>` | 当前会话是否**实际**在所有网卡上监听(运行时状态,而非保存的偏好) |
| `CheckForUpdates` | `(): Promise<void>` | 手动触发更新检查(有"已是最新"等对话框反馈) |
| `AutoCheckForUpdates` | `(): Promise<void>` | 静默检查更新并自动后台下载 |
| `GetAutoSetupToken` | `(): Promise<string>` | 返回本次进程的免登录凭据,前端用它调用 `POST /api/v1/auth/auto-setup` |
| `PickProjectDir` | `(): Promise<string>` | 打开系统目录选择框,把选中的目录加入本机沙箱已批准列表并返回;取消时为空 |
| `GetProjectDirs` | `(): Promise<string[]>` | 读取已批准的项目目录 |
| `RemoveProjectDir` | `(dir: string): Promise<void>` | 从已批准列表移除一个目录 |
| `GetApprovalMode` / `SetApprovalMode` | `(): Promise<string>` / `(mode: string): Promise<void>` | 读写本机沙箱审批模式;当前只接受 `auto` |
## 偏好设置存储(cmd/desktop/prefs.go) {#_5-偏好设置存储-cmd-desktop-prefs-go}
@ -102,8 +108,17 @@ flowchart LR
|------|------|--------|------|
| `http_port` | int | 0 | 内嵌 API 服务监听端口;0 或非法值(超出 1–65535)表示每次启动使用随机空闲端口 |
| `http_bind_public` | bool | false | 是否监听 `0.0.0.0`(允许局域网/公网访问内嵌 API) |
| `project_dirs` | string[] | 空 | 通过系统目录选择框批准的本机项目目录(绝对路径);只有列表中的目录能绑定到会话 |
| `approval_mode` | string | `auto` | 本机沙箱审批模式;未知值按 `auto` 处理,`ask`、`full` 尚未提供,保存时被拒绝 |
读写入口:`LoadDesktopPrefsHTTPPort()` / `LoadDesktopHTTPBindPublic()` / `SaveDesktopHTTPPortPreference()` / `SaveDesktopHTTPBindPublicPreference()`,读取失败或解析失败时静默回退为零值。
读写入口:`LoadDesktopPrefsHTTPPort()` / `LoadDesktopHTTPBindPublic()` / `SaveDesktopHTTPPortPreference()` / `SaveDesktopHTTPBindPublicPreference()`,以及本机沙箱用的 `LoadProjectDirs()` / `LoadApprovalMode()`,读取失败或解析失败时静默回退为零值。`project_dirs` 只能通过目录选择框(`PickProjectDir` 或 `POST /api/v1/system/host-project-dir`)追加,手工输入的路径不会被当作授权。
## 免登录启动与签名密钥
桌面版启动时不需要注册或登录:
- 每次启动生成一个随机凭据,只通过 Wails 绑定 `GetAutoSetupToken` 交给内置前端。前端在请求头 `X-WeKnora-Desktop-Token` 中携带它调用 `POST /api/v1/auth/auto-setup`,首次调用创建默认用户 `admin@weknora.local` 和空间,之后直接签发登录令牌。没有该凭据的请求(包括局域网内的其他设备和普通浏览器)会被拒绝。
- 未配置有效的 `SYSTEM_SIGNING_KEY`(或非默认值的 `SYSTEM_AES_KEY`)时,首次启动在偏好目录生成 `signing.key`(权限 `0600`)并作为 `SYSTEM_SIGNING_KEY` 使用,供文件预签名链接、网页嵌入会话等签名,重启后仍然有效。它只用于签名,不会替换加密已存凭据的 AES 密钥。
## 自动更新机制(cmd/desktop/update.go) {#_6-自动更新机制-cmd-desktop-update-go}
@ -128,6 +143,7 @@ flowchart LR
"outputfilename": "WeKnora Lite",
"frontend:dir": "../../frontend",
"wailsjsdir": "../../frontend/src",
"build:tags": "desktop",
"info": { "companyName": "Tencent", "productName": "WeKnora Lite", "productVersion": "1.0.0" },
"mac": { "category": "public.app-category.productivity", "titlebar": "hiddenInset" }
}
@ -135,9 +151,10 @@ flowchart LR
要点:
- `build:tags` 为 `desktop`:只有带该标签编译的程序才包含 Lite 本机沙箱,`wails build -tags ...` 传入的标签会与它合并。
- `frontend:dir` 指向仓库的 `frontend/`;`wailsjsdir` 指向 `frontend/src`,因此 Wails 自动生成的绑定输出在 `frontend/src/wailsjs/`(`go/main/App.js`、`App.d.ts` 及 `runtime/`)。
- **前端构建**:打包脚本单独构建前端,Wails 配置中不设置 `frontend:build`。WebView 通过反向代理访问内嵌后端。
- `cmd/desktop/build/` 仅包含 `appicon.png`(应用图标)与 `darwin/Info.plist`(macOS bundle 的 Go template,声明 `CFBundleIdentifier: com.wails.WeKnora Lite`、最低系统版本 10.13、Retina 支持等);`wails build` 的产物输出到 `cmd/desktop/build/bin/`。
- `cmd/desktop/build/` 包含 `appicon.png`(应用图标)、`darwin/Info.plist`(macOS bundle 的 Go template,声明 `CFBundleIdentifier: com.wails.WeKnora Lite`、最低系统版本 10.13、Retina 支持等)和 Windows 安装器模板 `windows/installer/project.nsi`(额外安装第三方许可证文件);`wails build` 的产物输出到 `cmd/desktop/build/bin/`。
## 前端如何感知桌面环境 {#_8-前端如何感知桌面环境}
@ -166,7 +183,7 @@ SKIP_FRONTEND=1 ./scripts/package-mac-app.sh
cd cmd/desktop && wails build -clean -tags "sqlite_fts5" -ldflags="$LDFLAGS" -o "WeKnora Lite"
```
该命令的"生成绑定"阶段使用 `-tags bindings` 单独编译 `main_bindings.go`(不连接数据库),并刷新 `frontend/src/wailsjs/` 下的绑定文件。
3. **组装产物**:将 `cmd/desktop/build/bin/WeKnora Lite.app` 复制到 `dist/`,并向 `.app/Contents/Resources/` 内放置 `.env`(来自 `.env.lite.example`)、`config/`、`migrations/sqlite/` 与 `web/` 前端资源。
实际生效的构建标签为 `wails.json` 中的 `desktop` 加上命令行的 `sqlite_fts5`。该命令的"生成绑定"阶段使用 `-tags bindings` 单独编译 `main_bindings.go`(不连接数据库),并刷新 `frontend/src/wailsjs/` 下的绑定文件。
3. **组装产物**:将 `cmd/desktop/build/bin/WeKnora Lite.app` 复制到 `dist/`,并向 `.app/Contents/Resources/` 内放置第三方许可证(`scripts/copy-licenses.sh`)、`.env`(来自 `.env.lite.example`)、`config/`、`migrations/sqlite/` 与 `web/` 前端资源。
最终产物为 `dist/WeKnora Lite.app`,双击即可运行。Windows/Linux 亦可在 `cmd/desktop` 下用 `wails build` 自行构建(更新机制已按 `.exe` / `xdg-open` 做了平台适配),但仓库当前仅提供 macOS 打包脚本与 `build/darwin` 资源。

View File

@ -20,10 +20,10 @@
## 安装与连接 {#怎么配}
在「设置 → 集成 → Chrome 扩展」查看连接指引,并复制当前实例的 API 地址。按以下步骤完成连接:
在「设置 → 发布集成 → Chrome 插件」查看连接指引,并复制当前实例的 API 地址。按以下步骤完成连接:
1. **获取 API 凭证**:在「设置 → API 信息」复制 API Key 与 API 地址。建议单独建一个 Key 并按需收窄能力(至少需要检索与入库相关能力,见[租户、用户与认证授权](../03-features/01-tenant-auth.md)的 API Key 章节);
2. **桌面版建议先固定端口**:用 WeKnora 桌面版时,在 API 信息里设一个固定端口(例如 37841)。否则每次启动端口变化,插件会连不上;
1. **获取 API 凭证**:在「设置 → 发布集成 → API 集成」复制 API Key 与 API 地址(引导页的「打开 API 信息」按钮会直接跳转到这里)。建议单独建一个 Key 并按需收窄能力(至少需要检索与入库相关能力,见[租户、用户与认证授权](../03-features/01-tenant-auth.md)的 API Key 章节);
2. **桌面版建议先固定端口**:用 WeKnora 桌面版时,在「API 集成」页设一个固定端口(例如 37841)。否则每次启动端口变化,插件会连不上;
3. **安装插件**:从 Chrome 应用商店安装;
4. **在插件里连接**:打开插件设置,选「企业/开发者」模式,填入 API 地址与 API Key。

View File

@ -16,9 +16,9 @@ Claw Skill 为 OpenClaw 生态中的智能体提供 WeKnora 接入能力,通
## 安装与连接 {#怎么配}
在「设置 → 集成 → Claw Skill」查看安装指引,复制当前实例的 API 地址、环境变量示例和安装命令。
在「设置 → 发布集成 → Claw Skill」查看安装指引,复制当前实例的 API 地址、环境变量示例和安装命令。
1. **获取 API 凭证**:「设置 → API 信息」里复制 API Key 与 API 地址;
1. **获取 API 凭证**:在「设置 → 发布集成 → API 集成」复制 API Key 与 API 地址(引导页的「打开 API 信息」按钮会直接跳转到这里);
2. **设置环境变量**:在终端或 `~/.zshrc` / `~/.bashrc` 里设置
```bash
@ -26,22 +26,30 @@ Claw Skill 为 OpenClaw 生态中的智能体提供 WeKnora 接入能力,通
export WEKNORA_API_KEY=sk-xxxxx
```
3. **安装 Skill**:在装好 OpenClaw CLI 的环境里执行引导页给出的安装命令,或到 ClawHub 页面按指引安装;
`WEKNORA_BASE_URL` 需要包含 `/api/v1`,引导页的示例已填入当前实例地址。
3. **安装 Skill**:在装好 OpenClaw CLI 的环境里执行下面的命令,或到 ClawHub 页面按指引安装;
```bash
openclaw skills install @lyingbug/weknora
```
4. **验证**:让 Agent 列一次知识库或跑一次检索,确认凭证与网络可达。
## 和 MCP 的关系
Claw Skill 和 MCP Server 均可供外部智能体调用,选择取决于客户端支持的接入方式及所需功能:
| | Claw Skill | MCP Server |
| | Claw Skill | MCP Server(内置) |
| --- | --- | --- |
| 面向 | OpenClaw / ClawHub 生态的 Agent | 支持 MCP 协议的客户端(Claude Desktop、VS Code Copilot 等) |
| 安装 | ClawHub 安装 Skill | `pip install tencent-weknora-mcp` 或 `uvx` 运行 |
| 传输 | 直接调 REST | stdio / SSE / Streamable HTTP |
| 能力范围 | 导入、检索、浏览(5 类) | 31 个工具,另含租户、模型、会话、Agent 问答、Wiki |
| 面向 | OpenClaw / ClawHub 生态的 Agent | 支持 MCP 协议的客户端(Claude Desktop、Cursor、Claude Code、VS Code Copilot 等) |
| 安装 | ClawHub 安装 Skill | 无需额外部署:在「设置 → 发布集成 → MCP Server」创建端点,客户端连接 `/mcp/<endpoint_id>` |
| 认证 | 空间 API Key(`WEKNORA_API_KEY`) | 每个端点独立令牌,可轮换、停用 |
| 传输 | 直接调 REST | Streamable HTTP;仅支持 stdio 的客户端通过 `mcp-remote` 桥接 |
| 能力范围 | 导入、检索、浏览(5 类) | 按端点勾选:检索与阅读、问答(端点默认 Agent)、Wiki、写入;可限定知识库范围 |
| 文档 | 本篇 | [MCP 集成](../03-features/08-mcp.md) |
需要会话、模型管理或 Wiki 工具时,使用 MCP Server;导入、检索和浏览资料可使用 Claw Skill。
需要问答、Wiki 工具,或希望按端点限定工具和知识库范围时,使用 MCP Server;在 OpenClaw 生态中导入、检索和浏览资料可使用 Claw Skill。仓库 `mcp-server/` 下的 Python MCP 服务已弃用,新接入请使用内置 MCP Server。
## 相关文档 {#相关}

View File

@ -19,6 +19,11 @@ WeKnora 通过 BrowserSkill daemon 和 [BrowserSkill](https://github.com/Tencent
3. 在智能推理输入框开启「本机浏览器」,再提交任务。配对成功不代表每轮自动启用。
4. 首次调用创建独立任务窗口;对话预览可定位页面、暂停、继续或结束当前浏览器任务。
<Screenshot
src="/screenshots/browser-connection.png"
caption="工具箱 → 浏览器连接:配对链接、连接状态与扩展安装入口"
hint="已配对且在线的状态:标签上的连接状态、设备信息、配对链接区、Chrome/Edge 商店入口与「手动安装(备用)」、「在侧边栏显示连接状态」开关;侧边栏工具箱旁可见绿色状态圆点。" />
连接状态显示在「浏览器连接」标签上(已连接、离线或未配对)。已配对时,侧边栏「工具箱」右侧的浏览器小图标也会用圆点标出状态:绿色为已连接,橙色为离线。不需要时可以在「浏览器连接」页关闭「在侧边栏显示连接状态」,该设置只保存在当前浏览器。同一页还可以设置「浏览器搜索指令」,指定偏好的搜索引擎和搜索地址。
授权按空间和用户保存;同一空间内多个对话共用设备授权,但各有任务。当前每个空间+用户保留一个设备授权,激活新设备会替换旧设备。

View File

@ -129,7 +129,7 @@ make package-mac-app # 打 macOS .app(scripts/package-mac-app.sh)
| --- | --- |
| `docker-build-app` | 构建 `wechatopenai/weknora-app`(`docker/Dockerfile.app`,注入 `scripts/get_version.sh` 的版本信息) |
| `docker-build-docreader` | 构建 `wechatopenai/weknora-docreader`(`docker/Dockerfile.docreader`) |
| `docker-build-frontend` | 多阶段构建 `wechatopenai/weknora-ui`(builder 内 `npm ci` + `npm run build`,无需宿主机预构建 dist) |
| `docker-build-frontend` | 多阶段构建 `wechatopenai/weknora-ui`(builder 内 `npm ci` + `npm run build`,无需宿主机预构建 dist;自动从 git 注入 `VITE_FRONTEND_COMMIT`) |
| `docker-build-all` | 以上三个镜像 |
| `docker-run` | 确保 `.env` 存在(缺失时从 `.env.example` 复制或 touch)后 `docker-compose up` |
| `docker-stop` / `docker-restart` | `docker-compose down` / `stop -t 60` + `up` |
@ -160,6 +160,16 @@ make package-mac-app # 打 macOS .app(scripts/package-mac-app.sh)
| `build-lite` / `run-lite` / `package-lite` / `package-mac-app` | Lite 模式构建/运行/打包(见 2.3) |
| `download_spatial` | `go run cmd/download/duckdb/duckdb.go` 下载 DuckDB spatial 扩展(数据分析工具用) |
### 模型厂商目录 {#_3-5-模型厂商目录}
| 目标 | 作用 |
| --- | --- |
| `model-catalog-generate` | `python3 scripts/model-catalog/generate.py`,重新生成厂商目录的元数据与协议覆盖 |
| `model-catalog-check` | 校验生成结果是否最新,并运行 `go test ./internal/models/...`(CI 同样校验) |
| `model-catalog-diff` | 对比 models.dev 输出模型元数据差异报告,仅供人工审阅,不写回文件;可用 `VENDOR=deepseek` 只看单个厂商 |
厂商接入方式见[扩展点](03-extension-points.md)。
## 测试体系 {#_4-测试体系}
### Go 单元测试(主模块) {#_4-1-go-单元测试-主模块}
@ -236,20 +246,27 @@ make fmt && make lint && make test
注意格式化标准是 **gofumpt**(比 gofmt 更严格),行宽上限 120。
也可以安装仓库自带的 Git hooks(`./scripts/install-git-hooks.sh`,把 `core.hooksPath` 指向 `scripts/git-hooks`):pre-commit 检查空白字符、自动 gofmt 并在已安装时运行 golangci-lint;pre-push 按 CI 执行 gofmt 与 `go vet` / `go test` / `go build`。临时跳过可设 `SKIP_HOOKS=1`,只跳过 pre-push 的测试可设 `HOOK_SKIP_TEST=1`。
新增或升级第三方依赖、改动随发行物分发的数据文件时,需同步更新 `THIRD_PARTY_NOTICES.md` 与 `licenses/`,并用 `scripts/check-license-bundle.sh` 自检(`app.yml` 会执行同样的检查)。
### CI 与提交流程 {#_5-2-ci-与提交流程}
`.github/` 下的实际配置:
| 文件 | 触发路径 | 作用 |
| --- | --- | --- |
| `workflows/app.yml` | 根模块 Go 代码、`go.mod`、`config/`、`migrations/`、`scripts/`、`docker/Dockerfile.app` | 主模块检查:gofmt 格式校验(只针对 PR 内的提交)、`go vet`、`go test`、`go build ./cmd/server` |
| `workflows/frontend.yml` | `frontend/`、`scripts/build_frontend_dist.sh` | Node 24:`npm test` + `npm run type-check` + `npm run build`;另构建 `frontend/Dockerfile` 多阶段镜像(不推送) |
| `workflows/app.yml` | 根模块 Go 代码、`go.mod`、`config/`、`migrations/`、`scripts/`、`docker/Dockerfile.app`、许可证文件、模型目录数据 | 主模块检查:gofmt 格式校验(只针对 PR 内的提交)、`go vet`、`go test`、`go build ./cmd/server`;另校验第三方许可证包、模型厂商目录生成结果与 Git hooks 测试 |
| `workflows/go-lint.yml` / `go-lint-cache.yml` | PR / main | golangci-lint 只报告 PR 相对合并基线新增的问题;`go-lint-cache.yml` 在 main 上预热缓存 |
| `workflows/frontend.yml` | `frontend/`、`scripts/build_frontend_dist.sh` | Node 24:`npm test` + `npm run type-check` + `npm run build`;另构建 `frontend/Dockerfile` 多阶段镜像(不推送),并验证镜像内嵌入页与 MCP 代理路由(`scripts/test_embed_nginx.py`) |
| `workflows/docreader.yml` | `docreader/`、`testdata/`、`packages/`、相关 Dockerfile | uv 装依赖 → `compileall` → `unittest discover docreader/tests`;再拉起 docreader gRPC 服务跑 `go test ./docreader/client ./docreader/proto` |
| `workflows/mcp-server.yml` | `mcp-server/` | Python 3.10-3.13 矩阵测试;合入 main 后按 `pyproject.toml` 里的版本号用 PyPI Trusted Publishing 自动发布(版本已存在则跳过上传,不依赖打 tag) |
| `workflows/cli.yml` | `cli/` | ubuntu/macos/windows 三平台矩阵,Go 1.26,`go build` + `go test -race -coverprofile` + `go vet` + skill wire 词表检查 |
| `workflows/cli-e2e.yml` | 手动 / label | CLI 端到端验收(label `acceptance-e2e` 或手动触发,见 4.3) |
| `workflows/docker-image.yml` | — | Docker 镜像构建发布 |
| `workflows/release-lite.yml` | — | Lite 版本发布 |
| `workflows/anydoc.yml` | `third_party/anydoc-go/`、`internal/infrastructure/docparser/` | 进程内 Office 解析引擎构建与测试 |
| `workflows/dsh-plugin.yml` | `packages/dsh-weknora/` | DeepSeek Harness 插件测试与发布 |
| `pull_request_template.md` | — | PR 模板 |
| `ISSUE_TEMPLATE/` | — | Issue 模板 |
| `dependabot.yml` | — | 依赖升级机器人 |

View File

@ -20,15 +20,16 @@ WeKnora 使用版本化迁移维护数据库结构,PostgreSQL 与 SQLite 分
```text
migrations/
├── versioned/ # PostgreSQL/ParadeDB 版本化迁移:000000-000091 共 92 版(184 个 .up/.down.sql 文件)
├── sqlite/ # SQLite 迁移:000000_init(压平的全量 schema)+ 其后的增量版本
├── paradedb/ # ParadeDB 附加脚本:00-init-db.sql(扩展初始化)、01-migrate-to-paradedb.sql(存量库切换)
├── versioned/ # PostgreSQL/ParadeDB 版本化迁移:000000-000110 共 111 版(222 个 .up/.down.sql 文件)
├── sqlite/ # SQLite 迁移:000000_init(压平的全量 schema)+ 000001-000030 增量版本
├── paradedb/ # ParadeDB 附加脚本:00-init-db.sql、01-migrate-to-paradedb.sql(存量库切换)
└── mysql/ # 00-init-db.sql,遗留的一次性 MySQL 建表脚本(未接入代码)
```
- PostgreSQL 的 `versioned/` 从 `000000_init` 到 `000091_mcp_tool_enabled`;
- `sqlite/` 以 `000000_init` 作为压平后的全量初始化(JSONB→TEXT、SERIAL→AUTOINCREMENT 等方言差异已适配),其后按需追加增量版本(当前到 `000013_mcp_tool_enabled`),同样由 golang-migrate 顺序执行;
- `paradedb/00-init-db.sql` 创建 `pg_search` 等扩展;BM25 索引使用中文 Lindera 分词器建在 `embeddings.content` 上。
- PostgreSQL 的 `versioned/` 从 `000000_init` 到 `000110_im_channel_locale`;
- `sqlite/` 以 `000000_init` 作为压平后的全量初始化(JSONB→TEXT、SERIAL→AUTOINCREMENT 等方言差异已适配),其后追加增量版本(当前到 `000030_im_channel_locale`),同样由 golang-migrate 顺序执行;
- `uuid-ossp`、`vector`、`pg_trgm`、`pg_search` 等扩展由 `versioned/` 迁移自行创建(000000、000002);BM25 索引使用中文 Lindera 分词器建在 `embeddings.content` 上;
- `paradedb/00-init-db.sql` 除扩展外还含一份旧版建表语句,**没有被 compose 或代码引用**。不要把它挂成数据库 initdb 脚本:它先建出的旧表会让 `000000_init` 失败。
### versioned/ 迁移史概览(按主题) {#_2-1-versioned-迁移史概览-按主题}
@ -41,16 +42,16 @@ migrations/
| 000019-000028 | 消息/IM 增强 | `messages` 扩列(images、rendered_content、agent_duration_ms)、`im_channels`、`im_channel_sessions` |
| 000029-000036 | 数据源与向量库抽象 | `data_sources`、`sync_logs`、`web_search_providers`、`vector_stores`、KB 的 asr_config/vector_store_id |
| 000037-000041 | Wiki 与任务队列 | `wiki_pages`、`wiki_folders`、`wiki_page_issues`、`wiki_log_entries`(已于 000077 移除)、`task_pending_ops`、`task_dead_letters` |
| 000042-000054 | RBAC / 审计 / 邀请 | `mcp_tool_approvals`、`tenant_members`、`audit_logs`、`organization_tenant_members`、`user_resource_favorites`、`tenant_invitations`、`user_kb_pins`、`invitation_tokens` |
| 000055-000060 | 处理管道与嵌入渠道 | `knowledge_processing_spans`、`knowledge_pending_subtasks`、`embed_channels`、HNSW 1024 维索引 |
| 000061-000067 | Wiki 层级 / OAuth / 文档多标签 / 建议问题 | `wiki_pages` 层级列、`mcp_oauth_clients`、`mcp_oauth_tokens`、`knowledge_tag_relations`、`principals`、`principal_models`、`tenant_api_keys`、`message_suggestion_sets`、`message_suggestion_events` |
| 000042-000054 | RBAC / 审计 / 邀请 / 系统设置 | `mcp_tool_approvals`、`tenant_members`、`audit_logs`、`organization_tenant_members`(原 `organization_members` 改名归档)、`user_resource_favorites`、`tenant_invitations`、`user_kb_pins`、`system_settings` 与 `users.is_system_admin`(000053)、邀请链接列 `tenant_invitations.token`/`accepted_count`(000054) |
| 000055-000060 | 处理管道与嵌入渠道 | `knowledge_processing_spans`、`knowledges.pending_subtasks_count`(000056,`finalizing` 状态计数)、`embed_channels`、HNSW 1024 维索引 |
| 000061-000067 | Wiki 层级 / OAuth / 文档多标签 / 主体身份 / 建议问题 | `wiki_pages` 层级列、`mcp_oauth_clients`、`mcp_oauth_tokens`、`knowledge_tag_relations`、主体身份列(000064:`tenants.api_principal_config`、`mcp_oauth_tokens.principal_type`/`principal_id`)、`tenant_api_keys`(000065,同时移除 `tenants.api_key`)、`message_suggestion_sets`、`message_suggestion_events` |
| 000068-000074 | 存储/资源/临时文档 | `storage_backends`、`resources`、`resource_bindings`、`resource_access_grants`、`temporary_documents`、平台级 API key、OAuth 刷新租期 |
| 000075-000076 | Wiki 版本历史与索引 | `wiki_page_revisions`、`wiki_pages.last_edit_source`/`last_editor_id`、`knowledges.metadata->>'external_id'` 前缀索引 |
| 000077 | 移除 Wiki 操作日志 | DROP `wiki_log_entries`,并删除历史遗留的 `page_type = 'log'` 页面;Wiki 变更统一记入知识库活动流 |
| 000078 | 分块编辑与自定义元数据 | `chunks` 增加 `source_content`/`content_revision`/`index_status`/`last_editor_id`/`context_header`,新增 `chunk_revisions` 表,`knowledges` 增加 `custom_metadata` |
| 000079 | 知识库文件夹树 | `knowledges` 增加 `folder_path` 列并回填历史目录上传(原先路径塞在 `file_name` 里),新增 `(tenant_id, knowledge_base_id, folder_path)` 索引 |
### 新增迁移(000080–000091) {#_2-2-新增迁移-000080–000091}
### 000080 之后的迁移 {#_2-2-000080-之后的迁移}
| 版本 | 变更 |
| --- | --- |
@ -66,8 +67,25 @@ migrations/
| 000089 | 技能 envs、tenant_user_env_vars |
| 000090 | tenant_skill_catalog;tenant_skills.catalog_id,回填已有安装 |
| 000091 | mcp_tool_approvals.enabled,默认 true |
| 000092 | mcp_services.usage_instructions;`mcp_metadata` 表,持久化 MCP 服务的工具目录快照 |
| 000093 | `browser_devices`、`browser_pairings`、`browser_task_interruptions`,浏览器连接的设备授权与配对 |
| 000094 | memory_subjects.extraction_state、memory_items.replaces_id、`memory_extraction_sessions` 表(按会话记录抽取进度);修复旧版本中待确认推断过早替换已生效记忆的数据 |
| 000095 | memory_item_embeddings.embedding(halfvec,仅在已安装 `vector` 扩展时添加)与检索索引 |
| 000096 | 数据迁移:钉钉渠道 `mode` 从 webhook 改为 websocket(Stream)。需在钉钉开发者后台开启 Stream 模式;down 为空操作 |
| 000097 | 会话分叉:sessions.parent_session_id / forked_from_message_id / fork_bootstrap,messages.sandbox_checkpoint |
| 000098 | `fork_snapshot_leases` 表,记录分叉会话落库前拍下的沙箱快照,便于回收 |
| 000099 | 将已安装的 pg_search 0.22.2–0.22.5 升级到 0.22.6;镜像未提供 0.22.6、其他版本或 `app.skip_embedding=true` 时跳过 |
| 000100 | 删除 chunks 上只拖慢写入的三个索引:`idx_chunks_chunk_type`、`idx_chunks_content_hash`、`idx_chunks_tenant_kg` |
| 000101 | knowledges.profile(文档画像),knowledge_bases.profile_config / generated_profile(AI 知识库描述) |
| 000102 | `mcp_endpoints` 表,空间对外发布的 MCP 端点 |
| 000103 | `message_artifacts` 表,从 `messages.artifacts` 回填;此后只读写新表。回填后旧列中有内容的行置为 NULL(列保留,兼容滚动升级中的旧实例);无法解析的 `file_size`/`created_at` 回退为 0 和消息创建时间,不中断迁移。down 迁移会把新表写回旧列 |
| 000104 | tenant_skills.served,新版本安装中或失败时记录仍在镜像中提供的版本 |
| 000105 | messages.context_checkpoint,Agent 上下文压缩摘要 |
| 000106 | messages `(session_id, created_at DESC, id DESC)` 索引 `idx_messages_session_created_id`,以 `CREATE INDEX CONCURRENTLY` 创建,不阻塞写入;构建中断会留下 INVALID 索引,需先 `DROP INDEX` 再重跑迁移 |
| 000107 | message_artifacts.deleted_at,用户删除的文件保留为墓碑行 |
| 000108 | sessions.sandbox_config_tenant_id(BIGINT,默认 0),记录会话所用沙箱配置属于哪个空间;按沙箱配置回填使用共享 Agent 的会话 |
| 000109 | sessions.host_workspace_dir(VARCHAR(1024)),Lite 桌面版主机沙箱的项目目录,创建后不再修改 |
| 000110 | im_channels.locale(VARCHAR(16),默认空串),IM 渠道固定回复语言,空串使用部署默认值 |
SQLite 版本号独立演进,不能与 PostgreSQL 数字一一对应:
@ -76,40 +94,50 @@ SQLite 版本号独立演进,不能与 PostgreSQL 数字一一对应:
| 000001–000002 | 移除 Wiki 日志、文件夹路径 |
| 000003–000004 | 自动标签、长期记忆 |
| 000005 | 消息附件与邀请字段 |
| 000006–000008 | 任务/死信、系统管理与设置、处理 spans/待处理子任务 |
| 000006–000008 | 任务/死信、系统管理与设置、处理 spans/待处理子任务计数 |
| 000009 | 历史 Embed memory 标志列;当前渠道接口不暴露此字段 |
| 000010–000011 | 多标签关联、principal 模型 |
| 000012–000013 | 消息 usage、MCP 工具 enabled |
| 000023 | `message_artifacts` 表,回填并清空旧列(对应 PostgreSQL 000103) |
| 000012–000013 | 消息 usage、MCP 工具 enabled(对应 000085、000091) |
| 000014–000016 | 浏览器授权、记忆一致性、记忆向量检索索引(对应 000093–000095;SQLite 无向量列,仍在应用内排序) |
| 000017 | 钉钉渠道改为 websocket(对应 000096) |
| 000018–000019 | 会话分叉、分叉快照租约(对应 000097–000098) |
| 000020–000022 | chunks 删冗余索引、知识画像、MCP 端点(对应 000100–000102) |
| 000023 | `message_artifacts` 表,回填并清空旧列(对应 000103) |
| 000024–000026 | messages.context_checkpoint、messages 会话时间索引、message_artifacts.deleted_at(对应 000105–000107) |
| 000027 | sessions.sandbox_config_tenant_id(对应 000108;Lite 无共享空间,不回填) |
| 000028 | 补建 `tenant_skills`、`tenant_skill_snapshots`、`tenant_skill_catalog`、`tenant_user_env_vars`(对应 000086–000090 与 000104)。此前 Lite 缺这四张表,技能读取凭据时报 `no such table` |
| 000029–000030 | sessions.host_workspace_dir、im_channels.locale(对应 000109–000110) |
000092(`mcp_metadata`、`mcp_services.usage_instructions`)与 000099(pg_search 升级)没有 SQLite 对应版本。
基线 schema 与后续增量共同决定新建库和已有库的最终结果;不能只看新增迁移文件名判断 Lite 是否有某张表。
## 最终表结构 {#_3-最终表结构}
以下为全部 up 迁移叠加后的**最终生效结构**(后续迁移对早期表的 ALTER 已合并)。所有业务表统一带 `created_at` / `updated_at`,多数带 `deleted_at`(GORM 软删除),不再逐一列出。
以下为全部 up 迁移叠加后的**最终生效结构**(后续迁移对早期表的 ALTER 已合并)。多数业务表带 `created_at` / `updated_at`,不少带 `deleted_at`(GORM 软删除),不再逐一列出。
### 租户与用户 {#_3-1-租户与用户}
| 表 | 用途 | 关键字段 |
| --- | --- | --- |
| `tenants` | 租户(工作空间),多租户体系根 | `id`(SERIAL,起始 10000)、`name`、`api_key`(唯一索引)、`retriever_engines`(JSONB)、`status`、`storage_quota`/`storage_used`、`agent_config`/`context_config`/`conversation_config`/`web_search_config`/`credentials`(JSONB)、`default_storage_backend_id`、`memory_config` |
| `users` | 登录用户 | `id`(UUID)、`username`(唯一)、`email`(唯一)、`password_hash`、`tenant_id`(FK→tenants,ON DELETE SET NULL)、`is_active`、`can_access_all_tenants`(系统管理员)、`preferences`(JSON) |
| `tenants` | 租户(工作空间),多租户体系根 | `id`(SERIAL,起始 10000)、`name`、`retriever_engines`(JSONB)、`status`、`storage_quota`/`storage_used`、`agent_config`/`context_config`/`conversation_config`/`web_search_config`/`credentials`/`api_principal_config`/`memory_config`(JSONB)、`default_storage_backend_id`。原 `api_key` 列已在 000065 迁入 `tenant_api_keys` 并删除 |
| `users` | 登录用户 | `id`(UUID)、`username`(唯一)、`email`(唯一)、`password_hash`、`tenant_id`(FK→tenants,ON DELETE SET NULL)、`is_active`、`can_access_all_tenants`(跨空间访问)、`is_system_admin`(系统管理员,000053)、`preferences`(JSON) |
| `auth_tokens` | 登录令牌 | `id`、`user_id`(FK→users,CASCADE)、`token`、`token_type`(access/refresh)、`expires_at`(TIMESTAMPTZ,000072 起)、`is_revoked` |
| `tenant_members` | 租户级 RBAC 成员关系 | `user_id`+`tenant_id`(软删除下唯一)、`role`(owner/admin/contributor/viewer)、`status`、`invited_by`、`joined_at` |
| `tenant_invitations` | 站内邀请 | `tenant_id`、`invitee_user_id`、`role`、`status`(pending/accepted/rejected)、`expires_at`;pending 唯一约束 |
| `invitation_tokens` | 邀请链接令牌(000054) | token 与租户/角色绑定 |
| `tenant_invitations` | 站内邀请与邀请链接 | `tenant_id`、`invitee_user_id`、`role`、`status`(pending/accepted/rejected)、`expires_at`;pending 唯一约束;`token`(邀请链接,唯一)/`accepted_count`(000054) |
| `tenant_api_keys` | 租户/平台 API Key | `tenant_id`(platform 作用域时为 NULL)、`scope_type`(tenant/platform,CHECK 约束)、`key_hash`(唯一)、`full_access`、`knowledge_base_ids`、`capabilities`、`expires_at`/`revoked_at` |
| `user_kb_pins` | 用户级知识库置顶 | PK(`tenant_id`,`user_id`,`kb_id`)+ `pinned_at` |
| `user_resource_favorites` | 用户收藏 | PK(`user_id`,`tenant_id`,`resource_type`,`resource_id`) |
| `system_settings` | 系统级设置(000053) | `key`、`value`/`value_type`、`category`、`is_secret`、`requires_restart`、`last_modified_by` |
| `audit_logs` | 审计日志(000044) | `tenant_id`、`actor_user_id`/`actor_role`、`action`、`target_type`/`target_id`/`target_user_id`、`request_path`/`request_method`、`outcome`(success/denied)、`scope_type`/`scope_id`、`details`(JSONB) |
### 模型与知识库 {#_3-2-模型与知识库}
| 表 | 用途 | 关键字段 |
| --- | --- | --- |
| `models` | AI 模型配置(LLM/embedding/rerank 等) | `id`、`tenant_id`(FK→tenants,CASCADE)、`name`/`display_name`、`type`(embedding/summary/rerank/llm…)、`source`、`parameters`(JSONB)、`is_default`、`is_builtin`、`managed_by`、`status` |
| `knowledge_bases` | 知识库 | `id`(UUID)、`tenant_id`、`name`、`type`(document/faq)、`chunking_config`/`image_processing_config`/`vlm_config`/`faq_config`/`asr_config`/`wiki_config`/`indexing_strategy`/`auto_tag_config`/`profile_config`/`generated_profile`(JSONB)、`embedding_model_id`/`summary_model_id`(FK→models)、`vector_store_id`(FK→vector_stores)、`storage_backend_id`(FK→storage_backends)、`creator_id`(FK→users)、`is_temporary`、`activity_scope` |
| `knowledges` | 知识条目(文档/网页/FAQ 等) | `id`、`tenant_id`、`knowledge_base_id`(FK)、`type`、`title`、`source`(VARCHAR(2048))、`parse_status`(unprocessed/processing/completed/failed)、`enable_status`、`file_name`/`file_type`/`file_size`/`file_path`/`file_hash`、`metadata`(内部入库状态)、`custom_metadata`(JSONB,用户自填元数据,000078)、`folder_path`(目录树路径,000079)、`summary_status`、`profile`(JSONB,文档画像:gist/主题/类型/典型问题,000101)、`channel`、`processed_at`/`error_message`。**没有 `tag_id` 列**——000063 起标签走 `knowledge_tag_relations` 关联表 |
| `models` | AI 模型配置(LLM/embedding/rerank 等) | `id`、`tenant_id`(FK→tenants,CASCADE)、`name`/`display_name`、`type`(`KnowledgeQA` / `Embedding` / `Rerank` / `VLLM` / `ASR`)、`source`、`parameters`(JSONB;v0.8.2 起可含可选的 `spec` 覆盖协议与能力,无需迁移)、`is_default`、`is_builtin`、`managed_by`、`status` |
| `knowledge_bases` | 知识库 | `id`(UUID)、`tenant_id`、`name`、`type`(document/faq/wiki)、`chunking_config`/`image_processing_config`/`vlm_config`/`faq_config`/`asr_config`/`wiki_config`/`indexing_strategy`/`auto_tag_config`/`profile_config`/`generated_profile`(JSONB)、`embedding_model_id`/`summary_model_id`(FK→models)、`vector_store_id`(FK→vector_stores)、`storage_backend_id`(FK→storage_backends)、`creator_id`(FK→users)、`is_temporary`、`activity_scope` |
| `knowledges` | 知识条目(文档/网页/FAQ 等) | `id`、`tenant_id`、`knowledge_base_id`(FK)、`type`、`title`、`source`(VARCHAR(2048))、`parse_status`(pending/processing/finalizing/completed/failed/cancelled/deleting)、`pending_subtasks_count`(000056,`finalizing` 阶段未完成的增强子任务数)、`enable_status`、`file_name`/`file_type`/`file_size`/`file_path`/`file_hash`、`metadata`(内部入库状态)、`custom_metadata`(JSONB,用户自填元数据,000078)、`folder_path`(目录树路径,000079)、`summary_status`、`profile`(JSONB,文档画像:gist/主题/类型/典型问题,000101)、`channel`、`processed_at`/`error_message`。**没有 `tag_id` 列**——000063 起标签走 `knowledge_tag_relations` 关联表 |
| `chunks` | 分块(检索最小单元) | `id`、`tenant_id`、`knowledge_base_id`、`knowledge_id`(FK)、`content`、`source_content`(解析器原始输出,不可变)、`content_revision`、`index_status`(ready/processing/failed)、`last_editor_id`、`context_header`(索引用标题面包屑)、`chunk_index`、`start_at`/`end_at`、`pre_chunk_id`/`next_chunk_id`(链表)、`parent_chunk_id`(父子分块自引用)、`chunk_type`(text/image/…)、`image_info`/`video_info`、`relation_chunks`/`indirect_relation_chunks`(JSONB)、`is_enabled`、`flags`、`status`、`content_hash`、`seq_id`、`tag_id` |
| `chunk_revisions` | 分块历史版本(000078) | `id`、`tenant_id`、`knowledge_base_id`、`knowledge_id`、`chunk_id`+`revision`(唯一索引)、`content`、`is_enabled`、`editor_id`、`edit_source`、`edited_at` |
| `embeddings` | 向量 + BM25 索引(Postgres/ParadeDB 检索引擎专用,受 `app.skip_embedding` 门控) | `id`、`source_id`+`source_type`(唯一,chunk/wiki 页等来源)、`chunk_id`/`knowledge_id`/`knowledge_base_id`、`content`(BM25 全文)、`dimension`、`embedding`(halfvec,HNSW 索引按 768/1024/3584 维分建)、`is_enabled`、`tag_id` |
@ -121,9 +149,9 @@ SQLite 版本号独立演进,不能与 PostgreSQL 数字一一对应:
| 表 | 用途 | 关键字段 |
| --- | --- | --- |
| `sessions` | 会话(对话上下文与检索参数快照) | `id`、`tenant_id`、`title`、`knowledge_base_id`、`agent_id`(FK→custom_agents)、`user_id`、`max_rounds`、`enable_rewrite`、`fallback_strategy`/`fallback_response`、`keyword_threshold`/`vector_threshold`、`embedding_top_k`/`rerank_top_k`/`rerank_threshold`、`rerank_model_id`/`summary_model_id`、`agent_config`/`context_config`(JSONB)、`sandbox_config_id` |
| `messages` | 消息 | `id`、`request_id`、`session_id`(FK)、`role`、`content`/`rendered_content`、`knowledge_references`(JSONB 引用)、`agent_steps`(JSONB,Agent 推理轨迹)、`mentioned_items`/`images`(JSONB)、`is_completed`/`is_fallback`、`channel`(web/IM 渠道)、`agent_id`+`agent_tenant_id`、`model_id`、`knowledge_id`、`agent_duration_ms`、`execution_context`、`used_memories`/`usage`(JSONB)。`artifacts` 列自 000103 起不再读写且已清空(仅为回滚与滚动升级保留),生成文件见 `message_artifacts` |
| `message_artifacts` | 技能生成的文件,一行一个(000103) | `session_id`、`message_id`、`position`(消息内序号,即下载接口的 index;与 `message_id` 唯一)、`url`(存储或 resource:// 引用,不返回客户端)、`file_name`/`file_type`/`file_size`、`content_hash`、`source_path`(同会话同路径视为同一文件的多个版本)、`mod_time`(RFC 3339 文本,保留纳秒精度供采集器比对)、`created_at`。无软删除,随消息软删除一并隐藏 |
| `sessions` | 会话(对话上下文与检索参数快照) | `id`、`tenant_id`、`title`、`knowledge_base_id`、`agent_id`(FK→custom_agents)、`user_id`、`max_rounds`、`enable_rewrite`、`fallback_strategy`/`fallback_response`、`keyword_threshold`/`vector_threshold`、`embedding_top_k`/`rerank_top_k`/`rerank_threshold`、`rerank_model_id`/`summary_model_id`、`agent_config`/`context_config`(JSONB)、`sandbox_config_id`/`sandbox_config_tenant_id`(沙箱配置及其所属空间,0 表示会话自身空间,000108)、`parent_session_id`/`forked_from_message_id`/`fork_bootstrap`(会话分叉,000097;不设外键)、`host_workspace_dir`(Lite 桌面版项目目录,000109) |
| `messages` | 消息 | `id`、`request_id`、`session_id`(FK)、`role`、`content`/`rendered_content`、`knowledge_references`(JSONB 引用)、`agent_steps`(JSONB,Agent 推理轨迹)、`mentioned_items`/`images`(JSONB)、`is_completed`/`is_fallback`、`channel`(web/IM 渠道)、`agent_id`+`agent_tenant_id`、`model_id`、`knowledge_id`、`agent_duration_ms`、`execution_context`、`attachments`、`used_memories`/`usage`(JSONB)、`sandbox_checkpoint`(分叉点的沙箱检查点,000097)、`context_checkpoint`(Agent 上下文压缩摘要,000105)。`artifacts` 列自 000103 起不再读写且已清空(仅为回滚与滚动升级保留),生成文件见 `message_artifacts` |
| `message_artifacts` | 技能生成的文件,一行一个(000103) | `session_id`、`message_id`、`position`(消息内序号,即下载接口的 index;与 `message_id` 唯一)、`url`(存储或 resource:// 引用,不返回客户端)、`file_name`/`file_type`/`file_size`、`content_hash`、`source_path`(同会话同路径视为同一文件的多个版本)、`mod_time`(RFC 3339 文本,保留纳秒精度供采集器比对)、`created_at`、`deleted_at`(000107,用户删除文件后保留墓碑行,保持 `position` 稳定且不被重新采集)。消息被软删除时其文件一并隐藏 |
| `message_suggestion_sets` | 建议问题集(000067) | `tenant_id`、`session_id`、`assistant_message_id`、`placement`(starter/follow_up)、`config_hash`+`locale`(缓存键,唯一)、`status`、`questions`(JSONB)、token/延迟统计、`lease_until` |
| `message_suggestion_events` | 建议问题曝光/点击事件 | `suggestion_set_id`(FK,CASCADE)、`question_id`、`event_type`、`actor_id` |
| `temporary_documents` | 会话内临时文档(000070) | `tenant_id`、`session_id`、`resource_ref`、`file_name`/`file_type`/`file_size`、`status`(uploaded/processing/ready/expired)、`content`、`chunks`(JSONB)、`expires_at` |
@ -133,11 +161,20 @@ SQLite 版本号独立演进,不能与 PostgreSQL 数字一一对应:
| 表 | 用途 | 关键字段 |
| --- | --- | --- |
| `custom_agents` | 自定义 Agent | **复合主键 (`id`,`tenant_id`)**、`name`、`is_builtin`、`created_by`(FK→users)、`runnable_by_viewer`、`config`(JSONB:模式/模型/工具/知识范围) |
| `mcp_services` | MCP 服务配置 | `id`、`tenant_id`、`name`、`enabled`、`transport_type`(stdio/sse/…)、`url`/`headers`/`auth_config`/`stdio_config`/`env_vars`(JSONB)、`is_builtin` |
| `mcp_services` | MCP 服务配置 | `id`、`tenant_id`、`name`、`enabled`、`transport_type`(stdio/sse/…)、`url`/`headers`/`auth_config`/`advanced_config`/`stdio_config`/`env_vars`(JSONB)、`is_builtin`、`usage_instructions`(本地维护的使用说明,000092) |
| `mcp_metadata` | MCP 工具目录快照(000092) | PK(`tenant_id`,`service_id`,`principal`),静态认证时 `principal` 为空串、OAuth 服务按用户主体分行;`config_fingerprint`、`tools`(JSONB)、`instructions`、`server_name`/`server_version`/`server_description`、`synced_at`;随服务删除级联 |
| `mcp_endpoints` | 空间对外发布的 MCP 端点(000102) | `tenant_id`、`name`/`description`、`enabled`、`token_hash`(Bearer token 的 SHA-256,未删除行唯一,明文只显示一次)/`token_hint`、`knowledge_base_ids`(JSONB,空数组表示全部知识库)、`tools`(JSONB 白名单)、`default_agent_id`、`rate_limit_per_minute`(默认 60)、`last_used_at` |
| `mcp_tool_approvals` | MCP 工具审批策略(000042) | (`tenant_id`,`service_id`,`tool_name`) 唯一、`require_approval`、`enabled`(默认 true) |
| `mcp_oauth_clients` | MCP OAuth 客户端(000062) | (`tenant_id`,`service_id`) 唯一、`client_id`/`client_secret`/`redirect_uri` |
| `mcp_oauth_tokens` | MCP OAuth 令牌 | (`tenant_id`,`user_id`,`service_id`) 唯一、`access_token`/`refresh_token`、`expires_at`、`refresh_lease_id`/`refresh_lease_until`(000074,防并发刷新) |
| `principals` / `principal_models` | 主体—模型授权(000064) | 主体(用户/租户)可用模型映射 |
| `mcp_oauth_tokens` | MCP OAuth 令牌 | (`tenant_id`,`principal_type`,`principal_id`,`service_id`) 唯一(000064 起按主体,原按 `user_id`)、`access_token`/`refresh_token`、`expires_at`、`refresh_lease_id`/`refresh_lease_until`(000074,防并发刷新) |
### 浏览器连接
| 表 | 用途与关键字段 |
| --- | --- |
| `browser_devices` | 已授权的浏览器扩展设备(000093),每个空间内每个用户一台;label、token_hash/previous_hash(只存 SHA-256,令牌轮换有宽限期)、expires_at/renew_after、last_seen_at、revoked_at、在线租约 owner/lease_until |
| `browser_pairings` | 一次性配对令牌哈希与过期时间 |
| `browser_task_interruptions` | 需要用户显式恢复的中断任务(scope_key + session) |
### 沙箱与技能
@ -145,9 +182,10 @@ SQLite 版本号独立演进,不能与 PostgreSQL 数字一一对应:
| --- | --- |
| `tenant_sandbox_configs` | id、tenant_id、name、sandbox_type、config(JSONB)、cordoned_at;未删除配置在空间内名称唯一 |
| `tenant_skill_catalog` | 空间技能定义;name/version/description/instructions、bundle_ref/bundle_sha256,空间内名称唯一 |
| `tenant_skills` | catalog_id 与 sandbox_config_id 对应一次安装;enabled/status/error、installed_snapshot_id、installing_since、install_session_id/install_message_id、envs |
| `tenant_skills` | catalog_id 与 sandbox_config_id 对应一次安装;enabled/status/error、installed_snapshot_id、installing_since、install_session_id/install_message_id、envs、served(新版本安装中或失败时仍在提供的版本,000104) |
| `tenant_skill_snapshots` | sandbox_config_id、skill_id、snapshot_id/parent_snapshot_id、generation、trigger/state、planned_name、superseded_at |
| `tenant_user_env_vars` | tenant_id、principal_type/principal_id、sandbox_config_id、skill_id、name、加密 value;空 skill_id 表示配置级变量 |
| `fork_snapshot_leases` | snapshot_id(PK)、tenant_id、sandbox_config_id、created_at;会话分叉时先记下沙箱快照,分叉失败或进程中断后由后台回收(000098) |
目录定义与安装分开;禁用技能只改变可见性。个人变量使用完整 principal 身份,不能按 IM 共享的合成 user_id 合并。空间变量与个人值加密存储,响应不回传个人值明文。
@ -155,12 +193,13 @@ SQLite 版本号独立演进,不能与 PostgreSQL 数字一一对应:
| 表 | 用途与关键字段 |
| --- | --- |
| `memory_subjects` | (tenant_id,subject_id) 唯一;个人 enabled、常驻 block_text、item_count、extract_cursor/pending_sessions/extract_scheduled_at、整理时间 |
| `memory_items` | kind/content/topic/normalized_key、importance/origin/status、来源会话/消息、valid_from/invalid_at/expires_at、superseded_by |
| `memory_subjects` | (tenant_id,subject_id) 唯一;个人 enabled、常驻 block_text、item_count、extract_cursor/pending_sessions/extract_scheduled_at、extraction_state(000094)、整理时间 |
| `memory_extraction_sessions` | PK(tenant_id,subject_id,session_id);按会话记录抽取游标、pending 标记与失败区间(000094) |
| `memory_items` | kind/content/topic/normalized_key、importance/origin/status、来源会话/消息、valid_from/invalid_at/expires_at、superseded_by、replaces_id(待确认条目要替换的旧条目,000094) |
| `memory_tombstones` | 删除/拒绝的主题与内容指纹,用于抑制重复抽取,不保存原正文 |
| `memory_topic_stats` | topic/aliases、hits、last_seen_at/promoted_at |
| `memory_doc_affinity` | knowledge_id/knowledge_base_id/title、hits/last_used_at |
| `memory_item_embeddings` | item_id、model_id、dims、vector;与条目分表存储 |
| `memory_item_embeddings` | item_id、model_id、dims、vector;PostgreSQL 装有 `vector` 扩展时另有 embedding(halfvec,000095)供库内检索,SQLite 在应用内排序;与条目分表存储 |
subject_id 使用 Principal.StorageID(),与 tenant_id 共同隔离身份。向量记录不放进条目列表,也不改变原知识库的访问权。
@ -169,7 +208,7 @@ subject_id 使用 Principal.StorageID(),与 tenant_id 共同隔离身份。向
| 表 | 用途 | 关键字段 |
| --- | --- | --- |
| `organizations` | 组织(跨租户协作单元,000012) | `id`、`name`、`owner_id`(FK→users)、`owner_tenant_id`、`invite_code`(唯一)+ 过期控制、`require_approval`、`searchable`、`member_limit` |
| `organization_members` | 组织的用户成员 | `organization_id`(FK,CASCADE)、`user_id`、`tenant_id`、`role` |
| `organization_members_pre_plan3` | 旧版组织用户成员表(000045 由 `organization_members` 改名归档,仅供回滚) | `organization_id`、`user_id`、`tenant_id`、`role`;成员关系已改由 `organization_tenant_members` 维护 |
| `organization_tenant_members` | 组织的租户成员(000045) | (`organization_id`,`tenant_id`) 唯一、`role`(admin/editor/viewer)、`representative_user_id` |
| `organization_join_requests` | 加入/升级申请 | `organization_id`、`user_id`、`status`(pending 唯一)、`requested_role`、`request_type`(join/upgrade)、审批字段 |
| `kb_shares` | 知识库共享到组织 | (`knowledge_base_id`,`organization_id`) 软删除下唯一、`source_tenant_id`、`permission` |
@ -189,9 +228,9 @@ subject_id 使用 Principal.StorageID(),与 tenant_id 共同隔离身份。向
| 表 | 用途 | 关键字段 |
| --- | --- | --- |
| `data_sources` | 外部数据源连接(Feishu/Lark/GitLab/IMA/Notion/语雀/RSS,000029) | `id`、`tenant_id`、`knowledge_base_id`、`type`、`config`(JSONB 凭证)、`sync_schedule`(cron)、`sync_mode`(incremental/full)、`conflict_strategy`、`sync_deletions`、`last_sync_at`/`last_sync_cursor`/`last_sync_result` |
| `data_sources` | 外部数据源连接(飞书/Lark 知识库与云盘、Notion、Confluence、语雀、钉钉、IMA、RSS、GitLab,000029) | `id`、`tenant_id`、`knowledge_base_id`、`type`、`config`(JSONB 凭证)、`sync_schedule`(cron)、`sync_mode`(incremental/full)、`conflict_strategy`、`sync_deletions`、`last_sync_at`/`last_sync_cursor`/`last_sync_result` |
| `sync_logs` | 每次同步的执行记录 | `data_source_id`(FK,CASCADE)、`status`、`started_at`/`finished_at`、`items_total/created/updated/deleted/skipped/failed`、`error_message` |
| `im_channels` | IM 渠道接入配置(企业微信/飞书/Slack 等) | `tenant_id`、`platform`、`agent_id`、`knowledge_base_id`、凭证配置 |
| `im_channels` | IM 渠道接入配置(企业微信/飞书/Slack 等) | `tenant_id`、`platform`、`agent_id`、`knowledge_base_id`、`mode`(websocket/webhook;钉钉自 000096 起只用 websocket)、`output_mode`、`session_mode`、`bot_identity`、`credentials`、`locale`(固定回复语言,空串用部署默认值,000110) |
| `im_channel_sessions` | IM 用户/线程 ↔ session 映射 | `im_channel_id`、`session_id`、`agent_id`、平台用户/会话标识 |
| `embed_channels` | 网页嵌入聊天组件渠道(000060) | `tenant_id`、`agent_id`、公开 token/域名配置 |
| `web_search_providers` | 联网搜索引擎配置(000030) | `id`、`tenant_id`、`name`、`provider`(bing/google/tavily/searxng…)、`parameters`(JSONB API key)、`is_default` |
@ -206,7 +245,6 @@ subject_id 使用 Principal.StorageID(),与 tenant_id 共同隔离身份。向
| `resource_access_grants` | 资源临时访问令牌 | `token_hash`(唯一)、`resource_id`、`access_scope`、`expires_at`/`revoked_at` |
| `task_pending_ops` | 通用待处理任务队列(000041) | `tenant_id`、`task_type`、`scope`+`scope_id`、`op`、`dedup_key`、`payload`(JSONB)、`fail_count`、`enqueued_at`/`claimed_at`(并发领取) |
| `task_dead_letters` | 失败任务死信归档 | `task_type`、`scope`/`scope_id`/`related_id`、`payload`、`last_error`、`fail_count`、`failed_at` |
| `knowledge_pending_subtasks` | 知识处理子任务队列(000056) | `knowledge_id`、`attempt`、`task_type`、payload |
| `knowledge_processing_spans` | 文档处理管道 trace(000055) | (`knowledge_id`,`attempt`,`span_id`) 唯一、`parent_span_id`、`name`(DocReader/Chunking/Embedding…)、`kind`、`status`、`input`/`output`/`metadata`(JSONB)、`error_code`/`error_message`、`duration_ms` |
| `schema_migrations` | golang-migrate 状态表(自动维护) | `version`、`dirty` |
@ -238,6 +276,8 @@ erDiagram
tenants ||--o{ sessions : "会话"
sessions ||--o{ messages : "消息"
sessions ||--o{ sessions : "parent_session_id (分叉)"
messages ||--o{ message_artifacts : "生成文件"
sessions }o--o| custom_agents : "agent_id"
sessions }o--o| knowledge_bases : "knowledge_base_id"
messages }o--o| knowledges : "knowledge_id"
@ -250,6 +290,8 @@ erDiagram
mcp_services ||--o{ mcp_tool_approvals : "工具审批"
mcp_services ||--o{ mcp_oauth_clients : "OAuth 客户端"
mcp_services ||--o{ mcp_oauth_tokens : "OAuth 令牌"
mcp_services ||--o{ mcp_metadata : "工具目录快照"
tenants ||--o{ mcp_endpoints : "对外 MCP 端点"
users ||--o{ organizations : "owner_id"
organizations ||--o{ organization_tenant_members : "租户成员"
@ -331,7 +373,7 @@ make migrate-goto version=60 # 迁移/回滚到指定版本
1. **创建文件**:`make migrate-create name=add_my_feature`,在 `migrations/versioned/` 下生成下一个版本号(创建前检查目录,使用下一个空闲版本的 up/down 文件);
2. **编写 up SQL**:注意 PostgreSQL 方言(JSONB、部分索引、`TIMESTAMP WITH TIME ZONE`);若涉及 `embeddings` 表,参考既有迁移用 `app.skip_embedding` GUC 做条件门控(`SELECT current_setting('app.skip_embedding', true)`),保证非 postgres 检索引擎部署也能通过迁移;
3. **编写 down SQL**:必须可逆(drop column/table/index),否则回滚链会断;
4. **同步 SQLite**:`migrations/sqlite/000000_init.up.sql` 是压平的全量 schema,**新增列/表必须合并进去**(注意方言转换:JSONB→TEXT、SERIAL→INTEGER AUTOINCREMENT、无部分索引语法差异等)。若变更需要在已有 Lite 库上生效(例如删表、删数据),还要在 `migrations/sqlite/` 追加一个增量版本;
4. **同步 SQLite**:在 `migrations/sqlite/` 追加下一个空闲版本的增量迁移,镜像同一变更(注意方言转换:JSONB→TEXT、SERIAL→INTEGER AUTOINCREMENT、TIMESTAMPTZ→DATETIME 等)。已有 Lite 库不会重放 `000000_init`,只改基线会让老库缺列/缺表。同时更新 `internal/database/migration_sqlite_versioned_schema_test.go` 中的表/列清单与期望版本号;
5. **同步 GORM 模型**:在 `internal/types/` 对应 struct 增加字段(GORM 只做 ORM 映射,生产库**不使用 AutoMigrate** 建表,schema 完全由 SQL 迁移驱动);
6. **验证**:`make migrate-up` → `make migrate-down` → `make migrate-up` 三连确认可逆;SQLite 侧用 `DB_DRIVER=sqlite` 启动一次 Lite 版验证初始化脚本。
@ -371,6 +413,8 @@ make migrate-up
BM25 索引(`USING bm25`、Lindera 中文分词)只在 ParadeDB 可用;原生 Postgres 部署需保证相应迁移的条件分支生效或改用 Elasticsearch 等外部检索引擎。存量原生 Postgres 库切到 ParadeDB 可参考 `migrations/paradedb/01-migrate-to-paradedb.sql`。
官方镜像自 v0.8.2 起为 `paradedb/paradedb:v0.22.6-pg17`。迁移 000099 只把已安装的 pg_search 0.22.2–0.22.5 升级到 0.22.6:若启动日志提示 `pg_search 0.22.6 is not available`,说明数据库镜像还没换,换镜像后手工执行 `ALTER EXTENSION pg_search UPDATE TO '0.22.6'`;其他版本线不会被自动升级或降级。
### 版本文件冲突 {#_7-5-版本文件冲突}
多个分支同时新增同一个版本号(如两个分支都生成同一数字前缀)会冲突:golang-migrate 按数字排序且版本号唯一。合并时后合入者需要把自己的迁移改成下一个空闲版本号(up/down 两个文件都要改名)。
多个分支同时新增同一个版本号(如两个分支都生成同一数字前缀)会冲突:golang-migrate 按数字排序且版本号唯一,目录里出现重复版本时整个目录无法加载,所有部署都会迁移失败。合并时后合入者需要把自己的迁移改成下一个空闲版本号(up/down 两个文件都要改名)。`internal/database/migration_versions_test.go` 会加载 `versioned/` 与 `sqlite/` 两个目录,CI 中可发现这类冲突(000105 即因此从 000104 重编号)。

View File

@ -1,6 +1,6 @@
# 扩展点指南
WeKnora 的解析器、分块策略、检索引擎、模型 Provider、搜索引擎、数据源、IM 适配器、Agent 工具和存储后端均通过接口接入。新增实现时,先实现对应接口,再在注册入口装配,并验证现有调用链。以下按扩展类型列出接口、已有实现和接入步骤。
WeKnora 的解析器、分块策略、检索引擎、模型厂商、搜索引擎、数据源、IM 适配器、Agent 工具和存储后端均通过接口接入。新增实现时,先实现对应接口,再在注册入口装配,并验证现有调用链。以下按扩展类型列出接口、已有实现和接入步骤。
## 扩展点总览 {#_0-扩展点总览}
@ -12,7 +12,7 @@ graph LR
subgraph APP["app (Go, internal/)"]
P2["分块策略<br/>(infrastructure/chunker)"]
P3["检索引擎<br/>(application/repository/retriever)"]
P4["模型 Provider<br/>(models/provider)"]
P4["模型厂商<br/>(models/providers)"]
P5["联网搜索引擎<br/>(infrastructure/web_search)"]
P6["数据源连接器<br/>(datasource/connector)"]
P7["IM 平台适配器<br/>(im/adapter.go)"]
@ -276,81 +276,103 @@ if slices.Contains(retrieveDriver, "postgres") {
```
仿照上例为新引擎加分支,用 `retriever.NewKVHybridRetrieveEngine(repo, 引擎类型)` 包装后注册;
如需支持知识库间移动文档时复用已有向量,再实现可选接口 `KnowledgeIndexMover`(`MoveKnowledgeIndices`:保留 chunk ID 与向量,只改所属知识库,且可安全重试);未实现时复用向量的移动会被拒绝,只能改用重新解析模式;
4. 若引擎需要独立部署,在 `docker-compose.dev.yml` 加一个带 profile 的服务(参考 `qdrant`/`opensearch`),并在 `.env.example` 补连接变量。
---
## 新增模型 Provider(internal/models/provider) {#_4-新增模型-provider-internal-models-provider}
## 新增模型厂商(internal/models/providers) {#_4-新增模型-provider-internal-models-provider}
模型接入分为协议、厂商、目录、运行时四层(概览见[模型管理](../03-features/06-models.md#分层结构))。大多数新厂商只需新增一份厂商定义并补充模型目录,复用已有协议即可。
### 接口定义
Provider 元数据接口 + 全局注册表在 `internal/models/provider/provider.go`:
厂商定义是一个结构体,而不是接口实现,位于 `internal/models/providers/definition.go`:
```go
// internal/models/provider/provider.go
type ProviderName string // "openai" / "anthropic" / "aliyun" / "zhipu" / "deepseek" / ...
type Provider interface {
// Info 返回服务商的元数据
Info() ProviderInfo
// ValidateConfig 验证服务商的配置
ValidateConfig(config *Config) error
}
// Register 添加一个提供者到全局注册表
func Register(p Provider)
```
`ProviderInfo` 描述展示名、各模型类型(chat/embedding/rerank)的默认 BaseURL、是否需要鉴权、额外配置字段等。Chat 请求的差异化适配(endpoint 拼接、thinking 参数、鉴权头、工具调用元数据)由 `internal/models/chat/provider.go` 的内部适配器接口承担:
```go
// internal/models/chat/provider.go
type providerAdapter interface {
Name() provider.ProviderName
Matches(model string) bool
Thinking() ThinkingStrategy
ShapeRequest(req *openai.ChatCompletionRequest, opts *ChatOptions, isStream bool)
TransformMessages(msgs []openai.ChatCompletionMessage) []openai.ChatCompletionMessage
Endpoint(baseURL, modelID string, isStream bool) string
Auth(req *http.Request, creds authCreds, body []byte)
ForceRawHTTP() bool
ExtractToolCallMetadata(raw json.RawMessage) types.ToolCallMetadata
InjectToolCallMetadata(toolCall map[string]any, metadata types.ToolCallMetadata)
// internal/models/providers/definition.go(节选)
type Definition struct {
ID string // 存入 models.parameters.provider 的稳定标识
Name string
Names map[string]string // 按语言的名称,如 "zh-CN"
Website string
Icon []byte // SVG
API api.API // 默认对话协议
RerankAPI api.RerankAPI // 未声明时默认 cohere-rerank
EmbeddingAPI api.EmbeddingAPI // 未声明时默认 openai-embeddings
TranscriptionAPI api.TranscriptionAPI // 未声明时默认 openai-transcriptions
DefaultBaseURLs map[types.ModelType]string
ModelTypes []types.ModelType
RequiresAuth bool
Auth AuthStyle // bearer / api-key / x-api-key / x-goog-api-key / none / signed
URLPatterns []string // 旧行未填 provider 时按 URL 识别
ExtraFields []ExtraField // 编辑器动态渲染的额外字段
CredentialLabels []CredentialLabel // 重命名凭证输入框(签名类接口)
Compat VendorCompat // 各协议的厂商级兼容默认值
ThinkingLevels api.ThinkingLevelMap
Order int // 厂商列表排序
// 可选钩子
Endpoint func(req EndpointRequest) (url string, query map[string]string)
PreferAPI func(baseURL string, spec models.ModelSpec) api.API
Signer func(creds api.Credentials) api.AuthFunc
}
```
Embedding 与 Rerank 各自有独立接口:
协议层按能力各有一个最小接口,新协议实现它即可接入:
```go
// internal/models/embedding/embedder.go
type Embedder interface {
Embed(ctx context.Context, text string) ([]float32, error)
BatchEmbed(ctx context.Context, texts []string) ([][]float32, error)
GetModelName() string
GetDimensions() int
GetModelID() string
EmbedderPooler
}
// internal/models/rerank/reranker.go
// internal/models/api/rerank.go
type Reranker interface {
Rerank(ctx context.Context, query string, documents []string) ([]RankResult, error)
GetModelName() string
GetModelID() string
Rerank(ctx context.Context, query string, documents []string) ([]RerankResult, error)
}
// internal/models/api/embeddings.go
type Embedder interface {
Embed(ctx context.Context, texts []string, kind EmbedInputType) ([][]float32, error)
}
// internal/models/api/transcriptions.go
type Transcriber interface {
Transcribe(ctx context.Context, req TranscriptionRequest) (*Transcription, error)
}
```
对话协议客户端实现 `internal/models/chat` 的 `Chat` 接口(`Chat` / `ChatStream` / `GetModelName` / `GetModelID`)。
### 现有实现
`internal/models/provider/provider.go` 中已定义 27 个 `ProviderName` 常量:openai、anthropic、aliyun、zhipu、openrouter、litellm、requesty、siliconflow、jina、generic、deepseek、gemini、volcengine、hunyuan、minimax、mimo、gpustack、moonshot、modelscope、qianfan、qiniu、longcat、lkeap、nvidia 等。具体 Provider 实现分布在 `internal/models/provider/` 下的各文件(如 `zhipu.go`、`gemini.go`、`hunyuan.go`、`generic.go`);特殊 embedding 实现如 `internal/models/embedding/jina.go`、`volcengine.go`、`nvidia.go`。
- **厂商**:`internal/models/providers/` 下 27 个文件,一个厂商一份(`aliyun.go`、`deepseek.go`、`generic.go`、`weknoracloud.go` 等),由 `builtin.go` 的 `Builtins()` 显式列出;图标在 `providers/assets/<id>.svg`。
- **协议**:`internal/models/api/<protocol>`。对话 `openaicompletions`、`openairesponses`、`anthropicmessages`、`googlegenai`;向量 `openaiembeddings`、`dashscopeembeddings`、`arkembeddings`、`googleembeddings`;重排 `cohererank`、`dashscoperank`、`nimrerank`、`tencentlkeap`、`volcengineknowledge`;语音 `openaitranscriptions`、`openaichataudio`。
- **模型目录**:`internal/models/catalog/data/seed.json`(模型元数据)+ `overrides.json`(协议、思考映射与 compat 修正)→ 由脚本生成 `models.generated.json`,编译时嵌入。
- **运行时**:`internal/models/runtime` 组合厂商定义与目录(`New()`),应用部署叠加 `config/models.json`,并为每个模型行解析出协议、端点和兼容设置。
### 新增步骤
1. **注册点一:`internal/models/provider/provider.go`** — 增加 `ProviderName` 常量;
2. 在 `internal/models/provider/` 新建 `myprovider.go`,实现 `Provider` 接口(`Info()` 给出默认 URL/支持的模型类型),并通过 `provider.Register(...)`(通常在 `init()` 或集中初始化处)挂入全局注册表——OpenAI 兼容协议的服务商到这一步即可用,chat 侧默认走通用 OpenAI 适配;
3. **注册点二(可选):`internal/models/chat/provider.go`** — 若 API 协议有差异(非标 endpoint、特殊鉴权、thinking 字段),实现并注册一个 `providerAdapter`;
4. **注册点三(可选)**:需要专有 Embedding/Rerank 协议时,在 `internal/models/embedding/`、`internal/models/rerank/` 各加实现并接入其构造工厂;
5. 如需开箱即用的内置模型,补充 `config/builtin_models.yaml` 声明(启动时会同步进 `models` 表)。
1. **新建厂商定义**:`internal/models/providers/<id>.go`,声明名称、支持的模型类型、各类型默认地址、鉴权方式、协议默认值及特殊端点钩子,并在包注释中写明官方文档依据;
2. **注册点一:`internal/models/providers/builtin.go`** — 把 `new<Id>Provider()` 加进 `Builtins()`;图标放入 `providers/assets/<id>.svg`;
3. **注册点二:模型目录** — 在 `internal/models/catalog/data/seed.json` 中为该厂商加一个条目(即使暂时没有模型也要有空列表,运行时按厂商 ID 读取目录),维护模型元数据;协议、思考映射与 compat 修正写在 `overrides.json`。模型键包含类型与 id / match,同名的对话和向量模型可以共存;
4. **生成目录**:执行 `make model-catalog-generate`。生成文件不要手改;
5. **新协议(可选)**:已有协议能覆盖时直接复用;确需新协议时新增 `internal/models/api/<protocol>` 包,并在对应工厂的协议分支中接入(对话 `internal/models/chat/chat.go` 的 `NewRemoteChat`、向量 `internal/models/embedding/protocol.go`、重排 `internal/models/rerank/reranker.go`、语音 `internal/models/asr/protocol.go`);
6. **校验**:运行 `make model-catalog-check`。
`make model-catalog-check` 先检查生成数据是否过期,再运行 `internal/models/...` 的全部测试:`providers` 的注册与图标检查;`runtime` 的解析与叠加;`parity` 包的**不变量**(每个模型条目的字段合法性、compat 键名可解码、上下文与最大输出自洽)和**逐模型出站请求检查**(每个对话模型在思考开 / 关两种情况下只能出现一个输出上限字段;不支持采样参数的模型不得带 temperature;始终思考的模型不得收到关闭开关等)。新厂商和新模型违反这些规则时测试直接失败,无需单独写用例。
前端不需要改动:厂商下拉、图标、额外字段、模型目录都由 `GET /api/v1/models/providers` 动态渲染。开箱即用的内置模型行由运维在 `config/builtin_models.yaml` 中声明,与厂商定义无关。
### 维护已有厂商
**新增或调整模型元数据**(新模型 id、上下文窗口、价格):先生成差异报告,再对照厂商文档更新 `seed.json`,最后重新生成目录。
```bash
make model-catalog-diff # 全部厂商
make model-catalog-diff VENDOR=deepseek # 只看一家
```
报告对比 [models.dev](https://models.dev/api.json) 的公开元数据:`+` 是上游有而目录没有的模型,`~` 是数值差异,`?` 是上游没收录的条目(国内厂商和别名经常如此,不代表错)。脚本只读不写,也从不在运行时调用。字段名、思考格式这类行为事实不会被自动同步,必须以厂商文档为准手工维护。
**厂商改了接口行为**(换了输出上限字段、新增 effort 取值、思考开关格式变化):改 `providers/<id>.go` 的 `Compat`,或 `overrides.json` 中对应模型的 `compat`,重新生成目录,并同步更新注释里的文档链接。`internal/models/api/openaicompletions/golden_test.go` 等快照测试会钉死出站 JSON,改动需先改测试预期。
**紧急修正**:不必等发版,可先用[部署叠加 `config/models.json`](../03-features/06-models.md#部署叠加-config-models-json)在部署侧修改,验证后再补回代码。
---
@ -383,9 +405,11 @@ func (r *Registry) Register(id string, factory ProviderFactory)
func (r *Registry) CreateProvider(providerType string, params types.WebSearchProviderParameters) (interfaces.WebSearchProvider, error)
```
支持按地区、时效过滤的引擎可额外实现可选接口 `FilteredWebSearchProvider`(`SearchWithFilters`);不支持过滤的引擎不得静默丢弃调用方请求的过滤条件。
### 现有实现
`internal/infrastructure/web_search/` 目录:`duckduckgo.go`、`google.go`、`bing.go`、`tavily.go`、`ollama.go`、`baidu.go`、`searxng.go`、`keenable.go`、`zhipu.go`(另有 `proxy.go` 出站代理支持)。类型常量在 `internal/types/web_search_provider.go`(`WebSearchProviderTypeBing/Google/DuckDuckGo/Tavily/Ollama/Baidu/Searxng/Keenable/Zhipu`)。
`internal/infrastructure/web_search/` 目录:`duckduckgo.go`、`google.go`、`bing.go`、`brave.go`、`tavily.go`、`ollama.go`、`baidu.go`、`searxng.go`、`keenable.go`、`zhipu.go`、`exa.go`、`metaso.go`、`bocha.go`、`serply.go`(另有 `proxy.go` 出站代理支持)。类型常量在 `internal/types/web_search_provider.go`(`WebSearchProviderTypeXxx`,与注册 ID 一一对应)。
### 新增步骤
@ -455,16 +479,25 @@ type StreamingConnector interface {
}
```
另有两个可选接口用于全量同步时仍能对账删除:`FullStreamingConnector`(`FetchFullStream`)与 `FullSyncWithCursor`(`FetchAllFromCursor`),在强制全量或 `sync_mode=full` 时重新拉取全部条目,同时保留上一次游标用于识别已删除的文档。未实现时,全量同步无法产生删除事件。
注册表同文件:`ConnectorRegistry`(`NewConnectorRegistry()` / `Register(connector)` / `Get(type)` / `List()`);连接器的 UI 元数据(名称、AuthType、capabilities)在同文件的 `ConnectorMetadataRegistry` map 中。
### 现有实现
| 类型 | 目录 | 说明 |
| --- | --- | --- |
| `feishu` / `lark` | `internal/datasource/connector/feishu/` | 同一实现,`NewConnector(RegionFeishu / RegionLark)` 区分区域 |
| `feishu` / `lark` | `internal/datasource/connector/feishu/wiki/` | 飞书 / Lark 知识库,同一实现按区域区分 |
| `feishu_drive` / `lark_drive` | `internal/datasource/connector/feishu/drive/` | 飞书 / Lark 云盘 |
| `notion` | `internal/datasource/connector/notion/` | 页面与数据库 |
| `confluence` | `internal/datasource/connector/confluence/` | Confluence |
| `yuque` | `internal/datasource/connector/yuque/` | 语雀 |
| `dingtalk` | `internal/datasource/connector/dingtalk/` | 钉钉文档 |
| `ima` | `internal/datasource/connector/ima/` | 腾讯 ima 知识库 |
| `rss` | `internal/datasource/connector/rss/` | RSS 订阅 |
| `gitlab` | `internal/datasource/connector/gitlab/` | GitLab 仓库 |
`internal/types/datasource.go` 中还有 `github`、`google_drive` 等尚未注册实现的类型常量。
### 新增步骤
@ -478,7 +511,8 @@ if err := registry.Register(mysourceConnector.NewConnector()); err != nil {
```
3. **注册点二:`internal/datasource/connector.go` 的 `ConnectorMetadataRegistry`** — 增加类型常量(`internal/types` 的 `ConnectorTypeXxx`)与元数据条目(Name/Description/AuthType/Capabilities);
4. 同步配置结构:`types.DataSourceConfig` 若需新增凭证字段,注意加密存储约定;前端数据源接入页按元数据渲染。
4. 同步配置结构:`types.DataSourceConfig` 若需新增凭证字段,注意加密存储约定;前端数据源接入页按元数据渲染;
5. 复用 `internal/datasource` 的公共工具:用户可填写的 API 地址先经 `ValidateConnectorBaseURL` 做 SSRF 校验,HTTP 请求使用 `NewConnectorHTTPClient`(带重定向与拨号期 SSRF 防护),生成文件名使用 `SanitizeFileName`。
---
@ -604,9 +638,9 @@ func (r *ToolRegistry) ListTools() []string
### 现有实现
工具名常量集中在 `internal/agent/tools/definitions.go`:`thinking`、`todo_write`、知识检索工具(`search_knowledge`、`read_document`、`list_documents`、`query_knowledge_graph`)、`database_query`、`data_analysis`、`data_schema`、`web_search`、`web_fetch`、沙箱/技能工具(`shell_exec`、`read_file`、`list_sandbox_files`、`write_sandbox_file`、`edit_sandbox_file`),记忆工具(`search_memory`、`search_conversations`)、wiki 工具(`wiki_read_page`、`wiki_write_page`、`wiki_replace_text`、`wiki_rename_page`、`wiki_delete_page`、`wiki_search`、`wiki_flag_issue`、`wiki_read_issue`、`wiki_update_issue`)。实现文件与工具同名(如 `search_knowledge.go`、`read_document.go`、`list_documents.go`、`data_analysis.go`、`mcp_tool.go`——后者把 MCP 服务的远程工具包装成 `types.Tool`)。
工具名常量集中在 `internal/agent/tools/definitions.go`:`thinking`、`todo_write`、知识检索工具(`search_knowledge`、`read_document`、`list_documents`、`query_knowledge_graph`)、`database_query`、`data_analysis`、`data_schema`、`web_search`、`web_fetch`、MCP 按需调用工具(`discover_mcp_tools`、`call_mcp_tool`)、沙箱/技能工具(`shell_exec`、`read_file`、`list_sandbox_files`、`write_sandbox_file`、`edit_sandbox_file`、`write_skill_file`、`edit_skill_file`),记忆工具(`search_memory`、`search_conversations`)、wiki 工具(`wiki_read_page`、`wiki_write_page`、`wiki_replace_text`、`wiki_rename_page`、`wiki_delete_page`、`wiki_search`、`wiki_flag_issue`、`wiki_read_issue`、`wiki_update_issue`);本机浏览器工具 `local_browser` 实现在 `browserskill*.go`。实现文件多与工具同名(如 `search_knowledge.go`、`read_document.go`、`list_documents.go`、`data_analysis.go`;`mcp_tool.go` / `mcp_catalog.go` 负责把 MCP 服务的远程工具按需发现与调用)。
已退役的检索工具名(`knowledge_search`、`grep_chunks`、`list_knowledge_chunks`、`get_document_info`、`wiki_read_source_doc`)仍以 `LegacyTool*` 常量保留:`legacyToolSuccessors` 把它们映射到 `search_knowledge` / `read_document`,`NormalizeAllowedTools` 在注册工具时自动改写已保存 Agent 配置里的旧名字,`SuccessorToolName` / `IsLegacyRetrievalTool` 供其他服务判定。重命名或合并工具时请沿用这一机制,而不是做数据迁移。
已退役的沙箱工具名(`execute_skill_script`、`read_skill`、`read_sandbox_file`)仅为解码历史记录保留,不再注册;已退役的检索工具名(`knowledge_search`、`grep_chunks`、`list_knowledge_chunks`、`get_document_info`、`wiki_read_source_doc`)仍以 `LegacyTool*` 常量保留:`legacyToolSuccessors` 把它们映射到 `search_knowledge` / `read_document`,`NormalizeAllowedTools` 在注册工具时自动改写已保存 Agent 配置里的旧名字,`SuccessorToolName` / `IsLegacyRetrievalTool` 供其他服务判定。重命名或合并工具时请沿用这一机制,而不是做数据迁移。
### 新增步骤
@ -698,7 +732,7 @@ default:
| 文档解析器 | `BaseParser.parse_into_text` | `docreader/parser/base_parser.py` | `docreader/parser/registry.py` `_build_default_registry()` |
| 分块策略 | tier 函数 `func(text, cfg, profile) []Chunk` | `internal/infrastructure/chunker/strategy.go` | 同文件 `runTier()` + 策略常量 |
| 检索引擎 | `RetrieveEngineRepository` | `internal/types/interfaces/retriever.go` | `container.go` `initRetrieveEngineRegistry()`(`RETRIEVE_DRIVER` 门控) |
| 模型 Provider | `Provider` / `providerAdapter` / `Embedder` / `Reranker` | `internal/models/provider/provider.go` 等 | `provider.Register()` + `internal/models/chat/provider.go` |
| 模型厂商 | `providers.Definition`(+ 协议层 `Reranker` / `Embedder` / `Transcriber`、`chat.Chat`) | `internal/models/providers/definition.go` | `internal/models/providers/builtin.go` `Builtins()` + `internal/models/catalog/data/seed.json` |
| 联网搜索 | `WebSearchProvider` | `internal/types/interfaces/web_search.go` | `container.go` `registerWebSearchProviders()` |
| 数据源连接器 | `Connector` / `StreamingConnector` | `internal/datasource/connector.go` | `container.go` `initConnectorRegistry()` + `ConnectorMetadataRegistry` |
| IM 适配器 | `Adapter`(+`StreamSender`/`FileDownloader`) | `internal/im/adapter.go` | `container.go` `registerIMAdapterFactories()` |

View File

@ -4,7 +4,7 @@
## 后端与模板
空间命名配置可选择 Docker、CubeSandbox、E2B,本文说明这三类后端的部署。桌面客户端另有依赖操作系统隔离能力的 `host` 后端,不属于服务端命名配置;旧 `local` 宿主机进程后端已移除。Docker 直接使用 Engine API;E2B 使用控制面 REST 与 envd 数据面;Cube 保留专用适配器处理模板和网络策略。
空间命名配置可选择 Docker、CubeSandbox、E2B,本文说明这三类后端的部署。Lite 桌面客户端另有依赖操作系统隔离能力的 `host` 后端,不属于服务端命名配置,构建要求见下文 [Lite 本机沙箱](#lite-本机沙箱);旧 `local` 宿主机进程后端已移除。Docker 直接使用 Engine API;E2B 使用控制面 REST 与 envd 数据面;Cube 保留专用适配器处理模板和网络策略。
标准镜像由 `docker/Dockerfile.sandbox` 定义,包含 Python 3.12、Node.js 20、Bash、jq 与 `/workspace`。命令和文件操作默认使用沙箱内 root;保留 UID 1000 的 `user` 供显式按账号执行。跨会话隔离由容器或远端沙箱提供,不能把工作目录约定解释为 root 的文件权限限制。
@ -67,7 +67,20 @@ Cube guest DNS 属于模板配置。更改 DNS/镜像后需重建模板才会进
| 安装依赖失败 | 默认拒绝出站时是否放行软件源;技能安装与会话使用同一网络策略 |
| 重连后状态丢失 | Redis 是否共享、TTL 是否到期、技能更新是否触发重建 |
## 图形桌面
## 交互终端与图形桌面
对话侧栏的终端和桌面都通过 WebSocket 连接会话沙箱,仅 Cube/E2B 支持,Docker 后端不提供。浏览器不能在 WebSocket 握手里携带认证头,因此都先用已登录的 POST 换取两分钟有效的短期票据,再把票据放在握手 query 中:
| 能力 | 取票据 | WebSocket |
| --- | --- | --- |
| 终端 | `POST /api/v1/sessions/:session_id/sandbox/terminal-ticket` | `GET /api/v1/sessions/:id/sandbox/terminal?ticket=...` |
| 桌面 | `POST /api/v1/sessions/:session_id/sandbox/desktop-ticket` | `GET /api/v1/sessions/:id/sandbox/desktop?ticket=...` |
入口代理必须为这两个路径转发 WebSocket Upgrade、放宽读超时,并避免在访问日志中记录 ticket query。标准 frontend Nginx 已为 `^/api/v1/sessions/[^/]+/sandbox/(terminal|desktop)$` 配置不含 query 的日志格式;自定义 Ingress 需自行处理。终端连上后,服务端大约每分钟复核一次登录状态、空间成员和会话归属,退出登录或被移出空间会断开终端。接口参数见[终端 API](../04-api/02-api-sandbox-skills.md#会话交互终端)与[桌面 API](../04-api/02-api-chat.md#sandbox-desktop)。
终端和桌面在无操作时按配置的 `terminal_idle_disconnect_sec` 断开(默认 900 秒,最短 60 秒,最长 24 小时),之后沙箱按提供商 TTL 暂停。终端以键盘输入和 PTY 输出计活动,桌面以键鼠计活动。
### 图形桌面
仅 Cube/E2B 桌面模板支持对话侧栏桌面。首次打开时由后端启动桌面进程;配置需选择桌面模板并设置 `desktop_enabled`。技能已安装后不能原地切换底模。
@ -75,12 +88,22 @@ Cube guest DNS 属于模板配置。更改 DNS/镜像后需重建模板才会进
浏览器 noVNC → WeKnora 票据中继 → 提供商网关 → websockify :6080 → 本机 x11vnc :5900
```
浏览器不持有沙箱 API Key、入站 token 或 websockify 密码。先通过已登录的 `POST /sessions/:session_id/sandbox/desktop-ticket` 获取两分钟有效的一次性票据,再连接桌面 WebSocket;票据仅可消费一次。接口前缀为 `/api/v1`,完整定义见[会话 API](../04-api/02-api-chat.md)。
代理需要支持 WebSocket,并避免在访问日志中记录票据 query。标准 frontend Nginx 已为桌面路径配置不含 query 的日志格式。Cube 桌面模板的 `exposedPorts` 只暴露 envd 的 49983,**不要把 6080 加入宿主机 NAT**,桌面必须经过网关与 WeKnora 中继。
浏览器不持有沙箱 API Key、入站 token 或 websockify 密码。桌面票据仅可消费一次,完整定义见[会话 API](../04-api/02-api-chat.md#sandbox-desktop)。Cube 桌面模板的 `exposedPorts` 只暴露 envd 的 49983,**不要把 6080 加入宿主机 NAT**,桌面必须经过网关与 WeKnora 中继。
每个会话同时只允许一条桌面中继,多副本槽位由 Redis 协调。沙箱重建后以 `SANDBOX_REBUILT` 提醒断开,不能把新桌面当成保留了原临时文件的旧实例。空闲判断使用 RFB 键鼠活动,截图请求不算用户操作。
## Lite 本机沙箱
`host` 后端只编译进带 `desktop` 构建标签的 Lite 桌面程序(`cmd/desktop/wails.json` 的 `build:tags`),服务端和单二进制 Lite 不包含。它在未选沙箱配置的会话中运行命令,用法见[技能目录与沙箱](../03-features/22-skills-sandbox.md#lite-host)。
| 平台 | 状态 |
| --- | --- |
| macOS | 使用系统 `sandbox-exec`(Seatbelt)执行每条命令;启动时检测不可用则不启用 |
| Windows | 尚未实现,报告不可用,不会退化为无隔离执行 |
| Linux | 不支持 |
每条命令都是新的本机进程,没有会话级实例,因此不写入会话的沙箱绑定,也不做工作区检查点。用户通过系统目录选择框批准的项目目录保存在 `desktop-prefs.json` 的 `project_dirs`;会话只能绑定列表中的目录本身,不能绑定其子目录或手工输入的路径。`approval_mode` 当前只支持 `auto`(在工作区内自由读写、禁止联网),写入其他值会被拒绝。偏好文件位置见[桌面客户端](../05-clients/05-desktop.md#_5-偏好设置存储-cmd-desktop-prefs-go)。
## 开发验证
单元测试不需要真实 daemon:

View File

@ -9,8 +9,8 @@
| 段名 | 来源与职责 |
| --- | --- |
| `base` | 显式正文优先;否则无绑定知识库用 `pure` 默认模板,有知识库用 `rag` 默认模板 |
| `steering` | 处理中途补充与取消,保留未完成任务 |
| `runtime_contract` | 数据与指令边界、当前文档范围、完成条件 |
| `steering` | 如何处理回答过程中用户追加的消息(补充、修改或取消),保留未完成任务;自定义正文同样带上 |
| `runtime_contract` | 数据与指令边界、当前文档范围、完成条件;已知用户语言时追加默认回答语言 |
| `sources` | 根据实际注册的工具集合选择来源规则;技能安装模式使用专门的安装验证说明 |
| `tools` | 通用执行、文件和沙箱约定;具体参数仍在工具定义中 |
| `output` | 公共输出格式、配图条件和完成检查 |
@ -36,6 +36,8 @@
`@MCP` / `@Skill` 产生当前轮的 `must_use` 提示。MCP 提及只为已授权服务设置优先提示,不移除其他已配置服务;尚未暴露的服务通过 `discover_mcp_tools` 发现。技能提及提示先读取对应 `SKILL.md`。这些选择不能授权无关操作,仍受用户明确的来源限制和后端权限约束。
回答过程中用户追加并选择立即补充的消息,在下一轮迭代前作为 user 消息接到消息列表末尾:发给模型的内容以 `<steer_message>` 包裹并附 `<continue_task>` 说明(`types.SteerMessageContent`),会话历史和界面保留用户原文;`steering` 段约定模型如何对待这类消息。
正常工具结果保留 `tool` 角色与调用 ID;消息修复时无法配对的结果以转义后的 `untrusted_tool_result` 数据块保留,不能提升为系统指令。Agent、普通问答和模型兜底共用来源数据边界规则,但三者并不使用完全相同的提示词拼装流程。
达到迭代上限或错误收尾时,`internal/agent/finalize.go` 沿用当前消息列表,保留历史、图片及工具调用配对,再追加收尾请求。最后一次调用不提供工具,设置 `tool_choice=none` 并关闭 thinking。

View File

@ -0,0 +1,99 @@
# v0.8.0 版本说明
发布日期:2026-09-03
v0.8.0 的主题是让智能体能够真正动手完成任务:技能成为空间内统一管理的资源,在会话级沙箱中执行脚本、处理文件并生成交付物;新增跨会话的长期记忆,让智能体记住你确认过的偏好和信息。此外,Office 文档可以在应用内直接解析,并新增 GitLab、腾讯 IMA 数据源、LiteLLM 模型接入和 DeepSeek Harness 插件。
从 v0.7.x 升级前,请先阅读[升级须知](#upgrade-notes)。完整的变更列表见 [CHANGELOG](https://github.com/Tencent/WeKnora/blob/main/CHANGELOG.md)。
## 技能沙箱 {#skill-sandbox}
智能体的技能在会话级沙箱中运行:每个对话有一个独立的沙箱,多轮任务共用同一个工作区。执行命令、读写和编辑文件、处理上传的附件、收集生成的文件,都在这个工作区里完成。
<Screenshot
src="/screenshots/skill-sandbox-chat.png"
caption="智能体根据知识库生成 Word 文档,并在对话旁预览生成的文件" />
- **三种后端**:Docker(单机或自建)、E2B(云端或兼容 E2B 的自建控制面)、CubeSandbox,使用同一套远程协议。
- **按空间配置**:镜像、CPU / 内存、存活时间、DNS、模板和快照都可以按空间配置;管理员还可以为每个配置设置网络策略,例如默认禁止出站、允许 / 拒绝列表。
- **Docker 后端默认关闭**:挂载 `docker.sock` 等同于宿主机 root 权限,需要在「系统设置 → 网络安全」中开启,或设置 `WEKNORA_SANDBOX_DOCKER_ENABLED=true`。
- **生成文件**:沙箱中生成的文件汇总到每条消息的产物抽屉,可以预览和下载,有新文件时会有提示。
- **长任务压缩**:沙箱中的长时间任务会压缩工具调用历史,而不是截断或改写文件;稳定的提示词前缀加上缓存标记,可以提高 Anthropic 和 OpenAI 兼容接口的缓存命中率。每轮对话的 token 用量也会记录下来。
详见[技能目录与沙箱](../03-features/22-skills-sandbox.md)与[沙箱部署与排障](../06-development/04-sandbox-deployment.md)。
## 空间技能目录 {#skill-catalog}
技能成为空间内的一等资源,不再是放在服务进程旁边的文件。
<Screenshot
src="/screenshots/skill-catalog.png"
caption="空间技能目录:各技能及其安装到的沙箱" />
- **多种安装来源**:ClawHub、SkillHub / skills.sh、GitHub / GitLab 链接,或上传 ZIP。
- **按沙箱安装**:每次安装都会在所选沙箱配置上生成一个快照,实时显示安装进度和安装记录,可以中途停止、重新安装;从沙箱卸载时保留目录中的安装包。
- **在线查看与编辑**:可以在设置中浏览和编辑已安装技能的文件;智能体也可以通过 `write_skill_file`、`edit_skill_file` 修改技能文件,`shell_exec` 不再要求必须先安装技能。
- **环境变量**:个人和空间级的技能环境变量在执行时注入,保存后不会再被读出。
- 用 `@` 提及技能时,不再意外缩小智能体可用的技能范围。
## 跨会话长期记忆 {#memory}
新的长期记忆能力,与 v0.7.1 移除的基于 Neo4j 的对话记忆相互独立。
- **按需开启**:空间开启后,每个用户还可以自行关闭。
- **分类记忆**:记忆分为资料、偏好、事实、事项、兴趣五类,可以显式写入,也可以由后台自动提取。
- **由你确认**:自动推断出的记忆在你确认之前处于待确认状态,不会直接生效。
- **使用方式**:资料和偏好在每轮对话中都会带上;情境类事实按关键词召回,也可以开启语义召回;智能体可以用 `search_memory` 按需查询。经常引用的文档会在检索时获得更高的权重。
- 设置、条目、主题、文档关联、确认 / 拒绝、导出和强制整理都通过 `/api/v1/memory/*` 提供,仅限完整权限的 API Key,操作对象始终是调用者本人。
详见[长期记忆](../03-features/23-memory.md)与[长期记忆 API](../04-api/02-api-memory.md)。
## 文档解析与数据源 {#parsing-and-sources}
- **应用内 anydoc 解析**:doc、docx、ppt、pptx 等 anydoc 能转换的 Office 文档可以直接在 Go 应用内解析,不再绕道 docreader。应用镜像默认链接 anydoc。
- **XMind 大纲解析**:`.xmind` 文件会解析成大纲,与其他文档一样建立索引。
- **文档自动打标签**:解析完成后,对话模型可以从知识库已有的标签中挑选合适的标签,增量添加,不会新建标签,也不会覆盖手动添加的标签。
- **GitLab 与腾讯 IMA 数据源**:GitLab 项目可以作为知识来源同步;腾讯 IMA 笔记通过笔记 OpenAPI 同步,遇到临时错误会自动重试。
- **解析质量**:DOCX 的纵向合并单元格和表格文本得以保留;PDF 内嵌图片不再出现全黑;网页抓取失败时直接报错,不会把错误页面收进知识库。
详见[文档解析](../03-features/03-document-parsing.md)与[数据源导入](../03-features/10-datasource.md)。
## 模型、搜索与生态 {#ecosystem}
- **LiteLLM**:作为一等厂商接入对话、向量和重排模型,一个网关地址即可转发到多个上游模型。
- **Exa 与秘塔搜索**:新增两个联网搜索服务商。
- **DeepSeek Harness 插件**:官方 npm 包 [`@wxg-prc-cpg/dsh-weknora`](https://www.npmjs.com/package/@wxg-prc-cpg/dsh-weknora) 提供 `weknora_search`、`weknora_read_document`、`weknora_ask`、`weknora_list_knowledge_bases` 四个只读工具,让 DeepSeek Harness 编码智能体可以检索 WeKnora 中的知识。详见 [DeepSeek Harness](../05-clients/08-deepseek-harness.md)。
## 对话体验 {#chat}
- 较长的对话会显示问题目录,方便快速定位;消息之间按时间显示分隔。
- `shell_exec` 以「命令 + 输出」卡片的形式展示;工具卡片上会显示沙箱文件列表和技能名称。
- 流式输出过程中,Mermaid 图表保持渲染状态,不再反复闪烁。
## 账号与安全 {#security}
- **OIDC 签名校验**:ID Token 通过 JWKS 校验签名;新增 `/auth/oidc/start`,可以直接跳转登录。
- **可选的复杂密码**:开启后,注册、修改密码和管理员重置密码都要求包含大小写字母、数字和特殊字符(`WEKNORA_AUTH_COMPLEX_PASSWORD_ENABLED` 或系统设置)。
- **管理员创建用户**:平台管理员可以在控制台直接创建用户,不再需要邀请链接。
- **邀请流程**:邀请已注册的用户时可以自动接受;仅邀请模式下,分享链接会先引导访客登录再加入空间。
- **沙箱安全**:Docker 沙箱中的所有执行都以沙箱用户(uid 1000)运行,关闭了可能逃出工作区的符号链接操作,并会回收被取消执行留下的僵尸进程。
## 升级须知 {#upgrade-notes}
| 变化 | 需要做什么 |
| --- | --- |
| 移除了宿主机进程(Local)沙箱后端 | 原有的 Local 沙箱配置需要改用 Docker(需手动开启)、E2B 或 Cube 重新创建 |
| Docker 沙箱后端默认关闭 | 在「系统设置 → 网络安全」中开启,或设置 `WEKNORA_SANDBOX_DOCKER_ENABLED=true` |
| 开启复杂密码后,不符合规则的注册、修改密码请求会被拒绝 | 开启前通知用户新的密码要求 |
数据库迁移:PostgreSQL 为 `000080`–`000090`,SQLite 为 `000003`–`000012`。Docker 沙箱后端要求 app 容器中的 `appuser` 属于 `docker.sock` 所在的用户组。
## 其他改进与修复 {#other-changes}
- **检索**:MMR 选择改为增量计算;混合检索遵循 `resource_urls=public`;`MatchCount=0` 不再截断全部结果;已删除的图片不会再被检索到。
- **IM**:飞书长连接支持反向代理,流式卡片在全量输出模式下会显示进度;企业微信、钉钉、云之家的若干兼容性改进;IM 问答支持文件附件。
- **空间与文档**:切换空间时会记住上次使用的空间;支持在个人设置中修改密码;按目录拖拽上传会保留目录结构;文档摘要可编辑,分块列表分页显示。
- **部署能力**:未注册的模块会在菜单和设置中隐藏(`GET /system/capabilities`),Lite 等精简版本不再显示缺失的功能。
- **问题修复**:高风险系统设置读取最新保存的值;飞书流式卡片不再卡在进行中;被引用的模型删除时会显示引用详情;共享知识库在智能体上下文中的文档数不再为 0;内置智能体的名称和描述跟随界面语言。
完整列表见 [CHANGELOG](https://github.com/Tencent/WeKnora/blob/main/CHANGELOG.md)。

View File

@ -0,0 +1,163 @@
# v0.8.2 版本说明
发布日期:2026-09-23
v0.8.2 让智能体走出对话框:它可以操作你电脑上的浏览器;知识库可以作为 MCP Server 发布给 Claude、Cursor 等其他 AI 工具;对话过程也更可控,可以中途补充要求、分叉或回滚。沙箱新增交互终端和图形桌面,模型接入改为按厂商目录自动配置,另有 Confluence、钉钉文档数据源和日语界面等更新。
从 v0.8.0 升级前,请先阅读[升级须知](#upgrade-notes)。完整的变更列表见 [CHANGELOG](https://github.com/Tencent/WeKnora/blob/main/CHANGELOG.md)。
## 本机浏览器 {#local-browser}
智能推理对话可以直接操作你电脑上的 Chrome 或 Edge。浏览器通过腾讯开源的 [BrowserSkill](https://github.com/Tencent/BrowserSkill) 扩展连接到 WeKnora,智能体在独立的任务窗口中打开网页、点击、填写表单、读取内容,再把结果汇报到对话里。
<Screenshot
src="/screenshots/local-browser-task.png"
caption="智能体查询 GitHub 最新 Release 后填写订单表单,对话右下角是任务预览" />
- **对话中可控**:任务预览显示在对话里,可以随时暂停、继续或结束,也可以跳到浏览器查看对应页面。
- **需要人时交给人**:遇到登录、验证码或需要授权的步骤,智能体会发起人工协助;你在浏览器里处理完,它再接着执行。
- **一次配对,多处可用**:在「工具箱 → 浏览器连接」复制配对链接,粘贴到扩展里即可。同一空间内的多个对话共用这台浏览器的授权,开启输入框的「本机浏览器」开关后才会使用。
<Screenshot
src="/screenshots/browser-connection.png"
caption="工具箱 → 浏览器连接:扩展版本、连接状态与智能体可执行的网页操作" />
Docker 部署的 app 镜像已内置 BrowserSkill 服务和配套扩展,通常无需额外配置;多副本部署需要配置节点互通地址和共享密钥。详见[本机浏览器](../05-clients/09-local-browser.md)。
## 内置 MCP Server {#mcp-server}
每个空间都可以把知识库发布为 MCP 服务,供 Claude Desktop、Cursor、Claude Code、VS Code 等支持 MCP 的客户端直接检索和提问,无需再单独部署 MCP 进程。
<Screenshot
src="/screenshots/mcp-server-endpoint.png"
caption="设置 → 发布集成 → MCP Server:端点地址与客户端配置" />
- 在「设置 → 发布集成 → MCP Server」新建端点,选择可访问的知识库和要开放的工具。
- 工具分四组:检索与阅读、问答(运行端点指定的智能体)、Wiki、写入;写入工具默认关闭。
- 每个端点有独立的令牌和调用频率上限(默认每分钟 60 次),令牌可以随时轮换。
- 页面直接给出 Cursor、VS Code、Claude Desktop 的配置片段和 Claude Code 的一行命令。
原来仓库中的 Python 版 `mcp-server/` 已标记为弃用。详见 [MCP 集成](../03-features/08-mcp.md#供外部客户端调用)。
## 对话控制 {#conversation-control}
<Screenshot
src="/screenshots/chat-steer-queue.png"
caption="回答进行中,输入框上方排队等待的补充要求" />
- **中途补充要求**:智能体还在执行时就可以继续输入。按 Enter 排队,当前步骤结束后处理;按 ⌘Enter / Alt+Enter 立即插入当前任务。
- **分叉与回滚**:可以从任意一次历史提问分叉出新对话,也可以原地回滚到某次提问;使用沙箱的对话会同时恢复对应时刻的工作区。
- **思考强度**:每个对话可以单独选择模型的思考强度。
- **截断提示**:回答因达到输出上限被截断时会明确标出,不再悄悄截断。
<Screenshot
src="/screenshots/artifacts-library.png"
caption="侧栏「产物」页:跨对话汇总智能体生成的文件" />
智能体生成的文件统一收在侧栏的「产物」页,可以按类型筛选、搜索、查看历史版本,也可以删除不需要的文件。把回答存入知识库时,编辑器改为分屏的 Markdown 源码与预览,并支持暂存草稿。
<Screenshot
src="/screenshots/chat-save-answer-editor.png"
caption="把回答添加到知识库:分屏编辑与预览" />
详见[会话体验](../03-features/18-chat-experience.md)。
## 沙箱:图形桌面、交互终端与本机沙箱 {#sandbox}
对话右侧的「沙箱可视化」面板新增「桌面」和「终端」两个页签,可以直接进入智能体正在使用的同一个沙箱。
<Screenshot
src="/screenshots/sandbox-desktop.png"
caption="图形桌面:通过浏览器操作沙箱内的桌面环境" />
<Screenshot
src="/screenshots/sandbox-panel-terminal.png"
caption="交互终端:查看工作区文件与命令结果" />
- **图形桌面**:需要 Cube 或 E2B 的桌面模板,并在沙箱配置中开启桌面。
- **交互终端**:Cube 和 E2B 沙箱可用,刷新页面后可以重新接上仍在运行的终端。
- 打开面板不会创建或唤醒沙箱;长时间无操作会自动断开,默认 900 秒。
- 智能体执行命令、安装技能时,工具卡片会实时显示输出。
**Lite 桌面版本机沙箱(macOS)**:没有选择远程沙箱的对话,会在系统沙箱中执行命令。新对话可以绑定电脑上的一个项目文件夹,智能体只能写入这个文件夹;命令不能联网,`.git` 目录只读,凭据目录始终不可访问。
**工具箱**:技能、MCP 服务和浏览器连接从「设置」移到侧栏的「工具箱」,旧的设置入口会自动跳转。
<Screenshot
src="/screenshots/toolbox.png"
caption="侧栏工具箱:技能管理、MCP 服务与浏览器连接" />
详见[技能目录与沙箱](../03-features/22-skills-sandbox.md)。
## 模型接入 {#models}
模型接入改为按「协议、厂商、模型目录」三层组织,内置 27 个厂商。添加模型时:
- 从厂商目录中选择模型后,会自动填入上下文窗口、最大输出、思考强度和视觉能力。
- 「实际调用方式」面板直接显示这个模型将使用的请求协议、请求地址和可选的思考强度。
- 个别接口与默认值不一致时,可以在高级选项中覆盖协议,或填写协议兼容 JSON。
- 语音识别覆盖所有在文档中提供该能力的厂商。
<Screenshot
src="/screenshots/model-editor-catalog.png"
caption="添加模型:从厂商目录选择模型并查看实际调用方式" />
详见[模型管理](../03-features/06-models.md)。
## 知识库与数据源 {#knowledge}
- **Confluence 数据源**:支持 Cloud 和 Server / Data Center,按空间同步已发布页面,增量更新,并带删除保护。
- **钉钉文档数据源**;腾讯 IMA 同步时会遍历子文件夹。
- **上传与解析**:上传面板显示整体进度,可以取消、重试;解析时间线展示各阶段耗时和失败原因;长时间没有进展的文档会标记为「排队中」或「疑似卡住」。
- **列表与下载**:文档和资源列表支持排序;可以批量打包下载原始文件。
- **其他**:上传时可以关闭文档摘要;知识库描述可以根据文档画像自动生成;FAQ 可以按启用状态筛选;活动记录会显示操作所用的 API Key 名称。
<Screenshot
src="/screenshots/kb-upload-tasks.png"
caption="上传任务面板:整体进度与单个文件的取消、重试" />
<Screenshot
src="/screenshots/kb-parse-timeline.png"
caption="解析时间线:各阶段耗时、失败原因与重试" />
<Screenshot
src="/screenshots/datasource-confluence.png"
caption="数据源:配置 Confluence 并选择要同步的空间" />
详见[知识库](../03-features/02-knowledge-base.md)与[数据源导入](../03-features/10-datasource.md)。
## 集成、界面与安全 {#platform}
- **联网搜索**:新增博查和 Serply;Brave 与 Serply 支持按地区和时效过滤。
- **IM**:每个渠道可以单独设置回复语言。
- **日语界面**:界面新增日语,可在界面中切换,也可以用 `DEFAULT_LOCALE` 设为默认。
- **CLI 配置页**:「设置 → 发布集成 → CLI」按三步引导完成安装和登录。
- **管理员创建用户**:系统管理员可以在控制台直接创建账号,生成一次性密码并复制账号信息。
- **仅白名单出站**:设置 `SSRF_DNS_WHITELIST_ONLY=true` 后,不在 `SSRF_WHITELIST` 中的域名在 DNS 解析之前就会被拒绝,适合离线或严格管控的私有化部署。
<Screenshot
src="/screenshots/integration-cli.png"
caption="发布集成 → CLI:三步完成安装与登录" />
## 升级须知 {#upgrade-notes}
| 变化 | 需要做什么 |
| --- | --- |
| `.env.example` 不再提供 `JWT_SECRET`、`SYSTEM_AES_KEY` 的默认值,并新增 `SYSTEM_SIGNING_KEY` | 新部署需要自行生成。**已有部署必须保留原来的 `SYSTEM_AES_KEY`**,否则已保存的凭据无法解密。未设置 `JWT_SECRET` 时每个进程会随机生成,重启后登录失效,多副本之间也无法共用 |
| 钉钉 IM 渠道只支持 Stream 模式 | 迁移 `000096` 会把 webhook 渠道自动改为 Stream;需要在钉钉开发者后台为应用开启 Stream 模式 |
| 沙箱内命令默认以 `root` 执行(v0.8.0 为 uid 1000) | 每个对话独占一个沙箱,隔离边界仍是容器;依赖普通用户身份的脚本需要自行调整 |
| 更新 MCP 服务时如果传了 `usage_instructions`,必须是非空文本且不超过 16000 字符 | 不传该字段则保留原有说明 |
| 组织邀请只能按工作空间 ID 精确查找 | 不再支持按名称搜索工作空间 |
| Go SDK 的 `UpdateAgentRequest.Avatar` 改为 `*string` | `nil` 表示保留头像,空字符串表示清除 |
数据库迁移:PostgreSQL 为 `000091`–`000110`,SQLite 为 `000013`–`000030`。其中 `000106` 以 `CONCURRENTLY` 方式创建索引,如果中途中断,需要先删除无效索引再重新执行迁移,参见[常见问题与升级排障](../01-getting-started/05-troubleshooting.md)。ParadeDB 镜像已升级,可以运行在不支持 AVX2 的 CPU 上;MinIO 镜像改为从 `quay.io` 拉取。
## 其他改进与修复 {#other-changes}
- **智能体**:检索工具合并为 `search_knowledge`、`read_document`、`list_documents`,旧工具名自动映射,无需迁移配置;对话历史按模型上下文窗口裁剪,压缩检查点跨轮保留;MCP 工具改为按需发现和调用,服务的工具目录会持久保存,并可以单独启用或停用某个工具。
- **技能**:旧版本技能升级时不再回滚目录,也不会中途下线;安装后会校验运行时依赖。
- **Wiki**:整页重写被截断时会续写;同名条目跨类型复用页面;引用的分块会附带图片说明。
- **检索与解析**:Milvus 支持多语言 BM25;Neo4j 查询增加上限保护;PaddleOCR-VL 请求超时可配置;PDF 在链接 anydoc 时仍默认使用内置解析器;内联 HTML 表格不再产生超长分块。
- **稳定性**:修复文档卡在「处理中」或「删除中」的多种情况;关闭共享空间中跨工作区访问的路径;已删除租户的 Wiki 任务不再调用模型;向量、重排和部分对话厂商的请求格式已与其官方文档对齐。
完整列表见 [CHANGELOG](https://github.com/Tencent/WeKnora/blob/main/CHANGELOG.md)。

View File

@ -1,6 +1,10 @@
# Build from the repository root with:
# docker build -t weknora-site website-docs
# docker build --platform=linux/amd64 \
# --build-arg WEBSITE_NGINX_PORT=8080 \
# -t weknora-site website-docs
# No host Node.js installation or prebuilt static-site/ is required.
# WEBSITE_NGINX_PORT is written into default.conf at build time. The intranet
# platform starts `nginx; sleep infinity` and does not run docker-entrypoint.sh.
FROM node:24-bookworm-slim AS builder
RUN apt-get update \
&& apt-get install -y --no-install-recommends git \
@ -16,8 +20,29 @@ RUN npm run setup
COPY . .
RUN npm run build
FROM nginx:stable-alpine AS runtime
# Pin the runtime base. Do NOT switch back to floating `nginx:stable-alpine`:
# that tag is now Alpine 3.24+, which fails to start on intranet hosts with
# CentOS 7's kernel 3.10 and old libseccomp (the v0.7.0 frontend outage).
# This digest is nginx 1.30.3 / Alpine 3.23.5, the same base as the frontend
# image that still starts there. apk stays on the 3.23 repos.
FROM nginx:1.30.3-alpine@sha256:0d3b80406a13a767339fbe2f41406d6c7da727ab89cf8fae399e81f780f814d1 AS runtime
# Some deployment platforms wrap the startup command with /bin/bash -c.
RUN apk add --no-cache bash
# Baked into default.conf below. Entrypoint still honors a runtime override
# when it actually runs; the platform path does not.
ARG WEBSITE_NGINX_PORT=80
ENV WEBSITE_NGINX_PORT=${WEBSITE_NGINX_PORT}
COPY deploy/nginx.conf /etc/nginx/conf.d/default.conf
RUN rm -rf /usr/share/nginx/html/*
RUN mkdir -p /etc/nginx/templates \
&& sed 's/listen 80;/listen ${WEBSITE_NGINX_PORT};/' /etc/nginx/conf.d/default.conf \
> /etc/nginx/templates/default.conf.template \
&& sed "s/listen 80;/listen ${WEBSITE_NGINX_PORT};/" /etc/nginx/conf.d/default.conf \
> /etc/nginx/conf.d/default.conf.baked \
&& mv /etc/nginx/conf.d/default.conf.baked /etc/nginx/conf.d/default.conf \
&& grep -q "listen ${WEBSITE_NGINX_PORT};" /etc/nginx/conf.d/default.conf \
&& rm -rf /usr/share/nginx/html/*
COPY --from=builder /build/static-site/ /usr/share/nginx/html/
EXPOSE 80
COPY docker-entrypoint.sh /docker-entrypoint.sh
RUN chmod +x /docker-entrypoint.sh
EXPOSE ${WEBSITE_NGINX_PORT}
ENTRYPOINT ["/docker-entrypoint.sh"]

View File

@ -84,6 +84,14 @@ docker run -d --name weknora-site --restart unless-stopped -p 8080:80 weknora-si
访问 `http://服务器地址:8080/`。如使用域名和 HTTPS,让现有反向代理转发到该端口即可。镜像内已经包含官网、文档和 Nginx 路由配置。
容器内的 Nginx 默认监听 80 端口,可以用环境变量 `WEBSITE_NGINX_PORT` 修改,无需重新构建。使用 `--network host`,或者部署平台要求容器监听指定端口时,这样设置:
```bash
docker run -d --name weknora-site --restart unless-stopped -e WEBSITE_NGINX_PORT=8080 -p 8080:8080 weknora-site:0.8.0
```
只是想换一个对外端口时,改 `-p` 左侧的宿主机端口就够了,例如 `-p 9000:80`。
也可以只复制 `website-docs/` 目录,在该目录执行 `docker build -t weknora-site:0.8.0 .`。构建上下文必须是 `website-docs/`,宿主机的依赖、旧构建产物和部署包由 `.dockerignore` 排除。
从旧文档镜像迁移时,将容器端口映射或反向代理目标端口从 `8081` 改为 `80`(宿主机端口可自行选择,例如 `-p 8081:80`)。域名根路径 `/` 现在提供官网,`/docs/` 提供文档,反向代理需覆盖整个站点并保留请求路径。容器使用 Nginx 官方镜像的默认入口,无需额外的 `docker-entrypoint.sh`。

View File

@ -0,0 +1,12 @@
#!/bin/sh
set -eu
export WEBSITE_NGINX_PORT="${WEBSITE_NGINX_PORT:-80}"
# Substitute only the port; preserve Nginx variables such as $uri.
envsubst '${WEBSITE_NGINX_PORT}' \
< /etc/nginx/templates/default.conf.template \
> /etc/nginx/conf.d/default.conf
# Match the frontend entrypoint: configure and start Nginx even with no arguments.
exec nginx -g 'daemon off;'

View File

@ -6,6 +6,9 @@ Logos identify supported integrations; their names and marks belong to their res
- WeKnora browser icon: copied unchanged from the existing product's `frontend/public/favicon.ico` into the homepage and documentation. The replacement square sail SVG is no longer shipped.
- Feishu, GitLab, Tencent IMA, Notion, Yuque, RSS, WeCom, Slack, Telegram: copied unchanged from the WeKnora frontend asset library.
- OpenAI, DeepSeek, Qwen, Hunyuan, Gemini, Ollama, MCP: static SVGs from [Lobe Icons](https://github.com/lobehub/lobe-icons), `@lobehub/icons-static-svg@1.95.0`. Upstream MIT license included with assets.
- Confluence, DingTalk: copied unchanged from the WeKnora frontend asset library (`frontend/src/assets/img/datasource-confluence.svg`, `frontend/src/assets/img/im/dingtalk.svg`).
- Claude (Anthropic), Zhipu, Kimi (Moonshot), Volcengine, MiniMax: copied unchanged from `internal/models/providers/assets/`, which carries the same Lobe Icons static SVGs; covered by the included Lobe Icons MIT license.
- BrowserSkill: `frontend/src/assets/browserskill/logo.png` from the WeKnora frontend (the extension's own icon, [Tencent/BrowserSkill](https://github.com/Tencent/BrowserSkill)), copied unchanged to `public/brands/browserskill.png` with its MIT license as `public/brands/BROWSERSKILL-LICENSE`.
- Chrome: [official Chrome website asset](https://www.google.com/chrome/static/images/chrome-logo-m100.svg).
- File formats, REST API, CLI: generic interface icons, not brand logos.
- LiteLLM: [official documentation favicon](https://docs.litellm.ai/img/favicon.ico).
@ -14,5 +17,10 @@ Logos identify supported integrations; their names and marks belong to their res
## Product screenshots
- Skill catalog and sandbox terminal: copied unchanged from `../public/screenshots/skill-catalog.png` and `sandbox-panel-terminal.png` to `public/product/skill-catalog.png` and `sandbox-terminal.png`, for the skills & sandbox gallery.
- Sandbox desktop (`public/product/sandbox-desktop.png`): the chat's sandbox panel on the 桌面 tab, showing the XFCE desktop of a desktop template. It shares the 终端与图形桌面 card with the terminal screenshot, switched inside the card.
- v0.8.2 gallery: `mcp-server-endpoint.png`, `chat-steer-queue.png` and `browser-connection.png` copied unchanged from `../public/screenshots/` to `public/product/`. The local browser card switches between two views of the same capability: 任务 (below) and 连接 (the browser connection page).
- Browser task (`public/product/local-browser-task.png`): the default view of the local browser card, a smart-reasoning chat driving the connected Chrome through BrowserSkill (GitHub release lookup, then filling the httpbin.org sample order form without submitting), with the in-chat task preview and pause / end controls.
- Wiki browser: copied unchanged from `../public/screenshots/wiki-browser.png` to `public/product/wiki-browser.png`. Shows the actual Wiki directory, linked page and source references using sample company policies.
- Wiki graph and revision history: copied unchanged from `../public/screenshots/wiki-graph.png` and `wiki-revision-history.png` to matching files in `public/product/`, for the horizontal Wiki gallery.

View File

@ -6,6 +6,8 @@ type Integration = { name: string; logo: string } | { name: string; icon: string
export const dataSources: Integration[] = [
{ name: "PDF / Office", icon: "file" },
{ name: "飞书", logo: "feishu.ico" },
{ name: "Confluence", logo: "confluence.svg" },
{ name: "钉钉文档", logo: "dingtalk.svg" },
{ name: "GitLab", logo: "gitlab.png" },
{ name: "腾讯 IMA", logo: "ima.png" },
{ name: "Notion", logo: "notion.ico" },
@ -16,10 +18,12 @@ export const dataSources: Integration[] = [
export const clients: Integration[] = [
{ name: "企业微信", logo: "wecom.svg" },
{ name: "飞书", logo: "feishu.ico" },
{ name: "钉钉", logo: "dingtalk.svg" },
{ name: "Slack", logo: "slack.svg" },
{ name: "Telegram", logo: "telegram.svg" },
{ name: "Chrome", logo: "chrome.svg" },
{ name: "MCP", logo: "mcp.svg" },
{ name: "BrowserSkill", logo: "browserskill.png" },
{ name: "MCP Server", logo: "mcp.svg" },
{ name: "API", icon: "code" },
{ name: "CLI", icon: "terminal" },
{ name: "DeepSeek Harness", logo: "deepseek-color.svg" },
@ -27,10 +31,15 @@ export const clients: Integration[] = [
export const modelProviders: Integration[] = [
{ name: "OpenAI", logo: "openai.svg" },
{ name: "Claude", logo: "anthropic.svg" },
{ name: "Gemini", logo: "gemini-color.svg" },
{ name: "DeepSeek", logo: "deepseek-color.svg" },
{ name: "Qwen", logo: "qwen-color.svg" },
{ name: "混元", logo: "hunyuan-color.svg" },
{ name: "Gemini", logo: "gemini-color.svg" },
{ name: "智谱", logo: "zhipu.svg" },
{ name: "Kimi", logo: "moonshot.svg" },
{ name: "火山引擎", logo: "volcengine.svg" },
{ name: "MiniMax", logo: "minimax.svg" },
{ name: "Ollama", logo: "ollama.svg" },
{ name: "LiteLLM", logo: "litellm.ico" },
];

View File

@ -78,8 +78,11 @@
.textLink svg { width: 17px; height: 17px; transition: transform .2s; }
.textLink:hover { color: var(--wk-accent-text); }
.textLink:hover svg { transform: translateX(3px); }
.shotPlaceholder { display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 10px; aspect-ratio: 3840 / 2112; padding: 24px; text-align: center; color: var(--mute); background: repeating-linear-gradient(135deg, var(--paper2) 0 12px, var(--paper) 12px 24px); }
.shotPlaceholder > span { font-size: 15px; color: var(--soft); }
.shotPlaceholder > code { font-size: 12px; word-break: break-all; }
.release { padding-block: 93px 44px; background: var(--paper2); border-block: 1px solid var(--rule); }
.releaseGrid { display: grid; grid-template-columns: 1.4fr 1fr; gap: 58px; align-items: center; }
.sandboxTopic { background: var(--paper); border-top: 0; padding-bottom: 93px; }
.artifactFigure { margin: 0; min-width: 0; background: var(--paper); border: 1px solid var(--rule); border-radius: 5px; box-shadow: 0 18px 45px -35px #101f3844; overflow: hidden; }
.artifactHeading { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: 8px; padding: 16px 20px; font-size: 13px; border-bottom: 1px solid var(--rule); }
.artifactHeading > span { display: inline-flex; align-items: center; gap: 8px; }
@ -88,14 +91,6 @@
.artifactImage img { display: block; width: 100%; height: auto; }
.artifactFigure figcaption { display: flex; flex-wrap: wrap; justify-content: space-between; gap: 8px; padding: 14px 20px; font-size: 12px; color: var(--soft); border-top: 1px solid var(--rule); }
.artifactFigure figcaption > span:last-child { color: var(--mute); }
.releaseFeatures article { display: grid; grid-template-columns: 27px 1fr; gap: 18px; padding-block: 25px; border-bottom: 1px solid var(--rule); }
.releaseFeatures article:first-child { padding-top: 0; }
.releaseFeatures article:last-child { border: 0; padding-bottom: 0; }
.releaseFeatures article > svg { margin-top: 4px; width: 26px; height: 26px; stroke-width: 1.3; }
.featureLabel { color: var(--wk-accent-text); font-size: 12px; letter-spacing: .08em; }
.releaseFeatures h3 { font-size: 20px; font-weight: 550; line-height: 1.5; margin: 5px 0 10px; }
.releaseFeatures p { font-size: 15px; line-height: 1.85; color: var(--soft); margin: 0 0 7px; }
.releaseFeatures .textLink { font-size: 13px; }
.releaseExtras { display: flex; align-items: center; justify-content: space-between; flex-wrap: wrap; gap: 12px 24px; padding-top: 29px; margin-top: 48px; border-top: 1px solid var(--rule); font-size: 13px; color: var(--soft); }
.releaseExtras > span { color: var(--mute); }
.releaseExtras p { margin: 0; }
@ -103,34 +98,54 @@
.site section.wiki[id] { scroll-margin-top: 64px; }
.wiki .sectionHeading { margin-bottom: 24px; }
.wiki .eyebrow { margin-bottom: 12px; }
.wikiGallery { min-width: 0; }
.wikiGalleryToolbar { display: flex; align-items: center; justify-content: space-between; flex-wrap: wrap; gap: 8px 20px; margin-bottom: 16px; }
.wikiGalleryTabs { display: flex; gap: 8px; flex-wrap: wrap; }
.wikiGalleryTabs button { display: inline-flex; align-items: center; gap: 9px; padding: 10px 16px; min-height: 44px; border: 1px solid transparent; border-radius: 3px; color: var(--soft); background: transparent; font-size: 14px; }
.wikiGalleryTabs button[aria-pressed="true"] { color: var(--ink); border-color: var(--rule); background: var(--paper2); }
.wikiGalleryTabs button:hover { color: var(--wk-accent-text); }
.wikiGalleryTabs svg { width: 19px; height: 19px; }
.wikiGalleryTrack { --wiki-slide-width: min(84%, 720px); --wiki-slide-gap: 24px; display: flex; gap: var(--wiki-slide-gap); overflow-x: auto; scroll-snap-type: x mandatory; overscroll-behavior-x: contain; scrollbar-width: thin; scrollbar-color: var(--rule) transparent; padding-bottom: 16px; }
.wikiSlide { flex: 0 0 var(--wiki-slide-width); scroll-snap-align: center; box-shadow: none; }
.wikiSlide .artifactHeading { padding-block: 10px; }
.wikiSlide .artifactHeading .textLink { font-size: 12px; min-height: 24px; color: var(--soft); }
.wikiSlide .wikiSlideCaption { display: block; padding: 18px 24px; }
.wikiSlideCaption h3 { margin: 0 0 8px; color: var(--ink); font-size: 22px; font-weight: 550; line-height: 1.5; }
.wikiSlideCaption p { margin: 0; max-width: 780px; color: var(--soft); font-size: 15px; line-height: 1.85; }
.wikiGalleryControls { margin-left: auto; color: var(--mute); font-size: 13px; }
.wikiGalleryControls > div { display: flex; align-items: center; gap: 18px; flex-shrink: 0; }
.wikiGalleryControls > div > span { font-family: ui-monospace, monospace; color: var(--soft); }
.wikiGalleryControls button { display: grid; place-items: center; height: 44px; width: 44px; border: 1px solid var(--rule); border-radius: 50%; color: var(--ink); background: var(--paper); }
.wikiGalleryControls button:first-child svg { transform: rotate(180deg); }
.wikiGalleryControls button:disabled { opacity: .3; cursor: default; }
.wikiGalleryControls button:hover:not(:disabled) { color: var(--wk-accent-text); border-color: var(--gold); }
@media (min-width: 1100px) {
.wikiGalleryToolbar { display: none; }
.wikiGalleryTrack { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); overflow: visible; scroll-snap-type: none; padding-bottom: 0; }
.wikiSlideCaption h3 { font-size: 20px; }
.wikiSlide .wikiSlideCaption { padding: 20px; }
.wikiSlide .artifactHeading { padding-inline: 16px; }
.cardActions { display: flex; align-items: center; gap: 12px; }
.showcase { display: grid; grid-template-columns: minmax(280px, 360px) minmax(0, 1fr); gap: 48px; align-items: start; }
.showcaseList { border-top: 1px solid var(--rule); }
.showcaseItem { position: relative; padding-left: 20px; border-bottom: 1px solid var(--rule); cursor: pointer; }
.showcaseItem::before { content: ""; position: absolute; left: 0; top: 20px; bottom: 22px; width: 2px; background: transparent; transition: background .25s; }
.showcaseItem[data-active="true"] { cursor: default; }
.showcaseItem[data-active="true"]::before { background: var(--gold); }
.showcaseItem h3 { margin: 0; font: inherit; }
.showcaseItem h3 button { display: flex; flex-direction: column; align-items: flex-start; gap: 6px; width: 100%; padding: 20px 0 8px; border: 0; background: transparent; text-align: left; cursor: inherit; }
.showcaseName { display: inline-flex; align-items: center; gap: 8px; color: var(--mute); font-size: 12px; letter-spacing: .06em; }
.showcaseName svg { width: 17px; height: 17px; }
.showcaseTitle { color: var(--soft); font-size: 19px; font-weight: 550; line-height: 1.5; transition: color .2s; }
.showcaseItem[data-active="true"] .showcaseName { color: var(--wk-accent-text); }
.showcaseItem[data-active="true"] .showcaseTitle { color: var(--ink); }
.showcaseItem:not([data-active="true"]):hover .showcaseTitle { color: var(--wk-accent-text); }
.showcaseDetail { padding: 0 0 22px; }
.showcaseDetail p { margin: 0; color: var(--mute); font-size: 15px; line-height: 1.85; transition: color .25s; }
.showcaseItem[data-active="true"] .showcaseDetail p { color: var(--soft); }
.showcaseFigure { box-shadow: none; }
.showcaseFigure .artifactHeading { padding-block: 10px; }
.showcaseFigure .artifactHeading .textLink { font-size: 12px; min-height: 24px; color: var(--soft); }
@media (max-width: 1100px) {
.showcase { grid-template-columns: 1fr; gap: 24px; }
.showcaseTitle { font-size: 18px; }
.showcaseItem h3 button { padding: 16px 0 6px; }
.showcaseItem::before { top: 16px; bottom: 18px; }
.showcaseDetail { padding-bottom: 18px; }
}
.viewChips { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 12px; }
.viewChips button { position: relative; display: inline-flex; align-items: center; gap: 6px; min-height: 30px; padding: 0 12px; overflow: hidden; border: 1px solid var(--rule); border-radius: 999px; color: var(--soft); background: var(--paper); font-size: 13px; cursor: pointer; transition: color .2s, border-color .2s; }
.viewChips button svg { width: 15px; height: 15px; color: var(--mute); }
.viewChips button[aria-pressed="true"] { color: var(--ink); border-color: var(--gold); }
.viewChips button[aria-pressed="true"] svg { color: var(--gold); }
.viewChips button:hover { color: var(--wk-accent-text); border-color: var(--gold); }
.viewLabel { margin-left: 2px; color: var(--mute); font-style: normal; }
.tabProgress { position: absolute; left: 0; bottom: 0; width: 100%; height: 2px; background: var(--gold); transform-origin: left; animation: tabProgress var(--step-ms, 4s) linear forwards; animation-play-state: paused; }
.tabProgress[data-running="true"] { animation-play-state: running; }
@keyframes tabProgress { from { transform: scaleX(0); } to { transform: scaleX(1); } }
@media (prefers-reduced-motion: reduce) { .tabProgress { animation: none; } }
.shotStack { display: grid; overflow: hidden; }
.shotLayer { grid-area: 1 / 1; opacity: 0; transform: scale(1.015); pointer-events: none; transition: opacity .45s ease, transform .6s cubic-bezier(.2, .7, .2, 1); }
.shotLayer[data-active="true"] { opacity: 1; transform: none; pointer-events: auto; }
@media (prefers-reduced-motion: reduce) { .shotLayer { transition: none; } }
.pendingLabel { color: var(--mute); font-size: 12px; }
.slideLinks { display: flex; flex-wrap: wrap; align-items: center; gap: 4px 24px; margin-top: 10px; }
.externalLink img { display: block; width: 20px; height: 20px; border-radius: 5px; }
.externalLink svg { color: var(--mute); }
.cardActions { min-height: 24px; }
.ecosystem { display: grid; grid-template-columns: 1fr .85fr 1fr; gap: 48px; padding: 38px 0 46px; border-block: 1px solid var(--rule); }
.ecosystemColumn > svg { width: 29px; height: 29px; color: var(--gold); }
.ecosystemColumn h3 { font-size: 23px; font-weight: 550; margin: 18px 0 7px; }
@ -142,11 +157,11 @@
.ecosystemCore > strong { font-size: 28px; margin-top: 10px; font-weight: 550; letter-spacing: -.03em; }
.ecosystemCore > span:not(:global(.wk-logo)) { font-size: 14px; color: var(--soft); }
.ecosystemCore > div { font-size: 12px; color: var(--gold); margin-top: 18px; }
.models { display: flex; align-items: center; justify-content: space-between; gap: 16px 25px; flex-wrap: wrap; padding-top: 28px; }
.models > span { color: var(--mute); font-size: 13px; }
.models { display: flex; align-items: center; justify-content: flex-start; gap: 16px 28px; flex-wrap: wrap; padding-top: 28px; }
.models > span { display: flex; align-items: center; justify-content: space-between; gap: 16px; flex-basis: 100%; color: var(--mute); font-size: 13px; }
.models > span .textLink { font-size: 13px; }
.models > p { display: inline-flex; align-items: center; gap: 9px; font-size: 16px; color: var(--soft); font-weight: 550; margin: 0; }
.models img { display: block; width: 24px; height: 24px; flex-shrink: 0; object-fit: contain; }
.models a { display: flex; align-items: center; min-height: 40px; min-width: 40px; color: var(--soft); }
.enterprise { background: var(--paper2); border-block: 1px solid var(--rule); padding-block: 87px; }
.enterpriseGrid { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 50px; border-top: 1px solid var(--rule); padding-top: 37px; }
.enterpriseGrid article > svg { color: var(--gold); width: 29px; height: 29px; }
@ -177,14 +192,9 @@
.sectionHeading > p { max-width: 370px; font-size: 15px; }
.mode { padding-inline: 23px; }
.mode h3 { font-size: 20px; }
.releaseGrid { gap: 32px; grid-template-columns: 1.15fr 1fr; }
.releaseFeatures h3 { font-size: 18px; }
.ecosystem { gap: 28px; grid-template-columns: 1fr .7fr 1fr; }
}
@media (max-width: 800px) {
.wikiGalleryTrack { --wiki-slide-width: 92%; --wiki-slide-gap: 14px; }
.wikiSlide .wikiSlideCaption { padding: 18px; }
.wikiSlideCaption h3 { font-size: 20px; }
.navigationOpen { display: flex; position: absolute; left: 0; top: 72px; right: 0; padding: 20px 32px 26px; background: var(--paper); border-bottom: 1px solid var(--rule); flex-direction: column; align-items: stretch; gap: 4px; box-shadow: 0 15px 20px #101f380a; }
.navigationOpen a { font-size: 16px; }
.hero { padding-top: 34px; }
@ -207,9 +217,7 @@
.mode > p { margin-bottom: 18px; }
.tags { margin-bottom: 17px; }
.release { padding-block: 65px 35px; }
.releaseGrid { grid-template-columns: 1fr; gap: 35px; }
.releaseFeatures h3 { font-size: 22px; }
.releaseFeatures p { font-size: 16px; }
.sandboxTopic { padding-bottom: 65px; }
.releaseExtras { justify-content: flex-start; margin-top: 28px; padding-top: 23px; }
.releaseExtras > span { flex-basis: 100%; }
.ecosystem { grid-template-columns: 1fr 1fr; gap: 32px; }
@ -228,10 +236,6 @@
.site .wiki { padding-block: 28px; }
.wiki .sectionHeading { gap: 12px; margin-bottom: 18px; }
.wiki .sectionHeading h2 { font-size: 28px; }
.wikiGalleryTabs { gap: 2px; }
.wikiGalleryTabs button { padding-inline: 9px; gap: 6px; font-size: 13px; }
.wikiGalleryTabs svg { width: 16px; height: 16px; }
.wikiSlide .wikiSlideCaption { padding: 18px 14px; }
.shell { width: calc(100% - 40px); }
.hero h1 { font-size: clamp(28px, 7.9vw, 38px); }
.releaseLink { font-size: 12px; gap: 8px; }
@ -255,8 +259,6 @@
.models { justify-content: flex-start; gap: 15px 22px; }
.models > span { flex-basis: 100%; }
.models > p { font-size: 15px; }
.releaseFeatures article { grid-template-columns: 24px 1fr; gap: 14px; }
.releaseFeatures h3 { font-size: 20px; }
.artifactHeading { padding-inline: 12px; }
.artifactHeading > span:last-child { font-size: 12px; }
.artifactFigure figcaption { padding-inline: 12px; }

View File

@ -4,7 +4,7 @@ import { themeInitializationScript } from "./theme";
export const metadata: Metadata = {
title: "WeKnora — 帮你找到答案,并将知识付诸实践",
description: "腾讯开源知识框架 WeKnora,集 RAG 问答、Agent 推理与自动 Wiki 于一体。v0.8.0 带来技能目录、会话级沙箱和跨会话长期记忆,支持私有化部署。",
description: "腾讯开源知识框架 WeKnora,集 RAG 问答、Agent 推理与自动 Wiki 于一体。v0.8.2 让智能体操作本机浏览器、以 MCP Server 对外提供知识库,并支持对话分叉与回滚;支持私有化部署。",
};
export default function RootLayout({

View File

@ -1,8 +1,10 @@
import { existsSync } from "node:fs";
import { join } from "node:path";
import Image from "next/image";
import Link from "next/link";
import { BrandLogo } from "./brand-logo";
import { Icon } from "./ui";
import { WikiGallery } from "./wiki-gallery";
import { ProductGallery, type GalleryShot, type GallerySlide } from "./product-gallery";
import { Header, ProductVideo } from "./interactive";
import { clients, dataSources, modelProviders, IntegrationMark } from "./brands";
import s from "./home.module.css";
@ -12,14 +14,38 @@ const docs = "/docs/";
const guide = (path: string) => `${docs}${path}.html`;
const modes = [
{ number: "01", icon: "search", label: "RAG", title: "回答有据可查", description: "结合语义与关键词检索查找相关资料,回答附带来源引用,可打开原文核对。", tags: ["混合检索", "多模态解析", "原文引用"], link: "03-features/05-retrieval-engines" },
{ number: "02", icon: "agent", label: "Agent", title: "用知识和工具完成任务", description: "智能体根据任务检索知识库、搜索网页、调用 MCP 工具与技能,并在沙箱中处理文件、运行脚本。", tags: ["多步推理", "工具调用", "技能执行"], link: "03-features/07-agent" },
{ number: "02", icon: "agent", label: "Agent", title: "用知识和工具完成任务", description: "智能体根据任务检索知识库、搜索网页、调用 MCP 工具与技能,在沙箱中处理文件、运行脚本,并可跨会话记住你确认过的偏好。", tags: ["多步推理", "工具调用", "技能执行", "长期记忆"], link: "03-features/07-agent" },
{ number: "03", icon: "wiki", label: "Wiki", title: "把文档整理成 Wiki", description: "从原始文档生成相互链接的 Wiki 页面与知识图谱,支持浏览、编辑和版本回滚。", tags: ["自动组织", "知识图谱", "版本回滚"], link: "03-features/14-wiki" },
];
const release = [
{ icon: "skills", title: "安装、管理和复用技能", text: "从 ClawHub、SkillHub、Git 或 ZIP 安装技能。在空间内统一管理,查看安装进度,浏览与编辑技能文件。", link: "03-features/22-skills-sandbox", label: "空间技能目录" },
{ icon: "sandbox", title: "在同一沙箱中继续执行任务", text: "支持 Docker、E2B、Cube 三种后端。同一会话中的多轮任务共用一个沙箱工作区,生成的文件可预览与下载。", link: "03-features/22-skills-sandbox", label: "会话级沙箱" },
{ icon: "memory", title: "跨会话保留偏好和任务信息", text: "在后续对话中使用已保存的偏好、事实与任务信息。自动提取的记忆由你确认,也可随时管理或关闭。", link: "03-features/23-memory", label: "长期记忆" },
];
const releaseExtras = ["Confluence / 钉钉文档数据源", "27 家模型厂商目录", "博查 / Serply 联网搜索", "日语界面", "仅白名单出站"];
const productShotExists = (src: string) => existsSync(join(process.cwd(), "public", src));
type SlideSource = Omit<GallerySlide, "shots"> & ({ image: string; alt: string } | { shots: Omit<GalleryShot, "available">[] });
const withAvailability = (slide: SlideSource): GallerySlide => {
const shots = "shots" in slide ? slide.shots : [{ image: slide.image, alt: slide.alt }];
return { name: slide.name, icon: slide.icon, title: slide.title, description: slide.description, link: slide.link, external: slide.external, shots: shots.map(shot => ({ ...shot, available: productShotExists(`/product/${shot.image}.png`) })) };
};
const releaseSlides = [
{ name: "本机浏览器", icon: "browser", shots: [
{ label: "执行任务", icon: "browser", image: "local-browser-task", alt: "WeKnora 实际界面:智能推理对话正在操作本机浏览器,对话中显示任务预览与暂停、继续、结束控制" },
{ label: "连接扩展", icon: "plug", image: "browser-connection", alt: "WeKnora 实际界面:工具箱的浏览器连接页,BrowserSkill 扩展已连接并列出智能体可执行的网页操作" },
], title: "操作你电脑上的浏览器", description: "借助腾讯开源的 BrowserSkill 扩展,智能体直接在你的 Chrome 或 Edge 中打开网页、填写表单;遇到登录或验证码时交给你。", link: guide("05-clients/09-local-browser"), external: { label: "BrowserSkill", href: "https://github.com/Tencent/BrowserSkill", logo: "browserskill.png" } },
{ name: "MCP Server", icon: "plug", image: "mcp-server-endpoint", title: "把知识库发布给其他 AI 工具", description: "为空间创建 MCP 端点,Claude、Cursor 等客户端连上即可检索知识库和提问。", alt: "WeKnora 实际界面:MCP 端点的连接信息,包含端点地址与 Cursor、Claude Desktop 的 mcpServers 配置", link: guide("03-features/08-mcp") },
{ name: "对话控制", icon: "branch", image: "chat-steer-queue", title: "随时调整进行中的对话", description: "回答中途可以补充要求,也能从任意一次提问分叉或回滚;生成的文件统一收在「产物」页。", alt: "WeKnora 实际界面:回答生成期间,输入框上方排队等待的补充要求", link: guide("03-features/18-chat-experience") },
].map(withAvailability);
const wikiSlides = [
{ name: "知识图谱", icon: "channels", image: "wiki-graph", title: "顺着链接,查看相关知识", description: "在知识图谱中查看页面之间的关系。点击条目,即可阅读相关内容。", alt: "Wiki 知识图谱:日常费用报销条目与相关页面的链接关系,右侧展示条目详情" },
{ name: "页面浏览", icon: "wiki", image: "wiki-browser", title: "按主题整理,保留出处", description: "开启 Wiki 后,从知识库文档中提取人物、产品和概念,生成带来源引用的页面,按目录浏览。", alt: "Wiki 浏览器:按主题组织的目录、年假页面、关联条目和原始文档引用" },
{ name: "版本历史", icon: "history", image: "wiki-revision-history", title: "随时编辑,改动可回溯", description: "直接修订页面,也可让智能体协助维护。查看版本差异,必要时恢复到历史内容。", alt: "Wiki 版本历史:年假页面的历史版本列表、内容差异和回滚入口" },
].map(withAvailability);
const sandboxSlides = [
{ name: "会话级沙箱", icon: "sandbox", image: "skill-sandbox-chat", title: "在同一沙箱中继续执行任务", description: "支持 Docker、E2B、Cube。同一会话的多轮任务共用一个工作区,生成的文件可预览和下载。", alt: "WeKnora 实际界面:智能体根据知识库生成 Word 文档,并在对话旁打开产物预览", link: guide("03-features/22-skills-sandbox") },
{ name: "图形桌面与终端", icon: "monitor", shots: [
{ label: "图形桌面", icon: "monitor", image: "sandbox-desktop", alt: "WeKnora 实际界面:对话右侧沙箱面板的桌面页签,显示沙箱内的 XFCE 图形桌面与文件管理器" },
{ label: "交互终端", icon: "terminal", image: "sandbox-terminal", alt: "WeKnora 实际界面:对话右侧的沙箱终端,列出工作区 output 目录中生成的 Word 文件" },
], title: "打开桌面和终端,看清每一步", description: "在对话旁打开图形桌面或交互终端,查看智能体的每一步操作,必要时亲自接手。", link: guide("03-features/22-skills-sandbox") },
{ name: "技能目录", icon: "skills", image: "skill-catalog", title: "安装、管理和复用技能", description: "从 ClawHub、SkillHub、Git 或 ZIP 安装技能,在空间内统一管理和复用。", alt: "WeKnora 实际界面:工具箱的技能管理页,列出 docx、pptx、pdf 技能及其安装到的沙箱", link: guide("03-features/22-skills-sandbox") },
].map(withAvailability);
export default function Home() {
return <div className={s.site}>
@ -27,7 +53,7 @@ export default function Home() {
<Header />
<main id="main">
<section className={`${s.shell} ${s.hero}`} aria-labelledby="hero-title">
<a href="#release" className={s.releaseLink}><span>v0.8.0</span> 技能、沙箱与长期记忆 <Icon name="arrow" /></a>
<a href="#release" className={s.releaseLink}><span>v0.8.2</span> 本机浏览器、MCP Server 与对话分叉 <Icon name="arrow" /></a>
<div className={s.heroGrid}>
<h1 id="hero-title">帮你找到答案,<br /><em>并将知识付诸实践。</em></h1>
<div className={s.heroAside}>
@ -49,32 +75,33 @@ export default function Home() {
</article>)}</div>
</section>
<section id="release" className={s.release} aria-labelledby="release-title"><div className={s.shell}>
<div className={s.sectionHeading}><div><p className={s.eyebrow}>02 / INTRODUCING v0.8.0</p><h2 id="release-title">智能体可以运行技能,<br />也能生成文件。</h2></div><a className={s.textLink} href={`${repo}/blob/main/CHANGELOG.md#080---2026-09-03`} target="_blank" rel="noreferrer">查看版本更新 <Icon name="arrow" /></a></div>
<div className={s.releaseGrid}>
<figure className={s.artifactFigure}><div className={s.artifactHeading}><span><Icon name="file" /> 在对话中预览生成的文件</span><span>AGENT → ARTIFACT</span></div><div className={s.artifactImage}><Image src="/product/skill-sandbox-chat.png" alt="WeKnora 实际界面:智能体根据知识库生成 Word 文档,并在对话旁打开产物预览" width={3840} height={2112} sizes="(max-width: 960px) 100vw, 60vw" /></div><figcaption><span>检索知识 → 执行任务 → 生成文档</span><span>产品实景</span></figcaption></figure>
<div className={s.releaseFeatures}>{release.map(feature => <article key={feature.title}><Icon name={feature.icon} /><div><span className={s.featureLabel}>{feature.label}</span><h3>{feature.title}</h3><p>{feature.text}</p><a className={s.textLink} href={guide(feature.link)}>了解更多 <Icon name="arrow" /></a></div></article>)}</div>
</div>
<div className={s.releaseExtras}><span>本次更新还包括</span><p>GitLab / 腾讯 IMA 数据源</p><p>anydoc Office 解析</p><p>DeepSeek Harness 插件</p><p>LiteLLM 接入</p></div>
<div className={s.sectionHeading}><div><p className={s.eyebrow}>02 / INTRODUCING v0.8.2</p><h2 id="release-title">智能体能操作浏览器,<br />知识库能接入其他 AI。</h2></div><a className={s.textLink} href={guide("07-releases/v0.8.2")}>查看版本说明 <Icon name="arrow" /></a></div>
<ProductGallery id="release-gallery" label="v0.8.2" slides={releaseSlides} />
<div className={s.releaseExtras}><span>本次更新还包括</span>{releaseExtras.map(item => <p key={item}>{item}</p>)}</div>
</div></section>
<section id="skills-sandbox" className={`${s.release} ${s.sandboxTopic}`} aria-labelledby="skills-sandbox-title"><div className={s.shell}>
<div className={s.sectionHeading}><div><p className={s.eyebrow}>03 / SKILLS &amp; SANDBOX</p><h2 id="skills-sandbox-title">智能体可以运行技能,<br />也能生成文件。</h2></div><a className={s.textLink} href={guide("03-features/22-skills-sandbox")}>了解技能与沙箱 <Icon name="arrow" /></a></div>
<ProductGallery id="sandbox-gallery" label="技能与沙箱" slides={sandboxSlides} />
</div></section>
<section id="wiki" className={`${s.shell} ${s.section} ${s.wiki}`} aria-labelledby="wiki-title">
<div className={s.sectionHeading}>
<div><p className={s.eyebrow}>03 / AUTOMATIC WIKI</p><h2 id="wiki-title">把文档整理成可浏览的 Wiki。</h2></div>
<div><p className={s.eyebrow}>04 / AUTOMATIC WIKI</p><h2 id="wiki-title">把文档整理成可浏览的 Wiki。</h2></div>
<a className={s.textLink} href={guide("03-features/14-wiki")}>了解 Wiki 的使用方式 <Icon name="arrow" /></a>
</div>
<WikiGallery />
<ProductGallery id="wiki-gallery" label="Wiki" slides={wikiSlides} />
</section>
<section id="ecosystem" className={`${s.shell} ${s.section}`} aria-labelledby="ecosystem-title">
<div className={s.sectionHeading}><div><p className={s.eyebrow}>04 / INTEGRATIONS</p><h2 id="ecosystem-title">数据源与工具集成</h2></div><p>同步飞书、GitLab 等平台的资料,<br />通过 IM、浏览器插件或 API 查询和使用。</p></div>
<div className={s.sectionHeading}><div><p className={s.eyebrow}>05 / INTEGRATIONS</p><h2 id="ecosystem-title">数据源与工具集成</h2></div><p>同步飞书、Confluence、GitLab 等平台的资料,<br />通过 IM、浏览器插件、MCP 或 API 查询和使用。</p></div>
<div className={s.ecosystem}>
<div className={s.ecosystemColumn}><Icon name="sources" /><h3>导入与同步资料</h3><p>上传文件、导入网页,或连接外部数据源。</p><div className={s.integrations}>{dataSources.map(item => <span key={item.name}><IntegrationMark item={item} /></span>)}</div><a className={s.textLink} href={guide("03-features/10-datasource")}>数据源集成 <Icon name="arrow" /></a></div>
<div className={s.ecosystemCore}><BrandLogo /><span>团队知识库与智能体</span><div>理解 · 检索 · 推理 · 行动</div></div>
<div className={s.ecosystemColumn}><Icon name="channels" /><h3>在常用工具中访问</h3><p>支持 IM 问答、浏览器插件和开发工具集成。</p><div className={s.integrations}>{clients.map(item => <span key={item.name}><IntegrationMark item={item} /></span>)}</div><a className={s.textLink} href={guide("03-features/12-im-integration")}>客户端与渠道 <Icon name="arrow" /></a></div>
<div className={s.ecosystemColumn}><Icon name="channels" /><h3>在常用工具中访问</h3><p>支持 IM 问答、浏览器插件、MCP 客户端和开发工具集成。</p><div className={s.integrations}>{clients.map(item => <span key={item.name}><IntegrationMark item={item} /></span>)}</div><a className={s.textLink} href={guide("03-features/12-im-integration")}>客户端与渠道 <Icon name="arrow" /></a></div>
</div>
<div className={s.models}><span>模型由你选择</span>{modelProviders.map(item => <p key={item.name}><IntegrationMark item={item} /></p>)}<a href={guide("03-features/06-models")} aria-label="查看全部模型厂商"><Icon name="arrow" /></a></div>
<div className={s.models}><span>模型由你选择 · 内置 27 家厂商 <a className={s.textLink} href={guide("03-features/06-models")}>查看全部 <Icon name="arrow" /></a></span>{modelProviders.map(item => <p key={item.name}><IntegrationMark item={item} /></p>)}</div>
</section>
<section id="enterprise" className={s.enterprise} aria-labelledby="enterprise-title"><div className={s.shell}>
<div className={s.sectionHeading}><div><p className={s.eyebrow}>05 / BUILT FOR YOUR TEAM</p><h2 id="enterprise-title">私有化部署,<br />按团队需要管理权限。</h2></div><p>配置数据存储与成员权限,<br />查看操作记录和任务运行状态。</p></div>
<div className={s.enterpriseGrid}><article><Icon name="server" /><h3>部署与存储</h3><p>支持 Docker、Kubernetes 与 Helm。模型、向量数据库和存储后端可按需替换,支持本地推理。</p></article><article><Icon name="shield" /><h3>空间与资源权限</h3><p>多空间隔离与四级角色矩阵。API Key 按能力和知识库限定范围,支持 OIDC 身份集成。</p></article><article><Icon name="trace" /><h3>审计与运行监控</h3><p>空间审计日志、运行时任务队列面板与 Langfuse 追踪,帮助团队定位问题、管理运行状态。</p></article></div>
<div className={s.sectionHeading}><div><p className={s.eyebrow}>06 / BUILT FOR YOUR TEAM</p><h2 id="enterprise-title">私有化部署,<br />按团队需要管理权限。</h2></div><p>配置数据存储与成员权限,<br />查看操作记录和任务运行状态。</p></div>
<div className={s.enterpriseGrid}><article><Icon name="server" /><h3>部署与存储</h3><p>支持 Docker、Kubernetes 与 Helm,也提供 Lite 单机版和桌面应用。模型、向量数据库和存储后端可按需替换,支持本地推理。</p></article><article><Icon name="shield" /><h3>空间与资源权限</h3><p>多空间隔离与四级角色矩阵。API Key 按能力和知识库限定范围,支持 OIDC 身份集成,可限制服务只访问白名单域名。</p></article><article><Icon name="trace" /><h3>审计与运行监控</h3><p>空间审计日志、运行时任务队列面板与 Langfuse 追踪,帮助团队定位问题、管理运行状态。</p></article></div>
</div></section>
<section id="get-started" className={`${s.shell} ${s.closing}`} aria-labelledby="closing-title">
<div className={s.sectionHeading}><div><p className={s.eyebrow}>GET STARTED</p><h2 id="closing-title">选择适合你的使用方式。</h2></div></div>

View File

@ -0,0 +1,121 @@
"use client";
import Image from "next/image";
import { useEffect, useRef, useState, type CSSProperties } from "react";
import { Icon } from "./ui";
import s from "./home.module.css";
export type GalleryShot = { label?: string; icon?: string; image: string; alt: string; available: boolean };
export type GallerySlide = {
name: string;
icon: string;
title: string;
description: string;
/** One screenshot, or several views of the same capability switched inside the figure. */
shots: GalleryShot[];
link?: string;
/** Optional external reference shown beside "了解更多", e.g. an upstream repository. */
external?: { label: string; href: string; logo?: string };
};
// The showcase plays itself once it is on screen: every screenshot stays for
// STEP_MS, and multi-view items walk through their views before moving on.
// Keyboard focus pauses it; any click stops it for good.
const STEP_MS = 4000;
const AUTO_ROUNDS = 2;
/** A feature list beside one large screenshot; the list doubles as the navigation. */
export function ProductGallery({ id, label, slides }: { id: string; label: string; slides: GallerySlide[] }) {
const root = useRef<HTMLDivElement>(null);
const [item, setItem] = useState(0);
const [shot, setShot] = useState(0);
const [auto, setAuto] = useState(true);
const [steps, setSteps] = useState(0);
const [visible, setVisible] = useState(false);
const [paused, setPaused] = useState(false);
const totalSteps = slides.reduce((count, slide) => count + slide.shots.length, 0);
const active = slides[item];
const activeShot = active.shots[shot];
useEffect(() => {
const element = root.current;
if (!element) return;
const observer = new IntersectionObserver(([entry]) => setVisible(entry.isIntersecting), { threshold: 0.4 });
observer.observe(element);
return () => observer.disconnect();
}, []);
const running = auto && visible && !paused;
useEffect(() => {
if (!running || window.matchMedia("(prefers-reduced-motion: reduce)").matches) return;
const timer = window.setTimeout(() => {
const lastView = shot + 1 >= slides[item].shots.length;
setShot(lastView ? 0 : shot + 1);
if (lastView) setItem((item + 1) % slides.length);
setSteps(steps + 1);
if (steps + 1 >= totalSteps * AUTO_ROUNDS) setAuto(false);
}, STEP_MS);
return () => window.clearTimeout(timer);
}, [running, item, shot, steps, slides, totalSteps]);
function selectItem(index: number) {
setAuto(false);
setItem(index);
setShot(0);
}
function selectView(index: number, view: number) {
setAuto(false);
setItem(index);
setShot(view);
}
return <div id={id} ref={root} className={s.showcase} onFocus={() => setPaused(true)} onBlur={() => setPaused(false)}>
<div className={s.showcaseList} aria-label={`${label} 功能`}>
{slides.map((slide, index) => <div key={slide.name} className={s.showcaseItem} data-active={index === item} onClick={() => { if (index !== item) selectItem(index); }}>
<h3><button type="button" aria-pressed={index === item} onClick={event => { event.stopPropagation(); selectItem(index); }}>
<span className={s.showcaseName}><Icon name={slide.icon} />{slide.name}</span>
<span className={s.showcaseTitle}>{slide.title}</span>
</button></h3>
<div className={s.showcaseDetail}>
<p>{slide.description}</p>
{slide.shots.length > 1 && <div className={s.viewChips} aria-label={`${slide.name}截图`}>
{slide.shots.map((entry, view) => {
const current = index === item && view === shot;
return <button key={entry.image} type="button" aria-pressed={current} onClick={event => { event.stopPropagation(); selectView(index, view); }}>
<Icon name={entry.icon ?? slide.icon} />{entry.label}
{/* Restarted whenever the timer restarts (new step or resume), so the bar and the switch stay in step. */}
{auto && current && <span key={`${item}-${shot}-${steps}-${running}`} className={s.tabProgress} data-running={running} style={{ "--step-ms": `${STEP_MS}ms` } as CSSProperties} aria-hidden="true" />}
</button>;
})}
</div>}
{(slide.link || slide.external) && <div className={s.slideLinks}>
{slide.link && <a className={s.textLink} href={slide.link}>了解更多 <Icon name="arrow" /></a>}
{slide.external && <a className={`${s.textLink} ${s.externalLink}`} href={slide.external.href} target="_blank" rel="noreferrer">{slide.external.logo && <Image src={`/brands/${slide.external.logo}`} alt="" aria-hidden="true" width={20} height={20} />}{slide.external.label}<Icon name="github" /></a>}
</div>}
</div>
</div>)}
</div>
<figure className={`${s.artifactFigure} ${s.showcaseFigure}`}>
<div className={s.artifactHeading}>
<span><Icon name={activeShot.icon ?? active.icon} />{active.name}{active.shots.length > 1 && activeShot.label && <em className={s.viewLabel}>· {activeShot.label}</em>}</span>
<div className={s.cardActions}>
{activeShot.available
? <a className={s.textLink} href={`/product/${activeShot.image}.png`} target="_blank" rel="noreferrer" aria-label={`查看${active.name}原图(新窗口)`}>查看原图 <Icon name="external" /></a>
: <span className={s.pendingLabel}>待补充</span>}
</div>
</div>
{/* Every screenshot stays mounted in one cell so switching cross-fades without resizing. */}
<div className={`${s.artifactImage} ${s.shotStack}`}>
{slides.flatMap((slide, index) => slide.shots.map((entry, shotIndex) => {
const current = index === item && shotIndex === shot;
return <div key={entry.image} className={s.shotLayer} data-active={current} aria-hidden={!current}>
{entry.available
? <Image src={`/product/${entry.image}.png`} alt={entry.alt} width={3840} height={2112} sizes="(min-width: 1100px) 60vw, 100vw" />
: <div className={s.shotPlaceholder} role="img" aria-label={entry.alt}><span>截图待补充</span><code>{`website-docs/homepage/public/product/${entry.image}.png`}</code></div>}
</div>;
}))}
</div>
</figure>
</div>;
}

View File

@ -17,6 +17,11 @@ const paths: Record<string, ReactNode> = {
model: <><path d="m12 2 10 5-10 5L2 7l10-5Zm-10 10 10 5 10-5M2 17l10 5 10-5" /></>,
shield: <><path d="m12 2 9 4v6c0 5-5 8-9 10-4-2-9-5-9-10V6l9-4Z" /><path d="m8 12 3 3 5-6" /></>,
trace: <><path d="M3 3v18h18M6 15l4-5 4 3 6-8" /><circle cx="10" cy="10" r="1" /><circle cx="14" cy="13" r="1" /></>,
browser: <><rect x="2" y="4" width="20" height="16" rx="2" /><path d="M2 9h20M6 6.5h.01M9 6.5h.01" /><path d="m11 13 6 2.5-2.6.9-.9 2.6Z" /></>,
plug: <><path d="M9 2v5m6-5v5M6 7h12v4a6 6 0 0 1-12 0V7Zm6 10v5" /></>,
branch: <><circle cx="6" cy="5" r="2" /><circle cx="6" cy="19" r="2" /><circle cx="18" cy="8" r="2" /><path d="M6 7v10m12-7c0 4-6 3-11.2 7.4" /></>,
monitor: <><rect x="2" y="3" width="20" height="14" rx="2" /><path d="M8 21h8m-4-4v4M6 7h5m-5 3h3" /></>,
swap: <path d="M4 8h13l-3-3m6 11H7l3 3" />,
menu: <path d="M4 6h16M4 12h16M4 18h16" />,
close: <path d="m5 5 14 14M5 19 19 5" />,
code: <path d="m7 7-5 5 5 5m10-10 5 5-5 5m-3-14-4 18" />,

View File

@ -1,73 +0,0 @@
"use client";
import Image from "next/image";
import { useRef, useState, useSyncExternalStore } from "react";
import { Icon } from "./ui";
import s from "./home.module.css";
const slides = [
{ name: "页面浏览", icon: "wiki", image: "wiki-browser", title: "按主题整理,保留出处", description: "开启 Wiki 后,从知识库文档中提取人物、产品和概念,生成带来源引用的页面,按目录浏览。", alt: "Wiki 浏览器:按主题组织的目录、年假页面、关联条目和原始文档引用" },
{ name: "知识图谱", icon: "channels", image: "wiki-graph", title: "顺着链接,查看相关知识", description: "在知识图谱中查看页面之间的关系。点击条目,即可阅读相关内容。", alt: "Wiki 知识图谱:日常费用报销条目与相关页面的链接关系,右侧展示条目详情" },
{ name: "版本历史", icon: "history", image: "wiki-revision-history", title: "随时编辑,改动可回溯", description: "直接修订页面,也可让智能体协助维护。查看版本差异,必要时恢复到历史内容。", alt: "Wiki 版本历史:年假页面的历史版本列表、内容差异和回滚入口" },
];
const wideLayoutQuery = "(min-width: 1100px)";
function subscribeToLayout(notify: () => void) {
const query = window.matchMedia(wideLayoutQuery);
query.addEventListener("change", notify);
return () => query.removeEventListener("change", notify);
}
const getWideLayout = () => window.matchMedia(wideLayoutQuery).matches;
const getServerLayout = () => false;
// Center intermediate slides; clamp the first and last to the real track edges.
function slidePosition(element: HTMLDivElement, index: number) {
const slide = element.children[index] as HTMLElement;
const first = element.children[0] as HTMLElement;
const centered = slide.offsetLeft - first.offsetLeft + slide.offsetWidth / 2 - element.clientWidth / 2;
return Math.max(0, Math.min(element.scrollWidth - element.clientWidth, centered));
}
export function WikiGallery() {
const track = useRef<HTMLDivElement>(null);
const [active, setActive] = useState(0);
const wide = useSyncExternalStore(subscribeToLayout, getWideLayout, getServerLayout);
function goTo(index: number) {
const element = track.current;
if (!element) return;
const next = Math.max(0, Math.min(slides.length - 1, index));
element.scrollTo({ left: slidePosition(element, next), behavior: window.matchMedia("(prefers-reduced-motion: reduce)").matches ? "instant" : "smooth" });
}
function syncActive() {
const element = track.current;
if (!element) return;
const distances = slides.map((_, index) => Math.abs(slidePosition(element, index) - element.scrollLeft));
setActive(distances.indexOf(Math.min(...distances)));
}
return <div className={s.wikiGallery} role="region" aria-label="Wiki 产品图集" aria-roledescription={wide ? undefined : "轮播图"}>
<div className={s.wikiGalleryToolbar}>
<div className={s.wikiGalleryTabs} aria-label="选择 Wiki 截图">
{slides.map((slide, index) => <button key={slide.image} type="button" aria-pressed={active === index} aria-controls="wiki-gallery-track" onClick={() => goTo(index)}><Icon name={slide.icon} />{slide.name}</button>)}
</div>
<div className={s.wikiGalleryControls}>
<div><button type="button" aria-label="上一张 Wiki 截图" aria-controls="wiki-gallery-track" disabled={active === 0} onClick={() => goTo(active - 1)}><Icon name="arrow" /></button><span aria-live="polite" aria-atomic="true">{String(active + 1).padStart(2, "0")} / 03</span><button type="button" aria-label="下一张 Wiki 截图" aria-controls="wiki-gallery-track" disabled={active === slides.length - 1} onClick={() => goTo(active + 1)}><Icon name="arrow" /></button></div>
</div>
</div>
<div id="wiki-gallery-track" className={s.wikiGalleryTrack} ref={track} tabIndex={wide ? -1 : 0} aria-label={wide ? "Wiki 的三项能力" : "Wiki 截图,可左右滑动或使用方向键切换"} onScroll={syncActive} onKeyDown={event => {
if (wide || event.target !== event.currentTarget) return;
if (!["ArrowLeft", "ArrowRight", "Home", "End"].includes(event.key)) return;
event.preventDefault();
goTo(event.key === "Home" ? 0 : event.key === "End" ? slides.length - 1 : active + (event.key === "ArrowRight" ? 1 : -1));
}}>
{slides.map((slide, index) => <figure key={slide.image} className={`${s.artifactFigure} ${s.wikiSlide}`} role="group" aria-roledescription={wide ? undefined : "幻灯片"} aria-label={`${index + 1} / ${slides.length}:${slide.name}`}>
<div className={s.artifactHeading}><span><Icon name={slide.icon} />{slide.name}</span><a className={s.textLink} href={`/product/${slide.image}.png`} target="_blank" rel="noreferrer" aria-label={`查看${slide.name}原图(新窗口)`}>查看原图 <Icon name="external" /></a></div>
<div className={s.artifactImage}><Image src={`/product/${slide.image}.png`} alt={slide.alt} width={3840} height={2112} sizes="(min-width: 1100px) 33vw, (max-width: 800px) 90vw, 720px" /></div>
<figcaption className={s.wikiSlideCaption}><h3>{slide.title}</h3><p>{slide.description}</p></figcaption>
</figure>)}
</div>
</div>;
}

View File

@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 Tencent
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

View File

@ -0,0 +1 @@
<svg height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Claude</title><path d="M4.709 15.955l4.72-2.647.08-.23-.08-.128H9.2l-.79-.048-2.698-.073-2.339-.097-2.266-.122-.571-.121L0 11.784l.055-.352.48-.321.686.06 1.52.103 2.278.158 1.652.097 2.449.255h.389l.055-.157-.134-.098-.103-.097-2.358-1.596-2.552-1.688-1.336-.972-.724-.491-.364-.462-.158-1.008.656-.722.881.06.225.061.893.686 1.908 1.476 2.491 1.833.365.304.145-.103.019-.073-.164-.274-1.355-2.446-1.446-2.49-.644-1.032-.17-.619a2.97 2.97 0 01-.104-.729L6.283.134 6.696 0l.996.134.42.364.62 1.414 1.002 2.229 1.555 3.03.456.898.243.832.091.255h.158V9.01l.128-1.706.237-2.095.23-2.695.08-.76.376-.91.747-.492.584.28.48.685-.067.444-.286 1.851-.559 2.903-.364 1.942h.212l.243-.242.985-1.306 1.652-2.064.73-.82.85-.904.547-.431h1.033l.76 1.129-.34 1.166-1.064 1.347-.881 1.142-1.264 1.7-.79 1.36.073.11.188-.02 2.856-.606 1.543-.28 1.841-.315.833.388.091.395-.328.807-1.969.486-2.309.462-3.439.813-.042.03.049.061 1.549.146.662.036h1.622l3.02.225.79.522.474.638-.079.485-1.215.62-1.64-.389-3.829-.91-1.312-.329h-.182v.11l1.093 1.068 2.006 1.81 2.509 2.33.127.578-.322.455-.34-.049-2.205-1.657-.851-.747-1.926-1.62h-.128v.17l.444.649 2.345 3.521.122 1.08-.17.353-.608.213-.668-.122-1.374-1.925-1.415-2.167-1.143-1.943-.14.08-.674 7.254-.316.37-.729.28-.607-.461-.322-.747.322-1.476.389-1.924.315-1.53.286-1.9.17-.632-.012-.042-.14.018-1.434 1.967-2.18 2.945-1.726 1.845-.414.164-.717-.37.067-.662.401-.589 2.388-3.036 1.44-1.882.93-1.086-.006-.158h-.055L4.132 18.56l-1.13.146-.487-.456.061-.746.231-.243 1.908-1.312-.006.006z" fill="#D97757" fill-rule="nonzero"></path></svg>

After

Width:  |  Height:  |  Size: 1.7 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 22 KiB

View File

@ -0,0 +1,11 @@
<svg width="48" height="48" viewBox="0 0 48 48" fill="none" xmlns="http://www.w3.org/2000/svg">
<path d="M0 12C0 5.37258 5.37258 0 12 0H36C42.6274 0 48 5.37258 48 12V36C48 42.6274 42.6274 48 36 48H12C5.37258 48 0 42.6274 0 36V12Z" fill="#1868DB"/>
<g clip-path="url(#clip0_1_6000)">
<path d="M34.7396 28.5301C27.3329 24.9487 25.1691 24.4136 22.0484 24.4136C18.3866 24.4136 15.2658 25.9367 12.4779 30.2179L12.0202 30.9177C11.6457 31.494 11.5625 31.6998 11.5625 31.9468C11.5625 32.1938 11.6873 32.3996 12.145 32.6878L16.847 35.6105C17.0967 35.7752 17.3048 35.8575 17.5128 35.8575C17.7625 35.8575 17.9289 35.734 18.1786 35.3635L18.9276 34.2109C20.0927 32.4408 21.1329 31.8645 22.4645 31.8645C23.6296 31.8645 25.0027 32.1938 26.7087 33.0171L31.6188 35.3224C32.1181 35.5693 32.659 35.4458 32.9087 34.8695L35.2389 29.765C35.4886 29.1887 35.3221 28.8182 34.7396 28.5301ZM13.1437 19.5149C20.5504 23.0963 22.7141 23.6314 25.8349 23.6314C29.4966 23.6314 32.6174 22.1083 35.4053 17.8271L35.8631 17.1273C36.2376 16.551 36.3208 16.3452 36.3208 16.0982C36.3208 15.8512 36.1959 15.6454 35.7382 15.3572L31.0362 12.4345C30.7866 12.2698 30.5785 12.1875 30.3705 12.1875C30.1208 12.1875 29.9544 12.311 29.7047 12.6815L28.9557 13.8341C27.7906 15.6042 26.7504 16.1805 25.4188 16.1805C24.2537 16.1805 22.8806 15.8512 21.1745 15.0279L16.2645 12.7226C15.7652 12.4757 15.2242 12.5992 14.9746 13.1755L12.6444 18.28C12.3947 18.8563 12.5612 19.2268 13.1437 19.5149Z" fill="white"/>
</g>
<defs>
<clipPath id="clip0_1_6000">
<rect width="24.7583" height="23.67" fill="white" transform="translate(11.5625 12.1875)"/>
</clipPath>
</defs>
</svg>

After

Width:  |  Height:  |  Size: 1.6 KiB

View File

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><path fill="#1677ff" d="M12 2C6.477 2 2 6.477 2 12s4.477 10 10 10s10-4.477 10-10S17.523 2 12 2m4.49 9.04l-.006.014c-.42.898-1.516 2.66-1.516 2.66l-.005-.012l-.32.558h1.543l-2.948 3.919l.67-2.666h-1.215l.422-1.763a17 17 0 0 0-1.223.349s-.646.378-1.862-.729c0 0-.82-.722-.344-.902c.202-.077.981-.175 1.595-.257a80 80 0 0 1 1.338-.172s-2.555.039-3.161-.057c-.606-.095-1.375-1.107-1.539-1.996c0 0-.253-.488.545-.257s4.101.9 4.101.9S8.27 9.312 7.983 8.99c-.286-.32-.841-1.754-.769-2.634c0 0 .031-.22.257-.16c0 0 3.176 1.45 5.347 2.245s4.06 1.199 3.816 2.228c-.02.087-.072.216-.144.37"/></svg>

After

Width:  |  Height:  |  Size: 672 B

View File

@ -0,0 +1 @@
<svg height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Minimax</title><defs><linearGradient id="lobe-icons-minimax-_R_0_" x1="0%" x2="100.182%" y1="50.057%" y2="50.057%"><stop offset="0%" stop-color="#E2167E"></stop><stop offset="100%" stop-color="#FE603C"></stop></linearGradient></defs><path d="M16.278 2c1.156 0 2.093.927 2.093 2.07v12.501a.74.74 0 00.744.709.74.74 0 00.743-.709V9.099a2.06 2.06 0 012.071-2.049A2.06 2.06 0 0124 9.1v6.561a.649.649 0 01-.652.645.649.649 0 01-.653-.645V9.1a.762.762 0 00-.766-.758.762.762 0 00-.766.758v7.472a2.037 2.037 0 01-2.048 2.026 2.037 2.037 0 01-2.048-2.026v-12.5a.785.785 0 00-.788-.753.785.785 0 00-.789.752l-.001 15.904A2.037 2.037 0 0113.441 22a2.037 2.037 0 01-2.048-2.026V18.04c0-.356.292-.645.652-.645.36 0 .652.289.652.645v1.934c0 .263.142.506.372.638.23.131.514.131.744 0a.734.734 0 00.372-.638V4.07c0-1.143.937-2.07 2.093-2.07zm-5.674 0c1.156 0 2.093.927 2.093 2.07v11.523a.648.648 0 01-.652.645.648.648 0 01-.652-.645V4.07a.785.785 0 00-.789-.78.785.785 0 00-.789.78v14.013a2.06 2.06 0 01-2.07 2.048 2.06 2.06 0 01-2.071-2.048V9.1a.762.762 0 00-.766-.758.762.762 0 00-.766.758v3.8a2.06 2.06 0 01-2.071 2.049A2.06 2.06 0 010 12.9v-1.378c0-.357.292-.646.652-.646.36 0 .653.29.653.646V12.9c0 .418.343.757.766.757s.766-.339.766-.757V9.099a2.06 2.06 0 012.07-2.048 2.06 2.06 0 012.071 2.048v8.984c0 .419.343.758.767.758.423 0 .766-.339.766-.758V4.07c0-1.143.937-2.07 2.093-2.07z" fill="url(#lobe-icons-minimax-_R_0_)" fill-rule="nonzero"></path></svg>

After

Width:  |  Height:  |  Size: 1.5 KiB

View File

@ -0,0 +1 @@
<svg height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Kimi</title><path d="M21.846 0a1.923 1.923 0 110 3.846H20.15a.226.226 0 01-.227-.226V1.923C19.923.861 20.784 0 21.846 0z" fill="#1783FF"></path><path d="M11.065 11.199l7.257-7.2c.137-.136.06-.41-.116-.41H14.3a.164.164 0 00-.117.051l-7.82 7.756c-.122.12-.302.013-.302-.179V3.82c0-.127-.083-.23-.185-.23H3.186c-.103 0-.186.103-.186.23V19.77c0 .128.083.23.186.23h2.69c.103 0 .186-.102.186-.23v-3.25c0-.069.025-.135.069-.178l2.424-2.406a.158.158 0 01.205-.023l6.484 4.772a7.677 7.677 0 003.453 1.283c.108.012.2-.095.2-.23v-3.06c0-.117-.07-.212-.164-.227a5.028 5.028 0 01-2.027-.807l-5.613-4.064c-.117-.078-.132-.279-.028-.381z" fill="#1783FF"></path></svg>

After

Width:  |  Height:  |  Size: 776 B

View File

@ -0,0 +1 @@
<svg height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Volcengine</title><path d="M19.44 10.153l-2.936 11.586a.215.215 0 00.214.261h5.87a.215.215 0 00.214-.261l-2.95-11.586a.214.214 0 00-.412 0zM3.28 12.778l-2.275 8.96A.214.214 0 001.22 22h4.532a.212.212 0 00.214-.165.214.214 0 000-.097l-2.276-8.96a.214.214 0 00-.41 0z" fill="#00E5E5"></path><path d="M7.29 5.359L3.148 21.738a.215.215 0 00.203.261h8.29a.214.214 0 00.215-.261L7.7 5.358a.214.214 0 00-.41 0z" fill="#006EFF"></path><path d="M14.44.15a.214.214 0 00-.41 0L8.366 21.739a.214.214 0 00.214.261H19.9a.216.216 0 00.171-.078.214.214 0 00.044-.183L14.439.15z" fill="#006EFF"></path><path d="M10.278 7.741L6.685 21.736a.214.214 0 00.214.264h7.17a.215.215 0 00.214-.264L10.688 7.741a.214.214 0 00-.41 0z" fill="#00E5E5"></path></svg>

After

Width:  |  Height:  |  Size: 858 B

View File

@ -0,0 +1 @@
<svg height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Zhipu</title><path d="M11.991 23.503a.24.24 0 00-.244.248.24.24 0 00.244.249.24.24 0 00.245-.249.24.24 0 00-.22-.247l-.025-.001zM9.671 5.365a1.697 1.697 0 011.099 2.132l-.071.172-.016.04-.018.054c-.07.16-.104.32-.104.498-.035.71.47 1.279 1.186 1.314h.366c1.309.053 2.338 1.173 2.286 2.523-.052 1.332-1.152 2.38-2.478 2.327h-.174c-.715.018-1.274.64-1.239 1.368 0 .124.018.23.053.337.209.373.54.658.96.8.75.23 1.517-.125 1.9-.782l.018-.035c.402-.64 1.17-.96 1.92-.711.854.284 1.378 1.226 1.099 2.167a1.661 1.661 0 01-2.077 1.102 1.711 1.711 0 01-.907-.711l-.017-.035c-.2-.323-.463-.58-.851-.711l-.056-.018a1.646 1.646 0 00-1.954.746 1.66 1.66 0 01-1.065.764 1.677 1.677 0 01-1.989-1.279c-.209-.906.332-1.83 1.257-2.043a1.51 1.51 0 01.296-.035h.018c.68-.071 1.151-.622 1.116-1.333a1.307 1.307 0 00-.227-.693 2.515 2.515 0 01-.366-1.403 2.39 2.39 0 01.366-1.208c.14-.195.21-.444.227-.693.018-.71-.506-1.261-1.186-1.332l-.07-.018a1.43 1.43 0 01-.299-.07l-.05-.019a1.7 1.7 0 01-1.047-2.114 1.68 1.68 0 012.094-1.101zm-5.575 10.11c.26-.264.639-.367.994-.27.355.096.633.379.728.74.095.362-.007.748-.267 1.013-.402.41-1.053.41-1.455 0a1.062 1.062 0 010-1.482zm14.845-.294c.359-.09.738.024.992.297.254.274.344.665.237 1.025-.107.36-.396.634-.756.718-.551.128-1.1-.22-1.23-.781a1.05 1.05 0 01.757-1.26zm-.064-4.39c.314.32.49.753.49 1.206 0 .452-.176.886-.49 1.206-.315.32-.74.5-1.185.5-.444 0-.87-.18-1.184-.5a1.727 1.727 0 010-2.412 1.654 1.654 0 012.369 0zm-11.243.163c.364.484.447 1.128.218 1.691a1.665 1.665 0 01-2.188.923c-.855-.36-1.26-1.358-.907-2.228a1.68 1.68 0 011.33-1.038c.593-.08 1.183.169 1.547.652zm11.545-4.221c.368 0 .708.2.892.524.184.324.184.724 0 1.048a1.026 1.026 0 01-.892.524c-.568 0-1.03-.47-1.03-1.048 0-.579.462-1.048 1.03-1.048zm-14.358 0c.368 0 .707.2.891.524.184.324.184.724 0 1.048a1.026 1.026 0 01-.891.524c-.569 0-1.03-.47-1.03-1.048 0-.579.461-1.048 1.03-1.048zm10.031-1.475c.925 0 1.675.764 1.675 1.706s-.75 1.705-1.675 1.705-1.674-.763-1.674-1.705c0-.942.75-1.706 1.674-1.706zm-2.626-.684c.362-.082.653-.356.761-.718a1.062 1.062 0 00-.238-1.028 1.017 1.017 0 00-.996-.294c-.547.14-.881.7-.752 1.257.13.558.675.907 1.225.783zm0 16.876c.359-.087.644-.36.75-.72a1.062 1.062 0 00-.237-1.019 1.018 1.018 0 00-.985-.301 1.037 1.037 0 00-.762.717c-.108.361-.017.754.239 1.028.245.263.606.377.953.305l.043-.01zM17.19 3.5a.631.631 0 00.628-.64c0-.355-.279-.64-.628-.64a.631.631 0 00-.628.64c0 .355.28.64.628.64zm-10.38 0a.631.631 0 00.628-.64c0-.355-.28-.64-.628-.64a.631.631 0 00-.628.64c0 .355.279.64.628.64zm-5.182 7.852a.631.631 0 00-.628.64c0 .354.28.639.628.639a.63.63 0 00.627-.606l.001-.034a.62.62 0 00-.628-.64zm5.182 9.13a.631.631 0 00-.628.64c0 .355.279.64.628.64a.631.631 0 00.628-.64c0-.355-.28-.64-.628-.64zm10.38.018a.631.631 0 00-.628.64c0 .355.28.64.628.64a.631.631 0 00.628-.64c0-.355-.279-.64-.628-.64zm5.182-9.148a.631.631 0 00-.628.64c0 .354.279.639.628.639a.631.631 0 00.628-.64c0-.355-.28-.64-.628-.64zm-.384-4.992a.24.24 0 00.244-.249.24.24 0 00-.244-.249.24.24 0 00-.244.249c0 .142.122.249.244.249zM11.991.497a.24.24 0 00.245-.248A.24.24 0 0011.99 0a.24.24 0 00-.244.249c0 .133.108.236.223.247l.021.001zM2.011 6.36a.24.24 0 00.245-.249.24.24 0 00-.244-.249.24.24 0 00-.244.249.24.24 0 00.244.249zm0 11.263a.24.24 0 00-.243.248.24.24 0 00.244.249.24.24 0 00.244-.249.252.252 0 00-.244-.248zm19.995-.018a.24.24 0 00-.245.248.24.24 0 00.245.25.24.24 0 00.244-.25.252.252 0 00-.244-.248z" fill="#3859FF" fill-rule="nonzero"></path></svg>

After

Width:  |  Height:  |  Size: 3.5 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 540 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 619 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 740 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 468 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.1 MiB

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