2026-08-06 10:22:10 +00:00
|
|
|
|
# API 参考:知识库与知识
|
|
|
|
|
|
|
2026-09-08 02:54:41 +00:00
|
|
|
|
创建知识库,导入与管理文档,并查询处理进度、复制或移动内容。
|
2026-08-06 10:22:10 +00:00
|
|
|
|
|
|
|
|
|
|
权限速记:读路由为 Viewer+ 且需对 KB 有 read 权限(自有/组织共享/共享 Agent 可见);写路由为“KB 创建者 OR Admin+”且需 write 权限。API key:读需 `retrieve`,内容写需 `ingest`,KB 生命周期需 `manage_kbs`(均可被 full-access 覆盖),并受 KB 白名单约束。
|
|
|
|
|
|
|
|
|
|
|
|
分块、标签与分块预览接口(`/chunks`、`/knowledge-bases/:id/tags`、`/chunker/preview`)在[分块与标签](./02-api-chunks.md)。
|
|
|
|
|
|
|
|
|
|
|
|
## 知识库(/api/v1/knowledge-bases)
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/knowledge-bases
|
|
|
|
|
|
|
|
|
|
|
|
用途:创建知识库。权限:Contributor+;API key `manage_kbs`/full。Handler: `internal/handler/knowledgebase.go`
|
|
|
|
|
|
|
|
|
|
|
|
请求体(`types.KnowledgeBase`):
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `name` | string | 是 | 名称 |
|
|
|
|
|
|
| `description` | string | 否 | 描述 |
|
|
|
|
|
|
| `type` | string | 否 | `document`(默认)/`faq`/`wiki` |
|
|
|
|
|
|
| `embedding_model_id` | string | 否 | Embedding 模型 ID |
|
|
|
|
|
|
| `chunking_config` | object | 否 | 分块配置(chunk_size/overlap/separators/strategy…) |
|
feat(gallery): add an image gallery tab with schema-driven filters (#3694)
* feat(image): observe image attributes and let the policy decide OCR
Describe each image with the VLM as before, but ask it to also observe two
attributes about the image in the same round — how much body text it carries
(contain.text) and whether it presents data visually (contain.data_visual) —
then let a small pure function decide whether that image is worth a second,
separate OCR round.
Per-class OCR was the first shape of this idea; a class (chart / photo / logo)
is only an indirect proxy for 'is there text worth reading here', and the class
table has to grow whenever a new kind of image shows up. The decision actually
needs the observed attributes, so it reads them directly, and the attribute set
is a backend registry row rather than a new class.
The observation and the caption share one VLM call; OCR stays a separate call
(prompt isolation, see #3291). An attribute the model does not answer for is
left absent rather than filled with a conservative default, so the trace never
claims an observation that did not happen, and an incomplete observation falls
back to the on_unobserved policy (OCR still runs). The registry also carries the
panel's display text, so a new attribute needs no frontend change.
Off by default: image_attrs_enabled=false keeps today's behaviour (one caption
and one OCR per image). KB config: image_processing_config.image_attrs_enabled /
image_actions; per-upload override via process_config. Registry:
GET /api/v1/image-attrs/schema.
* feat(gallery): add image gallery tab with schema-driven filters
Adds a 4th knowledge-base tab parallel to Documents/Wiki/Graph that
browses every image asset in a KB.
Backend:
- GET /api/v1/knowledge-bases/:id/images lists image assets projected
from chunks.image_info, with keyword (caption/OCR), multi-value
attribute (attr_<name>=<value>), is_enabled and sort filters applied
in memory, plus pagination.
- Resolves the source knowledge item title (SourceName) via a batched
GetKnowledgeBatch so the viewer can show a human-readable source.
Frontend:
- ImageGallery.vue: thumbnail grid + search/sort + schema-driven filter
panel (from GET /image-attrs/schema) + single-image viewer with
prev/next, attributes/caption/OCR/source.
- Wired as the gallery tab in KnowledgeBase.vue; i18n keys in all 5 locales.
* feat(gallery): drive filters/search/sort from a configurable attribute contract
The gallery UI is no longer hardcoded: it renders from a self-describing
contract served by GET /knowledge-bases/:id/gallery-config (live attribute
sources, every attribute's definition with usage flags merged across the
config tiers, and the caller's search activation state).
- Attribute sources form an open registry (types.RegisterGalleryAttrSource);
a builtin source models caption/ocr_text/timestamps/enabled so the gallery
has zero special cases.
- Usage resolution: user > KB > system > source, field by field; the system
tier lives in system_settings (gallery.policy, JSON, no rebuild), the KB
tier slot is wired in the engine but not stored yet.
- Search activation is the user's own record: mode (all|custom) plus
per-field on/off in users.preferences.gallery; source declarations never
set defaults (unrecorded = off in custom mode).
- image_info is read through a gallery-local struct, removing the compile
dependency on the attribute-pipeline types; the gallery builds and runs
with or without that feature deployed.
- ListImages validates search_in / sort_by / attr_filters against the
contract; ineligible fields are dropped, not served.
* fix(frontend): inline the shared graph-drawer stylesheet (@import instead of <style src>)
plugin-vue 6.0.6 keys unscoped src-style descriptors by the imported file
path, so AgentStreamDisplay.vue and WikiBrowser.vue — both importing
components/css/wiki-graph-drawer.less — overwrite each other during the
build and the second one crashes with "reading 'scoped'". Adding the
gallery changed the module order enough to make the collision hit every
time. Inlining the same stylesheet keeps the emitted CSS identical and
removes the shared descriptor key.
* feat(gallery): render attributes from short labels with descriptions in tooltips
A source could only say one thing about a value, so the filter panel had to put
a full sentence inside a checkbox. Attributes and their values now carry two
pieces of text: a short label for the space-constrained controls (checkbox,
search field, sort option) and a description for wherever there is room
(tooltip, detail panel).
The contract's value list becomes an array of {value, label, description}, and
the display helpers resolve each field separately: the gallery stamps the short
name on a control and moves the sentence into a tooltip. Translation overlays
are looked up per field, so a source that ships no gallery-specific text still
picks up the attribute pipeline's own wording.
* fix(gallery): let locale text win over the contract's wording
The filter panel read the backend's own label before asking the locale,
so a translated value never got a chance: the contract ships its own
default-language wording, and it shadowed the overlay for every locale.
Built keys were also off by a segment — imageAttr.<name> has to be
imageAttr.<name>.label, and the gallery's own keys live under
knowledgeEditor.wikiBrowser.gallery.attr — so builtin and system
attributes fell through to English on a Chinese UI.
* feat(gallery): top bar layout, pinned panels and per-value verdicts
The toolbar moves onto its own row above the grid, so the controls no
longer eat into the space the images are there for: search box, the two
scope switches, sort field and direction, and the result count all sit in
one flex row. The settings behind them are no longer inline either — each
opens as a popover under its control and can be pinned to a right-hand
rail, where the two panels take turns as tabs instead of both claiming
width at once.
Filtering gains a third state per attribute value. Where a value could
only be picked or not picked, it can now be "off" (hide those images),
"on" (show them whatever else says) or neutral (leave them alone), which
is what lets one attribute's rules talk about an image another attribute
tried to hide without the pair of them cancelling each other out: a
forced display outranks a forced hide, and anything no rule speaks about
stays visible.
The switch that used to only exist inside the panel now has a toolbar
home as well. "筛选:全显示" genuinely drops the attribute constraint
instead of imposing it against a panel the user cannot see.
Filtering used to empty the list the moment it was switched on. Any
image whose attribute was never observed — every image ingested before
the attribute pipeline existed — read as a mismatch for every filter,
which is not narrowing a list but losing it. Absence now stays silence:
an attribute no image carries places no constraint on it, until the
pipeline catches up and fills the value in.
Co-authored-by: WorkBuddy
* feat(gallery): expose the image attribute pipeline as a gallery source
The gallery's contract resolved to a single source, so the filter panel
could only offer "Enabled" while the attributes the observe-and-describe
pipeline fills in — contain.text, contain.data_visual — never reached the
UI. The registry is a gallery attribute source like any other: every
attribute it declares is offered to the gallery, filterable by default,
with the config tiers able to override the usage flags at runtime.
The registration lives in the attribute pipeline's own commit; this branch
carried an earlier, squapshot of that work which predated the split of an
attribute value into a short label and a description, so the registry's
value shape and this file have been brought in line with it. Both PRs now
hold byte-identical copies of the source hook, which is what lets either
one land first and the other merge cleanly afterwards.
Co-authored-by: WorkBuddy
* fix(gallery): viewer race, pin icon, panel anchoring and scope wording
Opening the viewer rendered the img element with the previous or empty
source while the proxy fetch was still producing a blob, and the error
that empty source fired locked the viewer in its failure state even
after the real image arrived. The resolved source now lands before the
flag is consulted, and a token keeps a slow fetch of one image from
overwriting a faster one that navigated past it.
The pin button drew nothing: TDesign has no "pushpin" glyph, so the
button rendered as an empty shell. It now uses pin / pin-filled, keeps
its place beside the tab bar, and a pinned rail assigns its columns
explicitly — the panel precedes the main section in the DOM, so leaving
the grid to source order handed the wide column to the panel and
squeezed the images into the rail.
The floating panel no longer appears at a hardcoded offset: it anchors
just below the arrow that summoned it, the arrow flips up while its
panel is out, a second press retracts, and any click elsewhere in the
toolbar closes it. When a rail is pinned the arrows turn to the
requested tab instead of spawning a second surface.
The scope words (全部 / 全显示 / 自定义) become plain status text rather
than a second dropdown — they name the current mode, and only the arrow
beside them opens the panel that changes it.
Co-authored-by: WorkBuddy
* fix(web): align the OCR-on-unobserved switch with the other setting rows
The switch sat bare inside its setting-row while every other switch on
the page is wrapped in setting-control, which is what reserves the right
column and centers the control vertically. With the row laid out from
the top, the bare switch hugged the row's upper edge and crowded the
description text — visibly out of place next to its neighbors. Wrapping
it in setting-control gives it the same right-aligned, centered slot as
the rest.
Co-authored-by: WorkBuddy
* fix(web): move the OCR-on-unobserved row out of the vertical schema row
The row lived inside setting-row-vertical, whose descendant rule stretches
every setting-info and setting-control beneath it to 100% width. Two
full-width flex children side by side cannot fit, so the control overflowed
the container and the switch landed past the right edge — visibly further
out than the switch on the row above. The row and its note now sit beside
the vertical block instead of inside it, under their own condition, so the
switch shares the ordinary row layout and its right edge lines up with the
"image attribute observation" switch above.
Co-authored-by: WorkBuddy
* fix(gallery): applying a verdict now activates the filter scope
Setting an off/on verdict while the panel's master switch was off
silently ignored it: buildParams only attaches attr_rules in custom
scope, and setVerdict never flipped the scope. A verdict the user just
expressed now switches the scope to custom; clearing the last meaningful
verdict returns to all, since custom with no rules constrains nothing.
* fix(gallery): search checkboxes stay visible and idle panels read as dimmed
The search panel hid its field checkboxes while the master switch was
on, so the only way to reach them was to flip the switch first. They now
sit next to the switch like the filter panel's verdicts do: dimmed in
all-field mode (where they carry no weight) yet clickable, and touching
one drops the mode to custom. The filter panel's verdict rows dim the
same way while the filter switch is off.
* fix(gallery): bulk verdict row, neutral default mark, panel polish
The clear-filters button never matched what the panel is for, so it is
now a bulk verdict row: one set of -/off/on buttons that applies the
chosen position to every value of every value-typed attribute, with the
default mark turned into a language-neutral dash. The panel head drops
its second divider (the tab bar already draws one) and the tabs follow
the toolbar's order: search left, filter right.
* fix(gallery): drop the all-fields caption and center the order arrow
The caption above the search checkboxes showed and hid with the master
switch, shoving the checkboxes down on every flip; it said nothing the
dimmed state doesn't, so it is gone. The order button's arrow is an
inline svg, which sits on the text baseline and reads as riding high;
it now centers against the label.
* fix(gallery): center the order arrow for real
vertical-align never applied: the icon is a flex item inside the
button's inline-flex text wrapper, and the wrapper's default stretch
pins the explicitly-sized 16px icon to the top of the 22px line box.
align-items: center on the wrapper is what actually centers it.
* fix(gallery): shorten panel tab labels in en and ru
The two-word labels overflowed the 300px panel and forced the tab bar
into scroll arrows; single-word labels fit in every locale that was
affected.
* docs: drop the image pipeline rewrite from this branch
The rewritten 'Go 侧接手后' paragraph belongs to the image attribute observation
work (#3635), which this branch carries as a prerequisite and which already
documents the caption_ocr / observation_driven split. Keeping a competing
rewrite of the same paragraph on the gallery branch makes it collide with
upstream, which extended that paragraph with the custom_instructions and inline
HTML table notes. Restoring the shared wording keeps the gallery branch free of
this file so upstream's edits merge cleanly.
* style: gofmt the gallery attribute types
Struct field tags in the resolved gallery config were one column narrow, so
gofmt rebroke the alignment block. Whitespace only.
* style(gallery): use design tokens in the gallery styles
The style guard ratchet fails on any new violation. ImageGallery.vue shipped
with 47 TDesign token fallbacks, 21 literal font sizes, 4 literal radii and a
0.15s transition; all of them now read the --app-* / --td-* tokens, which is
what the guard asks for and what dark mode depends on.
* lint(gallery): fix the golangci-lint findings in the gallery code
lll: the three over-long swagger @Param lines and one registry row were
shortened. ineffassign: ctx was assigned before the access check and then
reassigned, so the first value was dead; it is now declared once, after the
check. errcheck: the three unchecked c.Error calls in ListImages. revive: the
AttrSpec / AttrValue doc comment block was attached to the wrong type and split
into one block each. staticcheck S1016: the gallery registration converts the
registry value instead of restating its fields.
* lint(gallery): wrap the image query select and check the last c.Error
* style: reformat the wrapped image select in chunk.go
* fix(gallery): address review findings on ordering, KB switch and blob lifetime
- sortImageAssets: swap operands for desc instead of negating, keeping a
strict weak ordering so ties page stably
- ImageGallery: reload on knowledgeBaseId change, drop stale list
responses, fetch thumbnails in parallel with one cached blob per URL,
revoke blobs on unmount, default sort to builtin:created_at
- KnowledgeBase: non-wiki KBs with a stale wiki/graph tab fall back to
documents again
- handler: move ListImages godoc out of ListKnowledgeFolders' block and
document attr_filters / attr_rules
- DecideOCR: a payload with no OCR conditions uses the built-in policy
instead of silently skipping OCR
* docs(parsing): describe the caption_ocr and observation_driven image pipelines
Carried over from #3635, which this PR supersedes.
* fix(gallery): load local:// and other storage handles through the KB file proxy
The gallery's own scheme check only caught resource://, provider:// and
storage://, so local:// (the default storage), minio://, cos:// and s3://
images went straight into <img src> and never rendered. Resolve through
isProviderFileURL, the scheme list chat and wiki already use, and lock the
routing with a test.
* fix(kb-editor): keep API-customised OCR conditions on save and upload
The KB editor always wrote the registry default into image_actions.ocr.on,
so any unrelated edit replaced a knowledge base's custom OCR conditions
with the default table; the upload dialog did the same for the per-document
override. Keep a stored custom list and fall back to the registry default
only when there is none, and show the conditions actually in effect instead
of the default table in both panels.
* perf(gallery): de-duplicate, filter, sort and page images in SQL
Every gallery request used to read every image-bearing chunk of the KB,
OCR text included, decode it in Go and page in memory. A single query now
expands the image_info arrays, keeps one row per image URL, applies the
keyword / attribute / verdict / enabled filters and the sort, and returns
only the page with the filtered total.
The expansion carries narrow scalars only; filters and JSON sort keys are
evaluated on the winning entry of each image, and the page's JSON is read
back for its rows alone. Postgres runs the query with JIT off, since the
fixed 100-rows-per-call estimate of jsonb_array_elements otherwise prices
it ~100x high and compilation dominates.
On 20k images with 2 KB of OCR text each (40k chunks), a page drops from
~750 ms to ~100-200 ms on postgres and ~200 ms on sqlite; keyword search
over OCR text stays a full scan (~400-600 ms) until the text is indexed.
The filter semantics are pinned against both databases.
* perf(gallery): serve the gallery from a trigger-maintained chunk_images table
Reading images out of chunks.image_info meant parsing every image chunk of
the knowledge base on each request, so a page still cost time in
proportion to the KB. chunk_images (versioned/000113, sqlite/000032) keeps
one row per image_info entry with caption, OCR text and attributes as
columns; triggers on chunks keep it in step with every write path, and the
migration backfills existing chunks.
Copies of one image stay separate rows and the query lists the copy on the
most recently updated chunk through an indexed anti-join, so writes decide
nothing and concurrent writers need no locking. On postgres, caption and
OCR text get pg_trgm indexes when the extension is available.
On 20k images with 2 KB of OCR text each (40k chunks):
postgres first page 10 ms, page 500 41 ms, keyword 2 ms, filters 23 ms
sqlite first page 3 ms, page 500 39 ms, keyword 147 ms, filters 51 ms
down from ~100-600 ms. Writing those 40k image chunks costs 7.0 s instead
of 1.3 s on postgres (1.9 s instead of 1.0 s on sqlite), mostly the trigram
indexes; status and enable-flag updates patch rows in place.
---------
Co-authored-by: tayadwx <tayadwx@users.noreply.github.com>
Co-authored-by: wizardchen <wizardchen@tencent.com>
2026-09-25 04:33:59 +00:00
|
|
|
|
| `image_processing_config` | object | 否 | 图片属性观察配置:`model_id` / `image_attrs_enabled` / `image_actions`(`{ ocr: { on: [...], on_unobserved: bool } }`) |
|
2026-08-06 10:22:10 +00:00
|
|
|
|
| `storage_provider_config` | object | 否 | 存储配置 |
|
|
|
|
|
|
| `vector_store_id` | string | 否 | 向量库绑定(非法返回 code 2200/2201) |
|
|
|
|
|
|
| `faq_config` / `wiki_config` / `extract_config` / `indexing_strategy` | object | 否 | 类型相关配置 |
|
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
2026-09-24 03:26:34 +00:00
|
|
|
|
| `summary_model_id` | string | 否 | 摘要模型,也是自动标签和 AI 描述的默认模型 |
|
|
|
|
|
|
| `auto_tag_config` / `profile_config` | object | 否 | 自动标签、AI 知识库描述(仅 document 类型,见下文) |
|
2026-08-06 10:22:10 +00:00
|
|
|
|
|
|
|
|
|
|
响应:201 `{"success":true,"data":{KnowledgeBase}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge-bases -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"name":"产品文档","type":"document"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
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
2026-09-24 03:26:34 +00:00
|
|
|
|
### 自动标签与 AI 描述配置
|
2026-09-08 02:54:41 +00:00
|
|
|
|
|
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
2026-09-24 03:26:34 +00:00
|
|
|
|
创建知识库时 `auto_tag_config`、`profile_config` 位于顶层;更新时放在 `config.auto_tag_config`、`config.profile_config`。两者仅 document 知识库支持,默认 enabled=false。
|
2026-09-08 02:54:41 +00:00
|
|
|
|
|
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
2026-09-24 03:26:34 +00:00
|
|
|
|
`auto_tag_config`(自动标签):
|
2026-09-08 02:54:41 +00:00
|
|
|
|
|
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
2026-09-24 03:26:34 +00:00
|
|
|
|
| 字段 | 类型 | 默认值 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `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` 立即生成。更新示例:
|
2026-09-08 02:54:41 +00:00
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X PUT "$BASE/api/v1/knowledge-bases/kb-1" \
|
|
|
|
|
|
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
|
|
|
|
|
|
-d '{"name":"产品文档","config":{"auto_tag_config":{"enabled":true,"max_tags":3,"skip_if_tagged":true}}}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-08-06 10:22:10 +00:00
|
|
|
|
### GET /api/v1/knowledge-bases
|
|
|
|
|
|
|
|
|
|
|
|
用途:知识库列表。权限:Viewer+;API key `retrieve`/full。
|
|
|
|
|
|
|
|
|
|
|
|
| 查询参数 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `agent_id` | string | 否 | 过滤某共享 Agent 可见的 KB |
|
|
|
|
|
|
| `agent_source_tenant_id` | uint64 | 否 | 同名 Agent 被多个空间共享时,指定来源空间;取值会与共享关系校验,非法值直接 400 |
|
|
|
|
|
|
| `creator` | string | 否 | `mine` / `others` |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":[KnowledgeBase],"total","page","page_size"}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/knowledge-bases -H "X-API-Key: $API_KEY"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/knowledge-bases/:id
|
|
|
|
|
|
|
|
|
|
|
|
用途:知识库详情(共享 KB 携带 `my_permission`)。权限:Viewer+,KB read。查询参数:`agent_id`(可选)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{KnowledgeBase}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/knowledge-bases/kb-1 -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### PUT /api/v1/knowledge-bases/:id
|
|
|
|
|
|
|
|
|
|
|
|
用途:更新知识库。权限:创建者 OR Admin+,KB write;API key `manage_kbs`/full。
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `name` | string | 是(`binding:"required"`) | 名称 |
|
|
|
|
|
|
| `description` | string | 否 | 描述 |
|
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
2026-09-24 03:26:34 +00:00
|
|
|
|
| `config` | object | 否 | 局部配置更新:`chunking_config`、`image_processing_config`、`faq_config`、`wiki_config`、`auto_tag_config`、`profile_config`、`indexing_strategy` |
|
2026-08-06 10:22:10 +00:00
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{KnowledgeBase}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X PUT $BASE/api/v1/knowledge-bases/kb-1 -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"name":"产品文档 v2"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### DELETE /api/v1/knowledge-bases/:id
|
|
|
|
|
|
|
|
|
|
|
|
用途:删除知识库(锁定为属主空间 + Admin;共享 editor 不可删)。权限:创建者 OR Admin+,KB write;API key `manage_kbs`/full。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"message":"Knowledge base deleted successfully"}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X DELETE $BASE/api/v1/knowledge-bases/kb-1 -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### PUT /api/v1/knowledge-bases/:id/pin
|
|
|
|
|
|
|
|
|
|
|
|
用途:置顶/取消置顶(按用户维度存储)。权限:Viewer+,KB read。无请求体。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{KnowledgeBase(is_pinned 已切换)}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X PUT $BASE/api/v1/knowledge-bases/kb-1/pin -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/knowledge-bases/:id/hybrid-search(兼容 GET)
|
|
|
|
|
|
|
feat(retrieval): unify rerank across search APIs and expose diagnostics (#3675)
* feat(retrieval): unify rerank across search APIs and expose diagnostics
The two retrieval APIs each missed half of the job: hybrid-search could
tune recall but never reranked, knowledge-search always reranked with the
tenant config and exposed no recall parameters. Rerank itself lived in
four places with drifting thresholds, passages and composite scores.
- internal/reranking: one rerank stage (passage = title + cleaned body +
captions/OCR + generated questions, threshold with degradation and
top-1 fallback, composite score, MMR) used by the chat pipeline, the
agent search_knowledge tool and both APIs.
- hybrid-search: optional `rerank` object; absent keeps the old behavior.
- knowledge-search: vector/keyword thresholds, match_count, recall-path
switches and a `rerank` object that can override or disable rerank.
- Rerank model resolution: request > tenant RetrievalConfig > first
rerank model; an unknown requested model is a 400. Load or call
failures degrade to retrieval order instead of failing the search.
- Responses carry meta.rerank (outcome, model, thresholds, top score) so
an empty result explains itself (#2391).
- Go SDK and website-docs updated, including a "which API" section.
Refs #2976
* docs(retrieval): lead with which search API to use and when
knowledge-search is the default for callers; hybrid-search is the
low-level recall interface. Add a scenario table so the choice does not
hinge on reading the whole capability comparison.
2026-09-24 12:41:49 +00:00
|
|
|
|
用途:KB 内的底层召回(向量+关键词),默认不做 rerank,返回召回分;可选开启 rerank。适合评测召回、传预计算向量等需要控制原始召回的场景,一般的检索请用 [`knowledge-search`](./02-api-chat.md),选择方法见[检索接口怎么选](./01-api-overview.md#retrieval-api)。权限:Viewer+,KB read;API key `retrieve`/full。GET 携带 JSON body 仅为向后兼容(#1727),推荐 POST。
|
2026-08-06 10:22:10 +00:00
|
|
|
|
|
2026-08-26 09:31:05 +00:00
|
|
|
|
查询参数:`resource_urls=handle|public`(`public` 把结果 `content` / `image_info` 里的 `resource://` 换成可加载直链,详见 [API 总览](./01-api-overview.md))。
|
|
|
|
|
|
|
2026-08-06 10:22:10 +00:00
|
|
|
|
请求体(`types.SearchParams`):
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
feat(retrieval): unify rerank across search APIs and expose diagnostics (#3675)
* feat(retrieval): unify rerank across search APIs and expose diagnostics
The two retrieval APIs each missed half of the job: hybrid-search could
tune recall but never reranked, knowledge-search always reranked with the
tenant config and exposed no recall parameters. Rerank itself lived in
four places with drifting thresholds, passages and composite scores.
- internal/reranking: one rerank stage (passage = title + cleaned body +
captions/OCR + generated questions, threshold with degradation and
top-1 fallback, composite score, MMR) used by the chat pipeline, the
agent search_knowledge tool and both APIs.
- hybrid-search: optional `rerank` object; absent keeps the old behavior.
- knowledge-search: vector/keyword thresholds, match_count, recall-path
switches and a `rerank` object that can override or disable rerank.
- Rerank model resolution: request > tenant RetrievalConfig > first
rerank model; an unknown requested model is a 400. Load or call
failures degrade to retrieval order instead of failing the search.
- Responses carry meta.rerank (outcome, model, thresholds, top score) so
an empty result explains itself (#2391).
- Go SDK and website-docs updated, including a "which API" section.
Refs #2976
* docs(retrieval): lead with which search API to use and when
knowledge-search is the default for callers; hybrid-search is the
low-level recall interface. Add a scenario table so the choice does not
hinge on reading the whole capability comparison.
2026-09-24 12:41:49 +00:00
|
|
|
|
| `query_text` | string | 条件必填 | 查询文本(除非提供 `query_embedding`;开启 rerank 时必填) |
|
2026-08-06 10:22:10 +00:00
|
|
|
|
| `query_embedding` | []float32 | 否 | 预计算向量 |
|
|
|
|
|
|
| `vector_threshold` / `keyword_threshold` | float64 | 否 | 匹配阈值 |
|
feat(retrieval): unify rerank across search APIs and expose diagnostics (#3675)
* feat(retrieval): unify rerank across search APIs and expose diagnostics
The two retrieval APIs each missed half of the job: hybrid-search could
tune recall but never reranked, knowledge-search always reranked with the
tenant config and exposed no recall parameters. Rerank itself lived in
four places with drifting thresholds, passages and composite scores.
- internal/reranking: one rerank stage (passage = title + cleaned body +
captions/OCR + generated questions, threshold with degradation and
top-1 fallback, composite score, MMR) used by the chat pipeline, the
agent search_knowledge tool and both APIs.
- hybrid-search: optional `rerank` object; absent keeps the old behavior.
- knowledge-search: vector/keyword thresholds, match_count, recall-path
switches and a `rerank` object that can override or disable rerank.
- Rerank model resolution: request > tenant RetrievalConfig > first
rerank model; an unknown requested model is a 400. Load or call
failures degrade to retrieval order instead of failing the search.
- Responses carry meta.rerank (outcome, model, thresholds, top score) so
an empty result explains itself (#2391).
- Go SDK and website-docs updated, including a "which API" section.
Refs #2976
* docs(retrieval): lead with which search API to use and when
knowledge-search is the default for callers; hybrid-search is the
low-level recall interface. Add a scenario table so the choice does not
hinge on reading the whole capability comparison.
2026-09-24 12:41:49 +00:00
|
|
|
|
| `match_count` | int | 否 | 返回条数上限(默认 50) |
|
2026-08-06 10:22:10 +00:00
|
|
|
|
| `disable_keywords_match` / `disable_vector_match` | bool | 否 | 关闭某一路召回 |
|
feat(retrieval): unify rerank across search APIs and expose diagnostics (#3675)
* feat(retrieval): unify rerank across search APIs and expose diagnostics
The two retrieval APIs each missed half of the job: hybrid-search could
tune recall but never reranked, knowledge-search always reranked with the
tenant config and exposed no recall parameters. Rerank itself lived in
four places with drifting thresholds, passages and composite scores.
- internal/reranking: one rerank stage (passage = title + cleaned body +
captions/OCR + generated questions, threshold with degradation and
top-1 fallback, composite score, MMR) used by the chat pipeline, the
agent search_knowledge tool and both APIs.
- hybrid-search: optional `rerank` object; absent keeps the old behavior.
- knowledge-search: vector/keyword thresholds, match_count, recall-path
switches and a `rerank` object that can override or disable rerank.
- Rerank model resolution: request > tenant RetrievalConfig > first
rerank model; an unknown requested model is a 400. Load or call
failures degrade to retrieval order instead of failing the search.
- Responses carry meta.rerank (outcome, model, thresholds, top score) so
an empty result explains itself (#2391).
- Go SDK and website-docs updated, including a "which API" section.
Refs #2976
* docs(retrieval): lead with which search API to use and when
knowledge-search is the default for callers; hybrid-search is the
low-level recall interface. Add a scenario table so the choice does not
hinge on reading the whole capability comparison.
2026-09-24 12:41:49 +00:00
|
|
|
|
| `knowledge_base_ids` | []string | 否 | 一次检索多个知识库,路径上的 `:id` 必须在其中;这些知识库的 embedding 模型必须相同,否则返回 400 |
|
2026-08-06 10:22:10 +00:00
|
|
|
|
| `knowledge_ids` | []string | 否 | 限定知识条目 |
|
|
|
|
|
|
| `tag_ids` | []string | 否 | 标签过滤(OR) |
|
|
|
|
|
|
| `only_recommended` | bool | 否 | FAQ 仅推荐条目 |
|
|
|
|
|
|
| `skip_context_enrichment` | bool | 否 | 跳过父块/上下文补齐 |
|
feat(retrieval): unify rerank across search APIs and expose diagnostics (#3675)
* feat(retrieval): unify rerank across search APIs and expose diagnostics
The two retrieval APIs each missed half of the job: hybrid-search could
tune recall but never reranked, knowledge-search always reranked with the
tenant config and exposed no recall parameters. Rerank itself lived in
four places with drifting thresholds, passages and composite scores.
- internal/reranking: one rerank stage (passage = title + cleaned body +
captions/OCR + generated questions, threshold with degradation and
top-1 fallback, composite score, MMR) used by the chat pipeline, the
agent search_knowledge tool and both APIs.
- hybrid-search: optional `rerank` object; absent keeps the old behavior.
- knowledge-search: vector/keyword thresholds, match_count, recall-path
switches and a `rerank` object that can override or disable rerank.
- Rerank model resolution: request > tenant RetrievalConfig > first
rerank model; an unknown requested model is a 400. Load or call
failures degrade to retrieval order instead of failing the search.
- Responses carry meta.rerank (outcome, model, thresholds, top score) so
an empty result explains itself (#2391).
- Go SDK and website-docs updated, including a "which API" section.
Refs #2976
* docs(retrieval): lead with which search API to use and when
knowledge-search is the default for callers; hybrid-search is the
low-level recall interface. Add a scenario table so the choice does not
hinge on reading the whole capability comparison.
2026-09-24 12:41:49 +00:00
|
|
|
|
| `rerank` | object | 否 | 传入即开启 rerank(`{}` 使用空间配置的模型),字段见 [rerank 对象](./01-api-overview.md#retrieval-api) |
|
2026-08-06 10:22:10 +00:00
|
|
|
|
|
feat(retrieval): unify rerank across search APIs and expose diagnostics (#3675)
* feat(retrieval): unify rerank across search APIs and expose diagnostics
The two retrieval APIs each missed half of the job: hybrid-search could
tune recall but never reranked, knowledge-search always reranked with the
tenant config and exposed no recall parameters. Rerank itself lived in
four places with drifting thresholds, passages and composite scores.
- internal/reranking: one rerank stage (passage = title + cleaned body +
captions/OCR + generated questions, threshold with degradation and
top-1 fallback, composite score, MMR) used by the chat pipeline, the
agent search_knowledge tool and both APIs.
- hybrid-search: optional `rerank` object; absent keeps the old behavior.
- knowledge-search: vector/keyword thresholds, match_count, recall-path
switches and a `rerank` object that can override or disable rerank.
- Rerank model resolution: request > tenant RetrievalConfig > first
rerank model; an unknown requested model is a 400. Load or call
failures degrade to retrieval order instead of failing the search.
- Responses carry meta.rerank (outcome, model, thresholds, top score) so
an empty result explains itself (#2391).
- Go SDK and website-docs updated, including a "which API" section.
Refs #2976
* docs(retrieval): lead with which search API to use and when
knowledge-search is the default for callers; hybrid-search is the
low-level recall interface. Add a scenario table so the choice does not
hinge on reading the whole capability comparison.
2026-09-24 12:41:49 +00:00
|
|
|
|
响应:200 `{"success":true,"data":[SearchResult]}`;带 `rerank` 时多一个 `meta.rerank`(见 [meta.rerank 诊断](./01-api-overview.md#retrieval-api))。
|
2026-08-06 10:22:10 +00:00
|
|
|
|
|
|
|
|
|
|
```bash
|
2026-08-26 09:31:05 +00:00
|
|
|
|
curl -X POST "$BASE/api/v1/knowledge-bases/kb-1/hybrid-search?resource_urls=public" -H "X-API-Key: $API_KEY" \
|
2026-08-06 10:22:10 +00:00
|
|
|
|
-H 'Content-Type: application/json' -d '{"query_text":"退款流程","match_count":5}'
|
feat(retrieval): unify rerank across search APIs and expose diagnostics (#3675)
* feat(retrieval): unify rerank across search APIs and expose diagnostics
The two retrieval APIs each missed half of the job: hybrid-search could
tune recall but never reranked, knowledge-search always reranked with the
tenant config and exposed no recall parameters. Rerank itself lived in
four places with drifting thresholds, passages and composite scores.
- internal/reranking: one rerank stage (passage = title + cleaned body +
captions/OCR + generated questions, threshold with degradation and
top-1 fallback, composite score, MMR) used by the chat pipeline, the
agent search_knowledge tool and both APIs.
- hybrid-search: optional `rerank` object; absent keeps the old behavior.
- knowledge-search: vector/keyword thresholds, match_count, recall-path
switches and a `rerank` object that can override or disable rerank.
- Rerank model resolution: request > tenant RetrievalConfig > first
rerank model; an unknown requested model is a 400. Load or call
failures degrade to retrieval order instead of failing the search.
- Responses carry meta.rerank (outcome, model, thresholds, top score) so
an empty result explains itself (#2391).
- Go SDK and website-docs updated, including a "which API" section.
Refs #2976
* docs(retrieval): lead with which search API to use and when
knowledge-search is the default for callers; hybrid-search is the
low-level recall interface. Add a scenario table so the choice does not
hinge on reading the whole capability comparison.
2026-09-24 12:41:49 +00:00
|
|
|
|
|
|
|
|
|
|
# 固定召回参数,再用指定模型 rerank
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge-bases/kb-1/hybrid-search -H "X-API-Key: $API_KEY" \
|
|
|
|
|
|
-H 'Content-Type: application/json' \
|
|
|
|
|
|
-d '{"query_text":"退款流程","vector_threshold":0.3,"match_count":5,"rerank":{"model_id":"rr-1","threshold":0.2}}'
|
2026-08-06 10:22:10 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/knowledge-bases/copy
|
|
|
|
|
|
|
|
|
|
|
|
用途:跨 KB 拷贝内容(异步任务)。权限:Contributor+;API key `manage_kbs`/full(源/目标 KB 白名单在 handler 校验)。
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `source_id` | string | 是(`binding:"required"`) | 源 KB |
|
|
|
|
|
|
| `target_id` | string | 否 | 目标 KB(为空则自动创建) |
|
|
|
|
|
|
| `task_id` | string | 否 | 自定义任务 ID |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{"task_id","source_id","target_id","message"}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge-bases/copy -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"source_id":"kb-1"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/knowledge-bases/:id/duplicate
|
|
|
|
|
|
|
|
|
|
|
|
用途:创建 KB 副本(仅复制设置,不复制内容/索引/分享)。权限:Contributor+,源 KB read;API key `manage_kbs`/full。无请求体。
|
|
|
|
|
|
|
|
|
|
|
|
响应:201 `{"success":true,"data":{"source_id","target_id","message","knowledge_base":{...}}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge-bases/kb-1/duplicate -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
feat(knowledge): derive knowledge base descriptions from document profiles (#3370)
* feat(knowledge): derive knowledge base descriptions from document profiles
Knowledge bases only had a hand-written description, which most users
leave empty, so agents bound to several knowledge bases had nothing to
route on and searched all of them. This adds a generated description
that is derived from per-document data instead of maintained by a model.
Document profile: the summary call now returns JSON with a 2-3 sentence
summary plus a gist, 3-5 topic keywords, a document type and one
typical question (knowledges.profile). Input is capped at 8k chars and
output at 1024 tokens; plain-text replies from custom templates still
work and simply carry no profile. The summary chunk embeds the gist and
short summary.
Knowledge base aggregate: a database-only fold over those rows (counts
per file type, tag, normalized topic and doc type; stratified samples of
titles and questions; a hash of the inputs). Deleting, moving or
re-parsing a document changes nothing but the rows, so the next rebuild
is exact without any model judgement.
Description text: one small model call over the aggregate yields a
gist, merged topics and typical questions (knowledge_bases.
generated_profile). The call is skipped when the aggregate hash is
unchanged; failures keep the previous text and record the error; an
empty knowledge base clears it. The manual description is never
touched, and the agent runtime context renders both so the model can
pass knowledge_base_ids instead of fanning out.
Refreshes are requested from summary task exit, post-process completion,
deletion, cross-KB moves and enabling the option, debounced per
knowledge base in 30 s windows via kb:profile on the summary queue.
POST /knowledge-bases/:id/profile/generate regenerates synchronously.
profile_config (enabled, model_id, custom_instructions) opts a document
knowledge base in; the settings dialog shows the generated card with
regenerate and adopt-as-description actions in five locales. Search
results now log hits per chunk type so the value of indexing summary
chunks can be measured.
Migrations 000101 (PostgreSQL) and 000021 (SQLite) add the columns; the
SQLite schema test expects the new version and columns.
* fix(knowledge): keep generated descriptions out of duplicates and refresh clones
DuplicateKnowledgeBase copies the source row through JSON, which carried
generated_profile onto a knowledge base that has no documents yet, so
an empty duplicate advertised the source's topics. The duplicate now
starts without a generated description and keeps profile_config so it
derives its own once documents arrive.
CopyKnowledgeBase builds the target field by field and skipped
profile_config, and the clone task never asked for a description after
copying the documents, so a clone stayed undescribed until its next
upload. The target now carries a copy of profile_config and both clone
paths request a refresh on completion.
* fix(knowledge): refresh the loaded clone target and carry document profiles
ProcessKBClone requested the description refresh with the reservation
stub it builds before CopyKnowledgeBase runs. For the main create path
that stub has neither a type nor profile_config, so the refresh helper
rejected it and nothing was enqueued. The refresh now uses the loaded
target returned by CopyKnowledgeBase.
cloneKnowledge copied the summary text but not the structured profile,
so even a scheduled refresh would have aggregated titles without topics
until every clone was re-summarized. Cloned documents now carry an
independent copy of the profile.
2026-09-17 14:21:55 +00:00
|
|
|
|
### POST /api/v1/knowledge-bases/:id/profile/generate
|
|
|
|
|
|
|
|
|
|
|
|
用途:立即重新生成知识库的 AI 描述(`generated_profile`),同步执行一次文档画像聚合和一次小模型调用,不修改手写 `description`。权限:与更新知识库相同(创建者/Admin 且 KB write);API key `manage_kbs`/full。无请求体。仅 document 类型;未配置模型返回 400。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{"gist","topics":[...],"typical_questions":[...],"stats":{"document_count",...},"status":"ready","model_id","generated_at"}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge-bases/kb-1/profile/generate -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-08-06 10:22:10 +00:00
|
|
|
|
### GET /api/v1/knowledge-bases/copy/progress/:task_id
|
|
|
|
|
|
|
|
|
|
|
|
用途:查询拷贝进度(任务按空间隔离)。权限:Viewer+;API key `retrieve`/`manage_kbs`/full。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{status,progress,message,...}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/knowledge-bases/copy/progress/task-1 -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/knowledge-bases/:id/move-targets
|
|
|
|
|
|
|
|
|
|
|
|
用途:列出可作为移动目标的 KB(同类型/同 embedding)。权限:Viewer+,KB read。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":[KnowledgeBase]}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/knowledge-bases/kb-1/move-targets -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/knowledge-bases/:id/files
|
|
|
|
|
|
|
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
2026-09-24 03:26:34 +00:00
|
|
|
|
用途:KB 范围文件代理(渲染共享 KB 内容中的图片;上下文 tenant 已被重写为 KB 属主)。权限:Viewer+,KB read;KB 受限 key 拒绝,全空间 `retrieve`/full key 放行。注册于 `serveKBScopedFiles`(`internal/router/files.go`)。
|
2026-08-06 10:22:10 +00:00
|
|
|
|
|
|
|
|
|
|
| 查询参数 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `file_path` | string | 是 | `provider://...` 存储路径(禁止 `..`) |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 文件流(`Content-Type` 按扩展名推断;`Cache-Control: private`)。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl "$BASE/api/v1/knowledge-bases/kb-1/files?file_path=local://1/exports/chart.png" \
|
|
|
|
|
|
-H "Authorization: Bearer $TOKEN" -o chart.png
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 知识(KB 内容,/api/v1/knowledge-bases/:id/knowledge 与 /api/v1/knowledge)
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/knowledge-bases/:id/knowledge/file
|
|
|
|
|
|
|
|
|
|
|
|
用途:上传文件创建知识。权限:KB 创建者 OR Admin+,KB write;API key `ingest`/full。Handler: `internal/handler/knowledge.go`
|
|
|
|
|
|
|
|
|
|
|
|
multipart/form-data 字段:
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `file` | file | 是 | 上传文件 |
|
|
|
|
|
|
| `fileName` | string | 否 | 覆盖显示名 |
|
|
|
|
|
|
| `metadata` | JSON 字符串 | 否 | 自定义元数据 |
|
|
|
|
|
|
| `enable_multimodel` | bool | 否 | 多模态处理开关 |
|
|
|
|
|
|
| `tag_ids` | string | 否 | 逗号分隔标签 ID |
|
|
|
|
|
|
| `channel` | string | 否 | 摄取渠道 |
|
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
2026-09-24 03:26:34 +00:00
|
|
|
|
| `process_config` | JSON 字符串 | 否 | 解析配置覆盖(KnowledgeProcessOverrides),见下表 |
|
2026-08-06 10:22:10 +00:00
|
|
|
|
|
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
2026-09-24 03:26:34 +00:00
|
|
|
|
`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。正在删除或解析失败的同名文件不计为重复。
|
2026-08-06 10:22:10 +00:00
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge-bases/kb-1/knowledge/file \
|
|
|
|
|
|
-H "X-API-Key: $API_KEY" -F 'file=@./manual.pdf' -F 'enable_multimodel=true'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/knowledge-bases/:id/knowledge/url
|
|
|
|
|
|
|
|
|
|
|
|
用途:从 URL 抓取创建知识。权限/API key 同上。
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `url` | string | 是(`binding:"required"`) | 抓取地址 |
|
|
|
|
|
|
| `file_name` / `file_type` / `title` | string | 否 | 覆盖信息 |
|
|
|
|
|
|
| `enable_multimodel` | *bool | 否 | 多模态开关 |
|
|
|
|
|
|
| `tag_ids` | []string | 否 | 标签 |
|
|
|
|
|
|
| `channel` | string | 否 | 渠道 |
|
|
|
|
|
|
| `process_config` | object | 否 | 解析覆盖 |
|
|
|
|
|
|
|
|
|
|
|
|
响应:201 `{"success":true,"data":{Knowledge}}`;重复 URL 返回 409。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge-bases/kb-1/knowledge/url -H "X-API-Key: $API_KEY" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"url":"https://example.com/doc"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/knowledge-bases/:id/knowledge/manual
|
|
|
|
|
|
|
|
|
|
|
|
用途:创建手工(Markdown)知识。权限/API key 同上。
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `title` | string | 否 | 标题 |
|
|
|
|
|
|
| `content` | string | 否 | Markdown 内容 |
|
|
|
|
|
|
| `status` | string | 否 | `draft` / `publish` |
|
|
|
|
|
|
| `tag_ids` | []string | 否 | 标签 |
|
|
|
|
|
|
| `channel` | string | 否 | 渠道 |
|
|
|
|
|
|
| `process_config` | object | 否 | 解析覆盖 |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{Knowledge}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge-bases/kb-1/knowledge/manual -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"title":"FAQ 汇总","content":"# 内容","status":"publish"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/knowledge-bases/:id/knowledge
|
|
|
|
|
|
|
|
|
|
|
|
用途:KB 下知识列表。权限:Viewer+,KB read;API key `retrieve`/full。
|
|
|
|
|
|
|
|
|
|
|
|
| 查询参数 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `page` / `page_size` | int | 否 | 分页(默认 1/20) |
|
|
|
|
|
|
| `tag_ids` | string | 否 | 逗号分隔标签(OR) |
|
|
|
|
|
|
| `keyword` | string | 否 | 关键字 |
|
|
|
|
|
|
| `file_type` | string | 否 | 文件类型过滤 |
|
|
|
|
|
|
| `parse_status` | string | 否 | `pending/processing/completed/failed` |
|
|
|
|
|
|
| `source` | string | 否 | 渠道或 `manual`/`url` |
|
|
|
|
|
|
| `start_time` / `end_time` | string | 否 | RFC3339,按 `updated_at` 过滤 |
|
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
2026-09-24 03:26:34 +00:00
|
|
|
|
| `folder_path` | string | 否 | 按文件夹筛选;空字符串表示知识库根目录,不传则不按文件夹过滤 |
|
|
|
|
|
|
| `folder_recursive` | bool | 否 | 与 `folder_path` 配合,为 `true` 时包含子文件夹中的文档 |
|
2026-09-23 04:00:21 +00:00
|
|
|
|
| `sort_by` | string | 否 | 排序字段:`updated_at`、`created_at` 或 `file_name`;默认 `created_at` |
|
|
|
|
|
|
| `sort_order` | string | 否 | 排序方向:`asc` 或 `desc`;默认 `desc` |
|
|
|
|
|
|
|
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
2026-09-24 03:26:34 +00:00
|
|
|
|
未传排序参数时按 `created_at desc` 排序,取值不在上述范围内返回 400。使用 `updated_at` 时,重新解析、编辑或状态变化会影响顺序;使用 `file_name` 时按展示文件名忽略大小写排序,文件名为空会依次回退到标题和来源。相同排序值按知识 ID 排序,保证翻页结果稳定。
|
2026-08-06 10:22:10 +00:00
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":[Knowledge],"total","page","page_size"}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl "$BASE/api/v1/knowledge-bases/kb-1/knowledge?page=1&parse_status=completed" -H "X-API-Key: $API_KEY"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
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
2026-09-24 03:26:34 +00:00
|
|
|
|
### 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
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-08-06 10:22:10 +00:00
|
|
|
|
### GET /api/v1/knowledge-bases/:id/knowledge/folders
|
|
|
|
|
|
|
2026-09-08 02:54:41 +00:00
|
|
|
|
用途:获取知识库的文件夹目录树。整目录上传时目录结构会被保留(migration `000079` 起存在 `knowledges.folder_path` 列,历史 `file_name` 中的路径已回填到该字段)。权限:Viewer+ + KBAccessRead。
|
2026-08-06 10:22:10 +00:00
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":[{FolderNode}]}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/knowledge-bases/kb-1/knowledge/folders -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### PUT /api/v1/knowledge-bases/:id/knowledge/folders
|
|
|
|
|
|
|
|
|
|
|
|
用途:重命名或移动文件夹,连同其所有子目录一起改路径。目标路径已存在时两个文件夹合并;不允许移动到自己的子目录下。权限:KB owner 或 Admin+ + KBAccessWrite。
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `from` | string | 是 | 原路径 |
|
|
|
|
|
|
| `to` | string | 是 | 新路径 |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X PUT $BASE/api/v1/knowledge-bases/kb-1/knowledge/folders -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"from":"设计文档/旧版","to":"归档/设计文档"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### DELETE /api/v1/knowledge-bases/:id/knowledge
|
|
|
|
|
|
|
|
|
|
|
|
用途:清空 KB 全部内容(破坏性)。权限:Admin+,KB write;API key 仅 full-access。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"message":"Knowledge base contents clear task submitted","data":{"deleted_count":N}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X DELETE $BASE/api/v1/knowledge-bases/kb-1/knowledge -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/knowledge/batch
|
|
|
|
|
|
|
|
|
|
|
|
用途:按 ID 批量获取知识(跨 KB,handler 自行校验访问)。权限:Viewer+;API key `retrieve`/full。
|
|
|
|
|
|
|
|
|
|
|
|
| 查询参数 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `ids` | []string | 是 | 知识 ID(可重复传参或逗号分隔) |
|
|
|
|
|
|
| `kb_id` | string | 否 | 限定 KB |
|
|
|
|
|
|
| `agent_id` | string | 否 | 共享 Agent 范围 |
|
|
|
|
|
|
| `agent_source_tenant_id` | uint64 | 否 | 共享 Agent 的来源空间选择器,与共享关系校验 |
|
|
|
|
|
|
|
feat(knowledge): flag documents that stop making progress (#3557)
* feat(knowledge): flag documents that stop making progress
A document stuck in processing looked the same as one still working: a
spinner that polled forever, no hint of where it stopped, and, hours
later, a generic housekeeping failure.
- The batch and spans endpoints return last_activity_at for in-flight
rows: the later of updated_at and the newest span write. updated_at
only moves at stage transitions; span writes keep moving while a long
stage still works.
- After 20 minutes with no progress, the list and card views show
"may be stuck" with a tooltip. The timeline shows the stage it
stopped at and a stop-parsing button, plus a "last progress" stat.
Both pollers back off to 15s while everything in flight is stalled.
- When housekeeping fails a row, the error names the stalled stage and
the time of the last progress. It closes the row's open spans with
TASK_STALLED (the running stage fails, the rest are cancelled), so
the timeline shows where the run stopped instead of a spinner.
* fix(knowledge): locate stalls in finalizing and tell backlog from stuck
- Housekeeping reads the stall site from the latest attempt. It takes
the running stages, or, when none runs (post-process closes its stage
once enrichment is fanned out), the innermost running spans, mapped
back to their stage. Those spans fail with TASK_STALLED and are named
in the message; every stalled stage is listed in pipeline order. The
other open spans are cancelled. Every closed span gets a duration, and
the message leaves out the time when the heartbeat query failed.
- The spans tree prefers a TASK_STALLED failure for last_error over a
later subtask failure. current_stage falls back to the stage owning a
running subspan.
- Batch and spans responses flag rows quiet past the stall hint whose
work is still queued (waiting_in_queue), using the sweep's own probes.
At most 20 rows are probed per request, cached for a minute. The UI
shows these as queued, with no stop button in the banner.
* fix(knowledge): answer stall verdicts from one shared queue scan
- Probing a quiet document for a backlog rescanned the whole queue once
per document. When the document was absent, which is exactly the
stuck case, the scan ran to the end, and it read a Redis error as
"nothing queued". QueuedKnowledgeIDs now collects every referenced
knowledge ID in one pass and returns list errors. HousekeepingService
keeps that snapshot for a minute, shared across requests and
single-flight. A failed scan is not cached.
- With the per-request cap of 20 gone, every quiet row on a page gets a
verdict. The response carries it as stall_state (queued or stalled),
replacing waiting_in_queue. The UI marks a row as stuck only on a
"stalled" verdict. A row with no verdict, because the probe failed,
shows as ordinary processing instead of inviting a stop.
2026-09-22 13:34:08 +00:00
|
|
|
|
响应:200 `{"success":true,"data":[Knowledge]}`。处于 `pending`/`processing`/`finalizing` 的知识额外带 `last_activity_at`(RFC3339),取行的 `updated_at` 与该知识所有 span 最近一次写入中较晚的一个。超过 20 分钟无进展的知识再带 `stall_state`:`queued` 表示仍有任务在 asynq 队列或 Wiki 持久队列中等待(积压),`stalled` 表示已无任务可推进它(疑似卡住)。判定与 housekeeping 的积压判定相同;队列侧是一次全队列扫描,所有请求共享、缓存 60 秒。探测失败时不返回 `stall_state`,前端按普通解析中显示。
|
2026-08-06 10:22:10 +00:00
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl "$BASE/api/v1/knowledge/batch?ids=k-1&ids=k-2" -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/knowledge/:id
|
|
|
|
|
|
|
|
|
|
|
|
用途:知识详情。权限:Viewer+,父 KB read。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{Knowledge}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/knowledge/k-1 -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/knowledge/:id/stages 与 GET /api/v1/knowledge/:id/spans
|
|
|
|
|
|
|
|
|
|
|
|
用途:解析阶段/trace(两条路径同一 handler `GetKnowledgeSpans`)。权限:Viewer+,父 KB read。查询参数:`attempt`(int,0=最新一次)。
|
|
|
|
|
|
|
feat(knowledge): flag documents that stop making progress (#3557)
* feat(knowledge): flag documents that stop making progress
A document stuck in processing looked the same as one still working: a
spinner that polled forever, no hint of where it stopped, and, hours
later, a generic housekeeping failure.
- The batch and spans endpoints return last_activity_at for in-flight
rows: the later of updated_at and the newest span write. updated_at
only moves at stage transitions; span writes keep moving while a long
stage still works.
- After 20 minutes with no progress, the list and card views show
"may be stuck" with a tooltip. The timeline shows the stage it
stopped at and a stop-parsing button, plus a "last progress" stat.
Both pollers back off to 15s while everything in flight is stalled.
- When housekeeping fails a row, the error names the stalled stage and
the time of the last progress. It closes the row's open spans with
TASK_STALLED (the running stage fails, the rest are cancelled), so
the timeline shows where the run stopped instead of a spinner.
* fix(knowledge): locate stalls in finalizing and tell backlog from stuck
- Housekeeping reads the stall site from the latest attempt. It takes
the running stages, or, when none runs (post-process closes its stage
once enrichment is fanned out), the innermost running spans, mapped
back to their stage. Those spans fail with TASK_STALLED and are named
in the message; every stalled stage is listed in pipeline order. The
other open spans are cancelled. Every closed span gets a duration, and
the message leaves out the time when the heartbeat query failed.
- The spans tree prefers a TASK_STALLED failure for last_error over a
later subtask failure. current_stage falls back to the stage owning a
running subspan.
- Batch and spans responses flag rows quiet past the stall hint whose
work is still queued (waiting_in_queue), using the sweep's own probes.
At most 20 rows are probed per request, cached for a minute. The UI
shows these as queued, with no stop button in the banner.
* fix(knowledge): answer stall verdicts from one shared queue scan
- Probing a quiet document for a backlog rescanned the whole queue once
per document. When the document was absent, which is exactly the
stuck case, the scan ran to the end, and it read a Redis error as
"nothing queued". QueuedKnowledgeIDs now collects every referenced
knowledge ID in one pass and returns list errors. HousekeepingService
keeps that snapshot for a minute, shared across requests and
single-flight. A failed scan is not cached.
- With the per-request cap of 20 gone, every quiet row on a page gets a
verdict. The response carries it as stall_state (queued or stalled),
replacing waiting_in_queue. The UI marks a row as stuck only on a
"stalled" verdict. A row with no verdict, because the probe failed,
shows as ordinary processing instead of inviting a stop.
2026-09-22 13:34:08 +00:00
|
|
|
|
响应:200 `{"success":true,"data":{"knowledge_id","attempt","latest_attempt","parse_status","current_stage","last_activity_at","stall_state","trace":{...},"last_error":{...}}}`
|
|
|
|
|
|
|
|
|
|
|
|
`last_activity_at` 只在解析进行中返回,取行的 `updated_at` 与本次 attempt 各 span 最近一次写入中较晚的一个;`stall_state` 含义同上。`current_stage` 是仍在运行的阶段;没有运行中的阶段时(如 `finalizing`,后处理阶段已关闭、摘要等子任务仍在跑),取仍在运行的子 span 所属的阶段。被 housekeeping 判定卡死的知识,其卡住位置的 span 会以 `TASK_STALLED` 标为失败,`last_error` 优先指向它。
|
2026-08-06 10:22:10 +00:00
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/knowledge/k-1/spans -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### DELETE /api/v1/knowledge/:id
|
|
|
|
|
|
|
|
|
|
|
|
用途:删除知识(异步)。权限:KB 创建者 OR Admin+,KB write;API key `ingest`/full。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"message":"Delete task submitted","data":{"task_id"}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X DELETE $BASE/api/v1/knowledge/k-1 -H "X-API-Key: $API_KEY"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### PUT /api/v1/knowledge/:id
|
|
|
|
|
|
|
2026-09-08 02:54:41 +00:00
|
|
|
|
用途:更新知识元信息。权限同上。请求体(`types.Knowledge` 子集):`title`、`description`、`tags`、`custom_metadata`(均可选)。description 省略保持原摘要,显式空字符串清空摘要,非空值保存手工摘要;界面可在文档内容页编辑。
|
2026-08-06 10:22:10 +00:00
|
|
|
|
|
|
|
|
|
|
`custom_metadata` 是用户自填的描述性元数据(与系统内部使用的 `metadata` 分开存放,migration `000078`),校验规则见 `internal/application/service/knowledge.go`:
|
|
|
|
|
|
|
|
|
|
|
|
| 约束 | 值 |
|
|
|
|
|
|
| --- | --- |
|
|
|
|
|
|
| 字段数 | ≤ 20 |
|
|
|
|
|
|
| 键长度 | 1-64 字符,不能为空白 |
|
|
|
|
|
|
| 值类型 | string / number / boolean / null |
|
|
|
|
|
|
| 值长度 | ≤ 1000 字符 |
|
|
|
|
|
|
|
|
|
|
|
|
整体覆盖式更新(传入的对象替换原有对象)。元数据发生变化且该文档已有摘要时,会自动入队一次摘要刷新(`summary_status` 转为 `pending`)。元数据文本会参与摘要生成与文档级模型上下文(`Knowledge.CustomMetadataText()`)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"message":"Knowledge updated successfully","data":{Knowledge}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X PUT $BASE/api/v1/knowledge/k-1 -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' \
|
|
|
|
|
|
-d '{"title":"新标题","custom_metadata":{"部门":"研发中心","密级":"内部","版本":3}}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/knowledge/:id/regenerate-summary
|
|
|
|
|
|
|
|
|
|
|
|
用途:在分块内容或自定义元数据被编辑后,重新生成该文档的摘要。权限:KB owner 或 Admin+,且对父 KB 有 write 权限。
|
|
|
|
|
|
|
|
|
|
|
|
行为分两种:文档此前没有摘要(`summary_status` 为空或 `none`)时同步触发一次生成;已有摘要时改为入队刷新任务,`summary_status` 转为 `pending`,由 `knowledge_summary_refresh.go` 异步执行。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{Knowledge}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge/k-1/regenerate-summary -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### PUT /api/v1/knowledge/manual/:id
|
|
|
|
|
|
|
|
|
|
|
|
用途:更新手工知识内容(`ManualKnowledgePayload` 子集:`title/content/status/...`)。权限同上。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{Knowledge}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X PUT $BASE/api/v1/knowledge/manual/k-1 -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"content":"# 更新内容","status":"publish"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/knowledge/:id/reparse
|
|
|
|
|
|
|
|
|
|
|
|
用途:重新解析知识。权限同上。请求体(可选):`{"process_config":{...}}`。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"message":"Reparse task submitted","data":{Knowledge}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge/k-1/reparse -H "X-API-Key: $API_KEY"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/knowledge/:id/cancel-parse
|
|
|
|
|
|
|
|
|
|
|
|
用途:取消解析。权限同上。无请求体。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"message":"Knowledge parse cancelled","data":{Knowledge}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge/k-1/cancel-parse -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/knowledge/:id/download
|
|
|
|
|
|
|
|
|
|
|
|
用途:下载原始源文件(比预览更严格:Contributor+ 且 KB write;组织共享 Viewer 不可下载源文件)。API key `retrieve`/full。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 二进制流(`application/octet-stream`)。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -OJ $BASE/api/v1/knowledge/k-1/download -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/knowledge/:id/preview
|
|
|
|
|
|
|
|
|
|
|
|
用途:预览解析后的文件内容。权限:Viewer+,KB read。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 预览流(文本/HTML)。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/knowledge/k-1/preview -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### PUT /api/v1/knowledge/image/:id/:chunk_id
|
|
|
|
|
|
|
|
|
|
|
|
用途:更新某分块的图片信息(caption/OCR 等)。权限:KB 创建者 OR Admin+,KB write。路径参数:`id` 知识 ID、`chunk_id` 分块 ID。请求体为图片信息 JSON。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,...}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X PUT $BASE/api/v1/knowledge/image/k-1/c-1 -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"caption":"架构图"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/knowledge/search
|
|
|
|
|
|
|
|
|
|
|
|
用途:跨 KB 文件搜索(会话 @文件 选择器)。权限:Viewer+;API key `retrieve`/full。
|
|
|
|
|
|
|
|
|
|
|
|
| 查询参数 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
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
2026-09-24 03:26:34 +00:00
|
|
|
|
| `keyword` / `query` | string | 条件必填 | 关键字(两者等价);为空时必须传 `recent=true`,否则返回 400 |
|
|
|
|
|
|
| `file_types` | string | 否 | 逗号分隔的扩展名过滤,如 `csv,xlsx` |
|
|
|
|
|
|
| `offset` / `limit` | int | 否 | 分页;`limit` 默认 20,范围 1~100 |
|
|
|
|
|
|
| `recent` | bool | 否 | 关键字为空时返回最近文件 |
|
2026-08-06 10:22:10 +00:00
|
|
|
|
| `agent_id` | string | 否 | 共享 Agent 范围 |
|
|
|
|
|
|
| `agent_source_tenant_id` | uint64 | 否 | 共享 Agent 的来源空间选择器,与共享关系校验 |
|
|
|
|
|
|
|
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
2026-09-24 03:26:34 +00:00
|
|
|
|
响应:200 `{"success":true,"data":[Knowledge],"has_more":bool,"total":N}`
|
2026-08-06 10:22:10 +00:00
|
|
|
|
|
|
|
|
|
|
```bash
|
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
2026-09-24 03:26:34 +00:00
|
|
|
|
curl "$BASE/api/v1/knowledge/search?keyword=报告&limit=20" -H "Authorization: Bearer $TOKEN"
|
2026-08-06 10:22:10 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/knowledge/move/progress/:task_id
|
|
|
|
|
|
|
|
|
|
|
|
用途:查询移动任务进度。权限:Viewer+;API key `retrieve`/full。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{MoveProgress}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/knowledge/move/progress/task-1 -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### PUT /api/v1/knowledge/tags
|
|
|
|
|
|
|
|
|
|
|
|
用途:批量更新知识标签。权限:Contributor+;API key `ingest`/full(KB 白名单在 handler 校验)。
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `updates` | map[string][]string | 是(`binding:"required,min=1"`) | knowledge_id → tag_ids |
|
|
|
|
|
|
| `kb_id` | string | 否 | 限定 KB |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X PUT $BASE/api/v1/knowledge/tags -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"updates":{"k-1":["t-1"]},"kb_id":"kb-1"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/knowledge/batch-reparse
|
|
|
|
|
|
|
|
|
|
|
|
用途:批量重解析。权限:Contributor+;API key `ingest`/full。
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `kb_id` | string | 是(`binding:"required"`) | KB ID |
|
|
|
|
|
|
| `ids` | []string | 是(`binding:"required"`) | 知识 ID 列表 |
|
|
|
|
|
|
| `process_config` | object | 否 | 解析覆盖 |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"message":"Batch reparse task submitted","data":{"task_id"}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge/batch-reparse -H "X-API-Key: $API_KEY" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"kb_id":"kb-1","ids":["k-1","k-2"]}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/knowledge/batch-delete
|
|
|
|
|
|
|
|
|
|
|
|
用途:批量删除(≤200 条)。权限:Contributor+;API key `ingest`/full。
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `kb_id` | string | 是(`binding:"required"`) | KB ID |
|
|
|
|
|
|
| `ids` | []string | 是(`binding:"required"`) | 知识 ID 列表(≤200) |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"message":"Batch delete task submitted","data":{"task_id","deleted_count"}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge/batch-delete -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"kb_id":"kb-1","ids":["k-1"]}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/knowledge/folder
|
|
|
|
|
|
|
|
|
|
|
|
用途:把若干文档归类到指定文件夹(只改归类,不动知识库归属,也不重新解析)。权限:Contributor+ / API key `ingest`。
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `kb_id` | string | 是 | 知识库 ID |
|
|
|
|
|
|
| `knowledge_ids` | []string | 是 | 待移动的文档 |
|
|
|
|
|
|
| `folder_path` | string | 否 | 目标文件夹;空字符串表示移回知识库根目录 |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge/folder -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' \
|
|
|
|
|
|
-d '{"kb_id":"kb-1","knowledge_ids":["k-1","k-2"],"folder_path":"设计文档"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/knowledge/move
|
|
|
|
|
|
|
|
|
|
|
|
用途:跨 KB 移动知识(异步)。权限:Contributor+;API key `ingest`/full(源+目标 KB 均需在白名单)。
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `knowledge_ids` | []string | 是(`binding:"required,min=1"`) | 待移动知识 |
|
|
|
|
|
|
| `source_kb_id` | string | 是(`binding:"required"`) | 源 KB |
|
|
|
|
|
|
| `target_kb_id` | string | 是(`binding:"required"`) | 目标 KB |
|
|
|
|
|
|
| `mode` | string | 是(`binding:"required,oneof=reuse_vectors reparse"`) | 复用向量或重解析 |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{"task_id","source_kb_id","target_kb_id","knowledge_count","message"}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge/move -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' \
|
|
|
|
|
|
-d '{"knowledge_ids":["k-1"],"source_kb_id":"kb-1","target_kb_id":"kb-2","mode":"reuse_vectors"}'
|
|
|
|
|
|
```
|
2026-09-08 02:54:41 +00:00
|
|
|
|
|
|
|
|
|
|
## 实现参考
|
|
|
|
|
|
|
|
|
|
|
|
路由注册:`internal/router/routes_knowledge.go` 的 `RegisterKnowledgeBaseRoutes`、`RegisterKnowledgeRoutes`。Handler:`internal/handler/knowledgebase.go`、`internal/handler/knowledge.go`。
|