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 会完成以下工作：
- 在需要时安装并构建
upstream/deepseek-harness。 - 生成兼容源码并构建本插件。
- 首次运行时把当前仓库稳定链接到隔离的
.tmp/dsh-home；后续构建复用该链接。 - 启动 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。
维护文档
许可证见 LICENSE，第三方声明见 THIRD_PARTY_NOTICES.md。
No comments yet. Be the first to write one.