WorkBuddy 知识营地

Appearance

踩坑诊断库 ​

所有 Skill、MCP、工作流仅供个人学习测试，功能、计费、权限以 workbuddy.cn 官方为准。

诚实声明：本库条目为通用排查框架，真实案例实录将在运营中逐步补充并标注来源。

本库按故障大类组织，收录 7 大类、12 条通用排查框架。每条结构固定：现象 → 排查 → 根因 → 修复，并附排查示例、截图脚本占位清单、预防 checklist 与小红书引流文案。涉及 WorkBuddy 专有行为（定时任务机制、缓存路径、上下文窗口大小、计费口径等）一律标注「待核验（以 workbuddy.cn 官方为准）」，不编造官方版本号、错误码与功能细节。

一、MCP 故障合集 ​

以下为通用排查框架，非真实案例记录；具体根因请结合你的实际环境逐项验证。

MCP-01 · MCP 工具卡片红色离线 / 连接失败 ​

现象 ​

  • 已配置的 MCP 工具在客户端显示红色"离线/未连接"状态；

  • 调用时提示"连接失败/超时/无法到达"类通用文案；

  • 同账号下部分 MCP 正常、个别 MCP 异常，或全部异常。

排查（按顺序逐项验证） ​

  1. 确认是单个 MCP 异常还是全部 MCP 异常：全部异常优先怀疑本地网络/账号登录态。

  2. 查看该 MCP 的连接配置（地址、端口、Token 字段名）是否仍与服务端一致；重点核对是否多了空格、换行、截断。

  3. 在本机用通用网络工具（curl/浏览器/终端）直接访问该 MCP 服务地址，判断是客户端问题还是服务端不可达。

  4. 检查 Token/密钥是否过期、是否被服务端吊销；重新生成一次最小权限 Token 测试。

  5. 切换网络（手机热点 vs 办公网）排除代理/防火墙拦截；企业内网常见出站 443 被审计代理劫持。

  6. 重启客户端并重新加载 MCP 配置，观察状态是否由红转绿。

根因（常见类别） ​

  • 凭证类：Token 过期/写错字段/复制时带了多余字符。

  • 网络类：本机断网、代理拦截、DNS 解析失败、服务端临时不可用。

  • 配置类：地址变更后未同步、端口写错、JSON 配置少了引号导致解析失败。

  • 客户端类：会话内 MCP 加载状态卡住（待核验：以 workbuddy.cn 官方为准）。

修复（根治 + 预防） ​

  • 根治：按上述排查命中根因后修正配置或凭证；Token 走环境变量或密钥管理工具，禁止明文写进 Skill 脚本或提交到 git。

  • 预防：建立"MCP 健康检查清单"，每周一开工先看一眼连接状态；新增 MCP 时先在测试会话验证再挂到生产工作流。

排查示例 ​

bash
curl -v -m 5 https://<your-mcp-host>/health
# 期望：HTTP 200 或你方服务定义的健康检查响应
# 异常：超时 → 网络/防火墙；401/403 → Token；DNS 错误 → 本机解析

截图脚本占位清单 ​

序号页面/位置要展示的报错或界面元素标注说明
S1-1MCP 列表页红色离线状态徽章 + 工具名待补：需在真实客户端按此清单截图
S1-2MCP 配置详情抽屉地址/Token 字段（Token 打码为 ****）待补：需在真实客户端按此清单截图
S1-3调用报错浮层完整报错文案待补：需在真实客户端按此清单截图

预防 checklist ​

* [ ] MCP Token 存入环境变量/密钥工具，脚本内引用 $\{MCP\_TOKEN\} 占位

* [ ] 新增 MCP 先在独立测试会话跑通 3 次再接入工作流

* [ ] 每周一上午巡检 MCP 连接状态，红色项当天处理

* [ ] 配置文件纳入版本管理但 \.env 类密钥文件 \.gitignore

小红书引流文案：MCP 又红了？别着急重装——这张排查地图帮你 5 步定位是 Token 过期还是网络被墙。

MCP-02 · MCP 参数报错 / 权限拒绝 ​

现象 ​

  • MCP 连接正常，但调用某工具时返回"参数缺失/类型错误/权限不足"类提示；

  • 同一个 Skill 在别人会话里能跑，在你这里报参数错；

  • 改了提示词之后突然开始报权限错。

排查 ​

  1. 对照该 MCP 的工具 schema，逐个核对必填参数是否传齐、类型是否匹配（字符串 vs 数字 vs 数组）。

  2. 检查参数里是否混入了未清理的占位符（例如仍写着 <your-token>）。

  3. 确认当前 Token 所属账号/角色是否有该工具的调用权限；最小权限原则下常见"只给了读、没给写"。

  4. 把请求参数单独打印出来，用 curl/Postman 直接打 MCP 服务，绕开客户端判断是客户端拼装问题还是服务端拒绝。

  5. 核对是否在不允许的环境调用（例如生产写接口被限制只能内网访问）。

根因 ​

  • 参数拼装：Skill 模板里变量没替换、嵌套 JSON 多了一层引号。

  • 权限范围：Token scope 不够，服务端按最小权限拒绝。

  • 环境限制：该 MCP 仅允许指定网络/指定账号调用。

修复 ​

  • 根治：补齐参数 schema、申请对应 scope 的 Token；写操作单独用写 Token，与读 Token 分离。

  • 预防：在 Skill 入口加参数自检（必填项缺失直接报错并提示哪一项），不要等到 MCP 服务端拒绝才暴露。

排查示例 ​

bash
curl -X POST https://<your-mcp-host>/v1/tools/<tool-name> \
  -H "Authorization: Bearer ${MCP_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"arg1":"<value1>","arg2":<value2>}'

截图脚本占位清单 ​

序号页面/位置要展示的报错或界面元素标注说明
S2-1工具调用报错浮层参数错误/权限拒绝文案待补：需在真实客户端按此清单截图
S2-2该工具 schema 文档页必填参数表 + scope 说明待补：需在真实客户端按此清单截图

预防 checklist ​

* [ ] 读/写 Token 分离，写 Token 只在需要写的 Skill 里引用

* [ ] Skill 入口加必填参数自检，缺项直接给出可读提示

* [ ] 每次改提示词后跑一次最小调用冒烟测试

小红书引流文案：参数报错别让模型自己猜——把 schema 贴出来对一遍，5 分钟就能定位是少传了一个字段。

二、Skill 故障合集 ​

以下为通用排查框架，非真实案例记录；具体根因请结合你的实际环境逐项验证。

SKL-01 · Skill 不触发 / 误触发 ​

现象 ​

  • 明明说了该触发的话，Skill 没被唤起，模型走了普通聊天；

  • 不该触发的时候被唤起，干扰正常对话；

  • 同一个说法，有时触发有时不触发。

排查 ​

  1. 打开 Skill 的描述（description/触发说明），核对自己这句话是否真的落在描述覆盖的场景里。

  2. 检查是否被另一个更宽泛的 Skill "抢触发"：把其他 Skill 临时禁用，单独测这一个。

  3. 用更具体的说法重试一次（带上对象名、动作名），判断是触发词太模糊还是描述过宽。

  4. 核对 Skill 是否被启用/是否在当前会话的可用范围（待核验：以 workbuddy.cn 官方为准）。

  5. 查看 Skill 执行日志/调用记录，确认是"没触发"还是"触发了但立刻退出"。

根因 ​

  • 描述过宽/过窄：触发描述和用户真实说法对不上。

  • Skill 冲突：多个 Skill 描述重叠，路由随机。

  • 未启用/版本不一致：本地修改未生效或云端版本未发布。

修复 ​

  • 根治：把 description 写成"我负责 X，不负责 Y"的边界句式；把高频用户原话加进触发示例。

  • 预防：上线前用 10 句"应触发 + 5 句不应触发"做回归测试；冲突 Skill 改边界而不是加更多触发词。

排查示例 ​

text
【我负责】当用户要做 <具体动作 A> 且对象是 <具体对象 B> 时
【我不负责】<相邻但归其他 Skill 的场景 C、D>
【典型说法】<用户真实原话 1> / <用户真实原话 2>

截图脚本占位清单 ​

序号页面/位置要展示的元素标注说明
S3-1Skill 列表页该 Skill 启用开关状态待补：需在真实客户端按此清单截图
S3-2Skill 详情/描述页description 全文待补：需在真实客户端按此清单截图
S3-3会话日志/调用记录是否命中该 Skill 的记录待补：需在真实客户端按此清单截图

预防 checklist ​

* [ ] 每个 Skill 描述明确写"我负责/我不负责"边界

* [ ] 改 description 后跑 10\+5 句触发回归

* [ ] 冲突 Skill 改边界，不靠堆触发词解决

小红书引流文案：Skill 老是"该醒不醒、不该醒乱醒"？把描述改成边界句式，触发准确率立刻上来。

SKL-02 · Skill 文件越界 / 脚本异常 ​

现象 ​

  • Skill 执行时报"无权限访问路径/文件不存在"；

  • 脚本跑一半报错退出，留下半截产物；

  • 读写范围越出了 Skill 自己的工作目录。

排查 ​

  1. 确认脚本里所有路径是相对工作目录的占位路径，而不是写死的本机绝对路径（例如 /Users/xxx/...）。

  2. 核对该 Skill 被授权的文件白名单范围（待核验：以 workbuddy.cn 官方为准），是否真的覆盖了脚本要读写的目录。

  3. 单独跑一次脚本，把 stderr 完整打印出来；常见是依赖未装、解释器版本不对、权限位问题。

  4. 检查是否在脚本里写了sudo、写了系统目录、或尝试覆盖只读资源。

  5. 核对输入文件是否存在、是否为空、编码是否 UTF-8。

根因 ​

  • 路径越界：脚本假设了一个更宽的文件权限，实际白名单更窄。

  • 脚本环境：依赖缺失、解释器版本不一致、环境变量没注入。

  • 输入异常：空文件、编码错误、外部服务返回非预期格式。

修复 ​

  • 根治：脚本内一律用相对路径 + 工作目录占位；把需要的目录写进 Skill 权限申请说明；依赖随脚本打包或在 README 写清安装步骤。

  • 预防：脚本开头加"前置检查"（文件存在性、依赖版本、环境变量是否为空），失败立即退出并打印可读错误，不写半截产物。

排查示例 ​

bash
set -euo pipefail
: "${INPUT_FILE:?INPUT_FILE 未设置}"
: "${OUTPUT_DIR:?OUTPUT_DIR 未设置}"
[ -f "$INPUT_FILE" ] || { echo "缺输入文件: $INPUT_FILE"; exit 1; }

截图脚本占位清单 ​

序号页面/位置要展示的元素标注说明
S4-1Skill 执行报错浮层完整 stderr 末 20 行待补：需在真实客户端按此清单截图
S4-2Skill 权限配置页文件读写白名单范围待补：需在真实客户端按此清单截图

预防 checklist ​

* [ ] 脚本内禁止写死本机绝对路径

* [ ] 脚本开头 set \-euo pipefail \+ 前置自检

* [ ] 失败时清理半截产物，不留下脏文件

小红书引流文案：Skill 跑一半挂了还留一堆脏文件？加个前置自检，失败立刻干净退出。

三、定时任务故障合集 ​

以下为通用排查框架，非真实案例记录；具体根因请结合你的实际环境逐项验证。定时任务的唤醒机制、会话隔离、上下文保留策略等 WorkBuddy 专有行为一律待核验（以 workbuddy.cn 官方为准）。

CRON-01 · 定时任务休眠失效 / 到点不触发 ​

现象 ​

  • 设定了每天/每小时执行，但到点没动静；

  • 昨天还在跑，今天突然不跑了；

  • 客户端关掉之后就再也不触发（待核验：是否依赖客户端在线，以官方为准）。

排查 ​

  1. 核对 Cron 表达式本身：时区是否正确、是否漏了"分/时/日"某一段、是否用了不被支持的语法。

  2. 确认任务是"启用"状态，没有被手动暂停或禁用。

  3. 查看任务历史执行记录，判断是从未触发还是从某次后停止。

  4. 检查账号登录态/会话是否过期；长休眠后重新登录一次再观察。

  5. 核对执行时段是否被周末/节假日规则过滤。

  6. （待核验：以官方为准）确认客户端/后台进程是否需要保持在线。

根因 ​

  • 表达式错：时区错位（例如按 UTC 写了北京时）。

  • 状态错：任务被禁用、会话过期、登录态失效。

  • 环境依赖：客户端未运行、后台服务临时不可用。

修复 ​

  • 根治：显式指定时区；任务列表每周巡检一次启停状态；关键任务配一个"未执行告警"。

  • 预防：新建任务后先手动触发一次验证链路通畅，不要等到第二天才发现不跑。

排查示例 ​

text
□ 表达式是否 5/6 段齐全（分 时 日 月 周）
□ 时区是否显式写为 Asia/Shanghai
□ 是否包含不被支持的特殊字符（如 @reboot 等扩展语法）
□ 与你期望的下一次执行时间是否一致（用在线 Cron 解析器核对）

截图脚本占位清单 ​

序号页面/位置要展示的元素标注说明
S5-1定时任务列表启用开关 + Cron 表达式 + 下一次执行时间待补：需在真实客户端按此清单截图
S5-2任务执行历史最近几次执行记录/空态待补：需在真实客户端按此清单截图

预防 checklist ​

* [ ] Cron 表达式显式带时区

* [ ] 新建任务先手动触发一次验证

* [ ] 关键任务配"未按时执行"告警

小红书引流文案：定好的任务一觉睡死？90% 是时区没写对——把 Asia/Shanghai 显式加上立刻见效。

CRON-02 · 定时任务重复推送 / 上下文失忆 ​

现象 ​

  • 同一个任务在同一分钟推了多次结果；

  • 任务跨轮次运行时"忘了"上一轮的中间结果，从头再跑一遍；

  • 上次的执行结论这次完全没被引用。

排查 ​

  1. 检查是否被同时创建了多个同名/同表达式任务；去重保留一个。

  2. 查看是否有重试机制在失败后反复重推（待核验：重试策略以官方为准）。

  3. 确认任务间是否真的需要共享上下文：定时任务通常按"每次独立会话"运行（待核验：以官方为准），把需要复用的中间结果显式写到文件/知识库，不要依赖模型记忆。

  4. 核对推送通道是否被多个订阅者同时接收（例如多个机器人/多个 webhook）。

根因 ​

  • 任务重复：同名任务被建了多份，或重试策略过宽。

  • 上下文隔离：误以为定时任务会"记住"上一轮，实际每轮是新会话。

  • 通道重复：同结果被推到多个目的地。

修复 ​

  • 根治：用幂等键（日期 + 任务 ID）作为输出文件名/消息 ID，重复推送时下游可识别丢弃；跨轮次依赖的状态写盘或写知识库，不依赖对话历史。

  • 预防：所有定时任务命名规范统一（项目_任务_频率），列表里一眼能看出重复。

排查示例 ​

text
输出文件名：<project>_<task>_<YYYYMMDD>.md
推送消息 ID：<task_id>:<YYYYMMDDHH>
# 下游收到重复 ID 直接丢弃，不重复通知

截图脚本占位清单 ​

序号页面/位置要展示的元素标注说明
S6-1定时任务列表疑似重复任务的两行记录待补：需在真实客户端按此清单截图
S6-2推送通道配置多个 webhook/订阅者列表待补：需在真实客户端按此清单截图

预防 checklist ​

* [ ] 任务命名统一规范，便于去重

* [ ] 输出/推送带幂等键

* [ ] 跨轮次状态显式落盘，不依赖对话记忆

小红书引流文案：定时任务一边重复推一边失忆？两个小动作：加幂等键 + 状态落盘，立刻清爽。

四、RAG 知识库故障合集 ​

以下为通用排查框架，非真实案例记录；具体根因请结合你的实际环境逐项验证。RAG 的分块策略、召回 top-k、重排机制等 WorkBuddy 专有配置一律待核验（以 workbuddy.cn 官方为准）。

RAG-01 · RAG 幻觉 / 答非所问 ​

现象 ​

  • 问知识库内的问题，模型给出看似合理但库里根本没有的答案；

  • 引用了文档编号/页码，但翻原文对不上；

  • 简单事实题答错，复杂题反而对。

排查 ​

  1. 先用同一问题去原始文档里全文搜索，确认"答案"在库里是否真的存在。

  2. 打开召回过程（待核验：是否有召回调试面板，以官方为准），看实际捞回来的是哪几段；常见是召回片段根本不相关。

  3. 核对分块大小：块太大 → 上下文噪声多；块太小 → 上下文断裂，模型自行补全。

  4. 降低或升高召回数量（top-k）做对比，观察答案是否随召回变化。

  5. 检查问题本身是否过长、是否混入了与知识库无关的个人背景，干扰向量召回。

根因 ​

  • 召回不准：query 和文档表述风格差异大，向量相似度低。

  • 分块不当：块大小/重叠设置不合理。

  • 提示词缺失：没有明确告诉模型"库里没有就说不知道"，模型倾向于编。

修复 ​

  • 根治：在系统提示词里硬约束"仅基于召回片段回答，未命中时明确说知识库未覆盖"；调整分块策略；对高价值文档加标题/元数据提升召回。

  • 预防：建一份"高频问题 × 期望答案"小测试集，每次改 RAG 配置跑一遍回归。

排查示例 ​

text
仅基于下面提供的【召回片段】回答用户问题。
如果召回片段中没有足够信息，必须直接回复："知识库未覆盖此问题"，禁止自行补充。
回答末尾标注引用片段编号 [1][2]。

截图脚本占位清单 ​

序号页面/位置要展示的元素标注说明
S7-1问答对话页模型幻觉答案 + 用户问题待补：需在真实客户端按此清单截图
S7-2召回片段面板（如有）实际召回的文档片段列表待补：需在真实客户端按此清单截图

预防 checklist ​

* [ ] 系统提示词硬约束"未命中即拒答"

* [ ] 建 10\-20 条高频问题回归集

* [ ] 每次改分块/召回参数后跑回归

小红书引流文案：RAG 一本正经胡说八道？在提示词里加一句"没查到就说没查到"，幻觉立刻收敛。

RAG-02 · 检索旧版本 / 文档混杂 ​

现象 ​

  • 文档已经更新，但模型还在引用上个月的旧版本；

  • 同一份问题同时返回了 A 文档和 B 文档的内容，拼在一起自相矛盾；

  • 删除过的旧文档内容仍被召回。

排查 ​

  1. 核对文档更新后是否触发了重新索引/重建（待核验：索引刷新时机以官方为准）。

  2. 检查是否把"草稿版""归档版""正式版"都扔进了同一个知识库，没有元数据区分。

  3. 确认旧文档是否真的从知识库移除，而不只是本地删了文件。

  4. 在召回查询里加元数据过滤（例如 version=latest 或 status=published）做对比。

根因 ​

  • 索引未刷新：文档更新后向量库仍是旧切片。

  • 命名/元数据混乱：多版本共存但没打标签，召回时一锅端。

  • 删除不彻底：源文件删了但向量库残留。

修复 ​

  • 根治：知识库按"正式版/草稿版"分库或加元数据；文档更新后手动触发重建索引；删除文档时同步清理向量库。

  • 预防：文件名/元数据强制带版本号和生效日期；定期巡检"孤儿切片"（源文件已删但向量仍在）。

排查示例 ​

text
文件名：<主题>_v<语义化版本>_<生效日期 YYYYMMDD>.md
元数据字段：version / status(published|draft|archived) / effective_date
召回过滤：仅召回 status=published 且 effective_date <= today

截图脚本占位清单 ​

序号页面/位置要展示的元素标注说明
S8-1知识库文件列表多版本同名文件共存待补：需在真实客户端按此清单截图
S8-2召回片段面板同时命中新旧两版本文档待补：需在真实客户端按此清单截图

预防 checklist ​

* [ ] 文档命名强制带版本号与生效日期

* [ ] 更新后手动重建索引

* [ ] 删除文档时同步清理向量库，不留孤儿切片

小红书引流文案：知识库越更新越乱？给每个文档打上版本号和生效日期，召回立刻按"最新版"说话。

五、长任务故障合集 ​

以下为通用排查框架，非真实案例记录；具体根因请结合你的实际环境逐项验证。上下文窗口大小、长任务超时阈值、断点续跑能力等 WorkBuddy 专有行为一律待核验（以 workbuddy.cn 官方为准）。

LONG-01 · 断点丢失 / 上下文截断 ​

现象 ​

  • 任务跑到一半，模型"忘了"前面已经做过的步骤，从头再做；

  • 回答在某一句戛然而止，像被剪刀剪断；

  • 处理长文档时只对开头/结尾有反应，中间内容像没看见。

排查 ​

  1. 估算本次会话累计输入长度（文档 + 历史对话 + 工具返回），判断是否接近上下文窗口上限（待核验：具体窗口大小以官方为准）。

  2. 把超长文档分段喂入，每段独立提问，对比模型回答是否恢复正常。

  3. 核对是否在同一会话里塞了太多工具返回结果（日志/JSON/表格），这些会占掉大量上下文。

  4. 观察截断位置：常在输出 token 上限处戛然而止；缩短单次输出要求重试。

根因 ​

  • 窗口溢出：累计输入超过上下文窗口，早期内容被挤出。

  • 输出截断：单次输出 token 上限触顶。

  • 中间遗忘：长文本中段信息在注意力机制下被弱化（"中间丢失"现象）。

修复 ​

  • 根治：长任务拆成"子任务 → 中间结果落盘 → 新会话继续"；把大文档切块并行处理，最后汇总；不要把所有日志都塞进对话，写文件再让模型读关键摘要。

  • 预防：长任务模板里显式要求"每完成一步把结论写到 ./progress.md"，新会话第一件事读这个文件。

排查示例 ​

text
# progress.md
## 已完成
- [x] 步骤 1：xxx，结论：xxx
## 进行中
- [ ] 步骤 2：xxx
## 下一步提示
- 从这里继续，不要重做步骤 1

截图脚本占位清单 ​

序号页面/位置要展示的元素标注说明
S9-1对话窗口回答在中途截断的画面待补：需在真实客户端按此清单截图
S9-2progress.md 文件内容断点续跑模板示例待补：需在真实客户端按此清单截图

预防 checklist ​

* [ ] 长任务强制每步落盘 progress\.md

* [ ] 大文档切块并行，不一次性塞全文

* [ ] 工具日志写文件，对话里只留摘要

小红书引流文案：长任务跑一半模型就失忆？给它一个 progress.md，断点续跑比从头再来快 10 倍。

LONG-02 · 长任务中途中断 ​

现象 ​

  • 任务跑了几分钟后主动停止，没有任何报错；

  • 浏览器/客户端切换到后台后任务被挂起；

  • 工具调用在某个外部请求上一直挂着，直到整体超时。

排查 ​

  1. 核对是否触发了单次任务的最长执行时长（待核验：以官方为准）。

  2. 查看是不是某个 MCP/外部接口在等待响应，把整条链路拖死；单独测该接口。

  3. 确认客户端是否在后台被系统休眠（待核验：长任务是否依赖前台，以官方为准）。

  4. 检查是否有不可恢复的异常被静默吞掉（脚本里 try/except 空着）。

根因 ​

  • 超时：任务整体或某步调用触顶。

  • 外部依赖挂起：MCP/HTTP 请求没设超时。

  • 异常被吞：脚本静默 catch，看起来像"正常停止"。

修复 ​

  • 根治：所有外部请求显式设置超时（连接 5s、读取 30s）；脚本里 catch 后必须打印日志并重抛或落盘错误；长任务拆成可恢复的子段。

  • 预防：在任务入口加心跳（每 N 秒写一次 heartbeat.txt），无心跳则人工介入。

排查示例 ​

python
import requests
try:
    r = requests.get(url, timeout=(5, 30))
    r.raise_for_status()
except requests.Timeout:
    log.write("TIMEOUT at " + url)
    raise
except Exception as e:
    log.write(f"ERROR {type(e).__name__}: {e}")
    raise

截图脚本占位清单 ​

序号页面/位置要展示的元素标注说明
S10-1对话窗口任务静默停止、无报错的画面待补：需在真实客户端按此清单截图
S10-2日志文件被吞掉的异常或最后一次心跳待补：需在真实客户端按此清单截图

预防 checklist ​

* [ ] 所有外部请求显式设超时

* [ ] 脚本 catch 后必须打印日志，禁止空 except

* [ ] 长任务写心跳文件

小红书引流文案：任务跑到一半"悄无声息就死了"？加个超时 + 心跳，下次它死了你至少知道死在哪一步。

六、成本失控合集 ​

以下为通用排查框架，非真实案例记录；具体根因请结合你的实际环境逐项验证。计费口径、积分规则、速率限制等 WorkBuddy 专有数据一律待核验（以 workbuddy.cn 官方为准），本条目不引用任何具体官方数字。

COST-01 · 循环调用 / 无上限重试导致积分爆掉 ​

现象 ​

  • 一个看起来很普通的任务，消耗了远超预期的积分/额度；

  • 模型在两个工具之间来回调用，陷入死循环；

  • 失败后自动重试，重试次数没有上限，越错越烧钱。

排查 ​

  1. 查看本次任务的调用记录/用量明细（待核验：入口以官方为准），定位是哪一类调用在暴涨。

  2. 回放对话，确认是否出现"A 调 B、B 又调 A"的循环模式。

  3. 检查 Skill/脚本里的重试逻辑：是否写了 while true: try ... except: continue 这种无上限循环。

  4. 核对是否在循环里每次都重新加载大文档/重新跑长 RAG，导致 token 倍增。

  5. 对比同类型任务的历史用量，判断是这次异常还是长期偏高。

根因 ​

  • 调用循环：工具之间互相触发，模型没有跳出。

  • 重试无界：失败后无限重试，或重试间隔指数退避没设上限。

  • 重复加载：循环体内重复喂大上下文。

修复 ​

  • 根治：所有重试加最大次数（建议 3 次）和总预算上限；循环体内把大文档/大结果缓存到文件，不要每轮重读；在系统提示词里显式约束"同一动作连续失败 3 次必须停下来向用户报告"。

  • 预防：每周看一眼用量曲线，异常峰值当天复盘；高成本操作（长文档、多轮 RAG）前先做小样测试。

排查示例 ​

python
MAX_RETRIES = 3
for attempt in range(1, MAX_RETRIES + 1):
    try:
        return call_external()
    except Exception as e:
        log.write(f"attempt {attempt} failed: {e}")
        if attempt == MAX_RETRIES:
            raise RuntimeError("达到最大重试次数，停止") from e

截图脚本占位清单 ​

序号页面/位置要展示的元素标注说明
S11-1用量/积分页面异常峰值时段的消耗曲线待补：需在真实客户端按此清单截图
S11-2对话回放工具互相循环调用的连续记录待补：需在真实客户端按此清单截图

预防 checklist ​

* [ ] 所有重试逻辑写死 MAX\_RETRIES

* [ ] 循环体内大文档/大结果缓存到文件

* [ ] 每周巡检用量曲线，异常当天复盘

* [ ] 高成本操作先跑小样验证

小红书引流文案：积分一夜被烧光？十有八九是脚本里写了"失败就一直重试"——加个 3 次上限立刻止血。

七、缓存与本地文件异常合集 ​

以下为通用排查框架，非真实案例记录；具体根因请结合你的实际环境逐项验证。缓存目录路径、缓存策略、文件锁机制等 WorkBuddy 专有行为一律待核验（以 workbuddy.cn 官方为准）。

CACHE-01 · 缓存膨胀 / 文件读写冲突 ​

现象 ​

  • 磁盘可用空间持续下降，定位到 WorkBuddy 相关缓存目录占了大头（待核验：路径以官方为准）；

  • 两个 Skill/两次任务同时写同一个文件，输出内容互相覆盖或出现半截文件；

  • 明明改了源文件，模型读到的还是旧内容。

排查 ​

  1. 用磁盘占用工具（系统自带或 du）定位大目录，区分是缓存、日志还是真实产物。

  2. 核对缓存目录是否有自动清理策略；如果没有，加一个按时间（例如 7 天）的清理脚本。

  3. 检查是否有多个任务/会话同时写同一个输出文件；常见于定时任务重试 + 手动触发同时跑。

  4. 文件写入是否走"先写临时文件再 rename"的原子方式；直接覆盖写容易留下半截文件。

  5. 核对模型读文件时是否走了 RAG/向量缓存，源文件改了但索引没刷新，导致读到旧切片（见 RAG-02）。

根因 ​

  • 缓存不清理：历史会话、上传文件、临时产物长期堆积。

  • 并发写冲突：多进程写同一文件，无锁无原子写。

  • 读缓存不一致：源文件改了但上层缓存/索引没失效。

修复 ​

  • 根治：加定时清理任务（按 mtime 清理 N 天前的缓存）；所有产物写入走"临时文件 + rename"原子模式；并发写同一文件时加锁或按任务 ID 分文件。

  • 预防：把"缓存目录大小"加进每周巡检；文件命名带任务 ID + 时间戳，从根本上避免冲突。

排查示例 ​

python
import os, tempfile
def atomic_write(path, content):
    dir_ = os.path.dirname(path)
    fd, tmp = tempfile.mkstemp(dir=dir_, suffix=".tmp")
    with os.fdopen(fd, "w", encoding="utf-8") as f:
        f.write(content)
    os.replace(tmp, path)  # 原子替换，不留半截文件

截图脚本占位清单 ​

序号页面/位置要展示的元素标注说明
S12-1磁盘占用工具缓存目录体积占比待补：需在真实客户端按此清单截图
S12-2文件目录两个任务同时写同一文件产生的冲突现场待补：需在真实客户端按此清单截图

预防 checklist ​

* [ ] 每周巡检缓存目录大小，超阈值触发清理

* [ ] 所有产物写入走临时文件 \+ rename 原子模式

* [ ] 输出文件名带任务 ID \+ 时间戳，避免并发覆盖

* [ ] 源文件更新后同步失效上层缓存/索引

小红书引流文案：磁盘越用越满、改了文件模型还读旧的？一次清理 + 原子写入，两个毛病一起治。

附：本库使用与更新说明 ​

  • 本库所有条目均为通用排查框架，不代表任何真实故障案例；真实案例实录将在运营中逐步补充，并在条目末尾标注来源与复现环境。

  • 涉及 WorkBuddy 专有行为的描述（定时任务机制、缓存路径、上下文窗口、计费口径等）统一标注「待核验（以 workbuddy.cn 官方为准）」，使用前请对照官方最新文档。

  • 本库不收录交易策略、自媒体批量脚本等敏感内容；所有密钥、Token 在示例中均以占位符呈现，禁止明文存储。

  • 关联文档：版本兼容对照表、资产验收测试标准、最小可用配套资产包、FAQ/全站固定文案，见知识营地文件夹同目录下的兄弟文档。

（注：部分内容由豆包工作 AI 生成）

把 WorkBuddy 用明白——入门 · Skill · MCP · 工程案例 · 故障排除

© 2026 WorkBuddy 知识营地 · workedclub.com