doc

Author: cuipengfei

src/lib/AGENTS.md

@@ -32,6 +32,8 @@
 - `config.ts` 同时承载 provider 配置：`providers.<name>.baseUrl/apiKey/models.<model>.{temperature,topP,topK}`；取用时统一走 `getProviderConfig()`，不要在路由里手动 trim/校验
 - `paths.ts` 支持 `COPILOT_API_HOME` 覆盖默认目录；改路径逻辑时要兼顾 Windows/WSL 使用方式
 - `token.ts` 的刷新循环和 telemetry 初始化耦合，改认证链路时别漏 `trackAuthNewToken()` / `initTelemetry()`
+- `auto-session.ts` 当前只管理 `/models/session` 返回的 `session_token` / `available_models` 缓存；不要把它误当完整 Auto Router。若要处理 `Invalid auto-mode selector` 或模型选择异常，必须把 `/models/session/intent` 与最终 upstream request 一起验证。
+- `Copilot-Session-Token` 可能与生成它时的 Copilot auth/account context 绑定；改 `token.ts`、认证刷新或账户切换逻辑时，要检查 auto-session cache 是否需要失效，避免旧 session token 搭配新 auth token。
 - `smart-agent.ts` 只缓存 `forceAgent=true` 之决断；“尚在预算之内”不作缓存之项
 - `api-config.ts` 组装请求头后被三个 `create-*` service 共享调用，不要在 service 内重复构造 header
 - `logger.ts` 的 `getPremiumInfo()` / `formatStreamLog()` 现在被 chat-completions、messages、responses 三条路由共用；progress log 可以失败，但不能改写 SSE/JSON 响应内容

src/services/copilot/AGENTS.md

@@ -26,6 +26,8 @@
 - 三个 `create-*` service 各自生成 `modelCallId`（UUID）传入 telemetry，用于单次调用追踪
 - `create-chat-completions.ts`、`create-messages.ts`、`create-responses.ts` 现在都必须附着 upstream response headers，供 route 层最终转发；不要只返回 body / stream 而丢掉原始 headers
 - premium info 与 upstream response headers 是两条并行元数据链：前者走 `attachPremiumInfo()`，后者走 `attachResponseHeaders()`；不要用一个字段偷带另一个概念
+- 排查 Auto 模型问题时，不要只看本地 wrapper 日志。`Invalid auto-mode selector` 需要按后端链路验证：`/models/session` → `/models/session/intent` → final `responses/messages/chat` request；对比不带、带新、带旧/跨 auth 的 `Copilot-Session-Token`，并脱敏所有 token 原值。
+- 三条 `create-*` service 只应在模型命中当前 `available_models` 时附着 `Copilot-Session-Token`；如果未来接入 `/models/session/intent` 的 `chosen_model`，要把 selector/session-token 绑定语义收口在 service/lib 边界，不要在 route handler 分散实现。
 
 ## Native Messages Gotchas