人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载本篇技术指南围绕 GSD-2构建于 pi 运行时的元提示、上下文工程与规格驱动开发系统扩展开发中的Mode Behavior模式行为机制展开讲解运行模式如何决定扩展可用的 UI 方法、如何在无界面模式下优雅降级。读完本文你将掌握ctx.hasUI的正确判空姿势、阻塞式对话框与非阻塞式 UI 的边界、四类运行模式Interactive / RPC / JSON / Print对扩展行为的真实影响并能基于源码级案例写出在任何模式下都不会崩溃的扩展代码。一、为什么扩展作者必须理解模式行为GSD 扩展Extension是注入运行时、导出默认函数的 TypeScript 模块通过ExtensionAPIpi对象注册工具、命令、事件钩子与自定义 UI。但它有一个容易被忽略的前提模式行为决定了哪些 UI 方法可用。GSD 本体既可以交互式运行完整 TUI也可以以守护进程 / RPC / 管道等非交互形态被外部宿主驱动。扩展运行在非交互模式下时弹窗、确认框、输入框这类阻塞式对话框天然不可用——如果你不做保护就调用要么抛出错误要么阻塞整个 Agent 循环。因此官方在扩展技能的不可妥协规则里明确要求调用对话框方法前必须检查ctx.hasUI见 SKILL.md。二、四种运行模式一览根据官方参考文档 mode-behavior.mdGSD 共有四种运行模式扩展 UI 行为各不相同模式UI 方法说明Interactive默认完整 TUI正常运行——所有 UI 均可用RPC--mode rpcJSON 协议宿主处理 UI对话框经由子协议工作JSON--mode jsonNo-op事件流输出到 stdout无 UIPrint-pNo-op扩展照常运行但无法向用户发起提示从 CLI 入口实现看模式开关确实由命令行驱动在 cli.ts 中可以看到gsd --mode rpcJSON-RPC over stdin/stdout、gsd --mode mcpMCP server over stdin/stdout、gsd --mode text message文本输出模式等启动方式。也就是说同样的扩展代码在被--mode json或-p启动的实例中加载时UI 相关能力会被整体置为不可用。三、ctx.hasUI判断 UI 可用性的唯一可靠途径ExtensionContextctx在所有事件处理器中均可获得session_directory事件除外其中ctx.hasUI专门用于描述当前会话的 UI 可用性见 extensioncontext-reference.mdctx.hasUI为falsePrint 模式-p与 JSON 模式ctx.hasUI为trueInteractive 模式与 RPC 模式。官方推荐的标准保护写法如下任何调用对话框方法之前都应先做这个分支if (ctx.hasUI) { const ok await ctx.ui.confirm(Delete?, Sure?); if (!ok) return; } else { // 非交互模式的默认行为 // 或者直接继续不进行确认 }这里的关键在于ctx.ui.confirm属于阻塞式对话框——它会等待用户响应。在无 UI 的 Print / JSON 模式下这类方法没有任何可挂靠的界面直接调用会导致扩展行为不确定。而ctx.hasUI检查让扩展可以在有 UI 时给出完整交互体验在无 UI 时回退到默认继续或跳过确认的安全路径。四、阻塞式对话框必须先判hasUIctx.ui上提供的方法按阻塞特性分为两大类。必须经过ctx.hasUI保护的是阻塞式对话框它们会挂起直到用户给出响应const choice await ctx.ui.select(Pick one:, [A, B, C]); const ok await ctx.ui.confirm(Delete?, This cannot be undone); const name await ctx.ui.input(Name:, placeholder); const text await ctx.ui.editor(Edit:, prefilled text); // 定时对话框——超时后自动关闭 const ok await ctx.ui.confirm(Auto-confirm?, Proceeds in 5s, { timeout: 5000 });注意 RPC 模式下的一个细节ctx.hasUI在 RPC 模式为true因为对话框可以通过 RPC 子协议交给宿主如 VSCode 扩展、Web 界面渲染。所以有 UI不一定是本地终端 TUI也可能是宿主侧的 JSON 协议承载的界面。这也是为什么判断 UI 要用ctx.hasUI而非检测我是否在终端里。五、非阻塞方法fire-and-forget所有模式安全与之相对非阻塞方法notify、setStatus、setWidget、setTitle、setEditorText在所有模式下都是安全的——当没有可用 UI 时它们会静默变为 no-op空操作不会报错也不会阻塞。ctx.ui.notify(Done!, info); // Toastinfo | warning | error ctx.ui.setStatus(my-ext, ● Active); // 底部状态栏 ctx.ui.setStatus(my-ext, undefined); // 清除状态 ctx.ui.setWidget(my-id, [Line 1, Line 2]); // 编辑器上方的 Widget ctx.ui.setWidget(my-id, [Below!], { placement: belowEditor }); ctx.ui.setTitle(gsd - my project); // 终端标题 ctx.ui.setEditorText(Prefill); // 预填编辑器内容这类方法设计上就是尽力而为的它们负责向用户单向播报信息、更新状态或调整界面元素即使没有 UI 接收扩展的业务逻辑也完全不受影响。因此把它们与阻塞式对话框区别对待是 Mode Behavior 的核心心法不需要确认/输入的 UI 更新可以放心调用需要用户作答的对话框必须先过ctx.hasUI这道闸。六、源码级案例ask_user_questions 的三路路由仓库内置的 ask-user-questions.ts 是 Mode Behavior 在生产代码中的最佳范本。它需要向用户提出多道选择题因此必须同时处理本地 UI 可用 / 远程问答通道 / 完全无 UI三种情况其路由逻辑第 250-309 行如下hasRemote ctx.hasUI本地 UI 与远程通道同时可用用AbortController同时发起两者并竞速先到先得输家被取消hasRemote !ctx.hasUIheadless无本地 UI但配置了远程通道走远程问答!ctx.hasUI且无远程直接返回错误Error: UI not available (non-interactive mode)而不是冒险调用对话框兜底RPC 模式下custom()可能返回undefined此时降级为依次调用ctx.ui.select()的串行提问。这个案例验证了两件事其一ctx.hasUI是区分能不能弹对话框的第一判据即便在远程通道存在时也优先用它分派分支其二官方对非交互模式的定义是扩展照常运行但无法向用户发起提示——业务逻辑不中断只是交互路径需要降级或报错。如果你的扩展要开发提问/确认类能力直接借鉴这套三路路由即可。七、实践清单模式安全的扩展写法结合 extension-skeleton.ts 模板与技能文档的规则整理出以下可落地的检查清单对话框前必查ctx.hasUIconfirm/select/input/editor四类阻塞方法一律走if (ctx.hasUI) { ... } else { ... }分支非阻塞方法放心用notify/setStatus/setWidget/setTitle/setEditorText无需保护无 UI 时自动 no-op无 UI 时给出明确回退不要静默吞掉用户必须确认的关键操作至少输出一条日志或返回说明性的错误信息参考ask_user_questions的errorResult为 RPC 宿主留好接口ctx.hasUI在 RPC 模式为true对话框由宿主经子协议渲染因此不要在代码里假设有 UI 就等于本地终端测试覆盖非交互路径用--mode json或-p启动实例做冒烟验证确认扩展在无 UI 模式下仍能完成注册、事件钩子与工具执行只是跳过交互环节。扩展完整的加载路径与生命周期可参考 extension-lifecycle.md 与 events-reference.mdUI 方法全集见 extensioncontext-reference.md。遵循以上规则你的扩展就能在 GSD 的交互终端、RPC 宿主、headless JSON 管道和打印模式之间无缝游走既不阻塞 Agent 循环也不丢失交互能力。赞分享人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载相关推荐GSD-2 四种运行模式与扩展 UI 安全编程深入理解 Interactive / RPC / JSON / Print 模式及 ctx.hasUI 守卫GSD 2 四种运行模式与扩展 UI 安全编程深入理解 Interactive / RPC / JSON / Print 模式及 ctx.hasUI 守卫 本人工智能AI Agent代码智能体Agent 编排CLIAI 应用Pigsd四种运行模式完全指南交互、打印、JSON 与 RPCPigsd四种运行模式完全指南交互、打印、JSON 与 RPC 本文基于仓库文档 03 the four modes of operation.md ht人工智能AI Agent代码智能体Agent 编排CLIAI 应用GSD Quick Mode 深度解析用 /gsd:quick 在零仪式下安全执行临时任务GSD Quick Mode 深度解析用 /gsd:quick 在零仪式下安全执行临时任务 导读 本文深入剖析 get shit doneGSD系统中面向人工智能AI 应用提示工程开发工具工作流自动化AI Agent上一篇SuperClaude PM Agent 插件性能测试指南基于 Claude Code Plugin 的懒加载 Token 优化验证下一篇Go Micro v5.13.0 新特性micro deploy —— 基于 systemd SSH 的零平台服务部署指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考