人工智能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 编码代理pi-coding-agent的扩展体系系统讲解如何在扩展中修改发给 LLM 的系统提示System Prompt与上下文消息。你将掌握三条互补的注入通道通过before_agent_start事件在每一轮对话开始前改写 System Prompt 并注入持久化自定义消息、通过context事件在每次请求前过滤/变换消息序列、以及通过registerTool的promptSnippet与promptGuidelines让工具在激活时自动携带使用指南。读完即可为扩展实现每轮换风格、按工具给指引、按会话滤上下文的精细提示工程能力。所有示例均以 Extension 事件与 ToolDefinition 类型定义 中的真实签名为基础并辅以 扩展运行器 runner.ts、System Prompt 构造器 与 会话主循环 的源码级佐证可直接作为编写扩展的参考。为什么需要三条通道来修改提示pi 的扩展体系允许扩展订阅 Agent 生命周期事件、注册可被 LLM 调用的工具、注册命令与快捷键参见 Extension 系统类型定义。提示prompt是 Agent 行为的操作系统因此扩展系统提供了三个不同作用域的提示修改入口修改入口触发时机作用对象典型用途before_agent_start用户提交提示后、Agent 主循环开始前每轮一次System Prompt 追加自定义消息每轮切换语气/规则、注入会话级持久上下文context每次 LLM 请求发出前发送给 LLM 的完整消息列表过滤无关消息、压缩上下文、插入/删除消息registerTool的promptSnippet/promptGuidelinesSystem Prompt 构建时按激活工具集System Prompt 中Available tools与Guidelines小节让工具自带使用说明模型知道何时调用这三者对应 System Prompt 的全局改写消息面干预工具面增强三个层面可以单独使用也可以组合叠加。每轮修改before_agent_start事件完整示例pi.on(before_agent_start, async (event, ctx) { return { // Inject a persistent message (stored in session, visible to LLM) message: { customType: my-extension, content: Additional context for the LLM, display: true, }, // Modify the system prompt for this turn systemPrompt: event.systemPrompt \n\nYou must respond only in haiku., }; });事件负载与返回值BeforeAgentStartEvent的负载字段见 types.ts 定义prompt: string用户本次提交的提示文本含命令展开后的内容images?: ImageContent[]用户附带提交的图片内容systemPrompt: string当前生效的基准 System Promptbase system prompt。处理器返回对象支持两个可选字段message: { customType, content, display?, details? }注入一条自定义角色custom消息。它会被追加到本轮请求的用户消息之后并持久化到会话文件中对后续所有轮次持续可见systemPrompt: string本轮使用的完整 System Prompt。返回该字段即整体覆盖本轮提示。源码调用链印证在 agent-session.ts 中Agent 主循环先构造用户消息与待处理的 nextTurn 消息然后调用_extensionRunner.emitBeforeAgentStart(expandedText, currentImages, this._baseSystemPrompt)所有扩展返回的message会以role: custom压入消息队列并保留customType、content、display、details字段若存在返回的systemPrompt调用agent.setSystemPrompt(result.systemPrompt)使其对本轮生效若没有返回则显式agent.setSystemPrompt(this._baseSystemPrompt)确保上一轮产生的临时修改不会泄漏到本轮——这正是每轮重置到基准提示的设计保证。在 runner.ts 的emitBeforeAgentStart中多个扩展的处理器按注册顺序链式执行每个处理器都基于当前累积的systemPromptcurrentSystemPrompt计算后注册的处理器的返回值会覆盖前面处理器的结果所有message则会被收集合并。关于持久化在 agent-session.ts 中role custom的消息通过sessionManager.appendCustomMessageEntry(customType, content, display, details)写入会话即customType 注入的消息会长期驻留在会话上下文中。这也解释了注释中的提示——display: false可以控制该消息是否显示在 TUI 中渲染层通过getMessageRenderer(customType)查找对应的自定义渲染器见 runner.ts。实战要点注入持久上下文的最佳位置如果希望一段背景信息贯穿整个会话例如本项目遵循 X 规范在before_agent_start返回message即可无需每轮重复注入每轮临时指令只想影响当前这一轮如本轮只改这个文件优先使用systemPrompt返回字段它会随会话推进自动重置多扩展协同多个扩展同时注册before_agent_start时System Prompt 呈后写覆盖消息则全部保留——设计时注意避免与其他扩展的 systemPrompt 改写互相覆盖。上下文消息过滤context事件完整示例pi.on(context, async (event, ctx) { // event.messages is a deep copy — safe to modify const filtered event.messages.filter(m !isIrrelevant(m)); return { messages: filtered }; });语义与安全保证ContextEvent仅含一个字段messages: AgentMessage[]见 types.ts返回结构为{ messages: AgentMessage[] }。与before_agent_start不同context事件在每次 LLM 请求发出前都会触发因此既覆盖首轮也覆盖后续工具调用的每一轮请求。源码中 runner.ts 的 emitContext 首先执行structuredClone(messages)生成深拷贝再交给各扩展处理器链式过滤——这意味着处理器内可以安全地filter、splice、重排、替换消息不会污染会话内部状态多个处理器按注册顺序依次拿到前一个处理器过滤后的结果形成管道式的消息变换链若某个处理器返回的messages为 falsy/未定义则沿用当前累积结果不会中断链路。典型应用场景上下文瘦身过滤掉已过期的工具输出、无用的系统消息降低 token 消耗隐私/安全过滤在消息到达 LLM 前剔除包含密钥、敏感路径的内容配合仓库中的安全扫描思路条件注入根据ctx如当前会话、模型、目录决定是否把某些消息插入请求头部。注意事项该事件处理的是即将发送的消息因此不适合做跨轮持久化——持久化诉求应交给before_agent_start的message通道过滤后请保证消息序列在角色上仍然合法如保留首条 user/system 消息否则可能影响部分提供商的 API 校验。工具级提示内容promptSnippet与promptGuidelines完整示例pi.registerTool({ name: my_tool, promptSnippet: Summarize or transform text according to action, // Replaces description in Available tools promptGuidelines: [ Use my_tool when the user asks to summarize text., Prefer my_tool over direct output for structured data. ], // Added to Guidelines section when tool is active // ...parameters, execute... });二者在 System Prompt 中的落点ToolDefinition见 types.ts中promptSnippet?: string一段一行式简介。在默认 System Prompt 的Available tools:小节中替换该工具的description作为工具列表条目- my_tool: Summarize or transform text according to action。省略时回退到description字段promptGuidelines?: string[]一组指南要点。当该工具处于激活工具集时逐条追加到 System Prompt 的Guidelines:小节用于指导模型何时使用本工具、使用时遵循什么规则。构造机制源码佐证在 system-prompt.ts 中工具列表按tools.map((name) \- ${name}: ${toolSnippets?.[name] ?? toolDescriptions[name] ?? name})生成——promptSnippet正是在这里取代默认描述。而 [system-prompt.ts 的 L241-L246](https://link.gitcode.com/i/fde30559066b888a4c7d147f63190b40#L241-L246) 将扩展注册的promptGuidelines逐条trim()后经addGuideline去重追加最终与其他内置指南一起渲染进Guidelines: 小节。值得注意的实现细节指南只在该工具处于激活工具集时出现。默认激活工具为[read, bash, edit, write]见 BuildSystemPromptOptions 默认值自定义工具被激活例如通过ctx.runtime.setActiveTools或模型路由后其promptGuidelines才会进入 System Prompt同时 types.ts 注释 明确说明该字段when this tool is active生效。系统在addGuideline中通过Set去重避免多扩展注册重复指南。实战要点promptSnippet应控制在一行内因为它直接参与Available tools列表的排版promptGuidelines适合写调用条件 行为约束例如仅在用户明确要求总结时调用禁止对结构化数据直接输出优先使用本工具格式化仓库的扩展范例可参考 extensions/google-search真实扩展清单见 extension-manifest.json其中注册工具的方式即本节所示模式。综合实战三层注入协同以下示例把三个通道组合起来实现每轮注入会话级偏好 过滤过期工具输出 自定义工具自带使用指南的完整方案// 1) 每轮注入持久上下文 改写本轮提示 pi.on(before_agent_start, async (event) { return { message: { customType: prefs, content: Project conventions: use tabs, 80-col, prefer functional components., display: false, // 不在 TUI 中重复显示但 LLM 可见 }, systemPrompt: event.systemPrompt \n\nKeep answers under 200 words., }; }); // 2) 每次请求前过滤过期工具输出 pi.on(context, async (event) { const filtered event.messages.filter((m) { // 过滤超过一定轮次之前的 bash 输出示意 if (m.role ! toolResult) return true; return Date.now() - m.timestamp 60_000; }); return { messages: filtered }; }); // 3) 工具自带提示内容 pi.registerTool({ name: my_tool, promptSnippet: Transform text per the requested action, promptGuidelines: [ Use my_tool when the user asks to summarize or transform text., Prefer my_tool over direct output for structured data., ], parameters: { /* ... */ }, async execute(toolCallId, params, signal, onUpdate, ctx) { /* ... */ }, });组合使用时请留意三条通道的交互before_agent_start的systemPrompt返回值会覆盖registerTool等构造出的提示吗不会——before_agent_start拿到的event.systemPrompt本身就是包含工具列表与指南的当前基准提示你在其基础上做追加/修改即可保留工具指南除非你刻意整体替换。进一步阅读Extension 事件与类型定义全览BeforeAgentStartEvent、ContextEvent、ToolDefinition、ExtensionContext含getSystemPrompt()、getContextUsage()等运行时能力扩展运行器实现emitBeforeAgentStart、emitContext的链式处理与深拷贝语义System Prompt 构造器Available tools与Guidelines小节的内置生成逻辑会话主循环事件触发点、custom 消息持久化与 System Prompt 每轮重置机制扩展体系系列文档扩展生命周期与事件体系、事件机制详解、ExtensionContext 可用能力、Extension API 能力清单、自定义工具赋予 LLM 新能力、System Prompt 结构解剖、消息类型与 LLM 可见性、上下文注入模式扩展 Manifest 规范 与 扩展构建指南赞分享人工智能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点击查看免费下载相关推荐Brand TermsBrand Terms | Term | Full Name | Context | | | | | | abbreviation | full name |人工智能AI Agent代码智能体Agent 编排CLIAI 应用DeepSeek Harness 中工具 schema 的系统提示词组装机制PromptAssembly 与 system-prompt/assemble 瀑布事件DeepSeek Harness 中工具 schema 的系统提示词组装机制PromptAssembly 与 system prompt/assemble 瀑人工智能AI AgentAgent 框架DeepSeekGetQzonehistory 完整指南QQ空间说说备份与数据导出一步到位GetQzonehistory 完整指南QQ空间说说备份与数据导出一步到位 GetQzonehistory 是一款 QQ空间说说备份 工具扫码登录后抓取空间网页爬虫数据分析上一篇GSD-2 多模型多供应商工具策略ADR-005Provider 能力注册表、工具兼容过滤与跨供应商切换上下文保真下一篇Embroidermodder开源刺绣软件的革命创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考