v1.7.8

Claude Code Heihei v1.7.8

朗读连续性修复版：本版集中修复消息朗读的三个体验问题——长消息被提前掐断、切换会话打断朗读、音色选择器两处小毛病。小步修复版，无新功能、无破坏性变更。安装包未签名（Windows SmartScreen 可能提示，选「仍要运行」即可）。

朗读修复（本版重点）

• 长消息不再被提前掐断：朗读看门狗的时长估算按真机实测重新定标——旧预算在 1× 语速下只有实际耗时的 58%，长消息读着读着就被「卡死保护」掐断；1.5× / 2× 加速时更明显（旧实现还按语速打折，而实际加速并非线性）。现在 1× 与加速档都能完整读完。

切会话继续播

• 正在朗读时切换到别的会话，朗读不再中止，切回可继续控制。

音色选择器

• 弹层内点击（搜索框、内部控件）不再意外收起，选音色不再「点一下就关」。
• 音色名称正常显示：修复名字与语言码丢失、徽标显示错误的问题（此前列表里名称全是空的）。

v1.7.7

Claude Code Heihei v1.7.7

朗读音色升级版：v1.7.5 引入的消息朗读（TTS）本版补齐音色选择——默认自动挑更自然的音色，也可以在设置里自己选、试听、调语速。小步增强版，无破坏性变更。安装包未签名（Windows SmartScreen 可能提示，选「仍要运行」即可）。

默认音色自动择优

• 打分择优：默认音色不再「系统给哪个用哪个」——按名称质量（Natural/Enhanced 优先）、本地/在线、与消息语言匹配等维度自动挑选，中文消息优先中文音色。
• 列表排序：设置页音色列表组内按择优分降序，每组第一行标**「推荐」**徽标，好音色一眼可见。
• 记住选择：手动选过的音色按 voiceURI 记住；系统语音包更新导致该音色消失时自动回退到同语言次优，不再哑然无声。

设置页音色选择器

• 搜索 + 分组 + 试听：按语言分组（含中日韩等书写系统组），支持按名称搜索；每行试听按钮（试听会停掉上一段再播新的，不会叠音）。
• 语速可调：朗读语速滑杆，试听与实际朗读同一口径。
• 本地 / 在线标识：各音色标注本地引擎还是在线语音（在线音色断网时不可用，一目了然）。

降级（无可用语音时）

• 无语音引擎、音色列表为空、只有一个可用音色三种情况都有对应形态：朗读键自动隐藏或选择器给出明确说明，不留空转的面子功能。

v1.7.6

Claude Code Heihei v1.7.6

上下文面板口径与基准修复版：本版修掉上下文面板的三个误读来源——主标题虚高、「建议压缩」误报、分类明细与总量不同基准。小步缺陷修复版，无新功能、无破坏性变更。安装包未签名（Windows SmartScreen 可能提示，选「仍要运行」即可）。

上下文面板修复

• 主标题不再虚高：会话回退/重开等边界场景下，粗估改按「从最后检查点起算」的 boundary-aware 口径，主标题与分类明细同基准（此前主标按全量消息估算、明细按窗口内统计，两者对不上且主标偏高）。
• 「建议压缩」不再误报：用量被窗口上限钳制（clamp）时不再把压缩后的截断值当成真实占用触发提示；明细行也不因 clamp 缩水，与实际窗口内容一致。
• 明细标注「实测 / 估算」基准：各分类明细按数据来源分别标注——CLI 回传的实测数打「实测」徽标，面板本地粗估的打「估算」徽标并附基准说明，不再混排误导。
• Output 不计入上下文：助手输出 token 不占上下文窗口，面板不再把它计入用量（与 CLI 实际口径一致）。

v1.7.5

Claude Code Heihei v1.7.5

协作体验与「请求过大」防御版：本版新增消息朗读（TTS），补齐 413「Request too large」 的完整防御链（从「锁死只能等」变成「可自愈、可修复」），并让花名册变更实时通知主管。安装包未签名（Windows SmartScreen 可能提示，选「仍要运行」即可）。无破坏性变更。

消息朗读（TTS）

• 会话消息操作栏新增朗读键：走系统 speechSynthesis（无需联网、无需额外下载引擎），长回复自动分段按序朗读，喇叭图标三态（空闲 / 朗读中 / 暂停）。
• 音色自动挑选：按消息文本的**书写系统「字符数取多数」**匹配 voice（中文消息优先中文音色），不再「出现即选」；voice 列表变化（系统新增/移除语音包）自动跟随。
• 稳健性：某段朗读卡死由 watchdog 兜底跳段，跳段前先 cancel 防级联静默；暂停态喇叭常驻可点，恢复不丢进度。
• 无可用引擎或 voice 的环境自动降级：朗读键不出现，不影响其他功能。

413「Request too large」：从锁死到可修复

此前会话一旦触发 413（上下文+媒体超服务端上限），每回合复发、无法自救。本版补齐完整防御链：

• 事前：发送前字节级预检，超阈值先卸媒体引用、超限不发网络请求；协作通道（派活/汇报/信箱）限长——大汇报自动落盘、只发摘要+路径（服务端另有 512KiB 兜底）。
• 自愈：CLI 侧媒体剥离回扫越过无关消息深挖到根（原实现只回溯最近一条，永远剥不到）。
• 可修复：超限错误条新增**「修复会话」按钮**——一键执行定点卸载+重载，不再面对卡死小字束手无策；释放量按 KB/MB 自适应显示。
• 熔断：连续超限自动停发并通知主管；派活闸门对锁死会话拒派并直接指向修复入口。熔断计数按「连续」语义（成功即清零），不误伤健康会话。

花名册变更实时通知主管

• 员工增 / 删 / 改角色 / 降级为普通会话 / 删除会话 ⇒ 在册主管实时收到通知（此前主管只能靠翻花名册发现，继续给已失效的员工派活）。
• 通知一律投递（移除「仅在生成中」闸门——用户实测「加了员工主管却不知道」的根因）；删除唯一员工、批量删除也能正确摘条目并通知。
• CollabListTasks 在花名册查询失败时不再崩溃（空指针修复）。

系统通知配色

• 系统通知改独立配色：中性灰底 + 近黑正文 + 次黑图标（不再与用户气泡撞色、不再像报错）；实测中性填充与对话底对比度仅 1.04–1.36:1，补 1px 边框保证可分辨。

协作链路修复

• 主管会话斜杠命令失效修复：花名册摘要改为独立 content block 注入（此前混进用户正文，斜杠命令被当普通文本送模型），并确立不变量「用户正文块永远是最后一个 text 块」、附件同源与守卫用例。

已知限制

• TTS 依赖本机操作系统已安装的语音包；无语音包的环境朗读键自动隐藏。
• 安装包未签名（SmartScreen 提示「仍要运行」即可）。

v1.7.4

Claude Code Heihei v1.7.4

结构债收官版：v1.7.0 结构专项立下的三项验收目标本版全部收口——五个巨型文件的行数目标（G1）、分层违规清零（G2）、服务端（root）类型关卡（G9）。同时修掉一批用户实际会撞到的桌面缺陷（面板/弹窗静默失败、协作设置弹窗永久转圈、未登记会话无法登记、超时被当成失败），并新增**「上下文接近上限 → 一键压缩」**入口。无破坏性变更。

结构债收官（本版主线）

G1：五个巨型文件全部 ≤2500 行，豁免清零

文件	之前	现在
src/server/services/sessionService.ts	2660	2343
src/server/ws/handler.ts	~3227	2384
desktop/src/stores/chatStore.ts	2504	2490

• 做法是整族外移而非零敲碎打：转录派生域（消息窗口/用量/会话写入与维护）整簇并入 src/server/services/transcriptDerivation.ts；会话活动域、后台任务子域、CLI 消息翻译域、传输枢纽族分别上提到 sessionActivity.ts、sessionTransport.ts 等叶子模块；搬迁一律按纯移动纪律执行并逐字复核。
• scripts/file-size-allowlist.json 现为空表：原先给 sessionService（cap 3846）与 handler（cap 3372）两条时效豁免已撤——两者现在都按规则 1 的文字标准（≤2500）管理，不再吃 cap。行长数基线表剩 19 项（均为上游 CLI 代码，只减不增）。

G2：分层违规 18 → 0，例外 0

• 从 18 条「已知放行」分五批清到 0：上游 import 改注入缝下沉（三家 L2 服务对 ws/* 的上行依赖）、消掉 1 条真环、computer-use-python 下沉至 services/、环/动态 import/managedEnv 类残余 6 条全清。
• 门禁实况：bun run lint:layers → 无任何违规（此前靠 --ignore-known 放行 18 条）。

G9：服务端类型关卡（tsc 棘轮）落地并接入 CI

• 背景：root tsconfig.json 因 TS6 下带 baseUrl 而实际一个文件都没检查（只报 1 条 TS5101、exit 2 的真空检查）。
• 修法：去掉 baseUrl（paths 不受影响），补闸门 bun run lint:types——签名只紧不松（基线 scripts/tsc-baseline.json，7141 条存量挂账、本批不销账），另带真空自毁（0 诊断判红）与骤降判红（拦「基线调到 1」式假绿）。
• 判别力双段自证：单测段 14 条（新增红/计数+1 红/收敛不拦/真空红/骤降红…）；管道段 scripts/g9-seed-error.patch 注入类型错误必红、反向 git apply -R 复原必绿。
• CI 已接线（layer-lint job 主步 + 种子演练步）；pre-commit 不接（全量 tsc 分钟级，钩子只留 <2s 的 file-size）。

桌面缺陷修复（用户可见）

面板/弹窗「静默失败」普查全批修（A1–A6）

此前多处「有 loading 面、有 error 变量，但错误从不显示」：删除失败、拉取失败、提交失败、目录浏览失败、原生目录对话框失败都只落 console，界面照旧、用户以为没点。

现在统一改为失败态 + 重试（错误文案走统一的人话映射），六处全修：删除提供商失败、提供商列表拉取失败、任务提交失败、最近项目加载失败、目录浏览失败、原生对话框失败。

一处设计洞（测试抓到）：原生对话框流程开始前菜单会先关闭，失败态无处可显示——把失败态上移到外层持有，并在原生流程失败后重开菜单，面板重新挂载后失败提示仍在。

协作设置弹窗对「不在花名册的会话」永久转圈（v1.7.3 #2）

根因：原判断无法区分「花名册还没加载完」与「确实没这条」——后者恒为真，于是永久停在加载态、提交按钮一并锁死。现在拆成加载中 / 就绪 / 不在花名册（可重试）/ 拉取失败四态：不在花名册给出明确失败提示 + 重试，拉取失败给出可重试的失败态，二者不再混为一类。

未登记会话现在可以登记为协作会话

上一版把「未登记」与「查询失败」混成同一类并给了一条伪重试死路（本版修正）。现在：未登记（永久）放行表单——填写并保存即通过既有 upsert 路径完成首次登记；仅拉取中/拉取失败才锁提交。文案改为引导语（「该会话尚未登记为协作会话；填写以下信息并保存即完成登记。」）。

「请求超时」不再呈现为业务失败

Request timed out after 320s 此前被当普通错误弹红条，暗示「失败/重试」；实际它只断了连接、业务仍在后台跑。现在超时文案改为**「连接已超时；任务可能仍在后台运行，稍后刷新即可查看结果」，turn-change 错误条在超时态改用中性提示条**（五语言同步）；默认请求超时同步由 120s 提升到 320s。

新建协作会话菜单新增「（选择目录…）」

此前想给新项目开协作会话只能绕道（先建普通会话、再改目录）。现在「新建会话」菜单直接给一条选择目录入口，复用既有原生目录选择。

协作任务台账按钮图标

台账按钮的 ListChecks 与活动流按钮图标同像素冲突，按设计师定稿在同族内换字为 ClipboardList（label/行为/状态一律未动）。

上下文：接近上限提示与一键压缩（R1）

• 接近上限即提示：上下文用量接近窗口时给出提示条 + 一键压缩按钮；阈值直接取 CLI 返回值（autoCompactThreshold，已按 provider 覆盖后的窗口推导）——不自行推算，天然与 CLI 实际行为同口径。
• 按钮是普通发送：复用既有 send 通道发 /compact（CLI 本地命令），零新协议、零 CLI 改动、零服务端改动；已核实该路径不会被 skipSlashCommands 吃掉。回合进行中按钮禁用，防重复触发。
• 压缩结果有反馈：区分「正在压缩 / 已压缩 / 压缩后仍超窗」；区分依据是压缩后重新取数，不是猜测。
• 两个入口、一份实现：/context 面板与上下文指示器的悬停弹层共用同一个组件与同一批文案键（不新造第二套）。弹层本体是 pointer-events-none（不可见时浮在输入区上方），故入口只在弹层可见时可点，避免隐形按钮吞掉点击。
• 面板取数补一次短重试：压缩刚结束时 CLI 常仍在收尾，那次 get_context_usage 失败会直接落成错误；现在 post-compact 取数失败会延迟 5s 自动重试一次，仍失败才显示错误。
• 口径统一三处：用量饱和时显式显示「≥窗口」（不再用钳到 100% 的数字误导）、分类明细行与总量同尺、面板 Context 页与弹层一样打**「估算」**标（该数据同走 estimateOnly 通道）。

协作

• 主管注入消息捎带花名册摘要，消掉「主管不知道有哪些员工」的误判。
• 花名册摘要改「模型可见、用户不可见」：摘要走独立系统段注入（模型能看到），界面读路径剥离该段——此前摘要会漏进用户可见的转录；历史裸行与检索面片段两处漏点同批补修。

测试与 CI 稳定性（改动均在测试/脚本侧）

• 根除 CI 上的 Windows %TEMP% 8.3 短路径形态（如 RUNNER~1）：抽共享 mkdtempReal 并套用到 11 个路径敏感测试文件，消掉 27 条环境型失败。
• searchService.sessions runner 假红：runner 上全局单例的索引指向 fallback 目录且状态「已完成」，空索引内容吞掉两相阶段——改为显式注入 null，强制走被测引擎。
• 协作推送合并窗口未随用例复位导致跨文件顺序依赖假红——已修并留原序复跑证据。
• G9 闸门跨平台归一化三件套（仓库根绝对路径、bun 缓存路径、嵌套 node_modules、TS 并集成员序）——CI 上的「上百条新增」经归一后证实全部是形态差、非真实差异。
• bun-types 显式声明修 CI 干净环境的 TS2688，并据此重生成基线 7255 → 7141。

已知问题（本版未修，均带账）

1. turn-checkpoints 慢点（v1.7.3 挂档）：O(n²) 已证伪，同输入四次 4.1/54.5/68.8/70.7s（≈17×），成因未定、零代码改动。
2. 按 uuid 移除消息的快路径 64KB 窗口丢尾：既有债务，触发窄（目标行不在末尾且其后存量 >64KB）；修法方向已定（needle 不在窗口末尾时回退慢路径，慢路径已有大小上限保护）——本版未实施。
3. normalizeProjectPath 不展开 8.3 短路径：同一目录两种字符串形态对不上（CI 根因的产品侧对偶）。
4. 系统代理桥随 app 异常退出留下「死代理 env」：窗口期内连累一切走代理的请求；用户明确指示后期再议。
5. server-full 残余 20 条 = runner 环境型已知家族：真失败 0，按挂账口径解读（真回归会以「红文件清单变化」形式显现）。

v1.7.3-test.4（测试版）

测试版（Pre-release）：供升级验收使用。未跑全量测试。

本次内容：

• 花名册摘要修复：改为「模型可见、用户不可见」——独立系统段注入，用户消息流不再重复出现摘要行（含历史消息与搜索结果两处补漏）
• G9 类型关卡在 CI 完整闭环：tsc 棘轮主步 PASS + 种子判错演练两段通过

安装包未签名（Windows SmartScreen 可能提示，选「仍要运行」即可）。

v1.7.3-test.3（测试版）

测试版（Pre-release）：供升级验收使用。未跑全量测试。

本次内容：

• 未登记会话可登记
• 花名册摘要注入：主管收汇报时自动附在册员工摘要，不再误报「没有员工」
• 协作台账图标
• 结构还债：ws handler 3351 → 2384 行、sessionService 3796 → 2343 行、分层违规 18 → 0

安装包未签名（Windows SmartScreen 可能提示，选「仍要运行」即可）。

v1.7.3

Claude Code Heihei v1.7.3

清掉一批「已查实、暂未修」的缺陷：五条登记缺陷修掉四条——两处会让会话静默挂死的文件操作、一处永久转圈的协作弹窗、一处会毁掉整份台账的脏行、一处隔离实例读错实例的端口路径；第五条（turn-checkpoints 慢点）经实测把「O(n²)」证伪、成因仍未定，带数据挂档、本版未修。另把「请求超时」与「业务失败」在界面上区分开。无破坏性变更。

修复：五条登记缺陷中的四条

1. Bun 的 truncate 永不返回 → 两处产品路径改「重写语义」

• 现象：走到任一条用 truncate 的路径，await 永不返回——不报错、不抛异常、也不自愈，表现为静默挂死。
• 根因（后端探针 9/9 实证）：fs.truncate / FileHandle.truncate / fs.ftruncate（含 sync）在缩短、等长、变长三个方向全部不返回，三种 API 无差别 ⇒ 缺陷在底层 syscall 封装，「换个 API 绕开」不可行。
• 受影响的两处产品路径：
  • src/history.ts（提示历史写入器的回滚分支）：原 await truncate(...) 永不返回 ⇒ 其 catch 兜底（毒化标记）永远不执行 ⇒ 回滚静默挂死；
  • src/utils/sessionStorage.ts（按 uuid 移除单条会话）：原「定位行 + truncate」在两个分支都会出事——删最后一条直接挂死；删中间条则 truncate 挂住、补尾部永不执行 ⇒ 尾部永久丢失。
• 修法：两处都改为重写语义——把要保留的内容拼好后整体写回（写回天然截断，字节等价），彻底绕开 truncate。新增用例覆盖「删末条 / 删中间条」两种情形（结果字节等价）。
• 附带加固（独立审查发现）：上述重写路径用 Buffer.allocUnsafe(...) 且未检查 read 的实际读取字节数——与 CLI 子进程并发追加时可能「短读」，把未初始化的堆内存写回用户转录（既污染数据、又泄露内存内容）。已加一行守卫：短读即放弃本次删除（删除属清理动作，放弃无害，且不增净行数）；快路径同时补上与慢路径同款的大小上限，避免大转录下的读写尖峰。

2. 协作设置弹窗对「不在花名册的会话」永久转圈

• 现象：对不在花名册里的会话打开「协作设置…」，弹窗永久停在加载态，无失败态、无超时、无重试，提交按钮一并锁死（隔离演示实例观察 25 秒不消失）。
• 根因：原判断「编辑模式 && 未读到该会话」无法区分「花名册还没加载完」与「花名册加载完了、确实没这条」——后者恒为真 ⇒ 永远停在加载态。
• 修法：引入三态（加载中 / 就绪 / 不在花名册）：拉取完成后仍无此条，则给出明确的失败提示 + 重试按钮；该状态下提交按钮同样锁死（避免空表单被误提交覆盖原身份）。五语言各补一条文案，新增组件测试。

3. 端口文件读写两侧统一跟随配置目录（隔离实例不再污染 / 错读）

• 背景：端口发现文件（desktop-server.json）此前固定在 ~/.claude/cc-heihei，配置目录环境变量不参与 ⇒ 跑一个隔离实例会覆盖真实应用的端口记录，任何读它的工具（员工汇报、CLI 投递）会打到错实例。
• 修法（本版补齐两侧）：
  • 写侧 / 默认目录：默认路径改用「配置目录优先」的解析，隔离实例落在自己的配置目录内；显式传入 home 的既有契约不变。
  • 读侧：独立实测发现读侧此前没跟着改（仍以 home 为基准）——隔离实例读不到自己的端口文件、回落拿到真实应用的地址。本版把两处读取方一并改为同一解析，并补测试锁死「读侧确实接上了」。
• 兼容性：未设该环境变量时解析结果与旧写法逐字相同 ⇒ 真实用户零影响。

4. 台账 replay 缺字段行归一为 []

• 现象：任务台账里只要出现一行缺 deliverables / history 字段的数据（手写行、旧版本写的行），会让整份台账加载失败，而不是只跳过这一行。
• 更正说明（如实）：复核发现「坏 JSON 行的隔离跳过」早已存在；真正的缺口是 created 分支没有做字段归一——缺字段的行照旧入账，之后读路径展开时才抛错。
• 修法：缺失字段统一 ?? [] 兜底 + 入口归一，并对「发生归一的坏行」记一条诊断（可观测、不静默）；与同模块对旧数据兼容的既有口径保持一致。新增用例覆盖。

5. turn-checkpoints 慢点：「O(n²)」已证伪，成因未定（本版未修）

• 背景：上一版把「客户端 Request timed out after 320s」的根因候选指向某内部 checkpoint 拉取的结构性 O(m·n)。
• 本版实测结论：
  • 三个真实会话（6.6k / 12.9k / 20.3k 行）只读副本实测 2.1s / 70.7s / 54.5s——中档比大档还慢（非单调），且小→中 checkpoint 数只 +4% 而耗时 ×34 ⇒ 与规模、条目数均无关，复杂度假设被证伪；同测另一接口 258/376/647ms 呈 ≈O(n) 作对照；
  • 同一份 83MB 转录四次实测 4.1 / 54.5 / 68.8 / 70.7 秒（差约 17×） ⇒ 不是稳定的算法复杂度问题，更像外部状态相关（磁盘 / 页缓存 / 内存压力、JIT / GC 状态）；
  • CPU profiler 曾在慢跑里看到 82.9% 采样落在运行时正则引擎，但逐正则微探针实测三条候选正则合计仅 ≈0.1%，且快跑里该热点不出现 ⇒ 该「正则热点」可能是果而非因（推断，未证实）。
• 状态：成因未定、修法未落地、本版零代码改动——带数据挂档；下一步需多次采样 + 记录同刻系统状态继续分诊。

衍生修复

• 「320 秒超时」不再呈现为业务失败：Request timed out after 320s 此前被当普通错误弹红条，暗示「失败 / 重试」；实际它只断了连接、业务仍在后台跑。现在超时文案改为**「连接已超时；任务可能仍在后台运行，稍后刷新即可查看结果」，turn-change 错误条在超时态改用中性提示条**（而非红色失败条），并给了「刷新查看」的出路（五语言同步）。
• 409 跨项目派活文案的正则边界：已知服务端错误串的映射正则补回了词边界 \b（此前是前缀匹配），使这条业务错误串与相似串的区分更精确。
• CI 红灯：两笔测试侧修复（改动只在测试与断言，不碰产品行为）：
  • dispatch-mailbox 用例在 CI 上因 Windows %TEMP% 的 8.3 短路径（如 RUNNER~1）导致路径归一化不识别、台账过滤出 0 条——改用 realpath 后的规范路径；
  • MessageList 的 selectionchange 用例在慢机上因两帧 rAF 早于处理完成而同步查询不到按钮——改为带超时的显式异步查询。

结构与门禁

• 两条结构豁免（sessionService cap 3846 / handler cap 3372）expiresInVersion 由 1.7.3 续签至 1.7.4，理由＝「1.7.3 已含红灯区缺陷批 ⇒ 条件达成」。
• 如实口径：两个文件当前已超自身基线（sessionService 3796 > 3795；handler 3351 > 3322），续签后由 cap 覆盖；这是「红灯批＝修复批、非减行批」的直接结果，不是新债。

文档与站点（用户可见）

• 双语 README 与文档站首页按授权缩墙：撤下已无法重拍的旧一代界面截图，只保留当前且经验证的截图（新建会话欢迎页、本地模型页），并同步了截图规范与图注。

已知限制与未验证项（如实，不美化）

• #5（turn-checkpoints 慢点）为挂档项：本版未修，成因未定（详见上）。
• CI 两笔测试侧修复尚未经 CI 验证：相关提交尚未 push，只在本地 / 预检环境验证过；须 push 后由 CI 判定。
• tasks.test.ts 负载型偶发（v1.7.1 挂账）仍在：该文件曾在流水线内红过、但失败签名缺失，独立复现多次全绿，未登记进 known-flaky；本版未见新增证据，仍待 CI 观察。
• removeMessageByUuid 快路径的 64KB 窗口丢尾（既有债务，非本版引入）：快路径只读文件最后 64KB 找目标行，若目标行落在窗口内、而其后的存量超出窗口，则新旧两版同样会丢掉窗口外的尾部。触发条件窄（目标行不在末尾且其后存量 > 64KB）。v1.7.4 候选：needle 不在窗口末尾时回退慢路径。
• Bun truncate 的上游修复未证实：本版用「换操作方式」绕开；上游 changelog 未见对应条目、issue 库未搜，升级 Bun 能否根治未证实。

债务与豁免（如实披露）

• sessionService.ts 豁免 cap 3846、handler.ts 豁免 cap 3372，均 expiresInVersion 1.7.4。

升级说明

• 无破坏性变更；通过应用内「检查更新」即可升级（latest.yml + blockmap 支持增量下载），也可重新下载安装包覆盖安装。
• 启动后调用 GET /api/whoami 可查看当前运行版本号（返回 app、version、pid、startedAt）。

v1.7.2

Claude Code Heihei v1.7.2

让会话不再「静默假死」：修掉两个会让会话停在那里、既不报错也没有下文的问题——一个用错误地址把会话「起了却连不上」，一个是在等一个永远等不到的批准；并补上对应的可见性提示与兜底。无破坏性变更。

修复：会话静默假死的两个根因

1. 协议通知用一个无效地址去拉起会话

• 现象：某些会话会被「拉起」成一个僵尸会话——进程真的活着，但服务端零连接日志，投递显示成功（HTTP 201）却永远没有下文，会话卡住不动、transcript 不落盘。
• 根因：服务端启动时发出的「协议更新通知」，在拉起当时未运行的主管会话时，传的是一个端口为 0 的无效地址，命令行照着去拨号，自然永远连不上服务端。而这条通知有一个「已发送」标记文件——真实环境下早已存在，使它提前返回，于是这个缺陷长期被掩盖，只在全新环境（如隔离测试环境）里才暴露。
• 修法（四条一起）：
  1. 通知只发给正在运行的主管会话，不再为了发通知把没运行的会话拉起来（避免凭空创建会话、白烧额度）；
  2. 去掉那个端口 0 的常量，改取真实端口；
  3. 投递入口拒绝无效地址（缺端口、端口 0、越界等一律报错，让它当场显形而不是变成僵尸）；
  4. 「拉起成功」必须以真的连上为准——未确认连接前不再打印成功日志、不再把会话标记为运行中；同时不阻塞投递主路径（投递仍照常快速返回 201，后台补确认；迟到连上也算数）。
• 怎么验证的：三组实验确证根因——预置标记文件 → 不再复现；只造主管会话（不派活）→ 仍复现（说明「拉起者」就是通知本身）；交换投递顺序 → 无差异；无标记时 6/6 复现。修复后经真实流程验证：服务端出现连接日志、transcript 落盘。（未核实：提纲提到的「两轮端到端验证」具体轮次未在提交中逐条核到。）

2. 权限等待没有任何超时

• 现象：非员工会话（主管 / 用户）的工具调用若需要人工批准而无人应答，会永久等待——回合永不结束、会话假死；卡死期间后续消息全部排队。
• 根因：待批准的权限请求存在内存里，没有任何超时或过期机制，也没有任何东西会在无人应答时把它收掉。
• 修法：加两档有界超时——界面上有客户端在线时 15 分钟、无客户端时 90 秒（对齐现有重连退避上限，留约 3 倍余量）；到期自动拒绝并让回合继续跑完；客户端中途接入只延长、断开不缩短；对不存在的请求重复应答变成空操作（顺手堵掉「双击」竞态）。
• 怎么验证的：端到端冒烟跑通——90 秒整触发自动拒绝 → 工具被拒（is_error）→ 回合带着「工具被拒」继续至完成。单测覆盖两档、幂等、会话关闭清定时器等。

可见性与兜底

• 权限超时自动拒绝会显形：消息流里追加一行中性灰系统提示（五种界面语言），明确表达「该请求已被自动拒绝、工具未执行」——不会让你误以为工具跑过了；等待中另有一行静态提示（刻意不显示倒计时，因为中途接入会延长、数字会跳变）。
• 看门狗扩展到「被程序化拉起的主管会话」：这类会话假死时会被告警并做有限重推；绝不自动拉起——不替用户做「要不要起一个会话」的决定。（注：在权限卡死场景里，重推排在卡死回合之后，救不活它——真正救活靠上面的超时拒绝。）

内部改进（用户无感）

• 转录读取缓存：同一个转录文件此前会被整读 3–5 次（派活守卫、会话信息查询、各接口校验各读一遍）；改为内容寻址缓存后，三处解析型读取点换线，实测整读 3 → 1（有端到端整读计数与对照组验证）。
• 新逻辑落进 conversation/ 子模块，不为新特性单开行数豁免。
• 体积门禁口径修复：豁免条目的专属上限现在优先于基线（此前二者自相矛盾）。
• 新增回执消费诊断：补上「自动拒绝 → 派活方回执被消费」这条链此前没有任何正向物证的验证盲区（只加记录，零行为变更）。

已知限制与未验证项（如实，不美化）

• 渲染层视觉未真机走查：权限超时提示的字号、圆点、无动画等细节无组件测试锁定，由设计稿验收兜底，真机呈现需你走查（员工无法启动应用）。
• 720px 短屏降级未做：触发条件已定（真机走查发现该行过高时再做），届时需先补齐五种语言的短版文案。
• 转录缓存的失效风险：若发生「同尺寸重写 + 时间戳精度不足」的极端情况，理论上可能读到旧内容；已与既有摘要缓存用同一口径、触发概率极低故接受。但后果面更大——该缓存承载的是模型上下文（旧内容会污染模型输入）。将来若改「原地等长替换」的清理逻辑，两处缓存需一并复核（锚点已写进代码注释）。
• 「被投递拉起」标记不持久化：重启后该标记丢失，相关问题会静默回到豁免状态（已接受的取舍，如需覆盖属二期）。
• 无客户端 15 分钟档未做端到端覆盖（测试装置里没有桌面客户端）。
• 「320 秒超时」专项排查进行中：据主管口径，已定位为某内部循环的结构性候选成因，但 O(n²) 尚未证实、修法尚未落地——本版未修。（未核实：该项未在提交历史或仓库中找到对应物证，以事实为准。）

债务与豁免（如实披露）

• sessionService.ts 豁免上限续签为 3846（= 实测 3796 + 50），至 1.7.3，附条件「1.7.3 须含红灯区批次」。请注意：本版对该文件是「成本解耦」而非「减少行数」（净 +1 行）——诚实的口径就是不声称减行。
• handler.ts 豁免上限 维持 3372，至 1.7.3。

升级说明

• 无破坏性变更；通过应用内「检查更新」即可升级（latest.yml + blockmap 支持增量下载），也可重新下载安装包覆盖安装。
• 启动后调用 GET /api/whoami 可查看当前运行版本号（返回 app、version、pid、startedAt）。

v1.7.1

Claude Code Heihei v1.7.1

错误更好懂、Windows 保存不再失败：修掉一个 Windows 上「保存项目/本地 agent 编辑必然失败」的真缺陷；错误提示改为「人话标题 + 可折叠技术详情」，并把 26 处瞬时提示从英文技术串改成人话；协作消息的手写汇报也能被折叠；另有内部结构收尾与首次跑通全量自动化测试。无破坏性变更。

修复：Windows 上「保存 agent 编辑」必失败

• 现象：在 Windows 上更新（保存）一个项目/本地 agent 的编辑必然失败——不是偶发，是每次。
• 根因：写入时用的是一个「数值形式」的文件打开标志。原意是防止误写符号链接，但在 Windows 上其中一个安全标志位实际是 undefined（相当于没生效），使这串数值变成了 513——这个组合带着「清空原文件」却没带「文件不存在就创建」，被系统直接判为非法参数而拒绝。所以问题不在「某个标志不被支持」，而在标志组合本身在 Windows 上非法。
• 修法：Windows 上改用字符串形式的打开方式（语义与原意一致：覆盖写入、必要时创建）；非 Windows 分支与原来逐字相同，原有的安全检查一处未动。
• 值得说明的是：这个缺陷是跑测试发现的——测试基线里它一度被判为「平台不支持、跳过即可」，复核后确认为产品真缺陷，跳过只会把用户故障藏进绿色的基线。修复后该文件 12 项全过（原 9 过 3 败，3 条自然转绿）。

错误提示更清楚

• 错误态新增「人话标题 + 可折叠技术详情」：以前出错只有一个原始错误串；现在默认展示人话说明，右侧有「技术详情 ▾」按钮，默认折叠，展开可看到原始错误、错误分类与时间，并可一键复制。信息层级以人话为主，技术块用中性灰、不抢错误红的视觉。
• 26 处瞬时提示人话化：散落各处的英文技术错误串（如超时、连接失败）改为中文人话；业务错误仍原样显示（有信息量的不翻译）。
• 跨项目操作的 409 提示接入人话：此前这类拒绝会直出英文，现在显示可读说明（本条对应「跨项目派活被拒绝」）。
• 根崩溃屏不再只显示一行原始串：应用启动期崩溃时，改为「双语静态标题 + 可换行、可复制的原始错误块」（该界面在界面框架加载前触发，无法使用常规的错误组件，故采用最小可行做法）。
• 五种界面语言同步。

协作消息

• 手写汇报也能被折叠：此前只有通过协作工具发起的汇报会被折叠成卡片；若手写（直接发 HTTP）则不会。现在派活消息的页脚里加入了「手写汇报必须附任务号」的指引——照做即可被折叠。（已派出的旧派活不追溯；新派活生效。）
• 汇报消息带上「汇报自：<角色>」：汇报页脚新增来源角色信息，便于在折叠卡上分辨是谁汇报的。
  • 未验证/说明：该信息的服务端注入已就位，但折叠卡上把它显示出来的前端部分尚未实现（本版只做了服务端这一半）；「员工汇报 → 折叠卡显示汇报自谁」的端到端也未实跑。

内部结构（延续 v1.7.0 的拆分收尾）

• chatStore.ts：2504 → 2469 行，已达 2500 行的标准、还清此前登记的豁免。
• handler.ts：3500 → 3322 行，把一组零依赖纯函数迁入新模块 handlerPures.ts（净减约 178 行）。状态相关的大块经普查后判定「搬了反而更大」而保持不动。

测试与工程：本版首次跑通全量自动化测试

• 本版首次跑通了全量自动化测试：覆盖 src 286 个测试文件、desktop 240 个测试文件（合计约 6500 个用例规模；其中 desktop 基线为 3312 用例 / 0 失败 / 0 跳过 已核实）。测试在本机是安全的：按目录分段、逐文件、带内存守卫，全程可用内存充足、无进程被杀。
• 处置了 v1.7.0 测试基线的 9 条红——分类如下（合计 9）：
  • 1 条真缺陷：上面的 Windows 保存失败。
  • 2 条环境隔离问题：测试夹具未隔离宿主注入的环境变量（src/constants/system.test.ts、src/entrypoints/sdk/coreSchemas.modelInfo.test.ts）——加装保存/还原。
  • 1 条既有 flaky：computer-use-api.test.ts 钩子层超时——加显式超时加固（断言零改动）。
  • 2 条夹具失真：servants.test.ts 两条用例用了磁盘上不存在的「幽灵会话 id」，被同项目守卫判为伪造——改用真实落盘夹具，守卫与断言一字未改（零产品行为变更）。
  • 2 + 1 条测试滞后于有意变更：默认超时 120s→320s、错误提示人话化等按需求改了产品、测试没跟上——按新行为同步测试，未削弱覆盖（断言原文经独立核对）。
• 新增出包前验证脚本 scripts/preflight-release.mjs：把「出包验证」变成可重复的四阶段流程（gates / test / build / smoke），含内存守卫与每段核对「实际跑了多少用例文件」（防止「静默漏跑」造成假绿）；失败会按「偶发 / 已知 flaky / 疑似真回归」分栏。绝不 push、不建 Release、不动 git 历史。
• import 语义检查固化入 scripts/ 并接入 gates：把 v1.7 拆分期间靠临时脚本抓出的「导入语义漂移」类缺陷（典型如 fs 导入导致的全线「目录缺失」）变成正式关卡——非零退出即失败，并已自证有判别力。
• 出包前验证（preflight）本版首次真跑，四阶段结果如实如下：gates ✓（23 秒，0 失败：工作区干净 / 版本号 1.7.1 / 类型检查 0 错误 / 源码语法 2718 文件 / 门禁字面量 8/8 / import 语义检查通过）；test ✓*（929 秒，覆盖 120 多个 src 段 + src/server 逐文件 + 12 个 desktop 批，实质失败 0）；build ✓（223 秒，产出 Windows 安装包）；smoke 4/6（未过的两项见「已知限制与未验证项」）。过程中暴露的成片红全部是验证脚本自身的假红：首跑连修 5 处工具缺陷（环境变量假删除、desktop 批路径前缀、src 段失败无落盘、段清单缺 ./ 锚定导致 src/hooks/ 误吃 desktop/src/hooks/ 的 jsdom 用例、smoke 页脚断言契约）——修完这些后产品侧零回归。

已知限制与未验证项

• 非 Windows 分支无法在本机运行验证：修 Windows 缺陷时，非 Windows 的那条分支只做了静态核对，未在本机执行（本机是 Windows）。
• 图标字形与剪贴板权限需真机确认：错误详情的展开按钮用了图标字体，「一键复制」依赖剪贴板权限——两者的真机呈现与权限行为需在真机上确认（未验证）。
• 协作折叠端到端未实跑：见上文「协作消息」——「汇报自谁」的前端展示尚未实现，端到端未验证（本版 smoke 中对应的页脚端到端两项亦未通过，见下）。
• 出包前验证（preflight）首跑的挂账与未验证项（如实记录，均不写成已解决）：
  • 挂账 1 项：src/server/__tests__/tasks.test.ts 在流水线内红了 2 次，但失败签名缺失（当时 src 段未落盘），独立复现 ≥4 次全绿（含整目录负载 98 文件 / 2048 用例）；未定栏、未登记进 known-flaky（判定标准：签名缺失不足以证明是偶发）；下轮 preflight 若再现即定案。
  • smoke 两项未通过（页脚端到端 + 反例）——非本版引入：投递给主管会话的汇报，HTTP 201 成功、命令行进程已拉起（有 PID）、turn_started 已注入，但该回合始终不完成、transcript 不落盘，导致断言取不到末行；用 v1.7.0 的包跑同一流程行为完全一致 → 不是 v1.7.1 的回归；同一场景下员工侧会话投递正常。已另行排查（链路卡点、主管与员工侧差异、是否「新建且无 transcript 的主管会话」特有、以及在真实使用中投递给主管的消息会不会因此静默丢失、既有超时与可见性防护）。smoke 断言保持原样，链路问题解决后会自动转绿。
  • 因此，smoke 的页脚端到端两项本版未能验证（其余 4 项——工作目录状态回归、派活台账取到 taskId、产物门禁字面量 8/8、拉起超时伴生串与数值——均通过）。
• 折叠卡真机渲染、窄屏下较长的页脚行展示等，均为未验证。

债务（如实披露）

• sessionService.ts（3795 行）本版未拆：剩余部分为实例状态耦合 / 公开 API / 需专项设计的区域。其行数豁免上限 cap 3800 重签到 1.7.2，并附带条件「1.7.2 必须包含红灯区首批实施」。
• handler.ts 豁免上限收紧到 3372，同样续签到 1.7.2。
• 此前 chatStore.ts 的豁免已还清（条目从豁免清单删除）。
• 另有一批「零依赖小簇 / 依赖本地类型的簇」被登记为后续搬迁债务（注：提纲提到的「12 个零依赖小簇 + 2 个依赖本地类型的簇」这一具体数量，在提交历史与豁免清单中未逐条核到，以架构裁决文档为准）。

升级说明

• 无破坏性变更；通过应用内「检查更新」即可升级（latest.yml + blockmap 支持增量下载），也可重新下载安装包覆盖安装。
• 启动后调用 GET /api/whoami 可查看当前运行版本号（返回 app、version、pid、startedAt）。
• 建议桌面应用与其命令行组件使用同一版本。