# v0.8 执行文档 — Token 优化 + Phase B 接入

> Status: in_progress (2026-05-29)
> Parent: `docs/plan/v0.8-model-onboarding-redesign.md`
> 前置: Phase A M1-M3 + Security audit 已完成

## 0. 为什么写这份文档

Phase A 跑出了 5 个 reported-tokens trial，我**用数据**（不是猜）定位了真实瓶颈。
之前列的 5 个"听起来合理"的优化里，有 3 个其实没价值（system prompt 只占 0.7%）。
这份文档把测量结论 → 具体动作 → 验收标准串起来，避免再次发生"做了一堆但没量化"。

## 1. 测量结论（数据）

`scripts/lab-analyze.ts --success-only` 对 5 个有效 trial 的输出：

| 指标 | 数值 |
|---|---|
| Avg reported prompt tokens | **175,665** |
| Avg rounds | **15.4** |
| Avg system prompt | 1,157 tokens (**0.7%** of total) |
| Ratio reported / 我的估算 | **217-223%** |

**真实瓶颈**（重新排序）：

1. **轮数 × tool schema 重传** — 每轮重发完整历史 + 10 个 tool schema。
   10 × ~150 tok × 15 rounds ≈ **22k tokens 纯 schema 开销**
2. **Agent 串行调 setter** — 4 个 field 一个一个 `add_field_with_evidence`，
   每多 1 轮多传一份历史。
3. **`fetch_raw_docs` 100% 被调 2 次同 URL** — 纯浪费 ~1.5k tokens/trial
4. ~~System prompt 太大~~ — 错误假设。1.1k 只占 0.7%，不动。
5. ~~Tool result 太大~~ — 错误假设。fetch 实际只返 ~800 tok，远小于 30k cap。

## 2. M4 — Token 优化（按 ROI 排）

### M4.1 set_fields 批量工具（最大 ROI）

**问题**：agent 调 4 次 `add_field_with_evidence` 等于多 3 轮全量重传。

**改动** (`electron/ai/onboarding/tools.ts`)：
- 新增 `set_fields(fields: Array<{name, type, required, evidence, evidence_location, default?}>)`
- 保留旧 `add_field_with_evidence` 但 deprecate（system prompt 引导用 batch）
- system prompt 加一行："prefer set_fields with all known fields at once"

**验收**: rounds 从 15 降到 ≤10，reported tokens 降 ≥25%。

### M4.2 fetch_raw_docs URL 缓存

**问题**：5/5 trial 都重复 fetch 同 URL。

**改动** (`electron/ai/onboarding/tools.ts`)：
- per-trial 内存 `Map<url, FetchResult>`
- 第二次 hit 直接返回 + result 里加 `cached: true` 提示 agent
- 缓存随 `runOnboardingTrial` 生命周期销毁

**验收**: duplicate fetch 数为 0；省 ~7%。

### M4.3 合并 setter 工具

**问题**：tool schema 数量 × per-round 重传 = 高固定开销。

**改动** (`electron/ai/onboarding/tools.ts`)：
- 合三为一: `set_vendor_info({ baseUrl, auth, modelId, modelKind })`
- 删除 `set_vendor_baseurl` / `set_vendor_auth` / `set_model_identity`
- tool 总数 10 → 8

**验收**: 省 ~3-5%。

### M4.4 重测验证

跑：
```bash
pnpm run lab:onboard -- --docs https://docs.kie.ai/api-reference/kling/v3-0/generate-video \
  --kind video --key @.secrets/kie.key \
  --agent-key @.secrets/agent.key --agent-base https://dm-fox.rjj.cc/codex/v1 \
  --agent-model gpt-5.5
pnpm run lab:onboard -- --fixture attack-A-system-override --kind image ...
pnpm exec tsx scripts/lab-analyze.ts --success-only
```

**门槛**：avg reported tokens 必须 ≤ 120k（从 175k 降 ≥30%）。
没达到 → 回 M4.1 调整 system prompt 引导 agent 更激进 batch。

## 3. M5 — Phase B 接入 UI

### M5.1 catalog schema v2

**为什么**：v1 catalog 只有 `{id, kind, label, ...}`，onboarding 产物有
`{vendorBaseUrl, auth, mapping, evidence, testCurl}`。

**改动** (`electron/catalog/`):
- 加 `version: 2` 字段
- 新增 `OnboardedModel` 类型扩展 `Model`
- 写一次性迁移：v1 entry 跑过自动加 `version: 1` 标记
- Reader 同时支持 v1+v2

### M5.2 safeStorage 加密

**改动** (`electron/secrets/`):
- 新 `secretStore.ts`：`save(modelId, key)` / `read(modelId)` / `remove(modelId)`
- 落盘前 `safeStorage.encryptString`，读时 `decryptString`
- Catalog 只存 `keyRef: "model_id"`，不存明文

### M5.3 Wizard UI 主流程

**路径** (`src/components/onboarding/Wizard.tsx`):
- Step 1: 一个粘贴框（docs URL）+ 一个 API key 输入 + kind 选择
- Step 2: 实时进度面板（"正在阅读文档…" / "在测试调用…"），不暴露 tool name
- Step 3: 成功 → "已添加模型 XXX"；失败 → 简短说明 + "找开发者复制日志" 按钮

**Apple 原则**: 不出现 "vendor / mapping / JSON / endpoint" 字样。

### M5.4 IPC bridge

**改动** (`electron/preload/nomiDesktop.ts` + `electron/ipc/onboarding.ts`)：
- `nomiDesktop.onboarding.start(input) → { trialId }`
- `nomiDesktop.onboarding.subscribe(trialId, cb)` → 事件流
- main 进程执行 `runOnboardingTrial`，事件 IPC push

### M5.5 接入 5 个 kie.ai 模型（真机验收）

用新 wizard 接入：
1. seedance2.0
2. Happy House
3. GPT Image 2
4. Gemini Omni
5. kling 3.0

Agent 用 Kimi key (poor 模型，故意压一压 robustness)。
**每个模型成功** = 出现在 catalog + 在 node sidebar 可选 = M5 验收通过。
任何一个失败 → 回 M4 加 fixture 迭代。

## 4. 风险 & 兜底

| 风险 | 兜底 |
|---|---|
| M4.1 之后 agent 反而忘 batch | system prompt 给一个 set_fields 示例 |
| safeStorage 在 Linux/某些环境不可用 | fallback 到 base64 + warning（M5.2 兼容层） |
| Kimi 接 5 个模型可能全挂 | 用 GPT-5.5 验证一遍；Kimi 跑测准入门槛 |
| Token 实际没降 30% | 不进 Phase B，先回头查 ratio 217% 真实成因 |

## 5. 时间盒

- M4.1-4.3 实施: ~2h
- M4.4 重测: ~30min
- M5.1-5.4: ~6-8h
- M5.5 真机接入: ~2h（5 个模型 × 20min agent run）

总计 **~12h**。每个 M 完成 commit 一次。

## 6. 顺序

严格串行：M4.1 → M4.2 → M4.3 → M4.4（gate）→ M5.1 → M5.2 → M5.3+M5.4 并行 → M5.5。
