sn-deepresearch-cli

sn-deepresearch-cli

As the user entry point for SenseNova-Skills-DeepResearch, it is responsible for environment pre-checks, installation guidance, parameter confirmation, task startup, progress notification, and result delivery. The default npm package is sensenova-skills-deepresearch, and the project source code repository is https://github.com/OpenSenseNova/SenseNova-Skills-DeepResearch. Users directly install the package that has been built and published to npm, and do not need to clone the repository or build locally.

Environment pre-check

Before installing or starting SenseNova-Skills-DeepResearch, only check whether the current environment meets the runtime requirements:

Whether Node.js >= 22, Python >= 3.10, and npm are available;
Whether the deepresearch command provided by SenseNova-Skills-DeepResearch is already installed;
Whether the Hermes, Codex, Claude Code, or OpenClaw selected by the user exists.

Here, the system's command existence and version checks are sufficient. When the deepresearch command provided by SenseNova-Skills-DeepResearch is not yet installed, do not call deepresearch doctor、sources、browser、status and other SenseNova-Skills-DeepResearch subcommands in advance. When SenseNova-Skills-DeepResearch or the Harness is missing, report the missing items first, and do not silently switch to another Harness.

Do not display environment variable values, tokens, Cookies, npm credentials, or Harness Profiles.

Install or upgrade SenseNova-Skills-DeepResearch

Installation accesses the network and modifies the user-level npm directory, so obtain the authorization required by the current environment before executing it.

Install the built package from npm:

npm install --global sensenova-skills-deepresearch
deepresearch --help

Upgrade to the latest version:

npm install --global sensenova-skills-deepresearch@latest

Maintainers are responsible on the release side for building the Python wheel and npm tarball; the Skill must not ask users to clone the source code, run scripts/build_npm_package.py, create a build virtual environment, or download the tarball from GitHub Release. Only when the user explicitly provides a local .tgz and requests testing may npm install --global <local-tgz>。

Initialize the user-level Search configuration after installation:

deepresearch sources init
deepresearch sources list --json

The configuration file is located at ~/.deepresearch-cli/search/.env. Public sources do not require an API key; when extended sources are needed, only tell the user the variable names that should be filled in, and do not request or echo credentials.

Prepare the Harness

Hermes: reuse the existing Hermes login and model configuration.
Codex: confirm that codex exists and that codex login。
Claude Code: the current ACP Harness must be able to find the claude-agent-acp executable; the ordinary claude command cannot directly replace it. SenseNova-Skills-DeepResearch includes invocation adapter code, but does not bundle an external adapter. When the adapter is missing, after obtaining installation authorization, execute npm install -g @agentclientprotocol/claude-agent-acp. Completing installation does not mean login must be repeated: first run deepresearch doctor --harness claude-code --json to check authentication. When there is an existing ANTHROPIC_API_KEY、 ANTHROPIC_AUTH_TOKEN, Bedrock/Vertex configuration, or the adapter can reuse the existing Claude Code login, use it directly; only when the pre-check confirms that no usable authentication exists should the user be prompted to execute claude-agent-acp --cli auth login. Do not read or echo credential values.
OpenClaw: confirm that openclaw exists and that the Gateway is normal. The model is selected by the OpenClaw configuration; do not pass --harness-model. Before starting research, first identify the Agent and workspace actually used by the current session, and do not treat main、 ~/.openclaw/workspace or hardcode the path on another device. Check whether the Agent has write capability for the current workspace:
```
openclaw health --json
openclaw agents list --json
openclaw config get agents.entries.<current-agent>.sandbox --json
openclaw config get agents.entries.<current-agent>.tools --json
```
The workspace must allow writes (workspaceAccess: rw, or use a non-sandboxed workspace), and the tool policy must at least allow the use of read、write、edit、apply_patch、exec and process. If the configuration is missing, first explain that DeepResearch's plan, research, and report nodes need to create artifacts in this Run's attempt workspace. First explain to the user that write permission needs to be granted for the current Agent's current workspace, and only after obtaining authorization modify the corresponding Agent configuration, restart the Gateway, and re-verify; do not silently expand the permissions of other Agents or other workspaces. Do not start SenseNova-Skills-DeepResearch if the check does not pass. Repeat this pre-check when switching devices or Agents, and do not reuse fixed paths or configurations from an old machine.

After the configuration check passes, perform an OpenClaw write smoke test once before starting formal research:
```
deepresearch doctor --harness openclaw --json
```
This check must confirm that the ACP subsession can create and delete a temporary file in the current SenseNova-Skills-DeepResearch workspace; if it returns workspace-write failure, stop first and do not start formal research. The smoke test uses the actual workspace of the current device and current Agent, and does not reuse test results from other machines.

When the model, login, or Provider credentials are missing, explain the missing configuration and do not rewrite the Harness global configuration on the user's behalf.

Model call timeout and recovery

If the node logs show that a model call was aborted due to a long period of no response at the connection layer, stale/idle timeout, request timeout, broken pipe, or a similar provider error, first explain to the user: the failure occurred at the model provider/connection layer, and confirm the failed node, retry count, actual harness, provider, model, and timeout type; do not misjudge it as a search, report conversion, or SenseNova-Skills-DeepResearch installation failure.

First read the Harness's official configuration or diagnostic output to confirm whether it is a "no-response idle timeout" or a "whole-request timeout", and only display the configuration key names and current values, not credentials. Any operation that modifies the timeout, retry count, provider, or model must first explain the impact to the user and request authorization; do not silently modify the global configuration.

After obtaining authorization, preferably only for the provider/model actually used this time, adjust the no-response idle timeout to 300 seconds, then use the original harness to recover from the failed Run; do not rerun the already successful plan/research from the beginning. Taking Hermes as an example, after confirming the configuration key is providers.<provider_id>.models.<model>.stale_timeout_seconds , only then may you execute:

hermes config set providers.<provider_id>.models.<model>.stale_timeout_seconds 300
deepresearch resume <run-id> --harness hermes --progress tools

If another Harness is actually being used, first find out its equivalent configuration key and modification command, then confirm with the user; do not guess commands from memory. If retries still fail, keep the original Run and logs, and report the new failed node and provider error.

Prepare Camofox

Camofox is an optional fallback after ordinary web scraping fails; the base SenseNova-Skills-DeepResearch does not include browser files. When the user wants to enable it, first explain that several hundred MB of resources need to be downloaded additionally, then after authorization execute:

deepresearch browser setup
deepresearch browser start
deepresearch browser status --json

When the user chooses to enable it, confirm the health status. Camofox only accesses public web pages and is not used to bypass CAPTCHA, login, paywalls, or access controls. If it is not installed or unavailable, do not block the research; SenseNova-Skills-DeepResearch will switch to other sources. Only pass it in when the user explicitly requests it --no-camofox-fallback。

Confirm research parameters

Before starting, confirm the research question and three independent parameters:

Research depth:quick、normal or heavy
Report format:brief or formal_report
Delivery format:markdown、html、pdf or docx
Report language: follow the user's primary language; when the user explicitly specifies a language, use the specified value first (for example, use zh-CNfor Chinese and en-US）

Do not ask again for parameters the user has already provided; parameters not provided need to be confirmed with the user. When DOCX is selected, remind that Pandoc is required; when PDF is selected, remind that Typst is required. The user's primary language can be determined from the current conversation; do not ask again for the language parameter; only ask when it cannot be determined and the language would affect delivery. Before the above parameters are confirmed, do not start research that may run for a long time or incur costs.

Start research

Keep the query and title in their original text

The research text provided by the user in this round is the actual query for SenseNova-Skills-DeepResearch; after removing the prefix used only to trigger the Skill (for example, "use deepresearch"), pass the original text directly to SenseNova-Skills-DeepResearch.
Do not rewrite, expand, summarize, compress, or rename the query on the user's behalf, do not create a separate display title, and do not change the query into a "research + topic" title.
The scope, data source requirements, time range, and delivery requirements written by the user in the query must be preserved as-is. The research title is displayed by SenseNova-Skills-DeepResearch/Web based on the original query; the Skill does not participate in title generation.
mode、report_format、output_format and language are passed only as SenseNova-Skills-DeepResearch parameters and must not be mixed into or rewrite the query text.

Quick uses foreground SenseNova-Skills-DeepResearch:

deepresearch "<query>" \
  --mode quick \
  --report-format <brief|formal_report> \
  --output-format <markdown|html|pdf|docx> \
  --harness <hermes|codex|claude-code|openclaw> \
  --language <user-language> \
  --progress tools

Normal and Heavy use the Web entry point. Determine the port before starting: prefer the port explicitly specified by the user; otherwise check whether the default port is available and, if necessary, choose an available port. Do not hard-code the port in the Skill or promise the user an address that has not yet been confirmed. Run it in a background or persistent terminal session that can continuously read output and can return control to the Agent after startup:

deepresearch web "<query>" \
  --mode <normal|heavy> \
  --report-format <brief|formal_report> \
  --output-format <markdown|html|pdf|docx> \
  --harness <hermes|codex|claude-code|openclaw> \
  --language <user-language> \
  --host 127.0.0.1 \
  --port <selected-port> \
  --progress tools

Keep this process running and do not start a second identical research run. Wait for the SenseNova-Skills-DeepResearch logs to confirm that Web has started listening on the chosen port, then tell the user the actual address:

研究已经启动，可打开 http://127.0.0.1:<selected-port> 查看实时进度。

Replace <selected-port> with the port actually used in this run. Do not wait until the entire research is complete before replying to the user. If Web startup fails, report the startup error and do not provide an address that is not yet available.

Displaying a link does not mean forcing the browser to open; when GUI operations are needed, follow the authorization of the current environment. Use --host 0.0.0.0only when the user explicitly requests LAN access, and remind them that the run trace and report will be visible to the same network segment.

Harness/SenseNova-Skills-DeepResearch monitoring

After research starts, you must keep the Harness and SenseNova-Skills-DeepResearch monitoring processes used by this Run, and continuously observe their stdout/stderr, heartbeat, and deepresearch status <run-id> --json status. A long period without new output does not mean the process has failed: first read the status and recent logs, and do not repeatedly start the Harness, start a second SenseNova-Skills-DeepResearch, or terminate the existing process just because there is temporarily no output. When the monitoring session is interrupted, prefer reconnecting to the original process; only when it is confirmed that the original process has exited, the Run has ended, or the user explicitly requests a stop may you end monitoring or start a recovery command.

If monitoring finds a provider timeout, Harness exit, or Run failure, preserve the original process output and Run directory, explain to the user according to the "Model call timeout and recovery" process, and request authorization to modify the configuration; without authorization, do not restart, change the configuration, or start a new Harness in parallel.

Completion, failure, and recovery

Success: report run_id, run status, and output/<run-id>/ the final files in .
Failure or interruption: truthfully explain the failed node and retain runs/<run-id>/。
Recovery: after confirming the original process has ended, execute deepresearch resume <run-id> --harness <harness>。

Do not treat search hits or intermediate files as the final report, do not falsify completion status, and do not save user run records in the SenseNova-Skills-DeepResearch installation directory.

SenseNova-Skills-DeepResearch diagnostics

This section is used only after SenseNova-Skills-DeepResearch has been installed. Do not run the entire diagnostic set in advance during the normal research process; only when the user explicitly requests diagnostics, or when installation verification fails, Search is abnormal, Web is inaccessible, Run stops updating, a node fails, or the report is not generated, select the minimal read-only checks according to the current problem:

deepresearch --help
deepresearch diagnostics --json
deepresearch doctor --harness <harness> --json
deepresearch sources list --json
deepresearch domains list --json
deepresearch browser status --json
deepresearch status <run-id> --json
deepresearch resume --help
deepresearch web --help

When parameters are uncertain, first check the corresponding --help, and do not guess from memory.

Search abnormal: report only source availability and missing variable names.
Camofox unavailable: switch sources and continue the research, and do not let the workflow be blocked by this.
Run failed: retain the run records, and resume only after confirming the original process has ended.

When the above abnormalities occur, first execute deepresearch diagnostics --json, then fully read the SenseNova-Skills-DeepResearch built-in diagnostic manual pointed to by its path field. Do not infer the installation location of SenseNova-Skills-DeepResearch from the directory where the Skill is located, and do not read relative paths next to the Skill or in the source code repository.

Do not load the diagnostic manual during the normal process. If the command fails or the returned path does not exist, use the minimal read-only checks in this section and clearly state that the SenseNova-Skills-DeepResearch diagnostic manual is missing. Installation, configuration changes, service startup, and network operations in the diagnostic manual still need to comply with the authorization of the current environment; reading the manual itself does not expand the scope of user authorization.