codealive-context-engine

CodeAlive Context Engine

在整个代码生态系统中提供语义代码智能——涵盖当前项目、组织仓库、依赖项以及任何已索引的代码库。

身份验证

所有脚本都需要 CodeAlive API 密钥。如果任何脚本因“未配置 API 密钥”而失败，请帮助用户完成设置：

选项 1（推荐）： 运行交互式设置，并等待用户完成：

python setup.py

选项 2（不推荐——密钥会显示在聊天记录中）： 如果用户直接在聊天中粘贴 API 密钥，请通过以下方式保存：

python setup.py --key THE_KEY

在设置成功完成之前，不要重试失败的脚本。

目录

• 身份验证
• 工具概览
• 使用时机
• 快速入门
• 工具参考
• 数据源
• 配置

工具概览

工具	脚本	速度	成本	最适合
列出数据源	datasources.py	即时	免费	发现已索引的仓库和工作区。使用 --query "task" 可运行 AI 相关性筛选（成本低，但非即时），仅返回相关数据源
语义搜索	search.py	快	低	默认发现方式——按含义（概念、行为、架构）查找代码
Grep 搜索	grep.py	快	低	查找包含特定字符串或正则表达式的代码（标识符、字面量、模式）
仓库本体	ontology.py	快	低	了解单个仓库的高层概况
文件树	tree.py	快	免费	有界的仓库树检查
读取文件	read_file.py	快	免费	读取一个相对于仓库的文件路径，也可指定行范围
获取工件	fetch.py	快	免费	获取搜索结果标识符对应的完整内容
工件关系	relationships.py	快	免费	获取单个工件的完整调用图、继承关系或符号引用
ArtifactQuery 架构	schema.py	快	免费	查看支持的元数据查询实体、字段和示例
工件元数据查询	metadata.py	快	低	对已索引仓库进行只读聚合和查询分析
与代码库聊天	chat.py	慢	高	无状态的综合问答。仅在用户明确要求时调用。
获取版本	get_version.py	即时	免费	以 JSON 格式返回已安装的 CodeAlive 技能版本；无需 API 密钥或网络调用

成本指南： semantic_search 和 grep_search 是默认的起点——快速且便宜。使用 fetch_artifacts 加载完整源代码，并使用 get_artifact_relationships 跟踪调用图。这四种工具的成本都很低。

不建议使用聊天： chat.py 会在服务端调用大模型，耗时可能远超检索，而且每次调用的费用明显更高。v3 中它是无状态的：每个问题都要包含先前的发现、工件标识符、假设、范围和限制。除非用户明确要求（例如“使用聊天”或“调用聊天工具”），否则不要调用它。“询问 CodeAlive”或“搜索 CodeAlive”之类的说法不算明确要求——它们指的是搜索工具。

可修复的工具错误： 将返回的 <tool_error> 视为调用失败，而不是成功但结果为空。按照其中的 <try> 指引修正参数，并且仅当 <retry> 字段允许时重试。工具 API v3 始终会在 obj.error 中保留相同的错误，以供 JSON 模式自动化使用。

最高可靠性指南： 如果你的 Agent 支持子 Agent，且任务需要最高可靠性或深度，优先采用由子 Agent 驱动的工作流，组合使用 ontology.py、search.py、grep.py、fetch.py、tree.py/read_file.py、relationships.py、metadata.py 和本地文件读取。 三步工作流（搜索 → 筛选 → 加载真实内容）：

1. 搜索 — 通过描述和标识符查找相关代码位置
2. 筛选 — 仅使用 description 来判断哪些结果值得进一步查看。它只是一个指引，不是真实依据。不要据此得出结论。
3. 获取真实内容 — 对于你判断为相关的每个工件：
   • 外部仓库（无法本地访问）：python fetch.py <identifier>
   • 当前工作仓库：使用编辑器的文件读取工具读取显示路径中的文件 仅将真实的 content 视为事实依据。

当获取预览信息不足时，深入查看 relationships.py。 对于类似函数的工件，fetch.py 响应已预览最多 3 个出站调用和 3 个入站调用，因此对小型工件完成完整获取后，调用图本身很少成为运行 relationships.py 的理由。以下情况可使用它：

• 需要查看所有入站调用方 — 获取预览最多显示 3 个。 完整的入站列表也会显示测试覆盖情况（来自测试文件的入站调用）。
• 需要查看继承树 — --profile inheritanceOnly 会返回祖先和后代（接口实现、子类、基类链）。预览不包含继承关系。
• 需要查看符号引用 — 使用 --profile referencesOnly 查找引用某个类型或标识符的位置。
• 工件太大，无法获取到上下文中 — 相比拉取完整源代码，调用图是成本更低的摘要。

分析器噪声： 出站调用有时会包含使用 foreach/LINQ 的方法所产生的编译器生成辅助项（MoveNext、GetEnumerator、闭包调用）。忽略与工件实际逻辑不符的出站命中。

何时使用

语义搜索（默认）——你描述行为或概念：

• “身份验证是如何实现的？”
• “展示各个服务中的错误处理模式”
• “这个库的内部工作原理是什么？”
• “查找类似功能，为我的实现提供参考”

Grep 搜索——你知道确切文本：

• “查找 RepositoryDeleted 的所有用法”
• “在哪里配置了 ConnectionString？”
• “在整个代码库中搜索 TODO: fix”
• 错误消息、URL、配置键、导入路径、正则表达式模式

以下情况改用本地文件工具：

• 按名称或模式查找特定文件
• 在当前目录中精确搜索关键词
• 读取已知文件路径
• 搜索未提交的更改

快速入门

1. 查看已建立索引的内容

python scripts/datasources.py --query "the user's task in natural language"

建议将用户的任务作为 --query 传入，这样后端只会返回相关的数据源，并为每个数据源提供 relevanceReason。省略 --query 可列出所有内容（即时返回，不进行 AI 筛选）。

2. 搜索代码（快速、低成本）

python scripts/search.py "JWT token validation" my-backend
python scripts/search.py "authentication flow" my-repo --path src/auth --ext .py
python scripts/grep.py "AuthService" my-repo
python scripts/grep.py "auth\\(" my-repo --regex

3. 获取完整内容（针对外部仓库）

python scripts/fetch.py "my-org/backend::src/auth.py::AuthService.login()"

4. 深入查看工件的关系（可选）

# Full call graph (default)
python scripts/relationships.py "my-org/backend::src/auth.py::AuthService.login()"

# Inheritance hierarchy for a class
python scripts/relationships.py "my-org/backend::src/models.py::User" --profile inheritanceOnly

# Calls + inheritance, raise the per-type cap
python scripts/relationships.py "my-org/backend::src/svc.py::Service" --profile allRelevant --max-count 200

5. 与代码库聊天（不推荐——仅在用户明确要求时使用）

python scripts/chat.py "Explain the authentication flow. Prior context: none." my-backend
python scripts/chat.py "Given these prior findings and identifiers: ..., what about security considerations?" my-backend

除非用户明确要求，否则不要调用聊天功能。 v3 聊天是无状态的，没有 conversation_id；每个问题都要包含所需的全部上下文。其他任务请使用本体、搜索、grep、获取/读取、关系和元数据查询。

工具参考

get_version.py — 获取已安装版本

以 JSON 格式返回已安装的 CodeAlive Context Engine 技能版本。无需身份验证，也不会发出网络请求。

python scripts/get_version.py
# {"name": "codealive-context-engine", "version": "3.0.0"}

datasources.py — 列出数据源

python scripts/datasources.py --query "add OAuth to checkout"  # Only sources relevant to a task (recommended)
python scripts/datasources.py              # Ready-to-use sources (full list)
python scripts/datasources.py --all        # All (including processing)
python scripts/datasources.py --json       # JSON output

选项	描述
--query "TASK"	用户用自然语言描述的任务 / 意图。后端会运行 AI 相关性筛选器，仅返回相关的数据源，每个数据源都包含 relevanceReason。只要你知道用户想要完成什么，就建议使用此选项
--all	包含仍在处理中的数据源
--json	原始 JSON 输出（使用 --query 时：{"dataSources": [...], "message": "..."}）

失败时开放（Fail-open）： 如果无法进行相关性筛选，则会返回完整列表并注明原因——在将结果视为相关候选列表前，请检查提示信息。

search.py — 语义代码搜索（默认发现工具）

默认的起点。根据代码的作用——概念、行为、架构——查找代码，而不是匹配确切文本。当你能描述要查找的内容，但不知道代码库中的确切名称时使用。

python scripts/search.py <query> <data_sources...> [options]

选项	描述
--max-results N	可选的返回条目数上限
--path PATH	相对于仓库的路径或目录范围（可重复指定）
--ext EXT	文件扩展名范围，例如 .py 或 .ts（可重复指定）

description 仅用于初步筛选——它会告诉你哪些条目值得进一步查看。它不是事实依据，你绝不能据此得出结论。对于你认为相关的每条结果，都要加载实际源代码：对于外部仓库，使用 fetch.py <identifier>；对于当前工作目录中的仓库，使用编辑器的文件读取工具读取相应路径。只有实际的 content 才是事实依据。

grep.py — 精确文本 / 正则表达式搜索

查找包含特定字符串或正则表达式模式的代码。当你知道要查找的确切文本时使用，例如标识符、错误消息、配置键、URL、领域事件、导入路径、TODO 注释。

python scripts/grep.py <query> <data_sources...> [--regex] [--max-results N] [--path PATH] [--ext EXT]

选项	描述
--regex	将查询解释为正则表达式模式
--max-results N	可选的返回条目数上限
--path PATH	相对于仓库的路径或目录范围（可重复指定）
--ext EXT	文件扩展名范围，例如 .py 或 .ts（可重复指定）

行预览仍只是搜索证据，并非事实依据。在对行为得出结论前，请使用 fetch.py 或本地文件读取工具。

fetch.py — 获取构件内容

获取通过搜索找到的构件的完整源代码内容。对于无法在本地访问的外部仓库，请使用此工具。

python scripts/fetch.py <identifier1> [identifier2...] [--data-source NAME_OR_ID]

限制	值
每个请求的标识符上限	50
标识符来源	搜索结果中的 identifier 字段
标识符格式	{owner/repo}::{path}::{symbol}（符号），{owner/repo}::{path}（文件）
--data-source NAME_OR_ID	可选。数据源名称或 ID（来自结果的 Source: 行），用于区分在多个数据源中建立索引的标识符

对于类似函数的构件，响应会包含简短的关系预览（每个方向最多显示 3 个传入／传出调用）。如需查看完整的调用图、继承关系或引用，请使用构件的标识符运行 relationships.py。

**缺失的标识符。**如果无法解析某个标识符（或它不在你的访问范围内），fetch.py 不会悄悄将其丢弃，而是会输出一个“未找到”部分，列出每个具体的标识符，并提示你重新检查这些 ID，然后重试有问题的标识符。请告知用户哪些构件未能获取，而不要将其省略。

区分存在于多个数据源中的标识符。构件标识符仅在各自的数据源中唯一，因此同一个标识符可能属于多个数据源。如果不带 --data-source 获取此类标识符，后端会返回一个列出候选数据源的 409 响应，而不会替你选择。列出的每个候选项都能解析，因此工作流程如下：不带 --data-source 调用 → 查看 409 响应中的候选项 → 尝试其中一个 → 如果该数据源不是你想要的，则尝试下一个。要解析标识符，请获取所需搜索结果旁显示的 Source: 名称或 ID，并将其传入： python scripts/fetch.py <identifier> --data-source "backend"（或传入 ID）。 relationships.py 也支持相同的 --data-source 标志。如果指定 --data-source 的调用没有找到结果（脚本会显示“在数据源……中未找到内容”的提示），则该标识符属于其他数据源，或者选择器有误：请改用其他 Source: 值重试，或移除 --data-source 以获取 409 候选列表。

relationships.py — 深入了解 Artifact 的关系图

返回单个 Artifact 的完整调用图（传入／传出调用）、继承层级 （祖先／后代）或符号引用。这是用于深入分析的工具——在通过 search.py 或 fetch.py 获取标识符后，如果想了解 Artifact 与代码库其余部分的关系，请使用此工具。

python scripts/relationships.py <identifier> [--profile PROFILE] [--max-count N] [--data-source NAME_OR_ID]

选项	描述
--profile callsOnly	默认。传出 + 传入调用
--profile inheritanceOnly	祖先 + 后代
--profile allRelevant	调用 + 继承（4 组）
--profile referencesOnly	符号引用
--max-count N	每种关系类型最多返回的相关 Artifact 数量（1–1000，默认 50）
--data-source NAME_OR_ID	可选。数据源名称或 ID，用于消除在多个数据源中编入索引的标识符歧义（与 fetch.py 使用相同的 409 约定）
--json	输出原始 JSON 响应，而非格式化视图

相比 fetch 预览，此工具适用的情况：

• 需要所有传入调用方（包括测试）——fetch 预览 每个方向最多显示 3 个
• 需要继承树（--profile inheritanceOnly）——预览 不包含祖先／后代
• 需要符号引用（--profile referencesOnly）——预览 不包含引用
• Artifact 太大，无法提取到上下文中

**通常多此一举的情况：**你已经对一个适合放入上下文的小型 Artifact 运行了 fetch.py。你需要的传出调用要么在刚读过的 源代码中，要么在预览最多显示的 3 个结果中——只有在明确需要传入调用、继承或引用时，才使用 relationships.py。

**噪声提示：**使用 foreach／LINQ 的方法，其传出调用有时会包含编译器生成的 辅助项（MoveNext、GetEnumerator、闭包调用）。这些是分析器产物——忽略与 Artifact 实际逻辑不符的传出调用结果。

chat.py — 与代码库聊天（不推荐）

除非用户明确要求（例如“使用 chat”“调用 chat 工具”），否则不要调用。“询问 CodeAlive”或“搜索 CodeAlive”之类的说法指的是搜索工具，而非聊天。

将独立的问题发送给一个拥有所选已编入索引代码库完整上下文的 AI 顾问。返回综合整理、可直接使用的答案。

此工具速度慢且成本高——它会在服务端运行大模型，耗时可能远超检索。v3 中它是无状态的，因此每个问题都要包含先前的发现、标识符、假设、范围和限制。对于所有常规任务（查找代码、理解架构、调试），请改用 ontology、search、grep、fetch/read、relationships 和 metadata 查询。

python scripts/chat.py <question> <data_sources...> [options]

v3 中没有公开的 conversation_id。如需后续提问，请在下一个 question 中重述相关上下文。

数据源

Repository — 单个代码库，用于有针对性的搜索：

python scripts/search.py "query" my-backend-api

Workspace — 多个仓库，用于跨项目模式：

python scripts/search.py "query" workspace:backend-team

多个仓库：

python scripts/search.py "query" repo-a repo-b repo-c

配置

前置条件

• Python 3.8+（无需第三方软件包——仅使用标准库）

API Key 设置

此 skill 需要 CodeAlive API key。按以下顺序查找：

1. CODEALIVE_API_KEY 环境变量
2. 操作系统凭据存储（macOS Keychain / Linux secret-tool / Windows Credential Manager）

环境变量（所有平台）：

export CODEALIVE_API_KEY="your_key_here"

macOS Keychain：

security add-generic-password -a "$USER" -s "codealive-api-key" -w "YOUR_API_KEY"

Linux（freedesktop secret-tool）：

secret-tool store --label="CodeAlive API Key" service codealive-api-key

Windows Credential Manager：

cmdkey /generic:codealive-api-key /user:codealive /pass:"YOUR_API_KEY"

Base URL（可选，默认为 https://app.codealive.ai）：

export CODEALIVE_BASE_URL="https://your-instance.example.com"

对于可自托管的 CodeAlive，请使用你的部署源站。推荐使用 https://your-instance.example.com，但也接受 https://your-instance.example.com/api，并会自动规范化。

在此获取 API keys：https://app.codealive.ai/settings/api-keys

与 CodeAlive MCP 服务配合使用

此技能可独立运行，但与 CodeAlive MCP server 配合使用时体验最佳。MCP 服务通过模型上下文协议提供直接的工具访问，而此技能则提供工作流知识和查询模式，帮助你有效使用这些工具。

组件	提供内容
此技能	查询模式、工作流指导、兼顾成本的工具选择
MCP 服务	通过 MCP 协议直接提供 semantic_search、grep_search、fetch_artifacts、get_artifact_relationships、get_data_sources 工具

同时安装两者时，直接操作优先使用 MCP 服务的工具，引导式工作流则使用此技能的脚本。

详细指南

如需了解高级用法，请参阅参考文件：

• 查询模式 — 编写有效查询、反模式、特定语言示例
• 工作流 — 有关新手引导、调试、功能规划等的分步工作流