From x_likes
Operate the user's own X (Twitter) Likes via natural language — list likes, download media, check credential health. Backed by a local `x_likes_downloader serve --mcp` MCP server (Rust). All credentials stay on the user's machine.
How this skill is triggered — by the user, by Claude, or both
Slash command
/x_likes:x_likesThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
让 AI Agent 通过自然语言操作"我自己的 X 点赞"——列点赞、按需下载媒体、自检凭据健康状态。底层是本地的 `x_likes_downloader serve --mcp` MCP server(Rust 实现),凭据完全保留在用户机器上。
让 AI Agent 通过自然语言操作"我自己的 X 点赞"——列点赞、按需下载媒体、自检凭据健康状态。底层是本地的 x_likes_downloader serve --mcp MCP server(Rust 实现),凭据完全保留在用户机器上。
适用场景:
不适用:跨账号、批量监控他人、第三方 API key 模式。
x_likes_downloader 可执行文件 ≥ 2.1.0(含 serve --mcp 子命令)x_likes_downloader 必须在 PATH 中。MCP 客户端尝试启动失败时(如未安装),客户端会提示——请将用户引导到 GitHub Releasesx_likes_downloader setup --curl-file <path> 导入 cURL(首次使用)Skill 发行物按 host 注册(Claude Code plugin / Codex CLI plugin / OpenClaw skill / Hermes / Cursor);具体注册路径与命令见对应 host adapter README。本文件保持 host-agnostic。
Skill 通过 MCP 协议暴露四个工具。客户端在启动后会调用 tools/list 自动发现它们;下面给出每个工具的语义、参数、返回值与典型错误码。
list_likes用途:拉取当前账号的点赞推文列表(扁平 schema:id / author_handle / text / media[] / created_at 等)。返回值含 cursor 用于增量同步。Agent 应当把 tweets[].media[] 元素直接传给 download_media 下载。
参数(JSON Schema 已通过 tools/list 自动暴露给客户端):
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
all | bool | 否 | 翻页拉全部历史;默认仅首页 |
since_cursor | string | 否 | 增量同步起点游标(来自上次输出的 cursor 字段) |
count | number | 否 | 单页条数;默认 20 |
include_raw | bool | 否 | 同时返回原始 GraphQL entry,显著增加 token 成本(5–10 倍),仅用于调试 |
返回内容(CallToolResult { isError: false, content: [{type: "text", text: "<JSON>"}] },text 反序列化后):
{
"tweets": [
{
"id": "1234567890",
"author_handle": "alice",
"author_display_name": "Alice",
"text": "tweet 正文(无 t.co 替换)",
"created_at": "Thu Apr 06 15:24:15 +0000 2017",
"tweet_url": "https://x.com/alice/status/1234567890",
"is_retweet": false,
"is_reply": false,
"media": [
{
"tweet_id": "1234567890",
"type": "image", // image | video | gif
"url": "https://pbs.twimg.com/media/AAA.jpg?format=jpg&name=orig",
"suggested_filename": "AAA.jpg",
"bytes": null
}
],
"liked_at": null
}
],
"cursor": "...",
"schema_version": 1
}
典型错误 kind(content 反序列化后含 {kind, message, hint}):auth_expired / endpoint_stale / rate_limited / network_error / not_configured / internal_error
download_media用途:把一组 MediaItem 下载到沙箱目录。最佳实践:直接把 list_likes 输出的 tweets[].media[] 元素拼成数组传回——MediaItem 形态完全一致。
参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
items | MediaItem[] | 是 | 来自 list_likes 的 media 元素列表 |
subdir | string | 否 | 沙箱内子目录名;不允许 .. / 绝对路径 / 驱动器盘符 |
concurrency | number | 否 | 并发下载数;钳位 [1, 16],默认 4 |
进度反馈(重要):调用方在 MCP 请求 _meta.progressToken 中传入 token,server 会在下载过程中通过 MCP notifications/progress 实时推送进度。每条 notification 含:
progress(数值,绝对计数):已完成的 item 数(每完成一个 item 递增 1,绝对单调非递减)。多并发下也保证不回退total(数值):批次总 item 数,与 progress 配对使用——client 计算百分比 = progress / totalmessage(字符串):当前操作描述,含字节级进度细节(如 "starting tweet 12345"、"tweet 12345 1024/4096"、"tweet 12345 Downloaded")这与 MCP 规范的 ProgressNotificationParam 一致——progress 字段无 [0, 1] 范围约束,是单调递增的绝对进度数值,与 total 字段配对供 client 渲染百分比。完成时发出 progress == total(比例 1.0)。
为什么 progress 用 item 计数而不是字节比例:在 concurrency > 1 时多个 item 并发下载,单 item 内字节比例在 item 之间会非单调(item A 跑到 80% 时切换到刚开始的 item B 会"倒退")。让 progress 跟 item 计数走是保证单调性的最简方式;字节级细节仍在 message 字段呈现给用户。
不传 progressToken 时无进度通知,工具调用阻塞直到所有 item 完成。
返回内容(成功):
{
"downloads": [
{ "tweet_id": "...", "url": "...", "path": "...", "bytes": 12345, "status": "downloaded" },
// ... status 可为 "downloaded" / "skipped_existing" / "failed"
],
"summary": { "total": 5, "downloaded": 4, "skipped": 1, "failed": 0 }
}
典型错误 kind:sandbox_violation(subdir 路径穿越)/ invalid_item(items 字段不全)/ invalid_argument(concurrency 越界)/ network_error
分批使用建议:当 item 数量 > 20 或预计总字节数 > 50 MB 时,请将下载分成多次调用,每批 5–10 个 item。这样 MCP notifications/progress 能驱动用户可见的分阶段反馈,且避免单次调用阻塞过久。
auth_status用途:探测当前凭据是否仍可访问 Likes 端点。实际发起一次轻量真实请求(约 200ms),不是仅做字段检查。
参数:(无)
返回内容(健康):
{ "status": "healthy", "checked_at": "2026-05-08T12:34:56+00:00" }
返回内容(失效):isError: true,content 含 { kind, message, hint } 形态错误,kind 为 auth_expired / endpoint_stale / rate_limited / network_error / not_configured
auth_status 使用规范(重要)auth_status 执行真实网络请求,不应被频繁调用。Agent 应当仅在以下三种场景调用:
auth_expired 或 endpoint_stale 时,调一次确认是否真的需要重导 cURL禁止以下使用模式:
如果 Agent 需要更新鲜的状态,重新调用 list_likes 即可——它本身就会反映出 cookie 是否有效。
setup_from_curl用途:从用户提供的 cURL 文本导入凭据 + 协议参数(首次配置或 cookie 失效后重导)。
参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
curl_text | string | 是 | 完整的 cURL 文本(从浏览器 DevTools "Copy as cURL (bash)" 拷贝) |
安全保证:函数内存解析,不写临时文件;返回值不回显任何凭据。
返回内容(成功):
{
"written": true,
"path": "<host-managed credentials path>",
"protocol_params_extracted": true
}
典型错误 kind:
invalid_argument:cURL 内容不是 Likes 端点 / cookie 缺字段 / Bearer 缺失internal_error:写入凭据文件失败当 Agent 引导用户时:告诉用户在浏览器中打开 X,登录后从 DevTools Network 标签页找到任意 /Likes API 请求,右键"Copy as cURL",把整个文本作为 curl_text 参数传给本工具。
以下 x_likes_downloader 子命令不在 Agent 工具表内(也不在 MCP tools/list 暴露),请勿调用:
x_likes_downloader download:旧版"列+下"一把梭,写到 ./downloads,不走沙箱。保留给人类用户的现有工作流x_likes_downloader organize:按用户名归档已下载文件。Agent 通常会按自己的逻辑(按主题、时间)组织内容,无需服务端归档x_likes_downloader update:版本自更新,应由用户手动管理| 项 | 约定 |
|---|---|
| 协议 | MCP(JSON-RPC 2.0,stdio transport) |
| 工具调用 | tools/call { name, arguments } |
| 成功 | CallToolResult { isError: false, content: [{type:"text", text: <JSON>}] },text 反序列化即结果 |
| 业务错误 | CallToolResult { isError: true, content: [{type:"text", text: <error JSON>}] },text 含 {kind, message, hint, retry_after?} |
| 协议错误 | JSON-RPC level error response(unknown tool、bad args 等) |
| 进度反馈 | download_media 在请求带 _meta.progressToken 时通过 MCP notifications/progress 推送;其它工具无进度 |
| Cancellation | v2.0 收到 notifications/cancelled 被忽略(仅 stderr 日志记录);客户端如需强制终止可关闭 MCP 连接 |
auth_expired / endpoint_stale | Agent 应建议用户重新导出 cURL 并调用 setup_from_curl |
binary_missing | Agent 应将用户引导到 GitHub Releases 安装页 |
tools/call 响应不含任何凭据字段;setup_from_curl 返回值仅含 path 与 written 标志download_media 的写入路径被 sandbox 严格限定在 base dir 之内;Agent 即使尝试 subdir = "../etc" 也会被拒绝(返回 sandbox_violation)x_likes_downloader serve --mcp 是 v2 给 Agent 用的接口;人类用户继续可以直接在 shell 里跑:
x_likes_downloader setup --curl-file ~/curl_command.txt
x_likes_downloader auth status --json | jq
x_likes_downloader likes list --count 10 --json | jq '.data.tweets[] | {id, author_handle, text}'
x_likes_downloader media download --items @items.json --concurrency 4
这些 --json 子命令的 stdout JSON 信封契约未变,仍是人类调试 / shell pipeline 的首选。它们与 MCP server 共享同一份 lib 实现(agent::list_likes / agent::download_media / agent::auth_status / agent::import_curl),任何修复同时受益。
Agent 调用形态仅限 MCP——SOT 不再描述"spawn
x_likes_downloader <subcmd> --json"作为 Agent 路径。
Provides CDSS development patterns for drug interaction checking, dose validation, clinical scoring (NEWS2, qSOFA), and alert classification integrated into EMR workflows.
npx claudepluginhub herbertgao/x_likes_downloader --plugin x_likes