docs(comments): 注释中文化 · internal/runtime/model + internal/services/backthink（54 文件，纯替换）
- 只翻注释/文档字符串：`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
1 parent
f5cf117482
commit
3dc1232bc2
54 files changed
+1923
-1923
No files matched your search
@@ -12,45 +12,45 @@ import (
|
||||
"git.yeij.top/AskaEth/Cyrene_v2/internal/logger"
|
||||
)
|
||||
|
||||
// ModelRouter is the routing contract the agent (and loop) depend on. *Router
|
||||
// implements it; RuntimeLLM implements it too, so a hot-swappable provider can
|
||||
// serve as both the adapter and the router without a separate router reference
|
||||
// to keep in sync.
|
||||
// ModelRouter 是 agent（与 loop）依赖的路由契约。*Router
|
||||
// 实现它；RuntimeLLM 也实现它，因此一个可热切换的提供商
|
||||
// 可以同时充当适配器与路由器，无需另存一份 router 引用
|
||||
// 去保持同步。
|
||||
type ModelRouter interface {
|
||||
RouteRequest(req Request) (model string, needsVision bool)
|
||||
}
|
||||
|
||||
// runtimeChainSnapshot is an immutable, self-contained LLM stack snapshot. It is
|
||||
// stored and swapped atomically: a request that already captured a snapshot
|
||||
// keeps using that exact chain+router for its whole call, so a reload never
|
||||
// interrupts an in-flight request.
|
||||
// runtimeChainSnapshot 是不可变、自包含的 LLM 栈快照。它
|
||||
// 被原子存储与换入：已经捕获某个快照的请求
|
||||
// 整次调用都用那条确切的链+路由器，所以一次重载绝不会
|
||||
// 打断进行中的请求。
|
||||
type runtimeChainSnapshot struct {
|
||||
chain *Chain
|
||||
router *Router
|
||||
group runtimeconfig.Group
|
||||
groups []runtimeconfig.Group
|
||||
// providerChains holds one chain per *other* protocol declared by the active
|
||||
// group's personaProviders (裁决 03.4.1 的 per-persona provider：跨协议换
|
||||
// adapter). A persona whose provider binding resolves to one of these keys is
|
||||
// served by that chain; every other request keeps the default chain above.
|
||||
// providerChains 为生效组的 personaProviders 声明的每个
|
||||
// *其它* 协议各存一条链（裁决 03.4.1 的 per-persona provider：跨协议换
|
||||
// adapter）。提供商绑定解析到这些键之一的 persona 由
|
||||
// 那条链服务；其余所有请求仍走上面的默认链。
|
||||
providerChains map[string]*Chain
|
||||
}
|
||||
|
||||
// RuntimeLLM is the hot-swappable LLM provider stack for the runtime. It
|
||||
// implements Adapter (delegating to the current chain) and ModelRouter
|
||||
// (delegating to the current router). A panel save reloads models.json, rebuilds
|
||||
// a fresh chain+router and atomically swaps it in: new calls use the new stack
|
||||
// while calls already in flight finish on the old one.
|
||||
// RuntimeLLM 是运行时的可热切换 LLM 提供商栈。它
|
||||
// 实现 Adapter（委托给当前链）与 ModelRouter
|
||||
// （委托给当前路由器）。面板保存会重载 models.json、重建
|
||||
// 一份新的链+路由器并原子换入：新调用使用新栈，
|
||||
// 而进行中的调用在旧栈上跑完。
|
||||
type RuntimeLLM struct {
|
||||
path string
|
||||
env config.LLMConfig
|
||||
log *slog.Logger
|
||||
current atomic.Value // *runtimeChainSnapshot
|
||||
current atomic.Value // 类型：*runtimeChainSnapshot
|
||||
}
|
||||
|
||||
// NewRuntimeLLM builds the provider stack from models.json at path, falling back
|
||||
// to env. It loads the initial snapshot so the runtime is usable immediately.
|
||||
// log may be nil (a discard logger is used).
|
||||
// NewRuntimeLLM 由 path 处的 models.json 构建提供商栈，并回退
|
||||
// 到 env。它会加载初始快照，因此运行时立即可用。
|
||||
// log 可为 nil（此时使用丢弃式日志器）。
|
||||
func NewRuntimeLLM(path string, env config.LLMConfig, log *slog.Logger) *RuntimeLLM {
|
||||
if log == nil {
|
||||
log = slog.New(slog.NewTextHandler(io.Discard, nil))
|
||||
@@ -60,11 +60,11 @@ func NewRuntimeLLM(path string, env config.LLMConfig, log *slog.Logger) *Runtime
|
||||
return m
|
||||
}
|
||||
|
||||
// Path returns the models.json path this manager reads and reloads from.
|
||||
// Path 返回本管理器读取并重载的 models.json 路径。
|
||||
func (m *RuntimeLLM) Path() string { return m.path }
|
||||
|
||||
// Groups returns a copy of the current loaded groups; the active group (the one
|
||||
// a new request uses by default) is index 0.
|
||||
// Groups 返回当前已加载组的一份拷贝；生效组（新请求
|
||||
// 默认使用的那个）是下标 0。
|
||||
func (m *RuntimeLLM) Groups() []runtimeconfig.Group {
|
||||
src := m.load().groups
|
||||
out := make([]runtimeconfig.Group, len(src))
|
||||
@@ -72,18 +72,18 @@ func (m *RuntimeLLM) Groups() []runtimeconfig.Group {
|
||||
return out
|
||||
}
|
||||
|
||||
// Group returns the active group (index 0).
|
||||
// Group 返回生效组（下标 0）。
|
||||
func (m *RuntimeLLM) Group() runtimeconfig.Group { return m.load().group }
|
||||
|
||||
// Current returns the current chain and router. The returned chain stays valid
|
||||
// for calls already in flight; new calls pick up the latest swap.
|
||||
// Current 返回当前链与路由器。返回的链对进行中的
|
||||
// 调用仍然有效；新调用会拿到最新的换入结果。
|
||||
func (m *RuntimeLLM) Current() (*Chain, *Router) {
|
||||
snap := m.load()
|
||||
return snap.chain, snap.router
|
||||
}
|
||||
|
||||
// Reload re-reads models.json (falling back to env) and atomically rebuilds the
|
||||
// in-use chain+router. In-flight calls keep the previous snapshot.
|
||||
// Reload 重新读取 models.json（回退到 env）并原子重建
|
||||
// 在用的链+路由器。进行中的调用保持原快照。
|
||||
func (m *RuntimeLLM) Reload() error {
|
||||
groups, warn := runtimeconfig.LoadModels(m.path, m.env)
|
||||
if warn != nil {
|
||||
@@ -92,19 +92,19 @@ func (m *RuntimeLLM) Reload() error {
|
||||
return m.swap(groups)
|
||||
}
|
||||
|
||||
// Provider returns the active group's provider protocol.
|
||||
// Provider 返回生效组的提供商协议。
|
||||
func (m *RuntimeLLM) Provider() string { return m.load().group.Provider }
|
||||
|
||||
// Model returns the active group's primary model name.
|
||||
// Model 返回生效组的主模型名。
|
||||
func (m *RuntimeLLM) Model() string { return m.load().group.Model }
|
||||
|
||||
// Name implements Adapter, returning the active group id.
|
||||
// Name 实现 Adapter，返回生效组 id。
|
||||
func (m *RuntimeLLM) Name() string { return m.load().group.ID }
|
||||
|
||||
// Chat implements Adapter, delegating to the chain the request's persona
|
||||
// resolves to. A request that began before a reload completes on the snapshot it
|
||||
// captured. When no model is configured (nil chain) it returns ErrNoModel rather
|
||||
// than panicking.
|
||||
// Chat 实现 Adapter，委托给请求的 persona 所解析到的
|
||||
// 链。在重载完成前开始的请求，会在它已捕获的快照上
|
||||
// 跑完。未配置模型（链为 nil）时返回 ErrNoModel，而不是
|
||||
// panic。
|
||||
func (m *RuntimeLLM) Chat(ctx context.Context, req Request, opts Options) (Response, error) {
|
||||
chain := m.chainFor(req.PersonaID)
|
||||
if chain == nil {
|
||||
@@ -113,7 +113,7 @@ func (m *RuntimeLLM) Chat(ctx context.Context, req Request, opts Options) (Respo
|
||||
return chain.Chat(ctx, req, opts)
|
||||
}
|
||||
|
||||
// ChatStream implements Adapter.
|
||||
// ChatStream 实现 Adapter。
|
||||
func (m *RuntimeLLM) ChatStream(ctx context.Context, req Request, onEvent func(StreamEvent)) (Response, error) {
|
||||
chain := m.chainFor(req.PersonaID)
|
||||
if chain == nil {
|
||||
@@ -122,20 +122,20 @@ func (m *RuntimeLLM) ChatStream(ctx context.Context, req Request, onEvent func(S
|
||||
return chain.ChatStream(ctx, req, onEvent)
|
||||
}
|
||||
|
||||
// chainFor resolves the chain that serves this persona (裁决 03.4.1 的
|
||||
// per-persona provider). It consumes Router.RouteProviderForPersona — the
|
||||
// provider decision the router already made for this persona — and only switches
|
||||
// when BOTH hold:
|
||||
// chainFor 解出服务该 persona 的链（裁决 03.4.1 的
|
||||
// per-persona provider）。它消费 Router.RouteProviderForPersona ——
|
||||
// 路由器已为该 persona 做出的提供商决策 —— 且只在
|
||||
// 二者同时成立时才切换：
|
||||
//
|
||||
// - the persona has its own model binding (an entry in personaProviders alone
|
||||
// would send the group's default model name to another vendor's endpoint),
|
||||
// - and a chain exists for that provider (a declared protocol with no matching
|
||||
// group in models.json is reported when the snapshot is built, and the
|
||||
// persona then keeps the default chain rather than failing the turn).
|
||||
// - 该 persona 有自己的模型绑定（只写 personaProviders 一项
|
||||
// 会把组的默认模型名发到另一厂商的端点），
|
||||
// - 且该提供商存在一条链（声明了协议但 models.json 里没有
|
||||
// 对应组的情况会在构建快照时上报，
|
||||
// 该 persona 随后保留默认链，而不是让回合失败）。
|
||||
//
|
||||
// Everything else — no persona, no binding, same protocol as the active group —
|
||||
// returns the default chain, so a deployment without per-persona providers
|
||||
// behaves exactly as before.
|
||||
// 其余情形 —— 无 persona、无绑定、与生效组同协议 ——
|
||||
// 返回默认链，因此没有按 persona 提供商的部署
|
||||
// 行为与之前完全一致。
|
||||
func (m *RuntimeLLM) chainFor(persona string) *Chain {
|
||||
snap := m.load()
|
||||
if p := trimKey(persona); p != "" && snap.router != nil {
|
||||
@@ -148,7 +148,7 @@ func (m *RuntimeLLM) chainFor(persona string) *Chain {
|
||||
return snap.chain
|
||||
}
|
||||
|
||||
// RouteRequest implements ModelRouter, delegating to the current router.
|
||||
// RouteRequest 实现 ModelRouter，委托给当前路由器。
|
||||
func (m *RuntimeLLM) RouteRequest(req Request) (string, bool) {
|
||||
r := m.load().router
|
||||
if r == nil {
|
||||
@@ -157,9 +157,9 @@ func (m *RuntimeLLM) RouteRequest(req Request) (string, bool) {
|
||||
return r.RouteRequest(req)
|
||||
}
|
||||
|
||||
// RouteRequestForPersona implements PersonaRouter (裁决 03.4.1): the loop routes
|
||||
// a turn as the persona it answers as, and a per-persona binding in the active
|
||||
// models.json group reaches the request through here.
|
||||
// RouteRequestForPersona 实现 PersonaRouter（裁决 03.4.1）：loop 以
|
||||
// 本回合作答所依据的 persona 来路由，生效 models.json 组里的
|
||||
// 按 persona 绑定经由这里到达请求。
|
||||
func (m *RuntimeLLM) RouteRequestForPersona(personaID string, req Request) (string, bool) {
|
||||
r := m.load().router
|
||||
if r == nil {
|
||||
@@ -168,8 +168,8 @@ func (m *RuntimeLLM) RouteRequestForPersona(personaID string, req Request) (stri
|
||||
return r.RouteRequestForPersona(personaID, req)
|
||||
}
|
||||
|
||||
// loadInitial builds the first snapshot; a build failure leaves a nil chain so
|
||||
// calls report a clear no-model error instead of panicking.
|
||||
// loadInitial 构建首个快照；构建失败会留下 nil 链，
|
||||
// 使调用报告清晰的「无模型」错误而不是 panic。
|
||||
func (m *RuntimeLLM) loadInitial() {
|
||||
groups, warn := runtimeconfig.LoadModels(m.path, m.env)
|
||||
if warn != nil {
|
||||
@@ -178,8 +178,8 @@ func (m *RuntimeLLM) loadInitial() {
|
||||
_ = m.swap(groups)
|
||||
}
|
||||
|
||||
// swap rebuilds and atomically stores a snapshot for groups. A blank slice falls
|
||||
// back to the env-synthesized group so there is always at least one.
|
||||
// swap 为 groups 重建快照并原子存储。空切片会回
|
||||
// 退到 env 合成的组，因此始终至少有一个组。
|
||||
func (m *RuntimeLLM) swap(groups []runtimeconfig.Group) error {
|
||||
if len(groups) == 0 {
|
||||
groups = runtimeconfig.GroupFromEnv(m.env)
|
||||
@@ -192,8 +192,8 @@ func (m *RuntimeLLM) swap(groups []runtimeconfig.Group) error {
|
||||
return nil
|
||||
}
|
||||
|
||||
// load returns the current snapshot, or an empty (nil chain) one when the
|
||||
// manager was never initialized.
|
||||
// load 返回当前快照；管理器从未初始化时返回一个空
|
||||
// （nil 链）快照。
|
||||
func (m *RuntimeLLM) load() *runtimeChainSnapshot {
|
||||
if v := m.current.Load(); v != nil {
|
||||
return v.(*runtimeChainSnapshot)
|
||||
@@ -201,18 +201,18 @@ func (m *RuntimeLLM) load() *runtimeChainSnapshot {
|
||||
return &runtimeChainSnapshot{}
|
||||
}
|
||||
|
||||
// buildSnapshot turns the active group (index 0) into a chain+router. A group
|
||||
// without a base URL/model yields a nil chain (no model configured), surfaced as
|
||||
// ErrNoModel by the adapter methods.
|
||||
// buildSnapshot 把生效组（下标 0）变成链+路由器。没有
|
||||
// base URL/模型的组会产出 nil 链（未配置模型），由适配器
|
||||
// 方法表现为 ErrNoModel。
|
||||
//
|
||||
// The env-local rung is copied onto the group's flat config because a models.json
|
||||
// group does not carry it: without that copy the third degradation level
|
||||
// (裁决 03.4.3) would silently disappear as soon as models.json exists.
|
||||
// env 本地级会被复制到组的扁平配置上，因为 models.json
|
||||
// 的组不携带它：没有这次复制，第三级降级
|
||||
// （裁决 03.4.3）只要 models.json 一存在就会静默消失。
|
||||
//
|
||||
// The router is seeded with the active group's per-persona bindings
|
||||
// (裁决 03.4.1). It is deliberately NOT given the env vision model: image routing
|
||||
// is owned by vision.Router, and a "has image → switch model" rule here bypassed
|
||||
// that decision (裁决 14.4.1/14.4.5).
|
||||
// 路由器以生效组的按 persona 绑定播种
|
||||
// （裁决 03.4.1）。它刻意不给 env 的视觉模型：图像路由
|
||||
// 归 vision.Router 所有，而这里曾有的「带图 → 切换模型」规则绕过了
|
||||
// 那个决策（裁决 14.4.1/14.4.5）。
|
||||
func buildSnapshot(groups []runtimeconfig.Group, env config.LLMConfig, log *slog.Logger) (*runtimeChainSnapshot, error) {
|
||||
active := groups[0]
|
||||
cfg := active.ToLLMConfig()
|
||||
@@ -222,9 +222,9 @@ func buildSnapshot(groups []runtimeconfig.Group, env config.LLMConfig, log *slog
|
||||
return nil, err
|
||||
}
|
||||
if chain != nil {
|
||||
// Budgets are resolved inside the chain: the active group's own
|
||||
// maxTokens (models.json) wins, and env.FallbackMaxTokens only caps the
|
||||
// last step of a chain that really has a fallback (design/04 §3.1).
|
||||
// 预算在链内部解出：生效组自己的
|
||||
// maxTokens（models.json）优先，env.FallbackMaxTokens 只约束
|
||||
// 确实有降级步骤的链的最后一步（design/04 §3.1）。
|
||||
chain = chain.WithTokenBudget(active.MaxTokens, env.FallbackMaxTokens)
|
||||
}
|
||||
router := NewRouter(DefaultModelForProvider(cfg), personaRouterOptions(active, cfg)...)
|
||||
@@ -237,17 +237,17 @@ func buildSnapshot(groups []runtimeconfig.Group, env config.LLMConfig, log *slog
|
||||
}, nil
|
||||
}
|
||||
|
||||
// personaProviderChains builds one chain per protocol that the active group's
|
||||
// personaProviders declares and that models.json actually provides a group for
|
||||
// (裁决 03.4.1 的 per-persona provider：跨协议换 adapter). The persona's own
|
||||
// model name is pinned as the chain's primary model, so a caller that stamps the
|
||||
// persona without a routed model name still reaches the right endpoint.
|
||||
// personaProviderChains 为生效组 personaProviders 声明的、且
|
||||
// models.json 确实提供了对应组的每种协议各构建一条链
|
||||
// （裁决 03.4.1 的 per-persona provider：跨协议换 adapter）。persona 自己的
|
||||
// 模型名被钉为该链的主模型，因此即便调用方打上的
|
||||
// persona 没带被路由的模型名，也仍能到达正确端点。
|
||||
//
|
||||
// A persona that names the same protocol as the active group needs no chain of
|
||||
// its own: the default chain already speaks that protocol, and the per-persona
|
||||
// model name reaches it through the router. A personaProviders entry whose
|
||||
// protocol has no group is reported and skipped — a half-built chain could only
|
||||
// fail, and the persona keeps the default chain instead.
|
||||
// 与生效组同协议的 persona 不需要自己
|
||||
// 的链：默认链本就说那个协议，而按 persona 的
|
||||
// 模型名经路由器到达它。personaProviders 中协议
|
||||
// 没有对应组的条目会被上报并跳过——半构建的链只会
|
||||
// 失败，该 persona 改为保留默认链。
|
||||
func personaProviderChains(groups []runtimeconfig.Group, active runtimeconfig.Group, env config.LLMConfig, log *slog.Logger) map[string]*Chain {
|
||||
if len(active.PersonaProviders) == 0 {
|
||||
return nil
|
||||
@@ -283,12 +283,12 @@ func personaProviderChains(groups []runtimeconfig.Group, active runtimeconfig.Gr
|
||||
return out
|
||||
}
|
||||
|
||||
// personaChain builds and budgets the chain serving one persona through another
|
||||
// vendor's group: the group's flat config with the persona's own model name as
|
||||
// the primary model, plus the shared local last rung. The reasoning shape
|
||||
// (reasoning.kind) travels with the group's config, so a persona routed to
|
||||
// another vendor keeps that vendor's switch shape. It reports the reason and
|
||||
// returns nil when the group cannot serve a chain.
|
||||
// personaChain 构建并通过另一厂商的组服务某个 persona 的链，并
|
||||
// 为其定预算：组的扁平配置，persona 自己的模型名作为
|
||||
// 主模型，加上共享的本地最后一级。推理形状
|
||||
// （reasoning.kind）随组的配置一起走，因此被路由到
|
||||
// 另一厂商的 persona 仍保持该厂商的开关形状。它会报告原因，
|
||||
// 并在该组无法服务一条链时返回 nil。
|
||||
func personaChain(g runtimeconfig.Group, model string, env config.LLMConfig, log *slog.Logger) *Chain {
|
||||
cfg := g.ToLLMConfig()
|
||||
if cfg.Provider == ProviderAnthropic {
|
||||
@@ -310,10 +310,10 @@ func personaChain(g runtimeconfig.Group, model string, env config.LLMConfig, log
|
||||
return chain.WithTokenBudget(g.MaxTokens, env.FallbackMaxTokens)
|
||||
}
|
||||
|
||||
// groupForProvider returns the first group speaking the given protocol. The group
|
||||
// order in models.json is the operator's choice, so "first match" is a stable,
|
||||
// documentable rule rather than a silent pick — a duplicate protocol is reported
|
||||
// by the builder when it matters.
|
||||
// groupForProvider 返回第一条说指定协议的组。models.json 里
|
||||
// 组的顺序由运维者决定，所以「第一个匹配」是一条稳定、
|
||||
// 可记录的规则，而不是一次静默挑选——重复协议会在
|
||||
// 要紧的时候由构建器上报。
|
||||
func groupForProvider(groups []runtimeconfig.Group, provider string) (runtimeconfig.Group, bool) {
|
||||
for _, g := range groups {
|
||||
if g.Provider == provider {
|
||||
@@ -323,9 +323,9 @@ func groupForProvider(groups []runtimeconfig.Group, provider string) (runtimecon
|
||||
return runtimeconfig.Group{}, false
|
||||
}
|
||||
|
||||
// personaRouterOptions turns the active group's per-persona model/provider
|
||||
// bindings into router options (裁决 03.4.1). It is a helper so buildSnapshot
|
||||
// stays inside the 80-line function budget.
|
||||
// personaRouterOptions 把生效组的按 persona 模型/提供商
|
||||
// 绑定转换成 router 选项（裁决 03.4.1）。它是一个辅助函数，好让 buildSnapshot
|
||||
// 留在 80 行函数预算之内。
|
||||
func personaRouterOptions(active runtimeconfig.Group, cfg config.LLMConfig) []RouterOption {
|
||||
opts := []RouterOption{WithDefaultProvider(cfg.Provider)}
|
||||
for persona, model := range active.PersonaModels {
|
||||
|
||||
Reference in new issue
Block a user