fix(protocol): Claude Desktop local-agent — claude_code_only 不误判 OMP (#511)

[dofastted]

摘要

复刻已关闭 fork dofastted/vm2api#511（HEAD a120f38），在上游开干净 PR。

Supersedes

• Fork PR fix(protocol): recognize Claude Desktop local-agent requests #511（fork 已关，无法合并）
• 上游 fix(protocol): recognize Claude Desktop local-agent requests (#511 upstream) #512（占位 @file:/workspace/... 损坏，已关闭）

变更

• docs/PROTOCOL.md — 协议说明
• src/lib/identity/claude-code-only.mjs — 入口判定
• src/lib/identity/crs-persona.mjs — Desktop local-agent 指纹（UA / agent-sdk / desktop_app / anthropic-client-version）
• test/unit/claude-code-only.test.mjs — 单元测试
• CHANGELOG.md — 未发布 追加 fix(protocol): recognize Claude Desktop local-agent requests #511 条目

Claude Desktop local-agent（UA 含 local-agent 与 agent-sdk、平台 desktop_app、合法 anthropic-client-version）不再仅凭 cc_entrypoint=local-agent 判成 OMP，避免 claude_code_only 误 403；OMP 专属与 body-only relay 仍保守。

自检

• git diff origin/main --stat：5 文件，+92/−10
• rg '@file:|file:/workspace' 变更文件：0 命中
• biome format 已跑
• node --test test/unit/claude-code-only.test.mjs：16/16 通过

未做

• 未改 VERSION
• 无 tip-cut / tip 188
• 未动 fix: reuse search-history repairs and align Claude 2.1.296 #517（search-history，无关）

---

Note

Medium Risk
改动入站身份与 claude_code_only 403 边界，错误指纹可能误放第三方或误拦 Desktop；OMP 排除逻辑仍保守，但需依赖请求头完整性。

Overview
Claude Desktop local-agent 在开启 claude_code_only 时不再被当成 Oh My Pi / OMP，从而避免误 403。

原先只要 system 里出现 cc_entrypoint=local-agent 就会走 looksLikeOhMyPiSystem，和 OMP 共用同一套 OAuth 隐身前缀，Desktop 也会被挡在官方 Claude Code 家族之外。现在 looksLikeOhMyPiSystem 会结合请求头：UA 含 local-agent 与 agent-sdk/x.y.z、anthropic-client-platform: desktop_app、合法的 anthropic-client-version 时，不再仅凭 local-agent entrypoint 判 OMP，而是继续走 isOfficialClaudeCodeTraffic / isClaudeCodeFamilyRequest 等既有校验。OMP 专属 system 标记、缺头、会话/版本不一致、OpenAI tools 等仍会拒绝。

isOfficialClaudeCodeTraffic 与 looksLikeOfficialClaudeSystem 把 headers 传入 OMP 判定；docs/PROTOCOL.md 与 未发布 CHANGELOG 已同步说明。新增单元与协议层测试覆盖 Desktop 放行、count_tokens 头契约，以及 OMP 叠加 system 仍被拦。

^{Reviewed by Cursor Bugbot for commit e64fa5d. Configure here.}