用途
paper-cuts 用于处理任务之外的“摩擦”:在完成任务的过程中遇到、但不属于任务本身的阻碍或异常。用户决定每个摩擦如何处理,使用者的职责是发现、稍作查证并报告。
三类摩擦
- Library:所使用的依赖、框架、CLI 或服务(包括用户自己的库)中存在 bug、缺少功能、API 别扭、文档错误或错误信息无帮助。
- Machine:机器行为不符合预期,例如缺少二进制文件、版本错误、权限问题、磁盘已满、进程被杀、端口占用、配置过期。
- Blocked:想做但无法完成的事情,例如工具调用被拒、缺少凭据或集成、主机不可达、沙箱限制。
遇到摩擦时,尽可能绕过,记录后继续任务;修复、提 issue 或改配置都等待用户决定。
查证程度
每个摩擦只需做几次查询,足以填写卡片即可:
- Library:从 lockfile 获取已安装版本,搜索上游 issue,查看该版本之后的 changelog 或 release。
- Machine:记录命令及输出、可能原因,以及机器笔记是否已有覆盖。
- Blocked:记录具体错误或拒绝信息,以及解除阻塞所需的条件(权限、集成、机器变更)。
当能说明该问题是否已知、以及你建议如何处理时就停止;更深的研究等用户要求后再做。
报告格式
在每轮最终回复的任务报告之后,以 Paper cuts 段落结尾。每个摩擦每次会话只报告一次,即使再次遇到;没有则不输出该段落。
格式:
Paper cuts
1. <library@version 或 machine>:<一行描述发生了什么>
- Seen:<命令、错误或行为,适用时注明 file:line>
- Found:<查证结果,附链接:未关闭的 issue、已在 vX 修复、上游无记录>
- Proposal:<可采取的措施:提交上游 issue 或 PR、变通方案、机器变更、记入机器文档的笔记>
用户回复编号及处理方式:继续研究、提交 issue、修复或放弃。
用户决定后
- 继续研究:使用 research 技能,将答案作为更新后的卡片带回。
- 提交 issue:在上游仓库撰写 issue,包含版本、最小复现和相关部门 issue 链接;提交后回复链接。
- 修复:库方面按用户要求提供 patch 或 PR;机器方面执行变更,并将持久事实记录到机器笔记中。
适用场景与限制
适用于开发、调试和运维过程中系统化收集被忽略的阻碍性问题,避免反复遭遇同类摩擦。该技能不自动修复问题,不替用户做决定;具体修复方式、上游 issue 是否受理等取决于外部项目。