codex-flow: Instructions file for Codex

AGENTS.md — 给在本仓库工作的 AI agent 的常驻护栏

本仓库是一个与后端无关的动态工作流引擎(Codex 可用)。完整设计是唯一事实源: DESIGN-codex-dynamic-workflow.md。任何与你记忆/直觉冲突处,以该文档为准。

工作规则(每个 turn 都遵守)

1. 只做被明确要求的事。 文档/任务没让改的,不要碰、不要"顺手优化"、不要加功能或抽象。
2. 一次一项,改完即验证再继续。 每改完一个任务,跑 npm run typecheck 和 npm test, 贴输出,确认现有测试仍全过 + 新测试过,再做下一项。做完当前任务就停下等确认,别往下冲。
3. 不重构、不重命名、不动无关代码;不加新依赖(deps 只用 package.json 已列的: @openai/codex-sdk、openai、zod、zod-to-json-schema、ajv)。
4. 不改任何已通过测试的断言含义来"让它过"。测试红了就修代码,不是改测试。
5. 不确定 = 停下来问,绝不猜,也绝不替文档单方面做设计决定。
6. 每个独立修复做一个 git commit(如 fix #1: transient retry),便于逐项 review 和回滚。
7. 没实现的部分要明确标出并停下问,禁止留 TODO/占位却声称"完成"。

Codex App 自然语言驱动层

当用户在本仓库里说“启动动态工作流”“用动态工作流”“并行跑一下”“帮我拆成 workflow 跑” 这类话时,不要要求用户自己写 workflow 文件或敲命令。你就是缺失的驱动层:

1. 先用一句话复述要跑的目标;若输入材料/目标格式缺失,最多问一个必要问题。
2. 能直接推断时,在 .codex-flow/generated/ 下生成临时 *.workflow.ts。 这个目录已被 .gitignore 忽略,用于一次性工作流草稿和 journal。
3. workflow 必须导出 default async function workflow(ctx);优先用 ctx.parallel / ctx.pipeline / ctx.phase / ctx.agent 表达任务,不要写一次性大脚本绕过引擎。
4. 默认运行命令:

codex-flow run .codex-flow/generated/<name>.workflow.ts \
  --backend codex-sdk \
  --journal .codex-flow/generated/<name>.jsonl

1. 默认后端是 codex-sdk,使用用户的 Codex/ChatGPT 登录会员权益;不要让用户提供 API key。 只有用户明确要 openai-responses 或本地/第三方模型时,才讨论对应凭据或适配器。
2. 需要写真实仓库文件的节点必须显式传 cwd: process.cwd() 和 sandbox: "workspace-write";只读/分析节点用 sandbox: "read-only"。
3. 运行失败时先读错误,只修临时 workflow 或适配器暴露出的真实字段问题;不要改引擎不变量。
4. 最终只给用户看结果摘要、失败点、journal 路径和可复跑命令;不要把整份生成脚本大段贴出, 除非用户要求。

绝不可回退的不变量(写错 = 本次失败)

Codex API 事实(已实测核对,见设计文档附录 A):

• TS SDK 线程选项字段是 sandboxMode,不是 sandbox。
• thread.run/runStreamed 的 finalResponse 是字符串,要自己 JSON.parse,SDK 不替你解析。
• 最终答案取 item.type === "agent_message" 的 .text;SDK 里没有 assistant_message 这个类型(仅 codex-exec 适配器为防 CLI 漂移才两种拼写都收)。
• 自己写的 codex-exec 适配器用稳定公开旗标 --json(不是 SDK 内部的 --experimental-json); exec 的进程退出码权威;codex exec resume 时全局旗标放在 resume 之前。
• openai-responses 用 text.format: {type:"json_schema", strict:true} + parallel_tool_calls:false (不是 Chat 的 response_format)。