feat: add Codex plugin compatibility layer (skills + hooks + manifest) - #136
feat: add Codex plugin compatibility layer (skills + hooks + manifest)#136laserduor wants to merge 5 commits into
Conversation
Add Codex plugin support alongside existing OpenCode plugin: - .codex-plugin/plugin.json — Codex plugin manifest - skills/ — 8 flow-* skill symlinks + 5 agent SKILL.md files (agent-dev-lifecycle, agent-architect, agent-developer, agent-reviewer, agent-goal-verify) - hooks/hooks.json + hooks/session-start.ts — SessionStart hook injecting skill overview and project context - package.json — updated keywords and description The Codex layer is purely additive: it reuses the same assets/skills/ and assets/agents/ content, repackaged as Codex-compatible skills. No existing OpenCode functionality is modified.
devcxl
left a comment
devcxl
left a comment
There was a problem hiding this comment.
审核结论：CHANGES_REQUESTED
整体方向可行：纯 Prompt 架构下用 skills + hooks + manifest 做 Codex 兼容层，未侵入现有 OpenCode 代码。但当前实现有 4 个阻断级问题，合并前需要修复。
1. [CRITICAL] SessionStart hook 指向不存在的构建产物
hooks/hooks.json 中命令为 node ${PLUGIN_ROOT}/dist/hooks/session-start.js，但 hooks/session-start.ts 位于仓库根 hooks/ 目录，而 tsconfig.json 的 rootDir 是 src、include 只有 src/**/*.ts，npm run build 不会编译它，PR 也未提交编译后的 JS。插件安装后 hook 必然失败，上下文注入完全失效。
修复建议：把源文件移入 src/hooks/session-start.ts 纳入现有 tsc 构建（生成 dist/hooks/session-start.js），并给 hook 配置合理 timeout。
2. [HIGH] npm 发布包不包含任何 Codex 插件文件
package.json 的 files 只含 dist、assets、README.md，.codex-plugin/、skills/、hooks/ 均不在包内（已用 npm pack --dry-run 验证）。项目发布走 GitHub Actions npm publish，按现有流程发布后插件只剩空壳。
修复建议：files 增加 .codex-plugin、skills、hooks；或为 Codex 增加独立的 git/marketplace 分发入口并补充安装说明。
3. [HIGH] skills/ 下的 flow-* symlink 在插件导入时会被忽略
Codex 插件打包校验规则明确有 skill_symlink_ignored：skills/ 下直接放符号链接不会被识别为 skill，必须是包含 SKILL.md 的真实目录。若该兼容层要提交到插件目录，8 个 flow skills 会全部缺失。
修复建议：发布场景下复制为真实目录；若仅限 git 仓库内使用，请在 PR 中明确边界。
4. [HIGH] agent skills 仍依赖 OpenCode 内核，Codex 中不可执行
5 个 agent SKILL.md 沿用了 OpenCode 内核专属机制：
goal({op:"create", parent_issue_number:...})与goal({op:"complete"})：这是src/plugin/goal.ts提供的工具语法，Codex 没有同名同参工具；- 每次 idle 自动注入 continuation prompt：Codex 无此机制；
- autoResume 恢复：Codex 无此语义；
- 通过 Task 工具派发 @agent-goal-verify 并限制完成权限：这些在 Codex 中是 skills 而非 agents，权限约束无法强制。
flow skills（纯 git/gh prompt）基本可复用，但 agent-dev-lifecycle 与 agent-goal-verify 在 Codex 中按字面执行会卡住。需要适配 Codex 的 goal 工具接口，或声明兼容层仅支持纯 Prompt 流程并把 goal/continuation 依赖移出。
5. [MEDIUM] manifest 元数据不合法
interface.category: "Development"不在官方枚举中，应改为Developer Tools，否则提交目录会被plugin_category_unknown拒绝；interface.defaultPrompt第一条引用@dev-lifecycle，实际 skill 名是agent-dev-lifecycle；且官方禁止 starter prompts 含 app @mention，提交时可能被拒。
6. [MEDIUM] 无 CI 覆盖且当前 CI 未运行
该 PR 无任何 checks 结果；现有 CI 也覆盖不到新文件：prompt-lint 只扫 assets/，typecheck 不包含 hooks/。合并前应触发 CI，并考虑新增校验（manifest/hooks JSON 解析、hook 构建产物存在性、symlink 目标存在）。
7. [LOW] 其他
- 多个新文件缺末尾换行；
- hook 从仓库子目录启动时
process.cwd()取不到根 AGENTS.md； - 这是 feature 变更，按 Release Profile 应 bump minor（1.2.0），发布时
.codex-plugin/plugin.json的 version 需与 package.json 同步； - 仓库文档未说明 Codex 安装方式，也没有 marketplace 条目。
合并前验证清单
- 修复后
npm run build确认dist/hooks/session-start.js存在并可运行； npm run typecheck、npm test、npm run prompt-lint全绿；- 通过本地 marketplace 真实安装一次，确认 13 个 skill 可发现、SessionStart hook 生效；
- 若走 npm 分发，
npm pack --dry-run确认.codex-plugin/、skills/、hooks/、dist/hooks/均在包内。
Fix all 7 review items from PR devcxl#136: [CRITICAL] hooks/session-start.ts moved into src/hooks/ and compiled by tsc (rootDir=src). dist/hooks/session-start.js is now in the build output and referenced by hooks/hooks.json. Added timeoutMs: 10000. [HIGH] package.json files now includes .codex-plugin, skills, hooks. Verified with npm pack --dry-run that all required files are in tarball. [HIGH] flow-* symlinks replaced with real SKILL.md copies (Codex plugin validation rejects symlinks in skills/). [HIGH] agent-dev-lifecycle and agent-goal-verify adapted for Codex: - Removed goal({op:...}) dependencies (not available in Codex) - Replaced with Issue-based progress tracking (gh issue edit, checklist) - Removed continuation/autoResume references (Codex has no such mechanism) - agent-goal-verify now reads Issue body directly instead of goal tool [MEDIUM] manifest fixes: - category: "Development" → "Developer Tools" (official Codex enum) - defaultPrompt: removed @dev-lifecycle mention (actual skill name is agent-dev-lifecycle), removed forbidden @ mentions [MEDIUM] tsconfig.json: added exclude for node_modules and dist [LOW] hooks/hooks.json: added timeoutMs, trailing newlines
|
@devcxl 你好，感谢 review！你指出的 4 个 blocking 问题（SessionStart hook 构建产物、npm 包 files、flow-* symlink、agent skills 依赖 OpenCode 内核）已在提交
typecheck / test / build / prompt-lint 全部通过。麻烦有空重新 review 一下，谢谢！ |
devcxl
left a comment
devcxl
left a comment
There was a problem hiding this comment.
对照 OpenAI 官方 Codex 文档（Hooks / Build plugins）逐项核验过。整体方向正确：manifest 字段全部符合官方 schema、skills/ 与 hooks/hooks.json 是官方默认发现路径、${PLUGIN_ROOT} 展开受支持、SessionStart 钩子 stdout 纯文本会注入为 developer context。以下问题建议修复后再合。
[HIGH] hooks.json 使用了不存在的 timeoutMs 字段
官方文档仅支持 timeout（单位秒，示例 "timeout": 3）。timeoutMs: 10000 会被忽略并回落到默认 600s——钩子卡住时会拖住会话启动长达 10 分钟。请改为 "timeout": 10。
[HIGH] PR 描述称 flow- 为 symlink，实际是全量拷贝*
diff 中为 13 个新增普通文件（mode 100644），已逐字比对 skills/flow-tdd/SKILL.md 与 assets/skills/flow-tdd/SKILL.md 完全一致。双份副本会导致上游修改后静默漂移。建议三选一：① CI 增加 drift 检查（对比两份文件哈希）；② 改为真实 symlink（注意 npm pack 对符号链接的处理与 Windows 兼容性）；③ 在 prepublishOnly 构建时由 assets 生成副本。
[HIGH] 覆盖缺口：flow-research 与 researcher agent 未移植
assets/skills/ 下实际有 9 个 flow skills（含 flow-research），assets/agents/ 下有 6 个 agent prompt（含 researcher），本 PR 仅覆盖 8 + 5。若为有意裁剪请在描述中说明；否则请补齐，避免用户从 OpenCode 切到 Codex 时静默丢失能力。
[MEDIUM] 新增根目录 skills/ 可能被 OpenCode 侧重复加载
OpenCode 插件显式将 assets/skills 注册进 config.skills.paths，但 OpenCode 对插件包根目录 skills/ 存在自动发现机制，届时 flow-* 技能会重复注册、同名冲突。合并前请实测：打包安装到 OpenCode 后检查技能列表。若冲突，可将 manifest skills 指向其他目录名（官方允许任意 ./ 相对路径）。
[MEDIUM] 技能内残留 OpenCode 专属概念，在 Codex 上为死引用
① flow-* 的 Contract Trigger 引用的 /setup、/design、/tasks、/code、/review、/release 为 OpenCode commands，本次未移植；② agent-reviewer 中"不调用 goal({op:"complete"})"——goal tool 是 OpenCode 插件内核能力，Codex 上不存在。建议在 agent-dev-lifecycle 或 README 增加"平台差异"说明：Codex 侧无 goal 工具、无 slash commands、无自动续接，为纯 prompt 降级版本。
[MEDIUM] README 未更新
缺少 Codex 安装说明、钩子需在 /hooks 中完成信任审核的提示、以及本地安装需先 npm run build（钩子产物在 dist 中）的说明。
[MEDIUM] 缺少测试
建议补充：① plugin.json / hooks.json 结构校验测试；② skills/ 与 assets/skills 的 drift 测试；③ 扩展 test:pack 断言 tarball 包含 .codex-plugin/plugin.json、skills/、hooks/hooks.json（同时验证 npm 未过滤 .codex-plugin 点目录）。
[LOW] 细节
- manifest 中
"hooks": "./hooks/hooks.json"冗余（默认路径自动加载），可删除 version: "1.1.0"在 plugin.json 与 package.json 双份硬编码，建议测试断言一致防漂移session-start.ts：readFileSync无 try/catch（AGENTS.md 不可读时钩子直接崩溃）；正则/## Project Profile[\s\S]*?(?=##|$)/会误匹配## Project Profile Notes类标题；输出无大小上限- SessionStart 未配置 matcher，compact 时也会重复注入整段 context，建议
"matcher": "startup|resume" - PR 描述"零侵入"与实际修改 package.json、tsconfig.json 不符，措辞建议调整
…-research/researcher, harden hooks - skills/ → codex-skills/：避开 OpenCode 插件包 skills/ 自动发现导致的重复注册（manifest 允许任意相对路径） - 补齐 flow-research + agent-researcher（同步上游新增的 research 能力） - 同步 agent-dev-lifecycle 至上游最新：Phase 0 场景分诊 + Testing Decisions 兼容门 + 平台差异说明 - hooks.json：timeoutMs → timeout（秒），SessionStart 加 matcher startup|resume - session-start.ts：精确匹配 ## Project Profile、readFileSync try/catch、输出大小上限 - 新增 test/plugin/codex-compat.test.ts：manifest/hooks 结构校验、version 一致性、skills drift 防漂移 - test:pack 断言 tarball 含 .codex-plugin/codex-skills/hooks/dist-hooks；CI 增加 test:pack - README 补 Codex 安装说明（build、hook 信任审核、平台差异）
|
@devcxl 感谢第二轮详细 review！已全部处理完毕并推送（commit 85b624b，分支已 merge 最新 origin/main）。逐项说明： [HIGH] timeoutMs → timeout ✅ [HIGH] flow- 双份拷贝漂移* ✅ [HIGH] flow-research 与 researcher 未移植 ✅ [MEDIUM] 根目录 skills/ 被 OpenCode 重复加载 ✅ [MEDIUM] 技能内 OpenCode 专属概念 ✅ [MEDIUM] README 未更新 ✅ [MEDIUM] 缺少测试 ✅ [LOW] 细节 ✅
version：保持 1.1.0（按 Release Profile 由 release workflow 统一 bump），测试断言 plugin.json 与 package.json 版本一致防漂移。 本地 npm test（202 passed）/ typecheck / prompt-lint / build / test:pack 全部通过。麻烦再 review 一次，谢谢！ |
devcxl
left a comment
devcxl
left a comment
There was a problem hiding this comment.
第三轮审查结论：APPROVE ✅
针对 commit 85b624b9（第二轮 review 后的修复）逐项核验，第二轮提出的问题全部落地且有测试兜底：
✅ 已修复
- hooks.json：
timeoutMs→timeout: 10（秒制），新增matcher: "startup|resume"防 compact 重复注入 skills/→codex-skills/重命名，规避 OpenCode 侧自动发现导致的重复加载- 补齐
flow-research+agent-researcher（flow 9/9、agent 6/6 全覆盖） agent-dev-lifecycle重写（159→309 行）：新增「平台差异」章节，明确无 goal 工具/无 slash commands/无自动续接/agent 即 skill；goal({op:...})引用在 dev-lifecycle 与 reviewer 中全部清除- README 新增 Codex Installation 章节（build 先决条件、
/hooks信任审核、平台差异说明） - 新增
test/plugin/codex-compat.test.ts（158 行）：manifest 结构/版本同步/category 枚举、hooks 结构（timeout 秒制、matcher、dist 产物）、flow- drift 检查*（9/9 覆盖 + agent-ref 归一化比对）、无 OpenCode 内核构造（goal/continuation/autoResume） - CI 增加
test:pack，验证 tarball 含.codex-plugin/、codex-skills/、hooks/、dist/hooks/ - session-start.ts：readFileSync try/catch、精确匹配
## Project Profile标题、输出 12000 字符截断
⚠️ 非阻塞观察
- codex-skills 与 assets/skills 仍为双份拷贝（有意保留
@agent-*命名差异），drift 测试已兜底；后续上游 assets 变更时需同步更新（或考虑脚本生成） - flow-design/flow-tasks 等 Contract Trigger 仍引用
/design、/tasks等 OpenCode 命令——Codex 上不存在，但 agent-dev-lifecycle 的平台差异章节已说明，属轻微文档残留 - PR 分支尚无 CI 运行记录（fork PR 需手动批准 workflow），合并前建议触发一次 CI 确认 test:pack 通过
合并前验证清单：① 触发 CI 全绿（typecheck/test/build/test:pack）；② npm pack --dry-run 确认 tarball 含全部 Codex 文件（test:pack 已覆盖）；③ 本地 marketplace 安装后 15 个 skill 可发现。
|
@laserduor 你好，项目已发布 v1.2.0（今天），你的分支与新版 main 出现了冲突，麻烦 rebase 一下： 冲突文件（仅 2 处，都很简单）：
适配情况说明（已核验，无需担心）：
rebase 后：触发一次 CI（fork PR 的 workflow 需要仓库方批准，跑绿即可），确认 |
- package.json version 1.2.0（跟随已发布版本），files 保留 codex-skills/hooks - README：Codex Installation 章节与 v1.2.0 badges/计数合并 - .codex-plugin/plugin.json version 同步 1.2.0（测试断言双份一致） - npm test 249 passed / typecheck / prompt-lint / test:pack 全绿
|
@devcxl 冲突已解决并推送（commit 6fa7231），PR 现在 MERGEABLE ✅ 处理内容：
验证： 本地 CI 已随 push 触发，跑绿后就可以合并了，谢谢！ |
2 participants
概述
在现有 OpenCode 插件的基础上，增加 Codex 插件兼容层，使上游的 9 个 flow skills 和 6 个 agent prompts 也能在 Codex 中使用。
架构
纯 Prompt 架构下，Codex 兼容层非常简单——不需要 MCP server，仅通过 skills 目录 + hooks + manifest 实现：
codex-skills/hooks/hooks.json+src/hooks/session-start.tsdist/hooks/）.codex-plugin/plugin.json新增/修改文件
6 个 Agent Skills（核心）
从上游
assets/agents/的 agent prompt 转换为 Codex 兼容的 SKILL.md 格式：codex-skills/agent-dev-lifecycle/SKILL.md— 全流程编排器（含 Phase 0 场景分诊）codex-skills/agent-architect/SKILL.md— 架构设计codex-skills/agent-developer/SKILL.md— 编码实现codex-skills/agent-reviewer/SKILL.md— 双轴代码审查codex-skills/agent-goal-verify/SKILL.md— 目标验证codex-skills/agent-researcher/SKILL.md— 独立调研9 个 Flow Skills
codex-skills/flow-*与assets/skills/flow-*内容同步（test/plugin/codex-compat.test.ts做 drift 检查防止上游修改后静默漂移）。构建配置改动（非零侵入）
package.json：files增加.codex-plugin、codex-skills、hooks；test:pack断言 tarball 包含 Codex 插件文件tsconfig.json：src/hooks/纳入 tsc 构建（生成dist/hooks/session-start.js）.github/workflows/ci.yml：新增npm run test:pack步骤注意事项
codex-skills/：OpenCode 对 npm 插件包根目录的skills/存在自动发现机制，会与 OpenCode 侧assets/skills重复注册；改用非默认目录名并通过 manifestskills字段显式指向，避开冲突（Codex 官方允许任意./相对路径）@agent-*，避免与 OpenCode 的 agent 概念冲突agent-dev-lifecycle的平台差异说明）