SuperAPI AI 工具集

paper-cuts

编程与开发

查看项目

更新于 11-16 15:48

技能介绍

用途

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 是否受理等取决于外部项目。