[Design]: generic client preferences propagation (locale, timezone, etc.) — beyond _meta

[Million-mo]

背景

PR #128 通过 ACP initialize 的 _meta 字段传入 locale，实现了 i18n。功能方向正确，但字段设计需要讨论。

需要讨论的几个问题

1. 约定合适的字段

ACP 协议（v1）的 initialize 请求结构中没有任何多语言/locale 相关字段。协议层面的字段只有：protocolVersion、clientCapabilities（fs/terminal/elicitation/configOptions）、clientInfo（name/title/version）、_meta（扩展点）。

_meta 是 ACP 协议中 AnnotatedObject 的扩展点（field_meta），设计用途就是传递实现特定的附加信息。ACP 官方文档也确认，自定义能力可以通过 _meta 字段广告扩展支持。协议层面没有其他字段可以用来传 locale。

建议：继续用 _meta，但约定一个明确的 key 和文档：

"_meta": { "locale": "zh-CN" }

• key 就叫 locale，值为 BCP 47 语言标签（en、zh-CN、ja-JP）
• 在 ACP initialize response 中可以回传支持的 locale 列表，让客户端知道服务端支持哪些语言
• 在代码中用结构化的方式提取（一个 _extract_locale() 函数），而不是散落在各处

2. 配置如何通过 initialize 生效

PR #128 的链路是对的：

client initialize (_meta.locale)
  → AgentPoolACPAgent.initialize() 提取 locale
  → 透传到 ACPSessionManager.create_session() / resume_session()
  → ACPSession.client_locale
  → 注入 callable system prompt

这个链路保持不变。唯一要确认的是：locale 应该是 per-connection（initialize 时设定，整个连接生效）还是 per-session（new_session 时可以覆盖）？

建议：per-connection 为主（简单），后续如果需要 per-session 覆盖再加。

3. 环境变量控制的必要性

结论：不需要环境变量。

理由：

• locale 是客户端偏好，客户端切换语言后通过 initialize 通知即可，不需要服务端环境变量
• 环境变量适合"服务端默认值"场景（见下），但不应作为客户端偏好的传递通道
• 如果客户端没传 locale，应该走服务端默认配置（YAML），而不是环境变量

4. agentpool ACP 服务如何配置默认语言

当客户端没有在 initialize 中传 locale 时，agentpool 应该有一个默认值。这个默认值应该在 YAML 配置中设定。

建议：在 ACP server 配置或 agent 配置中加 default_locale 字段：

# 方案 A：server 级别默认
servers:
  acp:
    default_locale: zh-CN

# 方案 B：agent 级别默认
agents:
  assistant:
    default_locale: zh-CN
    system_prompt: "You are a helpful assistant."

优先级：_meta.locale（客户端传入）> default_locale（YAML 配置）> 无（agent 自行决定语言）

方案 A 更简单（一个服务一个默认语言），方案 B 更灵活（不同 agent 可以有不同默认语言）。倾向方案 A，除非有明确的 per-agent 语言差异需求。

5. 是否需要注入到 Jinja2 模板

结论：不需要。维持 PR #128 的 callable prompt 方式。

当前 system prompt 有两种渲染机制：

• Jinja2 模板渲染（format_system_prompt()）：在 sys_prompts.py 中，渲染时传入 agent、prompts、dynamic 等框架内部变量，面向的是 YAML 配置层面的静态模板渲染。
• Callable prompt：pydantic-ai 在每次 model call 时调用 callable 函数，返回动态字符串拼到 system prompt 中。get_cwd_context 就是这个模式。

不注入 Jinja2 的理由：

1. locale 是 per-connection 的运行时值，不是 YAML 配置时已知的静态值。把 client_locale 塞进 Jinja2 渲染上下文会让模板变量承担不属于它的职责。
2. callable prompt 已经够用。PR feat(acp): support locale injection via ACP initialize for i18n #128 的 get_locale_prompt() 返回 "Language: You MUST respond in {locale}."，每次 model call 时执行，简单直接，与 get_cwd_context 同构。
3. 不是所有 agent 都需要 locale 注入。用 callable prompt 时，只有客户端传了 locale 才追加这段 prompt；如果注入 Jinja2 变量，所有 agent 的模板都要改才能生效，反而增加了耦合。

总结

问题	建议
字段	_meta.locale，BCP 47 格式，文档化
生效机制	PR #128 现有链路不变
环境变量	不需要
默认语言	YAML default_locale，server 级别
Jinja2 注入	不需要，维持 callable prompt

Related

• PR feat(acp): support locale injection via ACP initialize for i18n #128: feat(acp): support locale injection via ACP initialize for i18n

[Million-mo]

i18n 方案总结：现状、问题、解决方案、遗留问题与风险

基于 PR #128 的实现、Issue #131 的设计讨论，以及与 xeno-agent 现有 {{LANG}} 机制的综合分析，汇总如下。

---

一、现状

agentpool 框架层：零 i18n 基础设施。无 locale 协商、无语言路由、无输出语言验证。system prompt 中的语言指令完全由 YAML 配置决定，客户端无法在运行时指定语言偏好。

xeno-agent 业务层：已有 {{LANG}} Jinja2 变量机制。每个 agent 的角色模板（如 fault_expert.j2）中包含 You should always speak and think in the "{{LANG}}" language.，值通过 FilePromptConfig.variables 在 YAML 中硬编码为 简体中文(zh-CN)。这是设计时的静态配置，无法运行时切换。

PR #128：通过 ACP initialize 的 _meta.locale 接收客户端语言偏好，透传到 ACPSession，作为 callable system prompt 注入（"Language: You MUST respond in {locale}."）。建立了 per-connection 的 locale 透传链路。

---

二、问题

2.1 PR #128 无法完全解决 think/output 中英文混杂

中英文混杂有四个根因，PR #128 只覆盖了第一个：

#	根因	PR #128 覆盖	说明
1	系统提示缺乏强制性语言指令	✅	PR 追加了 "You MUST respond in {locale}"，但仍是软指令
2	raw CoT 绕过 system prompt	❌	event_mapper.py 的 _normalize_thinking_event() 直接从 provider_details['raw_content'] 提取推理内容，vLLM/GLM/Kimi 的 raw CoT 经常是英文，不受 system prompt 影响
3	子 agent 委派不传播语言偏好	❌	xeno-agent delegation_provider.py 委派任务时不传递 locale，子 agent 可能使用不同语言
4	无输出语言后处理验证	❌	事件管道中无语言一致性检查，thinking 和 output 语言混合后不被检测或修正

2.2 与 xeno-agent 现有 {{LANG}} 机制冗余

xeno-agent 如果同时保留 YAML {{LANG}} 和 PR #128 的 callable prompt，system prompt 中会出现两条同义语言指令。不会冲突，但无叠加效果——一条软指令不听，两条同样不听。

2.3 缺少 default_locale fallback

PR #128 只实现了客户端传入路径。客户端未传 _meta.locale 时，无语言指令注入，agent 语言不可预测。

2.4 缺少自适应语言检测

部分业务场景下，客户端不显式传 locale，但希望 agent 根据用户输入语言自适应响应。当前无此能力。

---

三、解决方案

3.1 locale 优先级链（四层）

_meta.locale (客户端显式传入)
  ↓ 未传
auto-detect (从用户输入检测语言)
  ↓ 无法判断
default_locale (YAML server 级配置)
  ↓ 未配
无 (agent 自行决定)

原则：显式 > 隐式 > 默认。客户端显式传入覆盖一切；自适应仅在客户端未传时作为智能 fallback；default_locale 是最后的兜底。

3.2 各层实现方案

第一层：客户端 _meta.locale（PR #128 已实现）

• 字段：_meta.locale，BCP 47 格式（en、zh-CN、ja-JP）
• 时机：ACP initialize 时传入，per-connection 生效
• 验证：ASCII alphanumeric + hyphen，max 15 chars（已实现，防 prompt injection）
• 链路：initialize() → ACPSessionManager.create_session() → ACPSession.client_locale → callable prompt 注入

第二层：自适应语言检测（待实现）

• 触发：用户消息进入时，若 client_locale 为空
• 检测：轻量级语言检测（langdetect / fasttext），结果存入 ACPSession.auto_detected_locale
• 注入：复用 PR feat(acp): support locale injection via ACP initialize for i18n #128 的 callable prompt 链路，get_locale_prompt() 优先用 client_locale，其次 auto_detected_locale
• 可配置：检测策略（首条消息锁定 vs 每轮跟随）、置信度阈值、检测工具可选
• 注意：显式 client_locale 不被自适应覆盖

第三层：default_locale YAML 配置（待实现）

• 位置：ACP server 级配置
• 作用：客户端未传 locale 且自适应无法判断时的 fallback
• 优先级：_meta.locale > auto_detected_locale > default_locale > 无

servers:
  acp:
    default_locale: zh-CN

第四层：无 locale（现有行为）

• agent 依据 system prompt 中的已有语言指令（如 xeno-agent 的 {{LANG}}）自行决定
• 框架不注入额外语言指令

3.3 get_locale_prompt() 改造

def get_locale_prompt(self) -> str:
    locale = self.client_locale or self.auto_detected_locale or self.default_locale
    if not locale:
        return ""
    return f"Language: You MUST respond in {locale}."

PR #128 的透传链路完全复用，只是 locale 的来源多了 auto_detected_locale 和 default_locale。

3.4 与 xeno-agent {{LANG}} 的关系

• agentpool 框架定位为多租户通用服务，locale 优先级由客户端 > 自适应 > 默认配置决定
• xeno-agent 如需锁定语言（业务约束不允许运行时覆盖），在 YAML 模板层用 {{LANG}} 固化即可，不依赖框架的 locale 机制
• 两套机制不冲突：框架的 callable prompt 是运行时动态注入，{{LANG}} 是设计时静态渲染。如果 xeno-agent 不需要运行时 locale，不传 _meta.locale 且不配 default_locale 即可，框架不注入任何额外语言指令

3.5 关于 think/output 中英文混杂的深层解决

PR #128 的 locale 注入是基础设施层，解决根因 #1。根因 #2-#4 需要后续独立处理：

根因	解决方向	层级
#2 raw CoT 英文	event_mapper.py 中对 thinking 内容做语言检测/翻译	agentpool 框架
#3 子 agent 不传播 locale	delegation_provider.py 传递 locale 到子 agent	xeno-agent 业务
#4 无输出语言验证	post-turn hook 检测输出语言不一致并触发修正	agentpool 框架

这些不阻塞 PR #128 合入，但应在后续 issue 中跟踪。

---

四、遗留问题

1. default_locale 未实现——PR feat(acp): support locale injection via ACP initialize for i18n #128 缺少 YAML 配置 fallback，客户端未传 locale 时无语言指令。建议在 PR feat(acp): support locale injection via ACP initialize for i18n #128 中补上或拆为紧随的小 PR。
2. 自适应语言检测未实现——第二层优先级链需要额外的检测逻辑和配置项，建议单独 issue 跟踪。
3. think/output 混杂的深层根因未解决——PR feat(acp): support locale injection via ACP initialize for i18n #128 只覆盖根因 feat: add dynamic instructions from ResourceProviders for context… #1，根因 feat(tools): implement extended tool definitions with native Pydantic… #2-feat: add configurable skills loading paths with YAML configuration #4 需要后续 issue。
4. per-session locale 覆盖——当前是 per-connection，未来可能需要 per-session（new_session 时覆盖）。Issue [Design]: generic client preferences propagation (locale, timezone, etc.) — beyond _meta #131 建议后续再加。
5. locale 在 ACP initialize response 中的回传——服务端可回传支持的 locale 列表，让客户端知道服务端支持哪些语言。未实现。

---

五、风险

1. 软指令对 think token 控制力有限——无论 locale 以何种方式注入 system prompt，对 raw CoT / thinking token 的控制都是建议性的。模型的推理语言受训练数据影响，system prompt 的控制力有上限。根因 feat(tools): implement extended tool definitions with native Pydantic… #2 的 event_mapper 层干预可能比 prompt 层更有效。
2. 自适应检测的稳定性——用户首条消息可能过短（如"你好"），语言检测置信度低。短文本误判会导致整个会话语言错误。需要置信度阈值 + 首条消息锁定 vs 每轮跟随的策略选择。
3. 多 agent 切换时的 locale 一致性——switch_active_agent 中已实现 locale prompt 的清理和重新注入，但如果不同 agent 的 YAML 模板有不同的 {{LANG}} 硬编码，可能与框架注入的 locale 冲突。建议业务侧统一：要么用框架 locale 机制，要么用 {{LANG}}，不要混用。
4. prompt injection 已防护但需持续关注——PR feat(acp): support locale injection via ACP initialize for i18n #128 的 _extract_locale() 已做 ASCII 限制和长度限制，但未来如果 locale 需要支持更复杂的格式（如带 script tag 的 zh-Hans-CN），验证逻辑需要同步更新。

---

六、建议的下一步

优先级	行动	关联
P0	PR #128 补 default_locale YAML 配置 fallback	本 issue / PR #128
P1	PR #128 合入	PR #128
P2	新 issue：自适应语言检测设计	本 issue
P2	新 issue：event_mapper thinking 语言处理	根因 #2
P3	新 issue：子 agent locale 传播	根因 #3 / xeno-agent
P3	新 issue：输出语言验证 hook	根因 #4

[Million-mo]

方案讨论：通过校验+重试机制控制 output/think 语言一致性

背景

上文讨论了 event_mapper 层的语言检测/翻译方案。这里补充一个替代思路：复用 pydantic-ai 已有的 schema 校验+重试机制来控制输出语言，并分析其成本和适用性。

机制对比

pydantic-ai 已有两套"校验+重试"机制：

机制	校验对象	代码路径	失败后行为	能控制 think 吗
工具调用校验	ToolCallPart.args	tool_manager._validate_tool_args() → RetryPromptPart	模型重试工具调用	❌
Output schema 校验	agent 返回值	_output.py: OutputSchema.validate() → ModelRetry	模型重试整个输出	❌
Think 事件管道	ThinkingPart.content	event_mapper._normalize_thinking_event()	无校验入口	—（此路径无重试）

关键结论：think 不经过任何校验路径，无法用校验+重试控制。 校验+重试只对 output 和工具参数有效。

方案 A：Output Schema Validator + 重试

在 structured output 的 Pydantic model 上加语言检测 validator：

from pydantic import BaseModel, field_validator
from langdetect import detect

class DiagnosisResult(BaseModel):
    conclusion: str
    evidence: str
    confidence: float

    @field_validator('conclusion', 'evidence')
    @classmethod
    def must_be_chinese(cls, v: str) -> str:
        if len(v) > 50 and detect(v) != 'zh-cn':
            raise ValueError(
                f'Output must be in Chinese (zh-CN), detected {detect(v)}. '
                f'Please rewrite in 简体中文.'
            )
        return v

成本分析：

维度	正常情况（语言合规）	异常情况（语言不合规，触发重试）
额外延迟	langdetect ~微秒级，可忽略	1 次额外 LLM 调用（重试）
额外 token	0	1 次完整 output 的 token
额外依赖	langdetect（纯 Python，~200KB）	同左
框架改动	零（业务层 validator）	同左

优点：

• 零框架改动，纯业务层实现
• 正常情况下零开销（validator 通过即返回）
• 复用 pydantic-ai 已有的 ValidationError → ModelRetry 链路
• 可精确控制哪些字段需要语言一致性

缺点：

• 只对 structured output 有效，text output 无法校验
• think 语言完全不受控——这是根本限制
• 重试后模型可能仍然不合规（受 AgentRetries 上限限制），最终输出可能还是混语言
• langdetect 对短文本不稳定（已加 len(v) > 50 阈值缓解）

方案 B：Think 拦截（event_mapper 层）

在 event_mapper._normalize_thinking_event() 中检测 thinking 内容语言，不匹配时拦截：

def _normalize_thinking_event(event, target_locale=None):
    # ... 现有逻辑提取 text ...
    if text and target_locale:
        if len(text) > 50 and detect(text).split('-')[0] != target_locale.split('-')[0]:
            return None  # 拦截，不发给客户端
    # ... 现有逻辑 ...

成本分析：

维度	正常情况	异常情况（think 语言不匹配）
额外延迟	langdetect ~微秒级	同左（无重试）
额外 token	0	0（不重试）
额外依赖	langdetect	同左
框架改动	event_mapper 需传入 target_locale	同左
用户体验	无变化	think 不可见（标注员看不到推理过程）

优点：

• 零额外 LLM 调用，零 token 成本
• 微秒级延迟
• 简单直接

缺点：

• 丢失 think 可观测性（标注员看不到推理过程）
• 需要 event_mapper 改动（框架层）
• 无法让 think 变成目标语言，只是隐藏

方案 C：Think 翻译（event_mapper + 翻译服务）

在 event_mapper 层对 thinking 内容做翻译：

成本分析：

维度	正常情况	异常情况（think 语言不匹配）
额外延迟	langdetect ~微秒级	翻译服务调用（50-500ms）
额外 token	0	取决于翻译方案（见下）
额外依赖	langdetect + 翻译服务	同左
框架改动	event_mapper + 翻译集成	同左

翻译子方案：

翻译方案	延迟	成本	质量	依赖
复用 agent 的 LLM	1-3s	1 次 LLM 调用 token	高	无额外服务
Google Translate API	50-200ms	按字符计费	中	外部 API + 密钥
DeepL API	100-300ms	按字符计费	高	外部 API + 密钥
本地 NLLB-200 (1.3B)	200-500ms	CPU/GPU 资源	中	模型文件 + torch
本地 M2M-100	200-500ms	CPU/GPU 资源	中	模型文件 + torch

成本对比总览

方案	正常开销	异常开销	框架改动	think 覆盖	output 覆盖
A: Output validator + 重试	~0	1 次 LLM 调用	无	❌	✅
B: Think 拦截	~0	~0	event_mapper	✅（隐藏）	❌
C: Think 翻译	~0	翻译调用	event_mapper + 翻译	✅（翻译）	❌
A + B 组合	~0	1 次 LLM 调用	event_mapper	✅（隐藏）	✅

建议讨论的问题

1. 是否需要在框架层支持 think 语言控制？ 还是作为业务层（如 xeno-agent）的自行实现？

   • 方案 A 纯业务层即可实现，不阻塞 agentpool 框架
   • 方案 B/C 需要 event_mapper 改动，属于框架层

2. think 可观测性 vs 语言一致性的取舍：标注员是否需要看到推理过程？

   • 如果不需要 → 方案 B（拦截）最经济
   • 如果需要 → 方案 C（翻译）或接受 think 英文

3. 是否值得为 think 翻译引入额外服务依赖？

   • 复用 agent LLM 翻译：无新依赖但延迟高（1-3s）
   • 外部翻译 API：低延迟但引入外部依赖和费用
   • 本地小模型：无外部依赖但需要模型加载资源

4. 优先级：output 语言一致性（方案 A）vs think 语言一致性（方案 B/C），哪个对专家标注质量更关键？

   • 如果 output 合规就够 → 先上方案 A（零框架改动），think 后续再议
   • 如果 think 也必须中文 → 需要框架层支持方案 B/C

倾向性建议

方案 A（output validator）+ 方案 B（think 拦截）组合，分两步落地：

1. P0：方案 A——纯业务层，在 xeno-agent 的 output model 上加 language validator，复用 pydantic-ai 重试机制。零框架改动，立即可用
2. P2：方案 B——在 agentpool event_mapper 层加可选的 think 语言过滤，通过 session locale 配置触发。框架层改动，需独立 issue

方案 C（翻译）作为 P3 备选，仅在方案 B 的"think 不可见"无法接受时再考虑。