[OSS26] 类名定位文件 locate_class_file_by_class_name

[ponyha]

接口介绍

给定类的全限定名(支持普通类、内部类、嵌套类),在指定仓库内精准定位其源码文件路径与定义行号;找不到时给出近似候选列表。

工具名

locate_class_file_by_class_name

背景与目标

LLM Agent 拿到一个类全名后,常常需要立刻读源码。如果走关键词搜,容易被同名内部类、同名变量干扰。提供一个精确的"类名 → 文件路径"映射是必要的基础设施,支持 Java(后续可扩展)。

输入参数

参数	类型	必填	说明
class_full_name	string	是	类全限定名,如 com.example.UserController;对内部类用 Outer$Inner 或 Outer.Inner 都接受
repository_path	string	是	仓库本地绝对路径
include_inner_classes	bool	否	默认 true,是否在内部类匹配时一并返回外层文件

输出结构

{
  "class_full_name": "com.example.UserController",
  "found": true,
  "file_path": "src/main/java/com/example/UserController.java",
  "line_number": 14,
  "kind": "class",
  "is_inner_class": false,
  "outer_class_full_name": null
}

未找到时:

{
  "class_full_name": "com.example.NotExist",
  "found": false,
  "candidates": [
    "com.example.sub.NotExist",
    "com.example.NotExistImpl"
  ]
}

验收标准

• 内部类正确返回外层文件 + line_number 指向内部类定义行
• 同名跨包类不混淆(以 package + import 验证)
• 找不到时给出近似候选(可选,加分项)
• 单元测试覆盖:嵌套类、匿名内部类、package-info.java
• 中等仓库响应 < 2s

预估工作量

2-3 人日