内容
# Clay Backend 插件
[](LICENSE)
[](pyproject.toml)
一个 Claude Code 插件，用于填补 Clay 的聚合功能空白。Clay 逐行分析数据 - 该插件存储这些结果，添加语义搜索，并让 Claude 跨所有记录找到模式。
> "本周 8 个电话发现不足。预算资格是 #1 的空白 - 而且情况正在恶化。"
>
> "过去 5 次公司数据丰富中有 3 次标记了融资轮次，但没有一个潜在客户被路由到企业 AE。"
>
> "本月 4 个账户的支持票证情绪转为负面 - 都与相同的 onboarding 差距有关。"
>
> 这些洞察在 Clay 中是不可能的。他们需要跨行查看。此插件使它们自动出现。
## 快速开始
在 Claude Code 中：
```bash
/plugin marketplace add garavitgabriel/clay-backend-plugin
/plugin install clay-backend-plugin@garavitgabriel
```
告诉 Claude：**“我有一个 Clay 导出需要分析”** - 插件将指导您完成导入，然后您可以提问。
## 工作原理
```bash
Clay（每记录 AI 分析）
↓ webhook（自动）或 CSV 导出（手动）
Clay Backend 插件
├── webhook 服务器接收数据，因为 Clay 处理每一行
├── 本地存储记录（SQLite）
├── 为语义搜索生成嵌入
└── 通过 MCP 工具查询 Claude → 直接合成洞察
```
无需 Docker。无需外部数据库。无需服务器管理。
---
## 获取数据
### 选项 1：实时 Webhooks（推荐）
Clay 在处理每一行时自动发送数据。
```bash
您： “如何连接 Clay？”
Claude： → 显示 webhook URL + Clay 的 HTTP API 列的精确 JSON 正文模板
```
在 Clay 中，为您的表格添加一个 **HTTP API** 丰富列：
| 设置 | 值 |
|---------|-------|
| 方法 | POST |
| URL | `http://localhost:8742/webhook` |
| 正文 | 参见下文 |
```json
{
"record_id": "{{行 ID}}",
"analysis_type": "call_analysis",
"data": {
"summary": "{{AI 摘要}}",
"score": "{{分数}}",
"rep": "{{代表姓名}}"
},
"entity_id": "{{交易 ID}}",
"entity_name": "{{公司名称}}"
}
```
每次 Clay 处理一行时，结果会自动流入插件。
**将 Clay Cloud 连接到您的本地机器：**
Clay 在云中运行，因此它无法直接访问 `localhost`。使用 [ngrok](https://ngrok.com) 创建一个安全隧道：
```bash
# 安装和身份验证（一次性）
brew install ngrok
ngrok config add-authtoken <您的令牌> # ngrok.com 上的免费帐户
# 启动隧道
ngrok http 8742
```
在 Clay 中使用 ngrok URL（例如 `https://abc123.ngrok-free.app/webhook`）代替 localhost。
**安全性：** 在通过 ngrok 暴露时，在插件配置中设置 `WEBHOOK_API_KEY`。webhook 端点将需要所有请求中的 `Authorization: Bearer <key>`。询问 Claude “什么是 webhook URL？” - 它将显示要添加的确切标头。
Webhook 服务器默认绑定到 `127.0.0.1`（仅限此机器）- ngrok 隧道到 localhost，因此不需要其他操作。只有当网络上的另一个设备必须直接访问它时，才设置 `WEBHOOK_HOST=0.0.0.0`（或 `clay-webhook-daemon --host 0.0.0.0`），并设置 `WEBHOOK_API_KEY`。
### 选项 2：CSV 导入
导出您的 Clay 表格为 CSV，然后：
```bash
您： “导入此 CSV 调用分析” → 丢弃文件路径
Claude: “哪一列有行 ID？我们应该称此分析类型为什么？”
→ 映射列 → 导入 47 条记录 → “完成。询问我来查找模式！”
```
### 选项 3：粘贴 JSON
复制 Clay 的结构化分析输出并直接粘贴。Claude 将解析并导入它。
---
## 您可以使用
### 提问（交互式）
适用于任何类型的 Clay 数据 - 销售电话，公司丰富，支持票证，潜在客户评分，电子邮件分析，内容研究，竞争情报。
**查找模式：**
```bash
“您在查看本周的潜在客户丰富数据时看到什么模式？”
“我们最近 30 次销售电话中的常见异议是什么？”
“这些票证中有哪些支持问题反复出现？”
```
**语义搜索：**
```bash
“查找提到了融资的公司”
“显示给我表达了紧迫感的潜在客户”
“哪些丰富功能标记了合规问题？”
```
**跨类型比较：**
```bash
“比较我们的丰富数据与同一家公司的实际电话结果”
“电子邮件情绪如何与这些帐户的交易阶段相关联？”
“显示给我潜在客户评分与代表评估不一致的地方”
```
**跟踪趋势：**
```bash
“过去 3 周的潜在客户质量是否有所改善或恶化？”
“本季度竞争对手提及的频率发生了什么变化？”
“支持票证主题是否随着月份的变化而变化？”
```
### 自动分析（定时）
使用 `schedules.yaml` 配置运行守护进程 - 技能在 cron 上执行并将结果交付到 Slack 或返回 Clay。
```bash
clay-webhook-daemon --schedules schedules.yaml
```
```yml
schedules:
# 每周销售辅导摘要 → 每周一发送到 Slack
- name: weekly-coaching-digest
skill: analyze-patterns
cron: "0 8 * * 1"
context:
analysis_type: call_analysis
since: "7 天前"
prompt: "按代表划分的优先级和具体证据。"
outputs:
- type: slack
webhook_url: https://hooks.slack.com/services/XXX
# 每天潜在客户质量警报 → Slack 如果有问题
- name: lead-quality-check
skill: analyze-patterns
cron: "0 18 * * *"
context:
analysis_type: lead_scoring
since: "1 天前"
prompt: "如果平均质量低于 B，则提醒。"
outputs:
- type: slack
webhook_url: https://hooks.slack.com/services/XXX
# 每月丰富度审查 → 返回 Clay 进行路由
- name: monthly-enrichment-review
skill: analyze-patterns
cron: "0 9 1 * *"
context:
analysis_type: company_enrichment
since: "30 天前"
outputs:
- type: clay_webhook
url: https://your-clay-webhook-table
```
技能是游戏规则 - 相同的 `analyze-patterns` 技能在 Claude Code 中交互式地工作，并且通过调度器自动执行。编写一次，以两种方式使用。
输出发送到 **Slack** （传入 webhook）或 **Clay** （webhook 表 → Clay 路由到 Slack，电子邮件，CRM 或其他任何目的地）。
---
## 始终在线模式（可选）
默认情况下，webhook 服务器在 Claude Code 打开时运行。如果您希望数据 24 小时不间断积累 - 即使在晚上或周末 - 运行独立守护进程：
```bash
clay-webhook-daemon
```
这运行 webhook 接收器作为一个单独的后台进程。相同的数据库 - 当您下次打开 Claude Code 时，所有记录都已经存在。
```bash
# 自定义端口和数据目录
clay-webhook-daemon --port 9000 --data-dir ~/clay-data
# 在 Mac 上后台运行
nohup clay-webhook-daemon > /dev/null 2>&1 &
```
---
## 嵌入
嵌入功能支持语义搜索 - 按含义查找记录，而不是关键词。
| 提供商 | 成本 | 设置 |
|----------|------|-------|
| **OpenAI** （推荐） | 约 0.008 美元/1000 条记录 | 在插件配置中设置 `OPENAI_API_KEY` |
| **本地** | 免费 | `pip install clay-backend-plugin[local-embeddings]` （约 80MB 模型） |
| **无** | - | 跳过嵌入。过滤器和文本搜索仍然有效。 |
通过安装后的插件设置进行配置。如果您有 OpenAI 密钥（大多数 Clay 用户都有），这是最简单的途径。
---
## MCP 工具
为 Claude 提供 9 种工具：
| 工具 | 功能 |
|------|-------------|
| `ingest_records` | 导入 JSON 记录。自动去重。 |
| `ingest_csv` | 导入具有列映射的 CSV 文件。 |
| `query_records` | 按类型、实体、标签、日期范围或文本搜索筛选记录。 |
| `semantic_search` | 使用嵌入的跨记录自然语言搜索。 |
| `get_record` | 按 ID 获取单个记录。 |
| `list_analysis_types` | 显示存储的数据类型及其计数。 |
| `get_analytics` | 汇总统计数据、主要实体、存储大小。 |
| `get_webhook_url` | 获取 webhook URL 和 Clay 配置模板。 |
| `delete_records` | 删除记录类型、日期或 ID（需要至少一个筛选器）。 |
## 技能
| 技能 | 何时触发 |
|-------|-----------------|
| `/import-data` | 用户希望导入 Clay 数据（CSV、JSON 或粘贴） |
| `/analyze-patterns` | 用户询问模式、趋势、比较、辅导优先级 |
| `/setup-guide` | 用户询问如何设置或开始 |
---
## 数据架构
记录使用 **灵活的 JSON 架构** - 不绑定于销售、支持或任何特定领域：
```json
{
"record_id": "row-001",
"analysis_type": "call_analysis",
"data": { "any": "JSON you want" },
"entity_id": "deal-100",
"entity_name": "Acme Corp",
"tags": ["discovery", "qualified"],
"source": "gong"
}
```
仅 `record_id`、`analysis_type` 和 `data` 是必需的。其他所有内容都是可选的。
**事件时间 (`created_at`)**：可选地在分析事件发生的时间早于导入时包含 `created_at`（ISO 8601）- 例如，回填一个月通话分析。时间窗口查询（`since`/`until`，计划的“最近 7 天”运行）在此字段上过滤，因此如果没有它，批量导入都会折叠到导入日期。CSV 导入可以使用 `created_at_column` 进行映射。
**去重**: 记录由 `record_id` + `analysis_type` 唯一标识。发送相同的组合将更新现有的记录。
**跨记录连接**：使用 `entity_id` 当相同的交易/公司/潜在客户在多个表格中被分析时（例如，BDR 通话分析 + AE 通话分析 + 电子邮件情绪）。这就是实现跨阶段比较的原因。
---
## 用例
该插件适用于任何产生每记录 AI 分析的 Clay 工作流程。`data` 字段是灵活的 JSON - 插件不关心里面有什么。
### 销售辅导
Clay 分析 Gong 通话记录 → 插件发现团队范围内的辅导空白。
```
“您在查看上周的通话时看到什么模式？”
→ 预算资格在 65% 的通话中被跳过 - 全团队，而不仅仅是一个代表。
Bob 的通话平均分数为 34（团队平均 62）- 完全跳过发现。
潜在客户质量从 B 下降到 C+ - 9 个 D 级潜在客户来自同一个 webinar 活动。
```
安排每周 Slack 摘要，每周一发送 → 经理走进办公室时知道优先级。
### 公司丰富度和潜在客户路由
Clay 丰富公司（融资数据、技术栈、员工人数）→ 插件发现丰富数据中的模式。
```
“哪些本周丰富的数据看起来像企业前景，但被路由到 SMB 代表？”
→ 7 家公司被标记：所有公司都有 500 多名员工和最近的 Series C，
但由于评分模型优先考虑域名流量而不是员工人数，因此被评为 SMB。
建议调整路由阈值。
```
### 支持票证分析
Clay 对 Zendesk 票证进行情绪和主题分析 → 插件发现系统性问题。
```
“本月的主要支持主题是什么？它们是否正在恶化？”
→ 入门摩擦是 #1（34% 的票证）。它集中在
账户在 3 月 UI 更新后注册。12 个问题中有 8 个提到了
“找不到设置页面” - 可能是一个导航回归。
```
### 竞争情报
Clay 监控竞争对手在通话、电子邮件和新闻中的提及 → 插件跟踪发言权。
```
“[竞争对手 X] 被提及的频率是多少，上下文是什么？”
→ 竞争对手 X 在本月 45 次通话中被提及 18 次，比上个月的 9 次有所增加。背景发生了变化：以前提及的是“也在评估中”，
现在提及的是“向我们展示了演示”。他们在我们的中市场细分领域变得更加咄咄逼人。
```
### 电子邮件活动分析
Clay 对电子邮件回复进行情绪和意图评分 → 插件衡量活动效果。
```
“比较我们最近 3 次外发活动的回复情绪”
→ 活动 A（案例研究角度）：72% 积极回应，15% 预订会议
活动 B（ROI 计算器）：45% 积极，8% 会议
活动 C（冷介绍）：23% 积极，3% 会议
清晰的赢家。活动 A 的方法应该是模板。
```
### 跨阶段管道
多个 Clay 表格（BDR 通话 + AE 通话 + 潜在客户评分）通过交易 ID 连接 → 插件连接它们。
```
“交易在 BDR 资格和 AE 发现之间何处中断？”
→ 6 个匹配的交易中有资格差异。BDR 将其评为 B+，基于热情。
AE 发现没有确认的预算。 6 个中有 5 个 BDR 视为确认。
根本原因：BDR 将“我们有预算购买此类工具”视为
已确认。他们需要询问一个特定的数字。
```
---
## 架构
```
插件
├── .claude-plugin/plugin.json 插件清单 + 用户配置
├── .mcp.json MCP 服务器配置（自动启动）
├── skills/ 引导工作流（3 个技能）
├── agents/ 合成子代理
└── src/clay_backend/
├── server.py MCP 服务器（9 个工具）+ webhook 启动
├── webhook_server.py HTTP POST /webhook + GET /health
├── daemon.py 独立 webhook CLI
├── database.py SQLite + sqlite-vec
├── models.py Pydantic 模型
├── services/
│ ├── record_service.py 存储、去重、查询、聚合
│ ├── embedding_service.py 提供商工厂 + 文本提取
│ └── search_service.py 向量相似性搜索
└── embeddings/
├── base.py 抽象提供商接口
├── openai_provider.py text-embedding-3-small（1536 维）
└── local_provider.py all-MiniLM-L6-v2（384 维）
数据：`~/.claude/plugins/data/clay-backend-plugin/clay.db`
Webhook：`http://localhost:8742/webhook`
```
---
## 主机模式（可选）
不想处理 ngrok？将 webhook 接收器部署为一个小型托管服务并获取永久 URL。
**部署到 Railway/Render：** 仓库包括 `railway.toml`、`nixpacks.toml` 和 `hosted/render.yaml` - 将任一平台指向仓库并构建 `hosted/` 服务。设置 `DATABASE_URL`（PostgreSQL）和 `API_KEY` 环境变量。
**或手动部署：```bash
cd hosted/
# 设置 DATABASE_URL 到 PostgreSQL 实例
# 设置 API_KEY 进行身份验证
docker build -t clay-backend .
docker run -p 8000:8000 -e DATABASE_URL=... -e API_KEY=... clay-backend
```
然后配置插件使用远程模式：
```
REMOTE_URL=https://your-app.railway.app
REMOTE_API_KEY=your-api-key
```
远程模式下，插件查询托管服务而不是本地 SQLite。无需本地 webhook 服务器，无需 ngrok - Clay 直接发布到您的永久 URL。
| | 本地模式 | 远程模式 |
|--|-----------|-------------|
| 存储 | 您的机器上的 SQLite | 服务器上的 PostgreSQL |
| Webhook URL | localhost（需要 ngrok） | 永久公共 URL |
| 语义搜索 | 通过 OpenAI/本地嵌入 | 文本搜索（嵌入中） |
| 成本 | 免费 | ~$5/mo（Railway/Render） |
| 始终在线 | 需要守护进程运行 | 是的，24/7 |
---
## 开发
```bash
git clone https://github.com/garavitgabriel/clay-backend-plugin.git
cd clay-backend-plugin
# 安装所有内容（venv + 本地嵌入 + 调度器 + pytest）
make install
# — 或手动：
uv venv && uv pip install -e ".[local-embeddings,scheduler]`
# 使用 Claude Code 测试
claude --plugin-dir .
# 运行测试 / 校验 / 端到端烟雾（webhook → 导入 → 搜索）
make test
make lint
make smoke
```
> 调度器额外功能（anthropic、apscheduler、pyyaml、httpx）是 `clay_backend.scheduler` 所需的。纯 `[local-embeddings]` 安装涵盖所有其他功能。
## 路线图
- [x] 带有 9 个工具的 MCP 服务器（存储、查询、搜索、分析）
- [x] 可插拔的嵌入（OpenAI + 局部句子转换器）
- [x] 通过 sqlite-vec 进行语义搜索
- [x] Webhook HTTP 服务器（自动接收 Clay 数据）
- [x] 独立 webhook 守护进程（24/7 收集）
- [x] 引导式导入和分析技能
- [x] 合成代理进行深层跨记录分析
- [x] 主机后端选项（FastAPI + PostgreSQL）一键部署
- [x] 调度技能执行（cron → Anthropic API → Slack/Clay 交付）
- [ ] 主机模式下的嵌入支持（pgvector）
- [ ] 邮件输出用于调度报告
- [ ] 用于调度合成的大型记录] [ ] 嵌入支持（pgvector）
- [ ] Map-reduce 分片，用于非常大的记录集的调度综合（当前：显式预算提示，省略说明）
