atomtanstudio-craft-do

Craft.do 完整 REST API 集成技能：支持任务自动化、文档与文件夹管理、Obsidian 迁移，以及通过 blocks API 操作 Markdown 内容。

## 概述（中文）

Craft.do 完整 REST API 集成技能：支持任务自动化、文档与文件夹管理、Obsidian 迁移，以及通过 blocks API 操作 Markdown 内容。

## 技能正文

# Craft.do 集成技能

Craft.do — 精美笔记与文档应用 — 的完整 REST API 集成。

## 概述

本技能为 Craft.do 提供完整的程序化访问能力：
- **任务自动化：** 在收件箱/每日笔记/日志中创建、更新与管理任务
- **文档工作流：** 以编程方式创建、读取与组织文档
- **文件夹管理：** 通过 API 构建嵌套文件夹层级
- **Obsidian 迁移：** 一次性完整 vault 迁移并保留内容
- **内容操作：** 通过 blocks API 添加/编辑 Markdown 内容

Craft.do 特性：
- 原生 Markdown 支持
- 任务管理（收件箱、每日笔记、日志）
- 集合（数据库表）
- 层级文件夹与文档
- 完整 REST API 访问

## 设置

1. 从 Craft.do 设置中获取 API key
2. 安全存储凭据：

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

## API 能力

### ✅ 可用功能

#### 列出文件夹
```bash
curl -H "Authorization: Bearer $CRAFT_API_KEY" \
  "$CRAFT_ENDPOINT/folders"
```

返回所有位置：unsorted、daily_notes、trash、templates 及自定义文件夹。

#### 列出文档
```bash
curl -H "Authorization: Bearer $CRAFT_API_KEY" \
  "$CRAFT_ENDPOINT/documents?folderId=FOLDER_ID"
```

#### 创建文件夹（可选 parent 以实现嵌套）
```bash
# Root-level folder
curl -X POST \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "folders": [{
      "name": "Projects"
    }]
  }' \
  "$CRAFT_ENDPOINT/folders"

# Nested folder (requires parent folder ID)
curl -X POST \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "folders": [{
      "name": "Q1 2024",
      "parentFolderId": "PARENT_FOLDER_ID"
    }]
  }' \
  "$CRAFT_ENDPOINT/folders"
```

#### 创建文档
```bash
curl -X POST \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [{
      "title": "Document Title"
    }],
    "destination": {
      "folderId": "FOLDER_ID"
    }
  }' \
  "$CRAFT_ENDPOINT/documents"
```

**说明：** 文档创建时初始不含内容。使用 `/blocks` 端点添加内容。

#### 向文档添加内容
```bash
curl -X POST \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "blocks": [{
      "type": "text",
      "markdown": "# Document content\n\nFull markdown support!"
    }],
    "position": {
      "pageId": "DOCUMENT_ID",
      "position": "end"
    }
  }' \
  "$CRAFT_ENDPOINT/blocks"
```

#### 读取文档内容
```bash
curl -H "Authorization: Bearer $CRAFT_API_KEY" \
  "$CRAFT_ENDPOINT/blocks?id=DOCUMENT_ID"
```

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

#### 创建任务
```bash
curl -X POST \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tasks": [{
      "markdown": "Task description",
      "location": {"type": "inbox"},
      "status": "active"
    }]
  }' \
  "$CRAFT_ENDPOINT/tasks"
```

#### 更新任务（标记完成）
```bash
curl -X PUT \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tasksToUpdate": [{
      "id": "TASK_ID",
      "markdown": "- [x] Completed task"
    }]
  }' \
  "$CRAFT_ENDPOINT/tasks"
```

#### 列出任务
```bash
# Active tasks
curl -H "Authorization: Bearer $CRAFT_API_KEY" \
  "$CRAFT_ENDPOINT/tasks?scope=active"

# All completed (logbook)
curl -H "Authorization: Bearer $CRAFT_API_KEY" \
  "$CRAFT_ENDPOINT/tasks?scope=logbook"

# Upcoming
curl -H "Authorization: Bearer $CRAFT_API_KEY" \
  "$CRAFT_ENDPOINT/tasks?scope=upcoming"

# Inbox only
curl -H "Authorization: Bearer $CRAFT_API_KEY" \
  "$CRAFT_ENDPOINT/tasks?scope=inbox"
```

#### 移动文档
```bash
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`。

### ❌ 限制

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

## 常见用例

### 从外部系统同步任务
```bash
# Create task in Craft from Mission Control
TASK_TITLE="Deploy new feature"
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"
```

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

### 归档已完成工作
```bash
# Get all completed tasks
curl -H "Authorization: Bearer $CRAFT_API_KEY" \
  "$CRAFT_ENDPOINT/tasks?scope=logbook" | jq '.items[] | {id, markdown, completedAt}'
```

## 集成模式

### Mission Control → Craft 同步

**问题：** Mission Control 有自动化但 UI 较丑。Craft UI 精美但缺少自动化。

**解决方案：** 以 Mission Control 为单一数据源，将已完成工作同步到 Craft 供查看。

```bash
#!/bin/bash
# sync-to-craft.sh - Sync completed tasks to Craft

# Read completed tasks from Mission Control
COMPLETED_TASKS=$(cat mission-control/tasks.json | jq -r '.[] | select(.status=="done") | .title')

# Push each to 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` 等
- 列表：`- item`、`1. item`
- 任务：`- [ ] todo`、`- [x] done`
- 链接：`[text](url)`
- 代码：`` `inline` `` 或 ` ```block``` `
- 强调：`*italic*`、`**bold**`

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

## 最佳实践

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

## 错误处理

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

验证错误示例：
```json
{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "details": [{
    "path": ["tasks", 0, "markdown"],
    "message": "Invalid input: expected string"
  }]
}
```

## 未来可能

当 Craft 扩展 API 时：
- [ ] 通过 API 进行 Collections CRUD
- [ ] 任务删除
- [ ] 文档删除
- [ ] 高级搜索
- [ ] 用于实时同步的 Webhooks
- [ ] 大数据集的批量操作

## 资源

- [Craft API Docs](https://craft.do/api)（从 Craft 设置获取你的个人 API 端点）
- [Craft Blog - Collections](https://www.craft.do/blog/introducing-collections)
- [Craft YouTube](https://www.youtube.com/channel/UC8OIJ9uNRQZiG78K2BSn67A)

## 测试清单

- [x] 列出文件夹
- [x] 列出文档
- [x] 创建文档
- [x] 向文档添加内容（通过 /blocks 端点）
- [x] 读取文档内容
- [x] 创建任务
- [x] 更新任务（标记完成）
- [x] 列出任务（所有 scope）
- [x] 在位置间移动文档
- [x] 完整 Obsidian → Craft 迁移（含内容）
- [ ] 搜索（需完善格式）
- [x] Collections — API 不可访问
- [x] 删除任务 — 不支持
- [x] 删除文档 — 不支持（只能移动）

## 示例：完整工作流

```bash
# 1. Create a project folder
PROJECT_ID=$(curl -X POST \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Q1 2024 Projects"}' \
  "$CRAFT_ENDPOINT/folders" | jq -r '.id')

# 2. Create a project document
DOC_ID=$(curl -X POST \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"documents\": [{
      \"title\": \"Project Alpha\",
      \"content\": [{\"textContent\": \"## Overview\\n\\nProject details here.\"}],
      \"location\": \"$PROJECT_ID\"
    }]
  }" \
  "$CRAFT_ENDPOINT/documents" | jq -r '.items[0].id')

# 3. Create tasks for the project
curl -X POST \
  -H "Authorization: Bearer $CRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tasks": [
      {"markdown": "Design wireframes", "location": {"type": "inbox"}},
      {"markdown": "Build prototype", "location": {"type": "inbox"}},
      {"markdown": "User testing", "location": {"type": "inbox"}}
    ]
  }' \
  "$CRAFT_ENDPOINT/tasks"

# 4. Mark first task complete
TASK_ID=$(curl -H "Authorization: Bearer $CRAFT_API_KEY"