人工智能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 扩展体系的核心入口ExtensionAPI即扩展工厂函数中收到的pi对象系统梳理其注册、消息、会话、工具、模型、Provider 管理六大能力域并结合仓库源码packages/pi-coding-agent/src/core/extensions/types.ts、loader.ts、runner.ts与真实扩展实例extensions/google-search/index.ts、packages/pi-coding-agent/src/resources/extensions/memory/index.ts展开深入讲解。读完本文你将能够从零编写一个可注册 LLM 工具、斜杠命令、键盘快捷键、CLI 标志、消息渲染器与自定义模型 Provider 的完整扩展并理解各 API 的底层调用链与适用场景。1. 认识 ExtensionAPI扩展的终身注册接口pi对象是扩展模块默认导出函数收到的第一个参数也是扩展与 GSD-2 核心运行时交互的唯一入口。它在扩展加载阶段被创建并在扩展整个生命周期内持续存在——这意味着你既可以在初始化阶段用它注册各类能力也可以在事件回调或命令处理器中随时调用它的动作类方法。从源码实现看pi对象由createExtensionAPI()构造packages/pi-coding-agent/src/core/extensions/loader.ts#L450-L619。它的方法被清晰地分为两类注册类方法on、registerTool、registerCommand、registerShortcut、registerFlag、registerMessageRenderer、registerProvider、unregisterProvider写入扩展自身的注册表动作类方法sendMessage、sendUserMessage、appendEntry、exec等委托给共享运行时ExtensionRuntime由ExtensionRunner.bindCore()注入真实实现runner.ts#L403-L444。动作类方法在扩展加载阶段还是“抛错桩”throw stubs只有在运行时绑定完成后才可用——源码中createExtensionRuntime()为每个动作方法默认生成Extension runtime not initialized的报错实现loader.ts#L402-L443。因此扩展的标准模式是在工厂函数同步阶段完成注册把动作类调用放在事件回调或命令处理器里执行。完整的接口定义见 packages/pi-coding-agent/src/core/extensions/types.ts#L1330-L1630扩展工厂函数类型ExtensionFactory (pi: ExtensionAPI) void | Promisevoid支持同步与异步两种初始化方式types.ts#L1698-L1699。2. 核心注册把能力挂载到 Agent 生命周期注册类 API 决定了一个扩展能为 Agent 贡献什么。下表是核心注册方法的速查方法用途pi.on(event, handler)订阅 Agent 生命周期事件pi.registerTool(definition)注册一个 LLM 可调用的工具pi.registerCommand(name, options)注册一个/command斜杠命令pi.registerShortcut(key, options)注册键盘快捷键pi.registerFlag(name, options)注册 CLI 标志pi.registerMessageRenderer(customType, renderer)注册自定义消息渲染器pi.registerProvider(name, config)注册/覆盖模型 Providerpi.unregisterProvider(name)移除一个 Provider2.1pi.on订阅事件on(event, handler)将处理器挂到扩展对象的handlersMap 上loader.ts#L458-L462。事件类型是强类型联合ExtensionEvent涵盖会话生命周期session_start、session_switch、session_before_compact、session_end…、Agent 循环agent_start、agent_end、stop、turn_start、message_*…、工具执行tool_call、tool_result、tool_execution_*…、Git 生命周期before_commit、commit、before_push、before_pr…、验证与预算before_verify、verify_result、budget_threshold…、编排milestone_*、unit_*等完整列表见 types.ts#L1156-L1192。处理器签名ExtensionHandlerE, R接收事件对象与ExtensionContext可以返回void或各事件专属的结果类型如SessionBeforeCompactResult、BeforeCommitEventResult用于否决/改写见 types.ts#L1323-L1325。2.2pi.registerTool赋予 LLM 新能力这是扩展最常用的注册方法。ToolDefinition的关键字段types.ts#L368-L402name/label/description工具名LLM 调用时使用、UI 展示标签、LLM 语义描述promptSnippet/promptGuidelines可选注入系统提示词的工具列表片段与使用准则帮助模型正确调用工具parametersTypeBox 参数 schemaTSchema对工具参数做运行时校验compatibility可选声明 Provider 兼容性元数据如producesImages、schemaFeatures、minCapabilityTier用于 ADR-005 的能力感知工具过滤types.ts#L356-L363execute(toolCallId, params, signal, onUpdate, ctx)核心执行函数返回AgentToolResultrenderCall/renderResult可选自定义工具调用/结果的 TUI 渲染。仓库内置的google_search工具是教科书级的示例extensions/google-search/index.ts#L178-L413。它使用Type.Object定义参数 schemaquery必填、maxSources可选且限定 1–10在execute里通过ctx.modelRegistry解析凭据、设置 30 秒超时、命中会话内缓存并输出带截断的结果同时用renderCall/renderResult实现了调用中和结果态的 TUI 展示。注册工具的底层逻辑会同时向tool-compatibility-registry登记兼容性元数据并触发refreshTools()loader.ts#L464-L474工具集随后会经过 Provider 能力过滤与adjust_tool_set事件的二次调整sdk.ts#L469-L486。2.3pi.registerCommand定义/commandregisterCommand(name, options)注册斜杠命令RegisteredCommand结构types.ts#L1285-L1290description命令说明getArgumentCompletions?(prefix)可选为参数提供自动补全项handler(args, ctx)命令处理器接收参数字符串与ExtensionCommandContext见第 7 节。内存扩展的/memory命令展示了完整用法包括基于子命令前缀的补全packages/pi-coding-agent/src/resources/extensions/memory/index.ts#L165-L261api.registerCommand(memory, { description: View or manage extracted project memories, getArgumentCompletions: (prefix) { const subcommands [ { label: view, description: View current memories (default) }, { label: clear, description: Clear all memories for this project }, { label: rebuild, description: Re-extract all memories }, { label: stats, description: Show pipeline statistics }, ]; return subcommands .filter((s) s.label.startsWith(prefix)) .map((s) ({ value: s.label, label: s.label, description: s.description })); }, handler: async (args, ctx) { /* ... */ }, });命令名存在冲突保护内置命令优先同名扩展命令后注册者被跳过gsd命令被标记为受保护命令仅限特定扩展拥有runner.ts#L605-L687。2.4pi.registerShortcut键盘快捷键registerShortcut(key, options)接收KeyId如ctrlr与{ description?, handler(ctx) }。底层对内置键位有冲突保护interrupt、clear、exit、submit等 18 个保留动作不允许扩展覆盖非保留键可被覆盖但会给出诊断警告runner.ts#L80-L98、runner.ts#L525-L568。2.5pi.registerFlagCLI 标志registerFlag(name, { description?, type: boolean | string, default? })注册命令行标志注册时会把默认值写入运行时flagValuesMap后续 CLI 解析会覆盖该值loader.ts#L506-L514。2.6pi.registerMessageRenderer自定义消息渲染registerMessageRenderer(customType, renderer)为自定义消息类型注册 TUI 渲染器。渲染器签名MessageRendererT接收消息、展开选项与主题对象返回一个Componenttypes.ts#L1271-L1279。它与sendMessage/appendEntry的customType字段配合渲染器负责“如何显示”数据负责“传什么”。2.7pi.registerProvider/pi.unregisterProvider模型 Provider 管理扩展可以注册全新的 Provider也可以覆盖已有 Provider配置对象ProviderConfig支持types.ts#L1637-L1670authModeapiKey | oauth | externalCli | none默认为apiKeybaseUrl/apiKey/apiAPI 端点、密钥或环境变量名、API 类型models模型列表提供时整体替换该 Provider 的模型仅提供baseUrl则只覆盖地址oauth注册 OAuth 登录支持配合/loginstreamSimple自定义 API 的流式处理函数headers/authHeader请求头配置。ProviderModelConfig定义了模型的完整元数据id、name、reasoning是否支持扩展思考、inputtext/image、cost输入/输出/缓存读/缓存写的 token 单价用于成本追踪、contextWindow、maxTokens等types.ts#L1673-L1696。注册的时序很重要扩展加载期间的注册会被排队到pendingProviderRegistrations待bindCore()绑定模型注册表后一次性刷入加载完成后调用则立即生效无需/reloadtypes.ts#L1737-L1745、runner.ts#L434-L443。unregisterProvider(name)会移除该 Provider 的全部模型并恢复被覆盖的内置模型types.ts#L1613-L1626。3. 消息注入sendMessage与sendUserMessage消息类 API 让扩展能把内容注入会话、甚至主动触发一轮新的 Agent 交互方法用途pi.sendMessage(message, options?)向会话注入一条自定义消息pi.sendUserMessage(content, options?)发送用户消息触发一轮对话sendMessage的消息体用PickCustomMessage, customType | content | display | details描述types.ts#L1476-L1479其中customType与registerMessageRenderer注册的类型对应。若传triggerTurn: true注入后还会触发一轮处理。sendMessage投递模式delivery modes是控制消息与 Agent 流式输出时序的关键steer默认中断当前流式输出在当前工具执行完成后投递剩余工具调用被跳过——适合抢占式纠偏followUp等待 Agent 完全结束不再有工具调用后投递——适合在 Agent 空闲后追加信息nextTurn排队到下一次用户输入不中断当前回合——适合无侵入式的预注入。sendUserMessage(content, options?)总是触发一轮对话content可以是字符串也可以是(TextContent | ImageContent)[]支持图片消息options.deliverAs支持steer | followUptypes.ts#L1485-L1488。内存扩展就是sendMessage的典型使用者/memory stats把统计文本以customType: memory:stats、display: true注入会话展示memory/index.ts#L246-L251。4. 状态与会话持久化与导航方法用途pi.appendEntry(customType, data?)持久化扩展状态不会发送给 LLMpi.setSessionName(name)设置会话选择器中的显示名pi.getSessionName()获取当前会话名pi.setLabel(entryId, label)为条目打标签供/tree导航appendEntry向会话追加一条自定义类型条目它只用于持久化扩展自身的状态不会被送入 LLM 上下文这为扩展提供了一块干净的私有存储区。setLabel相当于“书签”机制——给某个会话条目附加标记随后可在会话树中据此定位types.ts#L1510-L1511。5. 工具管理运行时开关工具集方法用途pi.getActiveTools()获取当前激活的工具名列表pi.getAllTools()获取所有已注册工具name descriptionpi.setActiveTools(names)运行时启用/禁用工具getAllTools()返回ToolInfo[]其中ToolInfo PickToolDefinition, name | description | parameterstypes.ts#L1728。setActiveTools让扩展能在运行中按需收窄或扩展 LLM 可调用的工具面——例如按模型能力、按任务阶段切换工具集。这一能力与adjust_tool_set事件模型选择后按 Provider 能力增删/重排工具互补types.ts#L885-L909。6. 模型管理切换模型与思考深度方法用途pi.setModel(model)切换模型无 API key 时返回falsepi.getThinkingLevel()获取当前思考级别pi.setThinkingLevel(level)设置思考级别off到xhighsetModel(model, options?)接受一个Modelany对象options.persist可控制是否持久化选择返回Promiseboolean——当该模型的 Provider 没有任何可用 API key 时会返回falsetypes.ts#L1546-L1547。ThinkingLevel的取值域为off到xhighsetThinkingLevel会按模型能力做钳制——若模型不支持推理reasoning: false思考级别会被强制设为offsdk.ts#L384-L387。7. 工具与事件总线exec、events、getFlag、getCommands方法用途pi.exec(command, args, options?)执行一条 Shell 命令pi.events扩展间通信的共享事件总线pi.getFlag(name)读取已注册 CLI 标志的值pi.getCommands()获取当前会话所有可用的斜杠命令exec底层走execCommand(command, args, options?.cwd ?? cwd, options)默认工作目录为扩展加载时的cwdloader.ts#L555-L557。events是EventBus类型的共享总线供不同扩展之间发布/订阅自定义事件实现跨扩展协作。getFlag只返回本扩展自己注册过的标志值未注册的返回undefinedloader.ts#L521-L524。8. ExtensionCommandContext命令专属的会话控制权命令处理器收到的是ExtensionCommandContext它在ExtensionContext含ui、cwd、sessionManager、model、abort()、compact()、getSystemPrompt()等基础上额外提供了会话控制方法——这些方法在普通事件处理器中会死锁因此只在用户主动触发的命令中开放方法用途ctx.waitForIdle()等待 Agent 完成流式输出ctx.newSession(options?)创建新会话ctx.fork(entryId)从某个条目分叉出新会话ctx.navigateTree(targetId, options?)在会话树中导航ctx.reload()热重载扩展、技能、提示词、主题newSession支持parentSession、setup初始化回调、workspaceRoot、abortSignal选项types.ts#L310-L322。navigateTree的options支持summarize是否生成摘要、customInstructions、replaceInstructions、labeltypes.ts#L328-L331。switchSession(sessionPath)还支持切换到指定的会话文件。所有方法返回{ cancelled: boolean }用于区分操作被取消与成功完成。从源码看命令上下文由createCommandContext()构建这些处理器默认是“未绑定”的抛错桩直到bindCommandContext(actions)注入真实实现runner.ts#L736-L746、runner.ts#L446-L463。9. 端到端实战写一个最小扩展综合以上 API一个最小但完整的扩展结构如下可放置于~/.pi/agent/extensions/或项目extensions/目录参照 extensions/google-search/index.ts 的组织方式import type { ExtensionAPI } from gsd/pi-coding-agent; import { Type } from sinclair/typebox; export default function myExtension(pi: ExtensionAPI): void { // 1) 注册 LLM 工具 pi.registerTool({ name: hello, label: Hello, description: Returns a greeting. Use for simple demos., parameters: Type.Object({ name: Type.String({ description: Who to greet }), }), async execute(_toolCallId, params) { return { content: [{ type: text, text: Hello, ${params.name}! }], }; }, }); // 2) 注册斜杠命令 pi.registerCommand(demo, { description: Demo command, handler: async (_args, ctx) { await ctx.waitForIdle(); // 等待 Agent 空闲 pi.sendUserMessage(Run the hello tool on the current project.); // 触发一轮 }, }); // 3) 订阅事件会话启动时输出状态 pi.on(session_start, async (_event, ctx) { ctx.ui.notify(Demo extension active in ${ctx.cwd}, info); }); }编写扩展时的实践要点注册放同步阶段动作放回调里registerTool等注册方法在任何阶段都安全而sendMessage、exec等动作方法在绑定前调用会抛 Extension runtime not initialized善用事件钩子实现自动化像内存扩展那样在session_start时 fire-and-forget 启动后台流水线在before_agent_start中改写系统提示词注入上下文memory/index.ts#L89-L162为工具写好系统提示词元数据promptSnippet与promptGuidelines直接影响模型对工具的采用率参考 google_search 的做法extensions/google-search/index.ts#L187-L194冲突管理命令、快捷键、工具名都存在优先级规则注册前先通过getCommands()、getActiveTools()探测现场。10. 小结ExtensionAPI是一个覆盖面完整、类型安全的扩展接口注册侧覆盖工具、命令、快捷键、CLI 标志、消息渲染器与模型 Provider动作侧覆盖消息注入三种投递模式、会话持久化、工具集开关、模型切换与 Shell 执行命令上下文还额外解锁了会话树导航、分叉与热重载等“仅限用户主动操作”的高权限能力。通过on订阅 40 种生命周期事件并利用before_*系列事件的否决/改写返回值扩展可以深度嵌入 Agent 的决策循环——这正是 GSD-2 支持 Agent 长时间自主运行而不丢失全局上下文的关键机制。相关深度资料可继续阅读 ExtensionContext 详解、事件系统总览 与 扩展生命周期。赞分享人工智能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 Docker 沙箱实战指南为 Agent 长期自主运行搭建隔离环境GSD Docker 沙箱实战指南为 Agent 长期自主运行搭建隔离环境 GSDGitHub 加速计划 / gsd 2是一款基于元提示词meta pr人工智能AI Agent代码智能体Agent 编排CLIAI 应用Pigsd-2运行时架构全解Model Registry、Agent Session、事件系统与扩展机制如何协同工作Pigsd 2运行时架构全解Model Registry、Agent Session、事件系统与扩展机制如何协同工作 导读 本文以 Pi 架构文档 htt人工智能AI Agent代码智能体Agent 编排CLIAI 应用深入解析 gsd-2 中的 Pi终端原生、可无限扩展的编码 Agent 架构深入解析 gsd 2 中的 Pi终端原生、可无限扩展的编码 Agent 架构 Pi 是 gsd 2 仓库中内置的一套 终端原生编码 Agent 框架 位于开人工智能AI Agent代码智能体Agent 编排CLIAI 应用上一篇Seraphine英雄联盟战绩查询工具5分钟掌握智能BP与实时数据分析终极指南下一篇如何5分钟把Argos Translate离线机器翻译接入你的Python项目创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/6 2:31:43 · 阅读 1.2k ExtensionAPI 全景指南：掌握 pi 对象，为 GSD-2 构建可长时自主运行的 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 扩展体系的核心入口ExtensionAPI即扩展工厂函数中收到的pi对象系统梳理其注册、消息、会话、工具、模型、Provider 管理六大能力域并结合仓库源码packages/pi-coding-agent/src/core/extensions/types.ts、loader.ts、runner.ts与真实扩展实例extensions/google-search/index.ts、packages/pi-coding-agent/src/resources/extensions/memory/index.ts展开深入讲解。读完本文你将能够从零编写一个可注册 LLM 工具、斜杠命令、键盘快捷键、CLI 标志、消息渲染器与自定义模型 Provider 的完整扩展并理解各 API 的底层调用链与适用场景。1. 认识 ExtensionAPI扩展的终身注册接口pi对象是扩展模块默认导出函数收到的第一个参数也是扩展与 GSD-2 核心运行时交互的唯一入口。它在扩展加载阶段被创建并在扩展整个生命周期内持续存在——这意味着你既可以在初始化阶段用它注册各类能力也可以在事件回调或命令处理器中随时调用它的动作类方法。从源码实现看pi对象由createExtensionAPI()构造packages/pi-coding-agent/src/core/extensions/loader.ts#L450-L619。它的方法被清晰地分为两类注册类方法on、registerTool、registerCommand、registerShortcut、registerFlag、registerMessageRenderer、registerProvider、unregisterProvider写入扩展自身的注册表动作类方法sendMessage、sendUserMessage、appendEntry、exec等委托给共享运行时ExtensionRuntime由ExtensionRunner.bindCore()注入真实实现runner.ts#L403-L444。动作类方法在扩展加载阶段还是“抛错桩”throw stubs只有在运行时绑定完成后才可用——源码中createExtensionRuntime()为每个动作方法默认生成Extension runtime not initialized的报错实现loader.ts#L402-L443。因此扩展的标准模式是在工厂函数同步阶段完成注册把动作类调用放在事件回调或命令处理器里执行。完整的接口定义见 packages/pi-coding-agent/src/core/extensions/types.ts#L1330-L1630扩展工厂函数类型ExtensionFactory (pi: ExtensionAPI) void | Promisevoid支持同步与异步两种初始化方式types.ts#L1698-L1699。2. 核心注册把能力挂载到 Agent 生命周期注册类 API 决定了一个扩展能为 Agent 贡献什么。下表是核心注册方法的速查方法用途pi.on(event, handler)订阅 Agent 生命周期事件pi.registerTool(definition)注册一个 LLM 可调用的工具pi.registerCommand(name, options)注册一个/command斜杠命令pi.registerShortcut(key, options)注册键盘快捷键pi.registerFlag(name, options)注册 CLI 标志pi.registerMessageRenderer(customType, renderer)注册自定义消息渲染器pi.registerProvider(name, config)注册/覆盖模型 Providerpi.unregisterProvider(name)移除一个 Provider2.1pi.on订阅事件on(event, handler)将处理器挂到扩展对象的handlersMap 上loader.ts#L458-L462。事件类型是强类型联合ExtensionEvent涵盖会话生命周期session_start、session_switch、session_before_compact、session_end…、Agent 循环agent_start、agent_end、stop、turn_start、message_*…、工具执行tool_call、tool_result、tool_execution_*…、Git 生命周期before_commit、commit、before_push、before_pr…、验证与预算before_verify、verify_result、budget_threshold…、编排milestone_*、unit_*等完整列表见 types.ts#L1156-L1192。处理器签名ExtensionHandlerE, R接收事件对象与ExtensionContext可以返回void或各事件专属的结果类型如SessionBeforeCompactResult、BeforeCommitEventResult用于否决/改写见 types.ts#L1323-L1325。2.2pi.registerTool赋予 LLM 新能力这是扩展最常用的注册方法。ToolDefinition的关键字段types.ts#L368-L402name/label/description工具名LLM 调用时使用、UI 展示标签、LLM 语义描述promptSnippet/promptGuidelines可选注入系统提示词的工具列表片段与使用准则帮助模型正确调用工具parametersTypeBox 参数 schemaTSchema对工具参数做运行时校验compatibility可选声明 Provider 兼容性元数据如producesImages、schemaFeatures、minCapabilityTier用于 ADR-005 的能力感知工具过滤types.ts#L356-L363execute(toolCallId, params, signal, onUpdate, ctx)核心执行函数返回AgentToolResultrenderCall/renderResult可选自定义工具调用/结果的 TUI 渲染。仓库内置的google_search工具是教科书级的示例extensions/google-search/index.ts#L178-L413。它使用Type.Object定义参数 schemaquery必填、maxSources可选且限定 1–10在execute里通过ctx.modelRegistry解析凭据、设置 30 秒超时、命中会话内缓存并输出带截断的结果同时用renderCall/renderResult实现了调用中和结果态的 TUI 展示。注册工具的底层逻辑会同时向tool-compatibility-registry登记兼容性元数据并触发refreshTools()loader.ts#L464-L474工具集随后会经过 Provider 能力过滤与adjust_tool_set事件的二次调整sdk.ts#L469-L486。2.3pi.registerCommand定义/commandregisterCommand(name, options)注册斜杠命令RegisteredCommand结构types.ts#L1285-L1290description命令说明getArgumentCompletions?(prefix)可选为参数提供自动补全项handler(args, ctx)命令处理器接收参数字符串与ExtensionCommandContext见第 7 节。内存扩展的/memory命令展示了完整用法包括基于子命令前缀的补全packages/pi-coding-agent/src/resources/extensions/memory/index.ts#L165-L261api.registerCommand(memory, { description: View or manage extracted project memories, getArgumentCompletions: (prefix) { const subcommands [ { label: view, description: View current memories (default) }, { label: clear, description: Clear all memories for this project }, { label: rebuild, description: Re-extract all memories }, { label: stats, description: Show pipeline statistics }, ]; return subcommands .filter((s) s.label.startsWith(prefix)) .map((s) ({ value: s.label, label: s.label, description: s.description })); }, handler: async (args, ctx) { /* ... */ }, });命令名存在冲突保护内置命令优先同名扩展命令后注册者被跳过gsd命令被标记为受保护命令仅限特定扩展拥有runner.ts#L605-L687。2.4pi.registerShortcut键盘快捷键registerShortcut(key, options)接收KeyId如ctrlr与{ description?, handler(ctx) }。底层对内置键位有冲突保护interrupt、clear、exit、submit等 18 个保留动作不允许扩展覆盖非保留键可被覆盖但会给出诊断警告runner.ts#L80-L98、runner.ts#L525-L568。2.5pi.registerFlagCLI 标志registerFlag(name, { description?, type: boolean | string, default? })注册命令行标志注册时会把默认值写入运行时flagValuesMap后续 CLI 解析会覆盖该值loader.ts#L506-L514。2.6pi.registerMessageRenderer自定义消息渲染registerMessageRenderer(customType, renderer)为自定义消息类型注册 TUI 渲染器。渲染器签名MessageRendererT接收消息、展开选项与主题对象返回一个Componenttypes.ts#L1271-L1279。它与sendMessage/appendEntry的customType字段配合渲染器负责“如何显示”数据负责“传什么”。2.7pi.registerProvider/pi.unregisterProvider模型 Provider 管理扩展可以注册全新的 Provider也可以覆盖已有 Provider配置对象ProviderConfig支持types.ts#L1637-L1670authModeapiKey | oauth | externalCli | none默认为apiKeybaseUrl/apiKey/apiAPI 端点、密钥或环境变量名、API 类型models模型列表提供时整体替换该 Provider 的模型仅提供baseUrl则只覆盖地址oauth注册 OAuth 登录支持配合/loginstreamSimple自定义 API 的流式处理函数headers/authHeader请求头配置。ProviderModelConfig定义了模型的完整元数据id、name、reasoning是否支持扩展思考、inputtext/image、cost输入/输出/缓存读/缓存写的 token 单价用于成本追踪、contextWindow、maxTokens等types.ts#L1673-L1696。注册的时序很重要扩展加载期间的注册会被排队到pendingProviderRegistrations待bindCore()绑定模型注册表后一次性刷入加载完成后调用则立即生效无需/reloadtypes.ts#L1737-L1745、runner.ts#L434-L443。unregisterProvider(name)会移除该 Provider 的全部模型并恢复被覆盖的内置模型types.ts#L1613-L1626。3. 消息注入sendMessage与sendUserMessage消息类 API 让扩展能把内容注入会话、甚至主动触发一轮新的 Agent 交互方法用途pi.sendMessage(message, options?)向会话注入一条自定义消息pi.sendUserMessage(content, options?)发送用户消息触发一轮对话sendMessage的消息体用PickCustomMessage, customType | content | display | details描述types.ts#L1476-L1479其中customType与registerMessageRenderer注册的类型对应。若传triggerTurn: true注入后还会触发一轮处理。sendMessage投递模式delivery modes是控制消息与 Agent 流式输出时序的关键steer默认中断当前流式输出在当前工具执行完成后投递剩余工具调用被跳过——适合抢占式纠偏followUp等待 Agent 完全结束不再有工具调用后投递——适合在 Agent 空闲后追加信息nextTurn排队到下一次用户输入不中断当前回合——适合无侵入式的预注入。sendUserMessage(content, options?)总是触发一轮对话content可以是字符串也可以是(TextContent | ImageContent)[]支持图片消息options.deliverAs支持steer | followUptypes.ts#L1485-L1488。内存扩展就是sendMessage的典型使用者/memory stats把统计文本以customType: memory:stats、display: true注入会话展示memory/index.ts#L246-L251。4. 状态与会话持久化与导航方法用途pi.appendEntry(customType, data?)持久化扩展状态不会发送给 LLMpi.setSessionName(name)设置会话选择器中的显示名pi.getSessionName()获取当前会话名pi.setLabel(entryId, label)为条目打标签供/tree导航appendEntry向会话追加一条自定义类型条目它只用于持久化扩展自身的状态不会被送入 LLM 上下文这为扩展提供了一块干净的私有存储区。setLabel相当于“书签”机制——给某个会话条目附加标记随后可在会话树中据此定位types.ts#L1510-L1511。5. 工具管理运行时开关工具集方法用途pi.getActiveTools()获取当前激活的工具名列表pi.getAllTools()获取所有已注册工具name descriptionpi.setActiveTools(names)运行时启用/禁用工具getAllTools()返回ToolInfo[]其中ToolInfo PickToolDefinition, name | description | parameterstypes.ts#L1728。setActiveTools让扩展能在运行中按需收窄或扩展 LLM 可调用的工具面——例如按模型能力、按任务阶段切换工具集。这一能力与adjust_tool_set事件模型选择后按 Provider 能力增删/重排工具互补types.ts#L885-L909。6. 模型管理切换模型与思考深度方法用途pi.setModel(model)切换模型无 API key 时返回falsepi.getThinkingLevel()获取当前思考级别pi.setThinkingLevel(level)设置思考级别off到xhighsetModel(model, options?)接受一个Modelany对象options.persist可控制是否持久化选择返回Promiseboolean——当该模型的 Provider 没有任何可用 API key 时会返回falsetypes.ts#L1546-L1547。ThinkingLevel的取值域为off到xhighsetThinkingLevel会按模型能力做钳制——若模型不支持推理reasoning: false思考级别会被强制设为offsdk.ts#L384-L387。7. 工具与事件总线exec、events、getFlag、getCommands方法用途pi.exec(command, args, options?)执行一条 Shell 命令pi.events扩展间通信的共享事件总线pi.getFlag(name)读取已注册 CLI 标志的值pi.getCommands()获取当前会话所有可用的斜杠命令exec底层走execCommand(command, args, options?.cwd ?? cwd, options)默认工作目录为扩展加载时的cwdloader.ts#L555-L557。events是EventBus类型的共享总线供不同扩展之间发布/订阅自定义事件实现跨扩展协作。getFlag只返回本扩展自己注册过的标志值未注册的返回undefinedloader.ts#L521-L524。8. ExtensionCommandContext命令专属的会话控制权命令处理器收到的是ExtensionCommandContext它在ExtensionContext含ui、cwd、sessionManager、model、abort()、compact()、getSystemPrompt()等基础上额外提供了会话控制方法——这些方法在普通事件处理器中会死锁因此只在用户主动触发的命令中开放方法用途ctx.waitForIdle()等待 Agent 完成流式输出ctx.newSession(options?)创建新会话ctx.fork(entryId)从某个条目分叉出新会话ctx.navigateTree(targetId, options?)在会话树中导航ctx.reload()热重载扩展、技能、提示词、主题newSession支持parentSession、setup初始化回调、workspaceRoot、abortSignal选项types.ts#L310-L322。navigateTree的options支持summarize是否生成摘要、customInstructions、replaceInstructions、labeltypes.ts#L328-L331。switchSession(sessionPath)还支持切换到指定的会话文件。所有方法返回{ cancelled: boolean }用于区分操作被取消与成功完成。从源码看命令上下文由createCommandContext()构建这些处理器默认是“未绑定”的抛错桩直到bindCommandContext(actions)注入真实实现runner.ts#L736-L746、runner.ts#L446-L463。9. 端到端实战写一个最小扩展综合以上 API一个最小但完整的扩展结构如下可放置于~/.pi/agent/extensions/或项目extensions/目录参照 extensions/google-search/index.ts 的组织方式import type { ExtensionAPI } from gsd/pi-coding-agent; import { Type } from sinclair/typebox; export default function myExtension(pi: ExtensionAPI): void { // 1) 注册 LLM 工具 pi.registerTool({ name: hello, label: Hello, description: Returns a greeting. Use for simple demos., parameters: Type.Object({ name: Type.String({ description: Who to greet }), }), async execute(_toolCallId, params) { return { content: [{ type: text, text: Hello, ${params.name}! }], }; }, }); // 2) 注册斜杠命令 pi.registerCommand(demo, { description: Demo command, handler: async (_args, ctx) { await ctx.waitForIdle(); // 等待 Agent 空闲 pi.sendUserMessage(Run the hello tool on the current project.); // 触发一轮 }, }); // 3) 订阅事件会话启动时输出状态 pi.on(session_start, async (_event, ctx) { ctx.ui.notify(Demo extension active in ${ctx.cwd}, info); }); }编写扩展时的实践要点注册放同步阶段动作放回调里registerTool等注册方法在任何阶段都安全而sendMessage、exec等动作方法在绑定前调用会抛 Extension runtime not initialized善用事件钩子实现自动化像内存扩展那样在session_start时 fire-and-forget 启动后台流水线在before_agent_start中改写系统提示词注入上下文memory/index.ts#L89-L162为工具写好系统提示词元数据promptSnippet与promptGuidelines直接影响模型对工具的采用率参考 google_search 的做法extensions/google-search/index.ts#L187-L194冲突管理命令、快捷键、工具名都存在优先级规则注册前先通过getCommands()、getActiveTools()探测现场。10. 小结ExtensionAPI是一个覆盖面完整、类型安全的扩展接口注册侧覆盖工具、命令、快捷键、CLI 标志、消息渲染器与模型 Provider动作侧覆盖消息注入三种投递模式、会话持久化、工具集开关、模型切换与 Shell 执行命令上下文还额外解锁了会话树导航、分叉与热重载等“仅限用户主动操作”的高权限能力。通过on订阅 40 种生命周期事件并利用before_*系列事件的否决/改写返回值扩展可以深度嵌入 Agent 的决策循环——这正是 GSD-2 支持 Agent 长时间自主运行而不丢失全局上下文的关键机制。相关深度资料可继续阅读 ExtensionContext 详解、事件系统总览 与 扩展生命周期。赞分享人工智能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 Docker 沙箱实战指南为 Agent 长期自主运行搭建隔离环境GSD Docker 沙箱实战指南为 Agent 长期自主运行搭建隔离环境 GSDGitHub 加速计划 / gsd 2是一款基于元提示词meta pr人工智能AI Agent代码智能体Agent 编排CLIAI 应用Pigsd-2运行时架构全解Model Registry、Agent Session、事件系统与扩展机制如何协同工作Pigsd 2运行时架构全解Model Registry、Agent Session、事件系统与扩展机制如何协同工作 导读 本文以 Pi 架构文档 htt人工智能AI Agent代码智能体Agent 编排CLIAI 应用深入解析 gsd-2 中的 Pi终端原生、可无限扩展的编码 Agent 架构深入解析 gsd 2 中的 Pi终端原生、可无限扩展的编码 Agent 架构 Pi 是 gsd 2 仓库中内置的一套 终端原生编码 Agent 框架 位于开人工智能AI Agent代码智能体Agent 编排CLIAI 应用上一篇Seraphine英雄联盟战绩查询工具5分钟掌握智能BP与实时数据分析终极指南下一篇如何5分钟把Argos Translate离线机器翻译接入你的Python项目创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考