前言¶

在 DeepSeek Harness（DSH）里做智能体开发时，若背后接的是 New API 一类网关，常见做法是手写 HTTP 调用、把 sk- 密钥和系统访问令牌塞进对话或环境变量，或在浏览器里反复切管理后台。管理接口与 OpenAI 兼容的 /v1/* 认证方式不同，混用容易把 AI 密钥打到管理路由上。

dsh-plugin-newapi 把网关上的常用操作做成 DSH 一等工具，并在 Web 的 设置 → New API 提供与 CLI 共用的站点与凭据配置。下面介绍它做什么、如何安装配置，以及典型调用顺序。

这是什么¶

维护者 zh-Littlebird 在 npm 发布包名 dsh-plugin-newapi（当前资料版本 1.2.1，MIT）。社区目录 SkillHub 将其归类为 admin-security。

插件定位：把 New API 的站点自检、模型列表、对话、向量、令牌、渠道、日志、系统设置，以及覆盖全部端点族的通用调用入口，封装为 9 个 Host 工具；凭据在本机加密存放或走环境变量，模型侧只看见「已配置 / 缺失」。通过 dsh.bundle.patch 安装，不改 Harness 核心，无前端构建步骤，运行时仅依赖 Node.js 标准库。

核心功能¶

工具与条件注册¶

未配置网关根地址（baseUrl）时，只有 newapi_site 会注册到模型上下文；其余 8 个工具通过 when 条件隐藏，避免每个会话为不可用工具付出上下文成本。配置完成后，下列工具可用：

认证与安全边界¶

/v1/* 只使用 sk- 开头的 AI 密钥；/api/* 只使用系统访问令牌，并配合管理头 New-Api-User。sk- 密钥不会被发送到管理接口。

AI 密钥与访问令牌由用户在本机用 CLI 录入，加密存放在 $DSH_HOME/newapi/credentials.json；工具参数里不出现明文凭据。返回结果对令牌 key、渠道 key、api_key、access_token、password 等字段统一掩码；审计日志记录动作与路径，不记录请求体。

Web 设置页¶

Host 侧半暴露工具，Web 侧在 设置 → New API 注册页面，读写同一份 site.json 与加密凭据库，并与 newapi_site action="test" 共用自检逻辑。设置页经插件自有的 /newapi 回环路由与宿主通信，仅接受本机地址；无浏览器的 headless 部署不会注册该路由，工具与 CLI 仍可用。

安装与启用¶

前置条件¶

• DeepSeek Harness 0.2.2-rc.1 或同系列 0.2.x（engines.dsh: >=0.2.2-rc.1 <0.3.0）
• Node.js >= 22.19（推荐 24）
• 可访问的 New API 站点；管理接口需要 Admin/Root 账号的系统访问令牌

安装到 profile¶

在 profile 中安装插件包（也可传本地目录绝对路径，由包管理器建立 link）：

dsh plugin --profile desktop add dsh-plugin-newapi

dsh --profile desktop --dump-config | Select-String newapi

也可在 Web 的 Plugins 页面安装，或由 Agent 调用 plugin_manager 的 install_bundle，target 传包名 dsh-plugin-newapi 或本地目录绝对路径。

安装或更新 Host 插件后需重启 Harness 进程，新的 newapi_* 工具才会出现在模型中。

配置¶

用 CLI 写入站点与凭据（推荐）¶

在自己的终端执行，勿在对话里向模型发送密钥。进入插件目录后：

cd "dsh-plugin-newapi"

node scripts/dsh-newapi.mjs setup --base-url 192.0.2.10:3000 --user-id 1
node scripts/dsh-newapi.mjs set --api-key
node scripts/dsh-newapi.mjs set --access-token
node scripts/dsh-newapi.mjs status

setup 写入网关根地址（不要带 /v1 或 /api）；set --api-key 录入 sk- 密钥；set --access-token 录入个人设置 → 安全 → 系统访问令牌；status 只显示 available/missing。

默认数据目录为 $DSH_HOME/newapi/，含 site.json、credentials.json（AES-256-GCM）、master.key、audit.log 及新建令牌时的一次性明文文件目录 issued/。可用 --data-dir 或环境变量 DSH_NEWAPI_DATA_DIR 修改路径。

环境变量与插件键¶

也可将配置放进 Harness 进程环境变量：

$env:NEWAPI_BASE_URL = "https://api.example.com"
$env:NEWAPI_API_KEY = "sk-..."
$env:NEWAPI_ACCESS_TOKEN = "..."
$env:NEWAPI_USER_ID = "1"

cordis.patch.yml 中常见项包括：baseUrl、userId、apiKeyEnv（默认 NEWAPI_API_KEY）、accessTokenEnv（默认 NEWAPI_ACCESS_TOKEN）、secretsBackend（auto / env / file / none）、timeoutMs（默认 120000）、maxResponseBytes（默认 8388608）、allowManagementWrites、audit、debug。优先级为：显式插件配置 > 环境变量 > site.json。

Web 设置 → New API 可完成与 CLI 等价的网关地址、用户 ID 与凭据写入，并支持测试连接；地址末尾的 /v1、/api 等会被自动规范化。

典型用法¶

资料中的推荐顺序如下：

newapi_site { action: "test" }
newapi_models
newapi_chat { model: "gpt-4o-mini", messages: [...] }
newapi_tokens { action: "list", keyword: "my-app" }
newapi_tokens { action: "create", name: "my-app-v2", modelLimits: ["gpt-4o-mini"] }
newapi_tokens { action: "delete", id: 7, confirm: true }

先用 newapi_site 自检网关可达性、管理令牌与 AI 密钥能否列模型；再用 newapi_models 确认模型名，避免猜错 gpt-4o 与带前缀名称的差异。创建令牌时默认 delivery="file"：完整密钥写入 $DSH_HOME/newapi/issued/ 下文件，工具结果只给掩码与 keyFile 路径，避免密钥进入会话记录。

管理写操作通过 newapi_raw 时必须 confirm=true，并受 allowManagementWrites 约束；重定向一律拒绝，避免 Authorization 被转发到其他站点。

适用场景与注意¶

适合在 DSH 会话中需要反复查询模型、试对话、管令牌与渠道、看日志或读系统选项，又不想每次复制 curl 或暴露密钥的开发者与运维。也适合希望用 Web 设置页与 Agent 工具共用一套配置的团队。

务必注意：插件以当前 dsh 进程的用户与权限运行，管理写操作（令牌删除、渠道测试、newapi_raw 写请求等）具备与该进程等同的访问能力。安装前应阅读 GitHub 仓库 源码与 MIT 许可证，确认符合本机安全策略。DSH 生态强调「一切皆插件」；SkillHub 为社区目录，与 DeepSeek / 幻方无官方从属关系。

排障时可对照资料中的现象表：例如 CONFIG_MISSING 表示缺 baseUrl 或凭据；AI 与管理路由的 HTTP_401 含义不同；「无可用渠道」需结合令牌分组、渠道与 newapi_models 依次核对。

结尾¶

dsh-plugin-newapi 把 New API 的管理面与推理面拆清认证路径，用 9 个工具和一个设置页覆盖日常网关操作，并在未配置时尽量不占用模型上下文。进一步了解可访问目录页 zh-Littlebird/dsh-plugin-newapi 与源码 github.com/zh-Littlebird/dsh-plugin-newapi。