pigdoc

---
name: pigdoc
description: 搜索 PIG 官方文档并总结答案。当用户询问 PIG CLOUD、PIG AI、pigx 相关的技术问题、配置方法、功能说明，或明确说"查文档"、"搜一下"、"怎么配置"、"怎么实现"时触发。遇到 PIG 框架相关具体问题时应主动搜索文档后再回答，不要依赖训练数据中可能过期的信息。
---

# PIG 文档搜索技能

PIG 官方文档分布在两个索引中：

- `pig`：PIG Cloud、pigx、网关、权限、微服务等后端与平台能力
- `ai`：PIG AI、知识库、RAG、模型、向量库、工作流、智能体等 AI 能力

触发该技能后，需要先根据用户问题选择索引，再搜索并总结官方答案。

## 搜索步骤

### 1. 提取关键词

从用户问题中提取 1-3 个核心关键词。优先使用中文（文档以中文为主）。

**示例：**
- "多数据源怎么配置" → `多数据源`
- "oauth2 登录失败" → `OAuth2 登录`
- "网关路由 404" → `网关路由`

### 关键词预处理（项目名归一化）

用户经常把官方项目名改掉（如 `staronex`、`starone` 等），触发该技能时必须先做还原。

该规则主要用于 `pig` 侧检索，不要把 `pigx` 映射规则错误套用到 AI 术语上。

1. 抽取用户问题中的核心词后，识别是否包含项目名/库名。常见形态如 `xx_report`、`xx-xxx`、`xx_模块名`。
2. 若前缀不是标准官方关键词（例如 `report`、`网关`、`权限`、`配置` 等模块词），先尝试将该前缀映射为 `pigx`。
3. 同时保留原词与映射词做双关键词并行查询：
   - 原始关键词（用于兜底）
   - 映射后的关键词（用于主结果）

**示例：**
- `staronex_report 库没有表结构` → 优先查询 `pigx_report`，并补充 `staronex_report`
- `staronex-权限` → 优先查询 `pigx-权限`，并补充 `staronex-权限`
- `starone report 不存在` → 优先查询 `pigx report`

#### 推荐映射规则

- 显式别名：`staronex`、`starone` → `pigx`
- 其他自定义前缀：当查询中出现 `<前缀>_<后缀>`，且前缀明显是库/项目前缀时，优先改为 `pigx_<后缀>`
- 若出现歧义（例如命中很少），先返回映射结果，再回退原词补充搜索

### 2. 选择索引

按用户问题内容在 `pig` / `ai` 两个索引间路由：

- 命中 AI 语义时，查询 `ai`
  - 典型关键词：`PIG AI`、`知识库`、`RAG`、`模型`、`向量库`、`Embedding`、`工作流`、`智能体`、`图谱`、`Neo4j`
- 命中 Cloud / pigx 语义时，查询 `pig`
  - 典型关键词：`PIG Cloud`、`pigx`、`网关`、`权限`、`OAuth2`、`微服务`、`多数据源`、`注册中心`、`代码生成`
- 同时包含两类语义，或问题本身较模糊时，同时查询 `pig` 和 `ai`
  - 示例：`PIG AI 的知识库能不能和 pigx 权限系统一起用`
  - 示例：`怎么配置模型`

### 3. 调用搜索接口

根据第 2 步选中的索引，调用对应接口：

- `pig`：`https://search.pig4cloud.com/indexes/pig/search`
- `ai`：`https://search.pig4cloud.com/indexes/ai/search`

```bash
curl -s -X POST "https://search.pig4cloud.com/indexes/{index}/search" \
  -H "Content-Type: application/json" \
  -d '{"q": "关键词", "limit": 3}'
```

若需要双查，则分别请求两个索引，再合并结果。

### 4. 响应字段说明

| 字段 | 含义 |
|------|------|
| `hits[].lvl0` | 文档标题 |
| `hits[].content` | 文档正文（Markdown 格式） |
| `hits[].url` | 文档路径（如 `/doc/pigx/use/xxx`、`/doc/ai/rag/xxx`） |
| `hits[].lvl2` | 文档更新时间 |

### 5. 总结并回答

基于搜索结果，按以下格式输出：

---

**根据 PIG 官方文档，关于「用户问题」：**

**解答：**
[综合文档内容，提炼核心步骤或说明，用清晰要点列出。保留代码片段、配置示例等关键内容]

**参考文档：**
- [文档标题](链接) — 一句话说明该文档的作用

---

生成参考链接时，必须按命中的索引选择正确的文档路由：

- `pig` 结果：`https://docs.pig4cloud.com/pig#{url}`
- `ai` 结果：`https://docs.pig4cloud.com/ai#{url}`

**总结原则：**
- 保留文档中的代码块、XML/YAML 配置、关键注意事项
- 多篇文档说同一件事时合并，不重复
- 若同时查询了两个索引，先去重再总结，并在表述中说明答案主要来自 `pig`、`ai` 或两者共同支持
- 若双查后只有一个索引命中，只基于命中的那一侧回答
- 若搜索结果与问题关联度低，说明后基于已知知识补充回答
- 若 `hits` 为空，告知用户文档暂无相关内容

## 搜索不理想时

第一次搜索命中少于 2 条或内容明显不相关时，在已选索引范围内换一个关键词再搜一次，合并结果总结。

## 示例路由

- `多数据源怎么配置` → 查 `pig`
- `知识库接入 Neo4j 怎么配` → 查 `ai`
- `PIG AI 的知识库能不能和 pigx 权限系统一起用` → 同时查 `pig` 和 `ai`
- `staronex_report 库没有表结构` → 使用 `pigx` 映射后查 `pig`
- `怎么配置模型` → 问题较模糊，优先双查后按命中结果回答