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
@@ -2,22 +2,22 @@ package model
|
||||
|
||||
import "strings"
|
||||
|
||||
// Router maps roles to model names. An unknown role resolves to the configured
|
||||
// default model. A Router also carries a provider per role (defaulting to the
|
||||
// global provider) so a multi-vendor deployment can pair a role's model with the
|
||||
// correct protocol; the provider selection is surfaced via RouteProvider.
|
||||
// Router 把角色映射到模型名。未知角色解析为已配置的
|
||||
// 默认模型。Router 还按角色携带一个提供商（默认用
|
||||
// 全局提供商），好让多厂商部署能把角色的模型与
|
||||
// 正确协议配对；提供商选择通过 RouteProvider 暴露。
|
||||
//
|
||||
// Per 裁决 03.4.1 the "role" of per-role routing is the **persona** a turn
|
||||
// answers as, not the LLM message role: a persona binding wins over the
|
||||
// message-role binding, and a persona without a binding keeps the previous
|
||||
// behavior. The binding carrier is the active models.json group
|
||||
// (runtimeconfig.Group.PersonaModels / PersonaProviders).
|
||||
// 按裁决 03.4.1，按角色路由里的「角色」是本回合以之
|
||||
// 作答的 **persona**，而不是 LLM 消息角色：persona 绑定优先于
|
||||
// 消息角色绑定，而未绑定的 persona 保持原有
|
||||
// 行为。绑定的载体是生效的 models.json 组
|
||||
// （runtimeconfig.Group.PersonaModels / PersonaProviders）。
|
||||
//
|
||||
// Image routing is deliberately NOT this router's job any more (裁决
|
||||
// 14.4.1/14.4.5): the single authority for layered image routing is
|
||||
// runtime/multimodal/vision.Router, which the loop calls with the main model's
|
||||
// real image-input capability. A "has image → switch to the vision model" rule
|
||||
// here used to bypass that decision.
|
||||
// 图像路由刻意不再是本 Router 的职责（裁决
|
||||
// 14.4.1/14.4.5）：分层图像路由的唯一权威是
|
||||
// runtime/multimodal/vision.Router，由 loop 带着主模型真实的
|
||||
// 图像输入能力去调用它。这里曾有的「带图 → 切到视觉模型」规则
|
||||
// 绕过了那个决策。
|
||||
type Router struct {
|
||||
defaultModel string
|
||||
byRole map[Role]string
|
||||
@@ -28,25 +28,25 @@ type Router struct {
|
||||
personaProvider map[string]string
|
||||
}
|
||||
|
||||
// RouterOption configures a Router.
|
||||
// RouterOption 用于配置 Router。
|
||||
type RouterOption func(*Router)
|
||||
|
||||
// WithRoleModel binds a model to a role.
|
||||
// WithRoleModel 把模型绑定到角色。
|
||||
func WithRoleModel(role Role, model string) RouterOption {
|
||||
return func(r *Router) { r.byRole[role] = model }
|
||||
}
|
||||
|
||||
// WithVisionModel configures the dedicated vision model. It is kept for
|
||||
// backwards compatibility (tests and callers that route a pure image request by
|
||||
// model name) but production no longer sets it: image routing belongs to
|
||||
// vision.Router (裁决 14.4.1/14.4.5).
|
||||
// WithVisionModel 配置专用视觉模型。它保留下来是为了
|
||||
// 向后兼容（测试与按模型名路由纯图像请求的调用方），
|
||||
// 但生产路径不再设置它：图像路由属于
|
||||
// vision.Router（裁决 14.4.1/14.4.5）。
|
||||
func WithVisionModel(model string) RouterOption {
|
||||
return func(r *Router) { r.visionModel = model }
|
||||
}
|
||||
|
||||
// WithPersonaModel binds a model to a persona (裁决 03.4.1). A blank persona or
|
||||
// model is ignored so a partially configured group cannot create a binding that
|
||||
// routes a persona to an empty model.
|
||||
// WithPersonaModel 把模型绑定到 persona（裁决 03.4.1）。空的 persona 或
|
||||
// 模型会被忽略，因此半配置的组无法造出一个把 persona 路由到
|
||||
// 空模型的绑定。
|
||||
func WithPersonaModel(persona, model string) RouterOption {
|
||||
return func(r *Router) {
|
||||
if p := trimKey(persona); p != "" && model != "" {
|
||||
@@ -55,9 +55,9 @@ func WithPersonaModel(persona, model string) RouterOption {
|
||||
}
|
||||
}
|
||||
|
||||
// WithPersonaProvider binds a vendor protocol to a persona, so one persona can
|
||||
// answer through a different vendor than the group default (裁决 03.4.1). Pair it
|
||||
// with WithPersonaModel.
|
||||
// WithPersonaProvider 把厂商协议绑定到 persona，这样一个 persona 可以
|
||||
// 走与组默认不同的厂商作答（裁决 03.4.1）。请与
|
||||
// WithPersonaModel 配对使用。
|
||||
func WithPersonaProvider(persona, provider string) RouterOption {
|
||||
return func(r *Router) {
|
||||
if p := trimKey(persona); p != "" && provider != "" {
|
||||
@@ -66,21 +66,21 @@ func WithPersonaProvider(persona, provider string) RouterOption {
|
||||
}
|
||||
}
|
||||
|
||||
// WithDefaultProvider sets the provider returned by RouteProvider for roles with
|
||||
// no explicit binding. It defaults to openai.
|
||||
// WithDefaultProvider 设置 RouteProvider 对没有显式绑定的角色
|
||||
// 返回的提供商。它默认是 openai。
|
||||
func WithDefaultProvider(provider string) RouterOption {
|
||||
return func(r *Router) { r.defaultProvider = provider }
|
||||
}
|
||||
|
||||
// WithRoleProvider binds a provider to a role, so a multi-vendor deployment can
|
||||
// route a role to a different vendor's protocol (e.g. one role on anthropic, one
|
||||
// on openai). Pair it with WithRoleModel for the role's model name.
|
||||
// WithRoleProvider 把提供商绑定到角色，好让多厂商部署
|
||||
// 能把角色路由到另一厂商的协议（例如一个角色走 anthropic、一个
|
||||
// 走 openai）。请与 WithRoleModel 配对以给出该角色的模型名。
|
||||
func WithRoleProvider(role Role, provider string) RouterOption {
|
||||
return func(r *Router) { r.providerByRole[role] = provider }
|
||||
}
|
||||
|
||||
// NewRouter builds a Router with a default model applied to any role that has
|
||||
// no explicit binding.
|
||||
// NewRouter 构建 Router，并对任何没有显式绑定的角色
|
||||
// 套用默认模型。
|
||||
func NewRouter(defaultModel string, opts ...RouterOption) *Router {
|
||||
r := &Router{
|
||||
defaultModel: defaultModel,
|
||||
@@ -96,11 +96,11 @@ func NewRouter(defaultModel string, opts ...RouterOption) *Router {
|
||||
return r
|
||||
}
|
||||
|
||||
// trimKey normalizes a persona id or provider name before it is stored, so
|
||||
// " cyrene" and "cyrene" cannot become two different bindings.
|
||||
// trimKey 在存入之前归一化 persona id 或提供商名，因此
|
||||
// " cyrene" 与 "cyrene" 不会变成两个不同的绑定。
|
||||
func trimKey(k string) string { return strings.TrimSpace(k) }
|
||||
|
||||
// Route returns the model for a role, falling back to the default model.
|
||||
// Route 返回角色的模型，回退到默认模型。
|
||||
func (r *Router) Route(role Role) string {
|
||||
if m, ok := r.byRole[role]; ok && m != "" {
|
||||
return m
|
||||
@@ -108,11 +108,11 @@ func (r *Router) Route(role Role) string {
|
||||
return r.defaultModel
|
||||
}
|
||||
|
||||
// RouteProvider returns the provider for a role, falling back to the router's
|
||||
// default provider. It is the routing hook for a multi-vendor deployment: each
|
||||
// role can carry its own provider+model pairing, and roles without a binding fall
|
||||
// back to the global provider. The runtime/loop is expected to build a per-role
|
||||
// adapter or chain from this decision (the provider-aware factory is the builder).
|
||||
// RouteProvider 返回角色的提供商，回退到 Router 的
|
||||
// 默认提供商。它是多厂商部署的路由钩子：每个
|
||||
// 角色可以携带自己的提供商+模型配对，而未绑定的角色回
|
||||
// 退到全局提供商。runtime/loop 应据该决策构建按角色的
|
||||
// 适配器或链（提供商感知工厂就是构建器）。
|
||||
func (r *Router) RouteProvider(role Role) string {
|
||||
if p, ok := r.providerByRole[role]; ok && p != "" {
|
||||
return p
|
||||
@@ -120,16 +120,16 @@ func (r *Router) RouteProvider(role Role) string {
|
||||
return r.defaultProvider
|
||||
}
|
||||
|
||||
// RouteRequest picks the model for a request and reports whether the request
|
||||
// carries image content. When the request carries image content and a vision
|
||||
// model is configured, the vision model is returned with needsVision set to
|
||||
// true. Otherwise the role of the last message drives routing (user by
|
||||
// default).
|
||||
// RouteRequest 为请求挑出模型，并报告该请求
|
||||
// 是否携带图像内容。当请求携带图像内容且已配置
|
||||
// 视觉模型时，返回视觉模型并把 needsVision 置为
|
||||
// true。否则由最后一条消息的角色驱动路由（默认
|
||||
// user）。
|
||||
//
|
||||
// Deprecated in the production path: the loop routes by persona via
|
||||
// RouteRequestForPersona, and image routing belongs to vision.Router (裁决
|
||||
// 14.4.1/14.4.5). This method stays because it is the ModelRouter contract the
|
||||
// agent package and the existing tests are built on.
|
||||
// 在生产路径中已弃用：loop 改经
|
||||
// RouteRequestForPersona 按 persona 路由，图像路由属于 vision.Router（裁决
|
||||
// 14.4.1/14.4.5）。本方法保留是因为 agent 包与
|
||||
// 既有测试都建立在 ModelRouter 契约之上。
|
||||
func (r *Router) RouteRequest(req Request) (model string, needsVision bool) {
|
||||
role := RoleUser
|
||||
if n := len(req.Messages); n > 0 {
|
||||
@@ -142,18 +142,18 @@ func (r *Router) RouteRequest(req Request) (model string, needsVision bool) {
|
||||
return r.Route(role), needsVision
|
||||
}
|
||||
|
||||
// PersonaRouter is the optional persona-aware routing extension of ModelRouter
|
||||
// (裁决 03.4.1). The loop detects it on the agent's router and prefers it over
|
||||
// RouteRequest, so a per-persona model/provider binding actually reaches the
|
||||
// request. It is a separate interface so a router that only knows message roles
|
||||
// keeps working unchanged.
|
||||
// PersonaRouter 是 ModelRouter 可选的 persona 感知路由扩展
|
||||
// （裁决 03.4.1）。loop 会在 agent 的 router 上探测它，并优先于
|
||||
// RouteRequest 使用，从而让按 persona 的模型/提供商绑定真正到达
|
||||
// 请求。它单列为一个接口，好让只知道消息角色的 router
|
||||
// 保持可用、不被改动。
|
||||
type PersonaRouter interface {
|
||||
RouteRequestForPersona(personaID string, req Request) (model string, needsVision bool)
|
||||
}
|
||||
|
||||
// RouteForPersona returns the model bound to persona, falling back to the
|
||||
// router's default model. Unlike Route (message role) this is the persona-level
|
||||
// binding: 裁决 03.4.1 defines the "role" of per-role routing as the persona.
|
||||
// RouteForPersona 返回绑定到 persona 的模型，回退到
|
||||
// Router 的默认模型。与 Route（消息角色）不同，这是 persona 级
|
||||
// 绑定：裁决 03.4.1 把按角色路由的「角色」定义为 persona。
|
||||
func (r *Router) RouteForPersona(persona string) string {
|
||||
if m, ok := r.personaModel[trimKey(persona)]; ok && m != "" {
|
||||
return m
|
||||
@@ -161,8 +161,8 @@ func (r *Router) RouteForPersona(persona string) string {
|
||||
return r.defaultModel
|
||||
}
|
||||
|
||||
// RouteProviderForPersona returns the provider bound to persona, falling back to
|
||||
// the router's default provider (itself the active group's protocol).
|
||||
// RouteProviderForPersona 返回绑定到 persona 的提供商，回退到
|
||||
// Router 的默认提供商（其本身即生效组的协议）。
|
||||
func (r *Router) RouteProviderForPersona(persona string) string {
|
||||
if p, ok := r.personaProvider[trimKey(persona)]; ok && p != "" {
|
||||
return p
|
||||
@@ -170,11 +170,11 @@ func (r *Router) RouteProviderForPersona(persona string) string {
|
||||
return r.defaultProvider
|
||||
}
|
||||
|
||||
// RouteRequestForPersona routes a request as the given persona: a persona
|
||||
// binding wins over the message-role decision, and a persona without a binding
|
||||
// falls back to RouteRequest so nothing changes for the unconfigured case. It
|
||||
// reports whether the request carries an image, but never switches the model to
|
||||
// the vision model — that decision belongs to vision.Router (裁决 14.4.1/14.4.5).
|
||||
// RouteRequestForPersona 以给定 persona 路由请求：persona
|
||||
// 绑定优先于消息角色决策，而没有绑定的 persona
|
||||
// 回退到 RouteRequest，因此未配置的情形毫无变化。它
|
||||
// 报告请求是否携带图片，但绝不会把模型切到
|
||||
// 视觉模型——那个决策属于 vision.Router（裁决 14.4.1/14.4.5）。
|
||||
func (r *Router) RouteRequestForPersona(personaID string, req Request) (model string, needsVision bool) {
|
||||
needsVision = HasImage(req.Messages)
|
||||
if m, ok := r.personaModel[trimKey(personaID)]; ok && m != "" {
|
||||
@@ -187,7 +187,7 @@ func (r *Router) RouteRequestForPersona(personaID string, req Request) (model st
|
||||
return r.Route(role), needsVision
|
||||
}
|
||||
|
||||
// HasImage reports whether any message carries an image content part.
|
||||
// HasImage 报告是否有任何消息携带图片内容片段。
|
||||
func HasImage(msgs []Message) bool {
|
||||
for _, m := range msgs {
|
||||
for _, part := range m.Content {
|
||||
|
||||
Reference in new issue
Block a user