---

description: "在 DeepSeek Harness 中使用官方 Codex App Server 的 Agent Runtime。" kind: "package-bundle"

dsh-embedded-codex

dsh-embedded-codex 是 DeepSeek Harness 的外部 Bundle。它增加 Codex 模式 Agent 预设，让 DSH Web Session 使用官方 Codex App Server 和当前机器上的 ChatGPT Codex 登录。

Codex 负责模型循环、原生工具、sandbox、审批、隐藏历史和 compaction；DSH 继续负责 Session、Web/API、对话轨迹、持久化和 token 展示。其他 DSH Agent 预设不会受到影响。

环境要求

• Node.js ^22.19.0 或 >=24.0.0
• pnpm 11.7.0
• Git，且克隆时初始化 submodule
• 拥有 Codex 权限并已登录的 ChatGPT 账户

本项目固定使用 @openai/codex@0.149.1，不会调用 PATH 中其他版本的 Codex CLI。

从克隆到启动 Web

git clone --recurse-submodules <repository-url> D:\dsh-embedded-codex
Set-Location D:\dsh-embedded-codex
pnpm install --frozen-lockfile
pnpm exec codex login
pnpm dev

pnpm dev 会完成以下工作：

1. 在需要时安装并构建 upstream/deepseek-harness。
2. 生成兼容源码并构建本插件。
3. 首次运行时把当前仓库稳定链接到隔离的 .tmp/dsh-home；后续构建复用该链接。
4. 启动 DSH Web。

打开一个新 Session，选择 Codex 模式 即可。Codex 模式不需要 DEEPSEEK_API_KEY；其他标准预设仍使用各自配置的模型凭据。

如果克隆时没有携带 submodule，先执行：

git submodule update --init --recursive

常用命令

命令	用途
pnpm dev	构建、确保本地开发链接并启动隔离的 DSH Web；不会重复安装 Codex
pnpm dev:install	构建、打包并执行一次真实 tarball 安装，但不启动 Web
pnpm dev:web	启动已经安装好的隔离 Web，不重新构建
pnpm dev:remove	从隔离 Web Profile 移除开发插件
pnpm build	先准备 DeepSeek Harness，再生成并构建本插件
pnpm test	执行 build、Vitest、lint、文档检查和 tarball 隔离安装测试
pnpm pack	生成可安装的 .tgz；pnpm 会通过 prepack 自动先执行 build

调试单个测试不需要额外的 package script，例如：

pnpm exec vitest run tests/runtime.spec.ts

开发链接与真实安装

日常开发使用 pnpm dev。首次运行会通过稳定的 link: 依赖把本仓库注册进 DSH Web Profile；以后修改插件代码只会重新构建 lib，不会再次执行 pnpm add，也不会重新解析或下载 @openai/codex。插件运行时直接使用仓库根目录中由首次 pnpm install --frozen-lockfile 安装的固定 Codex 版本。

需要验证发布包时使用：

pnpm dev:install
pnpm dev:web

pnpm dev:install 会生成真实 .tgz，只删除并重建 .tmp/dsh-home/profiles/web/node_modules，然后通过 DSH CLI 安装 tarball。Profile 配置、lockfile、用户 patch 和 Session 数据不会被删除。这样既验证真实发布边界，也规避 pnpm 在已有 hoisted node_modules 上重新安装时抓取其他平台 optionalDependencies 的问题。再次执行 pnpm dev 会把 Profile 切回本地链接模式。

切换模式或重新安装前必须先停止正在运行的 DSH Web。Windows 会阻止删除正在使用的 node_modules；脚本会重试短暂的文件占用，仍无法处理时会提示停止 Web，不会扩大删除范围。

安装到现有 DSH

先生成本地 tarball：

pnpm pack

然后通过 DSH Web Profile 安装并启动：

dsh plugin --profile web add .\dsh-embedded-codex-0.1.0.tgz
dsh web

移除插件：

dsh plugin --profile web remove dsh-embedded-codex

包发布到 npm 后，也可以直接按包名安装：

dsh plugin --profile web add dsh-embedded-codex
dsh web

构建说明

父仓库的 Git submodule gitlink 是唯一的 DSH commit 来源，不再额外维护 commit 或源码摘要文件。pnpm build 会检查本地 submodule 是否与 gitlink 一致，并使用 .tmp/upstream-build.json 缓存已经完成的 DSH 构建；首次构建、gitlink 变化、产物缺失或 submodule 有源码修改时会重新构建 DSH。

本插件包含三个 DSH provider 的兼容替代实现，因此运行时仍会检查 Host package 版本。这个检查用于防止发布后的插件被加载进不兼容的 DSH，不是重复的 submodule 版本锁。

完整构建顺序：

DeepSeek Harness dependencies and build
  -> materialize compatibility sources and apply patches
  -> TypeScript declarations
  -> runtime and Web client bundles
  -> package structure verification

兼容 patch 规则

compat/patches 只存放扁平的 *.patch 文件。每个 patch 只能修改一个 DSH 文件，文件名必须把该文件相对于 upstream/deepseek-harness 根目录的路径中的 / 替换为 +：

<DSH 根目录相对路径，将 / 替换为 +>.patch

例如：

DSH 文件	patch 文件
packages/core/agent/src/index.ts	compat/patches/packages+core+agent+src+index.ts.patch
packages/api/session-controller/src/client/transport.ts	compat/patches/packages+api+session-controller+src+client+transport.ts.patch

pnpm build 会在应用前强制检查以下规则：

• compat/patches 中不能有子目录或其他类型的文件。
• 每个 patch 必须只有一个 diff --git 文件段。
• patch 的 diff --git、--- 和 +++ 路径必须完全等于文件名解码出的 DSH 路径。
• 目标必须位于构建脚本复制的 DSH provider 源码目录内。

普通插件开发只修改 src、presets 和 tests。需要改变 DSH 兼容 provider 时，应基于当前固定的 DSH commit 生成单文件 diff；一个改动涉及多个 DSH 文件时，必须拆成多个按上述规则命名的 patch。不要直接修改 compat/generated 或 lib：它们会在下一次构建时被删除并重新生成。修改完成后运行 pnpm test，确认所有 patch 仍能干净应用并通过完整打包安装测试。

配置

可以在更晚的 Profile patch 中覆盖 embedded-codex 条目：

- id: embedded-codex
  config:
    requireChatgptLogin: true
    approvalPolicy: on-request
    sandbox: workspace-write

字段	默认值	用途
providerName	codex	DSH 模型选择器中的 provider id
providerDisplayName	Codex	Provider 显示名称
defaultModelAlias	default	使用 Codex 原生默认模型选择
requireChatgptLogin	true	拒绝未登录或 API Key 登录
env	{}	显式传给 App Server 的环境变量
processCwd	当前进程目录	App Server 工作目录
approvalPolicy	on-request	Codex 原生审批策略
sandbox	workspace-write	read-only、workspace-write 或 danger-full-access
disposeGraceMs	3000	子进程关闭宽限时间
stderrMaxBytes	65536	保留的 stderr 诊断上限

常见问题

Web 仍显示旧的预设名称

执行 pnpm dev:install 后必须重启正在运行的 Web 进程：先按 Ctrl+C，再执行 pnpm dev:web。必要时在浏览器中按 Ctrl+F5。

真实安装使用内容哈希 tarball 文件名，避免 pnpm 因版本号没有变化而复用旧插件内容。日常 pnpm dev 使用稳定链接，不经过 tarball 缓存。

开发时开始下载所有平台的 Codex

先按 Ctrl+C 停止当前 DSH Web，再执行 pnpm dev。当前开发流程会把 Profile 切换为本地链接，后续插件修改不再执行 pnpm add。只有显式运行 pnpm dev:install 才会重建真实安装；重建前会移除可恢复的 Profile node_modules，因此 pnpm 只需安装当前平台的 Codex 包。

提示 submodule 未初始化或 commit 不一致

git submodule update --init --recursive

构建不会自动切换或更新 submodule commit。

找不到 Codex 登录

pnpm exec codex login

完成登录后重新创建一个 DSH Session。

维护文档

• 架构
• 兼容策略
• 测试策略
• 升级 DSH 或 Codex

许可证见 LICENSE，第三方声明见 THIRD_PARTY_NOTICES.md。