SuperAPI AI 工具集

create-research

编程与开发

查看项目

更新于 10-31 07:41

技能介绍

用途

create-research 是一项面向代码库调研的技能,用来回答用户关于某个代码库的具体问题。它的核心定位是:只记录和解释代码库“今天”的真实状态,形成一份技术地图或文档,而不是给出改进方案。

触发与前置步骤

该技能只在用户按名称明确调用时使用。调用后,首先检查系统提示中给出的任务制品目录,用 ls -La(目录可能是符号链接,不使用普通 ls 或 grep/glob 工具)查找 *research-questions*.md 之类文档。

  • 找到一份:读取并以其中内容作为研究问题。
  • 找到多份:先询问用户选择哪一份,再进行读取。
  • 不知道任务制品目录:回答“已准备好调研代码库,请提供研究问题或关注领域”,然后等待用户提问。

禁止读取 artifact 目录中不符合 research-questions 命名的其他文件(如 ticket.md/task.md),除非用户明确要求。

主要能力与工作方式

  1. 先完整读取用户直接提到的文件(文档、JSON、研究问题),使用 Read 工具且不设 limit/offset。
  2. 分析并拆分研究问题,识别相关组件、模式、目录与架构关系,形成研究计划。
  3. 派发并行子智能体,只使用规定的专用研究代理:
    • codebase-locator:定位文件与组件所在位置;
    • codebase-analyzer:理解具体代码如何运作;
    • codebase-pattern-finder:寻找现有模式示例;
    • web-search-researcher:检索外部文档与资源;
    • 若存在 humanlayer library researcher 工具,可用于依赖与库的调研。 代理名称因运行时不同而不同(如带命名空间的 rpi:codebase-analyzer 或不带前缀的 codebase-analyzer)。应合并相关问题,一般使用 2–6 个范围明确的子代理,而非每个问题一个代理;先用定位代理,再对关键发现用分析代理深入。使用网络调研代理时要求其返回链接,并在最终报告中保留这些链接。
  4. 等待全部子代理完成,汇总结果,以代码库实际发现为准,交叉连接各组件,附上文件路径与行号,标注数据流、调用栈、类型签名、伪代码、文件树、组件树等可视化结构。
  5. 生成研究文档:路径为 .humanlayer/tasks/TASKNAME/NN-research-DESCRIPTION.md,NN 为零填充的时间顺序编号(先 ls 找出已有最大编号后递增),DESCRIPTION 为 2–4 个单词的 kebab-case 短语;带工单时如 .humanlayer/tasks/ENG-1478-parent-child-tracking/02-research-parent-child-tracking.md,不带工单时如 .humanlayer/tasks/authentication-flow/02-research-auth-flow.md。模板读取自 {SKILLBASE}/references/research_template.md。
  6. 文档写完后如有未解决问题,可再派发一轮针对性调研并就地更新文档(最多一轮),仍无法解决则保留为未解决问题,并在最终答复中列出。
  7. 按 {SKILLBASE}/references/research_final_answer.md 模板回复用户;写入 .humanlayer/tasks/ 的文档会自动获得云永久链接(形如 http(s)://{DOMAIN}/artifacts/{artifactId}),应包含在最终输出中。若在 humanlayer 仓库主分支或已推送,可用 gh repo view --json owner,name 获取仓库信息并构造 https://github.com/{owner}/{repo}/blob/{commit}/{file}#L{line} 形式的引用链接。
  8. 处理后续追问时,按需再派发子代理,并就地更新既有文档,而非在末尾追加。

文档风格

研究文档应像一篇有意识写给他人看的技术解析:以带结论的标题组织(如“会话在守护进程确认写入前持久化到 Postgres”),而不是主题标签或问题复述;段落简短,表格、Mermaid 图、调用栈树、文件树、组件树、类型签名、伪代码与说明文字紧密相邻;引用融入叙述,先讲概念再给位置,相邻行用范围引用;代码引用部分要全面,可包含目录,并标明是否穷尽。每个发现小节需说明该组件当前的测试情况(测试文件位置、单元/集成/e2e 方式、mock 模式、fixtures),无测试也要明确写出。

限制

  • 不提出改进或变更建议、不做根因分析、不提议未来增强、不批评实现或指出问题、不建议重构/优化/架构调整,除非用户明确要求。
  • 不读取工单类文件,以保持研究对现状的客观性。
  • 只使用列出的专用研究代理,不使用 general-purpose、Explore、Plan 等其他代理。
  • 文档中的 markdown 嵌套代码块使用四个反引号作为外层围栏。

适用场景

需要理解某个代码库的既有实现、组件关系、数据流或架构现状,并希望得到一份可阅读、可追溯、含测试情况说明的技术文档时使用。