:memo: 完善agent

dashboard-v4/documents/development/search.md

@@ -4,17 +4,22 @@
 
 构建一个基于 **OpenSearch** 的佛教文献检索系统，支持 **巴利文、中文、英文** 的多语种搜索，覆盖经文、译文、字典等资源，满足以下核心需求：
 
-- 支持 **巴利文格位归一化搜索**（lemma 化）
-- 支持 **中文多粒度分词**（词组 / 单字）
+- 支持 **巴利文格位归一化搜索**（ synonyms 等效单词表）
 - 支持 **简繁体互查**
 - 支持 **Markdown 内容** 的搜索，并对 **黑体加权**
 - 支持 **页码标记搜索**
 - 支持 **语义相似搜索**（向量检索）
 - 支持 **跨语言搜索** （多语言 embedding 模型 + 向量检索 ）
+- 支持 **模糊搜索和精确搜索**
+- suggestion 支持 巴利字符英文字母化
+
+三层设计 数据层，api 层 , 交互层 满足简单查询到 RAG 的不同需求
 
 ---
 
-## 2. 数据类型
+## 数据层
+
+### 2. 数据类型
 
 系统需要存储和检索以下资源：
 
@@ -26,42 +31,100 @@
 2. **巴利语经文**
 
    - 标题（title）
-   - 内容（content, markdown 格式 ， sutta,paragraph sentence 三个级别，编号 放在 related_id 字段 如 93-6）
-   - 包含 lemma 化后的文本
+   - 内容（content, markdown 格式 ， 多个颗粒度，编号 放在 related_id 字段 如 93-6）
+   - 包含 embedding 化后的文本
 
 3. **译文**
 
    - 标题（title）
-   - 内容（与巴利文同结构，但是没有 sentence 级别）
+   - 内容（与巴利文同结构）
 
 ---
 
-## 3. 字段需求
-
-### 核心字段
-
-| 字段             | 类型         | 说明                                                                 |
-| ---------------- | ------------ | -------------------------------------------------------------------- |
-| `id`             | string       | 文档唯一 ID                                                          |
-| `resource_id`    | uuid         | 文档在数据库中的 id                                                  |
-| `resource_type`  | string       | 文档类型，例如 article / term / dictionary / translation / pali_text |
-| `title`          | string       | 文档标题，可以是中文或巴利文                                         |
-| `summary`        | string       | 文档摘要 纯文本                                                      |
-| `content`        | string       | 文档主体内容，支持 Markdown，可能包含黑体字                          |
-| `content_vector` | dense_vector | 文档主体内容的 embedding，                                           |
-| `related_id`     | string       | 用于关联的 ID 段落 id 句子 id                                        |
-| `bold_single`    | string       | 单个黑体文本，用于搜索加权                                           |
-| `bold_multi`     | string       | 多个黑体文本，用于搜索加权                                           |
-| `page_refs`      | array        | 页码标记数组，例如 \["V3.81","M3.58"，“PTS Vin II 57”]               |
-| `tags`           | array        | 文档主题标签                                                         |
-| `category`       | array        | 文档分类，例如 ["sutta", "vinaya"]                                   |
-| `author`         | string       | 作者或译者                                                           |
-| `language`       | string       | 资源语言 pali,zh-Hans,zh-Hant,en-US,my 等                            |
-| `updated_at`     | date         | 原始文档更新时间                                                     |
+### 3. 字段需求
+
+#### 核心字段
+
+- `id`：openSearch 唯一 ID
+- `resource_id`：文档在数据库中的 ID（UUID）
+- `resource_type`：文档类型（article | term | dictionary | translation | origin_text|nissaya）
+- `granularity`：文档颗粒度 "book | chapter | sutta | section | paragraph | sentence"
+- `title`：文档标题，可以是中文或巴利文
+  - `display`:文档显示用 不搜索
+  - `text`: 纯文本，模糊搜索用
+  - `vector`: embedding
+- `summary`：文档摘要 llm 根据 content 生成
+  - `text`: 摘要文本
+  - `vector`: embedding
+- `content`：文档主体内容
+  - `display`:文档显示用，支持 Markdown，可能包含黑体字
+  - `text`: 纯文本，模糊搜索用 小写
+  - `exact`: 精确搜索
+  - `tokens`: 对象数组
+    - `surface` : 显示拼写
+    - `lemma` : 去格位拼写
+    - `compound_parts` 复合词组分
+    - `case` 语法信息 如：sg_acc
+  - `vector`:文档内容的 embedding
+- `related_id`：关联的段落 ID、句子 ID ["chapter_93-5","m.n. 38","93-5","95-7-2-10"]
+- `bold_single`：单个黑体文本，用于搜索加权
+- `bold_multi`：多个黑体文本，用于搜索加权
+- `page_refs`：页码标记数组（如 \["V3.81","M3.58","PTS Vin II 57"]）
+- `tags`：文档主题标签（数组）
+- `category`：文档分类 枚举 "pali"| "commentary"|'subcommentary'
+- `path`：经文路径 "/suttapitaka/dighanikaya/mahavaggo/satipatthanasutta"
+- `language`：资源语言 pali, zh-Hans, zh-Hant, en-US, my 等
+- `metadata`：
+  - `APA`: APA 格式引文字符串
+  - `MLA`: MLA 格式引文字符串
+  - `author`：作者或译者
+  - `channel`: wikipali channel
+- `updated_at`：原始文档更新时间
+
+```json
+{
+  "id": "openSearch唯一ID",
+  "resource_id": "UUID",
+  "resource_type": "article | term | dictionary | translation | origin_text | nissaya",
+  "granularity": "book | chapter | sutta | section | paragraph | sentence"|"auto", // 新增
+  "title": "文档标题（中文或巴利文）",
+  "summary": {
+    "text": "摘要文本",
+    "vector": [
+      /* embedding 向量 */
+    ]
+  },
+  "content": {
+    "display": "Markdown 格式，含黑体字",
+    "text": "小写纯文本，模糊搜索用",
+    "exact": "精确匹配用",
+    "tokens": [
+      { "surface": "bhikkhave", "lemma": "bhikkhu", "case": "voc_pl" }
+    ],
+    "vector": [
+      /* embedding 向量 */
+    ]
+  },
+  "related_id": ["m.n.38", "93-5"],
+  "bold_single": ["某个黑体词"],
+  "bold_multi": ["多个黑体词"],
+  "page_refs": ["V3.81", "M3.58", "PTS Vin II 57"],
+  "tags": ["禅修", "业报"],
+  "category": ["pali", "atthakatha","tika"],
+  "path": "/suttapitaka/dighanikaya/mahavaggo/satipatthanasutta",
+  "language": "pali | zh-Hans | zh-Hant | en-US | my",
+  "metadata": {
+    "APA": "Smith, J. (2020). Title of the book. Publisher.",
+    "MLA": "Smith, John. Title of the Book. Publisher, 2020.",
+    "author": "译者或作者",
+  },
+  "updated_at": "2025-09-19T00:00:00Z"
+}
+```
 
 ---
 
-## 4. 技术实现
+### 4. 技术实现
 
 1. **全文搜索**
 
@@ -70,40 +133,80 @@
    - 支持巴利文 lemma 搜索
    - 支持 `page_refs` 页码搜素
 
-2. **过滤/精确查询**
+1. **巴利文格位归一化搜索**
+
+   - 使用 synonyms.txt 实现存储和查询去掉格位
+   - 保留一个原始字段供精确查询
+   - synonyms.txt 中包括中文术语，能够用中文查询巴利文
+   - 文件放在 opensearch/config/analysis/synonyms.txt
+   - 输入 亚卡 能搜索到 yakkha yakkho
+
+在配置里定义一个查询时同义词分析器：
+
+```json
+"analyzer": {
+  "pali_query_analyzer": {
+    "tokenizer": "standard",
+    "filter": ["lowercase", "pali_synonyms"]
+  },
+},
+"filter": {
+  "pali_synonyms": {
+    "type": "synonym_graph",
+    "synonyms_path": "analysis/pali_synonyms.txt"
+  },
+}
+
+```
+
+查询时指定 analyzer：
+
+```json
+{
+  "query": {
+    "match": {
+      "content.text": {
+        "query": "夜叉",
+        "analyzer": "pali_query_analyzer"
+      }
+    }
+  }
+}
+```
+
+1. **过滤/精确查询**
 
    - 按 `tags` 过滤主题
    - 按 `category` 过滤文献分类
 
-3. **黑体字搜索加权**
+2. **黑体字搜索加权**
 
    - 若匹配到 `bold_single` `bold_multi`（Markdown 黑体），排名靠前
 
-4. **语义搜索**
+3. **语义搜索**
 
    - 基于 `vector` 检索相似句子
    - 基于 `vector` 检索不同语言相似句子
    -
 
-5. **巴利相似句**
+4. **巴利相似句**
 
    - 忽略格位变化
    - 只搜索 sentence
 
-6. **页码搜索**
+5. **页码搜索**
 
    - 只搜索 `page_refs`
 
-7. **简繁体互查**
+6. **简繁体互查**
 
-   1. 索引时 & 查询时，程序层用 OpenCC 转换简繁（更灵活）
-   2. 使用 OpenSearch ICU plugin 的 icu_transform 做简繁映射
+   - 使用 OpenSearch ICU plugin 的 icu_transform 做简繁映射
 
-8. **处理变音符号**
+7. **处理变音符号**
 
    - analysis-icu
 
-9. **模糊搜索+精确匹配**
+8. **模糊搜索+精确匹配**
 
 ```json
 {
@@ -156,16 +259,18 @@
 }
 ```
 
----
+混合搜索 hybrid
+
+模糊搜索+语义搜索 权重为 7:3
 
-## 5. 插件依赖
+### 5. 插件依赖
 
-- k-NN 插件（已支持向量搜索，无需额外安装）
-- 中文分词
+- `k-NN` 插件（已支持向量搜索，无需额外安装）
+- 中文分词 `ik`
 - 巴利文转英文字母 `analysis-icu`
 - 简繁体转换 `icu_transform`
 
-## 多语言 embedding 模型（托管型 调用 API 即可）
+### 多语言 embedding 模型（托管型 调用 API 即可）
 
 适合快速上线，效果好，但依赖外部服务。
 
@@ -199,8 +304,408 @@ Prices per 1M tokens.
 | text-embedding-3-small | $0.02 | $0.01      |
 | text-embedding-3-large | $0.13 | $0.065     |
 
-1. **Cohere - `embed-multilingual-v3.0`**
+## API 层设计方案
+
+laravel API.实现简单和复杂两个查询接口
+
+### 搜索接口
+
+`GET /api/v3/search`
+
+查询参数：
+
+- `q` (string): 搜索关键词
+- `resource_type` (string): article|term|dictionary|translation|origin_text|nissaya
+- `granularity` (string): book|chapter|sutta|section|paragraph|sentence
+- `language` (string): pali|zh-Hans|zh-Hant|en-US|my
+- `category` (array): 文献分类过滤 ["pali", "commentary", "subcommentary"]
+- `tags` (array): 主题标签过滤
+- `page_refs` (string): 页码搜索，如 "M3.58"
+- `page` (int): 页码，默认 1
+- `page_size` (int): 每页数量，默认 20，最大 100
+- `search_mode` (string): fuzzy|exact|semantic|hybrid，默认 fuzzy
+
+#### 业务逻辑示例
+
+**关键词搜索**
+
+```bash
+GET /api/v3/search?q=世尊&search_mode=fuzzy
+```
+
+**语义搜索：**
+
+```bash
+GET /api/v3/search?q=佛陀关于慈悲的教导&search_mode=semantic
+```
+
+**巴利相似句搜索：**
+
+```bash
+GET /api/v3/search?q=sabbe dhammā anattā&resource_type=origin_text&language=pali&granularity=sentence&search_mode=fuzzy
+```
+
+**页码搜索：**
+
+```bash
+GET /api/v3/search?page_refs=M3.58
+```
+
+响应格式：
+
+```json
+{
+  "success": true,
+  "data": {
+    "total": 156,
+    "page": 1,
+    "page_size": 20,
+    "took": "120ms",
+    "results": [
+      {
+        "id": "doc_123",
+        "resource_id": "uuid-456",
+        "resource_type": "origin_text",
+        "granularity": "sentence",
+        "title": "法印经",
+        "content": {
+          "display": "sabbe dhammā anattāti",
+          "tokens": [
+            { "surface": "sabbe", "lemma": "sabba", "case": "nom_pl" },
+            { "surface": "dhammā", "lemma": "dhamma", "case": "nom_pl" },
+            { "surface": "anattāti", "lemma": "anatta", "case": "nom_pl" }
+          ]
+        },
+        "related_id": ["93-15"],
+        "page_refs": ["M3.58"],
+        "language": "pali",
+        "path": "/suttapitaka/majjhimanikaya",
+        "score": 0.95,
+        "similarity": 0.92 // 巴利相似句特有字段
+      }
+    ],
+    "aggregations": {
+      "resource_type": {
+        "buckets": [{ "key": "origin_text", "doc_count": 89 }]
+      },
+      "language": {
+        "buckets": [{ "key": "pali", "doc_count": 89 }]
+      }
+    }
+  },
+  "query_info": {
+    "original_query": "sabbe dhammā anattā",
+    "search_type": "pali_similar_sentence" // 后端识别的搜索类型
+  }
+}
+```
+
+### 自动建议接口
+
+输入英文字母，能查到带有特殊符号的巴利文
+
+`GET /api/v3/search-suggest`
+
+查询参数：
+
+- `q` (string): 输入的部分文本
+- `type` (enum): term|pali_romanized|page_ref
+- `language` (string): 建议的目标语言
+- `limit` (int): 返回数量，默认 10
+
+```json
+{
+  "success": true,
+  "data": {
+    "suggestions": [
+      {
+        "text": "四念处",
+        "pali": "satipaṭṭhāna",
+        "romanized": "satipatthana",
+        "type": "term",
+        "frequency": 156
+      }
+    ]
+  }
+}
+```
+
+## 交互层
+
+REACT + antd 实现聊天 Agent 调用不同的查询函数实现复杂的多轮对话查询
+
+### 查询类型
+
+- **单词解析**
+  - **词义解释** 例子：什么是四圣谛 查询 summary, content 找到与`四圣谛`相关的资源
+  - **佛教术语** 例子：请写一个竹林精舍的百科词条。 同上
+  - **词义比较** 例子：禅那与禅那缘有什么关系。查询`禅那` `禅那缘`
+- **经文解读**
+  - **根据资料解释经文** 例子：经文解读:{{chapter|95-4}}. 查询经文和相关参考资料`related_id=95-4`。用于经文阅读界面。
+- **经文查询**
+  - **给一个大概的意思，查询相关的经文** 如：佛陀让阿难尊者制作如田地的袈裟出自哪里，给出巴利文和译文。
+
+### 设计思路 --多功能代理设计思路：小而精的函数集
+
+我们的全文搜索项目将采用**“多个函数、较少参数”**的设计理念。这一策略旨在通过创建一组专精、单一职责的工具函数，来构建一个高效、可扩展且易于维护的搜索代理（Agent）。
+
+---
+
+#### 1. 设计核心
+
+传统的代理设计常将所有功能打包进一个庞大的函数（例如 `searchDocument`），并用大量参数来区分不同意图。这种做法虽然直观，但会给大型语言模型（LLM）带来认知负担，导致参数混淆和调用错误，并使得代码难以扩展。
+
+我们的设计为：**每个函数只负责一种明确的搜索意图**，并只接受其完成任务所必需的最少参数。这就像为代理配备了一套专用的工具箱，而不是一把万能钥匙。
+
+---
+
+#### 2. 实现方式
+
+我们为不同的搜索需求定义了以下几个功能独立的函数：
+
+- **`search_by_query(query, search_mode, ...)`**: 处理通用的、描述性的模糊或语义搜索。
+- **`search_by_page_ref(page_refs)`**: 专门用于精确的页码搜索。
+- **`get_term_definition(term)`**: 仅用于获取佛教术语的定义。
+- **`search_pali(query)`**: 专门用于巴利文的精确匹配搜索。
+
+代理将通过解析用户查询，准确地调用这四个函数中的一个。例如，当用户输入“M3.58”时，代理会立即识别为页码搜索意图，并调用 `search_by_page_ref` 函数，而不会在其他不相关的参数上浪费算力。
+
+---
+
+#### 3. 核心优势
+
+- **高准确率**：每个函数都有清晰、明确的用途，这极大地简化了 LLM 的判断过程，显著提高了函数调用的准确率。
+- **卓越的灵活性**：如果未来需要新增功能，例如“按作者搜索”，我们只需定义一个新的 `search_by_author(author)` 函数即可，无需改动任何现有代码。
+- **更易于维护**：由于每个函数都小而精，代码逻辑更清晰，方便开发和测试，降低了维护成本。
 
-   - 支持 100+ 语言，1024 维。
-   - 在跨语言语义检索任务中表现接近 OpenAI。
-   - 优势：提供 API，延迟较低。
+### 提示词
+
+```text
+你是一个专业的、精通巴利语和汉语的佛教文献检索助手。你的任务是分析用户的查询，并利用你拥有的工具（函数）来获取信息。
+
+严格遵守以下原则：
+1.  优先并恰当地使用提供的工具来满足用户的查询需求。
+2.  你的回答必须简洁、直接，仅包含从工具中获得的信息，不添加任何额外闲聊。
+3.  如果一个查询无法被任何工具处理，或者需要与用户进行澄清，请清晰地说明。
+4.  当用户的查询包含**页码标记**（例如：M3.58, V3.81）时，必须使用 `search_by_page_ref` 函数。
+5.  当用户的查询是**明确的佛教术语或词汇**（例如：四圣谛, mettā）时，必须使用 `get_term_definition` 或 `search_pali` 函数。
+6.  当用户的查询是**描述性、自然语言问题**（例如：佛陀关于慈悲的教导）时，必须使用 `search_by_query` 函数并指定 `search_mode='semantic'`。
+7.  当用户的查询是**普通关键词**（例如：比丘, 袈裟）时，使用 `search_by_query` 函数并指定 `search_mode='fuzzy'`。
+
+以下是你的工具箱：
+- `search_by_query`: 用于通用的模糊和语义搜索。
+- `search_by_page_ref`: 专门用于处理页码搜索。
+- `get_term_definition`: 专门用于获取术语定义。
+- `search_pali`: 专门用于处理巴利文精确搜索。
+
+请严格根据上述原则，选择最恰当的工具来处理用户的请求。
+```
+
+### function call
+
+```json
+[
+  {
+    "name": "search_by_query",
+    "description": "根据关键词或自然语言描述在佛教文献库中进行通用搜索，支持模糊和语义匹配。适用于“佛陀关于慈悲的教导”或“什么是八正道”这类查询。",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "query": {
+          "type": "string",
+          "description": "用户的搜索关键词或句子。"
+        },
+        "search_mode": {
+          "type": "string",
+          "enum": ["fuzzy", "semantic"],
+          "description": "指定搜索模式：'fuzzy' 用于模糊搜索, 'semantic' 用于语义相似度搜索。"
+        }
+      },
+      "required": ["query", "search_mode"]
+    }
+  },
+  {
+    "name": "search_by_page_ref",
+    "description": "根据页码标记（如 PTS VinIII 24, M3.58）在文献库中进行精确搜索，快速定位特定经文。",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "page_refs": {
+          "type": "string",
+          "description": "页码标记，例如 'PTS VinIII 24', 'M3.58', 'P3.81'。"
+        }
+      },
+      "required": ["page_refs"]
+    }
+  },
+  {
+    "name": "get_term_definition",
+    "description": "获取佛教术语或词汇的精确定义和解释，用于回答“什么是四圣谛”或“禅那是什么意思”这类问题。",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "term": {
+          "type": "string",
+          "description": "需要查询的佛教术语或词汇。"
+        }
+      },
+      "required": ["term"]
+    }
+  },
+  {
+    "name": "search_pali",
+    "description": "在巴利文经文中搜索精确匹配的词汇或短语，支持巴利文格位归一化。适用于“sabbe dhammā anattā”这类查询。",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "query": {
+          "type": "string",
+          "description": "需要精确匹配的巴利文词汇或短语。"
+        }
+      },
+      "required": ["query"]
+    }
+  }
+]
+```
+
+TypeScript 类型定义
+
+```TypeScript
+// ---------------------------------------------------------------- //
+//             核心搜索函数参数类型：search_documents               //
+// ---------------------------------------------------------------- //
+
+/**
+ * 搜索模式的枚举，用于指定不同类型的搜索。
+ * - 'fuzzy': 模糊搜索，支持巴利文变音符号、简繁体等。
+ * - 'exact': 精确匹配，用于专有名词或特定短语。
+ * - 'semantic': 语义搜索，基于向量检索。
+ * - 'hybrid': 混合搜索 fuzzy+semantic。
+ */
+export type SearchMode = 'fuzzy' | 'exact' | 'semantic' | 'hybrid';
+
+/**
+ * 文档类型的枚举，用于筛选不同来源的文档。
+ */
+export type ResourceType = 'article' | 'term' | 'dictionary' | 'translation' | 'original_text' | 'nissaya';
+
+/**
+ * 语言代码的枚举。
+ */
+export type Language = 'pali' | 'zh-Hans' | 'zh-Hant' | 'en-US' | 'my';
+
+/**
+ * search_documents 函数的参数类型。
+ * 这将作为 Function Calling 的 `arguments` 参数传递。
+ */
+export interface SearchDocumentsArgs {
+  /**
+   * 用户的搜索关键词或句子。
+   */
+  query: string;
+
+  /**
+   * 指定搜索模式，由 AI 助手根据用户意图判断。
+   */
+  search_mode: SearchMode;
+
+  /**
+   * 文档类型数组，用于过滤搜索结果。
+   */
+  resource_type?: ResourceType[];
+
+  /**
+   * 语言数组，用于过滤搜索结果。
+   */
+  language?: Language[];
+
+  /**
+   * 页码标记，仅在 search_mode 为 'page_search' 时使用。
+   */
+  page_refs?: string;
+
+  /**
+   * 主题标签数组，用于进一步过滤。
+   */
+  tags?: string[];
+}
+
+
+// ---------------------------------------------------------------- //
+//             术语定义函数参数类型：get_term_definition            //
+// ---------------------------------------------------------------- //
+
+/**
+ * get_term_definition 函数的参数类型。
+ */
+export interface GetTermDefinitionArgs {
+  /**
+   * 需要查询的佛教术语或词汇。
+   */
+  term: string;
+}
+
+
+// ---------------------------------------------------------------- //
+//              AI 助手返回的 Function Call 类型                    //
+// ---------------------------------------------------------------- //
+
+/**
+ * AI 助手返回的函数调用对象。
+ */
+export type AICallbackFunction = {
+  /**
+   * 要调用的函数名。
+   */
+  name: 'search_documents' | 'get_term_definition';
+
+  /**
+   * 传递给函数的参数。
+   * 这里使用泛型来确保参数类型与函数名匹配。
+   */
+  arguments: SearchDocumentsArgs | GetTermDefinitionArgs;
+};
+
+// ---------------------------------------------------------------- //
+//              后端 API 响应类型（示例）                           //
+// ---------------------------------------------------------------- //
+
+/**
+ * 核心文档卡片的数据结构。
+ */
+export interface DocumentResult {
+  id: string;
+  resource_id: string;
+  resource_type: ResourceType;
+  title: string;
+  content: {
+    display: string;
+    text: string;
+    vector?: number[];
+  };
+  related_id: string[];
+  page_refs?: string[];
+  language: Language;
+  score: number;
+  similarity?: number;
+}
+
+/**
+ * API 搜索响应的完整结构。
+ */
+export interface SearchResponse {
+  success: boolean;
+  data: {
+    total: number;
+    page: number;
+    page_size: number;
+    took: string;
+    results: DocumentResult[];
+  };
+  query_info: {
+    original_query: string;
+    search_type: SearchMode | 'term_definition';
+  };
+}
+```