Documentation
¶
Index ¶
- Constants
- func CompactReserveTokens(window int) int
- func DefaultConfigDir() string
- func DefaultConfigPath() string
- func LogContextWindowChoice(role, model string, window int, source ContextWindowSource)
- func ModelName(m agentcore.ChatModel) string
- func NeedsSetup(flagPath string) bool
- func SaveConfig(path string, cfg Config) error
- type Config
- type ContextWindowSource
- type FailoverEvent
- type FailoverReporter
- type ModelRef
- type ModelSet
- func (ms *ModelSet) CurrentSelection(role string) (provider, model string, explicit bool)
- func (ms *ModelSet) ForRole(role string) agentcore.ChatModel
- func (ms *ModelSet) ForRoleWithFailover(role string, report FailoverReporter) agentcore.ChatModel
- func (ms *ModelSet) Summary() string
- func (ms *ModelSet) Swap(role, provider, model string) error
- type ProviderConfig
- type RoleConfig
- type SwappableModel
Constants ¶
const CompactRatio = 0.85
CompactRatio 触发上下文压缩的相对阈值：tokens >= window * CompactRatio 时压缩。 0.85 是经验值，给"下一轮 prompt + 大工具结果"留 15% 头部空间，同时让大窗口 模型也能在 85% 主动压缩，避免在 1M 名义窗口下吃满才压（注意力衰退区）。
不暴露给用户配置：与已删除的 context_window 同源——多模型架构下让用户调 数字旋钮反复横跳，不如代码内固定一个合理值。
const DefaultContextWindow = 200000
DefaultContextWindow 模型未在 registry 登记时的兜底窗口大小。
const MinCompactReserve = 8000
MinCompactReserve 是 ReserveTokens 的下限。小窗口模型（如 32k 本地 qwen3:8b） 按 0.15 比例算 reserve 仅 4800，单次 commit_chapter 工具响应就能塞 5-8k， 一章正文 8-15k——会出现"压完立刻又超"。8000 兜底保证最坏场景下还有半轮缓冲。
Variables ¶
This section is empty.
Functions ¶
func CompactReserveTokens ¶ added in v0.4.0
CompactReserveTokens 按 CompactRatio 反算 ReserveTokens 并应用 MinCompactReserve floor：
threshold = window - reserve = window * CompactRatio reserve = max(MinCompactReserve, window * (1 - CompactRatio))
给 agentcore.context.Engine 的 EngineConfig.ReserveTokens 用。
func DefaultConfigDir ¶ added in v0.1.2
func DefaultConfigDir() string
DefaultConfigDir 返回 ~/.ainovel 目录路径；取不到家目录时返回空字符串。 仅用于读/写不强制存在的文件（如模型缓存），不会自动创建目录。
func DefaultConfigPath ¶
func DefaultConfigPath() string
DefaultConfigPath 返回全局配置文件路径 ~/.ainovel/config.json。
func LogContextWindowChoice ¶ added in v0.4.0
func LogContextWindowChoice(role, model string, window int, source ContextWindowSource)
LogContextWindowChoice 打印某个角色的窗口决策。source=default 时发 Warn 提示 该模型未在 registry 命中（OpenRouter 也未收录），后续上下文压缩会按兜底窗口 触发——若模型实际窗口更大，可在配置文件用 context_window 显式指定，避免被提前压缩、丢史。
func ModelName ¶ added in v0.1.2
ModelName 从 ChatModel 中提取当前模型名，失败返回空字符串。 支持 SwappableModel 的热切换：调用时总是返回最新值。
func SaveConfig ¶
SaveConfig 将配置写入指定路径（JSON 格式，缩进美化）。
Types ¶
type Config ¶
type Config struct {
// 运行时字段（不序列化到 JSON）
OutputDir string `json:"-"` // 输出根目录
// 默认 LLM 配置
Provider string `json:"provider"` // 默认 provider（Providers map 中的 key）
ModelName string `json:"model"` // 默认模型名
// Provider 凭证库
Providers map[string]ProviderConfig `json:"providers,omitempty"`
// 角色级模型覆盖
Roles map[string]RoleConfig `json:"roles,omitempty"`
// 创作参数
Style string `json:"style,omitempty"`
// ContextWindow 上下文压缩使用的窗口大小。留空（0）时按模型名自动解析：
// registry 命中用模型真实窗口，未命中兜底 DefaultContextWindow。
// 显式配置则优先生效——用于给 registry 查不到的自定义模型指定真实窗口，
// 或把大窗口模型钉在更小的值上提前触发压缩（1M 名义窗口在 200k+ 通常已注意力衰退）。
// 仅影响压缩阈值，不改变 LLM API 实际请求长度；配置值由用户自负其责。
ContextWindow int `json:"context_window,omitempty"`
}
Config 小说应用配置。
func LoadConfig ¶
LoadConfig 按优先级加载并合并配置：
- ~/.ainovel/config.json（全局）
- ./ainovel.json（项目级覆盖）
- flagPath 指定的路径（最高优先级）
func LoadConfigFile ¶ added in v0.0.2
LoadConfigFile 读取单个 JSON 配置文件，支持 // 行注释。 不做任何合并，仅返回该文件自身的配置。文件不存在时返回错误。
func (Config) CandidateModels ¶ added in v0.0.2
CandidateModels 返回某个 provider 下可供切换的模型列表。 优先使用 provider 显式声明的 models；同时补充当前配置中已出现过的该 provider 模型。
func (*Config) DefaultProviderConfig ¶
func (c *Config) DefaultProviderConfig() ProviderConfig
DefaultProviderConfig 返回默认 provider 的凭证配置。
func (Config) ResolveContextWindow ¶ added in v0.1.2
func (c Config) ResolveContextWindow(modelName string) (int, ContextWindowSource)
ResolveContextWindow 解析上下文压缩使用的有效窗口，按优先级：
- 配置文件 ContextWindow > 0 → 直接用（最高优先级，可超过模型真窗口）
- models.DefaultRegistry 按模型名查询（OpenRouter 基线 + 24h 刷新）
- 兜底 DefaultContextWindow（自定义代理 / 未知模型）
注意：返回值仅用于压缩阈值计算，不会缩小 LLM API 真实可发请求长度。
type ContextWindowSource ¶ added in v0.1.2
type ContextWindowSource string
ContextWindowSource 标记窗口取值的来源，供日志/诊断使用。
const ( CtxWindowConfig ContextWindowSource = "config" // 配置文件 context_window 显式指定 CtxWindowRegistry ContextWindowSource = "registry" // OpenRouter 基线命中 CtxWindowDefault ContextWindowSource = "default" // 兜底（自定义代理/未知模型） )
type FailoverEvent ¶ added in v0.1.0
type FailoverEvent struct {
Role string
Reason string
FromProvider string
FromModel string
ToProvider string
ToModel string
Err error
}
FailoverEvent 表示一次显式 provider 切换。 Reason 为短标签（rate_limit / timeout / stream_idle / network），用于结构化日志。
type FailoverReporter ¶ added in v0.1.0
type FailoverReporter func(FailoverEvent)
FailoverReporter 在发生显式切换时被调用。
type ModelRef ¶ added in v0.1.0
type ModelRef struct {
Provider string `json:"provider"` // provider 名称（Providers map 中的 key）
Model string `json:"model"` // 模型名（原样透传，不做任何解析）
}
ModelRef 表示一个 provider/model 组合。
type ModelSet ¶
type ModelSet struct {
Default *SwappableModel
// contains filtered or unexported fields
}
ModelSet 持有按角色分配的模型实例，未配置的角色回退到默认模型。
func NewModelSet ¶
NewModelSet 根据配置创建多模型集合。 相同 provider+model 组合复用同一个实例。
func (*ModelSet) CurrentSelection ¶ added in v0.0.2
CurrentSelection 返回角色当前生效的 provider/model。 role 为空或 "default" 时返回默认模型。
func (*ModelSet) ForRoleWithFailover ¶ added in v0.1.0
func (ms *ModelSet) ForRoleWithFailover(role string, report FailoverReporter) agentcore.ChatModel
ForRoleWithFailover 返回带有单次请求级 fallback 的角色模型。 仅当该角色显式配置了 fallbacks 时生效；未配置时退化为普通模型。
type ProviderConfig ¶
type ProviderConfig struct {
Type string `json:"type,omitempty"` // API 协议类型（openai/anthropic/gemini），自定义代理时指定
APIKey string `json:"api_key,omitempty"` // API Key
BaseURL string `json:"base_url,omitempty"` // API Base URL
Models []string `json:"models,omitempty"` // 可选模型列表，供 TUI 切换时展示
}
ProviderConfig 定义单个 LLM 提供商的凭证。
func (ProviderConfig) ProviderType ¶
func (pc ProviderConfig) ProviderType(name string) (string, error)
ProviderType 返回有效的 API 协议类型。 优先使用显式 Type；否则要求 provider 名本身已在 litellm 注册表中。
func (ProviderConfig) RequiresAPIKey ¶
func (pc ProviderConfig) RequiresAPIKey(name string) bool
RequiresAPIKey 返回该 provider 是否必须显式配置 api_key。 约定： 1. ollama / bedrock 允许无 key； 2. 显式指定 Type 的配置视为自定义代理，允许无 key； 3. 其他 provider 默认要求 key，保持对官方托管接口的保守校验。
type RoleConfig ¶
type RoleConfig struct {
Provider string `json:"provider"` // 主 provider 名称（Providers map 中的 key）
Model string `json:"model"` // 主模型名（原样透传，不做任何解析）
Fallbacks []ModelRef `json:"fallbacks,omitempty"` // 显式备用 provider/model 列表
}
RoleConfig 定义单个角色的模型覆盖。
type SwappableModel ¶ added in v0.0.2
type SwappableModel struct {
*agentcore.SwappableModel
// contains filtered or unexported fields
}
SwappableModel 是可热切换的 ChatModel 包装器。 已开始的请求继续使用旧实例；后续请求自动切到新实例。
func NewSwappableModel ¶ added in v0.0.2
func NewSwappableModel(provider, name string, model agentcore.ChatModel) *SwappableModel
func (*SwappableModel) Current ¶ added in v0.0.2
func (m *SwappableModel) Current() (provider, name string)
func (*SwappableModel) Info ¶ added in v0.0.2
func (m *SwappableModel) Info() llm.ModelInfo
func (*SwappableModel) ProviderName ¶ added in v0.0.2
func (m *SwappableModel) ProviderName() string
Source Files