docs: 新增agent开发文档和风险评估文档

2026-05-15 06:58:21 +00:00
parent 45abd36430
commit 4f3556a38b
35 changed files with 8257 additions and 0 deletions
--- a/plan/12_llm_wiki_knowledge_architecture.md
+++ b/plan/12_llm_wiki_knowledge_architecture.md
@@ -0,0 +1,221 @@
+# 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: 条款抽取和规则候选
+```