# ADR-0001: 引文 = 注入上下文（而非写进用户消息正文）

- 状态：已采纳
- 日期：2026
- 涉及：dsh-quote（引文注入工具）

## 背景

最初的极简设想是"把选中的文字块随用户消息一起发出去"。但用户明确：**引用的文字块应当注入到上下文中，而不是直接拼进 user 消息正文**。二者的差异看似微小，实则决定了整套架构：

- 若**拼进 user 消息**：引文混入用户自己的问题文本，模型难以区分"这是用户引用的旧内容"与"这是用户新写的意图"，追问时引用与被追问对象边界模糊；且纯 client 即可实现。
- 若**作为注入上下文**：用户消息保持干净，引文作为模型可读的独立上下文与问题并行喂入，语义清晰、贴合"基于这段继续提问"的意图。

## 决策

**引文 = 注入上下文，与用户消息分离，用完即走（一次性）。**

1. **语义**：划选 → 右键「引用到对话」→ 该会话登记一条**待生效引用** → 只在**下一次真实带用户文字**的回合，作为一条带插件来源的注入上下文喂给模型 → 随即清除。不进用户消息正文。
2. **架构（双面 host + client，由 DSH 硬约束决定）**：
   - **client 半端**：捕获选区文本 + 解析来源 messageId，经自有 cordis service 方法把待生效引用交给 host。
   - **host 半端**：为每个会话维护待生效引用队列；在 `agent/pre-step` 把待生效引用折叠为注入上下文（mirror 官方 `agent-instructions` 注入 `<system-reminder>` 的做法），只跟随真实用户回合，注入后清空。
3. **注入方式用 host `agent/pre-step` 折叠，而非 `systemPrompt.section` 等静态/常驻段**——因为引用是一次性、用完即走的动态内容，不是常驻系统提示。

## 备选方案与取舍

| 方案 | 结论 | 理由 |
|---|---|---|
| 引文拼进 user 消息正文 | 拒绝 | 污染用户问题文本，引用与追问边界模糊 |
| 纯 client 实现 | 拒绝（不可行） | DSH 无客户端上下文缓冲：浏览器端没有任何把内容写进模型上下文的 RPC/通道；"注入上下文"只能由 host 在 `agent/pre-step` 做 |
| 常驻/持久注入（systemPrompt.section 或跨会话持久） | 拒绝 | 引用是一次性、用完即走，无需常驻；保持最简 |
| 接入 dsh-codex-project 等现有插件 | 拒绝 | 语义无关（共享目录 vs 引文注入），无共享地基，独立成仓 |

## 依据

- 用户明确需求："引用的文字块应注入上下文，而非直接加在 user 消息中"；
- DSH 架构约束：浏览器端不能自行注入模型上下文，持久/一次性注入均须由 host 端在 `agent/pre-step` 折叠；
- 对齐官方 `agent-instructions` 的注入先例。

## 影响

- 插件为 **host + client 双面包**（独立 `dsh-quote` 仓库），client bundle + host half；
- host 端需为会话维护"待生效引用"队列 + `agent/pre-step` 一次性折叠逻辑；
- 引文在用户消息旁作为注入上下文呈现，二者分离；
- 此取舍不可逆（决定整体架构），故以 ADR 记录。