Craft.do 集成技能

为 Craft.do 提供完整的 REST API 集成——这是一款优雅的笔记与文档应用。

概述

本技能提供对 Craft.do 的完整程序化访问，支持：
- 任务自动化： 在收件箱/每日笔记/日志簿中创建、更新和管理任务
- 文档工作流： 以编程方式创建、读取和组织文档
- 文件夹管理： 通过 API 构建嵌套文件夹层级
- Obsidian 迁移： 一次性完整迁移知识库，保留所有内容
- 内容操作： 通过区块 API 添加/编辑 Markdown 内容

Craft.do 核心功能：
- 原生 Markdown 支持
- 任务管理（收件箱、每日笔记、日志簿）
- 集合（数据库表格）
- 层级化的文件夹和文档
- 完整的 REST API 访问

设置

1. 从 Craft.do 设置中获取您的 API 密钥。
2. 安全地存储凭据：

export CRAFT_API_KEY="pdk_xxx"
export CRAFT_ENDPOINT="https://connect.craft.do/links/YOUR_LINK/api/v1"

API 功能

✅ 已实现功能

列出文件夹

curl -H "Authorization: Bearer $CRAFT_API_KEY" \
  "$CRAFT_ENDPOINT/folders"

返回所有位置：未分类、每日笔记、回收站、模板以及自定义文件夹。

列出文档

curl -H "Authorization: Bearer $CRAFT_API_KEY" \
  "$CRAFT_ENDPOINT/documents?folderId=FOLDER_ID"

创建文件夹（支持可选父文件夹以实现嵌套）

# 根级文件夹
curl -X POST \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "folders": [{
      "name": "项目"
    }]
  }' \
  "$CRAFT_ENDPOINT/folders"

# 嵌套文件夹（需要父文件夹 ID）
curl -X POST \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "folders": [{
      "name": "2024年第一季度",
      "parentFolderId": "PARENT_FOLDER_ID"
    }]
  }' \
  "$CRAFT_ENDPOINT/folders"

创建文档

curl -X POST \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [{
      "title": "文档标题"
    }],
    "destination": {
      "folderId": "FOLDER_ID"
    }
  }' \
  "$CRAFT_ENDPOINT/documents"

注意： 文档创建时初始无内容。请使用 /blocks 端点来添加内容。

向文档添加内容

curl -X POST \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "blocks": [{
      "type": "text",
      "markdown": "# 文档内容\n\n支持完整的 Markdown 语法！"
    }],
    "position": {
      "pageId": "DOCUMENT_ID",
      "position": "end"
    }
  }' \
  "$CRAFT_ENDPOINT/blocks"

读取文档内容

curl -H "Authorization: Bearer $CRAFT_API_KEY" \
  "$CRAFT_ENDPOINT/blocks?id=DOCUMENT_ID"

返回包含所有区块的完整 Markdown 内容。

创建任务

curl -X POST \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tasks": [{
      "markdown": "任务描述",
      "location": {"type": "inbox"},
      "status": "active"
    }]
  }' \
  "$CRAFT_ENDPOINT/tasks"

更新任务（标记为完成）

curl -X PUT \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tasksToUpdate": [{
      "id": "TASK_ID",
      "markdown": "- [x] 已完成任务"
    }]
  }' \
  "$CRAFT_ENDPOINT/tasks"

列出任务

# 活动任务
curl -H "Authorization: Bearer $CRAFT_API_KEY" \
  "$CRAFT_ENDPOINT/tasks?scope=active"

# 所有已完成任务（日志簿）
curl -H "Authorization: Bearer $CRAFT_API_KEY" \
  "$CRAFT_ENDPOINT/tasks?scope=logbook"

# 即将到来的任务
curl -H "Authorization: Bearer $CRAFT_API_KEY" \
  "$CRAFT_ENDPOINT/tasks?scope=upcoming"

# 仅收件箱任务
curl -H "Authorization: Bearer $CRAFT_API_KEY" \
  "$CRAFT_ENDPOINT/tasks?scope=inbox"

移动文档

curl -X PUT \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documentIds": ["DOC_ID"],
    "destination": {"location": "unsorted"}
  }' \
  "$CRAFT_ENDPOINT/documents/move"

注意：只能移动到 unsorted、templates 或自定义文件夹 ID。不能直接移动到 trash。

❌ 当前限制

• 无集合 API - 集合（数据库）无法通过 API 访问
• 无法删除任务 - 只能创建/更新任务，不能删除
• 无法删除文档 - 不能直接删除文档（只能移动）
• 无搜索端点 - 搜索需要特定查询格式（需更多测试）
• 过滤功能有限 - 集合的过滤/分组仅在 UI 中可用，API 不支持

常见用例

从外部系统同步任务

# 从 Mission Control 在 Craft 中创建任务
TASK_TITLE="部署新功能"
curl -X POST \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"tasks\": [{
      \"markdown\": \"$TASK_TITLE\",
      \"location\": {\"type\": \"inbox\"},
      \"status\": \"active\"
    }]
  }" \
  "$CRAFT_ENDPOINT/tasks"

创建每日笔记

TODAY=$(date +%Y-%m-%d)
curl -X POST \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"documents\": [{
      \"title\": \"每日笔记 - $TODAY\",
      \"content\": [{\"textContent\": \"# $TODAY\\n\\n## 任务\\n\\n## 笔记\\n\"}],
      \"location\": \"daily_notes\"
    }]
  }" \
  "$CRAFT_ENDPOINT/documents"

归档已完成的工作

# 获取所有已完成任务
curl -H "Authorization: Bearer $CRAFT_API_KEY" \
  "$CRAFT_ENDPOINT/tasks?scope=logbook" | jq '.items[] | {id, markdown, completedAt}'

集成模式

Mission Control → Craft 同步

问题： Mission Control 有自动化功能但界面简陋。Craft 界面美观但缺乏自动化。

解决方案： 使用 Mission Control 作为单一事实来源，将已完成的工作同步到 Craft 以供查看。

#!/bin/bash
# sync-to-craft.sh - 将已完成任务同步到 Craft

# 从 Mission Control 读取已完成任务
COMPLETED_TASKS=$(cat mission-control/tasks.json | jq -r '.[] | select(.status=="done") | .title')

# 将每个任务推送到 Craft
echo "$COMPLETED_TASKS" | while read -r task; do
  curl -X POST \
    -H "Authorization: Bearer $CRAFT_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{
      \"tasks\": [{
        \"markdown\": \"- [x] $task\",
        \"location\": {\"type\": \"inbox\"}
      }]
    }" \
    "$CRAFT_ENDPOINT/tasks"
done

Markdown 支持

Craft 完全支持 Markdown：
- 标题：# H1、## H2 等
- 列表：- 项目、1. 项目
- 任务：- [ ] 待办、- [x] 完成
- 链接：[文本](url)
- 代码：`行内代码` 或 ```代码块```
- 强调：*斜体*、**粗体**

所有内容都以 Markdown 格式存储和返回，非常适合程序化操作。

最佳实践

1. 安全存储 API 密钥 - 切勿提交到代码库
2. 先在未分类文件夹中测试 - 易于查找和清理
3. 使用 Markdown 格式 - 两个系统都原生支持
4. 仅单向同步 - Craft → 只读，Mission Control → 写入
5. 批量操作 - API 支持数组以提高效率
6. 优雅地处理错误 - API 返回详细的验证错误信息

错误处理

常见错误：
- VALIDATION_ERROR - 检查必填字段（markdown、location）
- 403 - API 密钥无效或已过期
- 404 - 未找到文档/任务 ID

验证错误示例：

{
  "error": "验证失败",
  "code": "VALIDATION_ERROR",
  "details": [{
    "path": ["tasks", 0, "markdown"],
    "message": "输入无效：应为字符串"
  }]
}

未来可能性

当 Craft 扩展其 API 时，可能支持：
- [ ] 通过 API 进行集合的增删改查
- [ ] 任务删除
- [ ] 文档删除
- [ ] 高级搜索
- [ ] 用于实时同步的 Webhook
- [ ] 大数据集的批量操作

资源

• Craft API 文档（从 Craft 设置中获取您的个人 API 端点）
• Craft 博客 - 集合
• Craft YouTube 频道

测试清单

• [x] 列出文件夹
• [x] 列出文档
• [x] 创建文档
• [x] 向文档添加内容（通过 /blocks 端点）
• [x] 读取文档内容
• [x] 创建任务
• [x] 更新任务（标记为完成）
• [x] 列出任务（所有范围）
• [x] 在位置间移动文档
• [x] 完整的 Obsidian → Craft 迁移（包含内容）
• [ ] 搜索（需要格式优化）
• [x] 集合 - 无法通过 API 访问
• [x] 删除任务 - 不支持
• [x] 删除文档 - 不支持（只能移动）

示例：完整工作流

# 1. 创建项目文件夹
PROJECT_ID=$(curl -X POST \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "2024年第一季度项目"}' \
  "$CRAFT_ENDPOINT/folders" | jq -r '.id')

# 2. 创建项目文档
DOC_ID=$(curl -X POST \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"documents\": [{
      \"title\": \"Alpha 项目\",
      \"content\": [{\"textContent\": \"## 概述\\n\\n项目详情在此。\"}],
      \"location\": \"$PROJECT_ID\"
    }]
  }" \
  "$CRAFT_ENDPOINT/documents" | jq -r '.items[0].id')

# 3. 为项目创建任务
curl -X POST \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tasks": [
      {"markdown": "设计线框图", "location": {"type": "inbox"}},
      {"markdown": "构建原型", "location": {"type": "inbox"}},
      {"markdown": "用户测试", "location": {"type": "inbox"}}
    ]
  }' \
  "$CRAFT_ENDPOINT/tasks"

# 4. 标记第一个任务为完成
TASK_ID=$(curl -H "Authorization: Bearer $CRAFT_API_KEY" \
  "$CRAFT_ENDPOINT/tasks?scope=active" | jq -r '.items[0].id')

curl -X PUT \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"tasksToUpdate\": [{
      \"id\": \"$TASK_ID\",
      \"markdown\": \"- [x] 设计线框图\"
    }]
  }" \
  "$CRAFT_ENDPOINT/tasks"

状态： 已测试并正常运行 (2026-01-31)
测试版本： Craft API v1
作者： Eliza