内容
# 开源代码插件 Codex
使用 Codex 中的开源代码（OpenCode）。该仓库将 Codex 插件与捆绑的stdio MCP服务器打包在一起，以便 Codex 可以启动 OpenCode 任务、继续 OpenCode 会话、运行第二代理审查，并将可见的 Codex 线程历史记录转移到 OpenCode 会话中。
这是与`openai/codex-plugin-cc`相反的配套想法：不是在另一个代理中使用 Codex，而是该插件在 Codex 中公开 OpenCode。
## 当前状态
已实现并在本地验证：
- Codex 插件清单和存储库本地市场元数据。
- 捆绑的基于 Node 的stdio MCP服务器。
- 通过显式参数、环境、常用安装路径和`PATH`进行 OpenCode CLI 发现。
- OpenCode 运行、继续、救援、审查和对抗审查工具。
- 后台 OpenCode 作业状态、结果和取消工具。
- 区分完整 OpenCode 答案和部分工具日志的后台结果摘要。
- 用于可见用户/助手转录的 Codex 滚动 JSONL 解析器。
- Codex 可见转录到 OpenCode 导入 JSON 转换。
- 使用`opencode import`的`opencode_transfer`，可选的导入后继续。
## 工具表面
MCP 工具注册表在`plugins/opencode-plugin-codex/src/server.ts`中定义。保持此列表与该文件和`scripts/smoke-mcp.mjs`一致。
- `opencode_check`
- `opencode_run`
- `opencode_continue`
- `opencode_rescue`
- `opencode_review`
- `opencode_adversarial_review`
- `opencode_transfer`
- `opencode_status`
- `opencode_result`
- `opencode_cancel`
对于`opencode_run`，将任务说明放在`prompt`中。仅使用`files`来附加现有的文件系统路径；服务器在 OpenCode 可以将其视为缺失路径之前，会拒绝`files`中的提示类似文本，并在 `--file`参数之前发送提示，以便 OpenCode 不将其解析为另一个附件。
除非明确请求更广泛的 OpenCode 文件系统访问权限，否则不要要求 OpenCode 读取 Codex 私有运行时路径，例如`~/.codex`、`$CODEX_HOME`或`.codex/plugins/cache`。插件默认拒绝这些提示，因为 OpenCode 的沙箱通常无法读取 Codex 的私有运行时文件；相反，在提示中内联协作/PUA 期望，或指向`~/.config/opencode/skills`下经过验证的 OpenCode 原生技能文件。
对于文档审查工作流，避免直接附加`.docx`等二进制文件，除非 OpenCode 可以读取该格式。优先使用存储库脚本、解包文本或显式文本提取作为审查输入。
将`opencode_review`和`opencode_adversarial_review`用作有界二次检查。它们默认情况下不是完整的安全扫描；提示应命名确切的文件或差异，不应要求 OpenCode 调用`security-diff-scan`、威胁建模、攻击路径分析、验证技能或子代理进行有界审查。如果需要并行或完整的安全审计工作，请启动一个单独的、明确范围的 OpenCode 任务，并获得用户的明确批准。
对于后台作业，在引用 OpenCode 输出之前，请阅读`opencode_result.outputSummary`。只有`succeeded_with_text`且`resultComplete: true`才是完成的 OpenCode 答案。`queued_partial`、`running_partial`、`cancelled_partial`、`failed_partial`和`succeeded_without_text`仅是进程证据；在将 OpenCode 视为已审查或实施任何内容之前，请缩小或重新运行任务。
## 需求
- Node.js `>=22`
- npm
- 支持本地插件市场的 Codex
- 用于实时 OpenCode 操作的 OpenCode CLI
MCP 服务器按以下顺序发现 OpenCode：
1. 工具参数`opencodeBin`。
2. `OPENCODE_BIN`。
3. `~/.opencode/bin/opencode`。
4. `/opt/homebrew/bin/opencode`。
5. `/usr/local/bin/opencode`。
6. `PATH`。
## 从此仓库安装
构建捆绑的 MCP 服务器：
```bash
npm install
npm run build
```
将此仓库添加为 Codex 插件市场（如果尚未配置）：
```bash
codex plugin marketplace add /path/to/opencode-plugin-codex
```
然后从该市场安装`opencode-plugin-codex`。
可选：为 OpenCode 注册选定的 Codex 协作技能以从`~/.config/opencode/skills`读取：
```bash
npm run register:opencode-skills
```
注册脚本是保守的：它会跳过现有的冲突技能目标而不是覆盖它们，默认情况下不会符号链接 Superpowers，因为 OpenCode 可能已经从其包缓存加载 Superpowers，并且默认情况下不会注册 Codex 安全扫描技能，因为它们可以升级普通的审查。仅当 OpenCode 没有已经加载这些技能时，请设置`OPENCODE_REGISTER_SUPERPOWERS=1`。仅为明确范围的 OpenCode 安全扫描工作流设置`OPENCODE_REGISTER_SECURITY_SKILLS=1`。
## 开发
在发布 README、清单、MCP 服务器或工具更改之前运行完整的本地检查：
```bash
npm run check
git diff --check
```
`npm run check`执行：
1. TypeScript 类型检查。
2. MCP 服务器捆绑构建。
3. Vitest 单元测试。
4. 存储库插件验证。
5. MCP 烟雾测试，列出所有预期的工具。
实时 OpenCode 传输验证依赖于本地提供程序/模型访问：
```bash
OPENCODE_BIN="$HOME/.opencode/bin/opencode" \
OPENCODE_MODEL="provider/model-authorized-for-this-user" \
npm run smoke:live-transfer
```
## 隐私边界
`opencode_transfer`将可见的用户/助手转录文本导入 OpenCode 的本地会话数据库。默认情况下，它不包括 Codex 系统消息、开发人员消息、工具输出或推理。
`opencode_transfer`需要一个明确授权的`model`，采用提供程序/模型形式。模型访问权限是用户特定的，因此插件不会为传输导入或继续选择默认提供程序/模型。
## 文档管理
为了避免文档漂移，请将这些文件视为具有不同的权威：
- `README.md`：当前面向用户的安装、功能、需求和验证命令的源。
- `plugins/opencode-plugin-codex/README.md`：简明的市场/插件目录摘要。保持简短，并指向此处获取完整详细信息。
- `docs/verification.md`：有日期的验证账本。更新它时，会收集新的烟雾、审计或实时传输证据。
- `docs/development.md`：历史设计和实现笔记。它可能描述计划的布局或较早的环境快照；除非检查源文件，否则不要将其视为当前存储库合约。
- `plugins/opencode-plugin-codex/src/server.ts`：权威的 MCP 工具注册表。
- `scripts/smoke-mcp.mjs`：发布在此 README 中的工具列表的可执行守护程序。
更改工具、安装步骤、发现行为、传输隐私或验证命令时，请在与代码或清单更改的同一提交中更新此 README。
