HHostingByteSoftware
Ctrl K
ComunidadGuías…

docs/HANDOFF-2026-08-20.md

Rama master · réplica de lectura del repositorio original.

Archivo original ↗Preguntar a KiBot
# 交接说明 — 2026-08-20

> **⚠️ 这不是最新的一份。** 本文写的是 v3.9.34,**当前一份是
> [HANDOFF-2026-10-15.md](HANDOFF-2026-10-15.md)**。状态表与"仍未做"请以最新那份为准。
> 索引在 [README.md](README.md)。交接是 append-only,旧结论不删。

**上一份**:[HANDOFF-2026-08-06.md](HANDOFF-2026-08-06.md)(它停在 v3.9.20,不是现状)。
方法论仍看 [AUDIT-LEDGER.md](AUDIT-LEDGER.md)。本份只写**现在还能接手的事实**。

---

## 0. 当前状态

```
产品 tag     v3.9.34 —— 本份随发版改。OTA 跟最新 annotated tag。
master       与 origin 对齐后 `git describe` 应是 v3.9.34（或 tag 后的 -N-g…）。
             不要把 tag 后的 SHA 写成「就是这个版本」。
作者         dwgx。禁止 AI 署名 / Co-Authored-By
活树         D:\Project\WindsurfAPI。不要建 D:\Project\windsurf
Mac 路径     D:\Macos\workspace\Project\windsurf 只是联接
Windows      Node v24.16.0; 无 /usr/bin/git; core.filemode=false
             mutate / real-Git 夹具在 PowerShell 加载即失败,不当产品回归
```

开着的 issue / PR(2026-09-04 核对):

| | 状态 | 下一刀 |
|---|---|---|
| #258 | 开 | `DROUGHT_SAFE_SELECTORS` 进 v3.9.28。不扩 `FREE_REACHABLE`。等报告者旱灾下确认 200 |
| #257 | **已关**（COMPLETED） | 加号/401/API Key 旁路修进 v3.9.27。报告者 `Ok Solved` |
| #256 | **已关**（作者 08-20 自关，未 merge） | 解码器在 v3.9.24 起，默认关。Dashboard ACU / `#19/#20` 没进。默认开改找 #239 |
| #239 | 开 | v3.9.24 起 opt-in,默认关。#256 证人走了;终帧对账还在这条 |
| #250 | 开 | 已知活抓泄漏。钓竿已认 `<think>`。要现场 |
| #245 | 开 | 配置答疑写完,报告者没回 |
| #236 | 开 | 要原始 tool 文本 + 绕开 subapi 直连 |
| #208 | 开 | 公告,故意留 |
| #255 | **已关** | 诊断收下;合进去会打掉混合池 snapshot fallback |
| #185 | **已关** | 进 v3.9.24 |
| #259 | **已关**（未 merge） | OrcaRouter 一等公民 provider。not planned |

## 1. 接手三分钟内会踩的

1. **不要在 `master` 上 `git commit`。** `.githooks/pre-commit` 会拒,且发生在 `git add` 之后,树会脏。流程:分支 → 审 → `git merge --ff-only` → push。
2. **`npm test` 不是发布门。** 权威是 `npm run test:release`。突变规格 **不在** `npm test` 里;改 `src/` 必须 `for s in test/mutations/*.json; do npm run mutate -- "$s"; done`(Linux,要 `/usr/bin/git`)。
3. **不要打开、不要打印** `.env` / `accounts*` / `*session.env`。家里云 `/home/dwgx_user/WindsurfAPI` 带凭据,systemd `windsurfapi` 听 `0.0.0.0:3003`。覆盖该树仍要 Owner 点名。OTA 跟 annotated tag（v3.9.29 起）。门禁用 `~/scratch/` 隔离克隆。

## 2. 该暴露 / 不该暴露

**公开(git 跟踪,GitHub 可见)**

- `README.md` / `README.en.md` / `LICENSE`
- `docs/releases/RELEASE_NOTES_*.md`(发版正文)
- `docs/ENV-SWITCHES.md`、`docs/DEVIN-CONNECT-CUTOVER.md`
- 本交接链 + `docs/AUDIT-LEDGER.md` + HISTORY-LEDGER*(历史,append-only)
- 源码与测试。`.env.example` 只写开关名,不写值

**绝不进 git / 绝不贴到 issue**

- `.env`、`accounts.json`、`accounts.creds.json`、`*session.env`、`data/accounts*`
- `.trace/` `.wire-dump/` 抓包、ghidra 工程、`.devin-connect-calibrated.env`
- `docs-internal/`(研究笔记,gitignore)。抓包/bin/第三方整树拷贝更不该回来
- `.agent/` `.claude/` `.grok/` 控制面(含本机 `HANDOFF.md`、`CONTEXT.md`)
- 根目录 `CLAUDE.md` / `AGENTS.md`(gitignore;以仓库内约定为准,不要当成产品说明)

**描述符可以引用,不要当付费对账:** `leookun/devin-2api` 抽出的 `GetChatMessageResponse.committed_acu_cost = 22` (double) 是二进制字段号,不是官方周期对账。

## 3. 幻觉已改(本份相对上一份)

| 旧说法 | 现况 |
|---|---|
| 公开交接停在 v3.9.20 | 本份。产品 tag v3.9.34 |
| CHANGELOG「当前 v3.9.21 / 172 份说明」 | 索引改到 v3.9.34 / 185 份 |
| Connect 图 tag 静态猜 4 | **10**(#244) |
| `committed_acu_cost=^22` 没用 | 描述符就是 22/double;默认仍关 |
| #255 该 merge | 不该。关的是弱策略,不是诊断 |

## 4. 仍未做(不是漏做)

- 默认开 ACU `^22`:#256 证人走了。等 #239 报告者或 Owner 点名账号跑 `DEVIN_CONNECT_DEBUG_META=1` 终帧 `#22` + 官方周期 `billed_acus`
- #250 / #245 / #236:等报告者数据或活抓
- 家里云生产树:2026-08-21 `/health` 是 `98c46d6` / v3.9.24。之后 SSH 超时，是否已 OTA 到 v3.9.29 **未知**。覆盖仍要 Owner 点名。不要把「未部署」或「一定还是 98c46d6」当现状
- self-update-hotfix 个别过宽突变:规格债;产品基线绿
- HISTORY 总账停在 08-11 / v3.9.21(当时 172 份 notes)。v3.9.22–31 以本份为准,不要拿总账里的版本号当现状

## 5. 协议邻居(研究,2026-08-20)

| 项目 | 用途 |
|---|---|
| 本仓 | 最完整网关(四套前端 + 账号池 + 身份中和) |
| leookun/devin-2api | Connect;descriptor 库;`committed_acu_cost=22` |
| CaiJingLong/devin-gateway | 最小 Connect;不解码响应 #22 |
| WindSurf-gRPC-API | LS/gRPC,不是 Devin 聊天帧 |
| 官方 Analytics v2 | REST `billed_acus`,要 service_key,不是 session 帧 |

## 6. 发版口令

见 [releases/README.md](releases/README.md)。bump `package.json` 一次、`package-lock.json` 两次;annotated tag;不要在 master 上 commit。