人工智能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一个面向长期自主工作的 meta-prompting 与 spec-driven 开发系统中基于 TUI 的交互界面为扩展extension提供了强大的 UI 控制能力。本文聚焦ctx.ui中的持久化 UI 元素——它们一旦设置便停留在屏幕上直到被显式清除或覆盖——系统讲解状态栏Status/Footer、编辑器上方/下方的 Widget、流式输出期间的工作消息、自定义 Footer/Header、编辑器文本控制与主题切换等能力的完整用法。读完本文你将掌握如何编写真正可运行、可交互、可响应的 TUI 扩展 UI并理解这些 API 背后的源码级实现原理。一、持久化 UI 元素概览一次设置直到清除与ctx.ui.notify()这类一次性弹出通知不同持久化 UI 元素的特点是生命周期长设置之后它们会持续停留在屏幕上直到扩展调用对应的清除方法传入undefined或被新的值覆盖。这正是它们在设计上区别于普通消息的核心所在。从源码层面看这些能力全部定义在ExtensionUIContext接口中见 types.ts并由每种模式interactive、RPC、print各自提供实现。交互模式下的具体实现位于 extension-ui-controller.ts它把ctx.ui上的每个调用转发给宿主host的对应方法。理解这条调用链有助于你预判每个 API 的实际行为。持久化 UI 元素包括六大类元素设置 API清除方式状态栏条目Statusctx.ui.setStatus(key, text)setStatus(key, undefined)编辑器上方/下方 Widgetctx.ui.setWidget(key, content, options)setWidget(key, undefined)工作消息Working Messagectx.ui.setWorkingMessage(msg)无参调用恢复默认传null抑制自定义 Footerctx.ui.setFooter(factory)setFooter(undefined)自定义 Headerctx.ui.setHeader(factory)setHeader(undefined)编辑器文本/工具展开/标题setEditorText/setToolsExpanded/setTitle视 API 而定二、StatusFooter 状态栏多扩展独立占位状态栏用于展示扩展的持续状态例如运行模式、监控指示、当前阶段等。API 以key区分条目因此多个扩展可以设置互不干扰的独立状态条目它们会一起出现在 Footer 中。// 设置持续显示直到被清除或覆盖 ctx.ui.setStatus(my-ext, ● Active); // 支持使用主题色渲染 ctx.ui.setStatus(my-ext, ctx.ui.theme.fg(accent, ● Mode: Plan)); // 清除该 key 对应的状态 ctx.ui.setStatus(my-ext, undefined);源码实现细节在ExtensionUIContext的类型定义中types.tssetStatus的语义被明确为“Set status text in the footer/status bar. Pass undefined to clear.”。交互模式的实现将调用转发给host.setExtensionStatus(key, text)见 extension-ui-controller.ts。而真正存储这些状态的是FooterDataProvider类footer-data-provider.tssetExtensionStatus(key: string, text: string | undefined): void { if (text undefined) { this.extensionStatuses.delete(key); // undefined 即删除 } else { this.extensionStatuses.set(key, text); // 否则写入 Map } }可见undefined的语义在实现层就是Map.delete而不是存入一个空值——这正是“传入undefined即清除”这一约定的底层原因。三、Widget编辑器上方/下方区块Widget 是持久化 UI 中最灵活的区块可以放在输入编辑器上方默认或下方适合展示任务清单、扫描进度、命令预览等随会话持续更新的内容。3.1 简单字符串数组形式// 编辑器上方默认 placement ctx.ui.setWidget(my-widget, [Line 1, Line 2, Line 3]); // 编辑器下方 ctx.ui.setWidget(my-widget, [Below the editor!], { placement: belowEditor }); // 清除 ctx.ui.setWidget(my-widget, undefined);3.2 组件工厂形式支持主题与动态渲染当需要根据数据动态计算展示内容时使用组件工厂。工厂函数接收(_tui, theme)两个参数返回一个Component对象包含render和invalidate方法。下面是一个典型的待办事项列表示例ctx.ui.setWidget(my-widget, (_tui, theme) { const lines items.map(item item.done ? theme.fg(success, ✓ ) theme.fg(muted, theme.strikethrough(item.text)) : theme.fg(dim, ○ ) item.text ); return { render: () lines, invalidate: () {}, }; });源码实现细节setWidget的重载签名types.ts支持两种内容类型string[] | undefined—— 简单文本行((tui, theme) Component { dispose?(): void }) | undefined—— 组件工厂返回的组件可带可选的dispose钩子用于资源清理。关于放置位置WidgetPlacement类型types.ts只有两个合法值aboveEditor默认与belowEditor。ExtensionWidgetOptions仅包含一个可选字段placement。3.3 实战待办清单示例组合主题 API把 3.2 的代码与状态数据结合可构成一个可随 agent 工作推进而更新的清单 Widget// 在扩展的会话状态里维护 items const items: { text: string; done: boolean }[] []; ctx.ui.setWidget(task-list, (_tui, theme) { const render () { if (items.length 0) return [theme.fg(dim, (no tasks))]; return items.map(item item.done ? theme.fg(success, ✓ ) theme.fg(muted, theme.strikethrough(item.text)) : theme.fg(dim, ○ ) item.text ); }; return { render, invalidate: () {}, dispose: () console.log(widget disposed), }; });注意当items变化时需要调用ctx.ui.setWidget(task-list, undefined)再重新设置或者利用组件工厂配合tui.requestRender()触发重绘可参考后文自定义 Footer 中的响应式模式。四、Working Message流式输出期间的工作消息当 agent 正在流式生成回复时默认会展示一个“工作消息”通常伴随加载动画。扩展可以用setWorkingMessage临时覆盖它向用户传达当前正在执行的阶段性动作// 覆盖为自定义消息 ctx.ui.setWorkingMessage(Analyzing code structure...); // 无参调用恢复默认工作消息 ctx.ui.setWorkingMessage();源码实现细节setWorkingMessage的类型签名为setWorkingMessage(message?: string | null): voidtypes.ts注释明确了两个边界语义无参调用恢复默认工作消息传null完全抑制不显示。交互模式的实现extension-ui-controller.ts展示了它的工作方式当加载动画loadingAnimation存在时直接调用setMessage更新动画文案当动画尚不存在时则把消息暂存在pendingWorkingMessage中等待动画启动后再应用。若传入null则停止动画并清空状态容器。因此setWorkingMessage的正确用法是在长任务开始时设置结束时调用setWorkingMessage()恢复默认避免误导用户。五、自定义 Footer整体替换当内置 Footer 无法满足需求时可以用ctx.ui.setFooter传入一个组件工厂完全替换默认 Footer 的渲染逻辑。这是持久化 UI 中唯一能访问 Git 分支信息的入口。ctx.ui.setFooter((tui, theme, footerData) ({ invalidate() {}, render(width: number): string[] { const branch footerData.getGitBranch(); // 唯一的 Git 分支获取入口 const statuses footerData.getExtensionStatuses(); // 所有 setStatus 的值 const left theme.fg(dim, ${ctx.model?.id || no-model}); const right theme.fg(dim, branch || no git); const pad .repeat(Math.max(1, width - visibleWidth(left) - visibleWidth(right))); return [truncateToWidth(left pad right, width)]; }, // 响应式分支变化时重新渲染 dispose: footerData.onBranchChange(() tui.requestRender()), })); // 恢复内置 Footer ctx.ui.setFooter(undefined);footerData 提供的能力setFooter工厂的第三个参数是一个ReadonlyFooterDataProviderfooter-data-provider.ts它是对FooterDataProvider的只读视图通过Pick只暴露四个方法getGitBranch(): string | null—— 当前 Git 分支名不在仓库中返回null处于 detached HEAD 时返回detached。此数据在其他任何 API 中都拿不到getExtensionStatuses(): ReadonlyMapstring, string—— 所有扩展通过setStatus写入的状态值集合getAvailableProviderCount(): number—— 可用模型提供者数量供默认 Footer 展示使用onBranchChange(callback): () void—— 订阅分支变化返回取消订阅函数即上面示例中的dispose钩子。源码实现细节Git 分支是如何被监听的FooterDataProvider的分支检测与监听逻辑footer-data-provider.ts是一个值得学习的实现细节查找 HEAD 路径从process.cwd()向上逐级查找.git。它同时兼容常规仓库.git是目录与 Git worktree.git是包含gitdir:前缀的文件两种形态解析分支名读取 HEAD 文件内容若以ref: refs/heads/开头则截取分支名否则视为detached监听分支变化setupGitWatcher使用fs.watch监听 HEAD 所在目录而非 HEAD 文件本身。原因很微妙Git 提交时对 HEAD 采用“写临时文件再 rename 覆盖”的原子写方式这会改变文件的 inode导致直接 watch 文件失效watch 目录则不受影响。当 HEAD 变化时会清空分支缓存并逐个触发branchChangeCallbacks。因此如果你的自定义 Footer 需要显示分支名务必像示例那样用onBranchChange触发tui.requestRender()才能在分支切换时保持界面同步。六、自定义 Header启动区头部Header 显示在启动界面/聊天区上方同样支持整体替换ctx.ui.setHeader((tui, theme) ({ render(width: number): string[] { return [theme.fg(accent, theme.bold(My Custom Header))]; }, invalidate() {}, }));setHeader的类型定义types.ts说明其语义为设置自定义 Header 组件在启动时、聊天区上方展示传入undefined恢复内置 Header。工厂签名与setFooter类似但不接收 footerData仅有(tui, theme)。七、编辑器控制Editor Control持久化 UI 还提供一组直接操作核心输入编辑器的 API用于预填文本、获取当前内容、模拟粘贴以及控制工具输出面板的展开状态。7.1 设置 / 获取编辑器文本// 设置编辑器文本预填给用户 ctx.ui.setEditorText(Prefilled text for the user); // 获取当前编辑器文本 const current ctx.ui.getEditorText();7.2 模拟粘贴带大内容折叠处理// 触发粘贴处理流程包括大段内容的自动折叠 ctx.ui.pasteToEditor(pasted content);7.3 工具输出展开 / 收起// 读取当前展开状态 const wasExpanded ctx.ui.getToolsExpanded(); // 全部展开 / 全部收起 ctx.ui.setToolsExpanded(true); // 展开所有工具输出 ctx.ui.setToolsExpanded(false); // 收起所有工具输出7.4 终端标题ctx.ui.setTitle(pi - my project);源码实现细节这些 API 在交互模式下的实现extension-ui-controller.ts值得注意setTitle转发到host.ui.terminal.setTitle(title)即直接设置终端窗口/标签页标题pasteToEditor(text)被实现为向编辑器注入bracketed paste 转义序列\x1b[200~与\x1b[201~包裹文本。这意味着它走的是和真实终端粘贴完全相同的处理管道因此大段内容会自动触发粘贴特有的折叠collapse逻辑setEditorText/getEditorText分别映射到编辑器实例的setText/getText是同步、即时生效的操作。类型签名方面getToolsExpanded(): boolean与setToolsExpanded(expanded: boolean): void在 types.ts 中定义交互实现则直接读写宿主状态并触发重绘。八、主题管理Theme Management主题 API 允许扩展枚举、预加载、切换主题并始终能访问当前主题用于着色。// 列出所有可用主题含名称与文件路径 const themes ctx.ui.getAllThemes(); // [{ name: dark, path: ... }, ...] // 按名称加载主题不切换仅用于预取 const lightTheme ctx.ui.getTheme(light); // 按名称切换主题 const result ctx.ui.setTheme(light); if (!result.success) ctx.ui.notify(result.error!, error); // 也可直接传入 Theme 对象切换 ctx.ui.setTheme(lightTheme!); // 访问当前主题进行文本着色 ctx.ui.theme.fg(accent, styled text);API 语义与返回值根据类型定义types.tsreadonly theme: Theme—— 当前主题实例用于fg、bold、strikethrough等样式方法getAllThemes(): { name: string; path: string | undefined }[]—— 所有主题的名称与路径如path未定义可能表示内置主题getTheme(name: string): Theme | undefined—— 按名加载但不切换找不到时返回undefinedsetTheme(theme: string | Theme): { success: boolean; error?: string }—— 切换主题并返回结构化结果失败时error携带原因配合ctx.ui.notify(result.error!, error)可优雅地告知用户。源码实现细节切换的副作用交互模式的setTheme实现extension-ui-controller.ts展示了更多细节传入Theme对象时走setThemeInstance分支并触发重绘传入名称时走setTheme(name, true)成功后会同步把选择持久化到 settingsManagerhost.settingsManager.setTheme(themeOrName)这意味着通过ctx.ui.setTheme切换的主题会被记住下次启动依然生效无论哪种分支成功后都会调用host.ui.requestRender()让整个界面立即按新主题重绘。九、组合实践一个“会话监控”扩展示例把前文各能力组合起来可以构建一个完整、有实战价值的扩展。下面展示如何用一个扩展同时使用持久化 UI 的多个元素// 假设已在扩展入口拿到 ctx function initMonitorExtension(ctx) { // 1) Footer 状态显示监控模式 ctx.ui.setStatus(monitor, ctx.ui.theme.fg(accent, ● Monitoring)); // 2) 上方 Widget展示当前待办 ctx.ui.setWidget(monitor-tasks, [Step 1: plan, Step 2: implement, Step 3: verify]); // 3) 自定义 Footer左侧显示模型右侧显示 Git 分支分支变化自动重绘 ctx.ui.setFooter((tui, theme, footerData) ({ invalidate() {}, render(width: number): string[] { const branch footerData.getGitBranch() || no git; const left theme.fg(dim, ctx.model?.id || no-model); const right theme.fg(dim, branch); const pad .repeat(Math.max(1, width - visibleWidth(left) - visibleWidth(right))); return [truncateToWidth(left pad right, width)]; }, dispose: footerData.onBranchChange(() tui.requestRender()), })); // 4) 长任务开始时设置工作消息结束时恢复默认 ctx.ui.setWorkingMessage(Running monitor analysis...); // ... 任务完成后 ctx.ui.setWorkingMessage(); // 5) 清理阶段恢复内置 Footer 并清除状态 return () { ctx.ui.setFooter(undefined); ctx.ui.setStatus(monitor, undefined); ctx.ui.setWidget(monitor-tasks, undefined); }; }实战要点小结Key 隔离setStatus与setWidget都以字符串 key 管理不同扩展务必使用各自的 key 前缀如扩展名避免相互覆盖undefined即清除所有持久化元素Status、Widget、Footer、Header都以传入undefined表示恢复默认或删除Footer 是唯一拿分支的地方若需展示 Git 分支必须用setFooter并通过footerData.getGitBranch()获取同时配合onBranchChange实现响应式更新主题切换会被持久化ctx.ui.setTheme(name)成功后写回 settings影响下次启动请谨慎使用善用result.success切换主题这类可能失败的调用务必检查返回值并给出用户提示。十、进一步探索如果你想从源码层面深入理解这套持久化 UI 机制以下是本仓库中的关键入口API 类型定义packages/pi-coding-agent/src/core/extensions/types.tsExtensionUIContext、ExtensionWidgetOptions、WidgetPlacement交互模式实现packages/pi-coding-agent/src/modes/interactive/controllers/extension-ui-controller.tsFooter 数据提供者packages/pi-coding-agent/src/core/footer-data-provider.ts扩展系统入门docs/dev/extending-pi/01-what-are-extensions.md 与 docs/dev/extending-pi/14-custom-rendering-controlling-what-the-user-sees.mdTUI 组件接口docs/dev/pi-ui-tui/02-the-component-interface-foundation-of-everything.md主题与样式docs/dev/pi-ui-tui/11-theming-colors-and-styles.md赞分享人工智能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点击查看免费下载相关推荐如何快速掌握mometa低代码编辑器从架构解析到扩展开发的完整指南如何快速掌握mometa低代码编辑器从架构解析到扩展开发的完整指南 mometa是一款面向研发的低代码元编程工具提供代码可视编辑和辅助编码功能帮助开发者通低代码前端开发工具CANN稀疏矩阵算子库README审查README 审查清单与流程用于 readme review 模式 审查清单9 项 | 编号 | 检查项 | 检查内容 | | | | | | 1 |人工智能AI Agent代码智能体Agent 编排CLIAI 应用Gutenberg 编辑后管理包实战指南深入解析 wordpress/edit-post 与文章编辑器 UI 扩展Gutenberg 编辑后管理包实战指南深入解析 wordpress/edit post 与文章编辑器 UI 扩展 wordpress/edit post后端前端上一篇4步构建Windows安卓开发环境WSABuilds完整部署实战指南下一篇Svelte构建系统Rollup配置和打包优化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考