引用溯源规范（Web Reference Tracing）

当你需要在回答中引用外部项目、仓库、库、代码示例或技术文档时，必须通过互联网工具实时验证和溯源，而非仅凭训练数据中的记忆给出引用。

本规范覆盖所有"需要引用外部资源"的场景，包括但不限于：用户问某个库的用法、需要参考其他项目的实现、需要引用文档说明、需要引用社区最佳实践。

1. 为什么需要

大模型训练数据存在时效滞后和信息偏差。直接凭记忆引用会带来以下风险：

• API 签名已变更：记忆中是旧版签名，实际新版已弃用
• 仓库已迁移或弃用：记忆中的 GitHub 链接可能已 404
• 最佳实践已过时：社区已转向更好的替代方案
• 无法追溯来源：用户问"这个信息来自哪里？"时无法回答

通过实时溯源，你确保每条引用都是当下可验证的，且用户能追溯到原始来源。

2. 引用类型识别与查询策略

当你遇到对"其他仓库/项目/库"的引用需求时，先判断引用类型，选择对应的查询策略。

在开始查询前，先明确引用类型，选择对应的工具链。 不要对所有引用都用同一种查询方式。

⚠️ 关于 context7 的重要说明：context7 是一个预索引缓存系统（非实时查询），热门库 1 天刷新一次，冷门库最长 45 天才刷新。使用 context7 时，必须先调用 resolve-library-id 检查返回结果的质量（Code Snippets 数量、Source Reputation），不能默认 context7 一定能查到最新信息。详见 §3.2-§3.4。

3. 主链接查询规范

在引用任何外部资源时，必须先用网络工具获取当前最新信息，不能凭训练数据中的记忆直接输出。

3.1 按输入类型的查询流程

正确：

# 用户问 "Python 3.12 的 itertools.batched 怎么用"
# 步骤 1：搜索官方文档
context7_query_docs(libraryId="/python/cpython", query="itertools.batched")
# 步骤 2：获取结果后给出答案，并标注来源

错误：

# 直接凭记忆写 itertools.batched 的用法
# 可能记得的是 3.11 的提案版，和 3.12 正式版签名不同

3.2 context7 新鲜度机制说明

context7 是一个预索引缓存系统，不是实时查询网关。 它从 GitHub 仓库、文档网站、llms.txt 等来源抓取文档并缓存，按库的流行度分级刷新：

数据来源：Context7 官方文档 Keeping Libraries Fresh

刷新是在被请求时后台异步触发的，不阻塞当前查询。但如果一个冷门库长时间无人请求，可能根本不会触发刷新。

3.3 工具决策流程——基于热度的动态选择

不要使用固定的工具优先级。 正确的流程是：先尝试 context7，根据返回结果的质量决定是否继续使用，还是降级到其他工具。

收到引用查询需求
  │
  ├─ 用户给了直接 URL 吗？
  │   ├─ 是 → webfetch 直接获取，跳过 context7
  │   └─ 否 → 继续 ↓
  │
  ├─ 步骤 1：尝试 context7 resolve-library-id
  │   └─ 根据返回结果走不同分支：
  │
  │   ┌─────────────────────────────────────────────────────┐
  │   │ resolve-library-id 返回特征  │  判断  │  后续操作    │
  │   ├─────────────────────────────────────────────────────┤
  │   │ Code Snippets ≥ 500         │ 覆盖良好 │ query-docs  │
  │   │ Source Reputation = High    │         │ + 标注来源   │
  │   ├─────────────────────────────────────────────────────┤
  │   │ Code Snippets 100-500       │ 有覆盖但 │ query-docs  │
  │   │ Reputation ≥ Medium         │ 可能不全 │ + 准备备选   │
  │   ├─────────────────────────────────────────────────────┤
  │   │ Code Snippets < 100         │ 覆盖不足 │ 降级 ↓      │
  │   │ Reputation = Low/Unknown    │         │             │
  │   ├─────────────────────────────────────────────────────┤
  │   │ 返回空 / 无匹配             │ 不在索引 │ 跳过 context7│
  │   └─────────────────────────────────────────────────────┘
  │
  ├─ 降级路径（context7 覆盖不足或不在索引时）：
  │   1. websearch_web_search_exa 搜索项目官方地址
  │   2. webfetch 获取官方文档 / README / 源代码
  │   3. grep_app_searchGitHub 搜索真实代码示例
  │
  └─ 特殊场景直接跳过 context7：
      ├─ 用户问 "最新版本" / "刚发布的特性" → webfetch 查 Release
      ├─ 需要查看 CHANGELOG / Release Notes → context7 默认排除此类文件
      ├─ 需要查看废弃/归档目录 → context7 默认排除 archive/ deprecated/
      ├─ 极冷门 / 个人项目 → context7 大概率不在索引中
      └─ 用户给了直接 URL → webfetch 直接获取

**正确**：

```python
# 用户问 "一个冷门库 xxx-utils 怎么用？"
# 步骤 1：先试 context7
result = context7_resolve_library_id(libraryName="xxx-utils", query="usage")
# 步骤 2：发现返回空/无匹配 → 不在索引中
# 步骤 3：降级到 websearch
websearch_web_search_exa(query="xxx-utils npm library documentation")
# 步骤 4：webfetch 获取官网内容

错误：

# 用户问冷门库用法
# 直接默认 context7 能查到，结果返回空
# 没有降级到 websearch，凭记忆回答 → 可能过时或错误

3.4 context7 结果质量快速判断

拿到 resolve-library-id 返回结果后，用以下指标快速判断是否值得继续用 query-docs：

如果三项指标都在"可疑"或"放弃"区间，直接降级到 websearch + webfetch。

4. 子链接递归追踪规则

获取主内容后，必须扫描页面中的子链接，对技术相关的引用链接继续查询。

这是本规范的核心规则——不满足于单页面的内容，要顺着引用链查下去。

4.1 需要追踪的子链接类型

当主内容包含以下特征时，必须识别并追踪其中的链接：

• 论坛问答帖：回答者贴的"参考实现"、"相关文档"、"类似问题"链接
• 博文/教程："详见"、"更多信息请参考"、"基于 XXX 项目"中的链接
• 文档页："See also"、"Related"、"参考"章节中的链接
• GitHub Issue/PR：引用的其他 Issue、Commit、PR、代码行链接
• 技术规范/RFC：引用的其他规范或草案

4.2 不需要追踪的链接

• 导航性链接："首页"、"分类"、"标签"
• 社交媒体链接：Twitter、Reddit 等非技术平台
• 广告/追踪链接
• 登录/注册页面
• 已访问过的 URL（避免死循环）

4.3 追踪深度规则

深度限制硬性规定：最多追踪到深度 2，在任何情况下不得超过。

4.4 执行流程

收到引用查询需求
  │
  ▼
查询主链接 / 搜索主内容
  │
  ▼
扫描主内容中的子链接
  │
  ├─ 判断每个子链接是否与当前查询直接相关
  │   ├─ 是 → 用 webfetch 获取子链接内容（深度 1）
  │   │     └─ 判断是否需要继续（深度 2）→ 选择性继续
  │   └─ 否 → 跳过
  │
  ▼
整合所有来源的信息到回答
  │
  ▼
在回答中标注每层来源

正确（论坛问答场景）：

用户："Python 的 asyncio 中怎么限制并发数？"

步骤 1：先用 websearch 搜索，找到 Stack Overflow 回答
步骤 2：webfetch 获取 SO 回答内容
步骤 3：扫描内容，发现回答者贴了 GitHub 链接：
  "参考这个实现 https://github.com/example/async-semaphore"
步骤 4：webfetch 获取该 GitHub 仓库的源代码
步骤 5：整合 SO 回答 + GitHub 代码到最终回答

错误：

用户问技术问题
  → 找到一篇博客
  → 博客里写 "详见 https://github.com/xxx"
  → 跳过子链接，只摘录博客内容
  → 错过关键实现细节

5. GitHub / 代码托管仓库查询规范

当引用指向 GitHub 或其他代码托管仓库时，优先获取仓库的实际代码内容而非仅 README 摘要。

5.1 查询优先级

按以下优先级获取仓库信息：

1. 源代码文件（尤其是实现核心功能的 .py / .js / .rs / .go 等文件）
2. README / 文档（了解项目用途和基本用法）
3. Issue / PR（了解已知问题、讨论、设计决策）
4. Release / Changelog（了解版本变更和迁移指南）

5.2 GitHub 原始内容获取

对于 GitHub 上的文件，使用以下方式获取内容：

5.3 多源验证

如果同一个功能有多个相关仓库或实现，至少查询 2 个来源进行对比验证：

• 场景 A：用户问"哪个库最好" → 查 2-3 个候选库对比
• 场景 B：用户问"怎么实现 X" → 查官方文档 + 1 个社区实现
• 场景 C：用户问"这个 API 怎么用" → 查官方文档 + 1 个真实项目示例

5.4 GitHub Issue 调研规范

调研 GitHub Issue（回答已知问题、讨论、设计决策）时，禁止只凭标题或搜索结果摘要引用，按以下流程核实：

5.4.1 读取 body 与全部 comments

使用 gh issue view <n> --json body,comments（或 gh api）读取正文与全部评论，重点阅读维护者/自动代理的关闭说明与修复 commit 证据。引用时必须区分「完整读过 body+comments」与「仅标题/搜索结果」两种深度，不得混同。

5.4.2 核实 closed 状态的关闭原因

closed ≠ 已解决。通过 timeline 查询关闭事件（gh api repos/<owner>/<repo>/issues/<n>/timeline），区分三种情况：

• fixed：关闭说明含修复 commit（形如 fe91698），须验证 commit 存在且确实对应问题
• duplicate：指向另一 issue，必须追踪原 issue 核实
• wontfix / 其他：未解决，引用时如实说明

5.4.3 默认 3 个月时效窗口

引用 issue 的创建与讨论时间应在 3 个月内；超过窗口的标注时效风险（如「创建于 X 月，注意时效」）。用户明确指定时效窗口时以用户要求为准。

5.4.4 追踪关闭后的 cross-reference

closed 后的 cross-referenced 事件可能是新问题、回归或无关引用——逐条判断，closed 不代表问题永不复发。若发现相关的新 issue，一并纳入调研。

5.4.5 空评论不构成停止信号

读取 issue 时 comments 为空不代表无后续活动。必须查询 timeline 与 closedByPullRequestsReferences，以发现 bot 自动关联、cross-reference、状态变更等不体现在评论中的事件。

5.4.6 禁止以查询字段边界代替来源边界

gh issue view --json body,comments 只返回正文与评论两个字段，不得据此判定「已读完 issue」。读取来源前先定义「完整视图」所需字段清单，逐项获取后再下结论。

正确：

# 完整读取 body + 全部评论
gh issue view <issue-number> --json body,comments
# 核对关闭原因与修复 commit
gh api repos/<owner>/<repo>/issues/<issue-number>/timeline \
  --jq '.[] | select(.event == "closed")'

错误：

# 只取标题即引用——无法判断 closed 是 fixed、duplicate 还是 wontfix
gh issue view <issue-number> --json title

6. 引用信息的整合与输出规范

6.1 来源标注

在回答中引用外部信息时，必须在引用处标注来源 URL，而不是仅在末尾汇总。

正确：

根据 [Vite 插件 API 文档](https://vitejs.dev/guide/api-plugin.html)，
`transform` 钩子的执行顺序在 `resolveId` 之后。

错误：

根据 Vite 官方文档，`transform` 钩子在 `resolveId` 之后执行。
<!-- 未提供 URL，用户无法验证 -->

6.2 信息可信度标注

当引用的信息来源存在以下情况时，必须在回答中明确标注风险：

6.3 多来源汇总格式

当追踪了多个链接时，在回答末尾用 ### 信息来源 小节汇总所有引用。

### 信息来源
- [Vite 插件 API 文档](https://vitejs.dev/guide/api-plugin.html) — 主引用，钩子定义
- [rollup-plugin-vue 源码](https://github.com/example/rollup-plugin-vue/blob/main/src/index.ts) — 子链接（来自 SO 回答），代码示例
- [Stack Overflow #12345](https://stackoverflow.com/questions/12345) — 子链接，社区实践讨论

6.4 引用内容的剪裁原则

• 只摘录与用户问题直接相关的部分，不粘贴整篇文档
• 如果仓库代码较长，用 // ... 关键部分 ... 省略无关代码，保留核心逻辑
• 多来源信息有冲突时，如实列出差异，不做"合成式"的平滑处理

7. 安全边界与效率约束

7.1 查询数量限制

超过上限时：优先选择与用户问题最相关的链接，舍弃边缘链接。

7.2 避免死循环

• 维护一个已访问 URL 列表，新链接查询前先检查是否已访问过
• 不追踪以下类型的链接：
  • 纯导航链接（"首页"、"返回"、"上一页"）
  • 社交媒体链接（Twitter/X、LinkedIn、Reddit 帖子）
  • 明显的广告/追踪链接（含 utm_、ref=、sponsored）
  • 登录/付费墙后的页面
  • 与当前技术查询领域无关的链接

7.3 时效性考量

• 优先查询近 1 年内发布的内容
• 如果内容超过 2 年，标注过期风险
• 如果用户问的是"最新版本"的用法，设置时间过滤器优先选新内容
• 对于长期稳定的基础技术（如 POSIX API、C 语言标准），时效性要求可放宽

context7 时效性专项规则

context7 的缓存滞后窗口取决于库的流行度，你在使用时必须意识到这个滞后：

7.4 语境时效性（API/版本语义匹配）

引用 issue/PR/文档作为归因或证据时，除检查时间新旧（§7.3）外，必须核实其语义语境与当前讨论对象匹配：

1. API 版本匹配：issue 描述的 API（如 registerLayer）必须与当前讨论的版本一致；API 被重命名/移除后，旧 API 的 issue 不能作为新 API 行为的归因依据
2. 分支/通道匹配：issue 基于的分支（v2 / dev / next）与讨论对象一致——同一问题在不同通道行为可能不同
3. 验证方法：引用前读 issue 的 Environment 段（版本号 / API 调用示例）比对；必要时查当前分支源码确认该 API 仍存在

反例：用描述旧 API（registerLayer）的 issue 归因新 API（keymap.layer）的命令不显示问题——API 语境不匹配，归因错误。

7.5 成本意识

• 能用 1 次查询解决的问题，不用 3 次
• 先评估问题复杂度：简单 API 用法 → 1 次官方文档查询即可；复杂系统设计 → 需要多源追踪
• 子链接追踪前先问自己："这个子链接的信息会显著改变我的回答质量吗？"——如果不会，跳过

8. 禁止事项

• 禁止仅凭训练数据中的记忆给出引用，而不做实时验证
• 禁止伪造引用来源（编造不存在的 URL 或不存在的仓库）
• 禁止在子链接追踪中无限递归或超过深度 2 的限制
• 禁止引用与用户问题上下文无关的内容
• 禁止在获取到真实的最新内容后，仍然输出训练数据中的过时信息
• 禁止对多个冲突来源做"平滑合成"——必须如实列出差异
• 禁止在用户未要求的情况下，查询与问题无关的仓库或项目（保持回答聚焦）
• 禁止将付费墙后的内容作为引用来源（无法验证）
• 禁止追踪到的内容不做消化就直接丢给用户——必须分析、总结、整合

9. 自检要求

输出前请逐项自检：

• 是否对所有外部引用进行了实时网络验证，而非凭记忆输出？
• 获取的主内容中是否包含需要追踪的子链接（论坛回答链接、参考链接等）？
• 如果追踪了子链接，深度是否 ≤ 2？
• 所有引用是否标注了可访问的 URL 来源？
• 存在过时风险的引用是否标注了时间信息和风险警示？
• 存在多来源冲突时是否如实列出差异而非平滑合成？
• 引用信息是否经过分析整合，而非原样粘贴？
• 查询数量是否在合理范围（2-4 个为宜，不超过 6 个）？
• 是否避免了死循环（无重复 URL、无导航/社交链接追踪）？
• 引用的 GitHub Issue 是否读取了 body + 全部 comments（非仅标题）？
• 引用的 closed issue 是否核实了关闭原因（fixed / duplicate / wontfix）与修复 commit？
• 引用是否在 3 个月时效窗口内（超期已标注时效风险）？
• 是否追踪了 closed 后的 cross-reference（新问题 / 回归 / 无关引用）？
• 是否标注了每篇 issue 引用的查看深度（全文 / 标题级）？
• 引用 issue 作为归因/证据时，是否核实了其 API 语境与当前版本匹配（旧 API issue 未误归因新 API）？
• context7 专项检查：
  • 是否检查了 resolve-library-id 返回的 Code Snippets 数量？
  • Code Snippets < 100 时是否降级到了 websearch？
  • resolve-library-id 返回空时是否跳过了 context7？
  • 用户问最新版本/新特性时是否跳过了 context7？

如有任何一项未通过，修正后再输出。