Skill: qiantao1001/flomo-send (version 1.0.0)

--- name: flomo-send description: "Send notes and memos to flomo (浮墨笔记) via URL Scheme with automatic webhook fallback. Use when user wants to save thoughts, links, ideas, or content to their flomo inbox. Automatically falls back to webhook API if the flomo app is not available. Supports hashtags and quick capture workflows on macOS. IMPORTANT: After installing this skill, run `./scripts/configure.sh` to set up your flomo PRO webhook for the best experience." --- # 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).

path: README.md
content: # Flomo Send

通过 Webhook API 发送笔记到 flomo（浮墨笔记）的 OpenClaw Skill。

> ⚠️ 注意：本版本已取消 URL Scheme 模式（mac 应用当前不支持该功能）。
> 统一改为使用 Webhook API（需要 flomo PRO）。

## 功能特性

-- ✅ **Webhook 为主（已取消 URL Scheme）**：统一使用 Webhook API 进行发送，URL Scheme 模式已移除
- ✅ **交互式配置**：安装时自动引导配置 Pro 账户
- ✅ **标签支持**：自动解析 `#标签` 格式
- ✅ **长度检查**：自动验证 5000 字限制
- ✅ **特殊字符处理**：正确处理中文、引号等特殊字符

## 安装

```bash
# 进入 skill 目录
cd skills/flomo-via-app

# 运行交互式配置
./scripts/configure.sh
```

配置脚本会询问：
1. 是否有 flomo PRO 账户
2. Webhook token（支持完整 URL 或仅 token）
3. 配置保存位置（shell 配置文件 或 本地 .env）

## 使用方法

### 基础用法

```bash
# 发送简单笔记
./scripts/flomo_send.sh "我的快速想法"

# 带标签
./scripts/flomo_send.sh "读书笔记" "#读书 #认知"

# 从剪贴板
./scripts/flomo_send.sh "$(pbpaste)" "#待读"

# 管道输入
echo "来自管道的笔记" | ./scripts/flomo_send.sh
```

### URL Scheme

URL Scheme 直接调用已在本版本移除，因为 macOS 上的 flomo 应用当前不支持所需的行为。请改用 Webhook API（参见下方“配置”一节），或通过 `./scripts/configure.sh` 保存你的 Webhook 设置到本地 `.env` 后使用 `./scripts/flomo_send.sh`。

## 要求

- **flomo PRO 会员**（Webhook API 需要）
- **curl** 命令可用（脚本使用 `curl` 发送 HTTP 请求）
- **Python 3**（脚本使用 Python 构建 JSON payload，或可调整为纯 shell 实现）

## 配置

### 环境变量

| 变量 | 说明 |
|------|------|
| `FLOMO_WEBHOOK_TOKEN` | Webhook token |
| `FLOMO_WEBHOOK_URL` | 完整的 Webhook URL |

### 手动配置

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

添加到 `~/.zshrc` 或 `~/.bash_profile` 使其持久化。

## 限制

- 内容最多 **5000 字**
- 图片最多 **9 张**（仅 URL Scheme）
- Webhook 不支持图片

## 获取 Webhook Token

1. 访问 [flomo 设置页面](https://flomoapp.com/mine?source=incoming_webhook)
2. 复制你的专属 Webhook URL

## 项目结构

```
flomo-via-app/
├── SKILL.md              # Skill 定义（AI 使用）
├── README.md             # 本文件
├── scripts/
│   ├── configure.sh      # 交互式配置脚本
│   └── flomo_send.sh     # 发送笔记脚本
└── references/
    └── api.md            # API 详细文档
```

## License

MIT


path: _meta.json
content: ownerId: kn7dhfkk1kqa6nh0rx8ykm3qen80r821
slug: flomo-send
version: 1.0.0

path: references/api.md
content: # Flomo API Reference

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

flomo 提供了 API 和 URL Scheme 两种方式与其他软件交互。

---

## URL Scheme（推荐）

通过 URL Scheme 直接打开 flomo 应用并填入内容，支持文本和图片。

### 基础格式
```
flomo://create?content=<encoded-content>
```

### 路径
```
flomo://create
```

### 参数

| 参数名 | 含义 | 必传 | 最大长度 | 编码方式 |
|--------|------|------|----------|----------|
| `content` | 文本内容 | 否 | 5000 字（encode 前） | `encodeURIComponent` |
| `image_urls` | 图片 URL 数组 | 否 | 最多 9 个 URL | `encodeURIComponent(JSONString(Array))` |

### 示例

**纯文本笔记：**
```
flomo://create?content=%E7%AC%94%E8%AE%B0%E5%86%85%E5%AE%B9
```

**带图片的笔记：**
```
flomo://create?image_urls=%5B%22https%3A%2F%2Fexample.com%2Fimage1.png%22%2C%22https%3A%2F%2Fexample.com%2Fimage2.png%22%5D&content=%E7%AC%94%E8%AE%B0%E5%86%85%E5%AE%B9
```

**手机端测试链接：**
[在安装了 flomo app 的手机上点击试试](flomo://create?image_urls=%5B%22https%3A%2F%2Fflomo-resource.oss-cn-shanghai.aliyuncs.com%2Fhome%2Flogo.png!web%22%2C%22https%3A%2F%2Fflomo-resource.oss-cn-shanghai.aliyuncs.com%2Fhome%2F202103%2Fpic_feature_graph.png!web%22%5D&content=%E7%AC%94%E8%AE%B0%E5%86%85%E5%AE%B9)

### macOS 使用示例

```bash
# 发送纯文本
open "flomo://create?content=Hello%20World"

# 发送带标签的文本（标签直接写在内容中）
open "flomo://create?content=%E8%AF%BB%E4%B9%A6%E7%AC%94%E8%AE%B0%20%23%E8%AF%BB%E4%B9%A6"

# 发送多行文本（使用 %0A 作为换行符）
open "flomo://create?content=Line1%0ALine2%0ALine3"
```

### 限制

- **content**: 最多 5000 字（encode 前）
- **image_urls**: 最多 9 张图片
- 需要 flomo iOS/Android/macOS 应用支持

---

## Webhook API

通过 HTTP POST 请求发送笔记到 flomo，无需打开应用。

### 获取 Webhook 地址

1. 访问 [flomo 设置页面](https://flomoapp.com/mine?source=incoming_webhook)
2. 复制你的专属 Webhook URL

格式：
```
https://flomoapp.com/iwh/{your-webhook-token}
```

### 请求格式

```bash
curl -X POST https://flomoapp.com/iwh/xxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{"content": "笔记内容 #标签"}'
```

### 参数

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `content` | string | 是 | 笔记内容，支持 Markdown 格式和 `#标签` |

### 完整示例

```bash
# 基础用法
curl -X POST https://flomoapp.com/iwh/xxxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello from API"}'

# 带标签
curl -X POST https://flomoapp.com/iwh/xxxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{"content": "读书笔记 #认知 #学习"}'

# 多行内容
curl -X POST https://flomoapp.com/iwh/xxxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{"content": "第一行\n第二行\n第三行"}'
```

### 响应

**成功：**
```json
{
  "code": 0,
  "message": "ok"
}
```

**失败：**
```json
{
  "code": -1,
  "message": "错误信息"
}
```

### 限制

- 需要 PRO 会员
- 有调用频率限制（具体限制参见官方文档）

---

## URL Scheme vs Webhook 对比

| 特性 | URL Scheme | Webhook API |
|------|------------|-------------|
| 需要打开应用 | ✅ 是 | ❌ 否 |
| 支持图片 | ✅ 是 | ❌ 否（仅文本） |
| 服务器/自动化场景 | ❌ 不适用 | ✅ 适用 |
| 响应速度 | 即时 | 依赖网络 |
| 跨平台 | 需安装 app | 任何支持 HTTP 的环境 |

---

## 更多资源

- [flomo 扩展中心](https://flomoapp.com/mine?source=incoming_webhook) — 使用别人提供的扩展工具
- [第三方工具提交](https://github.com/flomoapp/3rd-party-tools) — 提交你的作品
- [PRO 会员购买](https://flomoapp.com/mine?source=incoming_webhook)

---

*文档更新时间：2025-02-08*
*来源：[flomo 官方帮助文档](https://help.flomoapp.com/advance/api.html)*


path: scripts/configure.sh
content: #!/bin/bash
#
# configure.sh - Interactive setup for flomo-send skill
#
# This script runs during skill installation to configure user preferences.
#

set -e

echo "📝 Flomo Skill Configuration"
echo "============================"
echo ""

# Check if running in interactive mode
if [ ! -t 0 ]; then
    echo "Note: Non-interactive mode detected. Skipping configuration."
    echo "To configure later, run: ./scripts/configure.sh"
    exit 0
fi

# Ask if user has flomo PRO account
echo "Do you have a flomo PRO account? (y/n)"
read -r HAS_PRO

case "$HAS_PRO" in
    [Yy]*)
        echo ""
        echo "✅ PRO account selected"
        echo ""
        echo "Please enter your flomo webhook token."
        echo "You can find it at: https://flomoapp.com/mine?source=incoming_webhook"
        echo ""
        read -rp "Webhook token (or full URL): " WEBHOOK_INPUT
        
        if [ -z "$WEBHOOK_INPUT" ]; then
            echo "⚠️  No webhook provided. You can configure it later by running this script again."
            exit 0
        fi
        
        # Detect if user pasted full URL or just token
        if echo "$WEBHOOK_INPUT" | grep -q "^https://flomoapp.com/iwh/"; then
            # Full URL provided
            WEBHOOK_URL="$WEBHOOK_INPUT"
            WEBHOOK_TOKEN=$(echo "$WEBHOOK_URL" | sed 's|https://flomoapp.com/iwh/||')
            echo ""
            echo "✅ Webhook URL configured"
        else
            # Just token provided
            WEBHOOK_TOKEN="$WEBHOOK_INPUT"
            WEBHOOK_URL="https://flomoapp.com/iwh/$WEBHOOK_TOKEN"
            echo ""
            echo "✅ Webhook token configured"
        fi
        
        # Determine shell config file for display
        SHELL_CONFIG=""
        if [ -n "$ZSH_VERSION" ] || [ -f "$HOME/.zshrc" ]; then
            SHELL_CONFIG="$HOME/.zshrc"
        elif [ -n "$BASH_VERSION" ]; then
            if [ -f "$HOME/.bash_profile" ]; then
                SHELL_CONFIG="$HOME/.bash_profile"
            else
                SHELL_CONFIG="$HOME/.bashrc"
            fi
        fi
        
        echo ""
        echo "Where would you like to save the configuration?"
        echo "1) Create a local .env file in skill directory (default - recommended)"
        echo "2) Shell config file ($SHELL_CONFIG)"
        read -rp "Choice [1-2] (default: 1): " CONFIG_CHOICE
        
        # Default to option 1 if empty
        CONFIG_CHOICE=${CONFIG_CHOICE:-1}
        
        case "$CONFIG_CHOICE" in
            2)
                # Save to shell config
                if [ -n "$SHELL_CONFIG" ]; then
                    echo "" >> "$SHELL_CONFIG"
                    echo "# Flomo Skill Configuration" >> "$SHELL_CONFIG"
                    echo "export FLOMO_WEBHOOK_TOKEN=$WEBHOOK_TOKEN" >> "$SHELL_CONFIG"
                    echo ""
                    echo "✅ Configuration saved to: $SHELL_CONFIG"
                    echo "   Please run: source $SHELL_CONFIG"
                else
                    echo "⚠️  Could not detect shell config file."
                    echo "   Please manually add to your shell config:"
                    echo "   export FLOMO_WEBHOOK_TOKEN=$WEBHOOK_TOKEN"
                fi
                ;;
            *)
                # Save to .env file (default)
                ENV_FILE="$(dirname "$0")/../.env"
                echo "# Flomo Skill Configuration" > "$ENV_FILE"
                echo "FLOMO_WEBHOOK_TOKEN=$WEBHOOK_TOKEN" >> "$ENV_FILE"
                echo "# FLOMO_WEBHOOK_URL=$WEBHOOK_URL" >> "$ENV_FILE"
                chmod 600 "$ENV_FILE"
                echo ""
                echo "✅ Configuration saved to: $ENV_FILE"
                echo "   The .env file has been created with restricted permissions (600)"
                echo "   This is the recommended option - keeps config isolated to this skill."
                ;;
        esac
        
        echo ""
        echo "🎉 Configuration complete!"
        echo "   You can now use the flomo_send.sh script with webhook fallback."
        ;;
    
    [Nn]*)
        echo ""
        echo "✅ Free account selected"
        echo "   The skill will use URL Scheme only (requires flomo app on macOS)."
        echo "   If you upgrade to PRO later, run: ./scripts/configure.sh"
        ;;
    
    *)
        echo ""
        echo "⚠️  Invalid input. Skipping configuration."
        echo "   You can run this script later to configure: ./scripts/configure.sh"
        exit 0
        ;;
esac

echo ""
echo "📖 Quick start:"
echo "   ./scripts/flomo_send.sh \"Your note\" \"#tag1 #tag2\""


path: scripts/flomo_send.sh
content: #!/bin/bash
#
# flomo_send.sh - Send notes to flomo app via URL Scheme with webhook fallback
#
# Usage:
#   ./flomo_send.sh "Note content" "#tag1 #tag2"
#   ./scripts/flomo_send.sh "$(pbpaste)" "#clippings"
#   echo "Note content" | ./scripts/flomo_send.sh
#

set -e

# Load local .env if present (export variables so they're available to curl/python)
ENV_FILE="$(dirname "$0")/../.env"
if [ -f "$ENV_FILE" ]; then
    set -o allexport
    # shellcheck disable=SC1090
    source "$ENV_FILE"
    set +o allexport
fi

# Get content from arguments or stdin.
# If the last positional argument starts with '#', treat it as TAGS and
# join the remaining arguments as CONTENT. Otherwise join all positional
# args as CONTENT. If no positional args are given, read from stdin.
TAGS=""
if [ $# -ge 1 ]; then
    LAST_ARG="${@: -1}"
    if [[ "$LAST_ARG" == \#* ]]; then
        TAGS="$LAST_ARG"
        if [ $# -ge 2 ]; then
            CONTENT="${@:1:$(($#-1))}"
        else
            # single arg which is a tag -> read content from stdin
            CONTENT=$(cat)
        fi
    else
        CONTENT="$*"
    fi
else
    CONTENT=$(cat)
fi

# Combine content and tags
if [ -n "$TAGS" ]; then
    FULL_CONTENT="${CONTENT} ${TAGS}"
else
    FULL_CONTENT="${CONTENT}"
fi

# Trim whitespace (remove leading/trailing spaces and newlines)
FULL_CONTENT=$(echo "$FULL_CONTENT" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')

# Check if content is empty
if [ -z "$FULL_CONTENT" ]; then
    echo "Error: Note content is empty" >&2
    echo "Usage: $0 \"Note content\" \"#tag1 #tag2\"" >&2
    exit 1
fi

# Check content length (flomo limit: 5000 characters before encoding)
if [ "${#FULL_CONTENT}" -gt 5000 ]; then
    echo "Error: Content exceeds 5000 character limit (current: ${#FULL_CONTENT})" >&2
    exit 1
fi

# Function: send via webhook. Returns 0 on success, non-zero on failure.
send_webhook() {
    if [ -n "$FLOMO_WEBHOOK_URL" ]; then
        WEBHOOK_URL="$FLOMO_WEBHOOK_URL"
    elif [ -n "$FLOMO_WEBHOOK_TOKEN" ]; then
        WEBHOOK_URL="https://flomoapp.com/iwh/$FLOMO_WEBHOOK_TOKEN"
    else
        return 2
    fi

    # Build JSON payload safely (handles quotes/newlines in content).
    if command -v python3 >/dev/null 2>&1; then
        PAYLOAD=$(printf '%s' "$FULL_CONTENT" | python3 -c 'import sys,json;print(json.dumps({"content": sys.stdin.read()}))')
    else
        # Fallback: escape simple cases (less safe for arbitrary input)
        ESCAPED=$(printf '%s' "$FULL_CONTENT" | sed -e 's/\\/\\\\/g' -e 's/"/\\\"/g' -e ':a;N;$!ba;s/\n/\\n/g')
        PAYLOAD="{\"content\": \"$ESCAPED\"}"
    fi

    RESP=$(curl -sS -w "\n%{http_code}" -X POST "$WEBHOOK_URL" -H "Content-Type: application/json" -d "$PAYLOAD" || true)
    HTTP_STATUS=$(echo "$RESP" | tail -n1)
    BODY=$(echo "$RESP" | sed '$d')

    if echo "$HTTP_STATUS" | grep -q "^2"; then
        echo "✓ Sent to flomo webhook: ${FULL_CONTENT:0:50}..."
        return 0
    else
        echo "Warning: Webhook request failed (HTTP $HTTP_STATUS): $BODY" >&2
        return 1
    fi
}

# Main: webhook-only delivery
if [ -n "$FLOMO_WEBHOOK_URL" ] || [ -n "$FLOMO_WEBHOOK_TOKEN" ]; then
    if send_webhook; then
        exit 0
    else
        echo "Error: webhook delivery failed. Check FLOMO_WEBHOOK_URL/FLOMO_WEBHOOK_TOKEN and network." >&2
        exit 1
    fi
else
    echo "Error: Webhook not configured. Set FLOMO_WEBHOOK_URL or FLOMO_WEBHOOK_TOKEN or run ./scripts/configure.sh" >&2
    exit 1
fi


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)