LLM 知识平台Tencent/WeKnora

| English | 简体中文 | 日本語 | 한국어 |

Overview • Architecture • Key Features • Getting Started • API Reference • Developer Guide

💡 WeKnora — 借助 RAG、智能体与自动 Wiki，将文档转化为鲜活的知识

📌 概述

WeKnora 是一个开源的、由 LLM 驱动的知识框架，专为企业级文档理解、语义检索和自主推理而构建。

https://github.com/user-attachments/assets/19b28ce2-a62f-4f54-b289-c983576259bc

2:25 · 1080p · 英语旁白与字幕。
它围绕三大核心能力构建：基于 RAG 的快速问答用于日常查询；ReAct Agent 可自主编排检索、MCP 工具、租户技能目录、会话持久化的 Docker / E2B / Cube 沙箱以及网络搜索，以处理复杂的多步骤任务；还有全新的 Wiki 模式，其中 agent 将原始文档提炼为可自我维护、相互链接的 markdown 知识库，并配有交互式知识图谱，支持手动编辑、修订历史和一键回滚。跨会话长期记忆会记住你是谁，以及你反复询问的内容。知识管理同样亲力亲为：树状结构文件夹视图保留上传内容的目录布局，带修订历史的分块编辑让检索分块可以像文档一样被编辑、对比差异和还原。结合多源接入（飞书 wiki / 飞书云盘 / GitLab / 腾讯 IMA / Notion / 语雀 / 钉钉文档 / RSS，且仍在增加）、用于将 agent 发布到外部网站的网站嵌入组件、用于程序化集成的带主体模型的限定范围 API 密钥、每个工作区的多实例存储后端以实现灵活的数据放置、20+ LLM 提供商集成（包括 LiteLLM）、完整的 Langfuse 可观测性，以及带 worker 池治理的运行时任务队列仪表盘、面向企业的多工作区 RBAC（4 级角色矩阵 + 每资源所有权 + 每工作区审计日志），以及完全可自托管的模块化架构，WeKnora 将分散的文档转变为可查询、具备推理能力、持续演进的知识资产。

该框架支持从飞书、GitLab、腾讯 IMA、Notion 和语雀自动同步知识（更多数据源即将推出），处理包括 PDF、Word、图片、Excel 和 XMind 在内的 10+ 种文档格式，并可通过企业微信、飞书、Slack 和 Telegram 等 IM 渠道直接提供问答服务。它兼容主流 LLM 提供商，包括 OpenAI、DeepSeek、通义千问（阿里云）、智谱、混元、Gemini、MiniMax、NVIDIA、LiteLLM 和 Ollama。Office 文件可通过 anydoc 在进程内解析。其完全模块化的设计允许替换 LLM、向量数据库和存储后端，并支持本地和私有云部署，确保完整的数据主权。WeKnora 还集成了 Langfuse，用于对 agent 推理、token 使用和流水线追踪进行全面可观测性。

✨ 最新更新
- v0.8.0 — 技能沙箱运行时（会话持久化的 Docker / E2B / Cube 后端，支持按租户的网络策略；移除本地宿主进程后端；Docker 需主动启用）；租户技能目录（从 ClawHub / SkillHub / git / zip 安装，按沙箱快照，实时进度，文件浏览/编辑，个人与工作区环境变量）；跨会话长期记忆（画像 / 偏好 / 事实 / 任务 / 兴趣，自动提取并确认，search_memory）；进程内 anydoc 办公文档解析器；官方 DeepSeek Harness 插件 @wxg-prc-cpg/dsh-weknora；GitLab 和腾讯 IMA 数据源；LiteLLM；Exa 和 Metaso 网页搜索；XMind 解析；聊天产物、问题大纲和时间戳；上下文压缩和提供商提示缓存标记。此外还有 OIDC JWKS 验证、可选的复杂密码、文档自动打标签，以及广泛的沙箱/安全加固。参见 CHANGELOG.md。
- v0.7.2 — 发布官方产品文档站点（VitePress；六个板块，约 50 个页面，覆盖约 360 个 API 端点和约 150 个环境变量，支持独立的 Docker/Nginx 部署、快速开始示例数据和本地 MCP 演示）；知识库文件夹树（上传路径作为一等数据存储，像文件管理器一样浏览/重命名/重新归档文档）；分块编辑与修订历史（在 UI 中编辑检索分块，按版本对比和回滚，自动重新索引，并支持自定义文档元数据）；Wiki 页面修订历史（快照 + 行级差异 + 一键回滚 + 浏览器内手动编辑）；通过 resource_urls=public / RESOURCE_URL_MODE 提供可直接加载的文件 URL（第三方应用无需再经过一次带认证的代理调用即可渲染图片和文件）；飞书云盘数据源以及通过 blocks API 同步 docx；批量文档打标签；MCP Server 1.1.x（迁移到 mcp 2.x 高层 API，官方 PyPI 包 tencent-weknora-mcp，新增 create_knowledge_from_text 和 list_shared_knowledge_bases，共 29 个工具）；AWS S3 默认凭证链（IAM Role / IRSA）；本地 HTML 上传解析；QQBot markdown 回复；新增针对 app / frontend / docreader / mcp-server 的 PR CI 检查。此外还有大规模 router 和 modelcontext 重构、rerank 和分块质量工作，以及广泛的稳定性修复。参见 CHANGELOG.md。
- v0.7.1 — 新增 云之家（Yunzhijia）IM 集成（WebSocket + 图片消息 + markdown 回复）；火山引擎 rerank 提供商（支持请求批处理）和 智谱 AI 网页搜索 提供商；用于控制平面自动化的 平台级 API 密钥（租户管理、系统设置、运行时队列、审计日志）；按知识库的活动审计追踪；FAQ 管理增强（过滤、标签、导出、导入追踪）；Langfuse OTLP/OTel 追踪迁移，支持 W3C traceparent 传播；聊天头部操作支持一键 Markdown 导出，并在引用抽屉中展示 wiki 工具结果；提示缓存可观测性；会话渠道治理（管理员级 IM/embed/API 会话）；高可用的飞书大 wiki 同步；以及移除遗留的 Neo4j 对话记忆依赖。此外还有广泛的 slug 完整性、SSRF 传输和状态同步加固。参见 CHANGELOG.md。
- v0.7.0 — 细粒度 作用域 API 密钥与主体模型（能力级授权 + 按知识库限制 + API 集成演练场）；运行时任务队列可观测性仪表盘与工作池治理（按阶段的池 + 按模型的并发调控器 + 失败任务检查/重试）；多实例存储后端（每个工作区多个存储实例、按知识库绑定、默认实例）；会话级临时附件（异步图片/文档解析 + 组合限制）；问题与后续建议；稳定的资源注册表，支持 LLM 上下文别名压缩；@Skill / @MCP 提及，支持作用域代理运行时；对话中途 MCP OAuth；QQBot 与 Lark（飞书国际版）IM 集成；Redis TLS；Requesty 模型提供商 + Keenable 网页搜索；无租户预配与受限自助工作区；管理员密码重置；知识库复制流程；weknora CLI v0.10。此外还有广泛的安全加固（SSRF、密钥脱敏、SQL 校验、IDOR）。参见 CHANGELOG.md。
- v0.6.3 — 网站嵌入组件与集成中心（安全模式令牌交换 + 速率限制）；聊天体验全面改造（引用弹出框、RAG 流水线进度、流式 markdown）；文档多标签与批量重新解析；Wiki 文件夹与层级导航；RSS 数据源；MCP OAuth2；EPUB / MHTML 解析；代理模型就绪检查；模型测试调试器；会话来源过滤；工作区删除 UI。参见 CHANGELOG.md。
- v0.6.2 — 按上传的流程配置，带上传确认对话框；使用 process_config 重新解析文档；weknora CLI v0.9（内置 Agent Skills、session stop、认证/配置文件统一）；知识库跑马灯多选；用于 1024 维 pgvector 嵌入的 HNSW 索引；聊天资源存储重构；仅 Langfuse 追踪（移除 Jaeger）。参见 CHANGELOG.md。
- v0.6.1 — 文档解析追踪时间线（Langfuse 风格的 span 树，带逐阶段进度 + 停止解析）；OpenSearch 向量存储驱动；通过 YAML 声明式内置模型；系统管理员与统一平台设置 + 审计日志；新用户入门指南；设置 UI 重新设计；weknora CLI v0.7 / v0.8（agent 优先的通信契约、NDJSON、--dry-run）；OpenDataLoader + PaddleOCR-VL 解析器；MCP 服务器多传输（stdio / SSE / HTTP）；按模型配置思考模式；腾讯 LKEAP 重排序 + 原生 Gemini 嵌入 + MiniMax-M3。参见 CHANGELOG.md。
- v0.6.0 — 工作区 RBAC（4 级角色矩阵 Owner / Admin / Contributor / Viewer + 按知识库所有权 + 按工作区审计日志）、工作区成员管理与多工作区 UX、自助工作区；weknora CLI v0.4 GA，带 mcp serve；跨向量存储的知识库检索扇出；AES-256-GCM 凭据加密 + docreader gRPC TLS + Token；智谱嵌入器 + 华为 OBS；服务端用户偏好；Go 1.26.0。参见 docs/RBAC说明.md 和 CHANGELOG.md。
- v0.5.2 — Wiki 摄取可扩展至 4 万文档的知识库（任务队列 + DLQ）；MCP 人在回路工具审批；Anthropic / Apache Doris / 腾讯 VectorDB / KS3 / SearXNG 后端；带实时预览的自适应 3 级分块；全局 ⌘K 命令面板；语雀连接器 + 微信小程序；weknora CLI 预览。
- v0.5.1 — 知识库批量管理；工作区级 IM 渠道概览；会话搜索 + 用户级固定；统一的模型 / 网络搜索 / MCP 设置卡片；按 agent 的 LLM 超时；桌面端工作区切换。
- v0.5.0 — Wiki 模式 GA — agent 自动生成结构化、相互链接的 Markdown wiki 页面，并带有知识图谱；UI 中的 wiki 浏览器 + 可视化图谱。
- v0.4.0 — WeKnora Cloud（托管 LLM + 解析）；Chrome 扩展；ClawHub Skill；微信 IM；附件处理；Azure OpenAI / 阿里云 OSS；Notion 连接器；百度 + Ollama 网络搜索；VectorStore 管理。
- v0.3.6 — ASR（音频）；飞书数据源自动同步；OIDC；IM 引用回复上下文 + 基于线程的会话；文档摘要；Tavily 搜索；并行工具调用；agent @mention 范围限制。
- v0.3.5 — Telegram / 钉钉 / Mattermost IM；IM 斜杠命令 + 问答队列；建议问题；VLM 自动描述 MCP 工具图像；Novita AI；渠道追踪。
- v0.3.4 — 企业微信 / 飞书 / Slack IM；多模态图像支持；NVIDIA 模型 API；Weaviate；AWS S3；AES-256-GCM API 密钥加密；内置 MCP 服务；混合搜索优化；final_answer 工具。
- v0.3.3 — 父子分块；知识库固定；回退响应；重排序的段落清理；存储自动创建；Milvus。
- v0.3.2 — 知识搜索入口；按来源的解析器与存储引擎配置；本地存储中的图像渲染；文档预览；火山引擎 TOS；Mermaid 渲染；批量会话管理；记忆图谱预览。
- v0.3.0 — 共享空间；Agent Skills + 沙箱化执行；自定义 Agent；数据分析师 Agent；思考模式；Bing / Google 网页搜索；API Key 认证；Helm chart；韩语 i18n；Qdrant。
- v0.2.0 — Agent 模式（ReACT）；多类型知识库（FAQ + 文档）；对话策略配置；DuckDuckGo 网页搜索；MCP 工具集成；支持 Agent 模式切换的新 UI；MQ 异步任务管理。

📱 界面展示

🛠️ Skill 沙箱对话 · 生成并预览 Word 文件

📦 Skill 目录 · 安装到 E2B 沙箱
🤖 Agent 模式 · 搜索、读取 Skill、写入沙箱文件

💬 智能问答对话

📖 Wiki 浏览器
🕸️ Wiki 知识图谱

🕘 Wiki 页面修订历史与回滚
✂️ 分块编辑与修订历史

📁 文件夹树与批量操作
🔭 可观测性 · Langfuse 追踪

🏗️ 架构

weknora-architecture.png

从文档解析、向量化、检索到 LLM 推理的全模块化流水线——每个组件均可替换、可扩展。支持本地 / 私有云部署，具备完整的数据主权，并提供零门槛的 Web UI 以便快速上手。

🧩 功能概览

智能对话

| 能力 | 详情 |
|------------|---------|
| 智能推理 | ReACT 渐进式多步推理，自主编排知识检索、MCP 工具、技能沙箱和网络搜索 |
| 快速问答 | 基于 RAG 的知识库问答，快速且准确地给出答案 |
| Wiki 模式 | 由 Agent 驱动，从原始文档自动生成结构化、相互链接的 markdown Wiki 页面；支持浏览器内手动编辑、页面修订历史、行级差异和一键回滚 |
| 技能目录与沙箱 | 工作区技能目录（ClawHub / SkillHub / git / zip）安装到会话持久化的 Docker / E2B / Cube 沙箱；shell_exec、文件工具、产物、按配置的网络策略；已移除本地主机进程后端 |
| 长期记忆 | 跨会话记忆（个人资料 / 偏好 / 事实 / 任务 / 兴趣），支持自动提取、用户确认和按需 search_memory |
| 工具调用 | 内置工具、MCP 工具（包括 OAuth2 远程服务、对话中途 OAuth）、网络搜索；通过 @Skill / @MCP 提及来限定每轮 Agent 运行时的范围 |
| 对话策略 | 在线 Prompt 编辑、检索阈值调优、多轮上下文感知、按 Agent 的引用输出开关 |
| 推荐问题 | 基于知识库内容自动生成问题建议和回答后的追问 |
| 临时附件 | 会话范围内的图片 / 文档上传，异步解析以支持一次性问答，并设有图片 + 附件合计上限 |
| 引用与 RAG 进度 | 内联引用弹窗和引用抽屉（区分网络 / 知识库来源）、共享 markdown 渲染，以及聊天中逐阶段的 RAG 流水线进度 |
| 会话管理 | 按来源（Web / IM / Embed）筛选和分组侧边栏会话，并支持内联重命名会话标题 |

知识管理

| 能力 | 详情 |
|------------|---------|
| 知识库类型 | FAQ / 文档 / Wiki，支持文件夹导入、URL 导入、多标签管理和在线录入 |
| 文件夹树 | 文件夹上传保留原始目录结构，并提供侧边栏树用于浏览、文件夹重命名，以及将文档重新归档到另一个文件夹 |
| 分块编辑与修订 | 直接在 UI 中编辑检索分块，支持按版本快照、差异对比和一键回滚，编辑后自动重建索引；生成的问题可添加、编辑、删除和重新生成；支持自定义文档元数据 |
| 按上传配置处理流程 | 通过上传确认对话框或 process_config API，为每个上传批次覆盖解析器、分块、多模态（VLM / ASR）、图谱提取和问题生成设置；可使用新设置重新解析 |
| 批量重新解析 | 一次为多个文档重新排队解析，并可选择按批次设置 process_config |
| 数据源导入 | 从飞书 Wiki / 飞书云盘 / Lark / GitLab / 腾讯 IMA / Notion / 语雀 / 钉钉文档 / RSS 源自动同步（更多数据源即将推出）；支持增量同步和全量同步 |
| 文档格式 | PDF / Word / Txt / Markdown / HTML / EPUB / MHTML / 图片 / CSV / Excel / PPT / JSON / XMind |
| 自动打标签 | 解析后，从知识库现有标签集中选取匹配标签，不创建新标签，也不覆盖手动标签 |
| 检索策略 | BM25 稀疏检索 / 稠密检索 / GraphRAG / 父子分块 / HNSW 加速的 pgvector（1024 维）/ 多维索引 |
| 批量选择与打标签 | 在知识库列表中框选拖拽多个文档，进行批量重新解析和批量打标签（常用标签已预选） |
| 端到端测试 | 全流程可视化，包含召回命中率、BLEU / ROUGE 指标评估 |

集成与扩展

| 能力 | 详情 |
|------------|---------|
| 大语言模型 | OpenAI / Azure OpenAI / Anthropic（Claude）/ DeepSeek / Qwen（阿里云）/ 智谱 / 混元 / 豆包（火山引擎）/ Gemini / MiniMax / NVIDIA / Novita AI / SiliconFlow / OpenRouter / Requesty / LiteLLM / Ollama |
| 嵌入模型 | Ollama / BGE / GTE / 智谱 / OpenAI 兼容 API |
| 向量数据库 | PostgreSQL（pgvector）/ Elasticsearch / OpenSearch / Milvus / Weaviate / Qdrant / Apache Doris / 腾讯 VectorDB |
| 对象存储 | 本地 / MinIO / AWS S3（IAM Role / IRSA 默认凭证链）/ 火山引擎 TOS / 阿里云 OSS / 金山云 KS3 / 华为云 OBS；每个工作区支持多个存储实例，可按知识库绑定并设置默认实例 |
| IM 渠道 | 企业微信 / 飞书 / Lark（飞书国际版）/ QQBot / Slack / Telegram / 钉钉 / Mattermost / 微信 / 云之家 |
| 网站嵌入 | 通过嵌入组件发布智能体，支持域名白名单、速率限制和安全模式令牌交换 |
| 网络搜索 | DuckDuckGo / Bing / Google / Tavily / 百度 / Ollama / SearXNG / Keenable / 智谱 AI / Exa / Metaso |
| API 集成 | 作用域 API 密钥（能力级授权 + 按知识库限制 + 限流的最后使用时间追踪），并提供 API 集成调试场；MCP OAuth 和嵌入会话按主体隔离；resource_urls=public 直接返回可加载的文件/图片 URL，省去第二次认证代理调用 |
| MCP 服务器 | 官方 PyPI 包 tencent-weknora-mcp，通过 stdio / SSE / HTTP 传输提供 29 个工具 |

平台

| 能力 | 详情 |
|------------|---------|
| 部署 | 本地 / Docker / Kubernetes（Helm），支持私有化和离线部署 |
| 界面 | Web UI / RESTful API / CLI（weknora）/ Chrome 扩展 / 网站嵌入组件 / 微信小程序 |
| 访问控制 | 工作区 RBAC，含 4 级角色矩阵（所有者 / 管理员 / 贡献者 / 查看者）、按知识库的资源归属、按工作区的审计日志、仅邀请制工作区、无租户预配与受控自助创建工作区、管理员密码重置（会话撤销）、跨工作区超级用户、作用域 API 密钥 |
| 安全 | 对 API 密钥和 MCP / 数据源凭据进行 AES-256-GCM 静态加密，并支持平滑密钥轮换；应用与 docreader 之间使用 gRPC TLS + Token；Redis TLS；SSRF 安全的 HTTP 客户端（数据源、URL 导入、重定向链）；响应中的密钥脱敏；技能沙箱隔离（Docker 可选 / E2B / Cube），并支持按配置的网络策略；OIDC ID-token JWKS 验证；可选的复杂密码策略 |
| 可观测性 | 集成 Langfuse（唯一追踪后端），用于 ReAct 循环、token 跟踪、工具调用和流水线追踪；内置 Langfuse 风格的文档解析追踪时间线，带分阶段进度；系统管理员运行时任务队列仪表盘（队列深度、按模型并发、失败任务检查与手动重试） |
| 任务管理 | MQ 异步任务，具有按阶段的 worker 池治理（核心 / 后处理 / 增强 / 维护 + 弹性共享池，以及独立的 Wiki 池）和按模型的后台并发调控器；版本升级时自动数据库迁移 |
| 模型管理 | 集中配置，通过 YAML 声明式内置模型，按知识库选择模型，按模型覆盖思考模式和嵌入维度，交互式模型测试调试器，多工作区内置模型共享，WeKnora Cloud 托管模型与解析 |

🧩 Chrome 扩展

WeKnora Chrome 扩展 让你可以直接将网页内容捕获到 WeKnora 知识库中。在浏览器中选择文本、图片或整个页面，一键保存为知识条目——无需复制粘贴或上传文件。

📱 微信小程序

WeKnora 小程序 提供了一个轻量级移动客户端，用于配置 WeKnora API 访问、选择知识库、导入 URL，并在微信中进行知识问答。

🦞 ClawHub 技能

WeKnora ClawHub 技能 是在 ClawHub 平台上发布的 WeKnora 技能。安装后，它可以通过 WeKnora REST API 实现文档导入（文件 / URL / Markdown）、跨知识库的混合搜索（向量 + 关键词）以及知识条目管理。

- 文档导入 — 通过 agent 上传文件、导入网页或写入 Markdown 知识
- 混合搜索 — 使用向量 + 关键词检索在知识库内或跨知识库搜索
- 知识管理 — 以编程方式列出、浏览、编辑和删除知识条目

🐋 DeepSeek Harness 插件
@wxg-prc-cpg/dsh-weknora 是官方的 DeepSeek Harness（dsh）插件（文档）。该 harness 本身不提供检索、嵌入或知识库能力，因此该插件为编码代理提供你的文档：dsh plugin --profile web add @wxg-prc-cpg/dsh-weknora，将其指向某个部署，代理的工具集中便会出现四个只读工具。

- weknora_search — 混合检索，逐字返回源段落，每段都带有可复用的 knowledge_id
- weknora_read_document — 按顺序重新组装单个文档的段落，支持分页
- weknora_ask — WeKnora 自身生成的带引用答案，基于 RAG 或 ReAct 流水线
- weknora_list_knowledge_bases — 知识库名称和 id，以便代理限定自己的搜索范围

⌨️ 命令行界面

weknora 是用于从终端或 AI 代理驱动 API 的官方 CLI。它以代理为先：每个命令默认输出稳定的 JSON 信封（带有映射到退出码的类型化错误码），而 --format text 则为人类渲染。它还提供精选的 MCP 工具接口（weknora mcp serve），并附带内置的 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"

对于无头 / CI 用途，设置 WEKNORA_API_KEY + WEKNORA_HOST 并完全跳过 auth login —— 不会将凭据写入磁盘。

安装 + 5 分钟快速入门请参见 cli/README.md，AI 代理所依赖的操作契约请参见 cli/AGENTS.md。

🚀 快速开始

🛠 前提条件

- Docker 和 Docker Compose
- 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

启动后，访问 http://localhost 即可开始使用。

若要使用本地 Ollama 模型，请先运行 ollama serve > /dev/null 2>&1 &。

🔄 升级

如果你已经在运行 WeKnora 并下载了更新的版本：

Set WEKNORA_VERSION in .env to the target release (e.g. 0.7.0), or keep latest
docker compose pull     # Pull images matching WEKNORA_VERSION
docker compose up -d    # Recreate containers with new images

仅运行 docker compose up -d 会复用本地缓存的镜像，可能导致 UI 版本与你下载的版本不同步。

🔧 可选服务（Docker Compose Profiles）

添加 --profile 标志以启用额外组件。可以组合多个 profile：
| 配置 | 描述 | 命令 |
|---------|-------------|---------|
| _（默认）_ | 核心服务 | docker compose pull && docker compose up -d |
| full | 所有功能 | docker compose --profile full pull && docker compose --profile full up -d |
| neo4j | 知识图谱（Neo4j） | docker compose --profile neo4j pull && docker compose --profile neo4j up -d |
| minio | 对象存储（MinIO） | docker compose --profile minio pull && docker compose --profile minio up -d |
| langfuse | 链路追踪（Langfuse） | docker compose --profile langfuse pull && docker compose --profile langfuse up -d |

组合配置：docker compose --profile neo4j --profile minio pull && docker compose --profile neo4j --profile minio up -d

停止服务：docker compose down

🌐 服务地址

| 服务 | URL |
|---------|-----|
| Web UI | http://localhost |
| 后端 API | http://localhost:8080 |
| Langfuse 链路追踪 | http://localhost:3000 |

MCP 服务器

请参阅 MCP 配置指南 了解必要的设置。

🔌 使用微信对话开放平台

WeKnora 作为微信对话开放平台的核心技术框架，提供了更便捷的使用方式：

- 零代码部署：只需上传知识即可在微信生态内快速部署智能问答服务，实现“即问即答”体验
- 高效问题管理：支持高频问题的分类管理，配合丰富的数据工具，确保答案准确、可靠且易于维护
- 微信生态集成：通过微信对话开放平台，WeKnora 的智能问答能力可无缝接入微信公众号、小程序等微信场景，提升用户互动体验

📘 API 参考

官网与产品文档：website-docs/ 包含产品主页以及按入门 → 架构 → 功能 → API → 客户端 → 开发组织的完整文档集。使用 Node.js 24，运行 cd website-docs && npm run setup && npm run build && npm run preview 可同时预览两者。统一的静态输出在 / 提供主页，在 /docs/ 提供文档；有关 Nginx 和 Docker 部署，请参阅该目录的 README。

故障排查常见问题：故障排查常见问题

详细 API 文档请见：API 文档

产品规划与即将推出的功能：路线图

🧭 开发者指南

⚡ 快速开发模式（推荐）

如果你需要频繁修改代码，无需每次都重新构建 Docker 镜像！使用快速开发模式：

启动基础设施
make dev-start

启动后端（新终端）
make dev-app

启动前端（新终端）
make dev-frontend

开发优势：
- ✅ 前端修改自动热重载（无需重启）
- ✅ 后端修改快速重启（5-10 秒，支持 Air 热重载）
- ✅ 无需重新构建 Docker 镜像
- ✅ 支持 IDE 断点调试

详细文档： 开发环境快速开始

🤝 贡献指南

欢迎提交 Issues 或 Pull Requests。

流程： Fork → 创建分支 → 提交更改 → 发起 PR

规范： 使用 gofmt 格式化代码，遵循 Conventional Commits（feat: / fix: / docs: / test: / refactor:）

验证

对于聚焦的 PR，请先验证更改范围：

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

提交前对更改的 Go 文件运行 gofmt。对于前端更改，请从 frontend/ 运行相关测试，并在更改涉及 TypeScript 或 Vue 组件时使用 npm run type-check。

完整的维护者门禁仍为：

make fmt
make lint
make test

make fmt 会格式化整个 Go 仓库，因此请仅在干净的工作区中运行，并审查生成的差异。部分全量测试套件需要本地基础设施或服务配置。如果全量检查因无关的基线或环境原因失败，请在 PR 中包含确切的命令和失败信息，同时仍为你的更改提供通过的针对性测试。

🔒 安全提示

重要： 从 v0.1.3 开始，WeKnora 包含登录认证功能以增强系统安全性。对于生产部署，我们强烈建议：

- 将 WeKnora 服务部署在内网/私有网络环境中，而非公网
- 避免将服务直接暴露到公网，以防止潜在的信息泄露
- 为你的部署环境配置适当的防火墙规则和访问控制
- 定期更新到最新版本以获取安全补丁和改进

👥 贡献者

感谢这些优秀的贡献者：

Contributors

📄 许可证

本项目基于 MIT 许可证 授权。
你可以自由使用、修改和分发代码，但需保留适当的署名。