AI 平台接入示例

本文给出 Dify、n8n、LangChain/LangGraph、Cursor、Claude Desktop、OpenAI SDK 等主流 AI 平台接入 sss-run 的完整示例。

通用前提：平台地址 http://localhost:9301，已在「设置 → AI 配置」配置好 LLM API Key。

---

1. Dify 接入

Dify 通过「自定义工具」导入 OpenAPI 规范，即可在 Agent 应用中调用平台全部 Tool。

步骤

1. 导出 OpenAPI：

   curl http://localhost:9301/ai/export/openapi -o sss-run-openapi.yaml

2. Dify 中导入：

   • 进入「工具 → 自定义 → 创建自定义工具」
   • 工具名称填 sss-run
   • 把上一步的 OpenAPI 内容粘贴到 Schema 框
   • 鉴权方式选「API Key」，填入平台认证 token（若有）

3. 在 Agent 应用中启用：

   • 创建一个 Agent 应用
   • 在「工具」中选择 sss-run，启用需要的工具
   • 测试对话：「查询 test_demo 表前 5 条数据」

效果

Dify Agent 会自动决定调用哪个工具，平台执行后把结果回灌给 Dify，Dify 再组织最终回答。

也可直接用 OpenAI 兼容方式：Dify 模型供应商配置中添加 OpenAI 兼容，Base URL 填 http://localhost:9301/v1。

---

2. n8n 接入

n8n 通过「HTTP Request」节点或 OpenAI 节点接入。

方式 A：OpenAI 节点（推荐，支持 Tool Calling）

1. 添加「OpenAI」节点
2. 模型供应商选「OpenAI API」，凭据中：
   • API Key：填平台 token
   • Base URL：http://localhost:9301/v1
3. 模型填 deepseek-chat（或平台配置的模型）
4. Tools 自动注入，无需手动配置

方式 B：HTTP Request 节点直接调用 Tool

{
  "method": "POST",
  "url": "http://localhost:9301/ai/tools/api_xxx/invoke",
  "headers": {"Content-Type":"application/json"},
  "body": {"args": {"param": {"limit": 5}}}
}

示例工作流

定时触发 → OpenAI 节点（带工具） → 写入 Excel，全程无需写代码。

---

3. LangChain / LangGraph (Python)

直接用 OpenAI SDK，Base URL 指向平台即可，tools 自动注入。

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:9301/v1",
    api_key="<平台token或任意值>"
)

# 方式 1：简单对话（工具自动注入）
resp = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role":"user","content":"查询 test_demo 表前 5 条数据"}]
)
print(resp.choices[0].message.content)

LangGraph Tool 节点

from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

# 平台作为 OpenAI 兼容后端
llm = ChatOpenAI(
    base_url="http://localhost:9301/v1",
    api_key="<token>",
    model="deepseek-chat"
)
# 工具由平台侧自动注入，LangGraph 侧无需定义 tools
agent = create_react_agent(llm, tools=[])
result = agent.invoke({"messages":[{"role":"user","content":"统计昨天的订单量"}]})
print(result["messages"][-1].content)

直接调用平台单个 Tool

import requests
r = requests.post(
    "http://localhost:9301/ai/tools/api_query_orders/invoke",
    json={"args": {"param": {"date": "2026-07-10"}}}
)
print(r.json())

---

4. Cursor 接入

Cursor 支持 MCP，直接配置平台 MCP 端点即可让 Cursor 调用你的全部能力。

在 Cursor 设置 → MCP 中添加：

{
  "mcpServers": {
    "sss-run": {
      "url": "http://localhost:9301/mcp"
    }
  }
}

配置后在 Cursor 对话中即可：「帮我查询 test_demo 表结构」「调用 xx 接口发一封邮件」。

---

5. Claude Desktop 接入

编辑 Claude Desktop 配置文件（claude_desktop_config.json）：

{
  "mcpServers": {
    "sss-run": {
      "url": "http://localhost:9301/mcp"
    }
  }
}

重启 Claude Desktop，即可在对话中调用平台工具。MCP 工具列表从 Tool Registry 动态生成。

---

6. OpenAI SDK (Node.js / TypeScript)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:9301/v1",
  apiKey: "<token>",
});

const resp = await client.chat.completions.create({
  model: "deepseek-chat",
  messages: [{ role: "user", content: "查询 test_demo 表前 5 条" }],
});
console.log(resp.choices[0].message.content);

---

7. 直接调用 Agent Runtime

不经过 LLM 的 Tool Calling，直接运行平台 Agent（适合程序化调用）：

curl -X POST http://localhost:9301/ai/agents/data-analyst/run \
  -H "Content-Type: application/json" \
  -d '{
    "input": "查询 test_demo 表并生成数据总结",
    "session_id": ""
  }'

返回 run_id 用于追踪，session_id 用于延续上下文。

---

8. 调用 RAG 知识库

# 创建知识库
curl -X POST http://localhost:9301/ai/knowledge \
  -d '{"name":"公司制度","embedding_model":"bge-large-zh"}'

# 上传文档
curl -X POST http://localhost:9301/ai/knowledge/<kb_id>/documents \
  -F "file=@policy.pdf"

# 检索
curl -X POST http://localhost:9301/ai/knowledge/<kb_id>/search \
  -d '{"query":"年假多少天","top_k":3}'

Agent 在对话中会自动调用 knowledge_search 工具回答知识库相关问题。

---

协议对照

平台	接入协议	端点
Dify	OpenAPI / OpenAI 兼容	/ai/export/openapi、/v1/chat/completions
n8n	OpenAI 兼容 / HTTP	/v1/chat/completions、/ai/tools/:name/invoke
LangChain/LangGraph	OpenAI 兼容	/v1/chat/completions
Cursor	MCP	/mcp
Claude Desktop	MCP	/mcp
OpenAI SDK	OpenAI 兼容	/v1/chat/completions
程序化调用	REST	/ai/agents/:name/run

所有接入方式共享同一份 Tool Registry，开发者只需在平台写一次接口，全部平台立即可用。