wynxing · wynxing · Apr 16, 2026 · Apr 14, 2026 · Apr 14, 2026 · Apr 14, 2026
diff --git a/docs/config-management-detail-design.md b/docs/config-management-detail-design.md
@@ -130,3 +130,14 @@ custom provider 来自：
 - 不在 `config` 中堆兼容旧字段的逻辑
 - 不把选择修正混进快照校验
 - 不把 provider/catalog/runtime 语义倒灌回 `config`
+
+## custom provider `models` 校验约束
+
+`~/.neocode/providers/<provider-name>/provider.yaml` 中允许通过 `models` 补齐模型元数据，用于 catalog/discovery 无法提供完整 `ContextWindow` 或 `MaxOutputTokens` 的场景。
+
+该能力的约束是：
+
+- `models[].id` 必须非空。
+- `models[].context_window` 和 `models[].max_output_tokens` 如果显式提供，必须大于 `0`。
+- 重复的模型 `id` 会在加载 custom provider 时直接失败，不保留 silently drop 的宽松行为。
+- 这些元数据不会写回 `config.yaml`，只在 custom provider 文件中声明，并通过现有 catalog 合并链路参与运行时解析。
diff --git a/docs/context-compact.md b/docs/context-compact.md
@@ -1,5 +1,11 @@
 # Context Compact
 
+## Auto Compact Failure Fallback
+
+- 当 `context.auto_compact.input_token_threshold <= 0` 时，系统会尝试基于当前模型的 `ContextWindow` 自动推导阈值。
+- 若当前 provider 选择无效、catalog snapshot 查询失败，或模型窗口元数据缺失，系统会直接回退到 `fallback_input_token_threshold`。
+- 自动推导失败不会静默关闭 auto compact；runtime 仍会拿到一个可用的保底阈值。
+
 本文档说明 NeoCode 中 context compact 的配置、执行链路和摘要约定。
 
 ## 概览
@@ -23,7 +29,9 @@ context:
     micro_compact_disabled: false
   auto_compact:
     enabled: false
-    input_token_threshold: 100000
+    input_token_threshold: 0
+    reserve_tokens: 13000
+    fallback_input_token_threshold: 100000
 ```
 
 - `manual_strategy`
@@ -39,7 +47,7 @@ context:
 - `auto_compact.enabled`
   控制是否启用基于 token 阈值的自动压缩；默认关闭。
 - `auto_compact.input_token_threshold`
-  当会话累计输入 token 数达到此阈值时触发自动压缩；默认 100000。
+  当会话累计输入 token 数达到此阈值时触发自动压缩；默认 `0`（自动推导），推导失败时回退到 `fallback_input_token_threshold`（默认 `100000`）。
 
 ## 自动压缩
 
@@ -154,3 +162,12 @@ compact 相关 runtime 事件包括：
 - `trigger_mode`
 - `transcript_id`
 - `transcript_path`
+
+## Auto Compact 阈值解析
+
+- `context.auto_compact.input_token_threshold > 0` 时，直接使用显式手动阈值。
+- `context.auto_compact.input_token_threshold <= 0` 时，系统会对当前选中的 provider/model 做自动推导。
+- 自动推导公式为 `resolved_threshold = context_window - reserve_tokens`。
+- `reserve_tokens` 默认 `13000`，用于给输出、tool call 和 system prompt 预留缓冲。
+- 如果当前模型没有可用的 `ContextWindow`，或窗口值小于等于 `reserve_tokens`，则回退到 `fallback_input_token_threshold`。
+- `fallback_input_token_threshold` 默认 `100000`，用于保证主链路在缺少模型窗口元数据时仍可稳定运行。
diff --git a/docs/guides/adding-providers.md b/docs/guides/adding-providers.md
@@ -270,3 +270,34 @@ func DefaultProviders() []ProviderConfig {
 ```
 
 所有内置 provider 都通过代码集中注册。模型选择器展示的候选模型由默认模型、动态发现结果和本地缓存共同组成。
+
+## custom provider 模型元数据补齐
+
+对于复用 `openaicompat` 驱动的 custom provider，如果上游 `GET /models` 不能返回可靠的上下文窗口信息，可以在：
+
+```text
+~/.neocode/providers/<provider-name>/provider.yaml
+```
+
+中显式声明 `models`：
+
+```yaml
+name: company-gateway
+driver: openaicompat
+api_key_env: COMPANY_GATEWAY_API_KEY
+models:
+  - id: deepseek-coder
+    name: DeepSeek Coder
+    context_window: 131072
+    max_output_tokens: 8192
+openai_compatible:
+  base_url: https://llm.example.com/v1
+  api_style: chat_completions
+```
+
+约束如下：
+
+- `models[].id` 必须非空。
+- `models[].context_window` 和 `models[].max_output_tokens` 如果显式配置，必须大于 `0`。
+- 同一个 `provider.yaml` 中重复的模型 `id` 会在加载阶段直接报错。
+- 这些元数据会进入统一的 model catalog 合并链路，优先级仍为“配置模型元数据优先于 discovery/default”。
diff --git a/docs/guides/configuration.md b/docs/guides/configuration.md
@@ -38,6 +38,8 @@ selected_provider: openai
 current_model: gpt-5.4
 shell: bash
 tool_timeout_sec: 20
+runtime:
+  max_no_progress_streak: 3
 
 tools:
   webfetch:
@@ -56,7 +58,9 @@ context:
     micro_compact_disabled: false
   auto_compact:
     enabled: false
-    input_token_threshold: 100000
+    input_token_threshold: 0
+    reserve_tokens: 13000
+    fallback_input_token_threshold: 100000
 ```
 
 ### 基础字段
@@ -79,6 +83,14 @@ context:
 | `context.compact.micro_compact_disabled` | 是否关闭默认启用的 micro compact |
 | `context.auto_compact.enabled` | 是否启用自动压缩 |
 | `context.auto_compact.input_token_threshold` | 自动压缩输入 token 阈值 |
+| `context.auto_compact.reserve_tokens` | 自动阈值推导时预留 token 缓冲（`resolved_threshold = context_window - reserve_tokens`） |
+| `context.auto_compact.fallback_input_token_threshold` | 自动推导失败时使用的保底阈值 |
+
+### `runtime` 字段
+
+| 字段 | 说明 |
+|------|------|
+| `runtime.max_no_progress_streak` | 连续”无进展”轮次熔断阈值，默认 `3`；streak 达到 `limit-1`（默认第 2 轮）时向模型注入一次系统级纠偏提示，达到 `limit`（默认第 3 轮）时终止运行 |
 
 ### `tools` 字段
 
@@ -134,6 +146,13 @@ openai_compatible:
   api_style: chat_completions
 ```
 
+## Auto Compact 失败与校验补充
+
+- 当 `context.auto_compact.input_token_threshold <= 0` 时，如果当前 provider 选择无效、catalog snapshot 查询失败，或模型缺少可用的 `ContextWindow`，系统会回退到 `fallback_input_token_threshold`，不会静默关闭 auto compact。
+- `~/.neocode/providers/<provider-name>/provider.yaml` 中的 `models[].id` 必须非空。
+- `models[].context_window` 和 `models[].max_output_tokens` 如果显式配置，必须大于 `0`。
+- `models` 中重复的模型 `id` 会在加载 `provider.yaml` 时直接报错。
+
 文件路径：
 
 ```text
@@ -222,3 +241,26 @@ config: environment variable OPENAI_API_KEY is empty
 - [添加 Provider](./adding-providers.md)
 - [配置管理详细设计](../config-management-detail-design.md)
 - [Context Compact](../context-compact.md)
+
+## Auto Compact 补充说明
+
+- `context.auto_compact.input_token_threshold > 0` 时，系统直接使用该显式阈值。
+- `context.auto_compact.input_token_threshold <= 0` 时，系统会根据当前 `current_model` 对应的 `ContextWindow` 自动推导输入阈值。
+- 推导公式为 `context_window - reserve_tokens`。
+- `reserve_tokens` 默认 `13000`。
+- 如果当前 provider/model 没有可用的 `ContextWindow` 元数据，则回退到 `fallback_input_token_threshold`。
+- custom provider 可以在 `~/.neocode/providers/<provider-name>/provider.yaml` 中通过 `models` 字段补齐模型元数据，例如：
+
+```yaml
+name: company-gateway
+driver: openaicompat
+api_key_env: COMPANY_GATEWAY_API_KEY
+models:
+  - id: deepseek-coder
+    name: DeepSeek Coder
+    context_window: 131072
+    max_output_tokens: 8192
+openai_compatible:
+  base_url: https://llm.example.com/v1
+  api_style: chat_completions
+```
diff --git a/go.mod b/go.mod
@@ -3,13 +3,13 @@ module neo-code
 go 1.25.0
 
 require (
-	github.com/atotto/clipboard v0.1.4
 	github.com/charmbracelet/bubbles v1.0.0
 	github.com/charmbracelet/bubbletea v1.3.10
 	github.com/charmbracelet/glamour v1.0.0
 	github.com/charmbracelet/lipgloss v1.1.1-0.20250404203927-76690c660834
 	github.com/spf13/cobra v1.10.2
 	github.com/spf13/viper v1.21.0
+	golang.design/x/clipboard v0.7.1
 	golang.org/x/net v0.52.0
 	golang.org/x/sys v0.42.0
 	gopkg.in/yaml.v3 v3.0.1
@@ -18,6 +18,7 @@ require (
 require (
 	github.com/Microsoft/go-winio v0.6.2 // indirect
 	github.com/alecthomas/chroma/v2 v2.20.0 // indirect
+	github.com/atotto/clipboard v0.1.4 // indirect
 	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
 	github.com/aymerick/douceur v0.2.0 // indirect
 	github.com/charmbracelet/colorprofile v0.4.3 // indirect
@@ -57,6 +58,9 @@ require (
 	github.com/yuin/goldmark v1.7.13 // indirect
 	github.com/yuin/goldmark-emoji v1.0.6 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
+	golang.org/x/exp/shiny v0.0.0-20250606033433-dcc06ee1d476 // indirect
+	golang.org/x/image v0.28.0 // indirect
+	golang.org/x/mobile v0.0.0-20250606033058-a2a15c67f36f // indirect
 	golang.org/x/term v0.41.0 // indirect
 	golang.org/x/text v0.35.0 // indirect
 )
diff --git a/go.sum b/go.sum
@@ -130,8 +130,16 @@ github.com/yuin/goldmark-emoji v1.0.6 h1:QWfF2FYaXwL74tfGOW5izeiZepUDroDJfWubQI9
 github.com/yuin/goldmark-emoji v1.0.6/go.mod h1:ukxJDKFpdFb5x0a5HqbdlcKtebh086iJpI31LTKmWuA=
 go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
+golang.design/x/clipboard v0.7.1 h1:OEG3CmcYRBNnRwpDp7+uWLiZi3hrMRJpE9JkkkYtz2c=
+golang.design/x/clipboard v0.7.1/go.mod h1:i5SiIqj0wLFw9P/1D7vfILFK0KHMk7ydE72HRrUIgkg=
 golang.org/x/exp v0.0.0-20231006140011-7918f672742d h1:jtJma62tbqLibJ5sFQz8bKtEM8rJBtfilJ2qTU199MI=
 golang.org/x/exp v0.0.0-20231006140011-7918f672742d/go.mod h1:ldy0pHrwJyGW56pPQzzkH36rKxoZW1tw7ZJpeKx+hdo=
+golang.org/x/exp/shiny v0.0.0-20250606033433-dcc06ee1d476 h1:Wdx0vgH5Wgsw+lF//LJKmWOJBLWX6nprsMqnf99rYDE=
+golang.org/x/exp/shiny v0.0.0-20250606033433-dcc06ee1d476/go.mod h1:ygj7T6vSGhhm/9yTpOQQNvuAUFziTH7RUiH74EoE2C8=
+golang.org/x/image v0.28.0 h1:gdem5JW1OLS4FbkWgLO+7ZeFzYtL3xClb97GaUzYMFE=
+golang.org/x/image v0.28.0/go.mod h1:GUJYXtnGKEUgggyzh+Vxt+AviiCcyiwpsl8iQ8MvwGY=
+golang.org/x/mobile v0.0.0-20250606033058-a2a15c67f36f h1:/n+PL2HlfqeSiDCuhdBbRNlGS/g2fM4OHufalHaTVG8=
+golang.org/x/mobile v0.0.0-20250606033058-a2a15c67f36f/go.mod h1:ESkJ836Z6LpG6mTVAhA48LpfW/8fNR0ifStlH2axyfg=
 golang.org/x/net v0.52.0 h1:He/TN1l0e4mmR3QqHMT2Xab3Aj3L9qjbhRm78/6jrW0=
 golang.org/x/net v0.52.0/go.mod h1:R1MAz7uMZxVMualyPXb+VaqGSa3LIaUqk0eEt3w36Sw=
 golang.org/x/sys v0.0.0-20210809222454-d867a43fc93e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=

diff --git a/internal/app/bootstrap.go b/internal/app/bootstrap.go
@@ -168,6 +168,15 @@ func BuildRuntime(ctx context.Context, opts BootstrapOptions) (RuntimeBundle, er
 		contextBuilder,
 	)
 	runtimeSvc.SetSkillsRegistry(buildSkillsRegistry(ctx, loader.BaseDir()))
+	runtimeSvc.SetAutoCompactThresholdResolver(runtimeAutoCompactThresholdResolverFunc(
+		func(ctx context.Context, cfg config.Config) (int, error) {
+			resolution, err := configstate.ResolveAutoCompactThreshold(ctx, cfg, modelCatalogs)
+			if err != nil {
+				return 0, err
+			}
+			return resolution.Threshold, nil
+		},
+	))
 
 	// 注入记忆提取钩子：当 AutoExtract 启用且 memoSvc 可用时，ReAct 循环完成后异步提取记忆。
 	if memoSvc != nil && cfg.Memo.AutoExtract {
@@ -306,3 +315,9 @@ type textGenAdapter func(ctx context.Context, prompt string, msgs []providertype
 func (f textGenAdapter) Generate(ctx context.Context, prompt string, msgs []providertypes.Message) (string, error) {
 	return f(ctx, prompt, msgs)
 }
+
+type runtimeAutoCompactThresholdResolverFunc func(ctx context.Context, cfg config.Config) (int, error)
+
+func (f runtimeAutoCompactThresholdResolverFunc) ResolveAutoCompactThreshold(ctx context.Context, cfg config.Config) (int, error) {
+	return f(ctx, cfg)
+}
diff --git a/internal/config/config.go b/internal/config/config.go
@@ -21,6 +21,7 @@ type Config struct {
 	Workdir          string           `yaml:"-"`
 	Shell            string           `yaml:"shell"`
 	ToolTimeoutSec   int              `yaml:"tool_timeout_sec,omitempty"`
+	Runtime          RuntimeConfig    `yaml:"runtime,omitempty"`
 	Context          ContextConfig    `yaml:"context,omitempty"`
 	Tools            ToolsConfig      `yaml:"tools,omitempty"`
 	Memo             MemoConfig       `yaml:"memo,omitempty"`
@@ -32,6 +33,7 @@ func StaticDefaults() *Config {
 		Workdir:        DefaultWorkdir,
 		Shell:          defaultShell(),
 		ToolTimeoutSec: DefaultToolTimeoutSec,
+		Runtime:        defaultRuntimeConfig(),
 		Context:        defaultContextConfig(),
 		Tools: ToolsConfig{
 			WebFetch: defaultWebFetchConfig(),
@@ -48,6 +50,7 @@ func (c *Config) Clone() Config {
 
 	clone := *c
 	clone.Providers = cloneProviders(c.Providers)
+	clone.Runtime = c.Runtime.Clone()
 	clone.Context = c.Context.Clone()
 	clone.Tools = c.Tools.Clone()
 	clone.Memo = c.Memo.Clone()
@@ -69,6 +72,7 @@ func (c *Config) applyStaticDefaults(defaults Config) {
 	if c.ToolTimeoutSec <= 0 {
 		c.ToolTimeoutSec = defaults.ToolTimeoutSec
 	}
+	c.Runtime.ApplyDefaults(defaults.Runtime)
 	c.Context.ApplyDefaults(defaults.Context)
 	c.Tools.ApplyDefaults(defaults.Tools)
 	c.Memo.ApplyDefaults(defaults.Memo)
@@ -122,6 +126,9 @@ func (c *Config) ValidateSnapshot() error {
 	if err := c.Tools.Validate(); err != nil {
 		return fmt.Errorf("config: tools: %w", err)
 	}
+	if err := c.Runtime.Validate(); err != nil {
+		return fmt.Errorf("config: runtime: %w", err)
+	}
 	if err := c.Context.Validate(); err != nil {
 		return fmt.Errorf("config: context: %w", err)
 	}