docs: 调研分支引用消息、来源回跳与缓存边界

[hifizz]

概要

本 PR 严格基于 codex/feat-agent-observability-evaluation@48483101ad11bc84b611b615f423577633fedacb，新增一篇面向产品经理和方案决策者的 Research 调研文档：

• docs/thread-reference/01-research.md

研究问题是：用户在 Thread A 划选 AI 回复、输入问题并创建 Thread B 后，B 的第一条用户消息应该怎样携带引用和来源信息，如何点击回到 A 的原 Message 并高亮，同时如何避免具体引用提前进入 System Prompt、破坏分叉前共同历史缓存。

核心结论

推荐将 B1 设计为一条包含两类内容的用户消息：

B1
├── 引用卡片：引用原文 + 产品内部来源信息
└── 用户问题：用户在弹窗中输入的内容

职责边界：

• 模型只看到引用原文和用户问题；
• 产品内部保存来源 Thread、来源 Message、文字锚点和格式版本；
• 来源信息由服务端根据已经验证的分支关系生成，不能完全信任客户端；
• Thread 的 fork* 字段仍是分支拓扑的权威来源，B1 引用是创建时的不可变引用快照；
• 具体引用不再进入 System Prompt，System 只保留稳定的“如何理解引用”规则；
• 模型输入排列为“固定规则 → A 的共同历史 → B1 引用 → B1 问题”，从而保护共同前缀缓存。

调研内容

文档按照 Research skill 的方式组织，包含：

• 用户目标、工程目标和可验证成功标准；
• 非代码方案与必要性判断；
• 当前代码基线和 Gap；
• 可直接复用、可扩展和缺失的能力；
• 四种候选方案及取舍；
• 推荐机制的非技术解释；
• 来源正常、历史版本、归档、删除或无权限时的表现；
• 编辑、重试、刷新和空分支路径；
• 对 Prompt Cache 的影响和边界；
• 关键风险、五个最小验证实验；
• 后续 Spec/Implement 阶段需要用户或工程师拍板的决策点；
• 未解决的不确定性和建议的 Spec 顺序。

代码基线发现

当前项目已经具备大部分基础：

• 划选时能够取得来源 Thread、来源 Message 和可持久化文字锚点；
• Thread 已保存并验证分支来源；
• UIMessage 已定义 data-quote；
• 用户消息 UI 和模型上下文转换已经识别引用；
• 现有 Markdown 高亮链路已实现位置、准确文本和模糊定位。

当前主要缺口是：创建 B1 时仍只写普通问题文本，而具体 anchorText 仍被拼入 System Prompt，已有能力尚未连接成完整引用链路。

范围边界

这是 Research 文档 PR：

• 不修改业务代码；
• 不修改数据库和 API；
• 不提交详细字段接口或迁移方案；
• 不实施跨 Project 引用、多模态引用或完整 @Thread；
• 不承诺任意模型线路百分之百命中缓存。

依据

• 当前仓库相关 Thread Chat、UIMessage、文字锚点、分支创建和模型上下文代码；
• W3C Web Annotation Data Model；
• AI SDK 官方 UIMessage、Data Parts、Message Metadata 和 convertToModelMessages 文档；
• OpenAI 官方 Prompt Caching 与 Codex Agent Loop 的共同前缀说明。

核验

• Base branch：codex/feat-agent-observability-evaluation
• Base SHA：48483101ad11bc84b611b615f423577633fedacb
• Head branch：codex/research-thread-quote-provenance
• Commit：5e2c36d7a75131111bb3d26137a50efc0dfeac74
• 相对基线前进 1 个提交；
• 只新增 docs/thread-reference/01-research.md；
• 无运行时代码变更，因此未执行 typecheck/build；以 GitHub PR 状态作为远端校验。

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
thread-chatbot	Error		Aug 29, 2026 9:06pm

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 691ce2b6-0730-480b-857a-56bd1a83a5ea

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}