@necokeine/dsh-codex-relay

Readme

# dsh-codex-relay

`@necokeine/dsh-codex-relay` 是一个可安装的 DeepSeek Harness 模型提供方插件。安装后，模型设置页和会话模型选择器会出现 **Codex**；DSH 通过本机 `codex app-server --stdio` 的 JSON-RPC 接口读取当前 Codex 账号可用的模型，并把每次模型请求交给 Codex 原生 agent loop。

Codex 的工具调用、命令执行和文件修改都在原生 Codex turn 内完成。DSH 不向 Codex 发送自己的工具 schema，也不会重复执行 Codex 已完成的工具调用；DSH 只记录请求和最终回答。

## 前置条件

- Node.js `^22.19.0` 或 `>=24.0.0`
- DeepSeek Harness `0.1.1-rc.2`
- 本机已经通过 Codex CLI 登录；插件固定使用 `@openai/codex@0.147.0` 提供的 binary，不依赖 `PATH` 中的其他 `codex` 版本

## 安装

从 npm 安装：

```sh
dsh plugin --profile default add @necokeine/dsh-codex-relay
dsh --profile default --dump-config
dsh --profile default
```

从源码安装时，本地目录使用 pnpm `link:`，不会代替源码目录安装依赖。先克隆仓库并安装依赖；`prepare` 会同时生成 `lib/`：

```sh
git clone https://github.com/necokeine/dsh-codex-relay.git
cd dsh-codex-relay
pnpm install
dsh plugin --profile default add "$PWD"
dsh --profile default --dump-config
dsh --profile default
```

`package.json` 的 `dsh.bundle` 声明会把 `cordis.patch.yml` 加入 profile。该层使用稳定行 ID `llm-codex`：若当前 DSH 版本内置了同名原型行，插件层会替换它；否则会直接插入。启动 Web 界面后，在模型设置页选择 **Codex**，再选择 Codex 原生账号公开的模型和推理强度。

从 Git 仓库安装源码时，pnpm 会要求显式允许该包的 `prepare` 构建脚本。发布到 npm 或使用 `pnpm pack` 生成的 tarball 会携带预构建的 `lib/`，无需安装时构建。

## 配置

插件设置保存在 `dsh-codex-relay` namespace：

```yaml
dsh-codex-relay:
  permissionMode: inherit
  disposeGraceMs: 3000
  env: {}
```

- `permissionMode`：`inherit`（默认）、`never`、`approve-for-me` 或 `dangerously-bypass-approvals-and-sandbox`
- `disposeGraceMs`：Codex app-server 进程树终止宽限时间，单位为毫秒
- `env`：显式传给 Codex 子进程的环境变量；原生登录和账号状态仍由 Codex home 管理
- `retryPolicy`：DSH LLM provider 的失败重试策略

`inherit` 会按每个 DSH 会话的实时审批策略决定 Codex 权限：

- DSH 界面为 `ask` 时，Codex 使用 `workspace-write` 和 `approvalPolicy: on-request`。命令沙箱提升、额外文件写入与权限扩展请求会进入同一个 DSH 审批界面；单次允许只映射为 Codex 的单次 `accept`，不会静默升级为整场会话授权。这使 `git commit` 创建 `.git/index.lock` 等需要提升权限的操作可以由用户批准。
- DSH 界面为 `never` 时，Codex 仍可在普通工作区内写文件，但所有需要提升权限的操作都会被拒绝，也不会弹出审批。

其余三个值是插件级覆盖：`never` 固定拒绝提升权限，`approve-for-me` 交给 Codex 原生自动审查器，`dangerously-bypass-approvals-and-sandbox` 则关闭沙箱与交互审批。最后一个选项风险最高，只应在已隔离且完全可信的工作区使用。

`session-title` 和 `compaction` 辅助请求不继承普通会话权限，始终强制使用 `approvalPolicy: never` 和 `sandbox: read-only`，并要求 Codex 不使用工具或修改外部状态。

## 运行机制

每次目录读取或模型调用都会启动一个临时 app-server 进程。模型调用在当前 DSH Session 的工作目录创建 ephemeral Codex thread，注入持久的 user/assistant 历史，随后执行一个原生 Codex turn。插件等待 terminal notification，只把 final answer 转成一个 DSH text block；完成、失败或取消后会终止并等待整个子进程树退出。

固定 bridge instruction 为：

```markdown
You are running as the selected Codex model provider inside DeepSeek Harness. Use only your native Codex tools and agent loop. Do not emit DeepSeek Harness tool calls; the host records your final answer.
```

## 开发

```sh
pnpm install
pnpm run check
pnpm run test:coverage
pnpm pack
```

## 已知限制

- 当前只向 DSH 声明文本输入；图片会在调用前投影为稳定的省略提示。
- 插件等待 Codex terminal notification 后一次性输出最终文本，不投影增量文本或 token usage。
- Codex 原生工具轨迹不会转换为 DSH `tool/call` 和 `tool/result` 事件；DSH Session 记录请求和最终回答，不记录 Codex 私有轨迹。
- `temperature`、`maxTokens`、`stop` 和 DSH 工具 schema 没有映射到该集成。