From 75910f2167280e18546b9e3a5f5884c00afff2bd Mon Sep 17 00:00:00 2001
From: Louis <8515500@gmail.com>
Date: Wed, 13 May 2026 12:28:07 +0800
Subject: [PATCH] docs: add context strategy acceptance guide

---
 docs/README.md                    |  2 +
 docs/context-engine-strategies.md | 88 +++++++++++++++++++++++++++++++
 docs/prompt-compatibility.md      |  2 +-
 3 files changed, 91 insertions(+), 1 deletion(-)
 create mode 100644 docs/context-engine-strategies.md

diff --git a/docs/README.md b/docs/README.md
index e999f661d..378c7a463 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -18,6 +18,7 @@
 
 - [DS2API 项目价值说明](./project-value.md)
 - [API -> 网页对话纯文本兼容主链路说明](./prompt-compatibility.md)
+- [Context Engine 策略验收说明](./context-engine-strategies.md)
 - [Tool Calling 统一语义](./toolcall-semantics.md)
 - [DeepSeek SSE 行为结构说明（逆向观察）](./DeepSeekSSE行为结构说明-2026-04-05.md)
 
@@ -64,6 +65,7 @@ Recommended reading order:
 
 - [DS2API project value note](./project-value.md)
 - [API -> pure-text web-chat compatibility pipeline](./prompt-compatibility.md)
+- [Context Engine strategy acceptance guide](./context-engine-strategies.md)
 - [Tool-calling unified semantics](./toolcall-semantics.md)
 - [DeepSeek SSE behavior notes (reverse-engineered)](./DeepSeekSSE行为结构说明-2026-04-05.md)
 
diff --git a/docs/context-engine-strategies.md b/docs/context-engine-strategies.md
new file mode 100644
index 000000000..bb7ed1325
--- /dev/null
+++ b/docs/context-engine-strategies.md
@@ -0,0 +1,88 @@
+# Context Engine 策略验收说明
+
+本文定义 `context_engine.strategy` 的可见输出、适用场景、回滚方式和测试口径。它补充 `docs/prompt-compatibility.md`，用于后续开发和发布验收。
+
+## 目标
+
+Context Engine 的目标不是伪装网页聊天记录，而是把 API 会话编译成模型更容易理解的当前任务上下文：
+
+- 短上下文保持 inline，不上传生成文件。
+- 长上下文上传中性的 conversation context / tool reference。
+- 模型默认不看到 DS2API 内部文件名或实现术语。
+- 最近上下文尽量无损，较早历史做语义压缩。
+- 所有策略都必须可解释、可测试、可回滚。
+
+## 策略矩阵
+
+| strategy | 输出形态 | 默认使用 | 适用场景 | 回滚价值 |
+|---|---|---:|---|---|
+| `raw_transcript` | 旧式 `# DS2API_HISTORY.txt` + `=== N. ROLE ===` transcript | 否 | 调试、回归、兼容旧行为 | 最高，保留旧形态 |
+| `natural_context` | `# Conversation Context` + 全量自然化轮次 | 否 | 需要完整历史但不想暴露实现术语 | 从压缩策略回退到全文 |
+| `context_capsule` | 当前任务 + 约束 + 早期摘要，不回放最近完整轮次 | 否 | 普通问答、长历史摘要 | 降低上下文体积 |
+| `hybrid_recent` | 当前任务 + 约束 + 早期摘要 + 最近精确上下文 | 是 | Agent 长任务、编程、调试 | 默认生产策略 |
+| `auto` | 自动选择上述策略 | 暂未实现 | 后续按请求形态选择 | 灰度入口 |
+
+## 默认策略：hybrid_recent
+
+`hybrid_recent` 必须包含：
+
+- `# Conversation Context`
+- `## Current Task`：最新 user turn 原文。
+- `## Non-Negotiable Instructions`：system / developer 等不可压缩约束的摘要。
+- `## Earlier Context Summary`：较早历史的短摘要；内容可以压缩，但不能引入新事实。
+- `## Recent Exact Context`：最近上下文无损保留，包含 tool call / tool result / assistant reasoning 的可见结构。
+
+验收要点：
+
+- 最新用户请求必须完整出现。
+- system / developer 约束必须出现，允许一行化但不能丢失。
+- 早期历史不得以大段原始 transcript 全量回放。
+- 最近精确上下文必须保留角色、顺序和工具链关系。
+- 默认输出不得包含 `DS2API_HISTORY.txt` 或 `DS2API_TOOLS.txt`。
+
+## 压缩安全边界
+
+以下内容不应被语义摘要改写，只能保留原文、结构化摘录，或在长度过大时做可解释裁剪：
+
+- 最新用户请求。
+- system / developer 指令。
+- 最近 tool call / tool result 链。
+- 失败测试日志中的错误类型、文件路径、行号、actual / expected。
+- 当前 diff / patch 的关键片段。
+- 用户明确的禁止项、偏好和验收条件。
+- 文件路径、函数名、配置键、环境变量名。
+
+## 回滚矩阵
+
+| 风险 | 建议回滚 |
+|---|---|
+| `hybrid_recent` 摘要遗漏关键背景 | `context_engine.strategy=natural_context` |
+| 自然化正文导致模型误判 | `context_engine.strategy=raw_transcript` |
+| 生成附件机制异常 | `current_input_file.enabled=false` |
+| 客户端或上游依赖旧文件名 | `current_input_file.filename_policy=legacy` |
+| 短上下文误触发上传 | 调大 `current_input_file.inline_max_tokens` |
+| 长上下文没有触发上传 | 调小 `current_input_file.inline_max_tokens` 或检查 `current_input_file.enabled` |
+
+## 测试口径
+
+每次修改 Context Engine 策略、current input file 渲染、工具引用正文或 token accounting 时，至少运行：
+
+```bash
+go test ./internal/config ./internal/promptcompat ./internal/httpapi/openai/history
+go test ./internal/httpapi/openai/... ./internal/httpapi/claude ./internal/httpapi/gemini ./internal/completionruntime
+./tests/scripts/run-unit-all.sh
+```
+
+PR Gate 仍以仓库根目录 `AGENTS.md` 为准。
+
+## 后续扩展
+
+`auto` 策略应在实现时输出可观测的选择原因，例如：
+
+- message count
+- tool result count
+- latest request length
+- code block / file path / test failure signals
+- selected strategy
+
+这些字段应进入 completion request 日志和后续 Admin/History 观测页。
diff --git a/docs/prompt-compatibility.md b/docs/prompt-compatibility.md
index 2041f5d45..a17e2d89e 100644
--- a/docs/prompt-compatibility.md
+++ b/docs/prompt-compatibility.md
@@ -496,7 +496,7 @@ promptcompat.NormalizeOpenAIMessagesForPrompt()
 
 > `shadow` 仅用于显式诊断和回归观察；默认运行路径使用 `enforce`。
 
-`context_engine.strategy` 用于选择上下文渲染策略，合法值为 `raw_transcript`、`natural_context`、`context_capsule`、`hybrid_recent`、`auto`，默认 `hybrid_recent`；环境变量 `DS2API_CONTEXT_ENGINE_STRATEGY` 可覆盖配置文件。`raw_transcript` 保留旧式按轮次 transcript，`natural_context` 输出更接近日常对话材料的上下文全文，`context_capsule` 输出任务胶囊，`hybrid_recent` 保留最近上下文并压缩较早历史，`auto` 预留给后续按请求形态自动选择策略。
+`context_engine.strategy` 用于选择上下文渲染策略，合法值为 `raw_transcript`、`natural_context`、`context_capsule`、`hybrid_recent`、`auto`，默认 `hybrid_recent`；环境变量 `DS2API_CONTEXT_ENGINE_STRATEGY` 可覆盖配置文件。`raw_transcript` 保留旧式按轮次 transcript，`natural_context` 输出更接近日常对话材料的上下文全文，`context_capsule` 输出任务胶囊，`hybrid_recent` 保留最近上下文并压缩较早历史，`auto` 预留给后续按请求形态自动选择策略。策略验收标准见 [Context Engine 策略验收说明](./context-engine-strategies.md)。
 
 ### Shadow 模式日志字段