知识库系统

知识库（KB）为 agent 提供可检索的团队知识。位于 knowledge/{kb_id}/。基于 llm-wiki 模式设计。

目录结构

knowledge/{kb_id}/
├── purpose.md               # KB 用途描述
├── schema.md                # 页面格式规则 + 工作流指令
├── index.md                 # 页面索引（自动维护，[[slug]] — 摘要）
├── log.md                   # 操作日志（grep 可解析：## [YYYY-MM-DD]）
├── raw/
│   └── sources/             # 原始文档（不可变，用户提供）
└── wiki/
    ├── entities/            # 实体页面（事物、工具、项目）
    ├── concepts/            # 概念页面（思想、模式、技术）
    └── overview.md          # 合成综述（可选）

Schema 工作流

定义于 knowledge/{kb_id}/schema.md，包含三套工作流指令：

Ingest Workflow：如何读取源 → 创建页面 → 更新关联页面的 cross-refs
Query Workflow：如何读 index → 钻取页面 → 合成答案 → 沉淀好答案
Lint Workflow：定期检查孤儿页、断链、矛盾

schema 由 LLM 和人类共同演化，是知识库持续维护的核心。

摄取流程

定义于 cococat/ingest/。三阶段 LLM 管道：

阶段一: 分析
  LLM 分析源文件 → 输出结构化 JSON（title, type, summary, entities, concepts, tags, related）

阶段二: 生成
  LLM 生成 wiki 页面（Markdown + YAML frontmatter），使用 [[Wikilink]] 格式

阶段三: 更新（llm-wiki 模式）
  1. 创建新页面
  2. 更新 index.md（带 summary 字段）
  3. LLM 更新每个关联页面的内容（添加新信息、更新 related frontmatter）
  4. 追加 log.md

一个源文件通常涉及 5-15 个现有页面的更新。

搜索机制

search_kb 工具的执行流程：

1. Token 化: 查询拆分为 token (英文 + CJK 双字母组)
2. 加权评分: 文件名匹配 +200, 标题匹配 +50, 行匹配 +20
3. 图扩展: 通过 frontmatter 的 related 字段找到关联页面
4. 预算控制: 按评分排序，累计 ≤ 8000 字符
5. 返回片段: 命中行前后 1-3 行上下文

交叉引用（Wikilink）

所有页面使用 [[Wikilink]] 格式：

[[slug]] 或 [[slug|显示文本]]
前端自动解析为可点击的页面内链接
后端 lint 工具检测断链和孤儿页

三个对齐版本

本次会话对知识库系统进行了三次 llm-wiki 对齐：

版本	内容
v1	多页关联 Ingest / lint 工具 / save_to_kb / [[Wikilink]] 格式
v2	Schema 工作流 / Ingest Phase 3 内容更新 / Index 摘要 / Log 格式 / 系统提示
v3	现有页面 Wikilink 转换 / 全操作日志 / clip_to_kb / Overview 合成 / Schema 精简

场景挂载

scenes/{scene_id}/mounted_kbs.json：

json

{"mounted": ["team-wiki"], "search_mode": "token"}

每个场景可挂载不同知识库。agent 只感知到本场景已挂载的知识库。挂载的 KB 信息和页面索引通过 ## Your Wiki Knowledge 注入系统提示。

维护操作

以下操作不再作为独立工具，改为通过系统提示的 ## Wiki Maintenance schema 引导 LLM 使用通用工具完成：

操作	使用工具
健康检查	`grep` + `read_file` 遍历检查孤儿页、断链
保存 Q&A	`write_file` 写入 wiki 目录
剪藏网页	`web_fetch` + `write_file` 存到 raw/sources/
生成综述	`read_file` 遍历 + `write_file`

知识库系统 ​

目录结构 ​

Schema 工作流 ​

摄取流程 ​

搜索机制 ​

交叉引用（Wikilink） ​

三个对齐版本 ​

场景挂载 ​

维护操作 ​