# Dify AI 工具接入完整部署记录（照着做就能成功）

> 实战日期：2026-08-15 | 目标：企微对话 → AI 调用 CordysCRM 售后 API
> 本文按「从头到尾」的顺序记录每一步操作、命令、踩坑和修复，下次接新工具照此文档复制执行。

## 〇、整体架构

```
企业微信消息
  → 回调服务（aliyun2:18790，wecom-callback）
  → Dify「企业微信」Chatflow 应用（Agent 节点，记忆窗口 10）
  → AI 判断意图 → 调用自定义工具（OpenAPI 定义）
  → 认证代理（aliyun2:8766，systemd cordys-api-proxy）
  → 目标 API（CordysCRM:8081）
  → 数据返回 → AI 格式化回答 → 推回企微
```

关键设计：**AI 负责决策，代理负责认证安全，接口系统只做数据读写。**

---

## 一、部署认证代理（10 分钟）

**为什么需要代理**：Dify 自定义工具只支持配「一个」认证 Header，但 CordysCRM 要两个（X-Access-Key + X-Secret-Key）。代理接收 Dify 的单 Token 请求，校验后注入双密钥转发。

### 1.1 代理脚本要点

`/data/cordys_api_proxy.py`（systemd `cordys-api-proxy`，端口 8766）：

- 校验 `X-Proxy-Token`（不对就 403）
- 转发时注入 `X-Access-Key` / `X-Secret-Key`
- **支持 chunked 传输**（Dify 的 SSRF 代理用 chunked，不支持就读不到 body）
- **参数修正钩子**：可强制替换 AI 传错的参数（如 customFormId）
- 日志全部 `flush=True`（否则 journald 里看不到）

```bash
# systemd 服务
cat > /etc/systemd/system/cordys-api-proxy.service << 'EOF'
[Unit]
Description=CordysCRM API Proxy for Dify
After=network.target
[Service]
Type=simple
ExecStart=/usr/bin/python3 /data/cordys_api_proxy.py
Restart=always
RestartSec=3
[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload && systemctl enable --now cordys-api-proxy
```

### 1.2 安全要点

- firewalld **不开** 8766 → 外网访问不到，仅 Docker 内网可用
- Dify api 容器访问宿主机的地址是 docker 网关：`172.20.0.1:8766`（`docker inspect dify_v1110_chns-api-1` 看 Gateway）

### 1.3 验证

```bash
# 带 token：200
curl -s 'http://127.0.0.1:8766/custom-form/list' -H 'X-Proxy-Token: zilan-crm-proxy-2026'
# 无 token：403
curl -s -o /dev/null -w '%{http_code}' 'http://127.0.0.1:8766/custom-form/list'
# 从 Dify 容器内测试（模拟真实调用路径）
docker exec dify_v1110_chns-api-1 curl -s 'http://172.20.0.1:8766/custom-form/list' -H 'X-Proxy-Token: zilan-crm-proxy-2026'
```

---

## 二、编写 OpenAPI 工具定义（30 分钟）

### 2.1 先摸清接口（别猜）

```bash
# 用 api-docs 看接口全貌
curl -s 'http://127.0.0.1:8081/v3/api-docs' \
  -H 'X-Access-Key: <key>' -H 'X-Secret-Key: <secret>'
# 从中提取：路径、方法、参数 schema、必填字段
```

### 2.2 查业务字段（下拉选项的 ID 映射）

AI 填下拉框要填选项 ID 不是文字，所以 description 里必须写全映射：

```
公司=178642865321400000(子兰=...001/焕境=...002)
问题处理阶段=...(未处理=...001/安排中=...002/处理中=...003/已处理=.../推迟处理=...)
```

### 2.3 OpenAPI JSON 结构

```json
{
  "openapi": "3.0.1",
  "info": {"title": "工具名", "version": "1.0.0"},
  "servers": [{"url": "http://172.20.0.1:8766"}],
  "security": [{"proxyTokenAuth": []}],
  "paths": {
    "/custom-form/data/page": {
      "post": {
        "operationId": "queryRecords",
        "summary": "查询售后记录",
        "description": "keyword 模糊匹配客户姓名。customFormId 固定 436092742804709376。",
        "requestBody": {"content": {"application/json": {"schema": {
          "type": "object",
          "properties": {
            "customFormId": {"type": "string", "default": "436092742804709376"},
            "keyword": {"type": "string", "description": "客户姓名"}
          }
        }}}}
      }
    }
  },
  "components": {"securitySchemes": {"proxyTokenAuth": {"type": "apiKey", "in": "header", "name": "X-Proxy-Token"}}}
}
```

⚠️ **servers.url 用 docker 网关地址**（`http://172.20.0.1:8766`），因为请求是从 Dify api 容器发起的，容器里 `127.0.0.1` 是它自己。

---

## 三、创建 Dify 工具（10 分钟）

### 3.1 UI 方式（手动）

Dify 后台 → 工作室 → 企业微信 → 编辑 → 左下「工具」→ 自定义 → 创建 → OpenAPI schema 粘贴 → 认证选 API Key（Header `X-Proxy-Token`，值 `zilan-crm-proxy-2026`）。

### 3.2 控制台 API 方式（自动化，本战采用）

**Step 1：建临时管理员账号**（不改用户现有账号，用完即删）

```sql
-- Dify 密码哈希 = pbkdf2_hmac sha256 10000轮；password列 = base64(hexlify(dk))；salt列 = base64(salt)
INSERT INTO accounts (id, name, email, password, password_salt, status, initialized_at)
VALUES (uuid_generate_v4(), 'temp-admin', 'temp-admin@zilan.local', '<hash>', '<salt>', 'active', CURRENT_TIMESTAMP);
INSERT INTO tenant_account_joins (id, tenant_id, account_id, role, current)
SELECT uuid_generate_v4(), '<tenant_id>', id, 'owner', true FROM accounts WHERE email='temp-admin@zilan.local';
```

⚠️ **哈希格式坑**：`hash_password` 返回 `hexlify(dk)`（hex 字节串），存入时还要 base64 一层。直接 base64(dk) 是错的，登录会「Invalid email or password」。

**Step 2：登录**（`password` 字段必须先 base64 编码！）

```bash
PWD64=$(echo -n '密码' | base64)
curl -s -c /tmp/dify_cj.txt -X POST 'http://127.0.0.1:8088/console/api/login' \
  -H 'Content-Type: application/json' \
  -d "{\"email\":\"temp-admin@zilan.local\",\"password\":\"$PWD64\",\"language\":\"zh-Hans\"}"
```

⚠️ 登录接口的 password 加密就是 **base64**（libs/encryption.py 源码确认），不是 RSA。

**Step 3：创建工具 provider**

```bash
CSRF=$(grep csrf_token /tmp/dify_cj.txt | awk '{print $7}')
curl -s -b /tmp/dify_cj.txt -H "X-CSRF-Token: $CSRF" \
  -X POST 'http://127.0.0.1:8088/console/api/workspaces/current/tool-provider/api/add' \
  -H 'Content-Type: application/json' \
  -d '{
    "provider": "工具名",
    "icon": {"type": "emoji", "content": "🔧"},
    "credentials": {"auth_type": "api_key_header", "api_key_header": "X-Proxy-Token", "api_key_value": "zilan-crm-proxy-2026"},
    "schema_type": "openapi",
    "schema": "<openapi json 字符串>",
    "privacy_policy": "", "custom_disclaimer": "", "labels": []
  }'
```

⚠️ **CSRF 坑**：登录 cookie 里有 `csrf_token`，请求头必须带 `X-CSRF-Token: <同值>`，否则 401。
⚠️ **auth_type 值**：`api_key_header`（不是旧的 `api_key`）。

**Step 4：拿到 provider id**

```sql
SELECT id, name FROM tool_api_providers;  -- 记下 UUID，Agent 节点要用
```

---

## 四、改造 Chatflow：LLM → Agent 节点（40 分钟，本次踩坑重灾区）

### 4.1 准备工作

```bash
# 看当前图结构
SELECT id, type, version FROM workflows WHERE app_id='<app_id>' ORDER BY updated_at DESC;
# draft = 编辑版本；version 是时间戳的 = 已发布版本
```

### 4.2 Agent 节点完整 JSON（正确版）

```json
{
  "type": "agent",
  "title": "AI助手",
  "desc": "",
  "version": "1",
  "model": {"provider": "langgenius/deepseek/deepseek", "model": "deepseek-v4-flash", "model_type": "llm", "mode": "chat", "completion_params": {"temperature": 0.7}},
  "agent_strategy_provider_name": "langgenius/agent/agent",
  "agent_strategy_name": "function_calling",
  "agent_strategy_label": "FunctionCalling",
  "memory": {"window": {"enabled": true, "size": 10}, "query_prompt_template": "{{#sys.query#}}", "role_prefix": {"user": "", "assistant": ""}},
  "tool_node_version": "2",
  "agent_parameters": {
    "model": {"value": {"provider": "langgenius/deepseek/deepseek", "model": "deepseek-v4-flash", "model_type": "llm", "mode": "chat", "completion_params": {"temperature": 0.7}}, "type": "mixed"},
    "tools": {"value": [{
      "provider_name": "<provider的UUID>",
      "provider_id": "<provider的UUID>",
      "type": "api",
      "tool_name": "queryRecords",
      "tool_label": "queryRecords",
      "tool_configurations": {},
      "enabled": true
    }], "type": "mixed"},
    "instruction": {"value": "<系统提示词>", "type": "constant"},
    "query": {"value": "{{#sys.query#}}", "type": "mixed"},
    "maximum_iterations": {"value": 3, "type": "constant"}
  }
}
```

### 4.3 三个致命坑（每个都实测踩过）

| # | 报错 | 根因 | 修法 |
|---|------|------|------|
| 1 | `'' is not a valid ModelType` | 模型参数缺 `model_type` 字段，且模型名要放 `model` 键（不是 `name`） | 按 4.2 补全 |
| 2 | `Invalid plugin id <工具名>` | 工具类型字段名是 **`type`**（值 `api`），我写成了 `provider_type` → 后端默认当 builtin | 改 `"type": "api"` |
| 3 | `invalid input syntax for type uuid: "售后问题跟进表"` | 后端把工具 dict 的 **`provider_name` 字段当 provider_id（UUID）** 用 | `provider_name` 和 `provider_id` 都填 UUID |

⚠️ 核心教训：**后端源码才是真相**。三个坑都是读 `agent_node.py` 源码定位的：
- `tool.get("type")` → 类型字段
- `tool.get("provider_name")` → 被塞进 `AgentToolEntity.provider_id`
- `_fetch_model` 读 `value["provider"]/value["model"]/value["model_type"]`

### 4.4 同步 draft + 发布（hash 机制）

```bash
# ① GET 拿当前 draft 的 hash
GET /console/api/apps/<app_id>/workflows/draft

# ② POST 提交（graph + features + hash + 环境变量）
POST /console/api/apps/<app_id>/workflows/draft
# payload: {"graph": {...}, "features": {...}, "hash": "<刚拿的hash>", "environment_variables": [], "conversation_variables": []}

# ③ 发布
POST /console/api/apps/<app_id>/workflows/publish
{"marked_name": "", "marked_comment": ""}
```

⚠️ **hash 坑**：每次 sync 后 hash 会变，下一次 sync 前必须重新 GET。否则报 `draft_workflow_not_sync`。

### 4.5 提示词模板

```
你是XX助手（原有身份约束）

【工具使用规则】
1. 用户询问某客户的售后记录时，调用 queryRecords 工具（用客户姓名做 keyword）
2. 用户要求新增记录且信息齐全时，先复述确认，用户明确同意后再调用 addRecord
3. 用户要求修改记录时，先 queryRecords 查出记录 id，再调用 updateRecord
4. 查询不到就如实回答"未查到相关记录"，禁止编造数据
5. 新增/修改成功后回复"已录入/已更新"，并简述内容
```

---

## 五、测试（真实数据验证）

```python
POST http://127.0.0.1:8088/v1/chat-messages
Header: Authorization: Bearer app-wecom-chat-20260815
Body: {"inputs": {}, "query": "帮我查一下刘丹的售后记录", "response_mode": "blocking", "user": "test_u"}
```

实测通过：AI 自动调 queryRecords，返回刘丹 3 条售后记录（地址/电话/问题类别/处理阶段/处理人/备注全部正确）。

**测试期间的排障路径**（以后遇到照这个顺序查）：

1. `docker logs dify_v1110_chns-api-1` → 看 Agent/工具执行错误（最快定位）
2. 日志里看到 `8766` 字样 → 请求已到代理，查 `journalctl -u cordys-api-proxy`
3. 代理日志显示 `→ HTTP 500` → 目标 API 报错，看代理记录的 body，多半是 AI 传错参数
4. AI 传错参数（如把表单名当 ID）→ 在代理加**强制替换逻辑**（比教 AI 靠谱）

---

## 六、收尾清单

- [ ] **转移工具 owner**：`UPDATE tool_api_providers SET user_id='<真实账号id>' WHERE user_id='<临时账号id>';` ⚠️ 否则删临时账号后 Dify 界面报 `user is None for api provider`，工具全部不显示
- [ ] 删除临时管理员账号（`DELETE FROM accounts WHERE email='temp-admin@...'`）
- [ ] 更新 CLAUDE.md（3.11 节：新 Dify Key、代理服务、工具清单）
- [ ] 更新 Obsidian（本文件 + 企业微信集成方案.md）
- [ ] 桌面回溯记录（含回滚方法）
- [ ] 企微实测一轮真实对话

---

## 七、复用到其他系统（改哪里）

| 要改的 | 位置 |
|--------|------|
| 目标 API 地址 | OpenAPI 的 servers.url + 代理脚本 CRM_BASE |
| 密钥 | 代理脚本 ACCESS_KEY/SECRET_KEY |
| 接口定义 | OpenAPI 的 paths + 字段映射 |
| 工具名 | OpenAPI operationId + Agent 节点 tools 数组 |
| 提示词 | instruction 的 value |
| 参数修正逻辑 | 代理 _forward 里的钩子 |

**全流程耗时参考**：无坑首接约 1 小时；复用本文档约 30 分钟（坑都写在上面了）。