API 与集成

WesCraft 提供完整的 HTTP API，支持与第三方工具集成、自动化工作流和 Webhook 回调。你可以通过 API 管理页面、数据表、收集箱、任务等所有核心功能。

HTTP 网关概览

WesCraft 运行时启动一个内置 HTTP 网关，默认监听 :3100 端口。

基础信息

获取 API Token

1. 打开 WesCraft 设置（Ctrl+,）
2. 选择 开发者 → API Token
3. 点击 生成新 Token
4. 复制并妥善保管 Token

认证方式

在每个请求的 Header 中携带 Token：

curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:3100/v1/pages

核心 API

页面管理

列出页面

GET /v1/pages?limit=20&offset=0

响应示例：

{
  "items": [
    {
      "id": "page-abc123",
      "title": "项目计划",
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-01-20T14:30:00Z",
      "parent_id": null
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

获取页面内容

GET /v1/pages/{pageId}

创建页面

POST /v1/pages
Content-Type: application/json

{
  "title": "新页面标题",
  "content": "页面内容，支持 Markdown",
  "parent_id": "page-parent123",
  "tags": ["标签1", "标签2"]
}

更新页面

PATCH /v1/pages/{pageId}
Content-Type: application/json

{
  "title": "更新后的标题",
  "content": "更新后的内容"
}

删除页面

DELETE /v1/pages/{pageId}

搜索

全文搜索

GET /v1/search?q=关键词&type=page&limit=10

参数说明：

收集箱

添加到收集箱

POST /v1/inbox
Content-Type: application/json

{
  "title": "自动采集的内容",
  "content": "正文内容...",
  "source": "api",
  "tags": ["自动化"],
  "metadata": {
    "source_url": "https://example.com/article",
    "author": "张三"
  }
}

列出收集箱内容

GET /v1/inbox?status=unread&limit=20

处理收集箱项目

POST /v1/inbox/{itemId}/convert
Content-Type: application/json

{
  "target": "page",
  "parent_id": "page-parent123",
  "ai_enhance": true
}

数据表

查询数据表记录

POST /v1/databases/{dbId}/query
Content-Type: application/json

{
  "filter": {
    "field": "状态",
    "operator": "equals",
    "value": "进行中"
  },
  "sort": {
    "field": "创建时间",
    "direction": "desc"
  },
  "limit": 50
}

自然语言查询

POST /v1/databases/{dbId}/ai-query
Content-Type: application/json

{
  "query": "找出本月金额最大的 5 笔订单"
}

创建记录

POST /v1/databases/{dbId}/records
Content-Type: application/json

{
  "fields": {
    "名称": "新项目",
    "状态": "待办",
    "优先级": "高",
    "截止日期": "2026-03-01"
  }
}

更新记录

PATCH /v1/databases/{dbId}/records/{recordId}
Content-Type: application/json

{
  "fields": {
    "状态": "已完成"
  }
}

任务

列出任务

GET /v1/tasks?status=pending&limit=20

创建任务

POST /v1/tasks
Content-Type: application/json

{
  "title": "完成季度报告",
  "description": "整理 Q4 数据并撰写总结报告",
  "priority": "high",
  "due_date": "2026-02-15",
  "tags": ["季度报告", "Q4"]
}

AI 对话

发送消息并获取 AI 回复

POST /v1/chat
Content-Type: application/json

{
  "session_id": "session-abc",
  "message": "帮我总结一下项目计划页面的要点",
  "context": {
    "page_id": "page-abc123"
  }
}

响应为 SSE 流式输出。

第三方工具集成

与 n8n 集成

WesCraft 可以作为 n8n 工作流的数据源和目标：

1. 在 n8n 中添加 HTTP Request 节点
2. 配置 WesCraft API 地址和 Token
3. 构建自动化流程

示例工作流：RSS 订阅 → 提取内容 → 保存到 WesCraft 收集箱

与 Zapier 集成

通过 Webhook 触发器实现 Zapier 集成：

1. 在 WesCraft 中配置 Webhook 出站通知
2. 在 Zapier 中创建 Catch Hook 触发器
3. 配置后续操作步骤

与命令行工具集成

使用 curl 或任何 HTTP 客户端调用 API：

# 获取今日待办任务
curl -s -H "Authorization: Bearer $TOKEN" \
  "http://localhost:3100/v1/tasks?status=pending&due=today" | jq .

# 快速添加笔记到收集箱
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"快速笔记","content":"临时想法..."}' \
  http://localhost:3100/v1/inbox

自动化工作流

定时任务

结合系统 cron 或外部调度器，实现自动化：

# 每天早上 9 点生成任务摘要
0 9 * * * curl -X POST http://localhost:3100/v1/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"生成今日任务摘要并发送到收集箱"}'

文件监听

通过 API 结合文件系统监听工具（如 fswatch），自动导入文件变更：

# 监听指定目录，新文件自动导入
fswatch ~/Documents/notes/ | while read file; do
  curl -X POST http://localhost:3100/v1/inbox \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"title\":\"$(basename $file)\",\"content\":\"$(cat $file)\"}"
done

Webhook 使用

配置出站 Webhook

当 WesCraft 中发生特定事件时，可以向外部 URL 发送通知。

1. 打开设置 → 开发者 → Webhook
2. 点击 添加 Webhook
3. 配置：
   • URL：接收通知的外部地址
   • 事件：触发的事件类型
   • 密钥：用于验证请求来源的签名密钥

支持的事件类型

Webhook 请求格式

{
  "event": "page.created",
  "timestamp": "2026-01-20T14:30:00Z",
  "data": {
    "id": "page-abc123",
    "title": "新建的页面",
    "created_by": "user-xyz"
  },
  "signature": "sha256=..."
}

验证签名

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(), payload.encode(), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

错误处理

HTTP 状态码

错误响应格式

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "字段 'title' 不能为空",
    "details": {}
  }
}

请求频率限制

• 默认限制：100 次/分钟
• 搜索接口：30 次/分钟
• AI 对话接口：10 次/分钟

注意事项

1. Token 安全：API Token 等同于账户权限，请妥善保管，不要在客户端代码中硬编码
2. 本地访问：默认仅允许本机访问，如需远程访问请配置网络安全策略
3. 数据一致性：API 操作和 UI 操作使用同一数据源，实时同步
4. 版本兼容：API 路径以 /v1/ 开头，未来不兼容变更会使用 /v2/
5. SSE 流：AI 对话接口使用 SSE 流式输出，请使用支持 SSE 的客户端库

相关文档

• 数据表高级功能
• 收集箱
• 故障排查