# Linkwarden

> Manage a Linkwarden instance through its official HTTP API: check configuration, search and inspect bookmarks, collections, tags and highlights, and perform controlled link, collection or tag changes with explicit confirmation for destructive actions.

- **Type:** Skill
- **Install:** `agentstack add skill-uvwt-agentdock-linkwarden`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [uvwt](https://agentstack.voostack.com/s/uvwt)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [uvwt](https://github.com/uvwt)
- **Source:** https://github.com/uvwt/agentdock/tree/main/skill-sources/linkwarden
- **Website:** https://uvwt.github.io/agentdock-docs/

## Install

```sh
agentstack add skill-uvwt-agentdock-linkwarden
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Linkwarden Skill

通过 Linkwarden 官方 HTTP API 查询和管理书签、集合、标签与高亮。Skill 使用 Bearer Token，只依赖 Python 标准库，不包含 Linkwarden 源码或服务端组件。

## 适用场景

使用本 Skill 处理：

- 检查 Linkwarden 实例版本、连通性和鉴权配置；
- 搜索书签，按集合、标签、置顶状态筛选；
- 查看书签详情、归档状态和高亮；
- 创建或修改书签；
- 查看、创建或修改集合；
- 查询标签；
- 在明确确认后删除书签、集合或标签，以及重新生成归档。

不要使用本 Skill 处理用户注册、密码重置、管理员用户管理、文件上传、Token 创建/吊销、批量删除或任意 API 透传。这些能力不属于当前安全边界。

## 环境变量

| 变量 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `LINKWARDEN_URL` | config | 是 | Linkwarden 实例根地址，例如 `https://links.example.com` |
| `LINKWARDEN_TOKEN` | secret | 是* | API Bearer Token；除公开状态检查外均必填 |
| `LINKWARDEN_INSECURE_TLS` | config | 否 | 仅自签名证书调试时设为 `1`；会跳过 TLS 证书校验 |

环境变量缺失时，脚本返回结构化错误，不会尝试读取浏览器 Cookie、配置文件或宿主私有目录。

## 安全约束

- 服务地址只允许 `http` 或 `https`，禁止在 URL 中嵌入用户名、密码、查询参数或片段。
- Token 只从当前进程环境读取，不通过参数传递，也不会出现在输出和错误信息中。
- 查询统一使用 `/api/v1/search`；不使用已废弃的 `GET /api/v1/links`。
- 修改书签或集合前先读取当前对象，再构造 Linkwarden 要求的完整请求体，避免未提供字段被意外清空。
- `delete-link`、`delete-collection`、`delete-tag` 和 `rearchive-link` 必须收到 `confirm: true`。
- 删除集合还必须提供与当前集合名称完全一致的 `confirm_name`。
- 删除标签还必须提供与当前标签名称完全一致的 `confirm_name`，以及与当前关联书签数量完全一致的 `confirm_link_count`。
- `rearchive-link` 会删除现有归档文件并触发重新归档，属于有数据影响的操作。
- 不开放批量操作和任意路径请求，避免扩大误操作范围。

## 执行方式

在 Skill 包根目录运行：

```bash
printf '%s' '{"skill_action":"status"}' | python3 run.py
```

输入必须是 JSON 对象，动作字段为 `skill_action`。输出始终为 JSON；HTTP 响应保持在 `response` 字段中。

## 动作

| 动作 | 类型 | 主要输入 | 说明 |
|---|---|---|---|
| `status` | 只读 | 无 | 检查环境配置；已配置 URL 时调用公开 `/api/v1/config` |
| `search` | 只读 | `query?`, `sort?`, `cursor?`, `collection_id?`, `tag_id?`, `pinned_only?` | 搜索或分页读取书签 |
| `get-link` | 只读 | `id` | 获取单条书签完整信息 |
| `get-highlights` | 只读 | `id` | 获取书签高亮 |
| `create-link` | 写入 | `url`, `name?`, `description?`, `collection_id?` 或 `collection_name?`, `tags?` | 创建 URL 书签 |
| `update-link` | 写入 | `id` 以及需要修改的字段 | 读取现状后合并更新；支持名称、URL、描述、样式、集合、标签和置顶用户 ID |
| `rearchive-link` | 破坏性写入 | `id`, `confirm: true` | 清除当前归档并触发重新归档 |
| `delete-link` | 删除 | `id`, `confirm: true` | 删除单条书签 |
| `list-collections` | 只读 | 无 | 获取当前用户可访问的集合 |
| `get-collection` | 只读 | `id` | 获取集合详情 |
| `create-collection` | 写入 | `name`, `description?`, `color?`, `icon?`, `icon_weight?`, `parent_id?` | 创建集合或子集合 |
| `update-collection` | 写入 | `id` 以及需要修改的字段 | 读取现状并保留成员关系后更新 |
| `delete-collection` | 删除 | `id`, `confirm: true`, `confirm_name` | 名称匹配后删除集合 |
| `list-tags` | 只读 | `search?`, `sort?`, `cursor?` | 查询标签，默认按名称升序 |
| `delete-tag` | 删除 | `id`, `confirm: true`, `confirm_name`, `confirm_link_count` | 名称与当前关联数量均匹配后删除单个标签 |

`tags` 推荐传字符串数组：

```json
{
  "skill_action": "create-link",
  "url": "https://example.com",
  "collection_id": 42,
  "tags": ["reference", "ai"]
}
```

修改书签时只提供需要变化的字段：

```json
{
  "skill_action": "update-link",
  "id": 101,
  "name": "新的标题",
  "tags": ["reference", "reviewed"]
}
```

脚本会先读取书签 101，保留未指定字段，再提交 Linkwarden 所需的完整更新对象。

删除标签前必须确认当前名称和影响数量：

```json
{
  "skill_action": "delete-tag",
  "id": 77,
  "confirm": true,
  "confirm_name": "legacy-tag",
  "confirm_link_count": 0
}
```

脚本会先读取标签 77；只要名称或关联数量已经变化，就拒绝删除。

## 操作流程

1. 首次使用先执行 `status`，确认 URL、Token 和实例连通性。
2. 涉及集合或标签名称时，先用 `list-collections` 或 `list-tags` 解析真实 ID。
3. 更新和删除前读取目标对象并向用户复述关键字段；删除标签时还要复述当前关联书签数量。
4. 写操作完成后再次读取目标对象，验证最终状态。
5. HTTP 失败时返回状态码、端点和服务端响应；不要用猜测替代真实失败证据。

接口和字段依据见 `references/api.md`。

## AgentDock 适配

在 AgentDock 中，把环境值配置到该 Skill 的独立环境，再通过绑定当前激活 Skill 的命令执行能力运行 `python3 run.py`。不要手工拼接已安装版本目录，也不要把真实 Token 写入 Skill 包、源码仓库或 Recall。

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [uvwt](https://github.com/uvwt)
- **Source:** [uvwt/agentdock](https://github.com/uvwt/agentdock)
- **License:** Apache-2.0
- **Homepage:** https://uvwt.github.io/agentdock-docs/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-uvwt-agentdock-linkwarden
- Seller: https://agentstack.voostack.com/s/uvwt
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.