Skip to content

Commit 7ca4b68

Browse files
committed
fix: align codex adapter and host agent fallback
1 parent 727f27a commit 7ca4b68

24 files changed

Lines changed: 788 additions & 108 deletions

‎README.md‎

Lines changed: 39 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
# DevCodex
22

3-
> AI 开发规范注入器 — Copilot / Claude Code 双主支持(Hook-First / Instruction-Fallback)
3+
> AI 开发规范注入器 — 从 Copilot / Claude Code 双主支持升级为 Copilot / Claude Code / Codex 三宿主支持(Hook-First / Instruction-Fallback)
44
55
[![npm](https://img.shields.io/badge/npm-%40vextjs%2Fdevcodex-blue)](https://github.com/vextjs/devcodex)
66
[![License](https://img.shields.io/badge/license-AGPL--3.0-green)](LICENSE)
77

88
## DevCodex 是什么?
99

10-
DevCodex 通过 `.github/`(Copilot)与 `CLAUDE.md + .claude/ + .mcp.json`(Claude Code)向受支持的 AI 编码客户端注入结构化的开发工作流规范。
10+
DevCodex 通过 `.github/`(Copilot)、`CLAUDE.md + .claude/ + .mcp.json`(Claude Code)以及 `AGENTS.md + .agents/ + .codex/`(Codex)向受支持的 AI 编码客户端注入结构化的开发工作流规范。
1111
在支持 Hooks 的宿主中,它优先用 `hooks/_runtime/lifecycle.cjs` 提供确定性的生命周期护栏;在不支持 Hooks 的宿主中,则回退到 instructions 语义层继续工作。
1212

1313
## 功能特性
@@ -18,7 +18,7 @@ DevCodex 通过 `.github/`(Copilot)与 `CLAUDE.md + .claude/ + .mcp.json`(
1818
- **持久记忆**: 每 Agent、每日的会话记录,结构化字段
1919
- **自动报告**: 每次会话自动写入报告,从不询问 — 直接执行
2020
- **安全底线**: S01~S07 七条不可覆盖的安全规则
21-
- **宿主硬门禁**: 在 VS Code Hooks 可用时,通过 `UserPromptSubmit` / `PreToolUse` / `PostToolUse` / `PreCompact` / `Stop` 提供确定性护栏
21+
- **宿主硬门禁**: 在 VS Code / Claude Code / Codex Hooks 可用时,通过 `UserPromptSubmit` / `PreToolUse` / `PostToolUse` / `PreCompact` / `Stop` 提供确定性护栏
2222
- **全模式入口检查**: 所有模式在实质任务前显示 PC0~PC7;dev 模式额外执行 PC4 规范雷达与完整合规链
2323
- **项目现实扩展**: 先做语义意图初判,再结合目标项目 Profile、目录与当前任务上下文修正最终路由、产物落点和验证方式
2424
- **执行护栏**: 新需求切换时优先按意图判断边界;涉及外部平台/API/兼容性判断时优先看官方文档;提交时压缩 commit subject
@@ -44,11 +44,12 @@ export NODE_AUTH_TOKEN=YOUR_GITHUB_PAT
4444

4545
```bash
4646
npm install @vextjs/devcodex
47-
npx @vextjs/devcodex init # 默认双部署:Copilot + Claude Code adapter
47+
npx @vextjs/devcodex init # 默认三宿主部署:Copilot + Claude Code adapter + Codex adapter
4848
npx @vextjs/devcodex init --claude # 仅 Claude Code adapter
49+
npx @vextjs/devcodex init --codex # 仅 Codex adapter
4950
```
5051

51-
默认 `init` 会先将 Copilot 规范文件复制到项目的 `.github/` 目录,再链式部署 Claude Code adapter(`CLAUDE.md + .claude/ + .mcp.json`):
52+
默认 `init` 会先将 Copilot 规范文件复制到项目的 `.github/` 目录,再链式部署 Claude Code adapter(`CLAUDE.md + .claude/ + .mcp.json`)与 Codex adapter(`AGENTS.md + .agents/ + .codex/`):
5253

5354
```
5455
.github/
@@ -64,8 +65,21 @@ npx @vextjs/devcodex init --claude # 仅 Claude Code adapter
6465
└── RULES.md ← 使用入口
6566
```
6667

68+
Codex adapter 会同步以下工作区根产物:
69+
70+
```
71+
AGENTS.md ← 与 instructions.md / copilot-instructions.md / CLAUDE.md 同源
72+
.agents/
73+
└── skills/ ← Skill 详细检查标准(与源仓库 skills/ 同步)
74+
.codex/
75+
├── hooks.json ← Codex Hook 入口配置
76+
└── hooks/_runtime/ ← 统一 lifecycle.cjs 运行时
77+
```
78+
6779
`init --claude` 是 Claude Code-only 路径:只写入 `CLAUDE.md`、`.claude/{instructions,skills,prompts,hooks/_runtime,mcp,data}` 与 `.mcp.json`,并同步开启项目级 hooks / MCP / permissions 配置。
6880

81+
`init --codex` 是 Codex-only 路径:只写入 `AGENTS.md`、`.agents/skills/` 与 `.codex/{hooks.json,hooks/_runtime}`。若工作区根已有非空 `AGENTS.md` 或 `.codex/hooks.json` 且内容不同,CLI 会先生成 `.bak.<timestamp>` 备份再覆盖为 DevCodex 受管副本。
82+
6983
> ⚠️ 请确保 IDE 的 "Use Instruction Files" 设置已开启(默认开启)。
7084
>
7185
> ℹ️ VS Code 中若启用 Hooks(Preview)且未被管理员禁用,DevCodex 会同时加载 `.github/hooks/*.json` 作为确定性生命周期护栏;不支持 Hooks 的宿主自动回退到 instruction-fallback。
@@ -74,7 +88,7 @@ npx @vextjs/devcodex init --claude # 仅 Claude Code adapter
7488
7589
## 使用
7690

77-
标准安装后,Copilot 会通过 `copilot-instructions.md` + `.github/` 自动加载;Claude Code 会通过 `CLAUDE.md` + `.claude/` + `.mcp.json` 自动生效。两条正式主支持链都无需额外选择 Agent,直接对话即可:
91+
标准安装后,Copilot 会通过 `copilot-instructions.md` + `.github/` 自动加载;Claude Code 会通过 `CLAUDE.md` + `.claude/` + `.mcp.json` 自动生效;Codex 会通过工作区根 `AGENTS.md` + `.agents/skills/` + `.codex/hooks.json` 生效。正式支持链都无需额外选择 Agent,直接对话即可:
7892

7993
```
8094
帮我重构 user 模块的权限校验逻辑
@@ -125,10 +139,12 @@ npx @vextjs/devcodex init --claude # 仅 Claude Code adapter
125139

126140
| 命令 | 说明 |
127141
|------|------|
128-
| `devcodex init` | 初始化:同步 Copilot `.github/`,并链式部署 Claude Code adapter |
142+
| `devcodex init` | 初始化:同步 Copilot `.github/`,并链式部署 Claude Code 与 Codex adapter |
129143
| `devcodex init --claude` | 初始化:仅同步 Claude Code adapter 到 `CLAUDE.md`、`.claude/` 与 `.mcp.json` |
130-
| `devcodex update` | 更新:覆盖同步 Copilot `.github/`,并链式覆盖 Claude Code adapter |
144+
| `devcodex init --codex` | 初始化:仅同步 Codex adapter 到 `AGENTS.md`、`.agents/` 与 `.codex/` |
145+
| `devcodex update` | 更新:覆盖同步 Copilot `.github/`,并链式覆盖 Claude Code 与 Codex adapter |
131146
| `devcodex update --claude` | 更新:仅覆盖同步 Claude Code adapter |
147+
| `devcodex update --codex` | 更新:仅覆盖同步 Codex adapter |
132148
| `devcodex migrate-layout plan` | 生成 `.devcodex` 工作区集中布局迁移清单 |
133149
| `devcodex migrate-layout apply --manifest <path>` | 按 manifest 执行集中布局切换 |
134150
| `devcodex migrate-layout rollback --manifest <path>` | 回滚集中布局迁移 |
@@ -195,11 +211,12 @@ node /path/to/devcodex/index.js status
195211

196212
### 在 IDE 中验证规则自动生效
197213

198-
1. 在目标项目执行 `devcodex init`(默认同步 `.github/`,并链式部署 `CLAUDE.md + .claude/ + .mcp.json`)
214+
1. 在目标项目执行 `devcodex init`(默认同步 `.github/`,并链式部署 `CLAUDE.md + .claude/ + .mcp.json` 以及 `AGENTS.md + .agents/ + .codex/`)
199215
2. 重启 IDE
200216
3. Copilot:直接在 Copilot Chat 中输入普通需求,确认无需 `@DevCodex` 也会按规则工作
201217
4. Claude Code-only:仅需单独部署 Claude Code adapter 时执行 `devcodex init --claude`,随后新开会话并确认 `CLAUDE.md`、`.claude/settings.json`、`.mcp.json` 已生效
202-
5. 若在 VS Code 中启用了 Hooks,可在输出面板检查 `GitHub Copilot Chat Hooks`,确认 `.github/hooks/devcodex.lifecycle.json` 已被加载
218+
5. Codex-only:仅需单独部署 Codex adapter 时执行 `devcodex init --codex`,随后新开会话并确认 `AGENTS.md`、`.agents/skills/`、`.codex/hooks.json` 已生效
219+
6. 若在 VS Code 中启用了 Hooks,可在输出面板检查 `GitHub Copilot Chat Hooks`,确认 `.github/hooks/devcodex.lifecycle.json` 已被加载
203220

204221
### 文档站本地预览
205222

@@ -214,12 +231,13 @@ npm run dev
214231

215232
```
216233
devcodex/
217-
├── instructions.md # 单源规范文件;安装时按平台生成 copilot-instructions.md / CLAUDE.md
234+
├── instructions.md # 单源规范文件;安装时按平台生成 copilot-instructions.md / CLAUDE.md / AGENTS.md
218235
├── agents/ # Agent 源文件;Copilot 端默认分发,Claude Code 端不分发
219236
├── instructions/ # 全局 Instructions(12 个,含工作流规则摘要,自动注入)
220237
├── skills/ # Skill 详细检查标准(35 个,按 01-common §按需读取表 路由读取)
221238
├── prompts/ # Prompt 模板(26 个)
222239
├── hooks/ # Workspace Hooks 配置与分发到 `.github/hooks/_runtime/` 的运行时
240+
├── codex/ # Codex Hook 配置源,分发到 `.codex/hooks.json`
223241
├── data/ # 运行时数据模板(分发到目标项目的空骨架)
224242
│ ├── README.md
225243
│ └── templates/ # 空模板:violations / pending-fixes / pending-issues / process-improvements / gap-registry
@@ -237,11 +255,12 @@ devcodex/
237255
| **GitHub Copilot (JetBrains)** | 同上但无 hooks(instruction-fallback) | ⚠️ 仅文本约束 | ⚠️ 仅文本 | ❌ 未内置 MCP | 🟡 Beta |
238256
| **Claude Code (CLI/桌面端)** | `CLAUDE.md` + `.claude/{instructions,skills,prompts,hooks/_runtime,mcp}/` + `settings.json` hooks + `.mcp.json` | ✅ `lifecycle.cjs` v1.9.2+ | ✅ Hook | ✅ MCP | 🟢 Full |
239257
| **Cursor IDE** | 通过 `.github/instructions/` 兼容读取(实测) | ❌ 不支持 hooks | ⚠️ 仅文本 | ❌ | 🟡 Best-effort |
240-
| **ChatGPT / OpenAI Codex** | ❌ 无官方适配路径 | ❌ | ❌ | ❌ | 🔴 Unsupported |
258+
| **OpenAI Codex app/CLI** | `AGENTS.md` + `.agents/skills/` + `.codex/hooks.json` | ✅ `lifecycle.cjs` | ✅ Hook | ❌ 未内置 MCP | 🟡 Beta |
259+
| **ChatGPT 普通对话** | 不读取本地工作区 `AGENTS.md` / `.agents/` / `.codex/`;可手工粘贴规则 | ❌ | ⚠️ 文本 | ❌ | 🔴 Unsupported |
241260

242-
> **安装命令**:默认双部署 → `npx @vextjs/devcodex init`;仅 Claude Code adapter → `npx @vextjs/devcodex init --claude`(v1.9.0+);Codex → 暂无(如需要可手工复制 `prompts/` 模板使用,但无记忆/合规自动化)。
261+
> **安装命令**:默认三宿主部署 → `npx @vextjs/devcodex init`;仅 Claude Code adapter → `npx @vextjs/devcodex init --claude`(v1.9.0+);仅 Codex adapter → `npx @vextjs/devcodex init --codex`。
243262
>
244-
> **能力差异**:🟢 Full = 硬门禁 + MCP + 自动同步;🟡 Beta/Best-effort = 仅 instruction 注入,无运行时拦截;🔴 Unsupported = 不在当前发布范围。
263+
> **能力差异**:🟢 Full = 硬门禁 + MCP + 自动同步;🟡 Beta/Best-effort = 尚未达到 Full,具体能力以矩阵各列为准;🔴 Unsupported = 不在当前本地 adapter 发布范围。
245264
246265
## IDE 兼容性
247266

@@ -267,19 +286,20 @@ devcodex/
267286

268287
**DevCodex 适合用于**:
269288
- 团队/个人需要在多项目之间统一 AI 开发工作流
270-
- 希望 Copilot 或 Claude Code 在 dev / fix / audit 场景下遵守一致的 CP 门控、合规检查与报告产出
289+
- 希望 Copilot、Claude Code 或 Codex 在 dev / fix / audit 场景下遵守一致的 CP 门控、合规检查与报告产出
271290
- 需要持久化会话记忆、规范自修复机制(PC4)的协作流程
272291

273292
**DevCodex 不适合用于**:
274293
- 单次、一次性、无需规范约束的快速原型场景
275294
- 当前不在正式支持矩阵中的客户端/宿主(见 §客户端支持矩阵)
276-
- 对 `.github/` / `.claude/` 目录有其他强约束、无法接受 DevCodex 写入的项目
295+
- 对 `.github/` / `.claude/` / `.agents/` / `.codex/` / `AGENTS.md` 有其他强约束、无法接受 DevCodex 写入的项目
277296

278297
**前置条件**:
279298
- Node.js ≥ 18(CLI 零依赖,仅使用标准库)
280-
- 已启用目标宿主的规则加载能力(Copilot `Use Instruction Files` / Claude Code 标准项目规则加载)
299+
- 已启用目标宿主的规则加载能力(Copilot `Use Instruction Files` / Claude Code 标准项目规则加载 / Codex 工作区 `AGENTS.md` 加载)
281300
- Copilot 路径:已安装支持的 GitHub Copilot IDE(VS Code / JetBrains 全量支持;Visual Studio / Xcode / Eclipse 部分支持,详见 §IDE 兼容性)
282301
- Claude Code 路径:允许项目级 hooks 与 MCP(`init --claude` 会写入默认配置)
302+
- Codex 路径:允许工作区根 `AGENTS.md`、`.agents/skills/` 与 `.codex/hooks.json` 作为受管部署副本
283303

284304
## Tier 说明
285305

@@ -291,10 +311,11 @@ DevCodex 的 `plugin.json` 声明 `tier: "free"`,所有 Skill 均标注 `tier:
291311

292312
## Agent 入口
293313

294-
仓库内保留两个 Agent 文件(`agents/devcodex.agent.md`、`agents/devcodex-auto.agent.md`)供 IDE 直接调用;`v1.9.8` 起 Copilot 端默认安装会同步到 `.github/agents/`,Claude Code 端仍不分发 agents。标准使用路径是:
314+
仓库内保留两个 Agent 文件(`agents/devcodex.agent.md`、`agents/devcodex-auto.agent.md`)供 IDE 直接调用;`v1.9.8` 起 Copilot 端默认安装会同步到 `.github/agents/`,Claude Code 与 Codex 端仍不分发 agents。标准使用路径是:
295315

296316
- **推荐**:通过 `copilot-instructions.md` + `instructions/` 自动注入,直接在 Copilot Chat 对话即可
297317
- **可选**:通过 `.github/agents/` 使用 `@devcodex` / `@devcodex-auto` 自定义 Agent 入口
318+
- **Codex**:通过 `AGENTS.md` 自动注入总则,通过 `.agents/skills/` 按需读取技能;不单独维护 `codex/AGENTS.md`
298319

299320
Auto v1.1 当前只在支持 Hook 的宿主里,对显式 `@devcodex-auto` 入口下的白名单路径提供 runtime 级硬保证;JetBrains 等 `instruction-fallback` 宿主仅同步规则语义,不承诺完全等价的自动放行。
300321

‎RULES.md‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,29 @@
11
# DevCodex v1.11.0 — 使用入口
22

3-
> AI workflow injector for Copilot / Claude Code · publisher: Rocky · version: 1.11.0
3+
> AI workflow injector for Copilot / Claude Code / Codex · publisher: Rocky · version: 1.11.0
44
55
## 正式主支持客户端
66

77
- **Copilot**:通过 `copilot-instructions.md` + `instructions/` 自动加载,无需选择 Agent;若宿主支持并启用 Hooks,还会通过 `.github/hooks/` 提供确定性的生命周期护栏。
88
- **Claude Code**:通过 `CLAUDE.md` + `.claude/{instructions,skills,prompts,hooks/_runtime,mcp}/` + `.mcp.json` 自动生效;MCP、hooks 与 permissions 由 `devcodex init --claude` 一并写入。
9-
- Copilot 端默认分发 `.github/agents/` 作为可选显式入口;Claude Code 端仍通过 Skills 路由,不分发 agents。
9+
- **Codex**:通过 `AGENTS.md` + `.agents/skills/` + `.codex/hooks.json` 自动生效;Codex-only 部署由 `devcodex init --codex` 写入,`AGENTS.md` 与 Copilot/Claude 入口同源。
10+
- Copilot 端默认分发 `.github/agents/` 作为可选显式入口;Claude Code 与 Codex 端仍通过 Skills 路由,不分发 agents。
1011

11-
## 双入口加载机制
12+
## 三宿主加载机制
1213

13-
DevCodex 同时支持两种加载路径,规则语义保持一致,由 IDE 决定实际生效方式:
14+
DevCodex 同时支持三类宿主加载路径,规则语义保持一致,由 IDE/宿主决定实际生效方式:
1415

1516
- **默认路径**:Copilot 走 `.github/copilot-instructions.md` + `.github/instructions/*`;Claude Code 走 `CLAUDE.md` + `.claude/instructions/*`
17+
- **Codex 路径**:Codex 走工作区根 `AGENTS.md`,并从 `.agents/skills/*` 按需读取 Skill;`.codex/hooks.json` 承载 Hook 入口
1618
- **Agent 路径(可选)**:`@devcodex` / `@devcodex-auto` — Copilot 端 `.github/agents/` 默认分发后可用,提供全自动模式(CP 自动通过)
1719

18-
无论哪条路径进入,所有 Instructions 均通过 `applyTo: "**"` 全局生效;在 VS Code 中,workspace hooks 作为额外的宿主硬门禁层工作,不替代规则语义层。
20+
无论哪条路径进入,所有 Instructions 均通过同一 `instructions.md` / instructions 目录派生;在支持 Hook 的宿主中,workspace hooks 作为额外的宿主硬门禁层工作,不替代规则语义层。
1921

2022
## 宿主模式
2123

22-
- **Hook-First**:VS Code Hooks 可用时,通过 `.github/hooks/` 承载 bootstrap、危险操作护栏和结束前兜底
24+
- **Hook-First**:VS Code / Claude Code / Codex Hooks 可用时,通过对应宿主 hooks 承载 bootstrap、危险操作护栏和结束前兜底
2325
- **Instruction-Fallback**:Hooks 不可用时,继续依赖 instructions / skills 承载软约束
24-
- **当前首阶段实现**:Hook 运行时由 `init/update` 一并分发到 `.github/hooks/_runtime/`,不要求目标项目从 `node_modules/@vextjs/devcodex/...` 读取脚本
26+
- **当前实现**:Hook 运行时由 `init/update` 一并分发到 `.github/hooks/_runtime/`、`.claude/hooks/_runtime/` 与 `.codex/hooks/_runtime/`,不要求目标项目从 `node_modules/@vextjs/devcodex/...` 读取脚本
2527

2628
## 正式需求与执行模板边界
2729

‎changelogs/unreleased.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,15 @@
66
77
---
88

9+
## 2026-05-27
10+
11+
- 新增 Codex adapter:默认 `devcodex init/update` 升级为 Copilot + Claude Code + Codex 三宿主同步,`--codex` 提供 Codex-only 路径并与 `--claude` 互斥。
12+
- 补齐 Codex 入口与 Hook 链路:`instructions.md` 同源生成 `AGENTS.md`,`skills/` 同步到 `.agents/skills/`,新增 `codex/hooks.json` 并同步统一 `lifecycle.cjs` 到 `.codex/hooks/_runtime/`。
13+
- 修复 Codex 新会话无预检查风险:`UserPromptSubmit` 输出同时包含 `systemMessage` 与 `hookSpecificOutput.additionalContext`,并新增 Hook runtime 回归测试。
14+
- 扩展发布前校验:V6/V8/V13/V24 与 pack-clean 覆盖 Codex 打包资产、部署副本哈希、Hook 语义探针、文档/Profile 口径和 workspace adapter 同步状态。
15+
- 修复 Codex 边界诊断与文档口径:multi-project warning 同步注入 `additionalContext`,`status/doctor` 增加 Codex hook command 与 config/trust 诊断,README 支持矩阵区分 OpenAI Codex 与 ChatGPT 普通对话。
16+
- 修复记忆与报告 `<agent>` 落点规则:当前实际宿主优先,`profile/config.json` 的 `agent` 仅作为无法识别宿主时的兜底提示,并补 MCP/validate 回归探针。
17+
918
## 2026-05-26
1019

1120
- 澄清 init/update 同步语义:默认 `init/update` 会同步 Copilot `.github/` 并链式部署 Claude Code adapter,`--claude` 为 Claude-only 路径;同步更新 README、CLI help 与项目 Profile。

‎codex/hooks.json‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
{
2+
"hooks": {
3+
"PreToolUse": [
4+
{
5+
"matcher": "",
6+
"hooks": [
7+
{
8+
"type": "command",
9+
"command": "node ./.codex/hooks/_runtime/lifecycle.cjs"
10+
}
11+
]
12+
}
13+
],
14+
"UserPromptSubmit": [
15+
{
16+
"hooks": [
17+
{
18+
"type": "command",
19+
"command": "node ./.codex/hooks/_runtime/lifecycle.cjs"
20+
}
21+
]
22+
}
23+
],
24+
"PostToolUse": [
25+
{
26+
"matcher": "",
27+
"hooks": [
28+
{
29+
"type": "command",
30+
"command": "node ./.codex/hooks/_runtime/lifecycle.cjs"
31+
}
32+
]
33+
}
34+
],
35+
"Stop": [
36+
{
37+
"hooks": [
38+
{
39+
"type": "command",
40+
"command": "node ./.codex/hooks/_runtime/lifecycle.cjs"
41+
}
42+
]
43+
}
44+
]
45+
}
46+
}

0 commit comments

Comments
 (0)