# @ever-works/codex-plugin 中文文档

规范地址：https://npmcn.com/package/%40ever-works/codex-plugin/

版本：1\.0\.18
npm 元数据更新时间：2026-11-03T08:57:28.542Z
中文译文更新时间：2026-11-14T01:42:17.352Z
软件包许可：AGPL-3\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40ever-works/codex-plugin
原文对照：https://npmcn.com/package/%40ever-works/codex-plugin/?lang=original
项目主页：https://github.com/ever-works/ever-works/tree/main/packages/plugins/codex#readme
源码仓库：https://github.com/ever-works/ever-works

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.1 MB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@ever-works/plugin ^1\.2\.16
- 首次发布：2026-06-06T08:18:25.976Z
- 最新版本发布：2026-11-03T08:57:28.101Z
- 近 30 天下载量：2641（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 15 个）

## 中文简介

Codex 生成器插件 - 代表生成 Codex 的完整管道插件

## 安装

```sh
npm install @ever-works/codex-plugin
```

也可以使用：`pnpm add @ever-works/codex-plugin`、`yarn add @ever-works/codex-plugin`、`bun add @ever-works/codex-plugin`

## README

# @ever-works/codex-plugin (英语)

将生成工作委托给 [代码 CLI](https://github.com/openai/codex)。一个单独的 Codex 会话研究、创建和更新临时工作空间内的工作项目JSON文件.

## 插件元数据

| 外地 | 数值 |
| --- | --- |
| 身份证 | `codex` |
| 类别 | `pipeline` |
| 能力 | `pipeline`, (中文(简体) ), `form-schema-provider`, (中文(简体) ), `device-auth` |
| 作者 | 永远工作团队 |
| 许可证 | AGPL-3.0 导弹 |
| 内建 | 对 |
| 可自动启用 | 没有 |

## 管道步骤

该插件运行了6个相继步骤 :

| {\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0} | 步骤 | 说明 | 可选 |
| --- | --- | --- | --- |
| 1个 | **设置代码x** | 下载/检查 Codex CLI 二进制并解析认证 | 没有 |
| 2个 | **准备背景** | 创建临时工作空间、种子现有项目和元数据 | 没有 |
| 3个 | **生成项目** | 执行 Codex CLI 作为 JSON 文件进行研究和生成项目 | 没有 |
| 页:1 | **收集结果** | 读取生成的 JSON 文件返回到管道结果 | 没有 |
| 页:1 | **抓取屏幕截图** | 对生成的项目进行截图( 通过截图提供者) | 对 |
| 6个 | **清理** | 删除临时工作空间 | 对 |

步骤3,a **分类学观察者** 监视新项目文件的工作空间并保存 `_meta/` 实时同步分类文件(类别,标签,品牌). 按项目报告进展情况.

## 认证

Codex支持两个认证模式:

### API 密钥

在插件设置中提供 OpenAI API 密钥( O)`apiKey` 页:1.

从一个 [平台.openai.com/账户/api键](https://platform.openai.com/account/api-keys)。 。 。 .

### 本地编码 Auth

如果没有配置 API 密钥, 插件可以使用存储在一个管理的每个用户的本地 Codex CLI 认证 `CODEX_HOME`通过登入向导或手动认证:

```bash
codex login
```

插件实现一个孤立 `CODEX_HOME` 用于每个 Ever Works 用户在其管理下的临时工作,所以本地 Codex 认证不依赖共享 `~/.codex/auth.json`。 。 。 .

登入UI提供3步流程:选择认证模式,配置证书,并验证连接.

## 设置

| 设置 | 类型 | 范围 | 说明 |
| --- | --- | --- | --- |
| `authMode` | 字符串 | 用户 | `api-key` 或者说 `local` (隐藏,由登机法师设置) |
| `apiKey` | 字符串 | 用户 | OpenAI API 密钥( 机密, 支持 env var) `OPENAI_API_KEY`(中文(简体) ) |
| `model` | 字符串 | 全球 | 生成模型( 默认 ): `gpt-5.4`(中文(简体) ) |
| `unsafeBypassSandbox` | 布尔 | 隐藏 | 在不兼容的主机上进行旁通编码沙箱 |

### 支持的模式

-   **GPT-5.4 (韩语)** (默认) - 400k 上下文
-   **最新代码** - 200公里背景
-   **GPT-5.2 编码** - 400k背景

## 表单Schema

插件提供了一个用户格式,有两个可配置字段:

| 外地 | 类型 | 默认 | 验证 | 说明 |
| --- | --- | --- | --- | --- |
| `target_items` | 编号 | 第50条 | 1 -500 (中文(简体) ) | 要生成的新项目的目标数量 |
| `capture_screenshots` | 布尔 | 虚假 | \- 说吧 | 获取生成项目的截图 |

## 提示系统

提示通过一个即时外观(如:Langfuse)来管理. 当找不到外部提示时,硬码默认被作为倒置.

提示键 :

-   `codex.system` - 系统即时模板
-   `codex.user` - 用户提示模板

两者都支持工作环境、现有项目、类别、标签和品牌的可变替代.

## 二进制管理

插件会自动下载并缓存 Codex CLI 二进制 :

-   二进制被缓存于 `/tmp/codex-generator/bin/`
-   支持 Linux (x64/arm64) 和 macOS (x64/arm64)
-   回到系统安装 `codex` 如果下载失败则命令
-   默认 CLI 版本 : `0.120.0`

## 处理错误

-   **非零退出代码**:作为软警告处理. 如果物品仍在生产中,结果就会成功,并附有警告.
-   **沙盒写块**:被探测和记录,但 **永远** 单靠沙盒绕道再试. 探测器读取了 Codex 的 stdout/stderr,这是模型出产的文本,可以注入内容(取出一页,README),因此不能允许它升级为 `--dangerously-bypass-approvals-and-sandbox`。旁通只有在操作员明确允许时才会发生 `unsafeBypassSandbox` (然后每跑一次都绕开) 见 [沙盒绕行](https://npmcn.com/package/%40ever-works/codex-plugin/#readme-sandbox-bypass)。 。 。 .
-   **结构化产出回收**: 如果 Codex 不写入项目文件而完成, 插件尝试使用二次通过 `--output-schema` 财务报告和审定财务报表 `--output-last-message` 以恢复结构化输出.
-   **隐蔽的秘密**编号: `getRealSecret` 帮助过滤出 UI 占位符值( E)`••••`在使用全权证书之前.

## 项目结构

```
src/
  codex.plugin.ts          # Main plugin class (IPlugin, IPipelinePlugin, IFormSchemaProvider, ILocalAuthProvider)
  types.ts                 # Step IDs, constants
  steps.ts                 # Pipeline step definitions
  form-schema.ts           # Form fields, groups, validation
  prompt-keys.ts           # Prompt facade keys
  device-auth.ts            # Device auth flow (codex login --device-auth)
  index.ts                 # Public exports
  prompt/
    system-prompt.ts       # Default prompts and variable builders
  utils/
    binary-manager.ts      # CLI binary download and caching
    pipeline-helpers.ts    # State management, auth resolution, progress reporting
    process-runner.ts      # Codex CLI subprocess execution
    workspace-manager.ts   # Workspace I/O (create, seed, read, cleanup)
    screenshot-capture.ts  # Screenshot facade integration
    taxonomy-sync.ts       # Merge new categories/tags/brands into _meta files
    taxonomy-watcher.ts    # Filesystem watcher for live taxonomy sync
    platform.ts            # Platform detection helpers
    subprocess-env.ts      # Environment variable setup for subprocesses
scripts/
  smoke-codex.mjs          # Manual smoke test script
```

## 发展

```bash
# Build
pnpm build

# Type-check
pnpm type-check

# Run tests
pnpm test

# Watch mode
pnpm test:watch

# Coverage
pnpm test:coverage
```

## 沙盒绕行

除非另有说明 否则Codex会运行在它自己的沙盒里 两条路可以运行它 `--dangerously-bypass-approvals-and-sandbox` (完全主机访问,不批准):

-   **生成管道** - 只有在操作员设定时 `unsafeBypassSandbox: true` (隐藏设置,默认) `false`) (中文(简体) ). 当 Codex 输出时, 插件不再自动升级 _说_ 写入被屏蔽: 该输出 即时输入的模型可以准确打印这些短语。 下降的升级记录为: 警告; 结构化输出回收仍在进行, 有沙箱.
-   **代码编辑路径** (单位:千美元)`executeCodeEdit`(b) —— **永远** 今天通过绕行旗。 它编辑一个工作空间 用于运行的平台需要不受限制的写作。 将任何主机运行代码编辑视为给定 codex 处理插件本身的 OS 权限: 在没有证书或网络的容器/ VM 中运行 不应该到达。 这种行为没有改变,这里有记载,因此是一种众所周知的、经过审查的权衡.

## 烟雾测试

本地验证真实的 Codex CLI 集成 :

```bash
pnpm smoke
```

对于需要沙盒绕行的主机:

```bash
CODEX_SMOKE_BYPASS_SANDBOX=1 pnpm smoke
```

无论是要求 `OPENAI_API_KEY` 环境或本地编码文件认证(`codex login`) (中文(简体) ).

## 解决问题

| 症状 | 可能的原因是 | 修补 |
| --- | --- | --- |
| 世代从不开始/留在 `0%` | `codex` 未选择此工程的运行中的管道插件 | 打开工作 **插件** → `pipeline` 能力和设置 `codex` 作为活动管道;或 设置为全球管道默认 **设置 — 插件** |
| 步骤失败 `No AI / search / screenshot provider configured` | 管道依赖于无法启用或没有证书的能力插件 | 启用并配置工作或全球匹配能力插件( AI 提供者、 搜索、 截图、 内容提取器) |
| 步骤输出看起来错误/ 通用 | Form-field 调制未设置; 使用与工程域不符的默认管道 | 打开 **生成表单** 为工作设置特定域(类别、目标关键词、源 URL),并重运行受影响的步骤 |
| 子进程错误 : `command not found` | `Codex Generator` 运行 API 主机上未安装 CLI | 在 API 主机上安装 Codex 生成器 CLI, 并确保它打开 `PATH`; 通过运行验证 `which <cli>` 发射的同一枚炮弹 `pnpm dev:api` |
| 认证 / 设备- 自动流动站 | 上游 IDE / 浏览器中从未确认设备自动代码 | 重运行设备自动流出 **设置 – 插件 – 代码 – 连接**,然后在代码到期前在上游服务中填写提示 |
| 主机重启后管道无法恢复 | 检查站没有继续存在(今天只有标准管道维持检查站) | 取消被卡住的运行并重新触发生成; 因为生产可靠性更可取 `standard-pipeline` |

## 文档

-   [工程文档](https://docs.ever.works/)
-   [Ever 工程仓库](https://github.com/ever-works/ever-works)
-   [插件系统](https://npmcn.com/package/plugin/README.md)
-   [Codex CLI 主页](https://github.com/openai/codex)
-   [OpenAI API 密钥](https://platform.openai.com/account/api-keys)

## 许可证

AGPL-3.0 导弹

## 常见问题

### @ever-works/codex-plugin 是什么？

Codex 生成器插件 - 代表生成 Codex 的完整管道插件

### 如何安装 @ever-works/codex-plugin？

在项目目录运行 npm install @ever-works/codex-plugin，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@ever-works/plugin（^1\.2\.16）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @ever-works/codex-plugin 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @ever-works/codex-plugin 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @ever-works/codex-plugin 可以商用吗？

@ever-works/codex-plugin 使用 AGPL-3\.0 许可。最严格的 Copyleft：除分发外，通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括，不构成法律意见，请以许可原文为准。

### @ever-works/codex-plugin 的下载量有多少？

根据 npm 官方下载统计，@ever-works/codex-plugin 在 2026/10/14 – 2026/11/12 这 30 天内被下载 2,641 次，日均约 88 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @ever-works/codex-plugin 还在维护吗？

最新版本 1\.0\.18 发布于 2026/11/03（10 天前）；至今共发布 15 个版本，其中过去 12 个月发布了 15 个；首次发布于 2026/06/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。