searching-sourcegraph

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Searching Sourcegraph

使用Sourcegraph进行搜索

Search before you build. Existing patterns reduce tokens, ensure consistency, and surface tested solutions.

先搜索再构建。现有模式可减少token使用、确保一致性，并呈现经过测试的解决方案。

Tool Selection Logic

工具选择逻辑

Start here:

Know the exact symbol or pattern? →
```
keyword_search
```
Know the concept, not the code? →
```
nls_search
```
Need to understand how/why? →
```
deepsearch
```
→
```
deepsearch_read
```
Tracing a symbol's usage? →
```
find_references
```
Need full implementation? →
```
go_to_definition
```
→
```
read_file
```
Need to know what repos a user has worked on? →
```
get_contributor_repos
```

Goal	Tool
Concepts/semantic search	`nls_search`
Exact code patterns	`keyword_search`
Trace usage	`find_references`
See implementation	`go_to_definition`
Initiate a deep search	`deepsearch`
Read deep search results	`deepsearch_read`
Read files	`read_file`
Browse structure	`list_files`
Find repos	`list_repos`
Search commits	`commit_search`
Track changes	`diff_search`
Compare versions	`compare_revisions`
Find repos a user has worked on	`get_contributor_repos`

从这里开始：

知道确切的符号或模式？ →
```
keyword_search
```
知道概念但不知道具体代码？ →
```
nls_search
```
需要了解运作方式/原因？ →
```
deepsearch
```
→
```
deepsearch_read
```
追踪符号的使用情况？ →
```
find_references
```
需要完整实现代码？ →
```
go_to_definition
```
→
```
read_file
```
需要了解用户参与过哪些仓库？ →
```
get_contributor_repos
```

目标	工具
概念/语义搜索	`nls_search`
精确代码模式	`keyword_search`
追踪使用情况	`find_references`
查看实现代码	`go_to_definition`
启动深度搜索	`deepsearch`
读取深度搜索结果	`deepsearch_read`
读取文件	`read_file`
浏览结构	`list_files`
查找仓库	`list_repos`
搜索提交记录	`commit_search`
追踪变更	`diff_search`
对比版本	`compare_revisions`
查找用户参与过的仓库	`get_contributor_repos`

Scoping (Always Do This)

范围限定（务必执行）

repo:^github.com/ORG/REPO$           # Exact repo (preferred)
repo:github.com/ORG/                 # All repos in org
file:.*\.ts$                         # TypeScript only
file:src/api/                        # Specific directory
file:.*\.test\.ts$ -file:__mocks__   # Tests, exclude mocks

Start narrow. Expand only if results are empty.

Combine filters:

repo:^github.com/myorg/backend$ file:src/handlers lang:typescript

repo:^github.com/ORG/REPO$           # 精确仓库（优先选择）
repo:github.com/ORG/                 # 组织下所有仓库
file:.*\.ts$                         # 仅TypeScript文件
file:src/api/                        # 指定目录
file:.*\.test\.ts$ -file:__mocks__   # 测试文件，排除模拟文件

从窄范围开始。仅当结果为空时再扩大范围。

组合过滤器：

repo:^github.com/myorg/backend$ file:src/handlers lang:typescript

Context-Aware Behaviour

上下文感知行为

When the user provides a file path or error message:

Extract symbols, function names, or error codes
Search for those exact terms first
Trace references if the error involves a known symbol

When the user asks "how does X work":

Use
```
deepsearch
```
to initiate the search, then
```
deepsearch_read
```
to retrieve results
Follow up with
```
read_file
```
on key files mentioned in the response

When the user asks who worked on something or what repos a contributor has touched:

Use
```
get_contributor_repos
```
with one or more usernames to discover their active repositories
Then scope subsequent searches to those repos

When the user is implementing a new feature:

Search for similar existing implementations first
Read tests for usage examples
Check for shared utilities before creating new ones

When troubleshooting an error, build failure, or runtime exception:

Extract exact symbols, error codes, or log lines from the stack trace or build output
Search for the error site, then trace the full call chain with
```
find_references
```
Check recent changes with
```
diff_search
```
and
```
commit_search
```
early — regressions are common
Identify all affected code paths and services before proposing a fix

When fixing a bug:

Extract exact symbols from the error message or stack trace
Search for the error site, then trace the full call chain with
```
find_references
```
Check recent changes with
```
diff_search
```
and
```
commit_search
```
early — regressions are common
Find all affected code paths before writing the fix
Read existing tests to understand intended behaviour

当用户提供文件路径或错误信息时：

提取符号、函数名或错误代码
先搜索这些精确术语
如果错误涉及已知符号，追踪其引用

当用户询问“X是如何工作的”时：

使用
```
deepsearch
```
启动搜索，再用
```
deepsearch_read
```
获取结果
对响应中提到的关键文件，后续使用
```
read_file
```
查看

当用户询问谁参与过某项工作，或贡献者接触过哪些仓库时：

使用
```
get_contributor_repos
```
并传入一个或多个用户名，发现他们活跃的仓库
之后将后续搜索范围限定在这些仓库内

当用户正在实现新功能时：

先搜索类似的现有实现
阅读测试用例获取使用示例
在创建新工具前先检查是否有可复用的共享工具

当排查错误、构建失败或运行时异常时：

从堆栈跟踪或构建输出中提取精确的符号、错误代码或日志行
搜索错误发生位置，再用
```
find_references
```
追踪完整调用链
尽早用
```
diff_search
```
和
```
commit_search
```
检查近期变更——回归问题很常见
在提出修复方案前，确定所有受影响的代码路径和服务

当修复bug时：

从错误信息或堆栈跟踪中提取精确符号
搜索错误发生位置，再用
```
find_references
```
追踪完整调用链
尽早用
```
diff_search
```
和
```
commit_search
```
检查近期变更——回归问题很常见
在编写修复代码前，找到所有受影响的代码路径
阅读现有测试用例，理解预期行为

Workflows

工作流

For detailed step-by-step workflows, see:

```
workflows/implementing-feature.md
```
— when building new features
```
workflows/understanding-code.md
```
— when exploring unfamiliar systems
```
workflows/debugging-issue.md
```
— when troubleshooting errors, build failures, stack traces, support issues, or runtime exceptions
```
workflows/fixing-bug.md
```
— when fixing bugs with extensive Sourcegraph search
```
workflows/code-review.md
```
— when reviewing a pull request or changeset

如需详细的分步工作流，请查看：

```
workflows/implementing-feature.md
```
—— 构建新功能时
```
workflows/understanding-code.md
```
—— 探索不熟悉的系统时
```
workflows/debugging-issue.md
```
—— 排查错误、构建失败、堆栈跟踪、支持问题或运行时异常时
```
workflows/fixing-bug.md
```
—— 使用Sourcegraph深度搜索修复bug时
```
workflows/code-review.md
```
—— 审查拉取请求或变更集时

Efficiency Rules

效率规则

Minimise tool calls:

Chain searches logically: search → read → references → definition
Don't re-search for the same pattern; use results from prior calls
Prefer
```
keyword_search
```
over
```
nls_search
```
when you have exact terms (faster, more precise)

Batch your understanding:

Read 2-3 related files before synthesising, rather than reading one and asking questions
Use
```
deepsearch
```
+
```
deepsearch_read
```
for "how does X work" instead of multiple keyword searches

Avoid common token waste:

Don't search all repos when you know the target repo
Don't use
```
deepsearch
```
for simple "find all" queries —
```
keyword_search
```
is faster
Don't re-read files you've already seen in this conversation

减少工具调用次数：

按逻辑链式调用工具：搜索 → 读取 → 查找引用 → 查看定义
不要重复搜索相同模式；使用之前调用的结果
当有精确术语时，优先使用
```
keyword_search
```
而非
```
nls_search
```
（更快、更精准）

批量理解内容：

先阅读2-3个相关文件再进行总结，而非读一个文件就提问
对于“X是如何工作的”这类问题，使用
```
deepsearch
```
+
```
deepsearch_read
```
，而非多次关键词搜索

避免常见的token浪费：

当知道目标仓库时，不要搜索所有仓库
简单的“查找全部”查询不要使用
```
deepsearch
```
——
```
keyword_search
```
更快
不要重复阅读本次对话中已经看过的文件

Query Patterns

查询模式

Intent	Query
React hooks	`file:.\.tsx$ use[A-Z].= \(`
API routes	`file:src/api app\.(get\|post\|put\|delete)`
Error handling	`catch.*Error\|\.catch\(`
Type definitions	`file:types/ export (interface\|type)`
Test setup	`file:.*\.test\. beforeEach\|beforeAll`
Config files	`file:(webpack\|vite\|rollup)\.config`
CI/CD	`file:\.github/workflows deploy`

For more patterns, see

query-patterns.md

意图	查询语句
React hooks	`file:.\.tsx$ use[A-Z].= \(`
API路由	`file:src/api app\.(get\|post\|put\|delete)`
错误处理	`catch.*Error\|\.catch\(`
类型定义	`file:types/ export (interface\|type)`
测试设置	`file:.*\.test\. beforeEach\|beforeAll`
配置文件	`file:(webpack\|vite\|rollup)\.config`
CI/CD	`file:\.github/workflows deploy`

如需更多模式，请查看

query-patterns.md

。

Output Formatting

输出格式

Search results:

Present as a brief summary, not raw tool output
Highlight the most relevant file and line
Include a code snippet only if it directly answers the question

Code explanations:

Start with a one-sentence summary
Use the codebase's own terminology
Reference specific files and functions

Recommendations:

Present as numbered steps if actionable
Link to specific patterns found in the codebase
Note any existing utilities that should be reused

搜索结果：

以简短摘要呈现，而非原始工具输出
突出显示最相关的文件和行
仅在直接回答问题时才包含代码片段

代码解释：

以一句话总结开头
使用代码库自身的术语
引用具体文件和函数

建议：

如果可执行，以编号步骤呈现
链接到代码库中找到的具体模式
注明任何应复用的现有工具

Common Mistakes

常见错误

Mistake	Fix
Searching all repos	Add `repo:^github.com/org/repo$`
Too many results	Add `file:` pattern or keywords
Missing relevant code	Try `nls_search` for semantic matching
Not understanding context	Use `deepsearch_read`
Guessing patterns	Read implementations with `read_file`

错误	修复方法
搜索所有仓库	添加 `repo:^github.com/org/repo$`
结果过多	添加 `file:` 模式或关键词
遗漏相关代码	尝试使用 `nls_search` 进行语义匹配
不理解上下文	使用 `deepsearch_read`
猜测模式	使用 `read_file` 查看实现代码

Principles

原则

Start narrow, expand if needed
Chain tools: search → read → find references → definition
Check tests for usage examples
Read before generating

从窄范围开始，必要时再扩大
链式调用工具：搜索 → 读取 → 查找引用 → 查看定义
查看测试用例获取使用示例
先阅读再生成内容