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

常用命令

调试单个测试不需要额外的 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

例如：

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

常见问题

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。