Wiki 能力

上传一堆散乱的文档之后，你常常还是不知道「这批资料里到底有什么」。Wiki 就是为这件事准备的：文档入库后，WeKnora 用大模型从原文里抽出人物、产品、概念等条目，为每个条目生成一篇带出处的 Markdown 页面，页面之间互相链接，形成一个可以像维基百科一样浏览的知识站点。

它和普通问答的区别在于：问答是「你问我答」，Wiki 是「先替你把知识整理好」。资料越多、越零散，Wiki 的价值越明显。而且这些页面不只给人看——Agent 也能读写它们，把它当成长期记忆用；模型写错的地方你可以直接改，每次改动都留版本、可回滚（见「人工编辑与版本历史」）。

<Screenshot src="/screenshots/wiki-browser.png" caption="Wiki 浏览器：左侧目录树，右侧生成的条目页面与出处" hint="展示左侧按类型分组的目录树、一篇实体页正文、页内 wiki 链接与来源文档引用。" />

怎么开启

1. 编辑知识库 → 「索引策略」里打开 Wiki；
2. 上传文档（已有文档也会被纳入，无需重传）；
3. 等待生成。Wiki 生成是异步的，文档多时会持续一段时间，知识库面包屑上有「索引中」提示；
4. 完成后进入知识库的 Wiki 页签浏览，图谱页签可以看条目之间的链接关系。

生成过程要调大模型，成本与文档量成正比。抽取密度可以在知识库的 Wiki 配置里调（focused / standard / exhaustive，见下文「抽取粒度」）。

<Screenshot src="/screenshots/wiki-graph.png" caption="Wiki 图谱视图：条目之间的链接关系" hint="展示图谱概览模式，节点按页面类型着色，可点击跳转到具体页面。" />

页面模型与层级

页面类型（PageType）

internal/types/wiki_page.go 定义了 6 种页面类型：

页面状态（WikiPageStatus）：draft / published（默认）/ archived。

目录树（Folder Hierarchy）

migration 000061_wiki_page_hierarchy.up.sql 引入独立的 wiki_folders 表（邻接表模型）：

• WikiFolder 以 ParentID（空串代表根）+ 物化 Path（/ 连接的名称链）组织树；空文件夹可独立存在，用户可以先搭好骨架；
• WikiPage.FolderID 是页面归属的唯一事实来源（FK → wiki_folders.id，空串表示 wiki 根）；
• 页面上的 CategoryPath / WikiPath / Depth / SortOrder 是从 folder 链派生的缓存投影；
• 目录最深 3 级（常量 WikiCategoryMaxDepth = 3），CleanWikiCategoryPath() 会规范化全角分隔符（／、｜ → /）并剔除类型标签。

关键字段

• Slug：页面在 KB 内的唯一标识（见下节）；
• SourceRefs：来源引用，格式 "<knowledge_id>|<doc_title>"；ChunkRefs：分块级证据引用；
• InLinks / OutLinks：wiki-link 反向/正向链接，维护图结构，GET /graph 可查询全局或 ego 视图；
• Aliases：别名（用于搜索与去重合并后的旧名指向）；Version：版本号。

生成流程

Wiki 生成由文档摄入（knowledge ingest）触发，经 Redis 任务队列异步执行。任务类型定义在 internal/types/task.go：

TypeWikiIngest   = "wiki:ingest"
TypeWikiFinalize = "wiki:finalize"

整个管道分四个阶段（Map-Reduce 结构）：

辅助提示词：

• WikiTaxonomyPlanPrompt：为同一批次的所有实体/概念统一规划目录路径（最多 2 级、优先复用已有文件夹），保证目录树连贯；
• WikiDeduplicationPrompt：判断新抽取项是否与既有页面同指一物，核心原则是 "related ≠ same"（相关不等于相同），返回 { merges: { "entity/new": "entity/existing" } }。

抽取粒度

WikiConfig（存于 knowledge_bases.wiki_config JSONB 列）中的 WikiExtractionGranularity 控制抽取密度：

并发与批处理

WikiConfig 相关参数（internal/types/wiki_page.go）：

生成流程图

flowchart TD
    A["文档入库 (knowledge ingest)"] --> B["任务入队 wiki:ingest (Redis 队列)"]
    B --> C["Pass 0: 候选 slug 抽取
WikiCandidateSlugPrompt"]
    C --> D["Taxonomy 规划
WikiTaxonomyPlanPrompt 统一目录路径"]
    C --> E["Pass 1..N: 分块引文标注
WikiChunkCitationPrompt + prefix caching"]
    E --> F["去重判定
WikiDeduplicationPrompt (related ≠ same)"]
    F --> G["Reduce: 按 slug 并发写页面
WikiPageModifySystemPrompt
增量合并 / 新建, 强制引用接地"]
    D --> G
    G --> H["写入 wiki_pages
变更投影到知识库活动流 (audit)"]
    H --> I["任务入队 wiki:finalize
(TaskID = wiki-finalize-KBID, 同 KB 去重)"]
    I --> J["Finalize: 重建索引 / 清理死链 / 交叉链接
纯 SQL 与图算法, 无 LLM"]
    J --> K["published 页面在 WikiBrowser 可浏览
Agent 工具可读写"]

Slug 机制

• 格式：<type>/<name>，如 entity/acme-corp、concept/rag、summary/<knowledge-uuid>；小写、连字符分隔，非拉丁文名做罗马化/拼音；

• 唯一性：数据库唯一索引（000037_wiki_and_indexing.up.sql）：

  sqlCopy

  CREATE UNIQUE INDEX idx_kb_slug ON wiki_pages (knowledge_base_id, slug) WHERE deleted_at IS NULL
  

  即 slug 在单个知识库内唯一，跨 KB 可以重复；

• 稳定性：文档更新重新抽取时，提示词强制模型复用旧 slug——

  If an entity or concept from the previous extraction still exists in the current document, reuse its exact slug from the previous list. Do NOT generate a new slug for the same thing.

  只有新出现的事物才生成新 slug，消失的项不再输出；

• Slug Handle（句柄代理）：ingest 的 LLM 调用中，高熵的真实 slug（尤其含 UUID 的 summary/...）会被替换为短句柄（ref-1、ref-2），模型输出 [[ref-1|title]] 后由后端还原为真实 slug，避免模型抄错 UUID（internal/application/service/wiki_slug_handles.go）；

• 引用作用：Agent 回答中的 wiki 引用以 [[slug|title]] 形式出现，InLinks/OutLinks 依 slug 维护页面图；重命名 slug（wiki_rename_page 工具）会自动更新所有反向链接。

发布与访问

所有 Wiki 路由挂在 /api/v1/knowledgebase/:kb_id/wiki 之下（internal/router/router.go），没有免登录的公开访问模式，读写均受 RBAC 与 KB 访问控制约束：

读接口（Viewer + KBAccessRead）

KBAccessRead 覆盖：KB 所有者、组织共享、以及通过共享 Agent 获得的访问。

写接口（OwnedWikiKBOrAdmin + KBAccessWrite）

写权限按 KB 归属判定：贡献者只要拥有该 KB 即可管理其 wiki，否则 403。API Key 场景按 ingest / retrieve capability 映射。

前端由 WikiBrowser.vue 提供浏览界面；文档解析期间 wikiStatusRefresh.ts 轮询 parse_status（pending / processing / finalizing），解析完成而摘要仍在生成时继续轮询。目录树的展开状态由 wikiDirectoryState.ts 单独维护：新建文件夹或刷新数据后，expandWikiDirectoryPath() 会把当前路径上的各级目录标记为「用户已展开」，避免刷新时整棵树塌回默认折叠状态。

人工编辑与版本历史

Wiki 页面是 LLM 生成的，难免有需要人工订正的地方。页面因此支持直接编辑，并保留完整版本历史（migration 000075）。

每个版本记的是谁改的

wiki_pages 上有两个溯源字段，last_edit_source 标记当前版本的作者类型：

配套的 last_editor_id 记录操作者（后台管道写入时为空）。界面上据此区分「这段是模型写的还是人改的」。

快照与回滚

• 每次页面被覆盖前，旧版本先整份快照进 wiki_page_revisions（标题、正文、摘要、页面类型、状态、别名，加上该版本的作者与时间）；当前版本只存在于 wiki_pages 里。(page_id, version) 上的唯一索引配合 ON CONFLICT DO NOTHING，让「先快照再更新」这条写路径在重试下保持幂等；
• GET /revisions/*slug 列历史版本（倒序，不含正文，附当前版本号）；带 ?version=N 则取该版本全文，用于 diff；
• POST /revert 传 {slug, version} 回滚。回滚不是把版本号退回去，而是以目标版本的内容产生一个新版本，edit_source 记为 revert，因此回滚本身也可被回滚。回滚到当前版本会返回 400（通常意味着前端拿的是过期的历史列表）。

历史保留策略

无节制留快照会被管道刷爆，因此采用两级上限（internal/types/wiki_page.go）：

• 软上限 50 版：只清理「可裁剪」的快照，即 pipeline 写的和历史遗留的空来源；
• 硬上限 200 版：不分作者一律裁剪，保证纯人工维护的页面存储也有界。

这样设计的用意是：一个热点页面被管道反复重写时，不会把用户真正在意的人工编辑挤出历史。

<Screenshot src="/screenshots/wiki-revision-history.png" caption="Wiki 页面版本历史：按来源区分的版本列表与回滚入口" hint="展示某个 wiki 页面的历史抽屉，含版本号、编辑来源（管道/人工/Agent/回滚）、编辑者与时间，以及对比/回滚按钮。" />

与 Agent 的关系

Wiki 不只是给人看的——它是 Agent 的一等公民工作区。internal/agent/tools/definitions.go 注册了 10 个 wiki 工具：

工具输出为 XML-like 结构（<wiki_page><metadata>...<summary>...<content>...），前端用 frontend/src/utils/wikiToolReferences.ts 的 parseWikiToolReferences() 解析成引用卡片渲染在对话中。

配套机制：

• Wiki Scope：Agent 会话内维护 wiki KB 白名单，支持通过 @mention 把范围收窄到特定文档/标签，工具执行时自动过滤 source_refs（internal/agent/tools/wiki_tools.go）；
• Wiki Fixer：内置 Agent（types.BuiltinWikiFixerID），负责自动修复 wiki 问题（死链、实体混淆等）。跨租户访问共享 KB 时要求租户角色 ≥ Editor，并自动提升到源租户上下文（internal/handler/session/wiki_fixer_scope.go）；
• 问题闭环：wiki_page_issues 表 + lint 接口 + auto-fix，人和 Agent 都可以报告/处理问题。

操作历史（知识库活动流）

Wiki 曾经维护一份独立的操作日志（wiki_log_entries 表 + GET /wiki/log 接口 + WikiBrowser 里的日志页签）。这份 feed 与知识库活动流内容重叠，已在 migration 000077_remove_wiki_log 中整体移除：表被 DROP，历史遗留的 page_type = 'log' 页面一并删除，log 不再是合法页面类型。

现在知识库活动流是唯一的操作历史入口：

• ingest 批次结束时，wiki_ingest_batch.go 汇总本批各类动作数量，调用 service.RecordWikiContentActivity() 写一条 wiki_content_changed 活动；
• 人工在 WikiBrowser 中创建/更新/删除页面时，internal/handler/wiki_page.go 同样把 manual_create / manual_update / manual_delete 投影到活动流；
• 活动记录落在审计日志体系（kb_activity.go → AuditLogService），可在「知识库 → 设置 → 活动」查看，保留策略与其它审计日志一致（见可观测性与审计）；
• 写入是 best-effort：活动记录失败不会让 wiki 编辑本身失败。

升级注意：如果外部集成还在调用 GET /api/v1/knowledgebase/:kb_id/wiki/log，需要改用知识库活动流接口 GET /api/v1/knowledge-bases/:id/activity。

失败恢复

internal/container/recover_pending_wiki_tasks.go 在服务启动时闭合 Lite 模式（进程内 SyncTaskExecutor）或 Redis 入队中断留下的缺口：

1. 扫描持久化的 task_pending_ops 表中 scope = knowledge_base 且 task_type ∈ {wiki:ingest, wiki:finalize} 的待处理组合；
2. 清理已删除 KB 的残留行（fail-closed）；
3. 对每个活跃 KB 重新入队触发任务：wiki:ingest 不带 TaskID（允许多批并发），wiki:finalize 使用 "wiki-finalize-" + KB_ID 去重（同一 KB 只保留一个 finalize）。重复入队无害——ingest 认领互不相交的行，finalize 在 lane 内合并。

实现参考

想读源码时按下表定位（路径相对仓库根目录）：