前言¶

DeepSeek Harness（DSH）把智能体、工具链和 Web 服务收进同一套 profile 里跑。若你已有基于 OpenAI SDK 或 /v1/chat/completions 的客户端，却希望请求真正落在 DSH 的 agent 会话上——带工具、bash、skills 和 preset，而不是单独再挂一层「只转发 token」的 LLM 网关——就需要在 harness 的 webServer 上增加一层 OpenAI 兼容面。

社区插件 dsh-openai-api（维护者 huyang2024）做这件事：安装到 profile 后，在现有 web 服务上额外提供 POST /v1/chat/completions、POST /v1/responses 与 GET /v1/models，底层由 真实的 DSH agent 会话 处理，而不是薄代理。

这是什么¶

dsh-openai-api 是 DSH 的 bundle 型插件（npm 包名 dsh-openai-api，当前资料中版本 0.2.0，MIT 许可证）。它在 DeepSeek Harness 的 webServer 与 llm runtime 之上，挂载 OpenAI 风格的 HTTP API；分类上属于 模型推理。目录页：skillhub.cn/plugins/huyang2024/dsh-openai-api；源码：github.com/huyang2024/dsh-openai-api。

核心功能¶

暴露的端点¶

「agent-backed」的含义¶

每次请求由 活跃的 DSH agent 会话（harness 的 agents 注册表与 agent loop）承接，因此调用方得到的是该 agent 的完整环境：已配置工具、bash/文件访问、skills、prompt 片段与 preset 人设。README 将其定位为 agent gateway，而非薄 LLM 代理：

1. 工具由 agent 决定：客户端传入的 tools、tool_choice、function-call 类消息会被拒绝；是否调用工具、调用哪些，由 agent 自行判断。
2. 流式粒度：流式 delta 按 已提交的 assistant 消息 推送，而非按 token；推理过程、工具调用与 token 级 chunk 不会出现在链路上，客户端只看到已提交的 assistant 文本。
3. 会话种子与续聊：同一 (key, preset) 的 首次 请求会把客户端完整 messages 渲染成带标签的 transcript 以初始化会话；后续请求只接受 最新一轮 user（历史已在会话内）。

会话标识¶

会话维度为 (API key 租户, X-Agent-Preset)：

• apiKey 区分调用方：每个 key 独立会话，不同 key 即使用相同 preset 也不共享；客户端重连时恢复自己的会话。
• X-Agent-Preset 请求头 指定加入的 preset（省略则用 profile 默认）；仅在 创建会话时 解析。

/v1/responses 同样绑定上述会话模型；previous_response_id 会被接受但 忽略（粘性会话即存储）。

安装与启用¶

从 GitHub 安装到 web profile：

dsh plugin --profile web add github:huyang2024/dsh-openai-api

或从本地目录安装（路径改为你的绝对路径）：

dsh plugin --profile web add file:/absolute/path/to/dsh-openai-api

包声明了 DSH bundle，新装入 profile 时会自动贡献 openai-api 组件，无需 手工写 insert:。安装后 重启 profile 生效。

DSH Desktop：需先初始化应用并完全退出；用桌面应用自带的 dsh（通过 Manage dsh Command… 注册），将上述命令中的 --profile web 换成 --profile desktop。npm 全局安装的 CLI 不能 管理 desktop profile。也可在桌面 Plugins 页用 GitHub 规格或本地绝对路径安装，并选择 Enable now。Desktop 默认 HTTP 端口 动态分配（不是固定的 3080），请以实际监听地址作为 API baseURL；GET /v1/models 可在不调用模型的前提下确认插件已运行。

若曾安装旧 scoped 包，需先卸载再装本包。更早版本若仅作为依赖且无 bundle 声明，更新后需在 Plugins 页启用，或把 dsh-openai-api 加入 profile package.json 的 dsh.profile.bundles 数组；若 profile 里仍有手工 insert: 的 openai-api，应改为在用户 patch 层用 id/config 覆盖（见下节），保留原有配置值。

配置¶

在 profile 用户 patch 层编辑，例如 web：$DSH_HOME/profiles/web/cordis.patch.yml（Desktop 为 profiles/desktop/cordis.patch.yml）：

- id: openai-api
  config:
    pathPrefix: '/v1'     # optional, default shown
    apiKeys: []           # optional; see below
    model: default        # optional; model id advertised at /v1/models
    provider: ''          # optional; provider route for created sessions
    cwd: ''               # optional; absolute working directory for sessions

修改后 重启 profile。各键均可选，未设则回退 host 默认。

典型用法¶

web profile 默认示例基址为 http://127.0.0.1:3080/v1（Desktop 请换成实际端口）。可选 preset 头：

import OpenAI from 'openai'
const client = new OpenAI({ baseURL: 'http://127.0.0.1:3080/v1', apiKey: 'local-key' })

// Optional: choose the agent preset the session joins (absent → default preset).
const preset = { 'X-Agent-Preset': 'custom-agent-preset' }

const reply = await client.chat.completions.create(
  { model: 'default', messages: [{ role: 'user', content: 'What are you?' }] },
  { headers: preset },
)

认证与信任边界¶

1. 配置了 apiKeys 时，须精确匹配 Authorization: Bearer <key>，匹配到的 key 即租户。
2. 未配置 apiKeys 时，仅服务 loopback 调用方（相对参考实现刻意收紧，避免误绑 LAN 导致未鉴权的 agent 暴露）。
3. 浏览器跨域：除非来源在 allowedOrigins 中，或携带有效 key，否则拒绝；三条路径均响应预检 OPTIONS。

适用场景与注意¶

适合：已有 OpenAI SDK 或兼容客户端，希望把流量接到 DSH agent（工具、文件、skills、preset 一体），而不是再维护单独 LLM 反向代理的团队。

务必注意：

1. 插件与当前 dsh 进程同权限 运行；agent 能执行的 bash/文件操作即该进程权限。安装前请阅读 源码与 MIT 许可证，自行评估信任边界。
2. 不要指望客户端侧 OpenAI tools 参数驱动工具链；行为由 DSH agent 定义。
3. 流式输出不是 token 流，对接现有「打字机」UI 时需按 消息提交 粒度处理。
4. 社区目录 skillhub.cn 为独立生态站点，与 DeepSeek / 幻方无官方从属关系；插件维护者为社区贡献者 huyang2024。

结尾¶

dsh-openai-api 在 DSH webServer 上补齐 OpenAI 兼容三端点，并把每次调用绑到真实 agent 会话与 (key, preset) 粘性会话模型。安装、配置与示例以 README 为准；进一步细节见 目录页 与 GitHub 仓库。