dsh-brave-search

dsh-brave-search 是一个可安装的 DeepSeek Harness 原生 bundle，注册统一的 brave_search 工具，调用 Brave Search API 的 Web、News、Image、Video 和 LLM Context 五类 GET 服务。

安装：用户只需一条命令

先在 Brave API 控制台创建一个 key。安装命令会把插件加入官方默认的 web profile；这里的 web 是 profile 名称，不是插件名称。如果你使用自定义 profile（例如 demo），请将命令中的 web 替换为该 profile 名称。

macOS（默认 zsh）

下面这一整行适用于 macOS 默认终端，可以直接复制粘贴。它会隐藏输入 key、持久写入 Harness 会自动读取的 ~/.env，安装插件并启动 dsh。这个 key 不会出现在命令历史中：

umask 077; read -rs "BRAVE_SEARCH_API_KEY?Brave API key: "; printf '\n'; if [ -e "$HOME/.env" ] && [ ! -f "$HOME/.env" ]; then printf '%s\n' "$HOME/.env exists but is not a regular file; rename or remove that directory first." >&2; unset BRAVE_SEARCH_API_KEY; else touch "$HOME/.env" && sed -i '' '/^BRAVE_SEARCH_API_KEY=/d' "$HOME/.env" && printf 'BRAVE_SEARCH_API_KEY=%s\n' "$BRAVE_SEARCH_API_KEY" >> "$HOME/.env" && unset BRAVE_SEARCH_API_KEY && (dsh plugin --profile web remove dsh-brave-search >/dev/null 2>&1 || true) && dsh plugin --profile web add github:high0/dsh-brave-search && npx @deepseek-ai/dsh web; fi

Linux（默认 bash）

Linux 默认通常是 bash，不能使用上面的 zsh read 语法；请使用这一整行：

umask 077; read -r -s -p 'Brave API key: ' BRAVE_SEARCH_API_KEY; printf '\n'; if [ -e "$HOME/.env" ] && [ ! -f "$HOME/.env" ]; then printf '%s\n' "$HOME/.env exists but is not a regular file; rename or remove that directory first." >&2; unset BRAVE_SEARCH_API_KEY; else touch "$HOME/.env" && sed -i '/^BRAVE_SEARCH_API_KEY=/d' "$HOME/.env" && printf 'BRAVE_SEARCH_API_KEY=%s\n' "$BRAVE_SEARCH_API_KEY" >> "$HOME/.env" && unset BRAVE_SEARCH_API_KEY && (dsh plugin --profile web remove dsh-brave-search >/dev/null 2>&1 || true) && dsh plugin --profile web add github:high0/dsh-brave-search && npx @deepseek-ai/dsh web; fi

macOS 使用 BSD sed，所以是 sed -i ''；Linux 使用 GNU sed，所以是 sed -i。如果 Linux 用户使用 zsh，仍需使用 Linux 版本的 sed -i。

Windows PowerShell

Windows CMD 和 PowerShell 不能直接运行上面的 Unix shell 命令。PowerShell 请复制执行下面这一段；它会隐藏输入 key、写入 Windows 用户目录下的 .env，然后安装并启动 web profile：

$envFile = Join-Path $HOME ".env"

if (Test-Path -LiteralPath $envFile -PathType Container) {
    throw "$envFile exists as a directory; rename or remove it first."
}

$secureKey = Read-Host "Brave API key" -AsSecureString
$keyPtr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secureKey)

try {
    $apiKey = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($keyPtr)
}
finally {
    [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($keyPtr)
}

if (Test-Path -LiteralPath $envFile) {
    $lines = @(Get-Content -LiteralPath $envFile | Where-Object {
        $_ -notmatch '^BRAVE_SEARCH_API_KEY='
    })
}
else {
    $lines = @()
}

[IO.File]::WriteAllLines(
    $envFile,
    [string[]]($lines + "BRAVE_SEARCH_API_KEY=$apiKey"),
    [Text.UTF8Encoding]::new($false)
)

Remove-Variable apiKey -ErrorAction SilentlyContinue

dsh plugin --profile web remove dsh-brave-search *> $null
dsh plugin --profile web add github:high0/dsh-brave-search
npx @deepseek-ai/dsh web

Windows 用户如果使用 WSL 或 Git Bash，应在对应的 Unix 环境中使用 Linux 版本；此时写入的是 WSL/Git Bash 的用户目录，而不是 Windows 原生用户目录。

上面的命令要求 ~/.env（Windows 下为用户目录中的 .env）是普通文件而不是目录，并会替换已有的 BRAVE_SEARCH_API_KEY 行。如果只想临时使用，也可以执行 export BRAVE_SEARCH_API_KEY="你的 Brave API key"（PowerShell 使用 $env:BRAVE_SEARCH_API_KEY="你的 Brave API key"）；这种方式只对当前终端有效，关闭终端后不会保留。命令中的 BRAVE_SEARCH_API_KEY 和 $HOME/.env 不要写成带反斜杠的 BRAVE\_SEARCH\_API\_KEY 或 \~/.env，否则 shell 可能无法正确识别变量或路径。

然后直接从 GitHub 安装已构建的 bundle（不需要 clone、npm install、编译或手动编辑 profile 文件）。如果你按官方命令运行 npx @deepseek-ai/dsh web，目标 profile 是 web：

dsh plugin --profile web add github:high0/dsh-brave-search

安装完成后启动 profile：

npx @deepseek-ai/dsh web

如果 profile 已经在运行，必须重启一次让新的后端 bundle 生效。上面的 add 命令会自动初始化 profile、安装依赖、登记 dsh-brave-search 配置层并加载 brave_search 工具。安装完成后不依赖本地源码目录，可以删除 clone 出来的仓库目录。

也可以把 web profile 的安装和启动写成一条命令（前提是已经通过 ~/.env 或当前终端设置了 BRAVE_SEARCH_API_KEY）：

dsh plugin --profile web add github:high0/dsh-brave-search && npx @deepseek-ai/dsh web

这里的 web 是 DeepSeek Harness 官方默认 profile 名称；demo 只是自定义 profile 的示例名称，不是插件要求的固定名称。插件是后端工具 bundle，不提供浏览器端 client.js，因此不会出现在页面启动资源清单中；重启对应 profile 后，工具 brave_search 才会注册到 Harness。

环境变量 BRAVE_SEARCH_API_KEY 始终优先于 profile 配置中的 apiKey。密钥不会被写入 URL、工具结果或错误消息。

固定版本（生产环境推荐）

如果希望后续仓库更新不会改变已安装代码，可以锁定一个完整 commit SHA（不要使用可能无法被 Git 远端解析的短 SHA）：

dsh plugin --profile web add github:high0/dsh-brave-search#ac7ac583cc47df09aa0a972b5068bc04c01c2295

更新插件时再次执行 add 并指定新的 commit；卸载使用：

dsh plugin --profile web remove dsh-brave-search

工具调用

{
  "service": "web",
  "query": "DeepSeek Harness plugin development",
  "params": {
    "country": "US",
    "search_lang": "en",
    "count": 10,
    "freshness": "pw"
  }
}

工具返回 Brave 原始 JSON。service 可选 web、news、image、video 或 llm_context。query 不能为空，最多 400 个字符、50 个单词。调用参数会覆盖相同服务的配置默认值。

支持的参数：

• Web / News / Video：country、search_lang、ui_lang、count、offset、freshness、safesearch、spellcheck、extra_snippets、goggles
• Image：country、search_lang、count、safesearch、spellcheck
• LLM Context：country、search_lang、count、freshness、maximum_number_of_urls、maximum_number_of_tokens、maximum_number_of_snippets、maximum_number_of_tokens_per_url、maximum_number_of_snippets_per_url、context_threshold_mode、safesearch、enable_local、enable_rich_callback

常用枚举和范围会在调用前校验：safesearch 为 off、moderate、strict；freshness 支持 pd、pw、pm、py 或官方日期区间格式；计数和限制参数必须是整数并位于 Brave 官方支持范围内。未知参数会直接拒绝。

故障排查

• dsh: failed to load .env: EISDIR：这不是插件错误。Harness 会自动读取用户目录下的 ~/.env 文件；如果该路径被其他程序用作目录（例如 Python 虚拟环境），就会出现此错误。请先退出正在使用该目录的程序，再将目录改名为其他名称，例如 mv ~/.env ~/.python-env，然后重新执行 npx @deepseek-ai/dsh web。如果你确实需要环境文件，应创建普通文件 ~/.env，每行使用 KEY=value 格式。
• MISSING_API_KEY：设置 BRAVE_SEARCH_API_KEY，或在插件配置中提供 apiKey。
• INVALID_PARAMS / INVALID_QUERY：检查服务对应的参数名、枚举和数值边界。
• TIMEOUT / CANCELLED：检查网络、timeoutMs 和调用方取消信号。
• HTTP_ERROR：Brave 返回了非 2xx；错误中会保留状态码和安全摘要。请查看 Brave 控制台中的配额、计费和限流状态。

llm_context 适合把检索内容直接作为模型上下文；普通 web 搜索适合需要完整搜索结果字段的场景。本 bundle 只使用官方 GET API，不下载图片、不抓取页面，也不实现 Brave Answers、Places 或 LLM Context POST 变体。

开发与测试

npm install
npm run typecheck
npm test
npm run build
npm pack --dry-run

真实 API 测试默认跳过；同时设置 BRAVE_SEARCH_API_KEY 和 BRAVE_SEARCH_SMOKE=1 后运行 npm run test:smoke。不要把 key 写入仓库或 CI 日志。