Clinkding - Linkding Bookmark Integration

# clinkding - Linkding Bookmark Manager CLI

一个基于 Go 的现代 CLI，用于管理 [linkding](https://github.com/sissbruecker/linkding)（一个自托管的书签管理器）中的书签。

## 功能介绍

**Linkding** 是一个自托管的书签管理器（类似 Pocket、Instapaper）。**clinkding** 是一个 CLI 工具，允许你在终端中或通过 AI 智能体管理你的书签。

可以将其视为： - **稍后阅读** - 捕获你想要阅读的 URL - **可搜索的库** - 对标题、描述、标签进行全文搜索 - **有序的集合** - 对相关书签进行标记和打包 - **个人存档** - 保存包含笔记和元数据的重要链接

## 快速开始

### 初始设置

```bash # Interactive configuration clinkding config init

# Or manually configure clinkding config set url https://your-linkding-instance.com clinkding config set token YOUR_API_TOKEN

# Test connection clinkding config test ```

### 配置文件

位置：`~/.config/clinkding/config.yaml`

```yaml url: https://linkding.example.com token: your-api-token-here

defaults: bookmark_limit: 100 output_format: auto ```

### 环境变量

```bash export LINKDING_URL="https://linkding.example.com" export LINKDING_TOKEN="your-api-token-here" ```

## 核心命令

### 书签

#### 列表与搜索

```bash # List recent bookmarks clinkding bookmarks list

# Search by keyword clinkding bookmarks list --query "golang tutorial"

# Filter by tag clinkding bookmarks list --query "tag:programming"

# Recent bookmarks (last 7 days) clinkding bookmarks list --added-since "7d"

# Unread bookmarks clinkding bookmarks list --query "unread:yes"

# JSON output for scripting clinkding bookmarks list --json

# Plain text (tab-separated) clinkding bookmarks list --plain ```

#### 创建书签

```bash # Simple bookmark clinkding bookmarks create https://go.dev

# With metadata clinkding bookmarks create https://go.dev \ --title "Go Programming Language" \ --tags "golang,programming,reference" \ --description "Official Go website" \ --unread

# Check if URL already exists before creating clinkding bookmarks check https://go.dev ```

#### 更新书签

```bash # Update title clinkding bookmarks update 42 --title "New Title"

# Add tags clinkding bookmarks update 42 --add-tags "important,work"

# Remove tags clinkding bookmarks update 42 --remove-tags "old-tag"

# Mark as read clinkding bookmarks update 42 --read

# Update description clinkding bookmarks update 42 --description "Updated notes" ```

#### 获取书签详情

```bash # Full details clinkding bookmarks get 42

# JSON output clinkding bookmarks get 42 --json ```

#### 归档与删除

```bash # Archive (hide from main list) clinkding bookmarks archive 42

# Unarchive clinkding bookmarks unarchive 42

# Delete permanently clinkding bookmarks delete 42 ```

### 标签

```bash # List all tags clinkding tags list

# Create a tag clinkding tags create "golang"

# Get tag details clinkding tags get 1

# Plain text output clinkding tags list --plain ```

### 书签包

书签包是相关书签的集合。

```bash # List bundles clinkding bundles list

# Create a bundle clinkding bundles create "Go Resources" \ --description "Everything related to Go programming"

# Update a bundle clinkding bundles update 1 --name "Go Lang Resources"

# Get bundle details clinkding bundles get 1

# Delete a bundle clinkding bundles delete 1 ```

### 资源

上传和管理书签的文件附件。

```bash # List assets for a bookmark clinkding assets list 42

# Upload a file clinkding assets upload 42 ~/Documents/screenshot.png

# Download an asset clinkding assets download 42 1 -o ./downloaded-file.png

# Delete an asset clinkding assets delete 42 1 ```

### 用户配置文件

```bash # Get user profile info clinkding user profile ```

## 智能体使用模式

### 从对话中保存 URL

```bash # User: "Save this for later: https://example.com" clinkding bookmarks create https://example.com \ --title "Article Title" \ --description "Context from conversation" \ --tags "topic,context" ```

### 搜索书签

```bash # User: "Find my golang bookmarks" clinkding bookmarks list --query "golang"

# User: "Show me unread programming articles" clinkding bookmarks list --query "tag:programming unread:yes"

# User: "What did I save last week?" clinkding bookmarks list --added-since "7d" ```

### 整理与标记

```bash # User: "Tag bookmark 42 as important" clinkding bookmarks update 42 --add-tags "important"

# User: "Create a bundle for my AI research links" clinkding bundles create "AI Research" \ --description "Machine learning and AI papers" ```

### 检索以供阅读

```bash # User: "Give me something to read" clinkding bookmarks list --query "unread:yes" --limit 5

# User: "Show me my golang tutorials" clinkding bookmarks list --query "tag:golang tag:tutorial" ```

## 输出格式

### 自动（默认）

适合终端显示的人性化表格和颜色。

### JSON

```bash clinkding bookmarks list --json ```

适合脚本编写和智能体解析的机器可读格式。

### 纯文本

```bash clinkding bookmarks list --plain ```

适合管道解析的制表符分隔值。

## 相对日期过滤

支持人性化时间范围：

```bash # Last 24 hours clinkding bookmarks list --added-since "24h"

# Last 7 days clinkding bookmarks list --added-since "7d"

# Last 6 months clinkding bookmarks list --modified-since "180d" ```

**支持的单位：** `h`（小时）、`d`（天）、`y`（年）

## 常见工作流

### 晨间阅读惯例

```bash # Check unread bookmarks clinkding bookmarks list --query "unread:yes"

# Get top 5 most recent clinkding bookmarks list --limit 5 ```

### 从剪贴板保存

```bash # macOS pbpaste | xargs -I {} clinkding bookmarks create {}

# Linux xclip -o | xargs -I {} clinkding bookmarks create {} ```

### 批量操作

```bash # Tag multiple bookmarks for id in 42 43 44; do clinkding bookmarks update $id --add-tags "important" done

# Archive old unread bookmarks clinkding bookmarks list --query "unread:yes" --added-since "30d" --plain | \ while read id _; do clinkding bookmarks archive "$id" done ```

### 备份书签

```bash # Export all bookmarks as JSON clinkding bookmarks list --json > bookmarks-backup-$(date +%Y%m%d).json

# Export specific tag clinkding bookmarks list --query "tag:important" --json > important.json ```

## 全局标志

适用于所有命令：

| 标志 | 描述 | |------|-------------| | `-c, --config <file>` | 配置文件路径 | | `-u, --url <url>` | Linkding 实例 URL | | `-t, --token <token>` | API 令牌 | | `--json` | 输出为 JSON | | `--plain` | 输出为纯文本 | | `--no-color` | 禁用颜色 | | `-q, --quiet` | 最小化输出 | | `-v, --verbose` | 详细输出 |

## 退出代码

| 代码 | 含义 | |------|---------| | 0 | 成功 | | 1 | 一般错误（API/网络） | | 2 | 无效用法（错误的标志/参数） | | 3 | 身份验证错误 | | 4 | 未找到 | | 130 | 中断（Ctrl-C） |

## 故障排除

### 测试配置

```bash # Verify settings clinkding config show

# Test connection clinkding config test ```

### 常见问题

**身份验证错误：** - 在 linkding Web 界面中验证 API 令牌 - 检查 URL 是否包含协议（`https://`） - 删除 URL 末尾的斜杠

**特定命令帮助：** ```bash clinkding bookmarks --help clinkding bookmarks create --help ```

## 链接

- **GitHub：** https://github.com/daveonkels/clinkding - **Linkding：** https://github.com/sissbruecker/linkding - **Homebrew：** `brew install daveonkels/tap/clinkding`

## 安装

### Homebrew (macOS/Linux)

```bash brew install daveonkels/tap/clinkding ```

### Go 安装

```bash go install github.com/daveonkels/clinkding@latest ```

### 二进制下载

从 [releases](https://github.com/daveonkels/clinkding/releases) 下载适合你平台的版本。

## Shell 自动补全

```bash # Bash clinkding completion bash > /etc/bash_completion.d/clinkding

# Zsh clinkding completion zsh > "${fpath[1]}/_clinkding"

# Fish clinkding completion fish > ~/.config/fish/completions/clinkding.fish ```

---

**构建者：** [@daveonkels](https://github.com/daveonkels) **许可证：** MIT

## 智能书签创建的智能体工作流

### 添加带有自动元数据的 URL

当用户说“添加这个到 linkding”或“保存此 URL”时，请遵循此工作流：

**1. 从 URL 中提取元数据**

使用 `summarize` 技能获取标题和描述：

```bash # Get page metadata summarize url https://example.com --format json ```

这将返回结构化数据，包含： - 标题 - 描述/摘要 - 主要内容

**2. 根据内容推断适当的标签**

仅将内容映射到**现有的规范标签**。不要创建新标签。

使用此规范标签列表（共 263 个标签）： - **技术：** webdev, design, programming, ai, cloud, devops, docker, linux, networking, security, privacy - **内容：** content, media, photography, video, audio, books, podcasting - **商业：** business, marketing, ecommerce, finance, career, productivity - **家庭：** smart-home, home-assistant, esphome, iot, home-improvement - **工具：** tools, cli, git, github, editor, reference, documentation - **数据：** data, analytics, mysql, nosql - **通信：** communication, email, messaging, slack - **教育：** education, guide, howto, research, testing - **地点：** texas, seattle, dallas（谨慎使用）

**标签选择规则：** - 最多使用 2-5 个标签 - 选择最适用的具体标签 - 如果不确定，默认使用更广泛的类别（例如，用 `tools` 而不是 `generator`） - 首先检查现有标签：`clinkding tags list --plain | grep -i <keyword>` - 永远不要创建如下标签：`awesome`, `cool`, `interesting`, `resources`, `tips`

**3. 使用元数据创建书签**

```bash clinkding bookmarks create "https://example.com" \ --title "Title from summarize" \ --description "Summary from summarize (1-2 sentences)" \ --tags "webdev,tools,reference" ```

### 工作流示例

**用户：** “保存这个到 linkding：https://github.com/awesome/project”

**智能体操作：**

```bash # 1. Check if already bookmarked clinkding bookmarks check https://github.com/awesome/project

# 2. Get metadata (use summarize skill) summarize url https://github.com/awesome/project --format json

# 3. Analyze content and infer tags # From summary: "A CLI tool for Docker container management" # Canonical tags: docker, devops, cli, tools

# 4. Create bookmark clinkding bookmarks create https://github.com/awesome/project \ --title "Awesome Project - Docker Container CLI" \ --description "Command-line tool for managing Docker containers with enhanced features" \ --tags "docker,devops,cli" ```

### 标签映射启发式规则

使用这些规则来映射内容 → 规范标签：

| 内容类型 | 规范标签 | |--------------|----------------| | Web 开发、HTML、CSS、JavaScript | `webdev`, `css`, `javascript` | | React、框架、前端 | `webdev`, `react` | | 设计、UI/UX、模型 | `design` | | Python、Go、Ruby 代码 | `programming`, `python`/`ruby` | | Docker、K8s、DevOps | `docker`, `devops`, `cloud` | | 家庭自动化、ESP32、传感器 | `smart-home`, `esphome`, `iot` | | AI、ML、LLM | `ai`, `llm` | | 生产力工具、工作流 | `productivity`, `tools` | | 金融、投资、加密货币 | `finance` | | 营销、SEO、广告 | `marketing` | | 购物、优惠、商店 | `ecommerce` | | 教程、指南、文档 | `guide`, `howto`, `documentation` | | 安全、隐私、加密 | `security`, `privacy` | | 本地（DFW/Seattle） | `texas`, `seattle` |

### 创建前的验证

始终运行这些检查：

```bash # 1. Does URL already exist? clinkding bookmarks check <url>

# 2. Do the tags exist? clinkding tags list --plain | grep -iE "^(tag1|tag2|tag3)$"

# 3. Are we using canonical tags? # Cross-reference against the 263 canonical tags # Never create new tags without explicit user request ```

### 用户请求保存多个链接

如果用户提供多个 URL：

```bash # Process each URL separately with metadata extraction for url in url1 url2 url3; do # Get metadata # Infer tags # Create bookmark done ```

### 更新现有书签

如果用户说“更新那个书签”或“给我刚才保存的添加标签”：

```bash # Get most recent bookmark recent_id=$(clinkding bookmarks list --limit 1 --plain | cut -f1)

# Add tags (don't remove existing ones unless asked) clinkding bookmarks update $recent_id --add-tags "new-tag"

# Update description clinkding bookmarks update $recent_id --description "Updated notes" ```

### 关键原则

1. **始终获取元数据** - 使用 `summarize` 获取好的标题/描述 2. **使用现有标签** - 在不检查规范列表的情况下永远不要创建新标签 3. **有所选择** - 最多 2-5 个标签，选择最适用的 4. **首先验证** - 创建前检查重复项 5. **提供上下文** - 包含简短的解释说明其有用之处

---

## 当前规范标签结构

Dave 的 linkding 实例在整合了 17,189 个重复项后拥有 **263 个规范标签**。

热门类别（按书签数量）： - `pinboard` (4,987) - 旧版导入标签 - `ifttt` (2,639) - 旧版导入标签 - `webdev` (1,679) - Web 开发 - `design` (561) - 设计/UI/UX - `content` (416) - 内容/写作 - `cloud` (383) - 云/托管/SaaS - `business` (364) - 商业/策略 - `ecommerce` (308) - 购物/市场 - `smart-home` (295) - 家庭自动化 - `productivity` (291) - 生产力工具

**黄金法则：** 如果不确定，请使用更广泛的现有标签，而不是创建新的具体标签。