Lumoswitch 文档
Agent 接入

DeepSeek Harness 接入

DeepSeek Harness（dsh）是 DeepSeek 开源的 Agent Harness，当前处于 Developer Preview。它通过插件组合 Agent、模型、工具和 Web UI，并支持把自定义 OpenAI-compatible 网关声明为模型提供方。

开始前请安装 Node.js，并在 Lumoswitch 中创建启用 OpenAI-compatible 输出的配置 API。命令通过官方 npx @deepseek-ai/dsh web 入口启动本机 Web UI。

方式总览

方式适合什么情况会写入什么退出后是否保留
仅本次启动临时测试地址、Key 和模型目录临时 Lumoswitch overlay；Harness 正常运行数据除外否
永久使用日常从同一入口启动本机 Web UI原生 DSH Home 与可选维护启动器是

两种方式都不会覆盖 $DSH_HOME/settings.yaml、默认 profile patch 或已有 provider。永久方式把 Access Key 保存在专属 DSH Home 中仅当前用户可读的 .env 文件里。

准备连接信息

占位符应填写的内容
{{api_base_url}}配置 API 的 OpenAI-compatible 地址，应包含 /v1
{{access_key}}当前配置使用的 Lumoswitch Access Key
{{model}}默认选择的下游模型名称
{{deepseek_harness_models_yaml}}全部下游模型及其有效推理能力生成的 Harness YAML 模型列表

控制台会把全部下游模型写入 overlay。只有传输方式已经确认的推理档位才会发布给 Harness；不支持推理的模型会显式关闭推理控制，固定或未知能力不会被猜测。

仅本次启动

在希望作为默认工作区的项目目录运行。临时目录只保存本次 Lumoswitch overlay，进程退出后自动删除：

(
  set -e
  LUMOSWITCH_DSH_TMP="$(mktemp -d "${TMPDIR:-/tmp}/lumoswitch-dsh.XXXXXX")"
  LUMOSWITCH_DSH_PATCH="$LUMOSWITCH_DSH_TMP/lumoswitch.cordis.yml"
  trap 'rm -f "$LUMOSWITCH_DSH_PATCH"; rmdir "$LUMOSWITCH_DSH_TMP" 2>/dev/null || true' EXIT
  cat > "$LUMOSWITCH_DSH_PATCH" <<'LUMOSWITCH_DSH_PATCH_EOF'
- id: agent-default-model
  config:
    provider: lumoswitch
    model: "{{model}}"
- id: llm-pi-ai
  config:
    providers:
      lumoswitch:
        displayName: Lumoswitch
        apiKeyEnv: LUMOSWITCH_DEEPSEEK_API_KEY
        api: openai-completions
        baseURL: "{{api_base_url}}"
        models:
{{deepseek_harness_models_yaml}}LUMOSWITCH_DSH_PATCH_EOF
  chmod 600 "$LUMOSWITCH_DSH_PATCH"
  env \
    LUMOSWITCH_DEEPSEEK_API_KEY="{{access_key}}" \
    npx @deepseek-ai/dsh web --patch "$LUMOSWITCH_DSH_PATCH"
)

终端会输出本机 Web UI 地址，默认是 http://127.0.0.1:3080。首次打开后选择当前工作区即可开始会话。Harness 自身仍会正常初始化 profile、保存会话并使用 npm 缓存；本命令只保证 Lumoswitch overlay 和进程环境中的 Key 不会在退出后保留。

永久使用

首次设置，或 Lumoswitch 地址、Access Key、模型发生变化时，运行下面的完整命令。它会写入专属原生 DSH Home 和可选维护启动器，并在更新前保留权限为 0600 的时间戳备份。

set -e
LUMOSWITCH_ROOT="$HOME/.config/lumoswitch/agents/deepseek-harness"
LUMOSWITCH_ENV="$LUMOSWITCH_ROOT/env.sh"
LUMOSWITCH_LAUNCHER="$HOME/.local/bin/lumoswitch-deepseek-harness"
mkdir -p "$LUMOSWITCH_ROOT" "$(dirname "$LUMOSWITCH_LAUNCHER")"
umask 077

if [ -f "$LUMOSWITCH_LAUNCHER" ]; then
  LUMOSWITCH_BACKUP="$LUMOSWITCH_LAUNCHER.backup.$(date +%Y%m%d-%H%M%S)-$$"
  cp "$LUMOSWITCH_LAUNCHER" "$LUMOSWITCH_BACKUP"
  chmod 600 "$LUMOSWITCH_BACKUP"
fi

LUMOSWITCH_DSH_HOME="$LUMOSWITCH_ROOT/dsh-home"
mkdir -p "$LUMOSWITCH_DSH_HOME"
cat > "$LUMOSWITCH_DSH_HOME/cordis.patch.yml" <<'LUMOSWITCH_CONFIG_EOF'
- id: agent-default-model
  config:
    provider: lumoswitch
    model: "{{model}}"
- id: llm-pi-ai
  config:
    providers:
      lumoswitch:
        displayName: Lumoswitch
        apiKeyEnv: LUMOSWITCH_DEEPSEEK_API_KEY
        api: openai-completions
        baseURL: "{{api_base_url}}"
        models:
{{deepseek_harness_models_yaml}}LUMOSWITCH_CONFIG_EOF
cat > "$LUMOSWITCH_DSH_HOME/.env" <<'LUMOSWITCH_ENV_EOF'
LUMOSWITCH_DEEPSEEK_API_KEY={{access_key}}
LUMOSWITCH_ENV_EOF

cat > "$LUMOSWITCH_ENV" <<'LUMOSWITCH_ENV_EOF'
export DSH_HOME="$HOME/.config/lumoswitch/agents/deepseek-harness/dsh-home"
LUMOSWITCH_ENV_EOF

case "$SHELL" in
  */zsh) LUMOSWITCH_PROFILE="$HOME/.zshrc" ;;
  */bash) LUMOSWITCH_PROFILE="$HOME/.bashrc" ;;
  *) LUMOSWITCH_PROFILE="$HOME/.profile" ;;
esac
touch "$LUMOSWITCH_PROFILE"
LUMOSWITCH_PROFILE_MARKER='# Lumoswitch Agent: deepseek-harness'
LUMOSWITCH_SOURCE_LINE='[ -f "$HOME/.config/lumoswitch/agents/deepseek-harness/env.sh" ] && . "$HOME/.config/lumoswitch/agents/deepseek-harness/env.sh"'
if ! grep -Fqx "$LUMOSWITCH_SOURCE_LINE" "$LUMOSWITCH_PROFILE"; then
  printf '\n%s\n%s\n' "$LUMOSWITCH_PROFILE_MARKER" "$LUMOSWITCH_SOURCE_LINE" >> "$LUMOSWITCH_PROFILE"
fi
printf '%s\n' "$LUMOSWITCH_PROFILE" > "$LUMOSWITCH_ROOT/profile-path"

cat > "$LUMOSWITCH_LAUNCHER" <<'LUMOSWITCH_LAUNCHER_EOF'
#!/usr/bin/env bash
set -e
LUMOSWITCH_ROOT="$HOME/.config/lumoswitch/agents/deepseek-harness"
LUMOSWITCH_ENV="$LUMOSWITCH_ROOT/env.sh"
LUMOSWITCH_LAUNCHER="$HOME/.local/bin/lumoswitch-deepseek-harness"

if [ "$1" = "--lumoswitch-clean" ]; then
  if [ -f "$LUMOSWITCH_ROOT/profile-path" ]; then
    LUMOSWITCH_PROFILE="$(cat "$LUMOSWITCH_ROOT/profile-path")"
    if [ -f "$LUMOSWITCH_PROFILE" ]; then
      LUMOSWITCH_PROFILE_MARKER='# Lumoswitch Agent: deepseek-harness'
      LUMOSWITCH_SOURCE_LINE='[ -f "$HOME/.config/lumoswitch/agents/deepseek-harness/env.sh" ] && . "$HOME/.config/lumoswitch/agents/deepseek-harness/env.sh"'
      LUMOSWITCH_PROFILE_TMP="$LUMOSWITCH_PROFILE.lumoswitch.$$"
      awk -v marker="$LUMOSWITCH_PROFILE_MARKER" -v source="$LUMOSWITCH_SOURCE_LINE" '$0 != marker && $0 != source' "$LUMOSWITCH_PROFILE" > "$LUMOSWITCH_PROFILE_TMP"
      mv "$LUMOSWITCH_PROFILE_TMP" "$LUMOSWITCH_PROFILE"
    fi
  fi
  if [ -d "$LUMOSWITCH_ROOT" ]; then
    find "$LUMOSWITCH_ROOT" -depth \( -type f -o -type l \) -delete
    find "$LUMOSWITCH_ROOT" -depth -type d -exec rmdir {} \; 2>/dev/null || true
  fi
  find "$(dirname "$LUMOSWITCH_LAUNCHER")" -maxdepth 1 -type f -name 'lumoswitch-deepseek-harness.backup.*' -delete
  rm -f "$LUMOSWITCH_LAUNCHER"
  printf '%s\n' 'Lumoswitch native setup and optional launcher removed. Open a new terminal to refresh the environment.'
  exit 0
fi

if [ -f "$LUMOSWITCH_ENV" ]; then . "$LUMOSWITCH_ENV"; fi
exec npx @deepseek-ai/dsh web "$@"
LUMOSWITCH_LAUNCHER_EOF

chmod 600 "$LUMOSWITCH_ENV"
find "$LUMOSWITCH_ROOT" -type f -exec chmod 600 {} \;
chmod 700 "$LUMOSWITCH_LAUNCHER"
. "$LUMOSWITCH_ENV"
printf '%s\n' 'Native Lumoswitch setup saved. Future command: npx @deepseek-ai/dsh web'
printf '%s\n' 'Optional maintenance launcher: ~/.local/bin/lumoswitch-deepseek-harness'
npx @deepseek-ai/dsh web

以后在任意项目目录运行：

npx @deepseek-ai/dsh web

调用目录会成为默认工作区位置。也可以继续传入 Web 参数，例如 npx @deepseek-ai/dsh web --port 3081。

Windows PowerShell 原生导入

以下命令在 Windows PowerShell 中原生运行，不需要 WSL。它们与本页的 macOS/Linux 模板使用同一组连接值。

仅本次使用（Windows）

& {
  $ErrorActionPreference = 'Stop'
  $lumoswitchConfig = Join-Path ([IO.Path]::GetTempPath()) ('lumoswitch-' + [Guid]::NewGuid().ToString('N') + '.yml')
  $lumoswitchConfigContent = @'
- id: agent-default-model
  config:
    provider: lumoswitch
    model: "{{model}}"
- id: llm-pi-ai
  config:
    providers:
      lumoswitch:
        displayName: Lumoswitch
        apiKeyEnv: LUMOSWITCH_DEEPSEEK_API_KEY
        api: openai-completions
        baseURL: "{{api_base_url}}"
        models:
{{deepseek_harness_models_yaml}}
'@
  [IO.File]::WriteAllText($lumoswitchConfig, $lumoswitchConfigContent, [Text.UTF8Encoding]::new($false))
  $lumoswitchEnvironmentNames = @('LUMOSWITCH_DEEPSEEK_API_KEY')
  $lumoswitchPreviousEnvironment = @{}
  foreach ($lumoswitchName in $lumoswitchEnvironmentNames) {
    $lumoswitchPreviousEnvironment[$lumoswitchName] = [Environment]::GetEnvironmentVariable($lumoswitchName, 'Process')
  }
  $lumoswitchExitCode = 0
  try {
    [Environment]::SetEnvironmentVariable('LUMOSWITCH_DEEPSEEK_API_KEY', '{{access_key}}', 'Process')
    $lumoswitchArguments = @('@deepseek-ai/dsh', 'web', '--patch', $lumoswitchConfig)
    $lumoswitchExecutable = Get-Command 'npx.cmd' -CommandType Application -ErrorAction SilentlyContinue
    if ($null -eq $lumoswitchExecutable) { $lumoswitchExecutable = Get-Command 'npx' -CommandType Application -ErrorAction Stop }
    & $lumoswitchExecutable.Path @lumoswitchArguments
    if ($null -ne $LASTEXITCODE) { $lumoswitchExitCode = $LASTEXITCODE }
  } finally {
    foreach ($lumoswitchName in $lumoswitchEnvironmentNames) {
      [Environment]::SetEnvironmentVariable($lumoswitchName, $lumoswitchPreviousEnvironment[$lumoswitchName], 'Process')
    }
    Remove-Item -LiteralPath $lumoswitchConfig -Force -ErrorAction SilentlyContinue
  }
  if ($lumoswitchExitCode -ne 0) { throw 'npx exited with code ' + $lumoswitchExitCode }
}

永久使用（Windows）

该命令会备份已有的 Lumoswitch 专用文件，并为配置和启动器收紧当前用户的访问权限。

& {
  $ErrorActionPreference = 'Stop'
  $lumoswitchRoot = Join-Path $env:LOCALAPPDATA 'Lumoswitch\agents\deepseek-harness'
  $lumoswitchLauncher = Join-Path $env:LOCALAPPDATA 'Lumoswitch\bin\lumoswitch-deepseek-harness.ps1'
  $lumoswitchBackupSuffix = (Get-Date -Format 'yyyyMMdd-HHmmss') + '-' + $PID

  function Protect-LumoswitchFile([string] $Path) {
    $lumoswitchSid = [Security.Principal.WindowsIdentity]::GetCurrent().User.Value
    & icacls.exe $Path '/inheritance:r' '/grant:r' ('*' + $lumoswitchSid + ':(F)') '*S-1-5-18:(F)' '*S-1-5-32-544:(F)' | Out-Null
    if ($LASTEXITCODE -ne 0) { throw "Could not restrict access to $Path" }
  }

  function Install-LumoswitchFile([string] $Path, [string] $Content) {
    [IO.Directory]::CreateDirectory((Split-Path -Parent $Path)) | Out-Null
    if (Test-Path -LiteralPath $Path) {
      $lumoswitchItem = Get-Item -LiteralPath $Path -Force
      if ($lumoswitchItem.PSIsContainer -or ($lumoswitchItem.Attributes -band [IO.FileAttributes]::ReparsePoint)) {
        throw "Lumoswitch refused to replace a directory or link: $Path"
      }
      $lumoswitchBackup = $Path + '.backup.' + $lumoswitchBackupSuffix
      Copy-Item -LiteralPath $Path -Destination $lumoswitchBackup
      Protect-LumoswitchFile $lumoswitchBackup
    }
    $lumoswitchTemporary = $Path + '.' + [Guid]::NewGuid().ToString('N') + '.tmp'
    try {
      [IO.File]::WriteAllText($lumoswitchTemporary, $Content, [Text.UTF8Encoding]::new($false))
      Move-Item -LiteralPath $lumoswitchTemporary -Destination $Path -Force
      Protect-LumoswitchFile $Path
    } finally {
      Remove-Item -LiteralPath $lumoswitchTemporary -Force -ErrorAction SilentlyContinue
    }
  }

  [IO.Directory]::CreateDirectory($lumoswitchRoot) | Out-Null
  $lumoswitchDshHome = Join-Path $lumoswitchRoot 'dsh-home'
  $lumoswitchPatch = Join-Path $lumoswitchDshHome 'cordis.patch.yml'
  $lumoswitchEnv = Join-Path $lumoswitchDshHome '.env'
  $lumoswitchPatchContent = @'
- id: agent-default-model
  config:
    provider: lumoswitch
    model: "{{model}}"
- id: llm-pi-ai
  config:
    providers:
      lumoswitch:
        displayName: Lumoswitch
        apiKeyEnv: LUMOSWITCH_DEEPSEEK_API_KEY
        api: openai-completions
        baseURL: "{{api_base_url}}"
        models:
{{deepseek_harness_models_yaml}}
'@
  Install-LumoswitchFile $lumoswitchPatch $lumoswitchPatchContent
  Install-LumoswitchFile $lumoswitchEnv 'LUMOSWITCH_DEEPSEEK_API_KEY={{access_key}}'

  $lumoswitchEnvironment = [ordered]@{}
  $lumoswitchEnvironment['DSH_HOME'] = (Join-Path $lumoswitchRoot 'dsh-home')
  foreach ($lumoswitchEntry in $lumoswitchEnvironment.GetEnumerator()) {
    [Environment]::SetEnvironmentVariable($lumoswitchEntry.Key, $lumoswitchEntry.Value, 'User')
    [Environment]::SetEnvironmentVariable($lumoswitchEntry.Key, $lumoswitchEntry.Value, 'Process')
  }

  $lumoswitchLauncherContent = @'
param([Parameter(ValueFromRemainingArguments = $true)][string[]] $AgentArgs)
$ErrorActionPreference = 'Stop'
$lumoswitchRoot = Join-Path $env:LOCALAPPDATA 'Lumoswitch\agents\deepseek-harness'
$lumoswitchLauncher = Join-Path $env:LOCALAPPDATA 'Lumoswitch\bin\lumoswitch-deepseek-harness.ps1'

function Remove-LumoswitchFile([string] $Path) {
  if (-not (Test-Path -LiteralPath $Path)) { return }
  $lumoswitchItem = Get-Item -LiteralPath $Path -Force
  if ($lumoswitchItem.PSIsContainer -or ($lumoswitchItem.Attributes -band [IO.FileAttributes]::ReparsePoint)) {
    throw "Lumoswitch refused to remove a directory or link: $Path"
  }
  Remove-Item -LiteralPath $Path -Force
}

if ($AgentArgs.Count -gt 0 -and $AgentArgs[0] -eq '--lumoswitch-clean') {
  foreach ($lumoswitchName in @('DSH_HOME')) {
    [Environment]::SetEnvironmentVariable($lumoswitchName, $null, 'User')
    [Environment]::SetEnvironmentVariable($lumoswitchName, $null, 'Process')
  }
  if (Test-Path -LiteralPath $lumoswitchRoot -PathType Container) {
    $lumoswitchRootItem = Get-Item -LiteralPath $lumoswitchRoot -Force
    if ($lumoswitchRootItem.Attributes -band [IO.FileAttributes]::ReparsePoint) { throw 'Lumoswitch refused to clean through a linked directory.' }
    foreach ($lumoswitchFile in @(Get-ChildItem -LiteralPath $lumoswitchRoot -File -Recurse -Force)) { Remove-LumoswitchFile $lumoswitchFile.FullName }
    foreach ($lumoswitchDirectory in @(Get-ChildItem -LiteralPath $lumoswitchRoot -Directory -Recurse -Force | Sort-Object FullName -Descending)) {
      if ($null -eq (Get-ChildItem -LiteralPath $lumoswitchDirectory.FullName -Force | Select-Object -First 1)) { Remove-Item -LiteralPath $lumoswitchDirectory.FullName -Force }
    }
    if ($null -eq (Get-ChildItem -LiteralPath $lumoswitchRoot -Force | Select-Object -First 1)) { Remove-Item -LiteralPath $lumoswitchRoot -Force }
  }
  $lumoswitchBin = Split-Path -Parent $lumoswitchLauncher
  if (Test-Path -LiteralPath $lumoswitchBin -PathType Container) {
    foreach ($lumoswitchBackup in @(Get-ChildItem -LiteralPath $lumoswitchBin -Filter 'lumoswitch-deepseek-harness.ps1.backup.*' -File -Force)) { Remove-LumoswitchFile $lumoswitchBackup.FullName }
  }
  Remove-LumoswitchFile $lumoswitchLauncher
  Write-Host 'Lumoswitch native setup and optional launcher removed. Open a new terminal to refresh the environment.'
  exit 0
}

$lumoswitchEnvironment = [ordered]@{}
$lumoswitchEnvironment['DSH_HOME'] = (Join-Path $lumoswitchRoot 'dsh-home')
foreach ($lumoswitchEntry in $lumoswitchEnvironment.GetEnumerator()) {
  [Environment]::SetEnvironmentVariable($lumoswitchEntry.Key, $lumoswitchEntry.Value, 'Process')
}
$lumoswitchExecutable = Get-Command 'npx.cmd' -CommandType Application -ErrorAction SilentlyContinue
if ($null -eq $lumoswitchExecutable) { $lumoswitchExecutable = Get-Command 'npx' -CommandType Application -ErrorAction Stop }
$lumoswitchArguments = @('@deepseek-ai/dsh', 'web')
& $lumoswitchExecutable.Path @lumoswitchArguments @AgentArgs
if ($null -ne $LASTEXITCODE) { exit $LASTEXITCODE }
'@
  Install-LumoswitchFile $lumoswitchLauncher $lumoswitchLauncherContent
  Write-Host 'Native Lumoswitch setup saved. Future command: npx @deepseek-ai/dsh web'
  Write-Host 'Optional maintenance launcher:' $lumoswitchLauncher
  $lumoswitchExecutable = Get-Command 'npx.cmd' -CommandType Application -ErrorAction SilentlyContinue
  if ($null -eq $lumoswitchExecutable) { $lumoswitchExecutable = Get-Command 'npx' -CommandType Application -ErrorAction Stop }
  $lumoswitchArguments = @('@deepseek-ai/dsh', 'web')
  & $lumoswitchExecutable.Path @lumoswitchArguments
  if ($null -ne $LASTEXITCODE -and $LASTEXITCODE -ne 0) { throw 'npx exited with code ' + $LASTEXITCODE }
}

导入会写入 Agent 支持的持久化配置，并直接启动 npx @deepseek-ai/dsh web。保存的 Lumoswitch 维护脚本不是启动 Agent 的必需入口；需要恢复或移除此接入时，运行它并追加 --lumoswitch-clean。

清除 Lumoswitch 接入

Windows PowerShell

先退出该 Agent 的所有 Lumoswitch 会话，再运行下面的命令。可选维护启动器会删除受管原生配置、恢复已保留的共享文件、清除 Lumoswitch 用户环境变量，并移除自身。

& {
  $lumoswitchLauncher = Join-Path $env:LOCALAPPDATA 'Lumoswitch\bin\lumoswitch-deepseek-harness.ps1'
  if (-not (Test-Path -LiteralPath $lumoswitchLauncher -PathType Leaf)) {
    throw 'The optional Lumoswitch maintenance launcher is missing. Run persistent import again before cleanup.'
  }
  & powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File $lumoswitchLauncher --lumoswitch-clean
}

macOS / Linux

下面的命令会删除专属 DSH Home、受管环境、可选维护启动器及其备份，不会删除 Harness profile、设置、工作区或会话：

"$HOME/.local/bin/lumoswitch-deepseek-harness" --lumoswitch-clean

清除后建议在 Lumoswitch 中轮换该 Access Key。

验证与排查

  • 启动后，模型选择器中应出现 Lumoswitch provider 和配置 API 的全部下游模型。
  • 已有 $DSH_HOME/settings.yaml 中保存的默认模型优先于 overlay 的初始默认值；此时在 Web UI 中切换到 Lumoswitch 模型即可。
  • 返回 401：重新复制当前配置的 Access Key，并确认没有多余空格。
  • 返回 404：确认 Base URL 包含且只包含一次 /v1。
  • 模型列表没有更新：重新复制永久命令，它会重新生成专属 overlay；无需修改 Harness 的共享设置。
  • DeepSeek Harness 仍处于 Developer Preview，升级后如出现配置 schema 错误，请先对照官方 provider 与 CLI 文档。

参考：DeepSeek Harness 仓库、模型提供方配置和dsh CLI 行为。

维护者发布字段
  • 平台 ID：deepseek-harness
  • 展示名称：DeepSeek Harness
  • 下游协议：openai-compatible
  • commandTemplate：复制「仅本次启动」代码框的完整内容
  • 永久策略：native
  • persistentCommandTemplate：复制「永久使用」中的完整设置命令
  • futureCommand：npx @deepseek-ai/dsh web
  • 展示顺序：35
  • 最近核验：2026-08-27

OpenCode Agent 接入

了解 OpenCode，并选择临时、永久或清除 Lumoswitch 接入

OpenAI SDK 接入

Next Page

On this page

DeepSeek Harness 接入方式总览准备连接信息仅本次启动永久使用Windows PowerShell 原生导入仅本次使用（Windows）永久使用（Windows）清除 Lumoswitch 接入Windows PowerShellmacOS / Linux验证与排查