citation-fixer

引用修复技能

约定： 请参阅 conventions/quality.md，了解每次修复都应遵循的标准引用格式。

输出规则： 所有链接必须具有确定性（由 API 数据构建，而非由 LLM 生成）。参见 _output-rules.md。

约定

本技能保证：

• 扫描每个 brain 页面的引用合规性。
• 缺失的引用会被标记并注明具体位置。
• 格式错误的引用会被修正为标准格式。
• （v0.25.1） 没有 URL 的推文/帖子引用会通过 X API 解析，并替换为确定性的 https://x.com/<handle>/status/<id> 链接。
• 以计数形式报告结果（已扫描、已修复、剩余）。

阶段

1. 扫描页面。 列出页面并逐一读取，检查行内的 [Source: ...] 引用。
2. 识别问题：
   • 没有任何引用的事实
   • 引用缺少日期
   • 引用缺少来源类型
   • 引用格式错误
   • （v0.25.1） 没有 x.com URL 的推文引用
3. 修复格式问题。 将格式错误的引用改写为符合 conventions/quality.md 的格式。
4. （v0.25.1）通过 X API 集成解析推文引用。
5. 报告结果。 统计：已扫描页面数、找到的引用数、已修复问题数、已解析推文数、剩余缺口。

推文解析流程（v0.25.1 扩展）

对于每个有问题的推文引用，遵循以下步骤。实际的 API 调用通过宿主已配置的任何 X 集成完成（典型形式为 recipes/x-api/ 下的一个配方，包含 handle / search-all 端点）。

第 1 步：识别有问题的引用

扫描页面，查找表明推文引用缺少 URL 的模式：

• 包含 tweeted、posted、said on X、RT、retweet、X post 等词语
• 包含看起来像推文的引述文本（简短、有力，常以引号开头）
• 有 [Source: ... X/Twitter ...] 但没有 x.com URL
• 提及互动指标（点赞、曝光量）但没有链接

第 2 步：提取可搜索内容

从每条有问题的引用中提取：

• handle（如有提及：@<username>）
• 引述文本（如有）
• 大致日期（通常见于周围的时间线条目中）

第 3 步：搜索实际推文

使用宿主的 X API 集成。查询模式：

# Handle + quoted text:
from:<handle> "<exact quote fragment>"

# Quoted text only:
"<exact quote fragment>"

# Original of a retweet:
"<exact quote>" -is:retweet

第 4 步：验证并提取元数据

找到候选推文后：

• 确认文本与引述片段一致。
• 提取推文 id、作者 handle、互动指标（点赞 / 转推 / 曝光量）。
• 构造 URL：https://x.com/<handle>/status/<tweet_id>。

第 5 步：修补 brain 页面

用正确的引用替换有问题的引用：

修改前：

"<quote fragment>" [Source: <some hand-wavy attribution>]

修改后：

"<full verified quote>" — <N> likes, <N> RTs, <N> impressions
[Source: [X/<handle>, YYYY-MM-DD](https://x.com/<handle>/status/<tweet_id>)]

批量模式

在批量扫描多个页面时：

查找候选页面

# Pages mentioning tweets but with no x.com links
for f in $(find . -name "*.md" -not -path "./node_modules/*"); do
  refs=$(grep -ci "tweet\|posted\|x post\|RT\|retweet\|said on X" "$f")
  links=$(grep -c "x.com/.*/status/" "$f")
  if [ "$refs" -gt 2 ] && [ "$links" -eq 0 ]; then
    echo "$f"
  fi
done

优先级顺序

1. 最近创建或更新的页面——新出现的有问题引用在上下文仍新鲜时最容易解决。
2. 高流量页面（其他技能频繁读写的页面）。
3. 其余页面——随时间进行的批量清理。

速率限制

• X API：遵守宿主的层级限制，不要高频请求。
• 每次批量运行目标约 50 个页面。
• 每个页面 1-3 次 API 调用（搜索 + 验证）。
• 每 10-20 个页面批量提交一次，以免部分失败导致进度丢失。

输出格式

Citation Audit Report
=====================
Pages scanned:        N
Citations found:      N
Issues fixed:         N
Tweet links resolved: N
Remaining gaps:       N (pages with uncitable facts)

失败处理

对于任何 gbrain 错误 code、退出码、[AGENT] 块或通知块，请遵循 agent 操作协议。针对本技能的具体说明：

• put_page 在批量处理中返回 revision_conflict：重新读取该页面，仅重新应用引用修复，然后继续；切勿用之前读取的副本覆盖。
• get_page 对被引用的来源返回 page_not_found：在报告中将该引用标记为无法解析，而不是改写为猜测的 slug。
• 批量提交被中断：已提交的页面保持修复状态；从最后一个已提交的页面恢复，而不是从头开始。

反模式

• ❌ 为没有来源的事实编造引用。需要标记出来。
• ❌ 删除缺少引用的事实（应标记，而不是删除）。
• ❌ 未阅读完整页面上下文就修复引用。
• ❌ 未先抽样检查质量就批量修复（参见 conventions/test-before-bulk.md）。
• ❌ 通过猜测推文 ID 来拼接推文 URL。必须始终通过 X API 获取，只使用可确定的链接。

集成

本 Skill 可通过以下方式调用：

• 手动调用——"修复此页面上的引用"
• 作为批量定时任务——每周扫描存在失效引用的页面
• 由其他 Skill 调用——enrich 或 media-ingest 可在提交前调用 citation-fixer 来校验输出

指标

如果作为周期性批处理运行，请将状态保存在一个小型 JSON 文件中，路径为 ~/.gbrain/citation-fixer-state.json：

{
  "last_run": "2026-04-15T...",
  "pages_scanned": 0,
  "citations_fixed": 0,
  "tweet_links_resolved": 0,
  "citations_unresolvable": 0,
  "pages_remaining": 1424
}

输出格式

该 Skill 的输出结构已在上方正文章节中说明（参见 "Output"、"Brain page format" 或同类章节）。此处保留的字面标题用于一致性测试（test/skills-conformance.test.ts）。