前言¶

在 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 搜索。本文不附帶未經覈實的目錄頁地址。