前言¶

在 DSH 这类「一切皆插件」的智能体环境中，Agent loop 需要一个可切换的主模型 Provider。如果开发者已经在本机维护 Codex CLI 登录态，并希望在 Harness Agent loop 中直接选择本地 Codex App Server 作为主模型，dsh-llm-codex-app-server 提供了这种接入方式。

它是一个 out-of-tree Harness bundle，安装后不会修改 deepseek-harness 仓库。下面介绍它的能力边界、安装方式和需要注意的事项。

插件定位¶

dsh-llm-codex-app-server 是一个 DeepSeek Harness LLM provider，底层使用本地已认证的 Codex App Server。

它的核心动作是向 DSH 注册一个名为 codex-local 的主模型 Provider，使 Harness Agent loop 可以在模型选择中直接使用它。

代码仓库地址为：

https://github.com/wss534857356/dsh-plugin-codex

该插件面向 DSH 版本范围：

>=0.1.2-alpha.1 <0.2.0

核心能力¶

注册为 Harness 主模型 Provider¶

该插件把本地 Codex App Server 包装成 Harness 可以调用的主模型 Provider。

安装后，codex-local 会作为可选择的 Provider 出现在 Harness Agent loop 中。也就是说，它不是单纯暴露某个外部命令，而是把 Codex App Server 接入 DSH 的模型调用路径。

复用本地 Codex 登录态¶

插件使用 CODEX_HOME 下的原生 Codex account state。

它不会读取、复制、记录或存储 OAuth tokens 或 API keys。对使用者来说，这意味着认证仍然由本地 Codex CLI 体系承担，插件本身不承担密钥保存职责。

会话复用与冷启动¶

在普通 Harness 会话中，插件会复用一个固定版本的 Codex App Server：

@openai/codex@0.147.0

复用条件是：该 App Server 运行在私有空目录中，并且一个临时线程在 bounded cache lease 仍然有效时保持可用。

当需要重建冷线程时，插件会把已记录的 Harness messages 在空 turn 之前注入，从而恢复上下文。后续的普通用户消息则通过 native turn input 发送。

Harness 的 system text 会作为 App Server 的 base instructions 提供。

工具调用与 harness_skill¶

插件会在 deepseek_harness 这个 App Server namespace 下声明 Harness tools。

它也会把外层 Harness 的 skill tool 暴露为：

harness_skill

这个工具的参数 schema 只接受当前 Harness session catalog 中存在的名称。这样可以让 Codex 侧调用到的技能名称仍然受当前 Harness 会话目录约束。

当 App Server 请求 deepseek_harness namespace 下的 declared tool 时，插件会发出一个真实的 Harness tool-call，结束当前模型步骤，并让 App Server callback 保持 pending。

需要注意：一个失败或被拒绝的 Codex-native action 仍然属于 action outcome；除非 App Server 报告 turn 本身失败，否则它不会直接导致 Harness 模型请求失败。

流事件、统计与图片附件¶

插件会把以下信息转换为 Harness stream events：

• reasoning
• assistant text
• usage
• Codex-owned context
• diagnostics
• action lifecycles

Codex cached input 会通过 Harness 的 cacheReadTokens 上报。这样，标准的 token meter 和 conversation statistics 可以显示缓存命中比例，而不需要额外的 Provider 专用 UI。

对于图片和包含图片的工具结果，插件会把它们保留为 durable 的 ImageAttachmentRef 值。在接近 App Server boundary 时，才会按协议需要临时转换。

如果 projected base64 payload 超过：

maxRequestImageBytes

插件会确定性地替换最旧的 model-visible images。资料中说明，保留的图片不会持久化 data URL。

浏览器呈现与设置卡片¶

插件包含一个浏览器插件。

它会 shadow 标准 Assistant cell，并渲染 codex-action blocks。渲染形式包括 Harness 的 compact disclosure row 和 state dot。

它还会通过 DSH 的：

settings.plugin.item

extension point 提供一个 Codex App Server settings card。

辅助能力¶

插件支持 compaction-basic。该辅助请求会使用一个 one-shot Codex model process。

它也会对 Codex Agents 的 web_search 调用进行条件拦截。非 Codex Agent 的调用会继续沿用原有 provider chain。

安装与启用¶

前置条件¶

先确认本机 Codex CLI 已完成登录：

codex login

然后安装插件。安装完成后，可以 dump 配置检查注册情况，再启动 DSH Web profile。

安装发布版本¶

dsh plugin --profile web add dsh-llm-codex-app-server@latest
dsh --profile web --dump-config
dsh --profile web

第一步安装插件，第二步检查当前 profile 的 dump 配置，第三步启动 Web profile。

从源码构建¶

如果要使用本地 checkout 构建产物，先安装依赖并执行检查：

pnpm install --frozen-lockfile
pnpm run check

pnpm run check 会执行仓库定义的检查与打包流程，生成可用于安装的 tarball。

随后把生成的 tarball 安装到 Harness profile：

dsh plugin --profile web add ./dist/dsh-llm-codex-app-server-<version>.tgz
dsh --profile web --dump-config
dsh --profile web

这里使用仓库生成的实际 tarball 名称，而不是手工拼接安装源。

典型用法¶

一个基本的启用流程如下：

1、先完成 Codex CLI 认证：

codex login

2、安装发布版本：

dsh plugin --profile web add dsh-llm-codex-app-server@latest

3、检查插件是否进入当前 profile 配置：

dsh --profile web --dump-config

4、启动 DSH Web profile：

dsh --profile web

启动后，codex-local 会作为 Harness Agent loop 中可选的主模型 Provider 存在。开发者可以把它用于需要本地 Codex App Server 的 Harness 会话。

适用场景与注意¶

适合这类插件的使用者通常是：

• 已经在本地使用 Codex CLI，并拥有可用登录态；
• 希望 DSH Web profile 的 Harness Agent loop 可以选择本地 Codex App Server；
• 需要把 Codex 的 reasoning、assistant text、usage、diagnostics 和 action lifecycles 映射回 Harness stream events；
• 需要 Codex App Server settings card 和 codex-action block 的浏览器呈现。

使用前需要注意：

• 该插件是 out-of-tree Harness bundle，安装本身不会修改 deepseek-harness 仓库。
• 插件声明不会读取、复制、记录或存储 OAuth tokens 或 API keys，但认证状态仍来自本地 CODEX_HOME。
• 图片附件会以 durable ImageAttachmentRef 形式保留；资料说明保留的图片不会持久化 data URL。
• 生成 public/example.png 等项目文件时，仍需要 Codex 请求一个带有明确 destination 的 declared Harness mutation tool。聊天附件本身不会隐式变成 workspace mutation。
• thread/start 属于 provider lifecycle disclosure，不能把它理解为模型执行了某个 native action 的证据。
• 插件会在当前 dsh 进程的权限上下文中运行。安装前应检查源码、依赖和仓库中的许可证文件。资料未明确许可证类型，仓库文件列表中可见 LICENSE，具体条款请以仓库内容为准。

结尾¶

dsh-llm-codex-app-server 的价值在于把本地已认证的 Codex App Server 接入 DSH 的主模型 Provider 层，同时保留 Harness 的工具调用、stream events、图片附件和 Web 呈现约定。

代码仓库：

https://github.com/wss534857356/dsh-plugin-codex

如果在 DSH 社区目录中浏览插件，也可以按 dsh-llm-codex-app-server 搜索。本文不附带未经核实的目录页地址。