zurl

Zurl 短链接管理

通过 Zurl 服务 API 管理短 URL。

执行规则

直接运行用户请求的命令，不要预先检查依赖项、环境变量或配置。如果有问题，脚本会报出明确错误——只有在出错后才检查并修复。

重要规则

1. API URL 只能从环境变量获取 — 必须设置 ZURL_APIURL；切勿硬编码 API 地址。
2. 自动生成短码 — 用户要求缩短 URL 但未指定短码时，脚本会自动生成 4 个字符的随机短码（字母 + 数字）。
3. 创建时不设置标题 — 创建短链接时，标题传入空字符串 ""，以便 Zurl 自动获取页面标题。请勿自行填写标题。
4. 显示所有域名 — 创建或更新短链接后，始终显示所有已配置的显示域名（来自 ZURL_DISPLAY_URLS；脚本的 short_links 字段包含完整 URL）。
5. 二维码域名 — 如果要生成二维码，请使用 ZURL_DISPLAY_URLS 中的第一个域名作为二维码内容（除非用户指定其他域名）。

环境变量

变量	必需	描述
ZURL_APIURL	✅	API 基础 URL，例如 http://192.168.1.100:3088
ZURL_TOKEN	❌	API 身份验证令牌（服务器启用身份验证时必需）
ZURL_DISPLAY_URLS	❌	以逗号分隔的显示域名列表；默认为 ZURL_APIURL

脚本会自动从 ~/.wmyskills/.env（所有技能共用）加载这些变量；如果脚本目录中存在 scripts/.env，则优先使用该文件。请以 scripts/.env.example 为模板，将变量添加到 ~/.wmyskills/.env，切勿覆盖已有文件。

要求

pip install python-dotenv

用法

脚本：scripts/zurl_api.py

创建短 URL

python scripts/zurl_api.py shorten <long_url> [short_code] [title] [description] [ttl_days]

参数	必需	描述
long_url	✅	原始长 URL
short_code	❌	自定义短码；未提供时自动生成（4 个字符）
title	❌	标题（留空以自动获取）
description	❌	描述
ttl_days	❌	生存时间（天）

更新短 URL

python scripts/zurl_api.py update <id> [long_url] [short_code] [title] [description] [ttl_days]

参数	必需	描述
id	✅	URL 数据库 ID（来自列表或搜索结果）
long_url	❌	新的长 URL
short_code	❌	新的短码
title	❌	新标题
description	❌	新描述
ttl_days	❌	新的生存时间（天）

脚本会跳过值为 None（未设置）的参数——不会将其发送到 API。如果 API 要求提供 long_url 或 short_code，省略它们会导致 422 错误。传入 ""（空字符串）可清空字段。short_code 不能为空；空值会被跳过，以避免 API 返回 500 错误。

编辑短 URL（key=value 格式）

# Update specific fields using -o key=value (repeatable)
python scripts/zurl_api.py edit <id> -o long_url=https://new.url -o title="New Title"

参数	必需	描述
id	✅	URL 数据库 ID（来自列表或搜索结果）
-o / --option	✅	key=value 键值对（可重复）。键：long_url、short_code、title、description、ttl_days

这是 update 的替代方式，使用 -o key=value 键值对，而不是位置参数。只有通过 -o 指定的字段会被更改——未指定的字段保持不变（而 update 会跳过未提供的位置参数，但空值 "" 会清空字段）。

删除短 URL

# Delete by short code
python scripts/zurl_api.py delete <short_code>

# Batch delete by short codes (comma-separated)
python scripts/zurl_api.py delete-batch code1,code2,code3

delete-batch 接受短码（slug）——脚本会遍历所有页面，查找对应的数据库 ID，然后删除这些 URL。与任何 URL 都不匹配的短码会被静默跳过。

列表与搜索

# List short URLs (paginated)
python scripts/zurl_api.py list [page] [limit]

# Search
python scripts/zurl_api.py search <keyword> [filter_type]

filter_type：all（默认）/ long_url / short_url / title

获取 URL 元数据

python scripts/zurl_api.py metadata <url>

返回目标页面的标题和描述。

向用户展示

创建或更新短链接后，解析 JSON 响应，并使用 short_links 字段（通过 ZURL_DISPLAY_URLS 配置）向用户展示结果。示例：

✅ Short URL created

Short Links:
  https://short.example.com/abc123
  https://s.example.com/abc123

Original URL: https://very-long-url.com/page
Title: Page Title

实际域名来自 ZURL_DISPLAY_URLS——以上示例仅供参考。

已验证的 API 端点

端点	方法	状态
/api/shorten_url	POST JSON	✅
/api/update_url/{id}	POST JSON	✅
/api/delete/url	POST 表单	✅
/api/delete/urls	POST JSON	✅
/api/urls	GET	✅
/api/search	POST JSON	✅
/api/get_url_metadata	POST 表单	✅

响应格式

脚本将 JSON 输出到 stdout。

成功（包含 short_links 的命令）：

{"code": 200, "msg": "...", "data": {"short_url": "abc123", "long_url": "...", ...}, "short_links": ["https://s.example/abc123", ...]}

short_links 字段由 shorten、update、list 和 search 添加。其他命令（delete、delete-batch、metadata）返回不含该字段的原始 API 响应。

成功（不包含 short_links 的命令）：

{"code": 200, "msg": "...", "data": {...}}

失败：

{"error": true, "status": 4XX, "detail": {...}}