---

你的 AI 编程助手跑了一个下午，产出两行代码。

它说「抱歉，这个拖得有点久」。

你不知道那两小时去哪了。你不知道是它慢，还是你在想。

Agent Crop 就是来回答这个问题的。

---

从传统性能优化到 Agent 工作范式优化

后端做性能优化靠 Trace：一次请求一条，找到最贵的那一段，改完再用同一个指标测一遍。 这套东西在大厂跑了二十年，撑过双十一，也撑过每一次线上事故复盘。

职场里也有同一套结构，叫复盘：做了什么、时间花在哪、下次怎么改。

Agent Crop 只是把对象换成了「人和 AI 一起干活」：

上图是一次请求的 span，下图是一次工作的时间去向。四步不变：测量、归因、优化、验证。

---

马鞭做什么

• 防跑偏、防摸鱼。 Agent 长时间没回话、没给出结论的时候，鞭策它想一想：是不是走错了路。
• 即刻反思。 被鞭策之后，要求它在当下的环境里找一找，还有没有能挽回的时间和方法。
• 复盘，自驱优化。 通过周报、月报做自我反思，自己沉淀方法论。

三件事凑齐才叫自驱，不然只是被催。

---

案例分析

我们有个环境部署工具，子命令很多。AI 每次用都得先 help 一层层翻，再挨个试——对应的 Skill 写得不完整。

Agent Crop 把这件事记了下来：同一个命令反复翻 help、反复试错，归到 tool-misuse 这一类。

这条记录被推回给 AI，让它即刻反思——不是模型不会用，是这个 Skill 缺了最关键的一页。它据此补了一份常用 Skill。

同一个动作，下一次：10 分钟，变成 30 秒。

这是我个人使用中的一个成果，它确实帮到了我。但它还不是一个完善的测评——这个工具还在开发中，请大家多多包容。不过我相信，这样一套方法论是行之有效的。

同样的症状还有：没问清楚就开始干（spec-drift）、做不到也不停手（no-evidence）、串行等待（serial-wait）。一共九类，见 docs/EVENTS.md。

---

Crop 是如何工作的

一次工作里，它只在几个点上出手。

flowchart LR
    A[你发消息] --> B[开始计时]
    B --> C[AI 干活]
    C -->|每次工具调用| D[记一笔]
    C --> E{超过红线?}
    E -->|是| F[注入一行提醒]
    F --> G[AI 即刻反思]
    G --> C
    E -->|否| H[回合结束]
    H --> I[记时长 / 失败 / 返工]
    I --> J[收工: 三句小结]
    J --> K[周报 / 月报]
    K --> C

那条回到「AI 干活」的环，就是马鞭：提醒 → 反思 → 改工作方式 → 再干。

---

安装与卸载

git clone https://github.com/oriliz/agent-crop.git ~/agent-crop
dsh plugin --profile <你的 profile> add ~/agent-crop
# 重启 dsh，新会话生效

装完不用改配置、不用动 AGENTS.md——协议通过插件注册进系统提示，卸载时自动移除。

Claude Code 的装法见 docs/INSTALL.md。

自检：

crop status                              # 最后一行会打印真实数据目录
tail -1 ~/.agentcrop/data/events.jsonl   # 应出现 "host":"dsh"

数据目录的历史名是 ~/.ai-coding-efficiency，新版叫 ~/.agentcrop。如果你的机器上还没有后者，crop status 最后一行打印的才是真实路径；想统一名字就 ln -s ~/.ai-coding-efficiency ~/.agentcrop，或用 KIT_SHARED_HOME 覆盖。

crop 是仓库里的脚本，先放进 PATH：

ln -sf ~/agent-crop/bin/crop /usr/local/bin/crop

卸载：

dsh plugin --profile <你的 profile> remove agent-crop-dsh
# Claude: claude plugin uninstall ai-coding-efficiency-kit

卸载不动数据。要一起清掉：rm -rf ~/.agentcrop

---

它记了什么、在哪记

宿主自动记

什么时候	记什么
会话开始 / 你发消息	工作区、任务块起点
每次工具返回	工具名、成功还是失败
回合结束	这一轮跑了多久
你下一次开口	等了你多久；超阈值记 idle_gap
超红线	提醒注入了一次
同工具 / 文件反复失败	返工信号

AI 主动报

字段	什么时候填	可能的值
phase	每次上报	start 开工 / progress 有进展 / blocked 卡住 / end 收工
task_id	每次上报	你给这件事起的短名，比如 refactor-auth
summary	每次上报	一句话：现在在做什么
cause	blocked 必填	一句话：为什么慢、卡在哪
next	可选	下一步的具体动作
category	blocked 必填	九选一：serial-wait repeat-pitfall design-churn decision-batching tool-misuse no-evidence spec-drift human-wait other
goal	开工时	一句话目标
type	开工时	design / implement / debug / docs
difficulty	开工时	s / m / l

category 是枚举，不是自由文本——填错直接失败。九类词表锁死，不会越记越乱。

这些只是判断，不是事实：自述永远不单独当结论，要和自动采集的时间、失败数对照着看。

数据只落本机 ~/.agentcrop/data（权限 0700），可用 KIT_DATA_DIR 覆盖。不存对话正文。

---

成本

只多花一点 Token，对速度几乎无感。

• 每回合多一行：注入 100–300 字符；卡住时 AI 上报一次，约 50–100 token。
• 不重读对话：总结基于结构化事件，不会把整段会话再塞回模型。
• 不拖时间：注入一行、上报一句，都是毫秒级。

一个 20 回合的工作，合计约 2k token。对比事后去会话里反查——一条中等会话就是几万 token，长的几十万，根本塞不进上下文。

---

它不做什么

• 不打分。 没有效率分，没有排行榜。
• 不上传。 数据只在这台机器上。
• 不改你的代码。 只观察；方案也只影响提示。
• 不替代 APM。 工具内部性能仍归 OpenTelemetry。
• 不给你老板看。 没有云，没有团队看板。

这是镜子，不是裁判。

---

文档

• docs/DESIGN.md — 设计原则与边界
• docs/EVENTS.md — 采哪些事件、怎么存、谁在用
• docs/SESSION-WORK.md — 会话与工作怎么绑定、怎么解绑、失效了怎么办
• docs/INSTALL.md — 四个宿主的安装与卸载
• docs/LONGEVITY.md — 长任务里怎么不被上下文冲刷掉

License

MIT — 随便用，随便改。

---