exa-context

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Exa Context

Exa 上下文

Token-efficient strategies for retrieving code context using exa-ai.

Use
--help
to see available commands and verify usage before running:

bash

exa-ai <command> --help

使用exa-ai高效获取代码上下文的Token优化策略。

运行前使用
--help
查看可用命令并验证用法：

bash

exa-ai <command> --help

Critical Requirements

关键要求

MUST follow these rules when using exa-ai context:

使用exa-ai上下文时必须遵守以下规则：

Shared Requirements

通用要求

This skill inherits requirements from Common Requirements:

Output format selection → All output operations

本技能继承自通用要求的规则：

输出格式选择 → 所有输出操作

MUST Rules

必须遵守的规则

Use dynamic tokens: Default
```
--tokens-num dynamic
```
adapts to content; specify exact number only when needed

使用动态Token数：默认
```
--tokens-num dynamic
```
会根据内容自动调整；仅在必要时指定具体数值

SHOULD Rules

建议遵守的规则

Prefer text format: Use
```
--output-format text
```
for direct use in prompts or documentation (removes JSON wrapper overhead)

优先使用文本格式：使用
```
--output-format text
```
以便直接在提示词或文档中使用（去除JSON包装的额外开销）

Cost Optimization

成本优化

Pricing

定价

1-25 results: $0.005 per search
26-100 results: $0.025 per search (5x more expensive)

Cost strategy:

Default to 1-25 results: 5x cheaper, sufficient for most queries
Need 50+ results? Run multiple targeted searches: Two 25-result searches with different angles beats one 50-result search (better quality, more control)
Use 26-100 results sparingly: Only when you need comprehensive coverage that multiple targeted searches would miss

1-25条结果：每次搜索$0.005
26-100条结果：每次搜索$0.025（贵5倍）

成本策略：

默认使用1-25条结果：便宜5倍，足以满足大多数查询需求
需要50+条结果？运行多次针对性搜索：两次25条结果的针对性搜索效果优于一次50条结果的搜索（质量更高，可控性更强）
谨慎使用26-100条结果：仅当多次针对性搜索无法覆盖你所需的全面内容时才使用

Token Optimization

Token优化

Apply these strategies:

Use toon format:
```
--output-format toon
```
for 40% fewer tokens than JSON (use when reading output directly)
Use text format:
```
--output-format text
```
to get raw context without JSON wrapper (ideal for piping to other commands)
Use JSON + jq: Extract only the context field with jq when processing programmatically
Set token limits: Use
```
--tokens-num N
```
to control response size

IMPORTANT: Choose one approach, don't mix them:

Approach 1: text format - Raw context output for direct use (no JSON wrapper)
Approach 2: toon format - Compact YAML-like output for direct reading
Approach 3: JSON + jq - Extract context field programmatically

Examples:

bash

undefined

应用以下策略：

使用toon格式：
```
--output-format toon
```
比JSON格式少用40%的Token（直接阅读输出时使用）
使用文本格式：
```
--output-format text
```
获取无JSON包装的原始上下文（适合管道到其他命令）
使用JSON + jq：程序化处理时，用jq仅提取上下文字段
设置Token限制：使用
```
--tokens-num N
```
控制响应大小

重要提示：选择一种方法，不要混合使用：

方法1：文本格式 - 用于直接使用的原始上下文输出（无JSON包装）
方法2：toon格式 - 用于直接阅读的类YAML紧凑输出
方法3：JSON + jq - 程序化提取上下文字段

示例：

bash

undefined

❌ High token usage - full JSON wrapper

❌ Token占用高 - 完整JSON包装器

exa-ai context "React hooks"

✅ Approach 1: text format for direct use (removes JSON overhead)

✅ 方法1：文本格式用于直接使用（去除JSON开销）

exa-ai context "React hooks" --output-format text

✅ Approach 2: toon format for reading (40% reduction)

✅ 方法2：toon格式用于阅读（Token减少40%）

exa-ai context "React hooks" --output-format toon

✅ Approach 3: JSON + jq to extract context only

✅ 方法3：JSON + jq仅提取上下文

exa-ai context "React hooks" | jq -r '.context'

undefined

exa-ai context "React hooks" | jq -r '.context'

undefined

Quick Start

快速开始

Basic Context Retrieval

基础上下文检索

bash

exa-ai context "React hooks useState useEffect" --output-format toon

bash

exa-ai context "React hooks useState useEffect" --output-format toon

Specific Token Limit

指定Token限制

bash

exa-ai context "Python async/await patterns" --tokens-num 5000

bash

exa-ai context "Python async/await patterns" --tokens-num 5000

Authentication Patterns

认证模式

bash

exa-ai context "JWT authentication with Ruby on Rails" \
  --tokens-num 3000 \
  --output-format text

bash

exa-ai context "JWT authentication with Ruby on Rails" \
  --tokens-num 3000 \
  --output-format text

Extract Context for Direct Use

提取上下文直接使用

bash

exa-ai context "GraphQL schema design best practices" \
  --tokens-num 4000 | jq -r '.context'

bash

exa-ai context "GraphQL schema design best practices" \
  --tokens-num 4000 | jq -r '.context'

Detailed Reference

详细参考

For complete options, examples, and advanced usage, consult REFERENCE.md.

完整的选项、示例和高级用法，请查阅REFERENCE.md。

Shared Requirements

通用要求

<shared-requirements>

Schema Design

Schema设计

MUST: Use object wrapper for schemas

必须：使用对象包装器定义Schema

Applies to: answer, search, find-similar, get-contents

When using schema parameters (

--output-schema

--summary-schema

), always wrap properties in an object:

json

{"type":"object","properties":{"field_name":{"type":"string"}}}

DO NOT use bare properties without the object wrapper:

json

{"properties":{"field_name":{"type":"string"}}}  // ❌ Missing "type":"object"

Why: The Exa API requires a valid JSON Schema with an object type at the root level. Omitting this causes validation errors.

Examples:

bash

undefined

适用范围：answer、search、find-similar、get-contents

使用Schema参数（

--output-schema

或

--summary-schema

）时，务必将属性包装在对象中：

json

{"type":"object","properties":{"field_name":{"type":"string"}}}

不要使用无对象包装的裸属性：

json

{"properties":{"field_name":{"type":"string"}}}  // ❌ 缺少"type":"object"

原因：Exa API要求根级别为对象类型的有效JSON Schema。省略该字段会导致验证错误。

示例：

bash

undefined

✅ CORRECT - object wrapper included

✅ 正确 - 包含对象包装器

exa-ai search "AI news"
--summary-schema '{"type":"object","properties":{"headline":{"type":"string"}}}'

❌ WRONG - missing object wrapper

❌ 错误 - 缺少对象包装器

exa-ai search "AI news"
--summary-schema '{"properties":{"headline":{"type":"string"}}}'

---

exa-ai search "AI news"
--summary-schema '{"properties":{"headline":{"type":"string"}}}'

---

Output Format Selection

输出格式选择

MUST NOT: Mix toon format with jq

禁止：混合使用toon格式与jq

Applies to: answer, context, search, find-similar, get-contents

toon

format produces YAML-like output, not JSON. DO NOT pipe toon output to jq for parsing:

bash

undefined

适用范围：answer、context、search、find-similar、get-contents

toon

格式生成类YAML输出，而非JSON。不要将toon输出通过管道传给jq解析：

bash

undefined

❌ WRONG - toon is not JSON

❌ 错误 - toon不是JSON格式

exa-ai search "query" --output-format toon | jq -r '.results'

✅ CORRECT - use JSON (default) with jq

✅ 正确 - 使用JSON（默认格式）与jq

exa-ai search "query" | jq -r '.results[].title'

✅ CORRECT - use toon for direct reading only

✅ 正确 - toon格式仅用于直接阅读

exa-ai search "query" --output-format toon


**Why**: jq expects valid JSON input. toon format is designed for human readability and produces YAML-like output that jq cannot parse.

exa-ai search "query" --output-format toon


**原因**：jq需要有效的JSON输入。toon格式专为人类可读性设计，生成的类YAML输出无法被jq解析。

SHOULD: Choose one output approach

建议：选择一种输出方法

Applies to: answer, context, search, find-similar, get-contents

Pick one strategy and stick with it throughout your workflow:

Approach 1: toon only - Compact YAML-like output for direct reading
- Use when: Reading output directly, no further processing needed
- Token savings: ~40% reduction vs JSON
- Example:
```
exa-ai search "query" --output-format toon
```
Approach 2: JSON + jq - Extract specific fields programmatically
- Use when: Need to extract specific fields or pipe to other commands
- Token savings: ~80-90% reduction (extracts only needed fields)
- Example:
```
exa-ai search "query" | jq -r '.results[].title'
```
Approach 3: Schemas + jq - Structured data extraction with validation
- Use when: Need consistent structured output across multiple queries
- Token savings: ~85% reduction + consistent schema
- Example:
```
exa-ai search "query" --summary-schema '{...}' | jq -r '.results[].summary | fromjson'
```

Why: Mixing approaches increases complexity and token usage. Choosing one approach optimizes for your use case.

适用范围：answer、context、search、find-similar、get-contents

选择一种策略并在整个工作流中坚持使用：

方法1：仅使用toon - 紧凑的类YAML输出，用于直接阅读
- 使用场景：直接阅读输出，无需进一步处理
- Token节省：比JSON减少约40%
- 示例：
```
exa-ai search "query" --output-format toon
```
方法2：JSON + jq - 程序化提取特定字段
- 使用场景：需要提取特定字段或管道到其他命令
- Token节省：减少约80-90%（仅提取所需字段）
- 示例：
```
exa-ai search "query" | jq -r '.results[].title'
```
方法3：Schema + jq - 带验证的结构化数据提取
- 使用场景：需要在多个查询中保持一致的结构化输出
- Token节省：减少约85% + 一致的Schema
- 示例：
```
exa-ai search "query" --summary-schema '{...}' | jq -r '.results[].summary | fromjson'
```

原因：混合使用方法会增加复杂度和Token占用。选择一种方法可针对你的使用场景进行优化。

Shell Command Best Practices

Shell命令最佳实践

MUST: Run commands directly, parse separately

必须：直接运行命令，单独解析

Applies to: monitor, search (websets), research, and all skills using complex commands

When using the Bash tool with complex shell syntax, run commands directly and parse output in separate steps:

bash

undefined

适用范围：monitor、search（websets）、research以及所有使用复杂命令的技能

使用Bash工具处理复杂Shell语法时，直接运行命令并在单独步骤中解析输出：

bash

undefined

❌ WRONG - nested command substitution

❌ 错误 - 嵌套命令替换

webset_id=$(exa-ai webset-create --search '{"query":"..."}' | jq -r '.webset_id')

✅ CORRECT - run directly, then parse

✅ 正确 - 直接运行，然后解析

exa-ai webset-create --search '{"query":"..."}'

Then in a follow-up command:

然后在后续命令中：

webset_id=$(cat output.json | jq -r '.webset_id')


**Why**: Complex nested `$(...)` command substitutions can fail unpredictably in shell environments. Running commands directly and parsing separately improves reliability and makes debugging easier.

webset_id=$(cat output.json | jq -r '.webset_id')


**原因**：复杂的嵌套`$(...)`命令替换在Shell环境中可能会意外失败。直接运行命令并单独解析可提高可靠性，便于调试。

MUST NOT: Use nested command substitutions

禁止：使用嵌套命令替换

Applies to: All skills when using complex multi-step operations

Avoid nesting multiple levels of command substitution:

bash

undefined

适用范围：所有技能执行复杂多步骤操作时

避免使用多层嵌套的命令替换：

bash

undefined

❌ WRONG - deeply nested

❌ 错误 - 深层嵌套

result=$(exa-ai search "$(cat query.txt | tr '\n' ' ')" --num-results $(cat config.json | jq -r '.count'))

✅ CORRECT - sequential steps

✅ 正确 - 分步执行

query=$(cat query.txt | tr '\n' ' ') count=$(cat config.json | jq -r '.count') exa-ai search "$query" --num-results $count


**Why**: Nested command substitutions are fragile and hard to debug when they fail. Sequential steps make each operation explicit and easier to troubleshoot.

query=$(cat query.txt | tr '\n' ' ') count=$(cat config.json | jq -r '.count') exa-ai search "$query" --num-results $count


**原因**：嵌套命令替换不稳定，失败时难以调试。分步执行可使每个操作清晰明确，便于排查问题。

SHOULD: Break complex commands into sequential steps

建议：将复杂命令拆分为分步操作

Applies to: All skills when working with multi-step workflows

For readability and reliability, break complex operations into clear sequential steps:

bash

undefined

适用范围：所有技能处理多步骤工作流时

为了可读性和可靠性，将复杂操作拆分为清晰的分步操作：

bash

undefined

❌ Less maintainable - everything in one line

❌ 可维护性低 - 所有操作在一行

exa-ai webset-create --search '{"query":"startups","count":1}' | jq -r '.webset_id' | xargs -I {} exa-ai webset-search-create {} --query "AI" --behavior override

✅ More maintainable - clear steps

✅ 可维护性高 - 步骤清晰

exa-ai webset-create --search '{"query":"startups","count":1}' webset_id=$(jq -r '.webset_id' < output.json) exa-ai webset-search-create $webset_id --query "AI" --behavior override


**Why**: Sequential steps are easier to understand, debug, and modify. Each step can be verified independently.

</shared-requirements>

exa-ai webset-create --search '{"query":"startups","count":1}' webset_id=$(jq -r '.webset_id' < output.json) exa-ai webset-search-create $webset_id --query "AI" --behavior override


**原因**：分步操作更易于理解、调试和修改。每个步骤可独立验证。

</shared-requirements>