fix(tui): 修复 /help 单页可选执行 + UTF-8 + 覆盖率修复

docs/context-compact.md

@@ -4,8 +4,8 @@
 
 ## 概览
 
-- runtime 当前仅接入手动触发的 compact，不包含自动 compact。
-- `internal/context/compact` 已支持 `manual` 与 `reactive` 两种 mode，供 runtime 后续在 provider 上下文过长错误场景接入调用。
+- runtime 已接入手动 compact、基于 token 阈值的自动 compact，以及 provider 上下文过长后的 `reactive` compact 自动恢复。
+- `internal/context/compact` 支持 `manual` 与 `reactive` 两种 mode。
 - 用户通过 `/compact` 对当前会话执行一次上下文压缩。
 - compact 前会先写入完整 transcript，随后生成并校验 compact summary，再回写会话消息。
 
@@ -69,7 +69,12 @@ context:
 3. 生成并校验 `[compact_summary]`。
 4. 返回压缩后的消息与 transcript 元信息。
 
-当前 runtime 主链尚未自动调用 `reactive` mode；后续接入时可继续复用现有 compact 事件，并通过 `trigger_mode=reactive` 区分。
+当 provider 返回“上下文过长”错误时，runtime 会：
+
+1. 识别 provider 归一化后的 typed error，必要时回退到错误文本匹配。
+2. 触发一次 `compact.Run(mode=reactive)`。
+3. 继续复用 `compact_start`、`compact_done`、`compact_error` 事件，并通过 `trigger_mode=reactive` 区分来源。
+4. 每次 `Run()` 最多只执行一次 reactive 重试，避免无限循环。
 
 ## 摘要协议
 
@@ -106,7 +111,7 @@ constraints:
 
 ## 事件
 
-manual compact 相关 runtime 事件包括：
+compact 相关 runtime 事件包括：
 
 - `compact_start`
 - `compact_done`

docs/runtime-provider-event-flow.md

@@ -10,6 +10,9 @@
 - `tool_result`
 - `error`
 - `token_usage`
+- `compact_start`
+- `compact_done`
+- `compact_error`
 
 ## ReAct 主循环
 
@@ -18,10 +21,12 @@
 3. 读取最新配置快照。
 4. 解析当前 provider 配置并构建 provider 实例。
 5. 调用 `context.Builder` 生成本轮请求使用的 `system prompt` 和消息上下文。
-6. 调用 `Provider.Chat`，并把流式事件桥接给 TUI。
-7. 保存 assistant 完整回复。
-8. 执行返回的工具调用，并保存每一个工具结果。
-9. 如果仍需继续推理，则进入下一轮；否则结束。
+6. 如命中 token 阈值自动压缩建议，则先执行一次 compact，再继续构造请求。
+7. 调用 `Provider.Chat`，并把流式事件桥接给 TUI。
+8. 如 provider 返回“上下文过长”错误，则触发一次 `reactive` compact，并仅重试一次当前请求。
+9. 保存 assistant 完整回复。
+10. 执行返回的工具调用，并保存每一个工具结果。
+11. 如果仍需继续推理，则进入下一轮；否则结束。
 
 ### Context Builder 输入与职责
 

internal/context/compact/runner.go

@@ -18,6 +18,8 @@ type Mode string
 const (
 	// ModeManual runs the explicit user-triggered compact flow.
 	ModeManual Mode = "manual"
+	// ModeAuto runs the token-threshold-triggered compact flow.
+	ModeAuto Mode = "auto"
 	// ModeReactive runs the provider-error-triggered compact flow.
 	ModeReactive Mode = "reactive"
 )
@@ -111,7 +113,7 @@ func (s *Service) Run(ctx context.Context, input Input) (Result, error) {
 		return Result{}, err
 	}
 
-	if input.Mode != ModeManual && input.Mode != ModeReactive {
+	if input.Mode != ModeManual && input.Mode != ModeAuto && input.Mode != ModeReactive {
 		return Result{}, fmt.Errorf("compact: unsupported mode %q", input.Mode)
 	}
 

internal/context/compact/runner_test.go

@@ -185,6 +185,54 @@ func TestReactiveCompactUsesKeepRecentAndReportsReactiveMode(t *testing.T) {
 	}
 }
 
+func TestAutoCompactUsesManualStrategyAndReportsAutoMode(t *testing.T) {
+	t.Parallel()
+
+	generator := &stubSummaryGenerator{summary: validSemanticSummary()}
+	runner := NewRunner(generator)
+	home := t.TempDir()
+	runner.userHomeDir = func() (string, error) { return home, nil }
+
+	messages := []providertypes.Message{
+		{Role: providertypes.RoleUser, Content: "old requirement"},
+		{Role: providertypes.RoleAssistant, Content: "old answer"},
+		{Role: providertypes.RoleUser, Content: "middle request"},
+		{Role: providertypes.RoleAssistant, Content: "middle answer"},
+		{Role: providertypes.RoleUser, Content: "recent request"},
+		{Role: providertypes.RoleAssistant, Content: "recent answer"},
+	}
+
+	result, err := runner.Run(context.Background(), Input{
+		Mode:      ModeAuto,
+		SessionID: "session-auto",
+		Workdir:   t.TempDir(),
+		Messages:  messages,
+		Config: config.CompactConfig{
+			ManualStrategy:           config.CompactManualStrategyKeepRecent,
+			ManualKeepRecentMessages: 4,
+			MaxSummaryChars:          1200,
+		},
+	})
+	if err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+	if !result.Applied {
+		t.Fatalf("expected auto compact applied")
+	}
+	if result.Metrics.TriggerMode != string(ModeAuto) {
+		t.Fatalf("expected trigger mode %q, got %q", ModeAuto, result.Metrics.TriggerMode)
+	}
+	if len(generator.calls) != 1 {
+		t.Fatalf("expected generator to run once, got %d", len(generator.calls))
+	}
+	if generator.calls[0].Mode != ModeAuto {
+		t.Fatalf("expected summary input mode %q, got %q", ModeAuto, generator.calls[0].Mode)
+	}
+	if generator.calls[0].Config.ManualStrategy != config.CompactManualStrategyKeepRecent {
+		t.Fatalf("expected auto compact to retain manual strategy, got %q", generator.calls[0].Config.ManualStrategy)
+	}
+}
+
 func TestManualCompactKeepRecentProtectsLatestExplicitUserInstruction(t *testing.T) {
 	t.Parallel()
 

internal/context/prompt.go

@@ -16,6 +16,8 @@ var defaultPromptSections = []promptSection{
 	{
 		title: "Tool Usage",
 		content: "- Use tools when they reduce uncertainty or are required to complete the task safely.\n" +
+			"- For risky operations, call the relevant tool first and let the runtime permission layer decide ask/allow/deny.\n" +
+			"- Do not self-reject a user-requested operation before attempting the proper tool call and permission flow.\n" +
 			"- Stay within the current workspace unless the user clearly asks for something else.\n" +
 			"- Do not claim work is done unless the needed files, commands, or verification actually succeeded.",
 	},

internal/context/prompt_test.go

@@ -1,6 +1,9 @@
 package context
 
-import "testing"
+import (
+	"strings"
+	"testing"
+)
 
 func TestDefaultSystemPromptSectionsReturnsCachedSections(t *testing.T) {
 	t.Parallel()
@@ -90,3 +93,25 @@ func TestComposeSystemPromptSkipsEmptySections(t *testing.T) {
 		t.Fatalf("composeSystemPrompt() = %q, want %q", got, want)
 	}
 }
+
+func TestDefaultToolUsagePromptEncouragesAskFlow(t *testing.T) {
+	t.Parallel()
+
+	sections := defaultSystemPromptSections()
+	var toolUsage string
+	for _, section := range sections {
+		if section.title == "Tool Usage" {
+			toolUsage = section.content
+			break
+		}
+	}
+	if toolUsage == "" {
+		t.Fatalf("expected Tool Usage section to exist")
+	}
+	if !strings.Contains(toolUsage, "permission layer") {
+		t.Fatalf("expected Tool Usage to mention permission layer, got %q", toolUsage)
+	}
+	if !strings.Contains(toolUsage, "Do not self-reject") {
+		t.Fatalf("expected Tool Usage to discourage self-reject, got %q", toolUsage)
+	}
+}

internal/provider/errors.go

@@ -4,6 +4,7 @@ import (
 	"errors"
 	"fmt"
 	"net/http"
+	"strings"
 )
 
 // 通用领域错误。
@@ -20,17 +21,41 @@ var (
 type ProviderErrorCode string
 
 const (
-	ErrorCodeAuthFailed ProviderErrorCode = "auth_failed"   // 认证失败（401）
-	ErrorCodeForbidden  ProviderErrorCode = "forbidden"     // 权限不足（403）
-	ErrorCodeNotFound   ProviderErrorCode = "not_found"     // 资源不存在（404）
-	ErrorCodeClient     ProviderErrorCode = "client_error"  // 客户端请求错误（4xx，排除上述分类）
-	ErrorCodeRateLimit  ProviderErrorCode = "rate_limited"  // 限流（429）
-	ErrorCodeServer     ProviderErrorCode = "server_error"  // 服务端错误（5xx）
-	ErrorCodeTimeout    ProviderErrorCode = "timeout"       // 超时
-	ErrorCodeNetwork    ProviderErrorCode = "network_error" // 网络错误（连接拒绝、DNS 失败等）
-	ErrorCodeUnknown    ProviderErrorCode = "unknown"       // 未知错误
+	ErrorCodeAuthFailed     ProviderErrorCode = "auth_failed"      // 认证失败（401）
+	ErrorCodeForbidden      ProviderErrorCode = "forbidden"        // 权限不足（403）
+	ErrorCodeNotFound       ProviderErrorCode = "not_found"        // 资源不存在（404）
+	ErrorCodeClient         ProviderErrorCode = "client_error"     // 客户端请求错误（4xx，排除上述分类）
+	ErrorCodeRateLimit      ProviderErrorCode = "rate_limited"     // 限流（429）
+	ErrorCodeServer         ProviderErrorCode = "server_error"     // 服务端错误（5xx）
+	ErrorCodeTimeout        ProviderErrorCode = "timeout"          // 超时
+	ErrorCodeNetwork        ProviderErrorCode = "network_error"    // 网络错误（连接拒绝、DNS 失败等）
+	ErrorCodeContextTooLong ProviderErrorCode = "context_too_long" // 上下文超出模型窗口
+	ErrorCodeUnknown        ProviderErrorCode = "unknown"          // 未知错误
 )
 
+var contextTooLongFragments = []string{
+	"context length",
+	"context_length_exceeded",
+	"context window",
+	"maximum context length",
+	"maximum prompt length",
+	"prompt is too long",
+}
+
+var contextTokenFragments = []string{
+	"requested too many tokens",
+	"too many tokens",
+}
+
+var contextTokenHints = []string{
+	"context",
+	"prompt",
+	"message",
+	"input",
+	"history",
+	"window",
+}
+
 // ProviderError 是 provider 层的领域错误类型。
 type ProviderError struct {
 	StatusCode int               // HTTP 状态码，0 表示非 HTTP 错误（如网络超时）
@@ -78,6 +103,13 @@ func classifyStatus(statusCode int) ProviderErrorCode {
 // NewProviderErrorFromStatus 根据 HTTP 状态码和消息构造 ProviderError。
 func NewProviderErrorFromStatus(statusCode int, message string) *ProviderError {
 	code := classifyStatus(statusCode)
+	// Only elevate to context_too_long for generic client errors (e.g. 400/413).
+	// Do not override specific classifications such as rate_limited (429) even if
+	// the message contains token-count fragments, which would mis-route throttling
+	// errors into the reactive-compact path.
+	if code == ErrorCodeClient && matchesContextTooLong(message) {
+		code = ErrorCodeContextTooLong
+	}
 	return &ProviderError{
 		StatusCode: statusCode,
 		Code:       code,
@@ -105,3 +137,54 @@ func NewTimeoutProviderError(message string) *ProviderError {
 		Retryable:  true, // 超时默认可重试
 	}
 }
+
+// IsContextTooLong 判断 provider 错误是否表示请求上下文超出模型窗口。
+// 优先识别 typed error，必要时再回退到消息文本匹配，兼容不同厂商或额外包装层。
+// 已被归类为 rate_limited (429) 的错误不会因文本片段而被误判为 context_too_long。
+func IsContextTooLong(err error) bool {
+	if err == nil {
+		return false
+	}
+
+	var pErr *ProviderError
+	if errors.As(err, &pErr) {
+		if pErr.Code == ErrorCodeContextTooLong {
+			return true
+		}
+		// Skip text fallback for errors that are already classified as a specific
+		// non-context error (e.g. rate_limited).  Token-count fragments in 429
+		// messages must not route the runtime into the reactive-compact path.
+		if pErr.Code == ErrorCodeRateLimit {
+			return false
+		}
+		if matchesContextTooLong(pErr.Message) {
+			return true
+		}
+	}
+
+	return matchesContextTooLong(err.Error())
+}
+
+// matchesContextTooLong 统一收敛常见“上下文过长”报错片段，减少 runtime 对厂商文案的感知。
+func matchesContextTooLong(message string) bool {
+	normalized := strings.ToLower(strings.TrimSpace(message))
+	if normalized == "" {
+		return false
+	}
+	for _, fragment := range contextTooLongFragments {
+		if strings.Contains(normalized, fragment) {
+			return true
+		}
+	}
+	for _, fragment := range contextTokenFragments {
+		if !strings.Contains(normalized, fragment) {
+			continue
+		}
+		for _, hint := range contextTokenHints {
+			if strings.Contains(normalized, hint) {
+				return true
+			}
+		}
+	}
+	return false
+}