oh-my-pi 编码代理 Plan 模式的工具决策收尾机制：ask 澄清与 xd://propose 方案提交的强制出口

oh-my-pi 编码代理 Plan 模式的工具决策收尾机制ask 澄清与 xd://propose 方案提交的强制出口【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-piPlan 模式是 oh-my-pi 编码代理在动手改代码之前先产出完整执行方案的阶段而plan-mode-tool-decision-reminder.md正是这个模式下一轮对话必须以决策性工具调用收尾的强制提醒。本文将以该提醒文档为骨架拆解其逐条指令的语义并结合 agent-session.ts 中的强制机制、resolve.ts 中的xd://propose设备协议与 ask.ts 的实现讲清楚 Plan 模式回合是如何被收敛为提问澄清或提交方案二选一的以及开发者可以据此理解的内部运行规则。背景Plan 模式的回合必须收敛约束oh-my-pi 的 Plan 模式开启后工作树与系统处于只读状态代理只能通过local://会话内规划产物来编写方案文件并把最终方案提交给用户审批。完整的 Plan 模式指令集定义在 plan-mode-active.md 中其核心约束包括工作树/系统只读绝不创建、编辑、删除、重命名工作树文件绝不运行改变状态的命令local://slug-plan.md是唯一规范方案文件方案slug使用小写短横线命名字母、数字、下划线、连字符实现方案时用write工具把方案slug/标题以纯文本写入xd://propose由用户选择执行选项后恢复完整写权限严禁用自然语言要求用户退出 Plan 模式也严禁用ask工具以文字形式请求审批——审批只能通过写xd://propose完成。正是在这样的约束下出现了一个需要兜底的场景如果某轮对话结束后代理既没有调用ask收集需求也没有通过xd://propose提交方案回合就处于未收敛状态。plan-mode-tool-decision-reminder.md就是由会话层在检测到这种状态时注入的一条 system-reminder强制代理做出唯一的选择。提醒文档逐条拆解唯一两种合法出口关联文档全文如下system-reminder Plan mode turn ended without a required tool call. You MUST choose exactly one next action now: 1. Call {{askToolName}} to gather required clarification, OR 2. Write the plan slug/title (slug, matching local://slug-plan.md) as plain text to xd://propose with {{writeToolName}} to finish planning and request approval You NEVER output plain text in this turn. /system-reminder其中{{askToolName}}与{{writeToolName}}是模板占位符。在 agent-session.ts 中渲染该模板时仅注入了askToolName: askwriteToolName在会话上下文中解析为write。也就是说实际注入模型的提醒明确给出两个且仅两个出口调用ask工具收集必要的澄清信息用write工具把方案slug必须匹配local://slug-plan.md以纯文本写入xd://propose结束规划并请求审批。同时强调本回合绝不输出纯文本——这意味着模型不能以自然语言段落结束回合任何想先聊聊再决定的做法都会被判定为未收敛继续收到提醒。出口一ask工具——偏好与权衡的澄清通道第一个出口是调用ask。从 ask.ts 的实现看该工具用于执行过程中与用户交互允许收集用户偏好或需求澄清含糊指令在执行过程中就实现选择征求意见为用户提供方向选择。其输入 schema 的关键字段包括questions至少一个问题每个问题有id、question文本、options选项列表以及可选的multi允许多选、recommended标记推荐选项索引自动追加 (Recommended) 后缀、header富交互弹窗的短展示标签。用户永远可以通过保留的 Other (type your own) 选项输入自定义文本。在 Plan 模式下ask的定位非常明确它只用于代码无法推导的偏好与权衡问题如意图、UX、范围边界、性能与简单性的取舍而可发现的事实位置、行为、签名、配置必须用glob/grep/read等探索工具自行发现禁止把探索能回答的问题抛给用户。正如 plan-mode-active.md 所规定的每个问题都必须改变方案或解决承重选择问题要批量提出绝不问探索能回答或填充性问题。出口二write xd://propose——方案提交与审批的唯一通道第二个出口是通过write工具写入xd://propose设备地址。这套解析设备机制定义在 resolve.ts 中RESOLVE_DEVICE_PATH xd://resolve把待定预览的采纳理由写入以应用暂存的阶段化变更REJECT_DEVICE_PATH xd://reject写入理由以丢弃暂存变更PROPOSE_DEVICE_PATH xd://propose写入方案slug以提交方案请求审批仅 Plan 模式激活期间有效。设备地址的设计思路是无工具 schema、无 JSON 协议所有解析动作都通过始终可用的write工具以纯文本写入xd://URL 完成没有任何东西寄生在系统提示中——暂存工作流在相关时刻才教授调用形状。isProposeToolCallresolve.ts通过解析write调用的 path 参数是否为xd://propose来判定方案提交调用而dispatchResolutionDeviceresolve.ts会把写入的文本体当作方案标题分发给 Plan 模式安装的PlanProposalHandler。如果 Plan 模式未激活写入会得到明确的错误没有等待审批的方案——xd://propose仅在 Plan 模式激活期间接受方案标题。提交后用户可选择四种执行选项见 plan-mode-active.md批准并执行新上下文、批准并压缩上下文、批准并保留上下文、保存并退出把方案复制到指定路径后开启新会话——所有选项都要求方案文件自包含因此方案slug必须与local://slug-plan.md完全一致且方案文件在审批后永不被重命名。底层强制机制#enforcePlanModeDecisionAtSettle的判定链提醒文档之所以会被注入是因为会话层在每一轮沉淀settle时执行了严格的收敛检查。核心逻辑位于 agent-session.ts 的#enforcePlanModeDecisionAtSettle()其判定链如下Plan 模式未启用则直接放行检查#planModeState?.enabled未启用返回false不注入找不到最后一条助手消息则放行错误/中止终止则放行stopReason为error或aborted时不打扰已调用决策工具则重置并放行#isPlanDecisionToolagent-session.ts判定消息中是否存在ask调用或write xd://propose调用只要命中就清零提醒计数与等待进展标记视为回合已收敛存在其他工具调用则放行只要有任意 toolCall说明代理还在探索/编辑过程中不强制处于等待进展状态则放行上一次提醒后已产生过工具进展不重复打扰提醒次数达到上限则放弃PLAN_MODE_REMINDER_MAX 3agent-session.ts达到上限后记录调试日志 Plan mode convergence: reminder cap reached; yielding to user把控制权交还用户——避免无限循环ask/write工具不可用则跳过若工具注册表中缺少这两个工具记录警告并跳过强制注入提醒递增计数、置位等待进展、把标签为plan-mode-decision的required级工具选择推入#toolChoiceQueue随后用prompt.render(planModeToolDecisionReminderPrompt, { askToolName: ask })渲染提醒作为role: developer消息同时追加到代理消息流与会话管理器最后调度代理继续运行来源标记为plan-mode-reminder。其中值得注意的两个工程细节强制 tool_choice提醒注入的同时把required级工具选择压入队列迫使模型下一轮必须调用决策工具而不是继续输出文本但如果后续回合因新提示、销毁、压缩、交接等原因没有继续运行onSkip回调会移除该强制选择避免把强制决策泄漏到无关回合。提醒次数上限连续 3 轮未收敛后系统主动让位给用户说明该机制是引导收敛而非无限纠缠最终决策权仍在用户手中。PlanModeState的结构plan-mode/state.ts也印证了这一流程enabled、planFilePath、workflowparallel/iterative、reentry等状态字段共同决定了 Plan 模式的整体行为而#enforcePlanModeDecisionAtSettle正是在enabled的前提下兜底回合收敛。提醒与其他 Plan 模式提示的配合关系plan-mode-tool-decision-reminder.md不是孤立存在而是 Plan 模式提示体系中的收尾兜底层plan-mode-active.md是常驻的 Plan 模式主指令定义只读约束、方案文件规范、工作流iterative 与 parallel、方案内容结构与审批选项并明确回合仅以两种方式结束ask收集需求/选择方案或write写入xd://proposeplan-mode-reference.md与 plan-handoff 相关模块处理既有方案引用与交接场景plan-mode-tool-decision-reminder.md则在模型违反上述结束条件时被注入用最简短的 system-reminder 把必须调用决策工具重新钉死。三者形成主指令定义规则 → 引用/交接处理延续 → 违规时强制提醒的闭环。从源码结构可以推断这种分层设计使得主提示可以保持精简而把回合收敛这种运行时状态相关的强制逻辑下沉到会话层的判定代码中提示文件只负责在触发时刻传达最关键的两条出口信息。对开发者的实践启示理解这套机制后在与 oh-my-pi 编码代理交互或二次开发相关能力时可以把握以下要点Plan 模式下的回合只允许两种结局要么代理调用ask向你提问澄清要么它把方案slug写入xd://propose等待审批——纯文本输出会被判定为未收敛ask只用于偏好与权衡可探索的事实文件位置、符号签名、行为代理必须自行用glob/grep/read发现因此你收到的提问应当都是选哪个方向/边界在哪级别的决策题且通常带推荐选项方案文件命名必须一致xd://propose写入的slug必须与local://slug-plan.md完全匹配审批后文件名不变方案文件必须自包含到让不熟悉对话的工程师能零决策从头执行强制不是无限循环连续 3 轮未收敛PLAN_MODE_REMINDER_MAX 3后系统会把控制权交还给你避免代理陷入自旋。这套提醒文档 会话层强制判定 xd:// 解析设备的组合保证了 Plan 模式产出的方案是决策完备、可独立执行的执行规格而非讨论记录——这正是approval may clear the conversation这一设计得以成立的前提。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考