docs: record cliproxyapi upstream merge workflow

Author: linhay

.agents/skills/gettokens-domain-engineering/SKILL.md

@@ -342,9 +342,22 @@ This skill unifies the technical rules for building, styling, and debugging GetT
 - **Codex Compatibility Ingress**: For OpenAI root-path compatibility needed by Codex-style clients, prefer centralized ingress normalization such as `/models` -> `/v1/models` and `/responses*` -> `/v1/responses*`. Do not scatter duplicate route handlers when a NoRoute rewrite can preserve the existing middleware and handler chain.
 - **Responses Tool Conversion**: The generic Responses-to-Chat converter should accept both flat `function` tool payloads and nested `tools[].function` payloads, and skip invalid function tools without a name.
 - **Reasoning Content Boundary**: Do not inject `reasoning_content` globally in the generic OpenAI Responses converter. Provider-specific response quirks belong in provider normalizers/executors such as the existing Kimi pattern.
+- **Upstream Merge Trigger**: When the user asks to "merge upstream branch", "sync upstream", or "daily merge CLIProxyAPI", treat it as the CLIProxyAPI upstream sync workflow unless they name a different repository. Use the maintained fork at `docs-linhay/references/CLIProxyAPI` and the branch `gettokens/sidecar`.
 - **Workflow**: Sync from canonical upstream -> patch maintenance branch -> rebuild sidecar -> replace binary in `GetTokens.app`.
 - **Binary**: Sidecar binary lives at `build/bin/GetTokens.app/Contents/MacOS/cli-proxy-api`.
 - **Fork Commit Order**: When the fork changes, commit inside `docs-linhay/references/CLIProxyAPI` first, then commit the parent repository gitlink and rebuilt sidecar artifacts. Do not leave the parent pointing at an uncommitted fork state.
+- **Standard Upstream Merge Loop**:
+  1. Check status in both layers: parent repo and fork. Protect unrelated parent changes and only stage the merge closure set.
+  2. In the fork, fetch `upstream` and `origin`; inspect upstream-only commits with `git log --cherry-pick --right-only --no-merges HEAD...upstream/main` before trusting a broad diff.
+  3. Inspect risk with `git diff --stat <old>..upstream/main` and, when useful, `git merge-tree --write-tree HEAD upstream/main` before starting the real merge.
+  4. Run focused baseline tests for the touched risk surfaces before merging when the current fork state is expected to be stable.
+  5. Merge `upstream/main`, resolve conflicts by preserving GetTokens runtime surfaces, then add narrow regressions for accepted upstream behavior that is not already locked by tests.
+  6. Run focused tests, `go test ./...`, and `git diff --check` in the fork; commit and push `origin/gettokens/sidecar`.
+  7. Rerun `./scripts/ensure-sidecar.sh darwin arm64` from the parent repo and confirm the sidecar meta records the new fork commit with `dirty=clean`.
+  8. Update the parent gitlink plus relevant `space`, dev docs, memory, and qmd index; commit only those relevant parent files.
+- **Protected Merge Surfaces**: During upstream sync, explicitly re-check `internal/gettokenshooks`, `internal/gettokensrouting`, `sdk/cliproxy/auth`, Codex WebSocket executor, usage / TTFT / reasoning helpers, system proxy behavior, and config diff visibility.
+- **Timing and Reasoning Hardening**: If upstream changes telemetry, timing, or reasoning extraction, avoid duplicating parsing or TTFT work across call sites. `SetTranslatedReasoningEffort` must not clear context reasoning effort when the translated payload has no config-derived effort. Keep `ttft_ms` as telemetry unless a consuming feature is explicitly scoped.
+- **Codex WebSocket Timing Guard**: When `codex_websockets_executor.go` changes, verify the four timing/live-session events still have a coherent order: `RecordCodexLiveUpstreamConnected`, `RecordCodexLiveFirstEvent`, `StartResponseTTFT`, and `MarkFirstResponseByte`.
 - **Subagent Upstream Audit**: When the fork has drifted far from upstream or the user explicitly asks for subagent review, split read-only subagents by risk surface before merging: overall upstream commit intent, WebSocket / route guard / channel routing, and compatibility areas such as Images / Gemini / translator. Treat `HEAD..upstream/main` mass-deletion diffs as a divergence artifact until each upstream commit is audited with `git log --cherry-pick --right-only` and `git show`.
 - **Audit-to-Test Rule**: If subagent review finds an accepted upstream behavior that is not directly locked by tests, add the narrow fork-side regression before closing the merge. Common examples are config diff visibility, payload model selection, `previous_response_id` cleanup, route guard failover, and provider-specific translator boundaries.
 - **Rebuild Command**: After fork changes that affect runtime behavior, rebuild the local sidecar with `./scripts/ensure-sidecar.sh darwin arm64` before desktop or Proxyman acceptance.

docs-linhay/dev/20260519-cliproxyapi-upstream-sync-session-distillation.md

@@ -101,6 +101,23 @@ git check-ignore -v <path>
 - `server` 文件本体不归档、不提交。
 - 不把该流程升级到 `AGENTS.md`；它属于 CLIProxyAPI fork 领域维护流程，已沉淀到 `gettokens-domain-engineering` skill。
 
+## 2026-05-28 后续触发约定
+
+用户后续只要说“合并上游分支”“同步上游”或“每日合并 CLIProxyAPI”，默认按 CLIProxyAPI upstream sync workflow 执行，除非明确指定其它仓库。执行入口固定为 `docs-linhay/references/CLIProxyAPI#gettokens/sidecar`，并按 fork 提交、sidecar 重建、父仓库 gitlink/docs/memory 提交的两层闭环收口。
+
+固定执行顺序：
+
+1. 父仓库和 fork 分别检查 `git status --short --branch`，父仓库只保护并 stage 本轮合并相关文件。
+2. fork 内 `git fetch upstream origin`，用 `git log --cherry-pick --right-only --no-merges HEAD...upstream/main` 识别真实 upstream-only commits；必要时用 `git merge-tree --write-tree HEAD upstream/main` 预判冲突。
+3. 合并前对高风险面跑 focused baseline；合并后先跑 touched surfaces 的 focused tests，再跑 `go test ./...` 和 `git diff --check`。
+4. 冲突处理优先保护 GetTokens 运行时面：`internal/gettokenshooks`、`internal/gettokensrouting`、`sdk/cliproxy/auth`、Codex WebSocket executor、usage / TTFT / reasoning、system proxy、config diff。
+5. fork 内提交并推送 `origin/gettokens/sidecar` 后，父仓库执行 `./scripts/ensure-sidecar.sh darwin arm64`，确认 meta 为新 fork commit 且 `dirty=clean`。
+6. 父仓库只提交 gitlink、space、dev 文档、memory 和必要构建产物；最后运行 `qmd update`、`qmd embed`，用 `qmd query` 抽查可检索。
+
+本轮新增的性能与重复劳动规则：当 upstream 改到 telemetry、TTFT 或 reasoning extraction，不在多个入口重复解析或重复启动计时。`TrackHTTPClient` 和 `ObserveResponse` 这类路径应共用 body 包裹逻辑；`SetTranslatedReasoningEffort` 只有在 translated payload 真正提取到 effort 时才覆盖 context 中已有值。
+
+`ttft_ms` 当前按 telemetry 字段对待，先通过 payload 测试锁定序列化，不默认扩展 UI/报表消费。若未来 WebSocket executor 再冲突，必须同时验证 `RecordCodexLiveUpstreamConnected`、`RecordCodexLiveFirstEvent`、`StartResponseTTFT`、`MarkFirstResponseByte` 四个时序点。
+
 ## 2026-05-24 同步记录
 
 本轮将 `docs-linhay/references/CLIProxyAPI#gettokens/sidecar` 从 `upstream/main@50d19e20`（`v7.1.20-1-g50d19e20`）合并到维护分支，生成 merge commit `1c5db246` 并推送到 `AxApp/CLIProxyAPI#gettokens/sidecar`。

docs-linhay/memory/2026-05-28.md

@@ -0,0 +1,92 @@
+# 2026-05-28
+
+## 记录
+- Codex `session-management` 的深度分析已改为 Go 侧批量处理，使用 `github.com/yanyiwu/gojieba` 做中文分词。
+- 分析入口支持全量、按项目、按指定 `sessionID` 批量分析，前端只负责展示结果。
+- 这个能力更适合作为 `session-management` 的第一个插件；后续分析、复盘、对比和导出能力应按插件宿主方式继续演进。
+- 一期插件宿主已落地：页面显示“会话插件”，首个内置插件提供当前项目、最近 20 条、全量分析入口。
+- 浏览器 dev bridge 上，全量分析 3545 条会话实际耗时约 166 秒；前端分析请求超时已从 30 秒提高到 300 秒，避免长任务误报失败。
+
+## 已验证
+- `go test ./internal/wailsapp -run 'TestAnalyzeCodexSessions'`
+- `go test ./...`
+- `node --test frontend/src/features/session-management/model.test.mjs`
+- `npm --prefix frontend run typecheck`
+- `npm --prefix frontend run build`
+- 浏览器验收：`http://127.0.0.1:5173/#frame=codex&workspace=session-management` 已能展示“会话分析”区域并返回结果。
+- 浏览器验收：插件宿主已展示“会话插件”和“分析最近 20 条”，点击最近 20 条后返回关键词结果。
+
+## 风险
+- 全量分析是长任务，dev bridge 仍依赖本地文件读取与分词，首次全量执行会比较慢。
+
+## 补充
+- Codex 账号详情弹窗的 header 重新做了桌面版信息架构，采用“身份行 + 标题状态 + 5 项元数据卡片”的结构，不再用无标签短值堆叠。
+- 这次视觉验收只按桌面场景收敛，产品不做手机端适配。
+
+## 会话插件设计稿
+- `session-management` 的一期设计稿已补齐，文件为 `docs-linhay/spaces/20260527-session-jieba-analysis/session-plugin-console-design-v01.html`。
+- 设计方向收敛为“密集型插件控制台”，首屏包含插件注册表、分析作用域、执行状态、会话列表、执行队列和插件输出六个区块。
+- 已完成桌面和 375px 窄屏检查，横向未溢出；截图已归档到 `docs-linhay/spaces/20260527-session-jieba-analysis/screenshots/20260528/session-management/`。
+- 设计稿已进入设计系统：新增 `SessionPluginConsolePanel` 纯展示组件和 `Design System/业务组件/会话插件控制台` Storybook story，并同步到 `storyCatalog` 与 `componentManifest`。
+- 账号详情里的 `AccountCredentialsSection` 与 `AccountVerifySection` 已合并为单个 `AccountCredentialVerifySection`，模块计划也同步去掉了独立 `verify` 段。
+
+## cc-switch deep link 设计
+- GetTokens deep link 的特殊场景 key 定为 `providerScope=current-active` / `providerScope=create-new`，用于显式区分“沿用当前激活 provider”与“创建新 provider”。
+- 这个 key 会作为后续 parser / preview / apply 的判断依据，不再只靠 `config.toml` 里有没有 `model_provider` 来猜场景。
+
+## deep link modal 设计
+- `docs-linhay/spaces/20260528-cc-switch-one-click-import/deep-link-import-modal-design.html` 已补成入口 modal 的单文件设计稿，结构沿用 `ModalFrame` 的硬边框工作台风格。
+- modal 信息架构固定为：header summary、parse rail、账号草稿、provider 连续性、受控 patch 预览、底部 action bar。
+- 视觉验证已做桌面与 375px 两档，移动端最终收敛为顶部徽标单列、header actions 单行、provider chip 可换行，避免横向裁切。
+- 截图已归档到 `docs-linhay/spaces/20260528-cc-switch-one-click-import/screenshots/20260528/deeplink/`。
+
+## 账号导入统一 modal
+- `20260528-account-import-unified-modal` 已落地：账户页上传文件和粘贴内容收敛为一个 `AccountImportModal`，支持多文件、粘贴 JSON 数组、候选队列和逐项移除。
+- 粘贴解析新增 `parseAccountImportPayloads`：复制账号卡 payload 保持 API Key / OpenAI-compatible / auth-file 原语义，普通 JSON 对象作为 auth-file 候选进入上传链路。
+- CPA 自动转换继续复用 app 内 `UploadAuthFiles` 后端归一化路径，前端不复制 ChatGPT Session / 9router OAuth 字段映射。
+- 候选队列项现在会展示解析后的内容预览，帮助用户在提交前核对每个导入对象的实际内容。
+- 预览证据已归档：`docs-linhay/screenshots/20260528/accounts/20260528-accounts-import-modal-preview-after-v01.png`。
+- 追补验证中账号导入 targeted tests、typecheck、完整 `test:unit`、build、build-storybook 均通过；此前 `SessionPluginConsolePanel.tsx` 设计系统 manifest 不一致已消除。
+- 此前整体验证通过：账户相关 targeted node tests、`npm --prefix frontend run typecheck`、`npm --prefix frontend run test:unit`、`npm --prefix frontend run build`、`npm --prefix frontend run build-storybook`。
+
+## CLIProxyAPI 日常上游合并
+- 按 `20260527-cliproxyapi-upstream-merge` 方案完成 2026-05-28 日常同步：`upstream/main` 合并到 fork `gettokens/sidecar`，新增 upstream tag `v7.1.24`。
+- fork 合并提交为 `d21a74b5`，已推送 `origin/gettokens/sidecar`；父仓库 `docs-linhay/references/CLIProxyAPI` gitlink 从 `b0cbe42` 前进到 `d21a74b5`。
+- 冲突仅发生在 `internal/runtime/executor/codex_websockets_executor.go`：保留 GetTokens live-session 上游连接/首事件记录，同时接入 upstream TTFT usage reporting。
+- sidecar 已重建：`d21a74b5:clean:cf463a7d5e44405ccd2ea5d5fca12ec5f8e956645fd1b6a610d17ad5edc58df0:darwin:arm64`。
+- 验证通过：fork focused tests、`go test ./...`、`git diff --check`、父仓库 `./scripts/ensure-sidecar.sh darwin arm64`。
+
+## CLIProxyAPI 合并后续收口 space
+- 新建 `docs-linhay/spaces/20260528-cliproxyapi-merge-hardening/`，用于收口这批 upstream merge 后的运行时采集改动。
+- space 的重点不是继续扩功能，而是确认 `ttft_ms` 的消费边界、补齐 `UsageReporter` 和 WebSocket 时序测试，并把后续合并热区文档化。
+
+## 会话管理读取性能
+- 线上 app 的 `session-management` 首屏卡顿根因是生产后端首次同步全量扫描 `~/.codex/sessions` 与 `~/.codex/archived_sessions`；本机样本为 3550 个 jsonl、约 8.1G，最大单文件约 317M。
+- 已将 Codex snapshot 路径改为优先读取 `~/.codex/.gettokens-session-management-snapshot-cache.json`，命中后立即返回并后台刷新；手动刷新仍执行真实全量扫描并回写磁盘快照。
+- snapshot 扫描不再保存完整 message 列表，也不再对每条消息做完整脱敏摘要；详情页和分析页仍按需完整解析单个会话文件。
+- 实测生产 Go 路径：无磁盘快照冷扫约 19.2s；命中磁盘快照后 `GetCodexSessionManagementSnapshot` 约 13ms。前端无缓存首屏复用 `InitialLoadingShell` 骨架动画，避免空白等待。
+- 验证通过：`go test ./internal/wailsapp`、`npm --prefix frontend run typecheck`、`node --test frontend/src/features/session-management/model.test.mjs frontend/src/features/session-management/cache.test.mjs`、`GETTOKENS_LIVE_SESSION_PERF=1 go test ./internal/wailsapp -run '^$' -bench BenchmarkLiveCodexSessionManagementSnapshot -benchtime=1x -count=1`。
+
+## 会话详情页优化
+- `GetCodexSessionDetail` / `GetClaudeCodeSessionDetail` 已改成按会话文件指纹读写磁盘缓存，并在 `App` 内保留内存缓存；文件未变化时重复打开详情会直接命中缓存。
+- 详情缓存落盘到 `~/.codex/.gettokens-session-management-detail-cache/`，文件变更后通过 size + mtime 自动失效。
+- UI 详情 payload 已做内存控制：只保留摘要行，清空完整 message `content`，最多返回最近 1000 条；App 内详情缓存最多 6 条且估算内容不超过 16MB，超大详情只落磁盘不驻留内存。
+- 这条路径保留了后端分析能力的完整消息解析，确保分析结果不改语义，但 UI 重复打开同一详情会明显更快且不会因多个大详情常驻导致 App 内存膨胀。
+- 实测 `sessions/2026/04/21/rollout-2026-04-21T16-57-43-019daf42-7c24-7a61-9a13-7c16c55973bf.jsonl`：首次冷读约 2.08s，重启 app 后命中磁盘详情缓存约 45.9ms，同一进程内再次打开约 78us。
+- 验证通过：`go test ./internal/wailsapp`、`npm --prefix frontend run typecheck`、`npm --prefix frontend run build`、`GETTOKENS_LIVE_SESSION_PERF=1 go test ./internal/wailsapp -run '^$' -bench BenchmarkLiveCodexSessionDetailCold -benchtime=1x -count=1`、`GETTOKENS_LIVE_SESSION_PERF=1 go test ./internal/wailsapp -run '^$' -bench BenchmarkLiveCodexSessionDetailDiskCached -benchtime=1x -count=1`、`GETTOKENS_LIVE_SESSION_PERF=1 go test ./internal/wailsapp -run '^$' -bench BenchmarkLiveCodexSessionDetailCached -benchtime=1x -count=1`。
+- 本次沉淀到项目级 skill：本地会话文件相关 API 必须区分 snapshot / UI detail / backend analysis，UI detail 必须有 payload 上限，内存缓存必须有 entry 和 byte 双上限。
+- 追补修正：`TestGetCodexSessionDetailMasksSensitiveTextAndKeepsMessageRows` 已按 UI detail 轻量化契约更新，改为断言 `Summary` 保留脱敏占位符且 `Content` 清空；新增 `TestCompactSessionManagementDetailForUIKeepsSummariesOnly` 锁定最多 1000 条摘要、清空正文且不 mutate 源对象。
+- 追补验证通过：`go test ./internal/wailsapp`、`go test ./...`、`npm --prefix frontend run typecheck`、`npm --prefix frontend run test:unit`、`npm --prefix frontend run build`、`npm --prefix frontend run build-storybook`。
+
+## CLIProxyAPI 合并后续收口执行
+- `20260528-cliproxyapi-merge-hardening` 已完成首轮收口，fork 提交 `fbcf3bb5 fix: harden usage reasoning and ttft reporting` 已推送到 `origin/gettokens/sidecar`。
+- 修复 `SetTranslatedReasoningEffort` 在 translated payload 无 reasoning 配置时清空 context reasoning effort 的问题；现在只有提取到 translated effort 时才覆盖。
+- 按用户要求减少重复劳动：`TrackHTTPClient` 和 `ObserveResponse` 共用 body 包裹逻辑，HTTP TTFT 路径不再重复启动计时。
+- `ttft_ms` 当前按 telemetry 字段处理，已通过 redis queue payload 测试锁定序列化输出；本期不扩展 UI/报表消费。
+- sidecar 已重建：`fbcf3bb5:clean:a3f32c9be29306928d103699760db583cbd8dde4dd899893313ea7731000d630:darwin:arm64`。
+- 验证通过：fork targeted tests、`go test ./...`、`git diff --check`、`./scripts/ensure-sidecar.sh darwin arm64`。
+
+## CLIProxyAPI 上游合并触发约定
+- 用户后续说“合并上游分支”“同步上游”或“每日合并 CLIProxyAPI”时，默认按 CLIProxyAPI upstream sync workflow 执行，目标为 `docs-linhay/references/CLIProxyAPI#gettokens/sidecar`。
+- 流程已沉淀到 `.agents/skills/gettokens-domain-engineering/SKILL.md` 和 `docs-linhay/dev/20260519-cliproxyapi-upstream-sync-session-distillation.md`：先审 upstream-only commits 和风险面，再 merge / focused tests / `go test ./...` / `git diff --check`，fork 提交推送后重建 sidecar，最后提交父仓库 gitlink、space、dev、memory 并更新 qmd。
+- 性能约束已纳入流程：telemetry、TTFT、reasoning extraction 合并时优先抽共用逻辑，避免在多个入口重复解析或重复启动计时。

docs-linhay/references/CLIProxyAPI

@@ -1 +1 @@
-Subproject commit b0cbe42cafa232b30cdedb1271b1bfe4ae6f14ad
+Subproject commit fbcf3bb559cdd8c3f85a31950814df763814e237