fix: retry thinking-only empty outputs, centralize reference marker stripping

- ValidateTurn no longer errors on thinking-only responses, deferring to
  ShouldRetryEmptyOutput which now also covers thinking-only outputs.
- Empty output retry uses multi-turn follow-up with a regeneration prompt
  suffix and parent_message_id in the same DeepSeek session.
- Centralize StripReferenceMarkersEnabled into textclean package to
  eliminate duplicated hardcoded booleans across 4 protocol handlers.
- Log a deprecation warning when the legacy "compat" config key is used.
- Document thinking-only retry and reference marker stripping in API.md.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

API.md

@@ -41,6 +41,8 @@
 - 适配器层职责收敛为：**请求归一化 → DeepSeek 调用 → 协议形态渲染**，减少历史版本中“同能力多处实现”的分叉。
 - Tool Calling 的解析策略在 Go 与 Node Runtime 间保持一致：推荐模型输出 DSML 外壳 `<|DSML|tool_calls>` → `<|DSML|invoke name="...">` → `<|DSML|parameter name="...">`；兼容层也接受 DSML wrapper 别名 `<dsml|tool_calls>`、`<|tool_calls>`、`<｜tool_calls>`、常见 DSML 分隔符漏写形态（如 `<|DSML tool_calls>`）、`DSML` 与工具标签名黏连的常见 typo（如 `<DSMLtool_calls>`），以及旧式 canonical XML `<tool_calls>` → `<invoke name="...">` → `<parameter name="...">`。实现上采用窄容错结构扫描：只有 `tool_calls` wrapper 或可修复的缺失 opening wrapper 会进入工具路径，裸 `<invoke>` 不计为已支持语法；流式场景继续执行防泄漏筛分。若参数体本身是合法 JSON 字面量（如 `123`、`true`、`null`、数组或对象），会按结构化值输出，不再一律当作字符串；若 CDATA 偶发漏闭合，则会在最终 parse / flush 恢复阶段做窄修复，尽量保住已完整包裹的外层工具调用。
 - `Admin API` 将配置与运行时策略分开：`/admin/config*` 管静态配置，`/admin/settings*` 管运行时行为。
+- 当上游返回 thinking-only 响应（模型输出了推理链但无可见文本）时，非流式补全会自动重试一次：以多轮对话 follow-up 方式追加 prompt 后缀 `"Previous reply had no visible output. Please regenerate the visible final answer or tool call now."` 并设置 `parent_message_id` 在同一 DeepSeek session 内让模型重新输出；重试最大 1 次。
+- 引用标记剥离（strip reference markers）当前为固定开启的运行时行为，所有协议适配层统一生效。
 
 ---
 

internal/assistantturn/turn.go

@@ -206,6 +206,11 @@ func ValidateTurn(turn Turn, policy promptcompat.ToolChoicePolicy) *OutputError
 	if strings.TrimSpace(turn.Text) != "" {
 		return nil
 	}
+	// Thinking-only with no visible text is not an immediate error;
+	// the caller should retry via ShouldRetryEmptyOutput first.
+	if strings.TrimSpace(turn.Thinking) != "" {
+		return nil
+	}
 	status, message, code := UpstreamEmptyOutputDetail(turn.ContentFilter, turn.Text, turn.Thinking)
 	return &OutputError{Status: status, Message: message, Code: code}
 }
@@ -221,12 +226,14 @@ func UpstreamEmptyOutputDetail(contentFilter bool, text, thinking string) (int,
 	return http.StatusTooManyRequests, "Upstream account hit a rate limit and returned empty output.", "upstream_empty_output"
 }
 
+// ShouldRetryEmptyOutput returns true when the turn produced no visible text
+// and has no tool calls or content filter. This includes thinking-only responses,
+// where the model returned reasoning but no answer — a retry may yield text.
 func ShouldRetryEmptyOutput(turn Turn, attempts, maxAttempts int) bool {
 	return attempts < maxAttempts &&
 		!turn.ContentFilter &&
 		len(turn.ToolCalls) == 0 &&
-		strings.TrimSpace(turn.Text) == "" &&
-		strings.TrimSpace(turn.Thinking) == ""
+		strings.TrimSpace(turn.Text) == ""
 }
 
 func FinalizeTurn(turn Turn, opts FinalizeOptions) FinalOutcome {

internal/config/codec.go

@@ -98,6 +98,9 @@ func (c *Config) UnmarshalJSON(b []byte) error {
 			}
 		case "compat":
 			// Removed field ignored instead of persisted.
+			if Logger != nil {
+				Logger.Warn("config key \"compat\" is deprecated and ignored; remove it from your configuration")
+			}
 		case "toolcall":
 			// Legacy field ignored. Toolcall policy is fixed and no longer configurable.
 		case "responses":

internal/httpapi/claude/handler_routes.go

@@ -8,6 +8,7 @@ import (
 
 	"ds2api/internal/config"
 	dsprotocol "ds2api/internal/deepseek/protocol"
+	"ds2api/internal/textclean"
 	"ds2api/internal/util"
 )
 
@@ -22,7 +23,7 @@ type Handler struct {
 }
 
 func stripReferenceMarkersEnabled() bool {
-	return true
+	return textclean.StripReferenceMarkersEnabled()
 }
 
 var (

internal/httpapi/gemini/handler_routes.go

@@ -5,6 +5,7 @@ import (
 
 	"github.com/go-chi/chi/v5"
 
+	"ds2api/internal/textclean"
 	"ds2api/internal/util"
 )
 
@@ -19,7 +20,7 @@ type Handler struct {
 
 //nolint:unused // used by native Gemini stream/non-stream runtime helpers.
 func stripReferenceMarkersEnabled() bool {
-	return true
+	return textclean.StripReferenceMarkersEnabled()
 }
 
 func RegisterRoutes(r chi.Router, h *Handler) {

internal/httpapi/openai/chat/handler.go

@@ -12,6 +12,7 @@ import (
 	"ds2api/internal/httpapi/openai/history"
 	"ds2api/internal/httpapi/openai/shared"
 	"ds2api/internal/promptcompat"
+	"ds2api/internal/textclean"
 	"ds2api/internal/toolcall"
 	"ds2api/internal/toolstream"
 )
@@ -36,7 +37,7 @@ type streamLease struct {
 }
 
 func stripReferenceMarkersEnabled() bool {
-	return true
+	return textclean.StripReferenceMarkersEnabled()
 }
 
 func (h *Handler) applyCurrentInputFile(ctx context.Context, a *auth.RequestAuth, stdReq promptcompat.StandardRequest) (promptcompat.StandardRequest, error) {

internal/httpapi/openai/responses/handler.go

@@ -11,6 +11,7 @@ import (
 	"ds2api/internal/httpapi/openai/history"
 	"ds2api/internal/httpapi/openai/shared"
 	"ds2api/internal/promptcompat"
+	"ds2api/internal/textclean"
 	"ds2api/internal/toolstream"
 )
 
@@ -29,7 +30,7 @@ type Handler struct {
 }
 
 func stripReferenceMarkersEnabled() bool {
-	return true
+	return textclean.StripReferenceMarkersEnabled()
 }
 
 func (h *Handler) applyCurrentInputFile(ctx context.Context, a *auth.RequestAuth, stdReq promptcompat.StandardRequest) (promptcompat.StandardRequest, error) {

internal/textclean/reference_markers.go

@@ -10,3 +10,11 @@ func StripReferenceMarkers(text string) string {
 	}
 	return referenceMarkerPattern.ReplaceAllString(text, "")
 }
+
+// StripReferenceMarkersEnabled returns true while reference-marker
+// stripping remains the fixed runtime default.  When the behaviour is
+// eventually removed this function can be deleted and callers can drop
+// the conditional.
+func StripReferenceMarkersEnabled() bool {
+	return true
+}