chore: initialize qiming workspace repository

qimingclaw/crates/agent-electron-client/docs/reviews/SOLUTION-RETENTION-ELECTRON-2026-03.md

@@ -0,0 +1,99 @@
+# Electron 相关方案留存（2026-03）
+
+本文档固化若干**已落地或评审通过**的设计与修复，便于后续合并分支、排查回归时对照。实现位置以 `qiming-agent` 主仓库为准；独立 worktree 中的实验以「附录」说明。
+
+---
+
+## 1. FirstTokenTrace 请求级采样（均匀分布）
+
+### 问题
+
+按 `requestId` 的 MD5 前 8 个十六进制字符得到 32 位无符号整数，若除以 `0xFFFFFFFF`（即 \(2^{32}-1\)），则最大哈希对应比值为 **1.0**，严格说不属于半开区间 \([0, 1)\)，且与「将 \(2^{32}\) 个整点均匀映射到单位区间」的常规定义不一致，在 `sampleRate` 接近 1 时会产生可观测偏差。
+
+### 方案
+
+- 除数使用 **\(2^{32}\)**，即十六进制字面量 `0x100000000`（或等价 `2 ** 32`）。
+- 判定仍为 `v < sampleRate`，其中 `v ∈ [0, 1)`。
+
+### 代码位置
+
+- `src/main/services/engines/perf/firstTokenTrace.ts` → `shouldSample()`
+
+### 与性能报告的关系
+
+首条消息/首 token 相关分析见 `docs/optimization/MACOS-FIRST-MESSAGE-PERF-REPORT-2026-03-31.md` 等；采样用于控制磁盘与日志量，不影响功能正确性，但影响统计代表性。
+
+---
+
+## 2. `sync-oss.sh` 与 GitHub Actions 运行记录
+
+### 背景
+
+脚本在**本机**通过 `gh` 触发 **目标仓库**（默认 `qiming-ai/qimingclaw`）的 `sync-electron-to-oss.yml`，此前存在两类风险：
+
+1. **`gh run list --limit 1`**：取的是「列表中最新一条」，并发或他人刚触发的 run 会导致**跟错 run**。
+2. **未指定 `--repo`**：`gh` 默认指向当前 checkout 的仓库；若在 `qiming-agent` 目录执行而实际 dispatch 到 `qimingclaw`，会列到**错误仓库**的 run。
+
+### 方案
+
+1. 在发起 `workflow_dispatch` 的 HTTP 请求**之前**，记录 `START_EPOCH`（当前 UTC 时间戳减约 10 秒，抵消客户端与 GitHub 时钟差）。
+2. 触发成功后轮询 `gh run list --repo "$REPO" --workflow=sync-electron-to-oss.yml`，在结果中筛选：
+   - `event == "workflow_dispatch"`；
+   - `createdAt` 解析为 epoch 后 **≥ `START_EPOCH`**；
+   - 取其中按时间**最新**一条的 `databaseId`。
+3. 所有 `gh run view` / 输出日志 URL 均带 **`--repo "$REPO"`**。
+4. 若在超时轮询内仍无法解析 run，脚本失败并提示用户用 `gh run list --repo "$REPO"` 人工核对。
+
+### 残余边界
+
+同一秒内对**同一仓库**多次 `workflow_dispatch`，仍可能歧义；若未来需要，可在 workflow `inputs` 中增加显式关联 ID。
+
+### 相关文档
+
+- `docs/QIMINGCLAW-WORKFLOW-DISPATCH.md`：在 qimingclaw 侧启用 workflow、Secrets、一次性复制路径说明。
+
+---
+
+## 3. CI 中版本号校验：POSIX `grep` 与 `ripgrep`
+
+### 问题
+
+在 `ubuntu-latest` 上若使用 `rg -q` 做 `x.y.z` 校验，**默认镜像未必安装 ripgrep**，校验步骤可能静默失败或整条 step 失败，与「MVP 仅允许纯数字三段版本」的意图不符。
+
+### 方案
+
+在 shell 中使用 **`grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'`**，依赖 POSIX 环境即可，与 `sync-electron-to-oss.yml` / `release-electron.yml` 中生成 `latest.json` 的版本字段策略一致。
+
+### 落地说明
+
+带 `channel`（stable/beta）与上述校验的 workflow 变更可能位于独立分支或 worktree；合并到主分支后，**qiming-agent 与 qimingclaw 两侧 workflow 文件应保持同步**（以实际执行 release/OSS 的仓库为准）。
+
+---
+
+## 4. 附录：stable / beta 更新通道（规划/分支）
+
+目标与 OSS 路径约定（先 beta 再 stable、beta 不写 `latest/latest.json` 等）见独立说明文档草案；若已合入主仓库，路径为：
+
+- `docs/RELEASE-CHANNELS.md`（若不存在，可参考 worktree `feat/stable-beta-update-channel` 内同名文件）
+
+客户端侧要点（实现以合入后的代码为准）：
+
+- SQLite `update_channel` 决定拉取的 `latest.json` URL（stable 与 beta 不同路径）。
+- 旧版客户端仅读 `latest/`，行为保持不变。
+
+---
+
+## 5. 文档索引
+
+| 主题 | 路径 |
+|------|------|
+| OSS 仅同步 workflow 启用说明 | [../QIMINGCLAW-WORKFLOW-DISPATCH.md](../QIMINGCLAW-WORKFLOW-DISPATCH.md) |
+| 自动更新架构 | [../architecture/auto-update.md](../architecture/auto-update.md) |
+| qimingcode 二进制签名说明 | [../QIMINGCODE-BINARY-SIGNING-2026-03-28.md](../QIMINGCODE-BINARY-SIGNING-2026-03-28.md) |
+| macOS 首条消息性能报告 | [../optimization/MACOS-FIRST-MESSAGE-PERF-REPORT-2026-03-31.md](../optimization/MACOS-FIRST-MESSAGE-PERF-REPORT-2026-03-31.md) |
+
+---
+
+*文档状态：留存归档；若实现迁移或策略变更，请在本文件顶部更新「最后修订」并保留变更摘要。*
+
+**最后修订：2026-03-31**