要从 Python 调用 Claude Context 的 TypeScript 语义搜索核心，需借助 TypeScriptExecutor 桥接工具。它通过动态生成临时 TypeScript 脚本、利用 npx ts-node 执行并捕获 JSON 输出，将 Python 参数无缝传递给 TypeScript 的 testContextEndToEnd 函数，从而驱动完整的嵌入、向量数据库连接、代码索引与语义搜索流程。本文将一步步引导你完成环境搭建、原理理解与实际调用。

Claude Context Python 桥接教程：从 Python 调用 TypeScript 语义搜索

Claude Context 的核心引擎是用 TypeScript 编写的，主要通过 MCP 插件服务于 Claude Code 等 AI 编程助手。如果你有一个 Python 项目，希望集成其强大的语义代码搜索能力，项目提供的 Python 桥接工具就是解决方案。本文将详细讲解其工作原理，并手把手指导你完成一次完整的端到端调用。

准备工作：环境配置与依赖安装

在开始之前，你需要确保本地环境满足以下条件：

Node.js 与 pnpm：Claude Context 的 TypeScript 代码依赖 Node.js 生态。请确保已安装 Node.js 和 pnpm。
安装项目依赖：进入项目根目录，运行 pnpm install 以安装包括 @zilliz/claude-context-core 在内的所有必要依赖。
设置环境变量：语义搜索需要向量嵌入服务和向量数据库。
- OPENAI_API_KEY：你的 OpenAI API 密钥，用于生成代码嵌入。关于其他嵌入提供商的配置，可参考Claude Context 嵌入提供商对比。
- MILVUS_ADDRESS：Milvus 向量数据库的地址，默认为 localhost:19530。更多数据库配置细节见Claude Context 向量数据库实现。

你可以在终端中使用以下命令设置环境变量（以 Linux/macOS 为例）：

export OPENAI_API_KEY="your-openai-api-key"
export MILVUS_ADDRESS="localhost:19530"

核心原理：TypeScriptExecutor 如何工作

TypeScriptExecutor 类（位于 python/ts_executor.py）是整个桥接的核心。它的工作原理可以概括为：创建临时包装脚本 -> 用 npx ts-node 执行 -> 解析 JSON 输出。

当你在 Python 中调用 executor.call_method("./test_context.ts", "testContextEndToEnd", config) 时，以下步骤会自动发生：

动态生成包装脚本：_create_wrapper_script 方法会创建一个临时的 .ts 文件。关键逻辑在于生成正确的模块导入路径。它会提取目标文件（如 test_context.ts）的文件名，去除 .ts 后缀，并生成相对于临时文件所在目录的 import 路径（例如 import * as targetModule from './test_context'）。这保证了模块能被正确解析。
参数序列化与注入：Python 的参数（如包含 openaiApiKey、milvusAddress 等的字典）会被 json.dumps 序列化，并作为常量嵌入到生成的 TypeScript 代码中。
子进程执行：使用 subprocess.Popen 调用 npx ts-node 来执行这个临时脚本。它会实时捕获标准输出和标准错误流。
结果解析与返回：执行器会监听输出，将非 JSON 行（通常是 TypeScript 代码中的 console.log 日志）实时打印出来，并从最后一行有效 JSON 中解析出最终结果返回给 Python。这使得调用过程既能获得实时进度反馈，又能拿到结构化数据。

端到端测试流程解析

test_context.ts 中的 testContextEndToEnd 函数展示了从配置到搜索的完整工作流，这正是我们希望通过 Python 调起的核心功能。该函数接收一个配置对象，依次完成以下步骤：

创建嵌入实例：使用提供的 openaiApiKey 初始化一个 OpenAIEmbedding 实例，模型默认为 text-embedding-3-small。
创建向量数据库实例：使用 milvusAddress 初始化一个 MilvusVectorDatabase 实例。
构建 Context 实例：将嵌入、向量数据库与一个代码分割器（AstCodeSplitter）组合，创建出核心的 Context 实例。代码分割策略是索引质量的关键，Claude Context 代码分割策略一文有详细分析。
检查索引状态：通过 context.hasIndex() 检查目标代码库是否已有索引，实现增量同步，避免重复工作。
索引代码库：如果不存在索引，则调用 context.indexCodebase() 进行异步索引，过程中会回调 console.log 以输出进度百分比。
执行语义搜索：使用 context.semanticSearch() 在已索引的代码库中，针对 searchQuery 进行语义搜索，并返回最相关的代码片段（这里 topK 为 5，相似度阈值 threshold 为 0.5）。
组装返回结果：最终，该函数会整理并返回一个包含成功状态、配置信息、索引统计、搜索结果摘要以及详细搜索结果列表的 JSON 对象。

实战：在 Python 中调用端到端测试

了解原理和流程后，让我们来看看 test_endtoend.py 是如何具体操作的。这是最简单的实践方式。

准备配置：从环境变量中读取 OPENAI_API_KEY 和 MILVUS_ADDRESS，并构建要索引的代码库路径（这里示例为项目自身的 packages/core/src 目录）和搜索查询语句。
实例化执行器并调用：创建 TypeScriptExecutor 对象，然后使用 call_method 传入 TypeScript 测试文件路径、函数名和配置字典。
处理与展示结果：根据返回的 result 字典中的 success 字段判断成败。成功时，详细打印出使用的配置、索引文件数、分块总数、搜索到的结果数量、平均相关性得分，并展示最相关的前三个结果片段（包含文件路径、行号、语言、相关性分数和内容预览）。

你可以直接运行这个脚本进行测试：

python python/test_endtoend.py

成功运行后，你将看到从启动测试到返回搜索结果的完整日志，证明 Python 已成功驱动 TypeScript 完成了整个语义搜索流程。

自定义调用：更灵活的使用方式

ts_executor.py 也暴露了一个便捷函数 call_ts_method，方便你调用自己编写的其他 TypeScript 函数。

假设你有一个 my_utils.ts 文件，其中导出了一个异步函数 fetchRemoteData：

// my_utils.ts
export async function fetchRemoteData(url: string): Promise<any> {
    const response = await fetch(url);
    return response.json();
}

你可以在 Python 中这样调用它：

from ts_executor import call_ts_method

try:
    data = call_ts_method(
        "./my_utils.ts",
        "fetchRemoteData",
        "https://api.example.com/data",
        working_dir="/path/to/your/ts/files" # 可选，指定工作目录
    )
    print("获取到的数据:", data)
except RuntimeError as e:
    print("调用失败:", e)

参数传递非常灵活，args 位置参数和 kwargs 关键字参数都会被 JSON 序列化后传递。这意味着你可以传递复杂对象、数组等数据结构，只要它们能被 JSON 序列化。

总结与注意事项

这个 Python 桥接工具是一个轻量级的解决方案，它让你无需将整个 Claude Context 核心引擎重写为 Python，就能在 Python 项目中快速集成和使用其语义搜索能力。它特别适合用于自动化测试、数据处理流水线或作为更大 Python 应用的一个功能模块。

在使用时，请注意：

性能开销：每次调用都会启动一个新的 npx ts-node 进程，并初始化嵌入模型和向量数据库连接，不适合高频次的单个请求调用。
错误处理：务必使用 try-except 捕获 RuntimeError，其中包含了 TypeScript 端抛出的错误信息。
临时文件清理：执行器会在执行完成后自动清理生成的临时 .ts 文件。

通过本文的教程，你应该已经掌握了从 Python 调用 Claude Context TypeScript 语义搜索能力的完整方法。如需进一步了解其底层架构，可以阅读Claude Context 核心引擎深度解析。

FAQ

Q: 调用时提示 “TypeScript file not found” 怎么办？ A: 请检查传入 call_method 或 call_ts_method 的 TypeScript 文件路径是否正确。该路径相对于你实例化 TypeScriptExecutor 时指定的 working_dir（默认为 Python 脚本的当前工作目录）。

Q: 为什么我的搜索结果返回为空 (foundResults: 0)？ A: 首先，确认 searchQuery 是否与索引代码库的内容有足够的语义相关性。其次，检查返回结果中的 indexStats，看 indexedFiles 和 totalChunks 是否为非零值，这能确认索引是否真正完成。如果索引失败，请检查 OPENAI_API_KEY 和 MILVUS_ADDRESS 的环境变量配置是否正确，以及 Milvus 服务是否可访问。

Q: 可以调用非导出的 TypeScript 函数吗？ A: 不可以。_create_wrapper_script 方法生成的代码是通过 import * as targetModule from ‘...’ 来导入整个模块的，因此只能调用模块中 export 出来的函数。

Claude Context Python 桥接教程：从 Python 调用 TypeScript 语义搜索 #

准备工作：环境配置与依赖安装 #

核心原理：TypeScriptExecutor 如何工作 #

端到端测试流程解析 #

实战：在 Python 中调用端到端测试 #

自定义调用：更灵活的使用方式 #

总结与注意事项 #

FAQ #