Bird
Bird 是单一的 X/Twitter 路由器。默认使用 SocialData 作为廉价的读取层。仅当任务需要经过认证的账户上下文、X 原生对象或明确批准的账户变更时，才使用官方的 xurl CLI。不得让两个提供者回答同一个常规读取请求。
触发条件与兼容性
用于处理 X/Twitter URL、推文/线程/文章提取、搜索、用户资料、回复/引用/上下文、媒体检索和 X 账户操作。
保留以下入口点：
/bird <请求>— 标准路由器。- 遗留
bird.py <URL 或 ID>— 仍然通过 SocialData 读取。 /xurl ...— 兼容入口点，供明确请求 xurl 的用户使用；它必须遵循 Bird 的路由和写入门控。
确定性路由
| 意图 | 主要提供者 | 备用提供者 | 边界条件 |
|---|---|---|---|
| 通过 URL/ID 读取推文 | SocialData | 仅用于公共可见证据的 web/浏览器 | 绝不因为 xurl 存在就升级到它 |
| 读取线程/对话/回复 | SocialData | 仅当 X 原生上下文唯一必要且受支持时的 xurl 读取 | 从获取的数据中确定线程，而非 URL 形状 |
| 搜索帖子 | SocialData 有界搜索 | 现有的 SocialData/web 研究路由 | 当前不假定 xurl 最近搜索可用 |
| 读取公开资料 | SocialData | 需要账户特定或当前 X 视图时的 xurl 用户查询 | 不进行批量图谱收集 |
| X 文章 | 优先使用 SocialData 推文负载；解析嵌套文章 | 带有 article 字段的 xurl 原始推文端点 | 当文章文本缺失时，跟随链接的第一方页面 |
| 下载附加媒体 | SocialData 元数据 + 有界 HTTPS 下载 | 仅用于可见公共媒体的浏览器 | URL/日志中不含 cookie；验证主机/大小/类型 |
| 我是谁 / 认证身份 | xurl | 无 | 只读账户上下文 |
| 后续互动所需的精确 X 原生对象 | xurl | 用于发现/上下文的 SocialData | 仅对精确的对象/端点使用 xurl |
| 发布、回复、引用、删除、喜欢、转推、书签、关注、屏蔽、静音、私信、上传 | xurl | 无 | 需要显式批准精确目标、内容和效果 |
加载提供者路由以获取端点配方、错误和回退规则。仅针对 xurl 特定任务加载 xurl 操作。
提供者与成本契约
- SocialData 是所有常规读取的默认选项。优先在当前运行时中使用配置的直接
SOCIALDATA_API_KEY。当直接密钥缺失且 H20 客户密钥具有socialdata能力时，使用经批准的 Human20 Keys SocialData 代理。可能存在通用的 H20 模型密钥，但返回provider not allowed: socialdata；这不构成切换到 xurl 的理由。 - 当前 Human20 Keys 对
social-request的默认价格等级已验证为0 credits/request；将其视为可变运行时状态，并在声明成本前重新检查。 - 一个用户请求通常应消耗一次查找/搜索以及线程或请求上下文所需的有界依赖读取。不得进行扇出、抓取关注者/关注、导出、流式处理、轮询或批量获取。
- 切勿静默地从 SocialData 回退到付费的 X API 调用。
xurl是根据能力需求而非提供者故障选择的。
机密与执行安全
- 绝不要读取、打印、解析、总结或暴露密钥存储、
~/.xurl、cookie、授权标头、API 密钥、承载令牌、请求签名或环境值。 - 仅通过安全的状态/探测命令验证凭据。不要使用 xurl 的
--verbose/-v或内联凭据标志。 - SocialData 调用是只读且有界的。将
401/403视为凭据/策略问题，402视为额度/计费问题，404视为不存在/私有/已删除，429视为速率限制，5xx视为提供者故障。不要将一类错误误标为另一类。 - 浏览器/中继是最后手段，绝不是 cookie 提取机制。
- 写操作是受保护的效果。在任何 xurl 变更之前，重新读取精确的目标和负载，要求用户对该精确效果进行显式批准，执行一次，并从原始 xurl/X 响应中验证。批准研究不等于批准互动或发布。
- 私信、删除、屏蔽、账户变更、媒体上传和公开发布绝不应隐式发生。
工作流程
- 对请求进行分类：
read（读取）、search（搜索）、profile（资料）、thread（线程）、article（文章）、media（媒体）、account-read（账户读取）或write（写入）。 - 标准化 X URL/ID 而不改变标识符。在决定推文与线程之前先获取数据。
- 根据表格路由。对于常规读取，首先恰好调用一次 SocialData。
- 防御性解析。文章负载可能位于
article.title、article.preview_text和article.content_state.blocks[]中；媒体可能嵌套在引用或转推的对象中。 - 如果用户询问某项内容是否重要，打开链接的第一方仓库/文档/文章并检查附加媒体。将 X 帖子视为声明/来源，而非自动证据。
- 如果所选提供者失败，报告确切的失败原因。仅当备用提供者仍能在不扩大成本、隐私或效果的情况下回答相同请求时，才使用已声明的备用提供者。
- 返回忠实于来源的输出和简洁的提供者收据。
输出契约
返回：
结果：<完整的请求内容或简洁忠实的答案>
类型：tweet | thread | article | profile | search | account-action
作者/来源：<安全的公共身份 + 规范 URL>
提供者：SocialData | xurl | web/browser fallback
证据：<ID、时间戳、指标/上下文（如果可用）>
操作回执：<仅限已批准的 xurl 变更；确切状态/对象 ID>
限制：<缺失/私有/已删除/速率/计划/提供者缺口，或无>
不要在面向用户的回执中暴露内部密钥、认证模式、密钥位置或私有运行时细节。
快速测试清单
-
/bird <推文 URL>选择 SocialData，而非 xurl。 -
/bird search from:handle选择有界的 SocialData 搜索。 -
/bird whoami选择只读的 xurl 身份。 -
/bird reply <URL> <文本>在 xurl 之前停止以获取精确批准。 - SocialData 的
402不应报告为缺少凭据；xurl 最近搜索失败不应禁用身份/资料读取。 - 线程和文章解析使用获取的结构，而非 URL 猜测。
- 移除 SocialData 默认或写入批准契约会导致验证失败。
完成标准
- 请求的 X 内容/操作已完成，或报告了一个确切的阻塞项。
- 常规读取首先使用了 SocialData，避免了重复的提供者支出。
- xurl 仅用于特定能力的原因。
- 任何写操作都已获得精确批准并进行了原始 API 回读。
- 没有机密/cookie/私有凭据材料进入输出、工件或日志。