AskaEth/Cyrene_v2
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(comments): 注释中文化 · internal/runtime/model + internal/services/backthink（54 文件，纯替换）
CI / Backend (build / vet / test / cross-compile) (push) Has been cancelled
Details
CI / Frontend (tsc + vite build) (push) Has been cancelled
Details

Browse Source 
- 只翻注释/文档字符串：`go/scanner` 剥注释后按 token 序列+literal 逐 token 比对，**54/54 文件 SAME**；
  改动文件总行数与 HEAD 漂移 = 0（严格 1:1，无合并/拆行）
- 裁决编号与 design 节号逐字保留（03.4.1/03.4.2/03.4.3/14.4.1/14.4.5/07.4.2-4、design/04 §3.1/§3.2 等）；
  `chat_template_kwargs` / `enable_thinking` / `reasoning_effort` / `thinking:{type}` 字段名与形状说明未动
- 存疑译法（已登记）：`persona` 在叙事语境用「角色」、标识符语境保留 `persona`（仓库既有模块本身混用）；
  `rung`→「级」；`provider` 存在「提供商/提供者」两种落笔（可按需一键统一）
- 复核：build/vet 绿 + 两包测试绿；gofmt 干净；残留英文注释 0 条
- 既有存量（未修，只报告）：`model/anthropic_test.go` 612 行 >500；`applyAnthropicEvent` 115 行 >80
This commit is contained in:
AskaEth committed 2026-10-04 16:27:54 +08:00
1 parent f5cf117482
commit 3dc1232bc2
54 files changed
+1923 -1923
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

internal/runtime/model/factory.go
+43 -43
View File
@@ -9,23 +9,23 @@ import (
"git.yeij.top/AskaEth/Cyrene_v2/internal/config"
)
// Provider names accepted by the provider-aware factory. These are the only two
// protocols the factory understands today; adding a vendor means adding a case
// here plus a matching adapter, not touching the rest of the package.
// 提供商感知工厂接受的提供商名。这是工厂目前理解的仅有的
// 两种协议；新增厂商意味着在这里加一个 case
// 再加一个配套适配器，而不必改动包内其它部分。
const (
// ProviderOpenAI selects the OpenAI-compatible /chat/completions protocol.
// ProviderOpenAI 选择 OpenAI 兼容的 /chat/completions 协议。
ProviderOpenAI = "openai"
// ProviderAnthropic selects the Anthropic Messages /v1/messages protocol.
// ProviderAnthropic 选择 Anthropic Messages 的 /v1/messages 协议。
ProviderAnthropic = "anthropic"
)
// ErrUnknownProvider is returned by the provider-aware factory when the
// configured provider name is not recognized.
// 配置的提供商名无法识别时，由提供商感知工厂返回
// ErrUnknownProvider。
var ErrUnknownProvider = errors.New("model: unknown provider")
// NewChatAdapter builds a single provider adapter selected by cfg.Provider. The
// empty provider defaults to openai for backward compatibility. An unrecognized
// provider returns ErrUnknownProvider.
// NewChatAdapter 按 cfg.Provider 构建单个提供商适配器。
// 提供商为空时为向后兼容默认用 openai。无法识别的
// 提供商返回 ErrUnknownProvider。
func NewChatAdapter(cfg config.LLMConfig) (Adapter, error) {
switch cfg.Provider {
case ProviderOpenAI, "":
@@ -37,25 +37,25 @@ func NewChatAdapter(cfg config.LLMConfig) (Adapter, error) {
}
}
// NewChatChain builds a fallback Chain for the configured provider: the primary
// model first, then the provider's fallback model when set and distinct. Each
// step is served by an adapter of the selected protocol. The empty provider
// defaults to openai. An unrecognized provider returns ErrUnknownProvider.
// NewChatChain 为配置的提供商构建降级 Chain：先是主
// 模型，再是提供商已设置且不同的降级模型。每一步
// 都由所选协议的适配器服务。提供商为空
// 时默认用 openai。无法识别的提供商返回 ErrUnknownProvider。
func NewChatChain(cfg config.LLMConfig) (*Chain, error) {
return NewChatChainWithLog(cfg, nil)
}
// NewChatChainWithLog is NewChatChain with a logger attached to every adapter it
// builds, so a provider-level reasoning decision (a thinking budget raised to fit
// max_tokens, a reasoning_effort value downgraded or ignored) is reported with
// its module source. A nil logger leaves the adapters' discard default in place.
// NewChatChainWithLog 是 NewChatChain，并为它构建的每个适配器
// 挂上日志器，好让提供商层面的推理决策（为容纳
// max_tokens 而抬高的思考预算、被降级或忽略的 reasoning_effort 值）
// 带着模块来源上报。nil 日志器则保留适配器的丢弃式默认值。
//
// It is also the only builder that appends the optional local third rung
// (裁决 03.4.3, primary → fallback → local), because that rung may speak a
// different protocol than the active group and therefore needs the raw logger to
// build its own adapter. It is appended only when the local rung is enabled AND
// fully configured; otherwise the chain keeps its two-level shape and the reason
// is reported.
// 它也是唯一会追加可选本地第三级（local rung）的构建器
// （裁决 03.4.3，primary → fallback → local），因为那一级可能说
// 与生效组不同的协议，因此需要原始日志器来
// 构建自己的适配器。只有当本地级已启用且完全
// 配置好时才会追加；否则链保持两级形状，并
// 上报原因。
func NewChatChainWithLog(cfg config.LLMConfig, log *slog.Logger) (*Chain, error) {
var chain *Chain
var err error
@@ -76,16 +76,16 @@ func NewChatChainWithLog(cfg config.LLMConfig, log *slog.Logger) (*Chain, error)
return chain, nil
}
// localChainStep builds the local third degradation rung as a chain step. It
// returns ok=false (and, when the rung was asked for but is incomplete, a WARN
// naming the missing field) when the rung is off, unconfigured or its provider is
// unknown — a half-configured step would only ever fail, which is worse than not
// having it.
// localChainStep 把本地第三级降级构造成一个链步骤。
// 当该级关闭、未配置或其提供商未知时，返回 ok=false
// （若该级被要求但配置不全，则附一条点出缺失字段的 WARN）
// ——一个半配置的步骤只会失败，那还不如没有
// 它。
func localChainStep(cfg config.LLMConfig, log *slog.Logger) (Step, bool) {
local := cfg.Local
// Configured() already requires Enabled, so the rung is off by default and a
// disabled rung can never become a chain step. The warning is emitted only
// when the rung was actually asked for but is incomplete.
// Configured() 本身已要求 Enabled，所以该级默认关闭，
// 被禁用的级永远不会成为链步骤。只有当该级确实被
// 要求、但配置不全时才发出该警告。
if !local.Configured() {
if local.Enabled {
warn(log, "local model rung enabled but not configured; skipping it",
@@ -112,8 +112,8 @@ func localChainStep(cfg config.LLMConfig, log *slog.Logger) (Step, bool) {
}
}
// newOpenAIChain builds a fallback chain from the OpenAI-compatible config block.
// Each step is an OpenAIChatAdapter against the configured endpoint.
// newOpenAIChain 由 OpenAI 兼容配置块构建降级链。
// 每一步都是针对该端点的 OpenAIChatAdapter。
func newOpenAIChain(cfg config.LLMConfig, opts ...OpenAIOption) (*Chain, error) {
if cfg.BaseURL == "" || cfg.Model == "" {
return nil, ErrNoModel
@@ -125,8 +125,8 @@ func newOpenAIChain(cfg config.LLMConfig, opts ...OpenAIOption) (*Chain, error)
return NewChain(steps...), nil
}
// newAnthropicChain builds a fallback chain from the Anthropic config block. Each
// step is an AnthropicChatAdapter against the configured /v1/messages endpoint.
// newAnthropicChain 由 Anthropic 配置块构建降级链。每一步
// 都是针对该 /v1/messages 端点的 AnthropicChatAdapter。
func newAnthropicChain(cfg config.LLMConfig, opts ...AnthropicOption) (*Chain, error) {
if cfg.AnthropicBaseURL == "" || cfg.AnthropicModel == "" {
return nil, ErrNoModel
@@ -138,9 +138,9 @@ func newAnthropicChain(cfg config.LLMConfig, opts ...AnthropicOption) (*Chain, e
return NewChain(steps...), nil
}
// DefaultModelForProvider returns the primary model name for the configured
// provider: the flat OpenAI Model for "openai", the Anthropic model for
// "anthropic". Used by callers (e.g. cmd/cyrene) to seed a Router's default.
// DefaultModelForProvider 返回配置提供商的主模型名：
// "openai" 取扁平配置里的 OpenAI Model，"anthropic" 取 Anthropic 模型。
// 调用方（如 cmd/cyrene）用它播种 Router 的默认值。
func DefaultModelForProvider(cfg config.LLMConfig) string {
if cfg.Provider == ProviderAnthropic {
return cfg.AnthropicModel
@@ -148,10 +148,10 @@ func DefaultModelForProvider(cfg config.LLMConfig) string {
return cfg.Model
}
// warn reports through the injected logger, falling back to a discard logger that
// still carries the module source so an unsourced record can never be emitted
// (project rule §10). It exists because a chain may be built without a logger
// (NewChatChain) while a skipped rung must still be reported.
// warn 通过注入的日志器上报，降级到一个仍带有模块来源的丢弃式
// 日志器，因此绝不会产生无来源日志
// （项目铁律 §10）。它之所以存在，是因为链可能在没有日志器
// 的情况下构建（NewChatChain），而被跳过的级仍须上报。
func warn(log *slog.Logger, msg string, args ...any) {
if log == nil {
log = discardLogger("model")