docs(openspec): 收紧当前 Thread 引用并定义低成本 Prompt Cache 架构

[hifizz]

概要

本 PR 基于：

• Base：codex/feat-agent-observability-evaluation@2f3024747ddb72e1e69aa916cb45addb7140f6ab
• Head：codex/design-thread-chat-prompt-cache@7561193844f5364f74ac071ae8379dada8a9ef84

本轮进一步收紧了 Quote 范围：v1 不支持任意跨 Thread、跨分栏或 @Thread 引用。

统一流程只覆盖：

1. 父 Thread 划选 -> 开新分支
2. 当前 Thread 划选 -> 当前 Thread Composer
3. 当前 Thread Markdown Artifact 批量批注 -> Artifact 来源 Thread Composer

Fork 的父 Thread 选区会自动成为新 Thread 第一轮的 branch-origin Quote。它是 Fork 拓扑的服务端派生数据，不代表系统支持把任意 Thread 内容加入另一个 Thread。

已确认产品决定

• 新 Quote 来源只允许 completed assistant Message；generating / stopped / failed 全部禁止。
• 每条用户 Message 最多支持 50 个 Quote。
• 50 是块数量上限；正式模型调用前仍执行模型 Route 相关的 Quote/Input Budget 预检。
• 普通 Quote 只允许来自目标 Composer 所属当前 Thread。
• 客户端 Command 不提交 sourceThreadId；服务端加载来源实体并验证它属于目标 Thread。
• 任意跨 Thread、跨分栏、跨 Project 和 @Thread 引用留到独立 change。
• 划选后弹窗不输入问题：只创建新 Thread，不创建 B1/BA1，不调用模型；branch-origin Quote Block 显示在新 Thread Composer。
• 当前 Thread 划选可加入当前输入框，不自动发送。
• Markdown Artifact 批量批注只能回填 Artifact 来源 Message 所属 Thread 的 Composer；一次发送只触发一次 AI 回复。

缓存与 Claude 成本目标

缓存与模型线路不再要求用户做技术选择，统一采用：

回答质量、工具行为、安全与终态不变差时，选择经过验证的最低真实总成本方案。

真实总成本包括：

未缓存输入
缓存写入
缓存读取
输出
Gateway / Relay 费用
路由漂移导致的缓存失效

• 第一条 Claude Probe 使用当前实际存在的 UMAPIS Claude Route。
• 如果不能证明缓存透传、cache Usage 和净成本下降，则保持关闭，不猜测已经省钱。
• 有 Anthropic 直连凭据时可作参考实验，不要求生产立即切换。
• 第一阶段使用 Provider 默认短时缓存；支持时按约 5 分钟验证。
• 1 小时 Extended TTL 默认关闭，只有真实会话间隔和读写费用证明更便宜且通过数据保留检查后才启用。
• 任何便宜方案只要导致质量、引用理解、工具、安全或终态回归，就不得启用。

目标 Prompt 顺序

稳定 Tool Profile
稳定 Agent Kernel
可选 Project Contract
冻结祖先历史
已完成分支历史
---------------- 缓存边界 ----------------
本轮 Runtime Control
Current User：Quote × 0..50 + comment + Text? + File*

具体 Quote 正文位于当前 User；具体 Anchor 不再进入前置 System Prompt。

以下信息永远不发送给模型：

quoteId / kind
Project / Thread / Message / Artifact ID
TextAnchor
标题 / 脚注 / 列位置
Draft / Command / Request / Trace ID

三个 OpenSpec Capability

specs/
├── thread-chat-message-quotes/spec.md
├── thread-chat-quote-composer/spec.md
└── thread-chat-prompt-cache/spec.md

thread-chat-message-quotes

定义：

• 当前 Thread Message / Artifact 两类普通 Quote 来源；
• Fork 自动 branch-origin 唯一父 Thread 来源例外；
• thread-quote-v1 Parts；
• completed-only 授权；
• 50 Quote 与模型输入预算；
• Edit/Retry/Legacy；
• Quote-to-model 只发送正文与 comment。

thread-chat-quote-composer

定义：

• 空问题开分支后 Quote Block 进入新 Thread Composer；
• 当前 Thread 内引用；
• 明确禁止任意跨 Thread、跨分栏和 @Thread；
• required branch-origin；
• 多引用去重、排序、删除；
• 当前 Thread Markdown 批量批注；
• Draft 发送前不创建 Message、不调用模型；
• 一次 Draft 只形成一条 User Message 和一次 assistant attempt。

具体 React 组件、富文本技术、视觉样式、拖拽、来源跳转和 Draft 持久化留到下一阶段前端 Research。

thread-chat-prompt-cache

定义：

1. 稳定前缀；
2. 动态尾部；
3. 非模型元信息；
4. 主动缓存分区；
5. Prompt Compiler 与 Prefix Hash；
6. Tool Profile 与实际模型 Route；
7. Claude 短缓存 Probe；
8. 质量硬门禁和真实总成本比较；
9. cache read/write、TTFT、实际成本与 Agent Eval；
10. off / observe / enabled 渐进发布。

数据与后端合同

• MessageSelectionInput 只提交 sourceMessageId + TextAnchor。
• ArtifactSelectionInput 只提交 artifactId + TextAnchor。
• 服务端从目标 Thread 和来源实体推导真实 Project/Thread ID。
• messages.parts JSONB 继续是 Quote Snapshot 的唯一事实源。
• threads Fork 字段继续是分支拓扑事实。
• 第一阶段不新增 Quote 表、不增加顶层 MessageDTO.quotes、不执行数据库迁移。
• quoteContentToModelText() / quoteTextToModelText() 使用版本化确定性 JSON 格式。
• compilePromptBase() + finalizeGenerationPrompt() 保护 inherited / branch history。
• ResolvedChatModel 暴露真实 Adapter、Gateway、upstream、routeId 与缓存能力。

文件

docs/prompt-cache/01-research.md
openspec/changes/optimize-thread-chat-prompt-cache/
├── .openspec.yaml
├── proposal.md
├── design.md
├── tasks.md
└── specs/
    ├── thread-chat-message-quotes/spec.md
    ├── thread-chat-quote-composer/spec.md
    └── thread-chat-prompt-cache/spec.md

范围边界

• 这是规划与合同 PR，不修改业务代码；
• 不执行数据库迁移；
• 不实现具体 Composer 前端；
• 不支持任意跨 Thread / @thread；
• 不承诺任意模型、任意代理或任意首次分叉 100% 命中；
• 缓存收益不得覆盖回答质量、安全、权限、终态和数据保留硬失败。

验证

• Head：7561193844f5364f74ac071ae8379dada8a9ef84
• OpenSpec strict validation：success
• PR 当前可合并；Vercel 状态与本规划文档改动无关，未据此推断部署失败原因。

[vercel]

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

Project	Deployment	Actions	Updated
thread-chatbot	Error		Sep 1, 2026 12:52am UTC

[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: Team

Run ID: fda879c2-1bee-4160-93b1-eb90c957fb78

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.}