让 Codex 遇到需要你拍板的事时,弹出结构化表单等你回答——选择题、是/否确认、填空、多选,答完它再继续干活。体验对标 Claude Code 的 AskUserQuestion,但属于 Codex。
不改 Codex 源码,不做网页 hack,不要求常驻 GUI。
你需要:
整段复制进 PowerShell,回车:
git clone https://github.com/EliotOK/JustAskMe.git
cd JustAskMe
.\Install.cmd就这样。安装器会自动:注册插件、绑定本机的 Node 路径、检查有没有旧配置冲突。如果检测到旧插件、手工 MCP 注册或本项目的旧技能副本,改跑:
.\Install.cmd --migrate安装器自包含,不依赖本机的 plugin-creator 辅助脚本。它先准备并检查新版本,再切换注册;同时在用户级 $CODEX_HOME/AGENTS.md(默认 ~/.codex/AGENTS.md)维护一个带标记的简短规则,让必要提问优先使用卡片。重复安装只更新这一托管区块,不覆盖其他用户规则。迁移会注释旧 MCP 配置,将旧技能移到扫描目录之外。恢复副本保存在 $CODEX_HOME/just-ask-me-backups/(默认 ~/.codex/just-ask-me-backups/)。失败时尝试恢复文件与注册;若 CLI 恢复失败,会明确报告并保留备份。旧插件源目录保留。含多行字符串的 TOML 配置需手动迁移,安装器会在写入前停止。
macOS / Linux 使用
python3 install.py;本次自动验收在 Windows 完成,其他系统仍需实机验证。
更懒的办法:把下面这句话直接发给 Codex,让它自己装—— 「从 GitHub 克隆 https://github.com/EliotOK/JustAskMe 并运行里面的 Install.cmd 把它装成你的插件」
- 重开一个 Codex 任务(插件在新任务里生效)。
- 发送:
调用 human_input_status 工具看看看到client_supports_form_elicitation: true和五个工具 → 连接成功。 - 发送:
遇到需要我决定的地方就弹卡片问我。比如:用 pnpm 还是 npm?Codex 弹出带选项的表单,选一个提交,它拿着答案继续 → 完成。
出问题了?直接翻下面的常见故障,绝大多数是一行解法。
不需要记任何命令。内置的 AskWithCard 技能只改变提问方式:Codex 本来就需要问你时,会优先弹卡片,不会因此增加问题。想让它更主动地问你:
- 说 「讨论模式」 或 「边做边讨论」——启用提问纪律:值得问的当场问、能自己查清的不烦你、答完立刻收束干活。这套纪律由内置的 DiscussWithMe 技能提供,详见下文。
- 说 「快聊一下」「展开讨论」「挑战一下我的想法」「先收束」——随时调整讨论深度。
- 四个工具各管一摊:选择(
ask_choice)、是/否(ask_confirm,破坏性操作前必用)、填空(ask_text)、多选(ask_multi_select)。细节见工具参考。
卸载:codex plugin remove just-ask-me@personal,再删掉 ~\plugins\just-ask-me 即可。
| 现象 | 处理 |
|---|---|
Install.cmd 报 Python 相关错误 |
装官方 Python(python.org)后重跑;安装器会自动选对解释器,LibreOffice 等软件塞进 PATH 的残缺 Python 不会再被误用 |
agent 说"我问不了" / 收到 declined 但你没看到表单 |
客户端在自动拒绝。看返回里的 auto_reject_suspected: true;本项目已把它改报为 needs_user_input,agent 会在对话里直接问。也可临时设 HIM_FALLBACK=http 拿到网页表单 |
Codex 启动报 failed to load configuration / missing field ... |
config.toml 的 [approval_policy.granular] 三个必填没写全(sandbox_approval / mcp_elicitations / rules)。通常根本不用写这个块——默认配置就能弹表单 |
cannot extend value of type string with a dotted key |
同时写了 approval_policy = "..." 和 [approval_policy.granular]。二选一 |
| 表单弹出来了,提交却无效 | Codex 的 tool_timeout_sec 小于等待时间。设 600 以上,并 ≥ HIM_TIMEOUT_MS/1000 |
列表里没有 human_input 或 disabled |
路径不对。node <那个路径> 手动跑一下,出 ready 说明路径没问题 |
表单弹了但浏览器没开(http 模式) |
无头环境。HIM_HTTP_OPEN=0,URL 仍会打到 stderr |
| 模型从来不调这些工具 | 新建任务确认技能列表里有 ask-with-card,并运行 human_input_status;仍缺失时重新安装插件并重启 Codex。项目需要更强的主动提问纪律时,再复制本仓库的 AGENTS.md |
验证排障三板斧(按可靠性):
- 让 agent 跑
human_input_status——服务端视角的真相; codex mcp list看Status = enabled;node scripts/smoke-stdio.mjs绕开 Codex 直接测 server——通过说明协议链路可用;真实客户端界面、等待和通知仍需单独验证。
所有 ask_* 返回同一个结构(outputSchema 已声明)。answered 表示提交了答案,discussion 表示提交了仅含自由文字的回复:
status |
含义 | agent 应该做什么 |
|---|---|---|
answered |
用户回答了 | 用 answer/selected/confirmed/free_text 继续,不要重复问 |
discussion |
用户仅提交自由文字 | 先解释追问;若文字已明确决定,直接采用 |
needs_user_input |
尚未取得可用表单答案 | 把 message 里的问题和选项原样复述到对话里,等用户回复 |
declined |
用户拒绝回答 | 不要再问。选最保守方案并声明假设,或报告需要决策 |
cancelled / timeout |
用户关掉 / 没人回答 | 未回答 ≠ 许可。破坏性操作上不要猜 |
invalid_response |
答了但内容不可用 | 读 message 后简化重问或声明假设 |
unsupported / error |
不支持 elicitation 且 fallback=off / 参数或服务端异常 | 读 message 与 next_step 照做 |
辅助字段:client_elicitation(客户端是否声明 elicitation 能力)、auto_reject_suspected(decline 快于 400ms,可能是客户端自动拒绝,耗时不能证明用户是否看到或拒绝——此时状态会被提升为 needs_user_input)。
| 工具 | 输入要点 | 返回 |
|---|---|---|
ask_choice |
question + 2–25 个 {label, description?}(2–5 个最佳);default 须精确匹配某 label;默认增加可点击的“自定义回答”,设置 allow_free_text: false 可关闭;timeout_ms 覆盖整次等待 |
预设选项在 selected,自定义回答在 free_text |
ask_confirm |
question(写清对象和后果);default? |
confirmed: boolean,answer 为 "yes"/"no" |
ask_text |
question;placeholder? 格式提示;default? |
answer(已 trim) |
ask_multi_select |
question + options;min?/max? 数量边界 |
selected: string[],answer 逗号连接 |
human_input_status |
verbose? |
能力/配置诊断,不提问不阻塞 |
安装器已把提问纪律通过 MCP initialize.instructions 下发,模型开箱即知基本规则。想让某个项目里纪律更硬,把本仓库的 AGENTS.md 复制到那个项目根目录即可。核心判断标准:
只有在「决策价值 > 打断成本」时才提问。 该问:关键歧义 / 不可逆的架构选择 / 方案同样合理靠偏好定 / 破坏性操作 / 用户可见行为有真实取舍。 不该问:小问题 / 能推断的自己定 / 能从仓库读出来的先读 / 答案不影响下一步的别问 / 问过的别再问。 拿不准的顺序:先读代码 → 按仓库约定推断 → 仍影响重大才提问。
环境变量(写进 [mcp_servers.human_input.env]):
| 变量 | 默认 | 说明 |
|---|---|---|
HIM_TIMEOUT_MS |
300000 |
单题等待上限(1000–3600000) |
HIM_FALLBACK |
return |
return | http | off,见下 |
HIM_HTTP_OPEN / HIM_HTTP_HOST / HIM_HTTP_PORT |
1 / 127.0.0.1 / 0 |
http 回退的浏览器/绑定/端口;不要改成 0.0.0.0 |
HIM_MULTISELECT_MODE |
array |
text 可降级为逗号分隔输入 |
HIM_AUTO_REJECT_MS |
400 |
快于此值的 decline 判定为客户端自动拒绝 |
HIM_LOG |
info |
日志级别,全部走 stderr |
HIM_STRICT_STDOUT |
1 |
0 = 关闭 console→stderr 重定向保险 |
回退三模式(客户端不支持 elicitation 时):return(默认)把问题原样交还 agent 在对话里问,不阻塞;http 起一个 127.0.0.1 上的一次性表单页(128 位随机 token、用完即关、零外部资源);off 直接报错。为什么用 HTTP 而不是终端提示?stdio 的 stdin 就是 JSON-RPC 通道,动它必坏协议——loopback HTTP 是唯一完全不碰消息流的回退。
手工接入(不想用插件安装器):在 %USERPROFILE%\.codex\config.toml 加:
[mcp_servers.human_input]
command = "node"
args = ["<本仓库克隆位置>\\dist\\index.js"]
startup_timeout_sec = 30
tool_timeout_sec = 600 # 必须 >= HIM_TIMEOUT_MS/1000
[mcp_servers.human_input.env]
HIM_FALLBACK = "return"
HIM_TIMEOUT_MS = "300000"完整注释版见 docs/codex-config.example.toml。手工注册与插件二选一:并存会出现两份 ask_* 工具;想切到插件形态,跑 .\Install.cmd --migrate。
从源码开发:npm install && npm run verify(typecheck + 44 个单元测试 + 打包 + 冒烟,期望 smoke test OK)。测试用真 MCP Client/Server 经 InMemoryTransport 相连,只把"人"换成脚本;另有 node scripts/smoke-stdio.mjs --manual 人工模式。
内置的 AskWithCard 技能(plugins/just-ask-me/skills/ask-with-card/)默认允许隐式调用。它只在 Codex 已经判断需要向用户提问时,把普通文字问题路由到合适的 human_input 卡片;不会主动寻找更多决策点,也不会降低提问门槛。
- 少量互斥候选使用
ask_choice;默认保留自由输入选项。 - 是/否问题使用
ask_confirm,开放输入使用ask_text,选择子集使用ask_multi_select。 - 卡片不可用时,退回普通文字提出同一个问题。
这项默认能力与讨论模式相互独立。
JustAskMe 服务器解决的是"怎么问"——弹卡片、等答案、状态可靠;AskWithCard 负责把已有问题路由到卡片;本仓库内置的 DiscussWithMe 技能(plugins/just-ask-me/skills/discuss-with-me/)则解决主动讨论时"何时问、问什么"。
对 Codex 说「讨论模式」「边做边讨论」「重要选择先问我」即可激活($discuss-with-me 亦同),当次会话内持续生效。它规定的核心纪律:
- 识别值得问的决策:答案会实质改变目标、范围、方法或返工量的才问;低影响、易撤销、不涉及偏好的细节自主处理,一句话说明即可。
- 提问时机:确认是决策点就当场发问,不要先把整个方案写完再问——那时用户改的成本已经变高,问题也从"你选哪条路"退化成"要不要推翻你"。
- 组织提问:一次一个关键决策;选项公平呈现、推荐要有依据;允许用户自由填写时不另造"其他"选项。
- 调节深度:「快聊一下」「展开讨论」「挑战一下我的想法」「先收束」随时切换,深度服务于决策,不取消收束条件。
- 让选项可追问:用户不了解选项差别时,先解释再请求选择,不把"给我讲讲"当成授权。
- 围绕具体产物讨论:抽象偏好难以表达时,做最小草稿或样例让你看效果再定,不用完整实现代替低成本示例。
- 收束执行:信息足够就立即开工,不添加"最后一个问题";最终交付记录实际方案与假设,不把讨论过程写进成品。
分工一句话:服务器负责可靠交互,AskWithCard 负责默认用卡片,DiscussWithMe 负责主动讨论重要决策。
脱离 Codex 也能用:技能本身是纯提示词,宿主无关。把 plugins/just-ask-me/skills/discuss-with-me/ 复制到 ~/.agents/skills/discuss-with-me/,Claude Code、ZCode、Cursor 等同样扫描该目录的 agent 就能识别同一套纪律——在它们那里,"同步提问工具"自动指宿主原生的选择题卡片(如 AskUserQuestion),没有卡片的环境则按技能规则降级为普通文字提问。仓库根目录的这份即为唯一正典,改动后请同步运行副本。
网上教程很多在细节上是错的,以下每条都在本机实测过:
| 事项 | 结论 |
|---|---|
| MCP SDK 支持 elicitation? | ✅ @modelcontextprotocol/sdk@1.30.0 的 elicitInput(params, options) |
| 返回结构 | { action: 'accept'|'decline'|'cancel', content? }(ElicitResultSchema) |
| form 模式字段 | 只支持扁平原始类型:string / boolean / number / integer / array-of-enum |
| SDK 会静默丢字段吗 | properties 走 Zod union + .strip(),未知键被丢掉而非报错;test/schema.test.ts 用 round-trip 深度相等断言把此事变成会失败的测试 |
| 客户端没声明能力时 | elicitInput() 直接 throw,不会发出去。本项目前置探测 + 对该 throw 兜底分类 |
| 默认超时 | timeout(默认 300s) |
| SDK 会校验用户回答吗 | McpError(InvalidParams),到不了本项目代码——所以有 allow_free_text |
| 取消能传递到 server 吗 | ✅ 客户端 abort → notifications/cancelled → extra.signal 被 abort |
| Codex CLI 支持 elicitation 吗 | ✅ 0.144.3 实测支持,默认配置就能弹表单;granular 的 mcp_elicitations 块通常不需要 |
| Codex 会渲染表单吗 | ✅ 实测原生渲染:模态框 + 选项 + 跳过/继续,来源标注 just-ask-me |
已实测:schema round-trip 无字段被 strip;stdio 被真实客户端拉起并完成 elicitation/create 往返;Codex Desktop 原生渲染 ask_choice 表单;OnRequest 策略下无需配置 mcp_elicitations;选项描述内联进 message 后如期显示。
未验证:Codex 对 array 字段(ask_multi_select)与布尔字段(ask_confirm)的渲染质量——若不理想,HIM_MULTISELECT_MODE=text 可降级;enumNames 是否被 Codex 采用(被忽略也不影响正确性)。详细验证记录见 VALIDATION.md。
已知取舍:数字字段完全不用(Codex 有公开问题会把数值 elicitation 字段降级成审批提示);ask_multi_select 故意不设 required,让空选走本项目自己的可读报错而非 SDK 校验;越界选项在 elicitation 路径上拿不到用户原话(Ajv 异常不含原始值),这正是 allow_free_text 的存在意义。
JustAskMe/
├── src/ # index(入口) server(tools+instructions) tools(提问流水线)
│ # elicitation(能力探测) forms(schema 转换) http-form(回退页)
│ # schemas/outcome(统一状态) config(HIM_* env) logger(stderr)
├── test/ # 46 个单元测试:schema 往返 / 四工具 / 取消归类 / 超时 / HTTP 回退端到端
├── scripts/smoke-stdio.mjs # 真实 stdio 子进程冒烟(--manual 人工模式)
├── plugins/just-ask-me/ # 发布产物:单文件 server + ask-with-card / discuss-with-me 技能
├── docs/codex-config.example.toml
└── AGENTS.md # 提问纪律(复制到你的项目根目录)
为什么是 TypeScript:MCP 官方 SDK 的 elicitation 支持最完整;Codex 是 Node 生态,node 零包装拉起;运行时依赖只有 @modelcontextprotocol/sdk 和 zod 两个。
MIT。
ask_choice 默认在第一张同步 MCP 卡片增加可点击的“自定义回答”。预设选项直接返回 answered;选择“自定义回答”才打开第二张文字输入卡,原题和选项会在卡片中重现,提交后返回 discussion。模型应结合完整文字理解回复,
先处理追问和“暂不执行”等限制,不能把任一提交自动视为操作授权。
HTTP 备用表单会按多选数量校验;无效提交保留页面和已填内容,修正后可继续提交。
开发验证:npm ci、npx playwright install chromium、npm run verify。
其中安装器测试使用临时用户目录及模拟 CLI,浏览器测试使用真实 Chromium。
这些测试不代替真实 Codex 的新用户安装、卡片展示、长时间等待和桌面通知验收。
通知及客户端允许的最长等待时间受 Codex 和操作系统配置影响,本插件不保证一定弹出系统通知。