* feat(datasource/dingtalk): 摄取钉钉"上传文件"(docx/pptx/xlsx/pdf)
钉钉连接器此前只导入原生 .adoc 文档:知识库里的上传文件既不会出现在选择器里,
也不会被同步,而且没有任何提示。
- 节点判定拆成 isOnlineDocument / isBinaryDocument / binaryContentType,isDocument()
变成"在线文档 ∪ 二进制文档",上传文件因此可被枚举与摄取;表格(axls)等其它原生
类型仍不在其中,避免枚举出同步读不了的节点。
- 上传文件通过钉盘下载 API 逐字节传输,交给 WeKnora 自己的解析器:先用
/v2.0/doc/dentries/{id}/queryDentryId 把节点 UUID 换成数字 spaceId/dentryId
(存储 API 拒绝非数字 spaceId),再取预签名 URL 下载。
- 大小上限加在传输上而不是列表元数据上:node.size 与存储对象并不一致。
- 预签名 URL 短命且带版本,传输失败会用新签名重试。
- Validate 对上传文件"解析位置但不传 payload",凭证校验不必为每个候选文件下载
数 MB;adoc 仍走 blocks API。
- 同步按类型分派:adoc 渲染 blocks,上传文件落原始字节并带上具体 MIME 类型与只含
一个扩展名的文件名;下载失败与读取失败一样是可重试的失败项,不推进游标。
本提交只含 C(上传文件摄取)。不含:校验循环容错(A)、跳过项日志与可见性(B)、
原生表格 axls(D)、多维表/手工引用/前端(E)。
* test(datasource/dingtalk): 上传文件用例改用合成文档名与占位 ID
- 夹具、断言与文件名注释里的文档名统一换成合成名 Employee-Handbook.docx,
用例语义不变:仍覆盖"名字已带扩展名时不重复追加"与 PK\x03\x04 字节断言。
- 去掉测试注释里"as verified against the live tenant"的表述,改为描述调用顺序。
- dentry 响应示例与用例中的数字 ID 换成明确占位符,不再出现可被误认的真实 ID。
* fix(datasource/dingtalk): 上传文件摄取改为数据源级开关,超限不再重试
评审意见(#3786):上传文件是本次新增的摄取路径,存量数据源升级后无需用户显式启用
就会在下一次同步(含增量)开始下载并向量化所选范围内的 docx/pptx/xlsx/pdf,可能
增加存储与 embedding 成本;同时单次下载里超出体积上限被当成可重试错误,没有
Content-Length 的超大文件会重签名再下满 3 次。
- 新增 `Settings.include_uploaded_files`(默认 false,未设置/非法值一律按 false)。
读取走与本仓库语雀连接器同名的 settingBool(v, def),并新增 documentSettings /
parseDocumentSettings 承载开关。
- 判定拆成"有没有读取路径"(isDocument)与"这个数据源收不收"(isIngestible):
Validate 的探测、ListResources、全量同步与增量同步(共用 scanWorkspace)四处
全部改用 isIngestible,关闭时行为与 main 一致。
- skipReason 对"能读但没开开关"的上传文件给出可操作的原因:说明
include_uploaded_files 未启用,而不是伪装成类型不支持;媒体文件与真正没有
摄取路径的类型保持原有说法。
- readLimited 改为返回哨兵错误 errDocumentTooLarge(同时包装上限字节数),
fetchSigned 据此返回 retryable=false:体积是对象的属性,新签名只会拿到同样的
字节。普通读错误仍然 retryable=true,仍会重签名重试。
- 前端数据源编辑弹窗(同步策略步骤)加对应开关,未触碰时不写回 settings;5 个
语言包补齐文案。
- website-docs 钉钉一节写明支持范围、默认值、64 MiB 单文件上限与成本影响。
测试补 include_uploaded_files 的未设置/显式关闭/显式开启三种状态:校验、资源列表、
全量同步、增量同步四处各自断言,直接选择上传文件在关闭时仍是失败的资源;流式超限
用例断言签名查询与对象下载各只发生一次,另加"普通读错误仍重试"的用例。
---------
Co-authored-by: linus-liu-web <11640009+linus-liu-web@users.noreply.github.com>
Co-authored-by: linus-liu-web <linus-liu-web@users.noreply.github.com>
|
||
|---|---|---|
| .github | ||
| Formula | ||
| cli | ||
| client | ||
| cmd | ||
| config | ||
| dataset | ||
| deploy | ||
| docker | ||
| docreader | ||
| docs | ||
| examples | ||
| frontend | ||
| helm | ||
| internal | ||
| licenses | ||
| mcp-server | ||
| migrations | ||
| miniprogram | ||
| misc | ||
| packages | ||
| scripts | ||
| testdata | ||
| tests/miniprogram | ||
| third_party/anydoc-go | ||
| website-docs | ||
| .air.toml | ||
| .dockerignore | ||
| .env.example | ||
| .env.lite.example | ||
| .gitattributes | ||
| .gitignore | ||
| .golangci.yml | ||
| CHANGELOG.md | ||
| LICENSE | ||
| Makefile | ||
| README.md | ||
| README_CN.md | ||
| README_JA.md | ||
| README_KO.md | ||
| SECURITY.md | ||
| THIRD_PARTY_NOTICES.md | ||
| VERSION | ||
| docker-compose.dev.yml | ||
| docker-compose.yml | ||
| go.mod | ||
| go.sum | ||
| rerank_server_demo.py | ||
| test_agent_config.sh | ||
README.md
Overview · Quick Start · What's New · Features · Clients · Docs · Development
Overview
WeKnora is an open-source, LLM-powered knowledge framework for enterprise document understanding, semantic retrieval and reasoning. It brings a team's documents together so they can be searched, reasoned over and kept up to date.
https://github.com/user-attachments/assets/5722b10d-d04d-49ed-a6cc-635a8c77d91f
1:52 · 1080p · No narration, English on-screen text
Use RAG to look things up, the agent for multi-step tasks, and the wiki to organize knowledge. All three work on the same knowledge bases.
The agent's toolbox. Skills installed from ClawHub / SkillHub / Git / ZIP run in session-persistent Docker / E2B / Cube sandboxes, with an interactive terminal and graphical desktop beside the chat. Through the BrowserSkill extension the agent operates the user's own Chrome or Edge, and external MCP services (OAuth included) can be connected and enabled tool by tool.
Beyond the three modes:
- Memory and curation: cross-session long-term memory keeps the profile, preferences and facts a user has confirmed. Folder uploads keep their directory tree, and retrieval chunks can be edited, diffed and rolled back.
- Data sources and formats: auto-sync from Feishu wiki / Feishu Drive / Confluence / GitLab / Tencent IMA / Notion / Yuque / DingTalk Docs / Seafile / RSS, with more on the way. 10+ document formats including PDF, Word, images, Excel and XMind; Office files are parsed in-process by anydoc.
- Channels and integrations: Q&A in WeCom, Feishu, Slack, Telegram and other IM apps; an embed widget for external websites; a built-in MCP Server for Cursor, Claude and other AI tools; scoped API keys with a principal model for programmatic access.
- Models: 29 built-in vendors with a generated model catalog, including OpenAI, DeepSeek, Qwen (Alibaba Cloud), Zhipu, Hunyuan, Gemini, MiniMax, NVIDIA, LiteLLM and Ollama.
- Permissions and operations: multi-workspace RBAC (four roles, per-resource ownership, per-workspace audit log), several storage instances per workspace, a runtime task-queue dashboard with worker-pool governance, and Langfuse tracing for agent steps, token usage and pipelines.
- Deployment: LLMs, vector databases and storage backends are all swappable. Deploy locally or on a private cloud and keep the data in your own environment.
Quick Start
|
ONLINE WeChat Dialog Open Platform Manage knowledge bases online and connect Q&A to Official Accounts, Mini Programs and other WeChat scenarios. Open the platform → |
CLOUD Tencent Cloud Lighthouse Deploy WeKnora from an application template and run it on your own cloud server. Deploy on Tencent Cloud → |
SELF-HOSTED Your own environment Deploy with Docker or Kubernetes and configure models, storage and networking yourself. Run with Docker Compose ↓ |
Run with Docker Compose
Requires Docker, Docker Compose and Git.
git clone https://github.com/Tencent/WeKnora.git
cd WeKnora
cp .env.example .env # Edit .env as needed, see comments in the file
docker compose pull # Pull the latest images
docker compose up -d # Start core services
Then open http://localhost and follow the onboarding guide. A walkthrough with sample data is in the Quickstart.
[!TIP] To use a local Ollama model, run
ollama serve > /dev/null 2>&1 &first. For the Ollama embedding model name,OLLAMA_BASE_URL, and RAM notes, see Configuration.
| Service | URL |
|---|---|
| Web UI | http://localhost |
| Backend API | http://localhost:8080 |
| Langfuse Tracing | http://localhost:3000 |
Optional services
Add --profile flags to enable additional components; multiple profiles can be combined.
| Profile | Adds |
|---|---|
| (default) | Core services |
full |
All features |
neo4j |
Knowledge Graph (Neo4j) |
minio |
Object Storage (MinIO) |
langfuse |
Tracing (Langfuse) |
docker compose --profile neo4j --profile minio pull
docker compose --profile neo4j --profile minio up -d
docker compose down # Stop services
Upgrading
If you already have WeKnora running and downloaded a newer release:
# Set WEKNORA_VERSION in .env to the target release (e.g. 0.8.2), or keep latest
docker compose pull # Pull images matching WEKNORA_VERSION
docker compose up -d # Recreate containers with new images
[!NOTE]
docker compose up -dalone reuses locally cached images and may leave the UI version out of sync with the release you downloaded. Read the upgrade notes before moving from v0.8.0.
Other ways to deploy
| Option | When to use it |
|---|---|
| Docker Compose | The standard deployment above: all features, multiple services |
| Kubernetes (Helm) | Production clusters; the chart is in helm/ |
| Lite single binary | Local or low-resource use with no external dependencies (SQLite + in-memory queue); see Lite vs. standard |
| Desktop app | The Lite runtime with a GUI, login-free start and a macOS host sandbox; no installer is published yet, so build it from source |
All options, hardware requirements and deployment topologies: Installation guide.
[!WARNING] WeKnora ships with login authentication, but for production deployments we strongly recommend that you:
- deploy it in an internal / private network rather than on the public internet;
- avoid exposing the service directly to public networks, to prevent information leakage;
- configure proper firewall rules and access controls for the deployment environment;
- regularly update to the latest version for security patches and improvements.
What's New
v0.8.2 · 2026-09-24 · release notes
Agents can operate the browser on your computer, knowledge bases can be published to other AI tools over MCP, and a running conversation can be steered, forked or rewound.
- Local Browser (BrowserSkill): agents drive the user's own Chrome / Edge through the open-source BrowserSkill extension, with a live task preview, pause / resume and hand-off for logins and CAPTCHAs.
- Built-in MCP Server: per-workspace
/mcp/<endpoint_id>endpoints over Streamable HTTP, each with its own token, knowledge-base scope, rate limit and tool groups. The Pythonmcp-server/is deprecated. - Conversation control: append requirements to a running turn, fork from any earlier question, rewind in place with sandbox checkpoints, and pick reasoning effort per session. Generated files are collected in a new artifacts library.
- Sandbox: interactive terminal and graphical desktop; macOS Lite host sandbox with project folders; a sidebar Toolbox for skills, MCP services and the browser connection.
- Models: rebuilt model catalog (27 built-in vendors with generated context-window, max-output, reasoning and vision metadata). Agent retrieval tools are consolidated into
search_knowledge/read_document/list_documents. - Knowledge and platform: Confluence and DingTalk Docs data sources; Bocha and Serply web search; Japanese UI; per-channel IM reply language; whitelist-only outbound mode.
[!IMPORTANT] Breaking: DingTalk channels are Stream-only, and sandbox commands run as
root. See the upgrade notes.
v0.8.0 · release notes
- Skill sandbox runtime: session-persistent Docker / E2B / Cube backends with per-tenant network policy; the Local host-process backend is removed and Docker is opt-in.
- Tenant skill catalog: install from ClawHub / SkillHub / git / zip, with per-sandbox snapshots, live progress, file browse/edit, and personal and workspace env vars.
- Cross-session long-term memory: profile / preference / fact / task / interest, auto-extracted with user confirmation, plus
search_memory. - Parsing and sources: in-process anydoc office parser; GitLab and Tencent IMA data sources; XMind parsing.
- Ecosystem: official DeepSeek Harness plugin
@wxg-prc-cpg/dsh-weknora; LiteLLM; Exa and Metaso web search. - Chat: chat artifacts, question outline and timestamps; context compaction and provider prompt-cache markers.
- Security: OIDC JWKS verification, optional complex passwords, document auto-tagging, and broad sandbox/security hardening.
Earlier releases (v0.2.0 – v0.7.2)
- v0.7.2 — Product documentation site; knowledge base folder tree; chunk editing with revision history; wiki page revisions; directly loadable file URLs (
resource_urls=public); Feishu Drive data source; batch tagging; MCP Server 1.1 (29 tools); AWS S3 default credential chain. - v0.7.1 — Yunzhijia IM; Volcengine rerank; Zhipu AI web search; platform-scoped API keys; per-KB activity audit; FAQ filtering, tagging and export; Langfuse OTLP tracing; one-click Markdown export.
- v0.7.0 — Scoped API keys and principal model; task-queue dashboard and worker-pool governance; multiple storage instances per workspace; temporary chat attachments;
@Skill / @MCPmentions; mid-conversation MCP OAuth; QQBot and Lark IM; Redis TLS;weknoraCLI v0.10. - v0.6.3 — Website embed widget & Integrations Center (secure-mode token exchange + rate limits); chat experience overhaul (citation popovers, RAG pipeline progress, streaming markdown); document multi-tag & batch reparse; Wiki folders & hierarchy navigation; RSS data source; MCP OAuth2; EPUB / MHTML parsing; agent model-readiness checks; model test debugger; session source filter; workspace deletion UI.
- v0.6.2 — Per-upload process configuration with upload-confirm dialog; document reparse with
process_config;weknoraCLI v0.9 (bundled Agent Skills,session stop, auth/profile harmonization); KB marquee multi-select; HNSW index for 1024-dim pgvector embeddings; chat resources store refactor; Langfuse-only tracing (Jaeger removed). - v0.6.1 — Document parsing trace timeline (Langfuse-style span tree with stage-by-stage progress + stop-parse); OpenSearch vector store driver; declarative built-in models via YAML; system admin & consolidated platform settings + audit log; new-user onboarding guide; settings UI redesign;
weknoraCLI v0.7 / v0.8 (agent-first wire contract, NDJSON,--dry-run); OpenDataLoader + PaddleOCR-VL parsers; MCP server multi-transport (stdio / SSE / HTTP); per-model thinking-mode config; Tencent LKEAP rerank + native Gemini embeddings + MiniMax-M3. - v0.6.0 — Workspace RBAC (4-tier role matrix
Owner/Admin/Contributor/Viewer+ per-KB ownership + per-workspace audit log), workspace member management & multi-workspace UX, self-service workspaces;weknoraCLI v0.4 GA withmcp serve; KB retrieval fan-out across vector stores; AES-256-GCM credential encryption + docreader gRPC TLS + Token; Zhipu embedder + Huawei OBS; server-side user preferences; Go 1.26.0. See Tenants & auth. - v0.5.2 — Wiki ingest scales to 40k-document KBs (task queue + DLQ); MCP human-in-the-loop tool approval; Anthropic / Apache Doris / Tencent VectorDB / KS3 / SearXNG backends; adaptive 3-tier chunking with live preview; global ⌘K command palette; Yuque connector + WeChat Mini Program;
weknoraCLI preview. - v0.5.1 — Knowledge-base batch management; workspace-wide IM channels overview; session search + user-scoped pinning; unified Model / Web Search / MCP settings cards; per-agent LLM timeout; desktop workspace switching.
- v0.5.0 — Wiki Mode GA — agents auto-generate structured, interlinked Markdown wiki pages with a knowledge graph; wiki browser + visual graph in the UI.
- v0.4.0 — WeKnora Cloud (hosted LLM + parsing); Chrome Extension; ClawHub Skill; WeChat IM; attachment processing; Azure OpenAI / Alibaba OSS; Notion connector; Baidu + Ollama web search; VectorStore management.
- v0.3.6 — ASR (audio); Feishu data-source auto-sync; OIDC; IM quote-reply context + thread-based sessions; document summarization; Tavily search; parallel tool calling; agent @mention scope restriction.
- v0.3.5 — Telegram / DingTalk / Mattermost IM; IM slash commands + QA queue; suggested questions; VLM auto-describe MCP tool images; Novita AI; channel tracking.
- v0.3.4 — WeCom / Feishu / Slack IM; multimodal image support; NVIDIA model API; Weaviate; AWS S3; AES-256-GCM API-key encryption; built-in MCP service; hybrid-search optimization;
final_answertool. - v0.3.3 — Parent-child chunking; KB pinning; fallback response; passage cleaning for rerank; storage auto-creation; Milvus.
- v0.3.2 — Knowledge Search entry; per-source parser & storage engine config; image rendering in local storage; document preview; Volcengine TOS; Mermaid rendering; batch session management; memory graph preview.
- v0.3.0 — Shared Space; Agent Skills + sandboxed execution; custom agents; Data Analyst agent; thinking mode; Bing / Google web search; API Key auth; Helm chart; Korean i18n; Qdrant.
- v0.2.0 — Agent Mode (ReACT); multi-type knowledge bases (FAQ + document); conversation strategy config; DuckDuckGo web search; MCP tool integration; new UI with agent mode switching; MQ async task management.
Full history: CHANGELOG.md.
Product Tour
Quick Q&A and smart reasoning
Two ways to ask. Quick Q&A answers from the knowledge base with RAG and cites the sources it used. In smart reasoning the agent plans multi-step work, searching, reading documents and calling tools and skills, and shows each step in the conversation. Docs →
Local browser
Operate the browser on your computer. Through Tencent's open-source BrowserSkill extension, the agent opens pages and fills in forms in your own Chrome or Edge, and hands over to you for logins and CAPTCHAs. Docs →
Skills and sandbox
Run skills and produce files. Docker, E2B and Cube backends are supported. Turns in the same session share one workspace, and generated files can be previewed and downloaded. Open the graphical desktop or interactive terminal beside the chat to follow each step and take over when needed. Docs →
Toolbox: MCP services and skills
Tools the agent can use. Connect external MCP services and choose, tool by tool, which are enabled and which calls need approval. Install skills from ClawHub, SkillHub, Git or ZIP, manage them per workspace, and reuse them across sandboxes. Docs →
Automatic wiki
Documents organized into a browsable wiki. With Wiki enabled, WeKnora extracts people, products and concepts from knowledge-base documents into pages with source citations, organized by directory. The knowledge graph shows how pages relate; pages can be edited directly and every change can be rolled back. Docs →
Observability
Tracing and runtime monitoring. Langfuse traces the reasoning, tool calls and token usage of each agent step. The document parsing timeline shows progress stage by stage, and the task-queue dashboard lists queued and failed tasks. Docs →
Architecture
A modular pipeline from document parsing, vectorization and retrieval to LLM inference, in which every component can be replaced or extended. It runs locally or on a private cloud, and the Web UI needs no setup to get started. More: Architecture overview · RAG pipeline · Extension points.
Features
| Area | Highlights |
|---|---|
| Q&A and agent | Quick Q&A answers from knowledge bases with citations; smart reasoning runs a ReAct agent over knowledge bases, web search, MCP tools, skills and the local browser. Steer, fork or rewind a running conversation, and keep long-term memory across sessions |
| Wiki | Agent-generated, interlinked wiki pages with a knowledge graph; in-browser editing, revision diff and rollback |
| Skills and sandbox | Skill catalog installed from ClawHub / SkillHub / Git / ZIP; session-persistent Docker / E2B / Cube sandboxes with network policy; terminal and graphical desktop beside the chat |
| Knowledge bases | FAQ, document and wiki bases; folder tree; chunk editing with revisions; per-upload parsing, chunking and multimodal settings; auto-tagging |
| Retrieval | Keyword + vector hybrid search, rerank, parent-child chunking and GraphRAG (Neo4j); end-to-end evaluation with recall and BLEU / ROUGE |
| Access and security | Workspace RBAC with four roles and an audit log; scoped API keys; OIDC; AES-256-GCM credential encryption; SSRF-safe outbound requests with a whitelist-only mode |
| Operations | Langfuse tracing for agent steps, tokens and pipelines; document parsing timeline; task-queue dashboard with worker pools; automatic migrations on upgrade |
Supported backends
| Component | Options |
|---|---|
| LLMs | 29 built-in vendors, including OpenAI / Azure OpenAI / Anthropic / DeepSeek / Qwen / Zhipu / Hunyuan / Doubao / Gemini / MiniMax / NVIDIA / SiliconFlow / OpenRouter / LiteLLM / Ollama |
| Embeddings | Ollama / BGE / GTE / Zhipu / OpenAI-compatible APIs |
| Vector databases | PostgreSQL (pgvector) / Elasticsearch / OpenSearch / Milvus / Weaviate / Qdrant / Apache Doris / Tencent VectorDB |
| Object storage | Local / Tencent Cloud COS / MinIO / AWS S3 / Volcengine TOS / Alibaba Cloud OSS / Kingsoft Cloud KS3 / Huawei Cloud OBS |
| Document formats | PDF / Word / PPT / Excel / CSV / TXT / Markdown / HTML / EPUB / MHTML / JSON / XMind / images |
| Data sources | Feishu wiki / Feishu Drive / Lark / Confluence / GitLab / Tencent IMA / Notion / Yuque / DingTalk Docs / Seafile / RSS |
| IM channels | WeCom / Feishu / Lark / QQBot / Slack / Telegram / DingTalk / Mattermost / WeChat / Yunzhijia |
| Web search | DuckDuckGo / Bing / Google / Tavily / Baidu / Ollama / SearXNG / Keenable / Zhipu AI / Exa / Metaso / Bocha / Serply |
| Deployment | Docker Compose / Kubernetes (Helm) / Lite single binary / desktop app; offline and private-cloud installs; UI in Chinese, English, Japanese, Korean and Russian |
Clients and Integrations
| Client | What it does | |
|---|---|---|
CLI weknora |
Agent-first command line for the full API, with a curated MCP tool surface and bundled Agent Skills | |
| Built-in MCP Server | Publishes knowledge bases to Cursor, Claude and other MCP clients over Streamable HTTP; the Python mcp-server/ is deprecated |
|
| Local Browser (BrowserSkill) | Lets agents operate the user's own Chrome / Edge | |
| Chrome Extension | Select text, images, or entire pages in the browser and save them as knowledge entries with one click, without copy-paste or file upload | |
| WeChat Mini Program | Lightweight mobile client: configure API access, select knowledge bases, import URLs, and ask knowledge chat from WeChat | |
| ClawHub Skill | A WeKnora skill on ClawHub for document import, hybrid search and knowledge management via the REST API | |
| DeepSeek Harness plugin | Gives dsh coding agents four read-only tools: search, read document, ask and list knowledge bases |
|
| Website Embed Widget | Publishes agents on external sites | |
| Go SDK | CRUD for knowledge bases, documents and sessions, plus SSE streaming Q&A | |
| WeChat Dialog Open Platform | Hosted Q&A built on WeKnora: upload knowledge and publish a Q&A service in WeChat without writing code |
Command-Line Interface
weknora is the official CLI for driving the API from a terminal or an AI agent. It is agent-first: every command emits a stable JSON envelope by default (with typed error codes mapped to exit codes), and --format text renders for humans. It also serves a curated MCP tool surface (weknora mcp serve) and ships bundled Agent Skills.
weknora profile add prod --host https://kb.example.com --use
weknora auth login
weknora kb list
weknora link --kb my-knowledge-base # bind the current directory
weknora doc upload notes.md
weknora chat "summarise the design doc"
For headless / CI use, set WEKNORA_API_KEY + WEKNORA_HOST and skip auth login; no credentials are written to disk. See cli/README.md for install + 5-minute quickstart and cli/AGENTS.md for the operational contract AI agents rely on.
Documentation
The full product documentation lives at weknora.weixin.qq.com/docs (in Chinese), organized as Getting Started → Architecture → Features → API → Clients → Development and covering ~360 API endpoints and ~150 environment variables.
| Start here | |
|---|---|
| Introduction | Capabilities overview |
| Installation | Docker Compose, Helm, Lite and desktop |
| Configuration | Environment variables and models |
| Troubleshooting FAQ | Common problems and fixes |
| API reference | REST API overview |
| Release notes | What changed in each release |
Development
If you need to frequently modify code, you don't need to rebuild Docker images every time. Use fast development mode:
make dev-start # Start infrastructure
make dev-app # Start backend (new terminal)
make dev-frontend # Start frontend (new terminal)
- Frontend modifications auto hot-reload (no restart needed)
- Backend modifications quick restart (5-10 seconds, supports Air hot-reload)
- No need to rebuild Docker images
- Supports IDE breakpoint debugging
See the Development guide for details.
The documentation site and product homepage are built from website-docs/. With Node.js 24, run cd website-docs && npm run setup && npm run build && npm run preview to preview both together; the unified static output serves the homepage at / and documentation at /docs/. See the directory's README for Nginx and Docker deployment.
Contributing
Welcome to submit Issues or Pull Requests.
- Process: Fork → Create branch → Commit changes → Open PR
- Standards: Format code with
gofmt, follow Conventional Commits (feat:/fix:/docs:/test:/refactor:)
Validating your change
For a focused PR, validate the changed scope first:
git fetch origin main
git diff --check origin/main...HEAD
golangci-lint run --new-from-rev=origin/main ./...
go test ./path/to/changed/package -count=1
Run gofmt on changed Go files before committing. For frontend changes, run the relevant tests from frontend/ and use npm run type-check when the change affects TypeScript or Vue components.
The full maintainer gate remains:
make fmt
make lint
make test
make fmt formats the entire Go repository, so run it only with a clean worktree and review the resulting diff. Some full-suite tests require local infrastructure or service configuration. If a full check fails for an unrelated baseline or environment reason, include the exact command and failure in the PR while still providing passing targeted tests for your change.
Contributors
Thanks to everyone who has contributed:
License
This project is licensed under the MIT License. You are free to use, modify, and distribute the code with proper attribution.