WeKnora deployment source with the reviewed wiki identity, summary and recovery fixes

2026-09-22 16:19:06 +08:00
commit f7fc992f57
3929 changed files with 1006607 additions and 0 deletions
@@ -0,0 +1,104 @@
+---
+title: Agent技能系统
+tags: [核心功能, Agent, Skills, 技能, 沙箱]
+aliases: [Agent Skills, 技能系统, agent-skills]
+source: agent-skills.md
+---
+
+# Agent 技能系统
+
+## 概述
+
+Agent Skills 是一种让 Agent 通过阅读"使用说明书"来学习新能力的扩展机制。与传统的硬编码工具不同，Skills 通过注入到 System Prompt 来扩展 Agent 的能力，遵循 **Progressive Disclosure（渐进式披露）** 的设计理念。目前仅支持带**智能推理**能力的智能体使用。
+
+### 核心特性
+
+- **非侵入式扩展**：不影响原有 Agent ReAct 流程
+- **按需加载**：三级渐进式加载，优化 Token 使用
+- **沙箱执行**：脚本在隔离环境中安全执行
+- **灵活配置**：支持多目录、白名单过滤
+
+> Skills 与 [MCP](../核心功能/MCP功能使用说明.md) 是两种不同的 Agent 扩展机制：Skills 通过 Prompt 注入，MCP 通过协议调用外部工具。
+
+## 设计理念
+
+### Progressive Disclosure（渐进式披露）
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ Level 1: 元数据 (Metadata)                                      │
+│ • 始终加载到 System Prompt • 约 100 tokens/skill                  │
+│ • 包含：技能名称 + 简短描述                                       │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓ 用户请求匹配时
+┌─────────────────────────────────────────────────────────────────┐
+│ Level 2: 指令 (Instructions)                                    │
+│ • 通过 read_skill 工具按需加载 • SKILL.md 的指令内容              │
+│ • 包含：详细指令、代码示例、使用方法                               │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓ 需要更多信息时
+┌─────────────────────────────────────────────────────────────────┐
+│ Level 3: 附加资源 (Resources)                                   │
+│ • 通过 read_skill 工具加载特定文件                               │
+│ • 通过 execute_skill_script 执行脚本                            │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Skill 目录结构
+
+```
+my-skill/
+├── SKILL.md           # 必需：主文件（含 YAML frontmatter）
+├── REFERENCE.md       # 可选：补充文档
+├── templates/         # 可选：模板文件
+└── scripts/           # 可选：可执行脚本
+```
+
+## 预加载技能
+
+系统内置了以下 5 个预加载技能：
+
+| 技能 | 用途 |
+|------|------|
+| citation-generator | 自动生成规范引用格式 |
+| data-processor | 数据处理与分析 |
+| doc-coauthoring | 引导用户完成结构化文档创作 |
+| document-analyzer | 深度分析文档结构和内容 |
+| summary-generator | 内容摘要生成 |
+
+预加载技能位于 `skills/preloaded/` 目录下。
+
+## 沙箱安全机制
+
+### 脚本安全校验
+
+执行前进行多层安全校验：危险命令检测、危险模式匹配、网络访问检测、反向 Shell 检测、参数注入检测等。
+
+### Sandbox 配置
+
+空间管理员在「设置 → 沙箱后端」中统一维护 Docker、CubeSandbox 或 E2B 配置。远端模板从目标集群实时获取；缺少 WeKnora 标准模板时由系统自动创建。智能体在编辑页选择一份空间配置，没有选择时不执行技能脚本。Docker、CubeSandbox、E2B 均保留会话级沙箱。
+
+## 配置示例
+
+```json
+{
+  "skills_enabled": true,
+  "skill_dirs": ["/path/to/project/skills"],
+  "allowed_skills": ["pdf-processing", "code-review"]
+}
+```
+
+## 相关主题
+
+- [MCP功能使用说明](MCP功能使用说明.md) — 另一种 Agent 扩展机制
+- [IM集成开发](../集成扩展/IM集成开发.md) — Agent 可通过 IM 渠道使用技能
+- [开发指南](../开发部署/开发指南.md) — 沙箱镜像的构建
+
+---
+
+## 反向链接
+
+- [Home](../Home.md) — Wiki 首页导航
+- [MCP功能使用说明](MCP功能使用说明.md) — 与 Skills 并列的 Agent 扩展机制
+- [IM集成开发](../集成扩展/IM集成开发.md) — Agent 在 IM 渠道中可使用技能
+- [版本路线图](../项目概述/版本路线图.md) — 路线图中的 Skills 社区扩展方向
@@ -0,0 +1,66 @@
+---
+title: MCP功能使用说明
+tags: [核心功能, MCP, 工具集成]
+aliases: [MCP使用, MCP功能]
+source: MCP功能使用说明.md
+---
+
+# MCP 功能使用说明
+
+## 功能概述
+
+- MCP（Model Context Protocol）让 WeKnora 可以安全地连接外部工具或数据源，扩展 Agent 在推理时可调用的能力。
+- 在前端 `设置 > MCP 服务`（`frontend/src/views/settings/McpSettings.vue`）中集中管理所有服务，无需手动改配置文件。
+- 每个服务都包含名称、传输方式（SSE / HTTP Streamable / Stdio）、连接地址或命令、认证信息以及高级超时与重试策略。
+
+> 关于系统级的内置 MCP 服务管理，参见 [内置MCP服务管理](内置MCP服务管理.md)
+
+## 入口与界面
+
+- 打开控制台左侧菜单 `设置 -> MCP 服务`，即可看到当前空间下的所有 MCP 服务列表。
+- 列表中可快速启停服务、查看描述，并通过右侧菜单执行"测试 / 编辑 / 删除"。
+- "添加服务"按钮会弹出 `McpServiceDialog`，用于创建或修改服务。
+
+## 常用操作流程
+
+### 1. 新建服务
+
+- 点击"添加服务"，填写名称与描述，选择传输方式。
+- SSE / HTTP Streamable 需提供可访问的服务 URL；Stdio 需配置 `uvx`/`npx` 命令与参数，可附加环境变量。
+- 根据需要填写 API Key、Bearer Token、超时与重试策略，保存后服务会出现在列表中。
+
+### 2. 启停服务
+
+- 在列表开关中切换启用状态，系统会即时调用后端 `updateMCPService`，失败时会自动回滚状态并弹出提示。
+
+### 3. 连接测试
+
+- 通过更多菜单选择"测试"，前端会调用 `/api/v1/mcp-services/{id}/test` 并弹出 `McpTestResult`。
+- 成功时会展示服务可用的工具清单（含输入 schema）和资源列表；失败时会显示错误信息，方便排查网络或鉴权问题。
+
+### 4. 编辑 / 删除
+
+- "编辑"会带出原有配置，修改后保存即可。
+- "删除"需要在弹窗中确认，完成后列表自动刷新。
+
+## 使用建议
+
+- **传输方式选择**：优先使用 SSE 获取流式体验；需要标准 HTTP Streamable 兼容时再切换；本地调试或离线环境适合使用 Stdio 并在同机启动 MCP Server。
+- **鉴权管理**：将 API Key / Token 保存在"认证配置"中，生产环境建议单独创建最小权限 Key，并定期轮换。
+- **重试策略**：对公网或第三方服务适当提高 `retry_count` 与 `retry_delay`，避免间歇性超时导致 Agent 中断
+
+## 相关主题
+
+- [内置MCP服务管理](../核心功能/内置MCP服务管理.md) — 系统管理员视角的内置 MCP 服务配置
+- [Agent技能系统](Agent技能系统.md) — 另一种 Agent 扩展机制
+- [IM集成开发](../集成扩展/IM集成开发.md) — IM 渠道中 Agent 使用 MCP 工具
+- [添加网络搜索引擎](../集成扩展/添加网络搜索引擎.md) — 扩展搜索能力的另一种方式
+
+---
+
+## 反向链接
+
+- [Home](../Home.md) — Wiki 首页导航
+- [内置MCP服务管理](内置MCP服务管理.md) — MCP 的系统级管理（管理员视角）
+- [Agent技能系统](Agent技能系统.md) — 与 MCP 并列的 Agent 扩展机制
+- [IM集成开发](../集成扩展/IM集成开发.md) — Agent 在 IM 渠道中可调用 MCP 工具
@@ -0,0 +1,105 @@
+---
+title: 内置MCP服务管理
+tags: [核心功能, MCP, 系统管理, 内置服务]
+aliases: [内置MCP, BuiltinMCP, BUILTIN_MCP_SERVICES]
+source: BUILTIN_MCP_SERVICES.md
+---
+
+# 内置 MCP 服务管理指南
+
+## 概述
+
+内置 MCP 服务是系统级别的 MCP（Model Context Protocol）服务配置，对所有空间可见，但敏感信息会被隐藏，且不可编辑或删除。内置 MCP 服务通常用于提供系统默认的外部工具和资源接入，确保所有空间都能使用统一的 MCP 服务。
+
+> 用户视角的 MCP 服务操作参见 [MCP功能使用说明](MCP功能使用说明.md)
+
+## 内置 MCP 服务特性
+
+- **所有空间可见**：内置 MCP 服务对所有空间都可见，无需单独配置
+- **安全保护**：内置 MCP 服务的敏感信息（URL、认证配置、Headers、环境变量）会被隐藏，无法查看详情
+- **只读保护**：内置 MCP 服务不能被编辑或删除，仅支持测试连接
+- **统一管理**：由系统管理员统一维护，确保配置一致性和安全性
+
+## 与内置模型的对比
+
+| 特性 | 内置模型 | 内置 MCP 服务 |
+|------|---------|--------------|
+| 标识字段 | `is_builtin` | `is_builtin` |
+| 可见范围 | 所有空间 | 所有空间 |
+| 隐藏信息 | API Key、Base URL | URL、认证配置、Headers、环境变量 |
+| 编辑保护 | 不可编辑/删除 | 不可编辑/删除 |
+| 前端标签 | 显示"内置"标签 | 显示"内置"标签 |
+| 启停控制 | — | 禁用开关（始终启用） |
+
+> 内置模型的详细管理参见 [内置模型管理](内置模型管理.md)
+
+## 如何添加内置 MCP 服务
+
+内置 MCP 服务需要通过数据库直接插入。
+
+### 1. 准备服务数据
+
+- 服务名称（name）
+- 服务描述（description）
+- 传输方式（transport_type）：`sse` 或 `http-streamable`
+- 服务地址（url）
+- 认证配置（auth_config）
+- 高级配置（advanced_config）
+- 空间ID（tenant_id）：建议使用小于 10000 的空间ID
+
+**支持的传输方式**：
+- `sse`：Server-Sent Events，推荐用于流式体验
+- `http-streamable`：HTTP Streamable，标准 HTTP 兼容
+
+> 注意：出于安全考虑，`stdio` 传输方式在服务端已被禁用。
+
+### 2. 执行 SQL 插入语句
+
+```sql
+INSERT INTO mcp_services (
+    id, tenant_id, name, description, enabled,
+    transport_type, url, auth_config, advanced_config, is_builtin
+) VALUES (
+    'builtin-mcp-001', 10000, 'Web Search', '内置 Web 搜索 MCP 服务',
+    true, 'sse', 'https://mcp.example.com/sse',
+    '{"api_key": "your-api-key"}'::jsonb,
+    '{"timeout": 30, "retry_count": 3, "retry_delay": 1}'::jsonb,
+    true
+) ON CONFLICT (id) DO NOTHING;
+```
+
+### 3. 验证插入结果
+
+```sql
+SELECT id, name, transport_type, enabled, is_builtin
+FROM mcp_services WHERE is_builtin = true ORDER BY created_at;
+```
+
+## 注意事项
+
+1. **ID 命名规范**：建议使用 `builtin-mcp-{序号}` 格式
+2. **空间ID**：建议使用第一个空间ID（通常是 10000）
+3. **JSON 格式**：`auth_config`、`advanced_config`、`headers` 必须是有效的 JSON
+4. **幂等性**：使用 `ON CONFLICT (id) DO NOTHING` 确保重复执行不会报错
+5. **安全性**：内置 MCP 服务的 URL、认证信息在前端会被自动隐藏
+6. **传输方式限制**：仅支持 `sse` 和 `http-streamable`
+
+## 将现有 MCP 服务设置为内置服务
+
+```sql
+UPDATE mcp_services SET is_builtin = true WHERE id = '服务ID' AND name = '服务名称';
+```
+
+## 移除内置 MCP 服务
+
+```sql
+UPDATE mcp_services SET is_builtin = false WHERE id = '服务ID';
+```
+
+---
+
+## 反向链接
+
+- [Home](../Home.md) — Wiki 首页导航
+- [MCP功能使用说明](MCP功能使用说明.md) — 用户视角的 MCP 服务操作
+- [内置模型管理](内置模型管理.md) — 同为内置系统配置，模式相似
@@ -0,0 +1,83 @@
+---
+title: 内置模型管理
+tags: [核心功能, 模型, 系统管理, 内置服务]
+aliases: [内置模型, BuiltinModel, BUILTIN_MODELS]
+source: BUILTIN_MODELS.md
+---
+
+# 内置模型管理指南
+
+## 概述
+
+内置模型是系统级别的模型配置，对所有空间可见，但敏感信息会被隐藏，且不可编辑或删除。内置模型通常用于提供系统默认的模型配置，确保所有空间都能使用统一的模型服务。
+
+> 同为内置系统配置的还有 [内置MCP服务管理](内置MCP服务管理.md)
+
+## 内置模型特性
+
+- **所有空间可见**：无需单独配置
+- **安全保护**：API Key、Base URL 被隐藏
+- **只读保护**：不能被编辑或删除，只能设置为默认模型
+- **统一管理**：由系统管理员统一维护
+
+## 如何添加内置模型
+
+### 1. 准备模型数据
+
+- 模型名称（name）
+- 模型类型（type）：`KnowledgeQA`、`Embedding`、`Rerank` 或 `VLLM`
+- 模型来源（source）：`local` 或 `remote`
+- 模型参数（parameters）：包括 base_url、api_key、provider 等
+- 空间ID（tenant_id）：建议使用小于10000的空间ID
+
+**支持的服务商（provider）**：`generic`、`openai`、`aliyun`、`zhipu`、`volcengine`、`hunyuan`、`deepseek`、`minimax`、`mimo`、`siliconflow`、`jina`、`openrouter`、`litellm`、`requesty`、`gemini`、`modelscope`、`moonshot`、`qianfan`、`qiniu`、`longcat`、`gpustack`
+
+### 2. 执行 SQL 插入语句
+
+```sql
+-- LLM 内置模型
+INSERT INTO models (
+    id, tenant_id, name, type, source, description, parameters,
+    is_default, status, is_builtin
+) VALUES (
+    'builtin-llm-001', 10000, 'GPT-4', 'KnowledgeQA', 'remote',
+    '内置 LLM 模型',
+    '{"base_url": "https://api.openai.com/v1", "api_key": "sk-xxx", "provider": "openai"}'::jsonb,
+    false, 'active', true
+) ON CONFLICT (id) DO NOTHING;
+
+-- Embedding 内置模型
+INSERT INTO models (...) VALUES (...) ON CONFLICT (id) DO NOTHING;
+
+-- Rerank 内置模型
+INSERT INTO models (...) VALUES (...) ON CONFLICT (id) DO NOTHING;
+```
+
+### 3. 验证
+
+```sql
+SELECT id, name, type, is_builtin, status
+FROM models WHERE is_builtin = true ORDER BY type, created_at;
+```
+
+## 注意事项
+
+1. **ID 命名规范**：建议使用 `builtin-{type}-{序号}` 格式
+2. **空间ID**：建议使用第一个空间ID（通常是 10000）
+3. **参数格式**：`parameters` 字段必须是有效的 JSON 格式
+4. **幂等性**：使用 `ON CONFLICT (id) DO NOTHING`
+5. **安全性**：API Key 和 Base URL 在前端会被自动隐藏
+
+## 模型配置与常见问题
+
+- 如果 Embedding 模型未正确配置，会导致文档无法上传。排查步骤参见 [常见问题](../运维排障/常见问题.md)
+- 模型参数中的 `provider` 决定了 API 调用格式和认证方式
+
+---
+
+## 反向链接
+
+- [Home](../Home.md) — Wiki 首页导航
+- [内置MCP服务管理](../核心功能/内置MCP服务管理.md) — 同为内置系统配置，模式相似
+- [常见问题](../运维排障/常见问题.md) — 模型配置相关的故障排查
+- [版本路线图](../项目概述/版本路线图.md) — 路线图中模型训练方向
@@ -0,0 +1,104 @@
+---
+title: 开启知识图谱功能
+tags: [核心功能, 知识图谱, Neo4j, 配置]
+aliases: [知识图谱配置, KnowledgeGraphSetup]
+source: 开启知识图谱功能.md
+---
+
+# 开启知识图谱功能
+
+本文档介绍如何在 WeKnora 中启用并验证知识图谱（Neo4j）功能，帮助你完成从环境准备到前端配置的全流程。
+
+## 前置条件
+
+- 已完成 WeKnora 后端与前端的基础部署
+- 具备可用的 Docker/Docker Compose 运行环境
+- 本地或远端可访问的 Neo4j 服务（推荐使用项目自带的 Docker Compose）
+
+> 快速入门参见 [知识图谱](知识图谱.md)
+
+## 步骤一：配置环境变量
+
+在项目根目录的 `.env` 文件中新增或修改以下变量：
+
+```
+NEO4J_ENABLE=true
+NEO4J_URI=bolt://neo4j:7687
+NEO4J_USERNAME=neo4j
+NEO4J_PASSWORD=your_strong_password
+# 可选：NEO4J_DATABASE=neo4j
+```
+
+说明：
+
+- `NEO4J_ENABLE` 设置为 `true` 才会启用知识图谱相关逻辑
+- `NEO4J_URI` 中的 `neo4j` 为 docker-compose 服务名，如使用外部实例请替换为实际地址
+- 如果生产环境使用密钥管理，请确保密码通过安全方式注入
+
+## 步骤二：启动 Neo4j 服务
+
+项目附带 Neo4j 组件，可直接用以下命令启动：
+
+```bash
+docker-compose --profile neo4j up -d
+```
+
+常见验证命令：
+
+```bash
+docker ps | grep neo4j
+```
+
+> 开发环境中 Neo4j 的启动方式参见 [开发指南](../开发部署/开发指南.md)
+
+## 步骤三：重启 WeKnora 服务
+
+为了让新的环境变量生效，重启后端与前端：
+
+```bash
+make stop && make start
+# 或者
+docker compose up -d --build
+```
+
+确保后端日志中出现 `neo4j` 初始化成功的提示。
+
+## 步骤四：在前端启用实体/关系抽取
+
+1. 登录 WeKnora 前端管理页面
+2. 打开「知识库设置」或创建新的知识库
+3. 勾选「启用实体抽取」与「启用关系抽取」开关
+4. 根据界面提示补充所需的 LLM、回调或模型参数（若有）
+
+保存后，系统会在文档入库阶段自动触发实体与关系抽取任务。
+
+## 步骤五：验证知识图谱
+
+### 方式一：Neo4j 控制台
+
+1. 访问 `http://localhost:7474`（或对应主机/端口）
+2. 使用 `.env` 中的账号密码登录
+3. 执行 `MATCH (n) RETURN n LIMIT 50;` 检查是否有新节点/关系
+
+### 方式二：WeKnora 界面
+
+在知识库或对话页面中上传文档后，前端应展示图谱可视化入口；对话时系统会自动根据意图查询图谱并返回补充信息。
+
+## 常见问题排查
+
+- **无法连接 Neo4j**：确认网络可达、`NEO4J_URI` 与用户名密码正确，并检查 Neo4j 容器日志
+- **未生成节点**：确认知识库已开启实体/关系抽取，且上传的文档已完成解析；查看后端日志中是否有抽取任务异常
+- **查询无结果**：尝试在 Neo4j 控制台执行 `CALL db.schema.visualization;` 查看 schema 是否存在，必要时重新导入文档
+
+> 更多排查建议参见 [常见问题](../运维排障/常见问题.md)
+
+完成以上步骤后，知识图谱功能即成功启用，可结合 RAG 及 Agent 流程提升问答质量。
+
+---
+
+## 反向链接
+
+- [Home](../Home.md) — Wiki 首页导航
+- [知识图谱](知识图谱.md) — 知识图谱快速入门（本页的精简版）
+- [开发指南](../开发部署/开发指南.md) — 开发环境中 Neo4j 的启动与配置
+- [常见问题](../运维排障/常见问题.md) — 图谱功能相关的故障排查
@@ -0,0 +1,50 @@
+---
+title: 知识图谱
+tags: [核心功能, 知识图谱, Neo4j]
+aliases: [KnowledgeGraph, 图谱]
+source: KnowledgeGraph.md
+---
+
+# 知识图谱
+
+## 快速开始
+
+- .env 配置相关环境变量
+    - 启用 Neo4j: `NEO4J_ENABLE=true`
+    - Neo4j URI: `NEO4J_URI=bolt://neo4j:7687`
+    - Neo4j 用户名: `NEO4J_USERNAME=neo4j`
+    - Neo4j 密码: `NEO4J_PASSWORD=password`
+
+- 启动 Neo4j
+```bash
+docker-compose --profile neo4j up -d
+```
+
+- 在知识库设置页面启用实体和关系提取，并根据提示配置相关内容
+
+> 详细的启用步骤参见 [开启知识图谱功能](开启知识图谱功能.md)
+
+## 生成图谱
+
+上传任意文档后，系统会自动提取实体和关系，并生成对应的知识图谱。
+
+![知识图片示例](../../images/graph3.png)
+
+## 查看图谱
+
+登录 `http://localhost:7474`，执行 `match (n) return (n)` 即可查看生成的知识图谱。
+
+在对话时，系统会自动查询知识图谱，并获取相关知识。
+
+## 相关主题
+
+- [开启知识图谱功能](../核心功能/开启知识图谱功能.md) — 知识图谱功能的完整启用指南
+- [常见问题](../运维排障/常见问题.md) — 知识图谱相关的故障排查
+
+---
+
+## 反向链接
+
+- [Home](../Home.md) — Wiki 首页导航
+- [开启知识图谱功能](开启知识图谱功能.md) — 本页的详细版本，包含完整的启用流程
+- [开发指南](../开发部署/开发指南.md) — 开发环境中 Neo4j 的配置与启动