researcher

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Researcher

Use Researcher when the work should become a durable, inspectable research run instead of a one-off answer. A good run gives the user a watch URL immediately, then stores sources, artifacts, costs, report output, and run-scoped chat context.

当你需要将工作转化为可持久化、可检查的研究任务，而非一次性答案时，请使用Researcher。一个优质的任务会立即为用户提供监控URL，随后存储数据源、工件、成本、报告输出以及任务范围的聊天上下文。

Product Model

产品模型

Think in five verbs:

Plan: preview a vague or high-stakes request before spending.
Run: start durable server-side work and share the watch URL immediately.
Inspect: read the truth bundle, markdown, sources, source extractions, usage, warnings, and events.
Iterate: fork, continue, deepen, focus, steer, re-extract, or regenerate the report.
Export: save markdown plus structured sources/source-extractions downstream.

可以用五个动词来理解：

规划（Plan）：在投入成本前，预览模糊或高风险的请求。
运行（Run）：启动持久化的服务器端工作，并立即分享监控URL。
检查（Inspect）：查看真实信息包、markdown内容、数据源、数据源提取结果、使用情况、警告信息和事件记录。
迭代（Iterate）：分支、续跑、深化、聚焦、引导、重新提取或重新生成报告。
导出（Export）：将markdown内容加上结构化的数据源/数据源提取结果保存到下游系统。

Setup

配置

Required input:

RESEARCHER_API_KEY

RESEARCHER_TOKEN

, a customer Researcher API token from

https://researcher.now/account/?setup=agent

Optional input:

RESEARCHER_BASE_URL

; default it to

https://researcher.now

Use
```
RESEARCHER_API_KEY
```
as the bearer token. Accept
```
RESEARCHER_TOKEN
```
as an alias if the environment already uses it.
If no customer token is available, send the user to
```
https://researcher.now/account/?setup=agent
```
.
Never search local files, shell history, or logs for customer tokens.
Never use admin-token, payment-bypass, or internal-only routes in customer workflows.

必填输入：

RESEARCHER_API_KEY

或

RESEARCHER_TOKEN

，即从

https://researcher.now/account/?setup=agent

获取的客户Researcher API令牌。

可选输入：

RESEARCHER_BASE_URL

；默认值为

https://researcher.now

。

将
```
RESEARCHER_API_KEY
```
用作Bearer令牌。如果环境已使用
```
RESEARCHER_TOKEN
```
，可将其作为别名使用。
如果没有客户令牌，引导用户访问
```
https://researcher.now/account/?setup=agent
```
。
切勿在本地文件、shell历史记录或日志中搜索客户令牌。
在客户工作流中，切勿使用管理员令牌、支付绕过或仅限内部使用的路由。

Choose The Operation

选择操作

Use
```
POST /v1/runs
```
with
```
preflightPlan:true
```
before spending when the customer prompt is vague, high-stakes, or needs an explicit success checklist.

Use

POST /v1/runs

for all new durable work. Pick

source.type

topic

url

feed

, or

video

; include

requestedBy

and an

Idempotency-Key

Use
```
source.type:"video"
```
for a YouTube URL, podcast/video link, or transcript-first task. Do not scrape video as a generic webpage.
Use
```
source.type:"url"
```
for a known webpage/domain extraction and
```
source.type:"feed"
```
for one-shot RSS, Atom, or JSON Feed ingestion.
Use
```
GET /v1/me
```
to confirm whether the bearer token is a customer or admin token before spending.
Use
```
GET /v1/runs
```
,
```
/v1/library
```
, or
```
/v1/library/recall?q=*
```
to enumerate existing runs and recall.
Use
```
GET /v1/runs/:id/job
```
for live run state. Read top-level
```
status
```
,
```
currentStage
```
,
```
currentActivity
```
, and
```
state
```
; legacy
```
job.status
```
remains nested under
```
job
```
.
Use
```
GET /v1/runs/:id/results
```
or
```
/markdown
```
to read a completed run.
Use
```
GET /v1/runs/:id/transcript
```
for typed video transcript segments instead of raw transcript metadata blobs.
Use
```
POST /v1/runs/:id/sources/:sourceId/redo
```
when a source extracted weakly and the run can be salvaged without forking.
Use
```
GET /v1/library/search?claim=...
```
for account-level claim recall across completed runs.
Use
```
POST /v1/runs/:id/chat
```
for questions scoped to one completed run, or the
```
/chat/sessions
```
endpoints for multi-turn UI flows.
Use
```
POST /v1/runs/:id/iterate
```
as the canonical iteration wrapper for start, pause, continue, deepen, focus, steer, report, fork, evaluate, cancel, and stop. Include
```
Idempotency-Key
```
on paid iterate calls.

Use

POST /v1/runs/:id/iterate

with

action:"cancel"

action:"stop"

to abort active work.

Use
```
/tags
```
,
```
/collections
```
,
```
/diff
```
,
```
/export
```
, and
```
/webhooks
```
when organizing runs, comparing continuations, or sending completed runs to downstream systems.

当客户的提示模糊、高风险，或需要明确的成功检查清单时，在投入成本前使用
```
POST /v1/runs
```
并设置
```
preflightPlan:true
```
。
所有新的持久化工作都使用
```
POST /v1/runs
```
。选择
```
source.type
```
为
```
topic
```
、
```
url
```
、
```
feed
```
或
```
video
```
；需包含
```
requestedBy
```
和
```
Idempotency-Key
```
。
对于YouTube URL、播客/视频链接或优先处理转录的任务，使用
```
source.type:"video"
```
。不要将视频作为通用网页进行抓取。
对于已知网页/域名提取，使用
```
source.type:"url"
```
；对于一次性RSS、Atom或JSON Feed导入，使用
```
source.type:"feed"
```
。
在投入成本前，使用
```
GET /v1/me
```
确认Bearer令牌是客户令牌还是管理员令牌。
使用
```
GET /v1/runs
```
、
```
/v1/library
```
或
```
/v1/library/recall?q=*
```
枚举现有任务并进行召回。
使用
```
GET /v1/runs/:id/job
```
获取任务的实时状态。查看顶层的
```
status
```
、
```
currentStage
```
、
```
currentActivity
```
和
```
state
```
；旧版
```
job.status
```
仍嵌套在
```
job
```
下。
使用
```
GET /v1/runs/:id/results
```
或
```
/markdown
```
查看已完成的任务。
使用
```
GET /v1/runs/:id/transcript
```
获取结构化的视频转录片段，而非原始转录元数据 blob。
当某个数据源提取效果不佳且无需分支即可挽救任务时，使用
```
POST /v1/runs/:id/sources/:sourceId/redo
```
。
使用
```
GET /v1/library/search?claim=...
```
在已完成的任务中进行账户级别的声明召回。
针对单个已完成任务的问题，使用
```
POST /v1/runs/:id/chat
```
；对于多轮UI流程，使用
```
/chat/sessions
```
端点。
使用
```
POST /v1/runs/:id/iterate
```
作为标准的迭代封装，用于启动、暂停、续跑、深化、聚焦、引导、报告、分支、评估、取消和停止操作。付费迭代调用需包含
```
Idempotency-Key
```
。

使用

POST /v1/runs/:id/iterate

并设置

action:"cancel"

或

action:"stop"

来中止正在进行的工作。

当整理任务、比较续跑版本或将已完成任务发送到下游系统时，使用
```
/tags
```
、
```
/collections
```
、
```
/diff
```
、
```
/export
```
和
```
/webhooks
```
。

Run Workflow

任务工作流

Convert the user's ask into a precise research prompt. Preserve requested output shape, required sources, time horizon, evaluation criteria, and exclusions.
Create the run and return the watch URL as soon as the API returns it. Do not wait for completion before sharing the link.
Track status through the watch URL, stream endpoint, or polling endpoint when the user wants updates.
On completion, fetch results, markdown, sources, extractions, and usage/cost if the user needs the final artifact or an audit.
For quality-sensitive work, review the report against the original prompt. Continue, deepen, focus, or fork instead of declaring success when prompt requirements are missing.

将用户的需求转换为精确的研究提示。保留要求的输出格式、必需的数据源、时间范围、评估标准和排除项。
创建任务，一旦API返回监控URL就立即返回给用户。不要等待任务完成后再分享链接。
当用户需要更新时，通过监控URL、流端点或轮询端点跟踪状态。
任务完成后，获取结果、markdown内容、数据源、提取结果以及使用情况/成本（如果用户需要最终工件或审计信息）。
对于对质量敏感的工作，对照原始提示审核报告。当提示要求未满足时，应进行续跑、深化、聚焦或分支操作，而非直接宣布成功。

Prompt Contract

提示约定

For research runs, include these fields in the prompt whenever they are known:

```
Objective
```
: the decision, hypothesis, or question being answered.
```
Output shape
```
: memo, ranked table, bullets, source list, thesis map, etc.
```
Evidence bar
```
: primary sources, expert commentary, recent sources, contrarian views, quantitative support, or transcript timestamps.
```
Scope
```
: geography, dates, companies, market segment, source types, and exclusions.
```
Quality checks
```
: what must be true before the run is considered good.

对于研究任务，只要已知以下字段，就应将其包含在提示中：

```
Objective
```
：要回答的决策、假设或问题。
```
Output shape
```
：备忘录、排名表格、项目符号、数据源列表、论点图等。
```
Evidence bar
```
：主要数据源、专家评论、近期数据源、相反观点、量化支持或转录时间戳。
```
Scope
```
：地域、日期、公司、细分市场、数据源类型和排除项。
```
Quality checks
```
：任务被视为合格前必须满足的条件。

Billing And Failure Handling

计费与故障处理

Use
```
maxCostUsd
```
as a cap when the user gives a budget. A budget is a ceiling, not a target spend.
If the API returns
```
402
```
or wallet/payment authorization errors, use
```
account_funding_url
```
from the response when present. Otherwise send the user to
```
https://researcher.now/account/
```
.
If a stage fails, surface the run URL and the useful error message. Do not replace a failed Researcher run with a generic web-search summary.
If the run has weak evidence or misses prompt requirements, use continuation or forked follow-up work rather than pretending the output is complete.

当用户给出预算时，使用
```
maxCostUsd
```
作为上限。预算是支出上限，而非目标支出。
如果API返回
```
402
```
或钱包/支付授权错误，若响应中包含
```
account_funding_url
```
，则使用该链接；否则引导用户访问
```
https://researcher.now/account/
```
。
如果某个阶段失败，展示任务URL和有用的错误信息。不要用通用的网页搜索摘要替代失败的Researcher任务。
如果任务的证据不足或未满足提示要求，应进行续跑或分支后续工作，而非假装输出已完成。

Output Style

输出样式

When creating a run, return:

the run title or topic
the Researcher run URL
the run id
budget/cap if one was set
what the run is currently doing, if available

When reading or reviewing a run, cite the Researcher URL and state whether the report satisfies the user's prompt contract. Include concrete missing requirements when it does not.

创建任务时，返回：

任务标题或主题
Researcher任务URL
任务ID
已设置的预算/上限（如果有）
当前任务正在执行的操作（如果可用）

查看或审核任务时，引用Researcher URL，并说明报告是否满足用户的提示约定。如果未满足，列出具体缺失的要求。

Iteration Decision Table

迭代决策表

iterate

: canonical wrapper; pass

action

start

pause

continue

deepen

focus

steer

report

fork

evaluate

cancel

, or

stop

```
fork
```
: create a separate reviewable child version without starting new paid work.
```
continue
```
: add more work to the same run or an approved fork.
```
deepen
```
: convenience continuation for broader/deeper acquisition.
```
focus
```
: convenience continuation narrowed to named topics.
```
steer
```
: mid-run guidance consumed at worker checkpoints.
```
report
```
: regenerate/update the report from the current corpus without more acquisition.
```
cancel
```
/
```
stop
```
: abort active work and settle measured usage.

iterate

：标准封装；传递

action

参数，取值为

start

、

pause

、

continue

、

deepen

、

focus

、

steer

、

report

、

fork

、

evaluate

、

cancel

或

stop

。

```
fork
```
：创建独立的可审核子版本，无需启动新的付费工作。
```
continue
```
：向同一任务或已批准的分支添加更多工作。
```
deepen
```
：用于更广泛/深入获取信息的便捷续跑操作。
```
focus
```
：缩小到指定主题的便捷续跑操作。
```
steer
```
：在工作检查点使用的任务中期引导指令。
```
report
```
：从当前语料库重新生成/更新报告，无需获取更多信息。
```
cancel
```
/
```
stop
```
：中止正在进行的工作并结算已产生的使用费用。

Downstream Export

下游导出

When saving a completed run to another knowledge store, fetch:

```
/markdown
```
for the human-readable memo.
```
/sources
```
for stored source rows.
```
/extractions
```
for structured claims, facts, caveats, quantitative facts, stakeholder positions, and citation-ready source records.
```
/transcript
```
for typed transcript segments on YouTube/video runs.
```
/usage
```
for cost audit.

For YouTube/video runs, avoid sending

metadata.raw.content

transcript fragment blobs into downstream LLM calls. Prefer the report, source records,

/transcript

, or transcript tab data.

Use

POST /v1/runs/:id/export

for webhook-shaped one-off export, or register completion webhooks with

POST /v1/webhooks

将已完成的任务保存到其他知识存储时，获取以下内容：

```
/markdown
```
：供人类阅读的备忘录。
```
/sources
```
：存储的数据源行。
```
/extractions
```
：结构化的声明、事实、注意事项、量化事实、利益相关者立场和可直接引用的数据源记录。
```
/transcript
```
：YouTube/视频任务的结构化转录片段。
```
/usage
```
：成本审计信息。

对于YouTube/视频任务，避免将

metadata.raw.content

转录片段blob发送到下游LLM调用中。优先使用报告、数据源记录、

/transcript

或转录标签页数据。

对于Webhook格式的一次性导出，使用

POST /v1/runs/:id/export

；或通过

POST /v1/webhooks

注册完成事件Webhook。

Recipes

参考示例

For copy-pasteable HTTP examples, endpoint payloads, and run-control recipes, load

references/api-recipes.md

如需可复制粘贴的HTTP示例、端点负载和任务控制参考示例，请加载

references/api-recipes.md

。",