🏗️ 关于

一个用于将 Bigin CRM 接入 OpenClaw 的简易技能

前提条件

• Bigin 账户（推荐使用开发者沙箱环境）
• Python 3.8+
• requests 库（执行 pip install requests 安装）

🏗️ 架构

┌─────────────────────────────────────────┐
│         OpenClaw Agent                  │
│  （您的个人销售助手）                   │
└─────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────┐
│      Bigin CRM Skill（Python）          │
│  - OAuth2 认证                          │
│  - REST API v2 封装器                   │
│  - 销售管线自动化                       │
│  - 联系人/公司管理                      │
└─────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────┐
│        Bigin CRM REST API v2            │
│  - 销售管线（核心销售模块）             │
│  - 联系人与公司                         │
│  - 任务、事件、通话                     │
│  - 产品与备注                           │
└─────────────────────────────────────────┘

🛠️ 核心功能

1. 认证与初始化

# 一次性 OAuth 初始化
bigin auth --client-id "1000.xxx" --client-secret "xxx"
# 自动打开浏览器进行 Bigin/Zoho 登录
# 凭据安全存储于 ~/.openclaw/credentials/bigin-crm.json

# 查看当前认证状态
bigin auth:whoami

2. 管线管理（核心功能）

# 创建一条管线记录（例如：商机/交易）
bigin pipeline create --contact-id 12345 --company-id 67890 
  --stage "Initial Contact" --amount 50000 
  --closing-date "2026-03-15" --owner "sales@yourcompany.com"

# 更新管线阶段
bigin pipeline update --id 12345678 --stage "Negotiation" 
  --amount 75000 --probability 70

# 推进至下一阶段
bigin pipeline advance --id 12345678

# 标记为成交或失败
bigin pipeline win --id 12345678
bigin pipeline lose --id 12345678 --reason "Budget constraints"

# 列出所有管线（按阶段、负责人筛选）
bigin pipeline list --stage "Proposal" --owner "me" --limit 50

# 搜索管线
bigin pipeline search --query "company:Acme" --stage "Open"

# 获取管线详情（含历史记录）
bigin pipeline get --id 12345678 --include-history

3. 联系人管理

# 创建联系人
bigin contact create --first-name "John" --last-name "Doe" 
  --email "john@company.com" --phone "+91-98765-43210" 
  --company "Acme Inc" --source "Website"

# 从 CSV 批量导入
bigin contact import --file contacts.csv --mapping mapping.json

# 搜索联系人
bigin contact search --query "company:Acme" --limit 100

# 更新联系人信息
bigin contact update --id 87654321 --phone "+91-99999-88888"

# 获取联系人详情（含关联管线）
bigin contact get --id 87654321 --include-pipelines

4. 公司管理

# 创建公司
bigin company create --name "Acme Inc" --industry "Technology" 
  --website "https://acme.com" --employees 50 
  --address "123 Business Park, Bengaluru"

# 搜索公司
bigin company search --query "industry:Technology"

# 获取公司详情（含全部联系人及管线）
bigin company get --id 67890 --include-contacts --include-pipelines

5. 任务与活动管理

# 创建跟进任务
bigin task create --related-to pipeline:12345678 
  --subject "Send proposal" --due "2026-02-25" --priority "High"

# 创建事件（会议）
bigin event create --related-to contact:87654321 
  --title "Product Demo" --start "2026-02-24 14:00" --duration 30 
  --location "Zoom"

# 记录一次通话
bigin call create --related-to contact:87654321 
  --subject "Discovery call" --duration 15 
  --outcome "Interested, follow-up scheduled"

# 列出即将到期的任务
bigin task list --due-before "2026-02-28" --status "Open"

# 标记任务为已完成
bigin task complete --id 54321

6. 管线自动化

# 自动分配未指派的管线（轮询模式）
bigin pipeline assign --unassigned --round-robin

# 为滞留管线创建跟进任务
bigin automation follow-up --stale-days 7 --create-tasks

# 基于用户活动自动推进管线阶段
bigin automation advance --auto-advance --criteria "proposal-sent-and-7-days"

# 批量更新管线阶段
bigin pipeline bulk-update --stage "Negotiation" 
  --new-stage "Closed Won" --criteria "probability-gt-80"

7. 报表与分析

# 管线报表
bigin report pipeline --by-stage --by-owner --output pipeline-report.csv

# 销售业绩报表
bigin report performance --owner "sales@company.com" 
  --month "2026-02" --output performance.json

# 销售预测（按概率加权）
bigin forecast --month "2026-03" --output forecast.csv

# 活动报表
bigin report activity --user "me" --week "2026-08" 
  --include-calls --include-tasks --include-events

8. AI 驱动功能

# 自动通过邮箱丰富联系人信息
"当我收到新发件人的邮件时，自动创建联系人，并检查其所属公司是否已存在"

# 智能管线评分
"基于以下维度对所有开放管线进行评分：最近活动时间、邮件回复情况、所处阶段时长、公司规模"

# 跟进提醒
"哪些联系人已超过 7 天未被触达？为其批量创建任务"

# 会议准备
"在我下午 2 点的产品演示前，请提供：该联系人历史记录、活跃中的管线、最近 3 封往来邮件、公司详细信息"

# 管线健康检查
"识别在相同阶段停留超过 14 天的管线，并建议下一步行动方案"

9. 与 Zoho Email Skill 集成

# 统一流程：邮件 → Bigin
# 1. 收到潜在客户邮件
# 2. 解析发件人信息 → 创建/更新联系人
# 3. 检查公司是否存在 → 如不存在则新建
# 4. 若无对应管线，则新建一条
# 5. 分配给销售代表
# 6. 设置跟进任务
# 7. 自动发送确认回执

📁 项目结构

bigin-crm-skill/
├── SKILL.md                          # 技能文档
├── config/
│   ├── bigin-config.json             # API 端点配置（bigin/v2）
│   └── oauth-config.json             # Client ID/secret 模板
├── scripts/
│   ├── bigin_crm.py                  # 主 Python 模块
│   ├── auth.py                       # OAuth2 流程（ZohoBigin 权限范围）
│   ├── pipelines.py                  # 管线操作（核心！）
│   ├── contacts.py                   # 联系人管理
│   ├── companies.py                  # 公司/客户账户管理
│   ├── tasks.py                      # 任务管理
│   ├── events.py                     # 事件/会议管理
│   ├── calls.py                      # 通话日志管理
│   ├── reports.py                    # 分析与报表
│   └── automation.py                 # 管线自动化
├── examples/
│   ├── bulk-import-contacts.csv      # 示例导入文件
│   ├── pipeline-mapping.json         # 管线阶段映射配置
│   └── automation-workflows/         # 预置工作流
│       ├── auto-assign.yaml
│       ├── follow-up-reminders.yaml
│       └── stage-advancement.yaml
├── tests/
│   ├── test_pipelines.py             # 管线单元测试
│   ├── test_contacts.py              # 联系人单元测试
│   └── test_automation.py            # 自动化单元测试
└── README.md                         # 安装与使用说明

📚 资源

Bigin API 文档

• Bigin API v2 概览： https://www.bigin.com/developer/docs/apis/v2/
• 模块 API： https://www.bigin.com/developer/docs/apis/v2/modules-api.html
• 批量 API： https://www.bigin.com/developer/docs/apis/v2/bulk-read/overview.html
• OAuth 指南： https://www.bigin.com/developer/docs/apis/v2/oauth-overview.html
• 通知 API： https://www.bigin.com/developer/docs/apis/v2/notifications/overview.html

Zoho OAuth 控制台

• API 控制台： https://api-console.zoho.com/
• 创建 “Server-based Application” 类型应用以启用 OAuth2

🚀 快速开始

前提条件

• Bigin 账户（推荐使用开发者沙箱环境）
• Python 3.8+
• requests 库（执行 pip install requests 安装）

步骤 1：创建 Zoho OAuth 应用

1. 访问 https://api-console.zoho.com/
2. 点击 “Add Client” → 选择 “Server-based Application”
3. 设置重定向 URI：http://localhost:8888/callback
4. 勾选权限范围：ZohoBigin.modules.ALL、ZohoBigin.settings.ALL
5. 记录下 Client ID 和 Client Secret

步骤 2：初始化项目

mkdir -p ~/.openclaw/skills/bigin-crm-skill
cd ~/.openclaw/skills/bigin-crm-skill
touch SKILL.md README.md
mkdir -p scripts config examples tests