* fix(deploy): bump paradedb image to v0.25.11-pg17
Batch-importing large knowledge bases on the pinned
paradedb/paradedb:v0.22.6-pg17 image drives PostgreSQL into a
PANIC/crash-recovery loop (corrupted page pointers in shared buffers,
amcheck clean, no OOM), taking every ingest task down with it.
Three independent fixes upstream cover this exact write path, and the
pinned image predates all of them:
- pgvector 0.8.2 fixed a buffer overflow in parallel HNSW index
builds, 0.8.3 fixed possible index corruption during HNSW vacuuming,
and 0.8.4 fixed inserts during HNSW vacuuming; the image ships
pgvector 0.8.1, and the embeddings table maintains three HNSW
halfvec indexes on import.
- pg_search gained WAL-based crash recovery in 0.24.0 (paradedb#4901):
without it, any backend crash corrupts BM25 segment metadata and
turns a single crash into a recovery loop (paradedb#4935).
- PostgreSQL core moved 17.9 -> 17.11; its release notes contain no
fix matching this failure signature, ruling the core out.
Bump the compose image tags to v0.25.11-pg17 (postgres and
langfuse-db-init, prod and dev) and update the docs that pin the old
tag. Fresh installs are covered by the existing schema SQL (verified
against 0.25.11: extensions, BM25 index and HNSW halfvec indexes all
create cleanly). Existing data volumes keep working across the image
swap without any action (keyword and vector queries byte-identical in
testing); ALTER EXTENSION pg_search/vector UPDATE aligns the SQL
catalog afterwards, and migration 000099 is a no-op for 0.25.x by
design. The Helm chart pins a different image line and is left alone.
Fixes#4077
* fix(migrations): upgrade pg_search catalog to 0.25.11 with the image
Swapping in the v0.25.11 image leaves the extension catalog at 0.22.x.
Calling extension functions such as paradedb.version_info() against the
mismatched catalog segfaults the backend and sends the whole server into
crash recovery, so the catalog upgrade is required rather than optional.
- Add migration 000115 to update pg_search 0.22.0-0.25.10 to 0.25.11 and
pgvector 0.8.0-0.8.3 to 0.8.4 when the server ships those versions.
- Skip 000099 on newer images instead of advising UPDATE TO '0.22.6',
which leaves the catalog behind the shared library and crashes.
- Rewrite the upgrade guide as one 0.22.x -> 0.25.11 path with a required
ALTER EXTENSION UPDATE and a note that rollback needs a backup.
- Extend scripts/test_paradedb_upgrade.py to verify 0.22.2 -> 0.25.11 by
default (--to 0.22.6 keeps the old path) and run CONCURRENTLY
migrations outside a transaction like golang-migrate does.
---------
Co-authored-by: LuckVd <LuckVd@users.noreply.github.com>
Co-authored-by: wizardchen <wizardchen@tencent.com>
* feat(chat): open cited documents at the cited passage
Clicking a citation used to show only the parsed chunk. It now opens the
original file in the references panel, jumps to the cited place and
highlights it, narrowed to the sentence the citation supports.
Parsing records where each chunk sits in the original file
(chunks.source_locators): PDF page and paragraph boxes from the docreader,
MinerU and PaddleOCR-VL layouts; Word paragraphs, slides, sheet rows and
EPUB chapters aligned in Go against any parser engine's Markdown; text
offsets for Markdown/TXT; segment times for audio. Pipeline text rewrites
are followed with a line-diff remapper. Scanned PDF pages get their OCR
text as quotes at search time so a sentence can pick its page.
The frontend renders PDFs with pdf.js and every other previewable type
with the existing preview, then highlights with the CSS Custom Highlight
API in a highlighter yellow that stays visible against the brand green.
* fix(docreader): serialize source blocks outside main so tests import it
test_docx_tables stubs docreader.parser in sys.modules, so importing
docreader.main from a later test failed in the full unittest discover run.
The wire conversion now lives in docreader.source_wire, which needs only
the proto.
* fix(chat): tighten source locators from review
- Remap rewritten-line-for-line stretches by line so scanned PDF pages
no longer drift onto the wrong page.
- Keep the source preview mounted for citations in the file already open.
- Wait for in-flight PDF page renders before looking for the text layer.
- Count image rune offsets in one pass; stream xlsx rows up to maxUnits.
- Start text locators after a UTF-8 BOM, as viewers decode without it.
- Only re-query image children for scanned-page results.
- Seek audio citations without autoplay and drop stale seek listeners.
- Fix the SQLite migration's cross-reference to versioned/000113.
* fix(migrations): renumber chunk source locators after main's chunk_images
main took versioned 000113 and sqlite 000032 for chunk_images, so the
source_locators column moves to versioned 000114 and sqlite 000033.
* 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
initDatabase() only switches on postgres and sqlite; any other DB_DRIVER
returns "unsupported database driver". The .env.example comment listed
mysql as a valid value, so anyone following it hit a startup failure.
migrations/mysql/00-init-db.sql is the other source of that impression --
it is kept roughly in sync whenever the base tables change, but nothing
references it. Add a README stating it is unwired and listing what real
MySQL support would still need.
Also correct the table count in the database-schema doc: that script now
covers 10 tables, not 7.
* feat(artifacts): add an artifacts library with its own message_artifacts table
Skill-generated files were only reachable from inside the conversation that
produced them. This adds a sidebar entry and a page that lists them across
every conversation the user can see.
Storage: artifacts move out of the messages.artifacts JSONB column into a new
message_artifacts table (PostgreSQL 000103, SQLite 000023), backfilled on
upgrade. The table is now the only source of truth; the old column is kept and
the down migration writes the table back into it. The message repository
loads artifacts for every message it returns and writes them on create,
update (when non-nil) and fork, so callers still use Message.Artifacts.
mod_time is stored as RFC 3339 text because the collector matches files on
nanosecond mtimes, which PostgreSQL timestamps would truncate.
API: GET /api/v1/artifacts lists the latest version of each file (grouped by
session + source path, with version_count), scoped like the session list,
with keyword / file type filters and paging. Downloads keep using the
per-session endpoint.
Frontend: "产物/Artifacts" sidebar entry (hidden without sandbox support), a
library page with type tabs, search, date groups, infinite loading, preview
drawer, download and jump-to-conversation; strings in all five locales. The
sidebar's top-menu paths are now one shared list.
* fix(artifacts): keep the restore hash guard and count versions by URL
RecordRestoredArtifactMtime again only stamps rows whose content hash matches
the restored content (and ignores empty hashes), and never rewrites the hash,
matching MessageArtifacts.WithRestoredMtime. Without the guard a restore of
v1's content also moved v2's mtime and relabelled v2 with v1's hash.
The library's version_count now counts distinct URLs per (session, source
path). A later answer that references an earlier file stores another row with
the same URL, which COUNT(*) reported as an extra version.
* fix(artifacts): scope the library to web chats and clear the legacy column
The library used the session list's default scope, which counts sessions
without an owner as legacy tenant-level rows. IM sessions are created without
an owner, so every member saw the file names and titles of every IM chat
(downloads then 404 for non-admins). The library now applies the same "web"
bucket predicate as the home sidebar, extracted from QueryPaged so the two
cannot drift: no IM mapping (including cleared ones), no embed marker, no
API-key owner.
Migrations 000103 / SQLite 000023 now clear messages.artifacts after the
backfill. Message loads still SELECT *, so the stale copy was read on every
history load. Only rows that carried artifacts are rewritten; the column stays
for instances on the old binary during a rolling upgrade, and the down
migration still rebuilds it from the table.
* fix(migrations): keep the 000103 backfill alive on malformed artifact JSON
A single file_size that is not an integer ("12.5", "") or a created_at that
does not parse ("garbage", month 13) raised a cast error and failed the whole
migration, blocking startup. Casts now go through pg_temp helpers that return
NULL on bad input, falling back to 0 and the message's created_at; valid rows
are unchanged. SQLite casts never raise; its migration test now covers the
same malformed values.
* docs(artifacts): describe the web-only library scope and the cleared legacy column
* 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.
Import and update WeKnora documentation with VitePress: getting started,
architecture, features, API reference, clients, and development guides.
Includes landing page with inline SVG illustrations, theme components,
doc check scripts, and product screenshots.
This commit introduces a complete set of documentation for WeKnora, organized into six main sections: Getting Started, Architecture, Features, API Reference, Clients, and Development Guide. Key highlights include:
- Detailed installation instructions and quick start guides.
- In-depth architectural overview and backend design documentation.
- Comprehensive feature descriptions, including multi-tenant support, document parsing, and agent capabilities.
- API reference covering approximately 360 endpoints with usage examples.
- Client documentation for various interfaces including web, CLI, and SDK.
This documentation aims to facilitate user onboarding and provide a thorough understanding of the WeKnora system.