SuperAPI AI 工具集

investigate

编程与开发

查看项目

更新于 11-06 10:09

技能介绍

investigate 是一个面向代码流调查的技能,来源于 duc01226/easy-claude。其核心目标是:在只读、有证据支撑的前提下,解释现有代码从触发点到退出点的行为,使每项发现都能映射到 file:line(或标记为“inferred”),并让后续决策建立在证据之上,而不改动源码。

用途与模式

  • 默认模式:执行只读代码流调查,梳理实体、命令/查询、事件处理器、控制器、消费者、组件等,追踪入口到出口的流程,分析业务规则、校验、授权、错误处理和边界情况。
  • --mode=debug:针对缺陷的根因调查。调用时需先完整阅读 references/mode-debug.md,执行复现、假设、端到端追踪、确认、$why-review 验证和报告等步骤,仅做调查,修复由 $fix 执行。
  • --mode=explain:以“目的 → 如何实现 → 为什么 → 影响”的单向开发者叙述形式输出,并写入被 git 忽略的账本文件;同样保持只读和证据要求。

主要能力

  • 先分类范围(quick / deep / debug / recommendation / explain),再按深度执行调查。quick 范围可跳过分析文件;deep 范围需要写入 tmp/analysis/[feature]-investigation.md 并回读;explain 范围使用开发者叙述和账本。
  • 按优先级发现相关文件:实体 > 命令/查询 > 事件处理器 > 控制器 > 消费者 > 组件。
  • 可选使用代码图(.code-graph/graph.db)提示调用方、依赖方和受影响测试,但代码图可能过期或不完整,必须通过阅读文件进行核实,且不是必需步骤。
  • 读取并记录每个文件的目的、符号、依赖和数据流,批量处理并更新进度。
  • 映射入口到出口的流程,记录转换、持久化、副作用和跨服务边界。
  • 提取业务规则、验证、授权、错误处理、正常路径和边界情况。
  • 在推荐范围下,执行强制验证链协议;跨服务范围需扫描生产者、消费者、saga 和契约。
  • 所有发现需要 file:line 证据,未验证内容标记为“inferred”;调查严格只读,不修改代码、计划或规范。

使用方式 通过显式调用技能名称触发,或在用户要求只读代码流调查时使用。调用参数可指定模式,例如 $investigate --mode=debug <bug> 或 --mode=explain [target]。执行时按阶段顺序进行,阶段开始前更新待办跟踪,完成后记录证据;若任务工具不可用,需维护等效跟踪器。跨工具名称需映射到宿主能力,实际不可用的必需能力应停止并询问用户。

适用场景

  • 理解某个功能从入口到退出的完整行为。
  • 定位业务逻辑所在位置及其副作用。
  • 调查缺陷根因(debug 模式)。
  • 为重构、移除等代码变更建议提供验证依据。
  • 需要跨服务或事件驱动路径分析时。

限制

  • 调查严格只读,不产生代码补丁、计划或规范变更。
  • 代码图仅为可选提示,可能过期或不完整,不能作为证据。
  • 每项主张都需要 file:line 证据,未验证内容只能标记为“inferred”。
  • 推荐范围必须完成完整验证链和置信度判断。
  • 关于收费、价格、平台支持等信息,资料未提供。