Skip to content

persist EPERM 根治(#362 follow-up):可诊断告警 + Windows AV 排除文档 #367

Closed

Description

@ranxianglei

背景

#362(Windows persist EPERM 风暴:4,879 次写失败 / 117 会话静默丢数据)的韧性层已由 acp-kernel PR #172 修复并合并(merge commit a559247):

  • 指数退避重试(默认 6 次 / 50ms 起 / 1600ms 上限,可配)
  • 最终失败 spill 到旁路文件 <name>.fb.json(不再 unlink 丢数据;loadAll 按 savedAt 调和 canonical/spill)
  • 限流告警(1 次 error + 之后按 2 的幂 warn,不再逐条刷屏)

但 #362 的根本修复还差两层——让用户能定位并自己修掉环境锁:可诊断告警(Layer 2)+ Windows AV 排除文档(Layer 3)。目前这两层没有任何 PR 覆盖。

根因回顾(多层叠加)

层 性质 状态
触发:sessions 目录的持久锁(Defender/索引器/同步工具) 环境 ❌ 代码修不了,需用户加 AV 排除
放大:长会话每轮 persist(高频写) 代码 —(可接受)
持续:无自愈(无回退文件名) 代码 ✅ PR #172 spill
量:逐条 error 刷屏 代码 ✅ PR #172 限流

关键:触发层是 reporter 机器上的环境锁(跨天粘滞 ~20h、从单会话扩散到 117 个 → 目录级锁),代码消不掉。PR #172 让锁发生时不丢数据、不刷屏,但用户仍看不到「该加 AV 排除项」的提示——失败在日志里只是限流的 [persist] ... failed,不指向根因,用户无从下手。

要做的事

1. 可诊断告警(Layer 2,主)

billion-context 侧检测 persist 对同一 id 连续 N 次 EPERM(N 建议 5,可配),打一次性可操作告警(之后静默或每 M 分钟最多一次),明确指向根因 + 解法:

[persist] 会话目录 <dir> 连续 N 次写失败(EPERM,rename 被锁)。
大概率是 Windows Defender/杀软/索引器/同步工具锁住了该目录。
请把 <dir> 加入 Defender 排除项(设置 → 病毒和威胁防护 → 管理设置 → 排除项 → 添加排除),
并确认没有 OneDrive/同步工具在同步该路径。

实现要点:

  • 检测点:billion-context 包装 acp-kernel StateStore 的地方(src/persist.ts),通过 store 的 log 回调或失败计数识别「同一 id 连续 EPERM」。
  • 若 acp-kernel 未暴露「连续 EPERM 失败」信号,可在 kernel 侧加一个轻量回调/计数器(通用,不写 Windows 特定文案);诊断文案放 billion-context(AV 排除是 Windows/billion-context 特定的,不该写进通用 kernel)。
  • 告警一次性(或每 M 分钟最多一次),避免又变成刷屏。
  • 仅 Windows + EPERM/EBUSY/EACCES 触发此告警(避免非 Windows / 非文件锁场景误报)。

2. Windows AV 排除文档(Layer 3)

README / CONFIGURATION(EN + zh-CN)加 Windows 章节:

  • 把 %USERPROFILE%\.local\share\billion-context\ 加入 Windows Defender 排除项(附步骤)。
  • 不要用 OneDrive/同步工具同步该目录。
  • 说明:高频 persist 会反复触发杀软实时扫描,加入排除项后可避免 EPERM 写失败。

验收标准

  • persist 对同一 id 连续 N 次 EPERM → 一次性可操作告警(指向 AV 排除);非 EPERM / 非 Windows 不触发。
  • 告警不刷屏(一次性或低频重复)。
  • 文档(EN + zh-CN)含 Defender 排除项步骤 + OneDrive 警告。
  • 新增测试覆盖「连续 EPERM → 告警一次」+「非 EPERM 不告警」+「非 Windows 不告警」。
  • npm run typecheck / npm test / npm run build 全绿。

参考

Activity

  1. ranxianglei commented on Aug 31, 2026

    @ranxianglei
    OwnerAuthor

    🤖 ework agent · vllm-qwen/qwen3.8-27b

    [bot] 收到 #367,开始处理 Layer 2(可诊断告警)+ Layer 3(Windows AV 排除文档)。

    先报一个关键发现(影响 #362 的完整闭环):

    我的计划:

    1. Layer 2(主):在 src/persist.ts 包装 acp-kernel StateStore 的 log 回调,检测「同一 id 连续 N 次 EPERM/EBUSY/EACCES」(N 默认 5,可配),仅 win32 触发,打一次性可操作告警(指向 Defender 排除项 + OneDrive 警告),之后静默(可配每 M 分钟最多一次)。检测逻辑放独立可测模块,不依赖 PR fix: harden context window — self-heal on upstream overflow + reserve output headroom #172——对当前 pin 的 0.0.46 即可工作(0.0.46 的写失败日志格式 [persist] write failed for <id>: <err> 已确认)。
    2. Layer 3:README / CONFIGURATION(EN + zh-CN)加 Windows 章节(Defender 排除项步骤 + OneDrive 警告)。
    3. 测试:连续 EPERM → 告警一次 / 非 EPERM 不告警 / 非 Windows 不告警 / 限流不刷屏。
    4. typecheck + test + build 全绿后开 PR。

    acp-kernel stable 发布 + 本仓库 pin bump 是跨仓库依赖,我会单独跟进(稍后补一个 issue 跟踪)。继续干活,有进展再回。

  2. ranxianglei commented on Aug 31, 2026

    @ranxianglei
    OwnerAuthor

    🤖 ework agent · vllm-qwen/qwen3.8-27b

    #367 的两层(Layer 2 可诊断告警 + Layer 3 Windows AV 排除文档)已完成,PR: #373

    Layer 2 — 可诊断告警(主)

    • persist 对同一会话 id 连续 N 次(默认 5,BILI_PERSIST_EPERM_ALERT_THRESHOLD)以文件锁错误(EPERM/EBUSY/EACCES)失败时,打一次性可操作告警:点名会话目录 + 指向 Windows Defender 排除项 + OneDrive/同步工具警告。
    • 默认一次性;可选低频重复(BILI_PERSIST_EPERM_ALERT_REPEAT_MS,0 = 一次性)。
    • 仅 Windows + 仅锁类错误触发 → 非 Windows / 非锁错误不告警(不刷屏、不误报)。
    • 检测点:src/persist.ts 包装 acp-kernel StateStore 的 log 回调。debounced scheduleSave 路径会吞掉写错误,其 [persist] (write|flushSync|shutdown flush) failed for <id>: <err> 日志是热路径唯一信号。新增 src/persist-eperm.ts(PersistEpermAlert 检测器,platform/now/onAlert 可注入便于测试)。对当前 pinned acp-kernel 0.0.46 即可工作,无需跨仓改动。

    Layer 3 — 文档

    README / CONFIGURATION(EN + zh-CN)新增 Windows 章节:Defender 排除项步骤 + OneDrive 警告 + 高频 persist 反复触发杀软实时扫描的说明。

    测试

    • 新增 tests/persist-eperm.test.ts(11 单测:第 N 次才告警 / 低于阈值 / 非锁错误 / 非 error 级 / 非 Windows / 一次性 / 限流节奏 / 按 id 计数 / 三种内核失败类型 / 无关日志不误匹配 / 告警文案)。
    • tests/proxy-persist.test.ts 集成:真实 SessionStore 把写失败路由过检测器,非锁错误不误告警。
    • 预检:npm run typecheck 干净 / npm test 862/862 通过 / npm run build 成功。

    ⚠️ 一个重要发现(已另开 issue 跟踪)

    当前 pinned 的 acp-kernel 0.0.46 并不包含 PR #172(spill 到 <name>.fb.json / error 限流)——已对安装后的 dist 验证:无 spill 代码、最终失败仍 fsp.unlink(tmp) 丢数据、无 error 限流。PR #172 只在 acp-kernel master / prerelease 0.0.46-pr.172.23。

    含义:在 acp-kernel 出一个含 PR #172 的 stable、且本仓 bump pin 之前,已发布的 billion-context 仍会复现 #362 的丢数据 + 刷屏。 本 PR 的 Layer 2 独立于 0.0.46(让锁「可诊断」),但「不丢数据」的韧性仍需 kernel bump。跨仓依赖(acp-kernel 先发 stable → 本仓 bump pin)我另开 issue 跟踪。

  3. ranxianglei commented on Aug 31, 2026

    @ranxianglei
    OwnerAuthor

    🤖 ework agent · vllm-qwen/qwen3.8-27b

    跨仓依赖的跟踪 issue 已开:#374 (acp-kernel PR #172 未进 stable 0.0.46 → #362 丢数据/刷屏仍 live,需 acp-kernel 先发 stable 再 bump pin)。

  4. ranxianglei commented on Aug 31, 2026

    @ranxianglei
    OwnerAuthor

    更新了 看看状态

  5. ranxianglei commented on Aug 31, 2026

    @ranxianglei
    OwnerAuthor

    🤖 ework agent · vllm-qwen/qwen3.8-27b

    状态更新:

    「更新」我看到了 —— acp-kernel 0.0.47 已发布,含 PR #172(spill 到 <name>.fb.json + 指数退避重试 + error 限流),我已对装好的 dist 逐条验证(recordFailure / spillPathFor / backoffMs = min(retryBaseMs·2^attempt, retryMaxMs))。master 也已把 pin 升到 0.0.47 并发 v0.1.66 —— 所以 #374 的「acp-kernel 先发 stable → 本仓 bump pin」这两步你已经做完了,#374 可以关掉了(Layer 1 韧性现在真正 ship 了)。

    但我发现 PR #373 的 Layer 2 检测器和 0.0.47 不兼容,正在修:

    • 0.0.47 把写失败日志从 [persist] write failed for <id>: <err> 改成了 [persist] write failed for <id> (total <N>x): <err>; data spilled to …,并且内核自己做了限流(只在 count=1,2,4,8… 打日志)。
    • 我原检测器按旧格式解析 + 自己逐条计数 → 在 0.0.47 下:正则会捕获成 <id> (total Nx)(按 id 计数失效),且内核限流后我看不到连续 5 条 → 告警永远不触发。
    • 修法:直接解析内核日志里的 (total <N>x)(内核的 count 就是「连续失败数」,成功即 clearFailure 重置),当 N ≥ 阈值 时告警。更简单也更稳,还顺带拿到 spill 路径信息。

    我更新 PR #373(检测器 + 测试 + rebase 到新 master)并跑绿后回你。

  6. ranxianglei commented on Aug 31, 2026

    @ranxianglei
    OwnerAuthor

    🤖 ework agent · vllm-qwen/qwen3.8-27b

    修好了,PR #373 已更新(rebase 到新 master + 适配 acp-kernel 0.0.47),全绿。

    改动(Layer 2 检测器适配 0.0.47):

    • 0.0.47 的写失败日志是 [persist] write failed for <id> (total <N>x): <err>; data spilled to …,且内核自己限流(只在 N=1,2,4,8… 打)。
    • 检测器改成直接解析内核日志里的 (total <N>x)(N 就是内核维护的「同 id 连续失败数」,成功即 clearFailure 重置),当 N ≥ 阈值(默认5) 且 win32 且 err 命中 EPERM/EBUSY/EACCES → 打一次性可操作告警(指向 Defender 排除项 + OneDrive 警告)。
    • 不再自己逐条计数(内核限流下逐条计数会漏 + 把 <id> (total Nx) 误当 id)。level 门槛放宽到 error|warn(内核 count≥2 打的是 warn)。
    • 测试重写:覆盖「N 跨过阈值→告警一次并带内核 N」「低于阈值不告警」「非锁错误(ENOENT)不告警」「warn 接受 / info 拒绝」「非 win32 不告警」「one-shot」「限频重复」「EPERM/EBUSY/EACCES 都触发」「无关日志行不匹配」。

    验证:

    • npm run typecheck 无错
    • npm test 874/874 通过
    • npm run build 成功(dist 2.56 MB)
    • 集成测试里抓到了 0.0.47 真实日志行 [persist] write failed for wire-1 (total 1x): ENOTDIR …; SPILLOVER ALSO FAILED — data at risk,确认检测器在路径上且对非锁错误不误报。

    PR #373:#373 (open,无冲突,等 CI / 你合并)。

    #374 可以关掉了 —— acp-kernel 0.0.47(含 PR #172)已发 stable、master 已 bump pin 并发 v0.1.66,Layer 1 韧性已真正 ship。

  7. added a commit that references this issue on Sep 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions