给 AI 准备代码索引怎么做？提取函数签名位置与类名，避免整库粘贴

把整个仓库粘贴给 AI 会引入无关材料，也难核对回答所指位置。先生成函数、异步函数和类的符号清单，再按任务选取源码片段，能让上下文更容易定位。

准备向AI提供相关代码片段的开发者。本文使用 Python 3.11 或以上版本的标准库，先验证一组人工构造的小样本。AI 负责提出实现或解释差异，结果由本地检查决定；这里没有把模型回答当成真实运行结果。

建立可定位的代码符号索引前，先定规则

符号索引不是检索模型，也不证明AI已经理解代码。它只把名称与源码范围关联起来，支持人工选择。

同名方法可能出现在不同类里，因此正式索引要保留层级。本例记录简单的父节点路径，避免把不同作用域同名函数合并。

end_lineno可帮助提取完整定义；装饰器行可能在def之前，如果任务涉及装饰器行为，提取范围要另外向前扩展。

给 AI 的输入要包含什么

把下面这份输入说明和你的实际样本一起交给可用的 AI 编程助手。示例只含虚构数据；对真实材料先去除账号凭据和个人信息。

创建标准库AST符号索引，记录kind、qualified_name、start、end；类方法保留类名，异步函数单独标注。不能执行源码。输出给AI后按名称选片段，排除密钥和无关目录。

要求模型保留检查条件，并把它认为缺少的业务定义列出来。若回答改变了输入字段、忽略异常分支或直接删除原材料，先要求修正，再运行。提示词的作用是缩小任务范围，验收仍以代码和数据为准。

保存并运行最小验证程序

下方程序把关键规则和验证用例放在同一个可复跑示例中，便于先理解输入如何变成输出，再用它检查 AI 给出的实现。

新建一个空目录，把下面代码保存为 check.py，在该目录打开终端，运行 python -X utf8 check.py。代码自带示例输入，不需要安装第三方库。

import ast
source="""class Store:
    def get(self, key):
        return key
async def fetch():
    return 1
"""
tree=ast.parse(source)
symbols=[]
def walk(node,parents=()):
    for child in ast.iter_child_nodes(node):
        is_symbol=isinstance(child,(ast.FunctionDef,ast.AsyncFunctionDef,ast.ClassDef))
        scope=parents
        if is_symbol:
            scope=parents+(child.name,)
            symbols.append({'kind':type(child).__name__,'name':'.'.join(scope),'start':child.lineno,'end':child.end_lineno})
        walk(child,scope)
walk(tree)
assert [x['name'] for x in symbols]==['Store','Store.get','fetch']
assert symbols[-1]['kind']=='AsyncFunctionDef'
print(symbols)

怎样判断结果符合要求

清单应有Store、Store.get与fetch三个符号，fetch标为AsyncFunctionDef。检查start/end是否与提供的五行源码对应。

下方是这份最小示例在本地执行得到的输出。它验证示例程序与断言的关系，不代表任何 AI 模型一次就能生成同样代码，也不构成性能或生产可靠性结论。

[{'kind': 'ClassDef', 'name': 'Store', 'start': 1, 'end': 3}, {'kind': 'FunctionDef', 'name': 'Store.get', 'start': 2, 'end': 3}, {'kind': 'AsyncFunctionDef', 'name': 'fetch', 'start': 4, 'end': 5}]

类范围包含其方法范围属于正常嵌套，并不意味着重复记录需要删掉。

让AI回答时引用完整符号名与原文件位置，避免“get函数”这样的模糊指向。

哪些失败必须停下来处理

语法错误文件要列入失败清单，不能静默从索引消失。

代码索引可能暴露内部结构，即使不含源码也应按项目授权范围分享；生成后仍需排除敏感目录。

接入自己的任务前再核对一次

实际索引增加repo相对路径、文件哈希和语言，缓存只在哈希一致时复用。

任务需要动态注册表或配置时，把相关配置作为单独来源，不能把AST符号清单当完整调用真值。

资料与适用范围

FunctionDef、AsyncFunctionDef、ClassDef节点记录名字、lineno与end_lineno。以下链接核对于 2026-10-03；运行环境及额外依赖按本文前述说明。

• https://docs.python.org/3.11/library/ast.html

相关基础可阅读 Cursor 代码库索引会索引什么？查看状态、排除文件并验证上下文。本文的重点是建立可定位的代码符号索引，可以把两项检查作为不同步骤保留。