集成与连接

WesCraft 支持与外部工具和服务集成，让数据在不同平台之间自由流动，打通你的工作生态。

第三方服务

支持的平台

WesCraft 通过 MCP（Model Context Protocol）和原生集成支持多种第三方服务：

平台类型	支持的服务	集成方式
即时通讯	企业微信、飞书、钉钉	原生渠道适配
邮件	IMAP/SMTP 邮箱	原生邮件集成
云存储	百度网盘、阿里云盘	MCP Server
项目管理	Jira、Trello、Notion	MCP Server
代码托管	GitHub、GitLab	MCP Server
CRM	Salesforce、HubSpot	MCP Server
知识库	Confluence、语雀	MCP Server

配置第三方集成

打开 设置 → 集成
找到目标服务
点击连接
按提示完成授权或填写配置信息
测试连接是否成功

即时通讯集成

以企业微信为例：

在企业微信管理后台创建应用
获取 Corp ID、Agent ID 和 Secret
在 WesCraft 设置中填入上述信息
配置回调地址
连接成功后，可以通过企业微信与 AI 对话

集成后的功能：

在企业微信中直接发送问题给 AI
AI 处理结果推送回企业微信
企业微信中的文件自动同步到知识库
接收 WesCraft 的通知消息

邮件集成

配置邮箱后，WesCraft 可以：

接收邮件并自动归档到指定目录
AI 分析邮件内容并提取关键信息
发送 AI 生成的邮件
按规则自动处理特定邮件

Webhook

Webhook 允许 WesCraft 在特定事件发生时向外部系统发送通知。

创建 Webhook

打开 设置 → 集成 → Webhook
点击 新建 Webhook
配置参数：

参数	说明	示例
名称	Webhook 名称	"通知飞书机器人"
URL	目标地址	`https://open.feishu.cn/...`
事件	触发事件	页面创建、任务完成
格式	数据格式	JSON
密钥	验证签名	可选

支持的 Webhook 事件

事件	说明	Payload 包含
`page.created`	新页面创建	页面 ID、标题、创建者
`page.updated`	页面更新	页面 ID、修改内容摘要
`page.deleted`	页面删除	页面 ID、标题
`task.completed`	任务完成	任务 ID、标题、完成者
`task.overdue`	任务逾期	任务 ID、标题、逾期天数
`file.indexed`	文件索引完成	文件路径、索引结果
`ai.run.completed`	AI 任务完成	运行 ID、结果摘要

Webhook 请求格式

{
  "event": "page.created",
  "timestamp": "2026-09-14T21:00:00+08:00",
  "data": {
    "page_id": "p_abc123",
    "title": "新建的页面",
    "created_by": "user123",
    "path": "/项目A/设计文档"
  },
  "signature": "sha256=..."
}

重试机制

发送失败后自动重试 3 次
重试间隔：30 秒、2 分钟、10 分钟
连续失败 10 次后自动禁用，需手动重新启用

API 接口

WesCraft 提供 RESTful API 供外部系统访问。

认证方式

使用 API Token 认证：

打开 设置 → 集成 → API
点击 生成 Token
设置 Token 名称和权限范围
复制并妥善保管 Token

请求时在 Header 中携带：

Authorization: Bearer <your-api-token>

主要 API 端点

页面操作

方法	端点	说明
`GET`	`/api/pages`	获取页面列表
`GET`	`/api/pages/:id`	获取页面详情
`POST`	`/api/pages`	创建页面
`PATCH`	`/api/pages/:id`	更新页面
`DELETE`	`/api/pages/:id`	删除页面

搜索

方法	端点	说明
`GET`	`/api/search?q=关键词`	全文搜索
`POST`	`/api/search/semantic`	语义搜索

数据表

方法	端点	说明
`GET`	`/api/tables`	获取数据表列表
`GET`	`/api/tables/:id/rows`	获取数据表行
`POST`	`/api/tables/:id/rows`	插入行
`PATCH`	`/api/tables/:id/rows/:rowId`	更新行

AI 交互

方法	端点	说明
`POST`	`/api/chat`	发送消息给 AI
`GET`	`/api/chat/sessions`	获取会话列表

频率限制

级别	限制
个人版	60 次/分钟
团队版	300 次/分钟
单个 Token	30 次/分钟

超过限制后返回 429 Too Many Requests。

数据同步

双向同步

配置与外部数据源的双向同步：

在 设置 → 集成 → 数据同步 中添加同步源
选择同步方向（单向 / 双向）
映射字段对应关系
设置同步频率
启动同步

同步策略

策略	说明	适用场景
实时同步	数据变更立即同步	高实时性要求
定期同步	按设定间隔同步	大量数据批量处理
手动同步	手动触发同步	敏感数据谨慎同步

冲突解决

当双向同步出现冲突时：

以最新为准 — 保留最近修改的版本
以来源为准 — 以外部数据源为准
以本地为准 — 以 WesCraft 数据为准
手动解决 — 提示用户手动选择

同步日志

每次同步操作都会记录：

同步时间
同步方向
成功/失败记录数
冲突处理情况
错误详情（如有）

插件扩展

MCP Server 集成

WesCraft 支持通过 MCP 协议连接外部工具，扩展 AI 的能力范围。

添加 MCP Server

打开 设置 → 集成 → MCP
点击 添加 MCP Server
填写配置信息：

名称: my-custom-mcp
传输方式: stdio  # stdio 或 sse
命令: /path/to/mcp-server
参数: ["--port", "8080"]

点击 测试连接
连接成功后，MCP 提供的工具会自动出现在 AI 的可用工具列表中

MCP 工具在 AI 中的使用

连接 MCP Server 后，AI 可以调用其提供的工具。例如连接了数据库 MCP Server 后：

用户: 查询上个月销售额前10的产品
AI: [调用 database_query 工具]
    查询结果如下：
    1. 产品A — ¥150,000
    2. 产品B — ¥120,000
    ...

自定义工具开发

你可以开发自己的工具集成到 WesCraft。详见开发者文档。

安全与权限

API Token 管理

每个 Token 设置独立的权限范围（只读 / 读写 / 管理）
设置 Token 有效期
随时撤销不再使用的 Token
查看 Token 的使用记录

集成权限控制

团队版中，管理员可以控制：

哪些集成可以被启用
哪些成员可以配置集成
每个集成可以访问哪些数据

数据传输安全

所有 API 请求使用 HTTPS
Webhook 支持签名验证
MCP Server 通信走本地加密通道
敏感配置使用加密存储

注意事项

第三方集成的可用性取决于外部服务的状态
API Token 应妥善保管，不要泄露到公开场所
数据同步可能产生额外的存储开销
MCP Server 需要在本地或可访问的网络中运行
Webhook 的目标 URL 需要能从 WesCraft 服务器访问到

常见问题

Q: 如何调试 Webhook 发送失败？

在 Webhook 管理页面查看发送日志，包括请求详情和响应内容。也可以使用 webhook.site 等工具测试。

Q: API 请求超时怎么办？

检查网络连接，对于大数据量请求考虑使用分页参数。建议设置合理的超时时间（30 秒以上）。

Q: MCP Server 连接不上？

确认：① MCP 二进制路径正确 ② 有执行权限 ③ 端口未被占用 ④ 查看 MCP Server 的日志输出。