# LLM Wiki 知识库架构

## 1. 定位

LLM Wiki 不是简单的文件库。

它是给 Agent 使用的知识底座，负责把制度、FAQ、审批经验、规则说明转成可检索、可引用、可版本化的知识。

## 2. 总体链路

```text
文档上传
  ↓
格式解析
  ↓
正文抽取
  ↓
分块 Chunking
  ↓
元数据标注
  ↓
向量索引
  ↓
条款抽取
  ↓
知识候选
  ↓
人工审核
  ↓
发布 Wiki
  ↓
Agent 检索引用
```

## 2.1 目录约束

LLM Wiki 解析产物不能与原始制度文件混放。

推荐目录：

```text
/app/server/storage/knowledge/<folder>/                原始知识文件
/app/server/storage/knowledge/.llm_wiki/              解析产物根目录
/app/server/storage/knowledge/.llm_wiki/documents/<document_id>/
  document.json
  text.md
  chunks.json
  clauses.json
  knowledge_candidates.json
  rule_candidates.json
/app/server/storage/knowledge/.llm_wiki/index.json
/app/server/storage/knowledge/.llm_wiki/sync_runs.json
```

约束：

- 原始文件目录只存原件，不存解析碎片。
- LLM Wiki 目录只存结构化产物，不反向覆盖原件。
- 所有解析产物必须能按 `document_id` 回溯到原始文件。

## 3. 知识类型

```text
policy_document
faq
rule_explanation
approval_case
risk_case
operation_manual
system_notice
```

## 4. 知识块结构

```json
{
  "chunk_id": "",
  "document_id": "",
  "title": "",
  "content": "",
  "domain": "reimbursement",
  "scenario": "travel_reimbursement",
  "tags": ["差旅", "住宿标准"],
  "effective_date": "",
  "version": "v1.0",
  "source_page": 4,
  "embedding_id": "",
  "status": "published"
}
```

## 5. 条款抽取

Hermes 可以从制度文档中抽取条款候选。

示例：

```json
{
  "clause_type": "amount_limit",
  "domain": "reimbursement",
  "scenario": "travel_reimbursement",
  "condition": {
    "city_tier": "一线城市",
    "employee_grade": "P5"
  },
  "limit": {
    "amount": 800,
    "currency": "CNY",
    "period": "night"
  },
  "source": "差旅制度 2026 第 4 页"
}
```

该结果不直接变成规则，先进入规则候选池。

## 5.1 增量形成策略

LLM Wiki 不应按天无脑全量重建。

每个文档都应维护签名：

```json
{
  "document_id": "",
  "original_name": "",
  "stored_name": "",
  "sha256": "",
  "version_number": 1,
  "updated_at": ""
}
```

只有在以下任一条件发生时，才重建对应文档的 LLM Wiki：

- `original_name` 变更。
- `stored_name` 变更。
- `sha256` 变更。
- `version_number` 变更。
- `updated_at` 变更，视为人工修改。

如果以上均未变化：

- 本次文档状态应记为 `unchanged_skipped`。
- 不重新抽取正文。
- 不重新分块。
- 不重新生成知识候选或规则候选。

## 6. Wiki 发布流程

```text
草稿知识
  ↓
Hermes 生成候选
  ↓
知识管理员审核
  ↓
发布
  ↓
Agent 可检索
```

## 7. 与 User Agent 的关系

User Agent 用 Wiki：

- 回答制度问题。
- 给风险解释提供条款依据。
- 给审批意见生成引用。
- 帮用户理解流程。

## 8. 与 Hermes 的关系

Hermes 用 Wiki：

- 每日知识候选生成。
- 发现制度与规则不一致。
- 生成规则优化建议。
- 生成 FAQ 候选。

补充要求：

- Hermes 对制度文档的处理默认是增量同步，不是每日全量重建。
- Hermes 应先检查知识库签名，再决定是否需要重建某个文档的 Wiki。
- Hermes 形成的是候选与草稿，不是正式发布内容。

## 9. 数据模型建议

```text
knowledge_documents
knowledge_chunks
knowledge_embeddings
knowledge_candidates
knowledge_reviews
knowledge_versions
```

当前最小落地允许先以文件索引实现：

```text
.llm_wiki/index.json
.llm_wiki/sync_runs.json
.llm_wiki/documents/<document_id>/document.json
```

后续再平滑迁移到数据库或向量库。

## 10. 开发阶段建议

```text
Step 1: 文档上传和文件管理
Step 2: 文本抽取和分块
Step 3: 元数据标注
Step 4: 向量索引
Step 5: 知识检索 API
Step 6: User Agent 问答引用
Step 7: Hermes 知识候选生成
Step 8: 人工审核发布
Step 9: 条款抽取和规则候选
```