appflowy-api

# AppFlowy API

## 概述
本 skill 用于自托管 AppFlowy 环境的 API 调用与自动化，覆盖登录鉴权、文档/视图/数据库操作、搜索、协作数据（collab）等常见场景。默认**不读取 `.env`**，仅在显式传入 `--env <path>` 时读取。

本 skill 当前适配 AppFlowy Cloud `0.12.3`。`doctor.py` 会通过 `/api/health` 检测版本并在不匹配时给出警告。

## 快速开始
1. 准备 base URL 与 GoTrue URL（可选 `--env <path>` 读取 `.env`）。
2. 使用账号密码获取 `access_token`。
3. 携带必要请求头调用 AppFlowy API。

```bash
# 获取 token
curl -sS -X POST "http://10.60.0.189/gotrue/token?grant_type=password" \
  -H "Content-Type: application/json" \
  -d '{"email":"<email>","password":"<password>"}'
```

```bash
# 调用 API（示例：搜索）
curl -sS "http://10.60.0.189/api/search/<workspace_id>?query=test" \
  -H "Authorization: Bearer <access_token>" \
  -H "client-version: 0.12.3" \
  -H "client-timestamp: 1700000000000" \
  -H "device-id: <uuid>"
```

## 统一入口（推荐）
统一入口脚本用于封装命令风格，适合自动化与外部集成：

```bash
python skills/appflowy-api/scripts/appflowy_skill.py list
python skills/appflowy-api/scripts/appflowy_skill.py help apply-grid
```

## 配置优先级
解析优先级（从高到低）：
1. 命令行参数：`--base-url`、`--gotrue-url`、`--client-version`、`--device-id`
2. 配置文件：`--config <path>`（JSON，示例见 `skills/appflowy-api/references/config.example.json`）
3. 环境变量：`APPFLOWY_BASE_URL`、`API_EXTERNAL_URL`、`APPFLOWY_GOTRUE_BASE_URL`
4. `.env` 文件：仅在传入 `--env <path>` 时读取

## 常用脚本
```bash
# 获取 token
python skills/appflowy-api/scripts/get_token.py --email <email> --password <password>
```

```bash
# 自检（不会自动读取 .env）
python skills/appflowy-api/scripts/doctor.py --config skills/appflowy-api/references/config.example.json --email <email> --password <password>
```

```bash
# 生成“用户管理系统”文档（UTF-8 模板，表格顺序为正序）
python skills/appflowy-api/scripts/create_user_management_doc.py --config skills/appflowy-api/references/config.example.json --email <email> --password <...

# AppFlowy API Skill

用于自托管 AppFlowy 的 API 调用与自动化：登录获取 token、文档/视图/数据库操作、搜索、协作数据更新等。

## 入口方式
本技能提供两类入口：
1. **单脚本入口**：直接运行某个脚本，如 `python scripts/doctor.py ...`  
   - 优点：脚本即文档，参数最清晰  
   - 适合：脚本级调试、精细控制
2. **统一入口**：`python scripts/appflowy_skill.py <command> ...`  
   - 优点：命令风格统一、便于上层工具封装  
   - 适合：自动化流程、对外集成

查看统一入口可用命令：
```bash
python skills/appflowy-api/scripts/appflowy_skill.py list
```

查看某个命令帮助：
```bash
python skills/appflowy-api/scripts/appflowy_skill.py help apply-grid
```

## 结构
- `SKILL.md`：技能说明（供 Codex/Claude/OpenClaw 读取）
- `scripts/`：可复用脚本与通用库
- `references/`：API 参考与模板文件（UTF-8）
- `examples/`：示例命令与用法

## 快速示例
```bash
# 自检
python skills/appflowy-api/scripts/appflowy_skill.py doctor --config skills/appflowy-api/references/config.example.json --email <email> --password <password>

# 应用 Grid 模板（就地修改）
python skills/appflowy-api/scripts/appflowy_skill.py apply-grid --config skills/appflowy-api/references/config.example.json --email <email> --password <password> --workspace-id <workspace_id> --view-id <view_id> --template-file skills/appflowy-api/references/templates/fitness_plan.example.json
```