Skip to content

Commit 7c8393f

Browse files
committed
fix: tighten codex host coverage and docs
1 parent c47814d commit 7c8393f

8 files changed

Lines changed: 158 additions & 3 deletions

File tree

‎README.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -184,6 +184,8 @@ AGENTS.md ← 与 instructions.md / copilot-instructions.md / CL
184184
| `devcodex migrate-layout apply --manifest <path>` | 按 manifest 执行集中布局切换 |
185185
| `devcodex migrate-layout rollback --manifest <path>` | 回滚集中布局迁移 |
186186
| `devcodex status` | 状态:检查已安装的组件 |
187+
| `devcodex doctor` | 诊断当前宿主、Agent、Hook、Profile 与记忆状态 |
188+
| `devcodex help` | 查看 CLI 子命令与选项帮助 |
187189
| `devcodex init --dry-run` | 预览模式:仅显示将复制的文件 |
188190

189191
## `.devcodex` 工作区集中布局(v1.10.0+)
@@ -305,6 +307,16 @@ README / 用户使用文档当前补充两类专项 Skill:`readme-authoring`
305307
> **安装命令**:默认三宿主部署 → `npx @vextjs/devcodex init`;仅 Claude Code adapter → `npx @vextjs/devcodex init --claude`(v1.9.0+);仅 Codex adapter → `npx @vextjs/devcodex init --codex`。
306308
>
307309
> **能力差异**:🟢 Full = 已验证 Hook 事件 + MCP + 自动同步;🟡 Beta/Best-effort = 尚未达到 Full,具体能力以矩阵各列为准;🔴 Unsupported = 不在当前本地 adapter 发布范围。默认 `safety-only` 下,bootstrap / CP / auto 白名单等流程问题为提醒并继续,仅危险命令硬拦;设置 `DEVCODEX_HOOK_ENFORCEMENT=strict` 后,支持硬拦的事件才会停止流程。
310+
>
311+
> **MCP 边界**:`.mcp.json` 是 Claude Code adapter 的自动写入文件;DevCodex 当前不会为 Copilot 或 Codex 自动写入 MCP manifest。若 Copilot / Codex 宿主后续支持本地 MCP,请按宿主能力手工配置,再用 `devcodex doctor` 或宿主自带诊断命令核对状态。
312+
313+
## 运行时配置
314+
315+
| 配置项 | 默认值 | 说明 |
316+
|--------|--------|------|
317+
| `DEVCODEX_HOOK_ENFORCEMENT` | `safety-only` | `safety-only` 只对危险命令硬拦,流程类问题提醒放行;`strict` 会对宿主支持硬拦的事件启用更严格的 runtime 阻断 |
318+
319+
> 建议:默认先保持 `safety-only`;只有在团队已验证宿主 Hook 事件覆盖度后,再切到 `strict`。
308320
309321
### Hook 拦截动作语义
310322

@@ -319,6 +331,24 @@ DevCodex Hook runtime 不再把所有拦截都等同为“停止”。拦截会
319331

320332
> 宿主输出契约:Claude Code 与 Codex 的非工具事件不复用工具级 `hookSpecificOutput.permissionDecision`。Codex `Stop/UserPromptSubmit` 使用顶层 `decision:"block"`,`PreCompact` 使用 `continue:false`;工具调用拦截才使用 `permissionDecision`。
321333
334+
## 常见问题与排错
335+
336+
1. **Hook 没生效 / 规则看起来没加载**
337+
- 先运行 `devcodex doctor`
338+
- 再核对当前宿主是否真的支持本地 Hook 硬拦,以及目标项目是否已重新打开会话
339+
2. **Profile 没加载或 workspace-namespace 路径不对**
340+
- 先运行 `devcodex doctor`
341+
- 再用 `devcodex help` 查看 `profile init` 和 `migrate-layout` 子命令,核对 `.devcodex/workspace/profile/` 与项目命名空间路径
342+
3. **Codex / Copilot 想用 MCP**
343+
- 先确认宿主本身是否支持本地 MCP
344+
- DevCodex 当前只会自动写 Claude Code 的 `.mcp.json`;Codex / Copilot 需要手工配置
345+
4. **CP 卡住或只看到提醒不拦截**
346+
- 先确认当前是否处于 `safety-only`
347+
- 如需更严格的流程门禁,再评估是否启用 `DEVCODEX_HOOK_ENFORCEMENT=strict`
348+
5. **不知道该跑哪个诊断命令**
349+
- `devcodex doctor` 看宿主 / Hook / Profile / 记忆状态
350+
- `devcodex help` 看 CLI 子命令与参数说明
351+
322352
## IDE 兼容性
323353

324354
> v1.9.6+ 与上方"客户端支持矩阵"语义对齐:✅=自动加载且经实测;⚠️=加载但能力降级或未实测;❌=不支持。Hooks 列仅代表宿主是否具备可接入 Hook 事件,不代表所有 DevCodex 规则都能硬拦。

‎agents/README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,3 +38,9 @@
3838
## 与 Instructions 路径的关系
3939

4040
Agent 路径与默认 copilot-instructions 路径**两者规则完全一致**,由 IDE 决定实际生效方式(参见 `RULES.md §双入口加载机制`)。选择 Agent 路径不会改变 Instructions 的优先级与加载顺序。
41+
42+
## 与 `plugin.json` 的边界
43+
44+
- `agents/*.agent.md` 是 **Copilot 兼容的显式 Agent 入口**,解决的是“用户如何显式选择 `@devcodex` / `@devcodex-auto`”。
45+
- `plugin.json` 是 **DevCodex 内部注册表**:用于描述 skills / instructions / prompts / agents 的分发与打包元数据,不是 Copilot、Claude Code 或 Codex 直接读取的 Agent 入口文件。
46+
- 维护时若看到两处都提到 Agent,不应混为同一层:`.agent.md` 负责“入口体验”,`plugin.json` 负责“包内清单与元数据”。

‎instructions/01-common.instructions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -167,7 +167,7 @@ applyTo: "**"
167167
| audit.需求文档 | `audit-common` · `audit-requirements` · `audit-session` |
168168
| audit.项目工程 | `audit-common` · `audit-project` · `audit-session` |
169169
| audit.报告 | `audit-common` · `audit-report` · `audit-session` |
170-
| audit.通用文档 | `audit-common` · `audit-document` · `audit-session` |
170+
| audit.通用文档 | `audit-common` · `audit-document` · `audit-session`(README / 用户使用文档额外叠加 `audit-readme`) |
171171
| analyze.default | (Instruction 已完整,无需额外 Skill)|
172172
| analyze.research | `analyze-research` |
173173
| self-fix | (Instruction 已完整,无需额外 Skill)|

‎instructions/12-audit.instructions.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ applyTo: "**"
3434
| 需求文档/PRD | 需求文档 |
3535
| 项目工程/代码质量 | 项目工程 |
3636
| 报告文件 | 报告 |
37-
| 一般文档 | 通用文档 |
37+
| 一般文档 | 通用文档(README / 用户使用文档额外叠加 `audit-readme`) |
3838

3939
- 基于用户意图智能识别,不依赖关键词
4040

@@ -166,3 +166,5 @@ applyTo: "**"
166166
- A — 内容 🔴:DA-1 结构完整性 · DA-2 内容准确性
167167
- B — 引用 🔴/🟡:DA-3 引用有效性 · DA-4 术语一致性
168168
- C — 受众 💡/🔴:DA-5 受众适配 · DA-6 关联一致性
169+
170+
> README / 用户使用文档不单独开新的第 7 类审查目标,仍归入“通用文档”;但执行时必须在 `audit-document` 基础上额外叠加 `audit-readme`,补做 `RM-1~RM-6` 用户路径、快速开始、排错与消费链一致性检查。

‎scripts/test-cli-behavior.js‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,26 @@ function assertRuntimeDataBootstrap(runtimeRoot) {
111111
}
112112
}
113113

114+
function assertCodexAdapterState(root) {
115+
const sourceInstructions = fs.readFileSync(path.join(ROOT, 'instructions.md'), 'utf8')
116+
const agentsMd = fs.readFileSync(path.join(root, 'AGENTS.md'), 'utf8')
117+
const hooks = readJson(root, '.codex/hooks.json')
118+
const sourceSkillFiles = walk(path.join(ROOT, 'skills')).filter(file => path.basename(file) === 'SKILL.md')
119+
const installedSkillFiles = walk(path.join(root, '.agents', 'skills')).filter(file => path.basename(file) === 'SKILL.md')
120+
121+
assert.strictEqual(agentsMd, sourceInstructions)
122+
assert.strictEqual(installedSkillFiles.length, sourceSkillFiles.length)
123+
assert.ok(fs.existsSync(path.join(root, '.agents', 'skills', 'routing', 'SKILL.md')))
124+
assert.ok(fs.existsSync(path.join(root, '.codex', 'hooks', '_runtime', 'lifecycle.cjs')))
125+
126+
for (const eventName of ['PreToolUse', 'UserPromptSubmit', 'PostToolUse', 'Stop']) {
127+
const entries = hooks.hooks?.[eventName]
128+
assert.ok(Array.isArray(entries) && entries.length > 0, `missing Codex hook event: ${eventName}`)
129+
const commands = JSON.stringify(entries)
130+
assert.ok(commands.includes('node ./.codex/hooks/_runtime/lifecycle.cjs'), `unexpected hook command for ${eventName}`)
131+
}
132+
}
133+
114134
function assertClaudeMergeState(root, { claudeMdManaged }) {
115135
const settings = readJson(root, '.claude/settings.json')
116136
const mcp = readJson(root, '.mcp.json')
@@ -149,6 +169,7 @@ function testClaudeInitPreservesCustomConfig() {
149169

150170
runCli(['init', '--claude'], root)
151171
assertClaudeMergeState(root, { claudeMdManaged: false })
172+
assertRuntimeDataBootstrap(path.join(root, '.devcodex'))
152173

153174
const backupRoot = path.join(root, '.devcodex', '.tmp', 'backups')
154175
assert.strictEqual(findBackups(backupRoot, 'CLAUDE.md').length, 0)
@@ -164,6 +185,7 @@ function testClaudeUpdateBacksUpAndPreservesCustomConfig() {
164185

165186
runCli(['update', '--claude'], root)
166187
assertClaudeMergeState(root, { claudeMdManaged: true })
188+
assertRuntimeDataBootstrap(path.join(root, '.devcodex'))
167189

168190
const backupRoot = path.join(root, '.devcodex', '.tmp', 'backups')
169191
assert.ok(findBackups(backupRoot, 'CLAUDE.md').length >= 1)
@@ -217,6 +239,51 @@ function testCodexInitBootstrapsWorkspaceNamespaceData() {
217239
fs.rmSync(root, { recursive: true, force: true })
218240
}
219241

242+
function testCodexInitBacksUpManagedFiles() {
243+
const root = createTempRoot('devcodex-cli-codex-init-')
244+
writeFile(root, 'package.json', '{ "name": "tmp-codex-init" }\n')
245+
writeFile(root, 'AGENTS.md', '# custom agents instructions\n')
246+
writeJson(root, '.codex/hooks.json', {
247+
hooks: {
248+
Stop: [{ hooks: [{ type: 'command', command: 'echo custom-stop' }] }]
249+
}
250+
})
251+
252+
runCli(['init', '--codex'], root)
253+
254+
assertCodexAdapterState(root)
255+
assertRuntimeDataBootstrap(path.join(root, '.devcodex'))
256+
257+
const backupRoot = path.join(root, '.devcodex', '.tmp', 'backups')
258+
assert.ok(findBackups(backupRoot, 'AGENTS.md').length >= 1)
259+
assert.ok(findBackups(backupRoot, 'hooks.json').length >= 1)
260+
261+
fs.rmSync(root, { recursive: true, force: true })
262+
}
263+
264+
function testCodexUpdateRefreshesAdapterInWorkspaceNamespace() {
265+
const root = createTempRoot('devcodex-cli-codex-update-')
266+
writeJson(root, '.devcodex/layout.json', { version: 1, mode: 'workspace-namespace' })
267+
writeFile(root, 'packages/app-a/package.json', '{ "name": "app-a" }\n')
268+
writeFile(root, 'packages/app-a/AGENTS.md', '# stale codex agent\n')
269+
writeJson(root, 'packages/app-a/.codex/hooks.json', {
270+
hooks: {
271+
UserPromptSubmit: [{ hooks: [{ type: 'command', command: 'echo stale-command' }] }]
272+
}
273+
})
274+
275+
runCli(['update', '--codex'], path.join(root, 'packages', 'app-a'))
276+
277+
assertCodexAdapterState(path.join(root, 'packages', 'app-a'))
278+
assertRuntimeDataBootstrap(path.join(root, '.devcodex', 'packages', 'app-a'))
279+
280+
const backupRoot = path.join(root, '.devcodex', 'packages', 'app-a', '.tmp', 'backups')
281+
assert.ok(findBackups(backupRoot, 'AGENTS.md').length >= 1)
282+
assert.ok(findBackups(backupRoot, 'hooks.json').length >= 1)
283+
284+
fs.rmSync(root, { recursive: true, force: true })
285+
}
286+
220287
function testProfileInitUsesNestedNamespaceRoot() {
221288
const root = createTempRoot('devcodex-cli-profile-')
222289
writeJson(root, '.devcodex/layout.json', { version: 1, mode: 'workspace-namespace' })
@@ -239,6 +306,8 @@ function main() {
239306
testDoctorAvoidsCodexBiasInMixedHostRepo()
240307
testDefaultInitBootstrapsActiveRootData()
241308
testCodexInitBootstrapsWorkspaceNamespaceData()
309+
testCodexInitBacksUpManagedFiles()
310+
testCodexUpdateRefreshesAdapterInWorkspaceNamespace()
242311
testProfileInitUsesNestedNamespaceRoot()
243312
process.stdout.write('cli behavior test passed\n')
244313
}

‎scripts/validate.js‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2435,6 +2435,46 @@ function checkV42() {
24352435
console.log('[V42] release gate / package completeness sync checked')
24362436
}
24372437

2438+
function checkV43() {
2439+
const probes = [
2440+
{
2441+
file: 'README.md',
2442+
needles: ['devcodex doctor', 'devcodex help', '## 常见问题与排错', 'DEVCODEX_HOOK_ENFORCEMENT', 'MCP 边界']
2443+
},
2444+
{
2445+
file: 'agents/README.md',
2446+
needles: ['plugin.json', 'DevCodex 内部注册表', '.agent.md']
2447+
},
2448+
{
2449+
file: 'instructions/01-common.instructions.md',
2450+
needles: ['audit-readme', 'README / 用户使用文档额外叠加']
2451+
},
2452+
{
2453+
file: 'instructions/12-audit.instructions.md',
2454+
needles: ['audit-readme', 'README / 用户使用文档不单独开新的第 7 类审查目标']
2455+
},
2456+
{
2457+
file: 'skills/routing/SKILL.md',
2458+
needles: ['audit-readme', 'README / 用户使用文档额外叠加']
2459+
},
2460+
{
2461+
file: 'website/docs/guide/development.md',
2462+
needles: ['devcodex doctor', 'DEVCODEX_HOOK_ENFORCEMENT', '.mcp.json']
2463+
}
2464+
]
2465+
2466+
for (const probe of probes) {
2467+
const content = read(path.join(ROOT, probe.file))
2468+
for (const needle of probe.needles) {
2469+
if (!content.includes(needle)) {
2470+
err(`[V43] host docs / README audit route drift in ${probe.file}: missing "${needle}"`)
2471+
}
2472+
}
2473+
}
2474+
2475+
console.log('[V43] host docs / README audit route sync checked')
2476+
}
2477+
24382478
function checkV29() {
24392479
const probes = [
24402480
{
@@ -2690,6 +2730,7 @@ checkV39()
26902730
checkV40()
26912731
checkV41()
26922732
checkV42()
2733+
checkV43()
26932734

26942735
console.log('')
26952736
if (errors.length) {

‎skills/routing/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ description: 定义意图识别结果到工作流的路由映射。本 Skill 为
4848
| audit | 需求文档 | `skills/audit-requirements/SKILL.md` |
4949
| audit | 项目工程 | `skills/audit-project/SKILL.md` |
5050
| audit | 报告 | `skills/audit-report/SKILL.md` |
51-
| audit | 通用文档 | `skills/audit-document/SKILL.md` |
51+
| audit | 通用文档 | `skills/audit-document/SKILL.md`(README / 用户使用文档额外叠加 `skills/audit-readme/SKILL.md`) |
5252

5353
## 特殊路由规则
5454

‎website/docs/guide/development.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -154,6 +154,13 @@ Hook / CLI / visible reply / sticky project / workspace guard 相关任务还要
154154

155155
`.devcodex/**/profile/config.local.json` 用于本地私有 overlay:长期连接、env 引用、受控扩展位 `extensions.<namespace>`。它不替代 `config.json`,也不能覆盖 `mode` / `agent` / `pluginVersion`。若项目使用了本地连接别名或扩展位,需在 `01-项目信息.md` 或 Profile README 说明用途、字段语义和使用方式。
156156

157+
### 诊断与排错入口
158+
159+
- `devcodex doctor`:查看当前宿主、Hook、Profile、记忆与 adapter 状态,适合先判断“规则到底有没有加载”
160+
- `devcodex help`:查看 CLI 子命令与参数,尤其是 `profile init`、`migrate-layout`、`init/update --claude/--codex`
161+
- `DEVCODEX_HOOK_ENFORCEMENT`:默认 `safety-only`,仅危险命令硬拦;切到 `strict` 前应先确认宿主确实支持对应 Hook 事件
162+
- `.mcp.json` 目前只由 Claude Code adapter 自动写入;Codex / Copilot 若宿主支持 MCP,需要手工配置,不能把 Claude 的 `.mcp.json` 当成三宿主通用入口
163+
157164
### 推荐结论与确认交互
158165

159166
分析、审计或执行报告存在多个建议/路径时,必须给出推荐结论与推荐理由;没有后续动作时写明“推荐:无后续动作”。用户确认先抽象为 ConfirmationRequest,再按宿主能力使用按钮、权限提示、Hook 阻断或文本确认 fallback。

0 commit comments

Comments
 (0)