deep-research

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Deep Research (via DeepAPI)

深度研究（通过DeepAPI）

We use DeepAPI (deepapi.co) for all deep research. This fully replaced the retired

perplexity-deep-research

skill that called OpenRouter/Perplexity directly.

我们使用DeepAPI（deepapi.co）完成所有深度研究工作。它已完全取代了直接调用OpenRouter/Perplexity的已停用

perplexity-deep-research

技能。

API key

API密钥

Read
```
DEEPAPI_API_KEY
```
from the environment; setup writes it to
```
~/.deepapi/env
```
.
Gotcha: do NOT
```
source ~/.zshrc
```
— it breaks the shell (exit 126). Use the env var if set, else load the platform file:

bash

[ -n "$DEEPAPI_API_KEY" ] || . ~/.deepapi/env
KEY=$DEEPAPI_API_KEY
BASE=${DEEPAPI_API_BASE_URL:-https://deepapi.co}

Key missing → stop and ask the user. Never print or log the key.

从环境变量中读取
```
DEEPAPI_API_KEY
```
；配置时会将其写入
```
~/.deepapi/env
```
。
注意事项： 请勿执行
```
source ~/.zshrc
```
——这会导致shell崩溃（退出码126）。如果已设置环境变量则使用它，否则加载平台文件：

bash

[ -n "$DEEPAPI_API_KEY" ] || . ~/.deepapi/env
KEY=$DEEPAPI_API_KEY
BASE=${DEEPAPI_API_BASE_URL:-https://deepapi.co}

若密钥缺失→停止操作并询问用户。切勿打印或记录密钥。

Step 1 — Build the research prompt

步骤1 — 构建研究提示

Write ONE self-contained paragraph following the

research-prompt

skill:

Lead with the single question + the decision/end use it informs.
Embed all context — no back-and-forth needed.
Number 3-6 inline sub-questions (1, 2, 3…). One mission per prompt.
State include/avoid constraints; prefer primary sources; separate fact from inference.

Field limits:

query

≤ 4000 chars (the paragraph goes here), optional

context

≤ 8000, optional

instructions

≤ 2000. Do NOT pass

model

provider

fields — the API rejects provider controls.

遵循

research-prompt

技能的要求，撰写一段独立完整的段落：

以单个问题及其要支撑的决策/最终用途开头。
嵌入所有上下文信息——无需来回沟通。
列出3-6个内嵌子问题（1、2、3…）。每个提示对应一项任务。
说明包含/排除的约束条件；优先使用原始数据源；区分事实与推论。

字段限制：

query

≤4000字符（段落内容放在此处），可选

context

≤8000字符，可选

instructions

≤2000字符。请勿传入

model

或

provider

字段——API会拒绝提供商控制参数。

Step 2 — Run it

步骤2 — 执行查询

One call = one cited answer (targets 700-1,120 words; the server allows up to ~5 minutes, most runs finish much faster).

bash

IDK=$(uuidgen)   # keep this; retries must reuse the SAME Idempotency-Key
jq -n --rawfile p /tmp/dr_prompt.txt '{query:$p, maxCostUsd:"0.70"}' > /tmp/dr_body.json
curl -s --max-time 320 "$BASE/v1/research/deep" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDK" \
  -d @/tmp/dr_body.json > /tmp/dr_result.json

The API minimum is

maxCostUsd: "0.35"

per call. Use the recommended

maxCostUsd: "0.70"

by default; raise it above $0.70 only if the user approves.

一次调用会生成一个带引用的答案（目标字数700-1120字；服务器允许最长等待约5分钟，多数运行会快得多）。

bash

IDK=$(uuidgen)   # 保留此值；重试时必须使用相同的Idempotency-Key
jq -n --rawfile p /tmp/dr_prompt.txt '{query:$p, maxCostUsd:"0.70"}' > /tmp/dr_body.json
curl -s --max-time 320 "$BASE/v1/research/deep" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDK" \
  -d @/tmp/dr_body.json > /tmp/dr_result.json

API的单次调用最低成本为

maxCostUsd: "0.35"

。默认使用推荐的

maxCostUsd: "0.70"

；仅在用户批准的情况下才将其提高到0.70美元以上。

Step 3 — Read the report + sources

步骤3 — 读取报告与数据源

bash

jq -r '.status'                    /tmp/dr_result.json   # succeeded | failed
jq -r '.output.answer'             /tmp/dr_result.json   # the report
jq -r '.output.sources[]?.url'     /tmp/dr_result.json   # source URLs

Save the report to a markdown file for the user and list citation URLs beneath it. Don't report research costs unless the user asks.

output.sources

comes back empty while the answer shows

[n]

citation markers, still deliver the report, but tell the user.

bash

jq -r '.status'                    /tmp/dr_result.json   # succeeded | failed
jq -r '.output.answer'             /tmp/dr_result.json   # 报告内容
jq -r '.output.sources[]?.url'     /tmp/dr_result.json   # 数据源URL

将报告保存为markdown文件提供给用户，并在下方列出引用URL。除非用户询问，否则无需告知研究成本。

若

output.sources

返回为空，但答案中显示

[n]

引用标记，仍需交付报告，但要告知用户此情况。

Bigger topics — multi-call reports

大型主题 — 多调用报告

One call tops out around 1,100 words. For a full deep-research report, fire one call per numbered sub-question (each with its own Idempotency-Key), then synthesize all answers + sources into a single markdown file.

单次调用的输出上限约为1100字。对于完整的深度研究报告，可为每个编号子问题发起一次调用（每个调用使用独立的Idempotency-Key），然后将所有答案和数据源整合为单个markdown文件。

Failure modes

失败场景

HTTP 402
```
insufficient_credits
```
→ stop; the user tops up at deepapi.co/credits; then retry with the SAME
```
Idempotency-Key
```
(safe — replays don't double-charge).
HTTP 429
```
rate_limit_exceeded
```
→ wait
```
Retry-After
```
seconds, retry once.
```
status: failed
```
/ HTTP 502 → report
```
requestId
```
+
```
error.message
```
to the user. Do not retry in a loop.
Replayed request (same Idempotency-Key) returns HTTP 200 with
```
replayed: true
```
and no new charge.
Envelope/auth mechanics and all other endpoints: see the
```
deepapi
```
skill.

HTTP 402
```
insufficient_credits
```
→停止操作；用户需前往deepapi.co/credits充值；然后使用相同的
```
Idempotency-Key
```
重试（安全——重放不会重复扣费）。
HTTP 429
```
rate_limit_exceeded
```
→等待
```
Retry-After
```
秒后重试一次。
```
status: failed
```
/ HTTP 502→向用户报告
```
requestId
```
+
```
error.message
```
。请勿循环重试。
重放请求（使用相同的Idempotency-Key）会返回HTTP 200，且
```
replayed: true
```
，不会产生新费用。
信封/认证机制及所有其他端点：请查看
```
deepapi
```
技能。