Appearance
01 · 如何做一个工具
从一个卡死两小时的下午开始，经历 16 轮迭代、四路专家审查，最终长出一套可给任何 WorkBuddy 做配置体检的自动化工具。
💡 核心方法论：「从问题到工具」4 步法
做工具的难点不是写代码，是把「修好一个问题」变成「让这类问题永远不会再发生」。以下是可复用的步骤：
| 步骤 | 做什么 | 关键动作 |
|---|---|---|
| ① 看根因 | 不猜，直接读日志/数据，找到真正原因 | 看原始输出，不靠推测 |
| ② 修问题 | 把眼前的问题解决 | 配置修复、流程调整 |
| ③ 建标准 | 描述「好的状态应该是什么样的」 | 写检查规则，把标准显式化 |
| ④ 做工具 | 让 AI 按标准定期检查，自动产出报告 | 用 Skill 把检查机器化 |
普通人走到 ② 就停了。走到 ③④ 就是把一次性修复升维成系统性能力——也就是这篇案例在教的事。
🔴 起点：那个卡死的下午 [步骤①：看根因]
时间： 2026 年 5 月 12 日 上午 9:42
桔子打开 WorkBuddy，发了一条指令。屏幕上出现：「正在思考… 正在压缩上下文…」。等了 10 分钟没动，半小时没动，两小时后仍无任何响应。
第一反应是猜：配置问题？模型抽风？网络故障？——三个猜测都是错的。
诊断：直接读日志
WorkBuddy 的运行日志揭示了死循环的全貌：
09:42:26 正在压缩上下文... tokens=100202/100000 ← 超限，触发压缩
09:43:45 压缩完成。tokens=100202/100000 ← 压缩后完全没变
09:43:45 正在压缩上下文... tokens=100202/100000 ← 立刻再次触发
...（无限循环）压缩前 100202，压缩后还是 100202。零变化。
根因：models.json 缺少 maxInputTokens 配置 → WorkBuddy 用默认 100K 阈值 → 系统固定开销（65-80K）已接近阈值 → 每次压缩都无效 → 死循环。
展开看完整根因分析
WorkBuddy 每次对话自动加载系统文件（SOUL.md + AGENTS.md + USER.md + 工具定义 + 规则框架），固定开销约 65-80K token。压缩机制只动对话历史，不动系统配置。修之前：固定开销 70K + 对话历史 30K = 100K → 触发压缩 → 压完还是 75K → 再触 —— 永远逃不出去。
⚡ 修复：两件事，15 分钟 [步骤②：修问题]
| 修复项 | 做了什么 |
|---|---|
补 maxInputTokens | 给 4 个模型设真实上限的 60% |
| 配置瘦身 | 32KB → 13KB，详细规范移到按需加载的参考文件 |
修完，死循环解除。
💡 转折：从「修好」到「永远别再出」 [步骤③：建标准]
「能不能有一个工具，提前发现这类问题——不是等出了事才知道？」
这一问催生了 workbuddy-auditor。
核心思维跃迁
普通路径： 出问题 → 找原因 → 修好 → 继续
更高效的路径： 出问题 → 找原因 → 修好 → 建立机制，让这类问题消失
🛠️ 工具设计：三轮关键决策 [步骤④：做工具]
第一轮：用学术框架定义「好配置」
不靠感觉，先调研。检索了现有评估方法论后选定：
| 框架 | 角色 |
|---|---|
| 五维约束检测（SlsDetector） | 主引擎：5 类约束逐项推理找违规 |
| 信息效率比（Shannon 信息论） | 总览指标：有用信息 ÷ 总 token |
| 影响链路分析（Pearl 因果推断） | 解释层：追踪配置 → 行为 → 结果 |
第二轮：6 种方案并排比较
不让 AI 出一个方案，而是用强制差异化指令生成 6 种完全不同的方案，在 HTML 网格中并排比较，每个标注取舍。
第三轮：四路专家轮番拆解
通过 WorkBuddy 专家模式邀请四种视角审查：
| 专家 | 关键发现 | 改动 |
|---|---|---|
| 工具评估 | 维度数写错、计数遗漏 | 全部修复 |
| 数据分析 | 10 个同类小问题会「吃掉」其他权重 | 按类型独立递减算法 |
| 性能测试 | Flash 模型不确定时乱给分数（仅 61%） | 引入三态判定：✅/❌/⚠️可疑 |
| 安全 | API Key 可能随报告泄露（8 项风险） | 脱敏机制 + 修复白名单 + diff 预览确认 |
用达尔文技能优化器做独立评分。三轮单维优化：84.8 → 85.5 → 87.3 → 88.5。
📊 最终产物
一份暗色主题 HTML 报告：46 项指标、7 个维度、P0/P1/P2 三级违规、可操作建议清单。最关键的检查项 V1（maxInputTokens）——就是当初导致死循环的那个缺口。
📋 自查清单：什么时候值得把问题做成工具？
满足以下 3 条就该 Skill 化：
| 条件 | 说明 |
|---|---|
| ① 会反复发生 | 同一类坑踩第二次就该做了，第三次是浪费 |
| ② 有明确的「对/不对」 | 能写成检查规则，不靠感觉判断 |
| ③ 多步骤、容易遗漏 | 三步以内靠记性，五步以上靠工具 |
更好的工具设计原则：
- 自包含：换个人用也能得到同样结果
- 按需加载：主文件放常用规则，附属文件放详细参考
- 三态判定：不只对/错，加入「可疑（人工核查）」
- 不可逆操作先预览：修改前 diff，逐条确认，自动备份
🔗 相关工具
- WorkBuddy Auditor — 本案例的最终产物
- 案例 02 · 如何探索方向 — 本案例用到的「6 种方案并排比较」方法详解
案例来源：CASE-001 + CASE-002 | 2026-05-12