内容
# dify-rag-skill
用于将Dify用作RAG知识系统的Claude Code技能和脚本。
该存储库包含两个配套技能：
- `dify-rag-inject`：准备Google Drive文档为检索友好的Markdown并将其发送到Dify摄入工作流。
- `dify-rag-search`：搜索Dify知识库并返回检索到的块，以便Claude可以编写最终答案。
- `dify-rag` MCP服务器：向Claude.app / Claude Desktop公开Dify搜索和摄入功能。
设计保持职责分明：
- Dify存储和检索知识。
- Claude Code读取源文档，准备Markdown，检查检索到的块，并编写面向用户的答案。
- 在搜索流程中，不要求Dify生成最终答案。
这是一个独立的辅助项目。它不是官方的Dify、Anthropic或Google产品。
## 功能
### 摄入
当您要求Claude Code将Drive文档添加到Dify时，摄入技能会引导Claude Code完成以下步骤：
1. 在Google Drive中找到目标文件。
2. 检测文件是否有文本层。
3. 在需要时将富含图像的PDF转换为页面图像。
4. 读取并将内容结构化为Markdown。
5. 将`category`、`doc_name`和`doc_text`发送到Dify工作流API。
6. 让您的Dify工作流创建或更新适当的知识文档。
Claude.app / Claude Desktop可以通过MCP服务器执行相同的摄入流程：
1. 使用其Drive连接器读取源文档。
2. 将内容转换为检索友好的Markdown。
3. 调用`inject_dify_knowledge`并传入`category`、`doc_name`和`markdown`。
4. 让本地MCP服务器调用配置的Dify摄入工作流。
### 搜索
当您要求Claude Code搜索知识库时，搜索技能会：
1. 向Dify知识库检索API发送查询。
2. 搜索一个或多个Dify数据集。
3. 按分数合并检索到的块。
4. 打印源文档名称、分数和块文本。
5. 让Claude根据这些证据生成最终答案。
## 存储库内容
- `SKILL.md`：摄入技能说明。
- `search/SKILL.md`：搜索技能说明。
- `dify_inject.py`：用于调用Dify `/workflows/run`的Python客户端。
- `dify_search.py`：用于Dify数据集列表和检索的Python客户端。
- `mcp-server/`：用于Claude.app / Claude Desktop的本地MCP服务器。
- `install.sh`：用于两个技能的交互式安装程序。
- `config.example`：安全的配置模板，不包含实际的URL或API密钥。
## 要求
- macOS或Linux shell环境。
- 配置了Google Drive MCP或等效的Drive连接器的Claude Code。
- 已填充的Dify知识库。
- 用于摄入的已发布Dify工作流应用。
- 用于摄入的Dify工作流API密钥。
- 用于搜索的Dify知识库API密钥。
- Python 3。
- 用于富含图像的PDF的`pdftoppm`。
在macOS上，使用以下命令安装Poppler：
```bash
brew install poppler
```
## Dify API合约
### 摄入工作流
摄入技能不会为您创建Dify工作流。您需要一个已发布的Dify工作流应用，该应用接受以下输入：
| 输入 | 类型 | 描述 |
|---|---|---|
| `category` | 字符串 | 知识库、集合或路由类别。 |
| `doc_name` | 字符串 | 要创建或更新的文档名称。 |
| `doc_text` | 字符串 | 检索就绪的Markdown正文。 |
包含的摄入客户端将此有效负载发送到：
```text
<DIFY_BASE_URL>/workflows/run
```
带有：
```json
{
"inputs": {
"category": "...",
"doc_name": "...",
"doc_text": "..."
},
"response_mode": "blocking",
"user": "dify-rag-skill"
}
```
Dify工作流如何创建数据集、文档、块或更新由您的Dify实现决定。
### 搜索检索API
搜索技能使用Dify知识库API：
- `GET /datasets`以发现可见的数据集。
- `POST /datasets/{dataset_id}/retrieve`以检索块。
如果`DIFY_DATASET_IDS`为空，搜索客户端会列出可见的数据集并跨数据集搜索。如果您想限制搜索范围，请配置逗号分隔的数据集ID。
## 安装
克隆存储库并运行安装程序：
```bash
git clone https://github.com/atschool/dify-rag-skill.git
cd dify-rag-skill
./install.sh
```
安装程序将：
- 将摄入技能复制到`~/.claude/skills/dify-rag-inject/`。
- 将搜索技能复制到`~/.claude/skills/dify-rag-search/`。
- 将MCP服务器复制到`~/.dify-rag/mcp-server/`。
- 检查`pdftoppm`是否可用。
- 如果有Node.js和npm，则安装MCP服务器的npm依赖项。
- 创建一个共享的本地配置`~/.dify-rag/config`。
- 询问您的Dify工作流API密钥。
- 询问您的Dify知识库API密钥。
- 如果尚未配置，则询问您的Dify API基准URL。
配置文件是您本地机器特有的，刻意被Git忽略。
## Claude.app / Claude Desktop MCP设置
Claude Code可以直接读取已安装的技能。Claude.app / Claude Desktop则不能。为了从Claude.app使用Dify搜索，请将MCP服务器添加到您的Claude桌面配置中。
运行`./install.sh`后，MCP服务器安装在：
```text
~/.dify-rag/mcp-server/server.mjs
```
在macOS上，编辑：
```text
~/Library/Application Support/Claude/claude_desktop_config.json
```
添加或合并此条目，替换`/Users/you`为您实际的主目录：
```json
{
"mcpServers": {
"dify-rag": {
"command": "node",
"args": ["/Users/you/.dify-rag/mcp-server/server.mjs"]
}
}
}
```
然后重启Claude.app。
MCP服务器公开：
- `search_dify_knowledge`：搜索Dify并返回检索到的块。
- `list_dify_datasets`：列出可见到配置的Knowledge Base API密钥的数据集。
- `inject_dify_knowledge`：通过配置的Dify摄入工作流添加或更新准备好的Markdown文档。
## 配置
安装程序创建：
```text
~/.dify-rag/config
```
文件使用简单的`KEY=VALUE`行：
```bash
DIFY_BASE_URL=
DIFY_APP_KEY=
DIFY_DATASET_API_KEY=
DIFY_DATASET_IDS=
```
使用Dify API基准URL作为`DIFY_BASE_URL`。常见的示例如下：
```bash
DIFY_BASE_URL=https://your-dify.example.com/v1
DIFY_BASE_URL=http://localhost/v1
```
使用：
- `DIFY_APP_KEY`作为摄入工作流API密钥。
- `DIFY_DATASET_API_KEY`作为知识库搜索API访问。
- `DIFY_DATASET_IDS`仅在您希望将搜索限制到特定数据集时。
环境变量也受支持，并优先于配置文件:
```bash
export DIFY_BASE_URL="https://your-dify.example.com/v1"
export DIFY_APP_KEY="your-workflow-api-key"
export DIFY_DATASET_API_KEY="your-knowledge-base-api-key"
export DIFY_DATASET_IDS="dataset-id-1,dataset-id-2"
```
## 从Claude Code使用
### 将文档添加到Dify
询问Claude Code类似的问题：
```text
在Drive中找到产品概述PDF并将其添加到Dify，分类为“product-docs”。
```
Claude Code应该使用`dify-rag-inject`。
### 搜索Dify
询问Claude Code类似的问题：
```text
在Dify中搜索产品文档中关于帐户设置的内容。
```
或：
```text
/rag account setup
```
Claude Code应该使用`dify-rag-search`，检查返回的块并根据这些块回答。如果块不支持答案，Claude应该说出来而不是猜测。
在Claude.app / Claude Desktop中，询问相同的问题并配置MCP服务器后。Claude应该使用`search_dify_knowledge` MCP工具而不是直接搜索Google Drive。
### 从Claude.app / Claude Desktop添加文档
询问Claude.app类似的问题：
```text
在Google Drive中找到活动赞助PDF，将其转换为RAG友好的Markdown并将其添加到Dify，分类为“events”。
```
Claude.app应该使用其Drive连接器读取源文档，准备Markdown，然后调用`inject_dify_knowledge`。MCP服务器从您的本地配置中读取`DIFY_APP_KEY`；该密钥不会提交到Git。
## 手动摄入
如果您已经有一个Markdown文件，可以直接调用摄入客户端：
```bash
python3 ~/.claude/skills/dify-rag-inject/dify_inject.py \
--category "product-docs" \
--doc-name "product-overview" \
--file "./product-overview.md"
```
预览而不发送：
```bash
python3 ~/.claude/skills/dify-rag-inject/dify_inject.py \
--category "product-docs" \
--doc-name "product-overview" \
--file "./product-overview.md" \
--dry-run
```
## 手动搜索
搜索所有可见的数据集：
```bash
python3 ~/.claude/skills/dify-rag-search/dify_search.py \
--query "account setup" \
--top-k 5
```
搜索特定数据集：
```bash
python3 ~/.claude/skills/dify-rag-search/dify_search.py \
--query "account setup" \
--dataset-id "<dataset-id>" \
--top-k 5
```
按名称或确切ID过滤数据集：
```bash
python3 ~/.claude/skills/dify-rag-search/dify_search.py \
--query "account setup" \
--category "onboarding" \
--top-k 5
```
JSON输出：
```bash
python3 ~/.claude/skills/dify-rag-search/dify_search.py \
--query "account setup" \
--format json
```
列出可见的数据集：
```bash
python3 ~/.claude/skills/dify-rag-search/dify_search.py \
--list-datasets
```
## 卸载
删除已安装的技能和本地配置：
```bash
rm -rf ~/.claude/skills/dify-rag-inject
rm -rf ~/.claude/skills/dify-rag-search
rm -rf ~/.dify-rag
```
这不会删除Dify上的任何内容。
## 安全说明
- 永远不要提交`config`；它可能包含API密钥。
- `config.example`必须保持没有实际的URL、密钥、数据集ID、客户名称或内部示例。
- 安装程序在创建或更新时将本地配置文件设置为模式`600`。
- 搜索客户端打印检索到的源块。根据终端输出和日志进行相应处理。
- 在上传源文档包含敏感数据时，请查看生成的Markdown。
- 对于公共分支，请保持示例通用，避免使用实际的公司、客户、数据集或网络详细信息。
## 故障排除
| 症状 | 可能原因 | 检查内容 |
|---|---|---|
| `DIFY_BASE_URL is not set` | 缺少基准URL | 运行`./install.sh`或设置环境变量。 |
| `APIキーが未設定` 或 `DIFY_APP_KEY` 缺失 | 缺少工作流API密钥 | 设置摄入工作流API密钥。 |
| `DIFY_DATASET_API_KEY is not set` | 缺少知识库API密钥 | 设置知识库API密钥。 |
| `HTTP 401` | 无效密钥或错误的密钥类型 | 检查是否使用正确的工作流或知识库API访问密钥。 |
| `No datasets matched` | 数据集过滤器太窄或密钥缺乏访问权限 | 检查`DIFY_DATASET_IDS`、`--category`和密钥权限。 |
| Claude.app搜索Google Drive而不是Dify | MCP服务器未配置或Claude.app未重启 | 检查`claude_desktop_config.json`，重启Claude.app，并确认`dify-rag`MCP服务器已连接。 |
| MCP服务器启动失败 | 缺少Node依赖项 | 在安装Node.js和npm后重新运行`./install.sh`。 |
| `Workflow not published` | Dify工作流未发布 | 在Dify中发布工作流应用。 |
| 连接错误 | Dify无法访问 | 确认URL、网络、反向代理和`/v1` API路径。 |
| `pdftoppm`未找到 | Poppler丢失 | 在macOS上使用`brew install poppler`安装Poppler。 |
| 图片文本难以阅读 | PDF渲染分辨率太低 | 增加摄入技能工作流中的`pdftoppm` DPI。 |
## 开发
在打开拉取请求之前运行基本检查：
```bash
bash -n install.sh
python3 -m py_compile dify_inject.py dify_search.py
node --check mcp-server/server.mjs
```
在不影响您实际主目录的情况下测试安装程序：
```bash
tmp_home=$(mktemp -d)
printf 'workflow-key\nknowledge-key\nhttp://localhost/v1\n' | HOME="$tmp_home" bash install.sh
cat "$tmp_home/.dify-rag/config"
```
测试MCP服务器启动：
```bash
node ~/.dify-rag/mcp-server/server.mjs
```
它应该保持运行并记录到stderr。按`Ctrl-C`停止它。
在发布或发布之前，请扫描以防止意外私密数据：
```bash
rg -n '192\.168\.[0-9]+\.[0-9]+|(^|[^0-9])10\.[0-9]+\.[0-9]+\.[0-9]+|172\.(1[6-9]|2[0-9]|3[0-1])\.[0-9]+\.[0-9]+|DIFY_APP_KEY=.+|DIFY_DATASET_API_KEY=.+|customer|internal' .
git status --short
```
## 存储库状态
该项目是一个轻量级集成助手。它假设您已经操作Dify，可以为您的组织设计摄入工作流和数据集权限。
## 许可证
MIT。参见 [LICENSE](./LICENSE)。
