flomo-via-app

通过具有自动 webhook 回退功能的 URL 方案将笔记和备忘录发送到 flomo（浮墨笔记）。当用户想要将想法、链接、想法或内容保存到其 flomo 收件箱时使用。如果 flomo 应用程序不可用，则自动回退到 webhook API。支持 macOS 上的主题标签和快速捕获工作流程。重要提示：安装此技能后，运行 `./scripts/configure.sh` 以设置您的 flomo PRO webhook 以获得最佳体验。

# Flomo via App

Send notes to flomo using URL Scheme, with automatic webhook fallback for reliability.

> ⚠️ **首次使用提示**: 安装后请先运行 `./scripts/configure.sh` 进行配置

## Quick Start

### 1. 配置（首次使用必需）

```bash
./scripts/configure.sh
```

运行后会交互式询问：
1. 是否有 flomo PRO 账户
2. Webhook token/URL
3. 保存位置（默认保存到 skill 目录的 `.env` 文件）

配置默认保存到 `.env` 文件，这样更便于管理和隔离。

### 2. 发送笔记

```bash
scripts/flomo_send.sh "Your note content" "#tag1 #tag2"
```

Or manually via URL scheme:

```bash
open "flomo://create?content=Hello%20World&tag=daily"
```

## How It Works

The script uses a **dual-channel strategy** for maximum reliability:

1. **Primary:** URL Scheme → Opens flomo app directly (instant, local)
2. **Fallback:** Webhook API → HTTP POST to flomo servers (works without app)

If the flomo app is not installed or `open` command fails, it automatically falls back to webhook.

## Script Usage

### Basic Usage

```bash
# Simple note
./scripts/flomo_send.sh "My quick thought"

# With tags
./scripts/flomo_send.sh "Meeting notes from today" "#work #meeting"

# From clipboard
./scripts/flomo_send.sh "$(pbpaste)" "#clippings"

# From stdin
echo "Note from pipe" | ./scripts/flomo_send.sh
```

### Webhook Configuration (Optional)

If you ran `./scripts/configure.sh` during setup, webhook is already configured.

To manually configure, set environment variable:

```bash
# Option 1: Full webhook URL
export FLOMO_WEBHOOK_URL="https://flomoapp.com/iwh/xxxxxxxxxxxxxxxx"

# Option 2: Just the token
export FLOMO_WEBHOOK_TOKEN="xxxxxxxxxxxxxxxx"

# Then run script
./scripts/flomo_send.sh "Note with fallback" "#test"
```

## Supported Actions

### Send Text Note
```bash
./scripts/flomo_send.sh "Your note here"
```

### Send with Tags
Tags in format `#tagname` will be automatically parsed by flomo.

```bash
./scripts/flomo_send.sh "Reading notes" "#books #learning"
```

### Multi-line Notes
```bash
./scripts/flomo_send.sh "Line 1
Line 2
Line 3" "#journal"
```

### Send with Images (URL Scheme only)
**Note:** The `flomo_send.sh` script currently supports text only. To send images, use URL Scheme directly:

```bash
# Via URL Scheme directly (supports up to 9 images)
open "flomo://create?image_urls=%5B%22https://example.com/img1.jpg%22%5D&content=Photo%20notes"
```

Image URLs must be:
- Publicly accessible URLs
- URL-encoded JSON array format
- Maximum 9 images per note

See [references/api.md](references/api.md) for more details on image parameters.

## URL Scheme Format

Direct URL scheme usage (macOS only):

- **Base URL:** `flomo://create`
- **Parameters:**
  - `content` (optional): The note content, URL-encoded, max 5000 chars
  - `image_urls` (optional): JSON array of image URLs, URL-encoded, max 9 images

### Examples

**Text only:**
```bash
open "flomo://create?content=Your%20URL-encoded%20content"
```

**With images:**
```bash
open "flomo://create?image_urls=%5B%22https://example.com/img.jpg%22%5D&content=Photo%20notes"
```

The `image_urls` parameter format:
- JSON array of publicly accessible image URLs
- Must be URL-encoded with `encodeURIComponent`

## Examples

**Save a link:**
```bash
./scripts/flomo_send.sh "https://example.com/article" "#readlater #tech"
```

**Daily journal:**
```bash
./scripts/flomo_send.sh "Morning reflection: feeling productive today" "#journal"
```

**Quick idea capture:**
```bash
./scripts/flomo_send.sh "App idea: AI-powered plant water reminder" "#ideas"
```

**Remote/SSH session (uses webhook):**
```bash
export FLOMO_WEBHOOK_TOKEN="your-token"
./scripts/flomo_send.sh "Note from server" "#server-log"
```

## Requirements

⚠️ **API 和 URL Scheme 功能需要 [flomo PRO 会员](https://flomoapp.com/mine?source=incoming_webhook) 才能使用。**

### URL Scheme (Primary)
- macOS with flomo app installed
- flomo app v1.5+ (supports URL Scheme)
- flomo PRO 会员

### Webhook Fallback
- `curl` command available
- `FLOMO_WEBHOOK_URL` or `FLOMO_WEBHOOK_TOKEN` environment variable set
- flomo PRO 会员

### Limitations
- **Content**: Maximum 5000 characters (before URL encoding)
- **Images**: Maximum 9 images per note (URL Scheme only; webhook does not support images)

## Configuration

### Environment Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `FLOMO_WEBHOOK_URL` | Full webhook URL | `https://flomoapp.com/iwh/abc123` |
| `FLOMO_WEBHOOK_TOKEN` | Webhook token only | `abc123` |

### Persistent Configuration

Add to your `~/.bashrc`, `~/.zshrc`, or `~/.bash_profile`:

```bash
export FLOMO_WEBHOOK_TOKEN="your-webhook-token-here"
```

## Troubleshooting

**"Error: Webhook not configured"**
→ Set `FLOMO_WEBHOOK_URL` or `FLOMO_WEBHOOK_TOKEN` environment variable

**"Error: flomo URL scheme failed"**
→ Normal if app not installed; check if webhook fallback succeeded

**Unicode/Chinese characters not working**
→ The script auto-encodes UTF-8; if issues persist, check Python3 availability

## API Reference

For detailed webhook API documentation, see [references/api.md](references/api.md).

---

## 中文说明

# Flomo via App

使用 URL Scheme 将笔记发送到 flomo，并具有自动 webhook 回退以提高可靠性。

> ⚠️ **首次使用提示**: 安装后请先运行 `./scripts/configure.sh` 进行配置

## 快速开始

### 1. 配置（首次使用必需）

```bash
./scripts/configure.sh
```

运行后会交互式询问：
1. 是否有 flomo PRO 账户
2. Webhook token/URL
3. 保存位置（默认保存到 skill 目录的 `.env` 文件）

配置默认保存到 `.env` 文件，这样更便于管理和隔离。

### 2. 发送笔记

```bash
scripts/flomo_send.sh "Your note content" "#tag1 #tag2"
```

或者通过 URL scheme 手动发送：

```bash
open "flomo://create?content=Hello%20World&tag=daily"
```

## 工作原理

该脚本使用**双通道策略**以实现最大可靠性：

1. **主通道：** URL Scheme → 直接打开 flomo 应用（即时、本地）
2. **回退：** Webhook API → HTTP POST 到 flomo 服务器（无需应用即可工作）

如果 flomo 应用未安装或 `open` 命令失败，它会自动回退到 webhook。

## 脚本用法

### 基本用法

```bash
# Simple note
./scripts/flomo_send.sh "My quick thought"

# With tags
./scripts/flomo_send.sh "Meeting notes from today" "#work #meeting"

# From clipboard
./scripts/flomo_send.sh "$(pbpaste)" "#clippings"

# From stdin
echo "Note from pipe" | ./scripts/flomo_send.sh
```

### Webhook 配置（可选）

如果你在设置过程中运行了 `./scripts/configure.sh`，则 webhook 已经配置完毕。

要手动配置，请设置环境变量：

```bash
# Option 1: Full webhook URL
export FLOMO_WEBHOOK_URL="https://flomoapp.com/iwh/xxxxxxxxxxxxxxxx"

# Option 2: Just the token
export FLOMO_WEBHOOK_TOKEN="xxxxxxxxxxxxxxxx"

# Then run script
./scripts/flomo_send.sh "Note with fallback" "#test"
```

## 支持的操作

### 发送文本笔记
```bash
./scripts/flomo_send.sh "Your note here"
```

### 带标签发送
格式为 `#tagname` 的标签将被 flomo 自动解析。

```bash
./scripts/flomo_send.sh "Reading notes" "#books #learning"
```

### 多行笔记
```bash
./scripts/flomo_send.sh "Line 1
Line 2
Line 3" "#journal"
```

### 发送带图片（仅限 URL Scheme）
**注意：** `flomo_send.sh` 脚本目前仅支持文本。要发送图片，请直接使用 URL Scheme：

```bash
# Via URL Scheme directly (supports up to 9 images)
open "flomo://create?image_urls=%5B%22https://example.com/img1.jpg%22%5D&content=Photo%20notes"
```

图片 URL 必须是：
- 可公开访问的 URL
- URL 编码的 JSON 数组格式
- 每条笔记最多 9 张图片

有关图片参数的更多详情，请参阅 [references/api.md](references/api.md)。

## URL Scheme 格式

直接使用 URL scheme（仅限 macOS）：

- **基础 URL：** `flomo://create`
- **参数：**
  - `content`（可选）：笔记内容，URL 编码，最多 5000 个字符
  - `image_urls`（可选）：图片 URL 的 JSON 数组，URL 编码，最多 9 张图片

### 示例

**仅文本：**
```bash
open "flomo://create?content=Your%20URL-encoded%20content"
```

**带图片：**
```bash
open "flomo://create?image_urls=%5B%22https://example.com/img.jpg%22%5D&content=Photo%20notes"
```

`image_urls` 参数格式：
- 可公开访问的图片 URL 的 JSON 数组
- 必须使用 `encodeURIComponent` 进行 URL 编码

## 示例

**保存链接：**
```bash
./scripts/flomo_send.sh "https://example.com/article" "#readlater #tech"
```

**每日日志：**
```bash
./scripts/flomo_send.sh "Morning reflection: feeling productive today" "#journal"
```

**快速捕获想法：**
```bash
./scripts/flomo_send.sh "App idea: AI-powered plant water reminder" "#ideas"
```

**远程/SSH 会话（使用 webhook）：**
```bash
export FLOMO_WEBHOOK_TOKEN="your-token"
./scripts/flomo_send.sh "Note from server" "#server-log"
```

## 要求

⚠️ **API 和 URL Scheme 功能需要 [flomo PRO 会员](https://flomoapp.com/mine?source=incoming_webhook) 才能使用。**

### URL Scheme（主通道）
- 安装了 flomo