Pi（gsd-2）自定义技术栈完全指南：Extensions、Skills、Prompt Templates 与 Themes 四层定制体系详解

人工智能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 代理的四层自定义机制——Extensions扩展、Skills技能、Prompt Templates提示词模板与 Themes主题。读完本文你将掌握每层的适用场景、目录放置规则、调用方式与底层实现原理能够根据实际需求为 Pi 组装出从快速改文字提示到完全重写运行时行为的任意自定义能力。四层自定义栈总览Pi 提供四层由浅入深的自定义机制每层服务于不同的目的从改个颜色到完全接管运行时逐级递增能力与复杂度┌─────────────────────────────────────┐ │ Extensions │ ← TypeScript 代码。完整运行时访问权限。 │ Custom tools, events, UI, │ 可以做任何事。 │ commands, providers │ ├─────────────────────────────────────┤ │ Skills │ ← Markdown 指令 脚本。 │ On-demand capability packages │ 任务匹配时才加载。 │ loaded by the agent │ ├─────────────────────────────────────┤ │ Prompt Templates │ ← Markdown 片段。 │ Reusable prompts expanded │ 通过 /name 快速文本展开。 │ via /templatename │ ├─────────────────────────────────────┤ │ Themes │ ← JSON 颜色定义。 │ Visual appearance │ 修改后热重载。 └─────────────────────────────────────┘理解这四层的关键在于权衡表达能力与使用成本Extensions 是唯一的程序级定制能够挂钩事件、注册工具、渲染 UI几乎无所不能但也要求开发者编写并维护 TypeScript 模块Skills 面向按需装载领域能力是结构化、渐进式披露的指令包Prompt Templates 只是简单的文本展开Themes 则仅影响 TUI 视觉外观。下一层无法满足需求时再向上一层升级。一、Extensions拥有完整运行时访问权的最高层定制Extensions 是 TypeScript 模块拥有完整的运行时访问权限。它们可以挂钩每一个事件、注册可供 LLM 调用的工具、添加命令、渲染自定义 UI、覆盖内置行为、注册模型提供者model providers。Extensions 是最强大的自定义机制。放置位置~/.gsd/agent/extensions/全局所有项目可用.gsd/extensions/项目级仅当前项目生效入口文件解析规则从源码 extension-discovery.ts 可以确认扩展目录的入口解析遵循manifest 优先、文件名回退的确定性顺序若目录内存在带pi清单对象的package.json则该清单具有权威性pi.extensions数组中的每个条目按目录解析为入口文件若声明pi: {}无 extensions则返回空——这是库目录如 cmux的退出机制仅当不存在pi清单时才回退到index.ts→index.js的自动探测。顶层目录下的.ts/.js文件会被视为独立扩展入口子目录则通过上述规则解析见 discoverExtensionEntryPaths。同时已安装扩展若与内置扩展 manifest ID 相同则以安装版为准shadow 覆盖见 mergeExtensionEntryPaths。Manifest 与启停机制带清单的扩展在目录内放置extension-manifest.json字段包括id、name、version、description、tiercore/bundled/community、requires.platform以及声明能力的providestools、commands、hooks、shortcuts和dependencies。可参考仓库内示例 extensions/google-search/extension-manifest.json{ id: google-search, name: Google Search, version: 1.0.0, description: Web search via Google with AI-synthesized answers and source citations, tier: bundled, requires: { platform: 2.29.0 }, provides: { tools: [google_search], hooks: [session_start] } }启停由 extension-registry.ts 维护没有 manifest 的扩展总是加载向后兼容新安装的扩展默认全部启用唯一让扩展停止加载的方式是显式执行gsd extensions disable id。核心扩展tier: core不可禁用尝试禁用会返回错误提示。真实扩展示例如何注册一个 Tool仓库内的 Google Search 扩展extensions/google-search/index.ts展示了完整模式导出一个接收ExtensionAPI的默认函数在其中调用pi.registerTool({...})注册google_search工具同时通过pi.on(session_start, ...)挂钩会话启动事件检查认证状态、pi.on(session_shutdown, ...)清理会话级缓存。工具定义中包含name、label、description、promptSnippet、promptGuidelinesLLM 使用指引、基于 TypeBox 的parameters参数约束以及execute执行逻辑和renderCall/renderResult的自定义 TUI 渲染。export default function (pi: ExtensionAPI) { pi.registerTool({ name: google_search, label: Google Search, description: Search the web using Google Search via Gemini. ..., parameters: Type.Object({ query: Type.String({ description: The search query }), maxSources: Type.Optional( Type.Number({ description: Maximum number of source URLs (default 5, max 10)., minimum: 1, maximum: 10 }) ), }), async execute(_toolCallId, params, signal, _onUpdate, ctx) { // 调用 Gemini grounding、解析来源、会话内缓存…… }, }); }从实现可见扩展能够访问ctx.modelRegistry、ctx.ui等上下文对象具备完整的运行时能力。本仓库还内置了大量生产级扩展可供学习例如src/resources/extensions/gsd/GSD 编排系统本身就是一个巨型扩展、ollama、mcp-client、context7、remote-questions等。完整的扩展开发文档见 docs/dev/extending-pi/ 与 docs/extension-sdk/。二、Skills按需加载的 Agent 能力包Skills 是遵循 Agent Skills 标准agentskills.io的按需能力包。一个 skill 是包含SKILL.md文件的目录其中写有 agent 要遵循的指令。Skills 是渐进式progressive的只有技能名称和描述会进入系统提示词agent 仅在任务匹配时才读取完整的SKILL.md。工作流程启动时Pi 扫描技能目录并提取每个技能的 name description这些描述被列在系统提示词中即available_skills目录当任务与某个技能描述匹配时agent 使用read工具加载完整的SKILL.mdagent 遵循其中指令并使用相对路径引用脚本/资源。源码 skill-discovery.ts 印证了 frontmatter 解析逻辑SKILL.md以---\n开头通过name:与description:键提取元数据探测到的新技能会被格式化为newly_discovered_skillsXML 块注入系统提示词使后续任务立即可见formatSkillsXml。调用方式/skill:brave-search # 显式调用 /skill:pdf-tools extract file.pdf # 带参数调用放置位置~/.agents/skills/全局——跨所有 agent 共享.agents/skills/项目级向 git 根目录逐级向上搜索此外 skill-discovery.ts 还兼容~/.claude/skills/Claude Code 官方技能目录两个目录会被合并扫描。标准目录结构my-skill/ ├── SKILL.md # 必需frontmatter 指令 ├── scripts/ # 辅助脚本可选 │ └── process.sh └── references/ # 参考文档可选 └── api-guide.md对于复杂技能create-skill 技能 推荐的 Router 模式进一步扩展为五目录结构skill-name/ ├── SKILL.md # Router 原则 ├── workflows/ # 分步流程FOLLOW ├── references/ # 领域知识READ ├── templates/ # 输出结构COPY FILL └── scripts/ # 可复用代码EXECUTE其核心设计约束包括SKILL.md必须控制在 500 行以内渐进式披露、正文优先使用语义化 XML 标签objective、process、success_criteria而非 markdown 标题、YAML frontmatter 必备name小写连字符命名与目录一致和description说明做什么 何时使用。仓库内置了大量真实技能作为参考例如 src/resources/skills/tdd/SKILL.md、src/resources/skills/forensics/SKILL.md、src/resources/skills/create-gsd-extension/SKILL.md 等。Skills 与 Extensions 的选择Skills 的加载成本低只有描述常驻系统提示词适合承载领域知识包Extensions 则适合需要程序逻辑工具、事件、UI的能力。二者可以组合例如 GSD 自己的 gsd-headless 技能 负责教会 agent 如何通过 headless CLI 编排项目而编排的底层实现则由 gsd 扩展提供。三、Prompt Templates通过/name展开的可复用提示词Prompt Templates 是 Markdown 文件通过/名称展开为提示词。它是纯文本展开支持位置参数$1、$2、$不涉及任何代码逻辑。完整示例以下文件放在~/.gsd/agent/prompts/review.md--- description: Review staged git changes --- Review the staged changes (git diff --cached). Focus on: - Bugs and logic errors - Security issues - Performance problems Focus area: $1使用方式输入/review error handling即展开为完整提示词其中$1被替换为error handling。YAML frontmatter 中的description用于在命令列表中展示该模板的用途。放置位置~/.gsd/agent/prompts/全局.gsd/prompts/项目级底层机制模板变量替换与缓存快照需要注意Prompt Templates/name展开与 GSD 扩展内部的 prompt 引擎是两套体系。GSD 扩展使用的 prompt loaderprompt-loader.ts揭示了模板系统的通用实现要点模板文件从prompts/与templates/目录按.md后缀加载文件名去扩展名作为模板名占位符采用{{variableName}}语法进行替换替换前会先校验模板声明的所有{{变量}}都必须在提供的变量集中有值否则抛出GSD_PARSE_ERROR——这能避免内存中的扩展代码比磁盘上的模板旧、导致缺变量崩溃的经典问题模板在启动时被warmCache()快照进内存缓存prompt-loader.ts防止运行中的会话被并发覆盖的模板文件破坏保证了加载速度与运行期一致性。实战建议Prompt Templates 适合沉淀高频、稳定、无逻辑的提示词片段例如代码审查、PR 描述生成、问题复述模板。一旦模板需要条件分支、动态数据或与外部系统交互就应该升级为 Skill结构化指令或 Extension真正的代码。四、Themes热重载的 TUI 颜色主题Themes 是定义 TUI 调色板的 JSON 文件支持热重载编辑文件后 Pi 立即应用变更无需重启。内置主题darklight放置位置~/.gsd/agent/themes/全局.gsd/themes/项目级主题色在扩展中的使用方式主题对象通过回调参数传递给 UI 渲染代码不要直接 import 主题模块。TUI 主题文档 提供了完整的取色 API// 前景色 theme.fg(accent, Highlighted text) theme.fg(success, ✓ Passed) theme.fg(error, ✗ Failed) theme.fg(warning, ⚠ Warning) theme.fg(muted, Secondary text) theme.fg(dim, Tertiary text) // 背景色 theme.bg(selectedBg, Selected item) theme.bg(toolSuccessBg, Success background) // 文本样式与组合 theme.bold(Bold text) theme.fg(accent, theme.bold(Bold and colored))前景色按语义分为若干类别供主题 JSON 分别定义类别颜色键通用text、accent、muted、dim状态success、error、warning边框border、borderAccent、borderMuted消息userMessageText、customMessageText、customMessageLabel工具toolTitle、toolOutputDifftoolDiffAdded、toolDiffRemoved、toolDiffContextMarkdownmdHeading、mdLink、mdCode、mdQuote、mdHr、mdListBullet等语法高亮syntaxComment、syntaxKeyword、syntaxString、syntaxNumber、syntaxType、syntaxOperator等思考过程thinkingOff、thinkingMinimal、thinkingLow、thinkingMedium、thinkingHigh、thinkingXhigh模式bashMode背景色包括selectedBg、userMessageBg、customMessageBg、toolPendingBg、toolSuccessBg、toolErrorBg。此外主题还支持通过highlightCode(code, language, theme)做语法高亮渲染可用getLanguageFromPath根据文件路径自动推断语言。可参考 google-search 扩展的 renderCall / renderResult 中主题的实战用法。总结如何选择正确的定制层层级技术形态能力范围何时使用Prompt TemplatesMarkdown /name参数展开纯文本提示词需要可复用的静态提示词片段SkillsSKILL.md 脚本/参考文档按需加载的领域指令需要结构化、渐进披露的能力包且任务驱动触发ExtensionsTypeScript 模块manifest工具、事件、UI、命令、提供者、覆盖内置行为需要真实程序逻辑或运行时访问ThemesJSON 颜色定义TUI 视觉外观只想调整界面配色热重载即时生效四层机制可叠加使用例如以 Themes 美化外观、以 Prompt Templates 沉淀常用提示、以 Skills 注入领域知识、以 Extensions 提供底层工具与 UI 组件。这一分层设计的核心理念是**用最简单的手段解决问题**——把文本问题留在文本层把代码问题交给代码层从而在保证灵活性的同时控制复杂度。各层的更多细节可继续查阅 Pi 扩展完整指南、Pi 官方文档索引 以及 TUI 主题与样式文档。赞分享人工智能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点击查看免费下载相关推荐DLSS Swapper 完整教程免费替换游戏中的 DLSS 版本并支持一键回滚DLSS Swapper 完整教程免费替换游戏中的 DLSS 版本并支持一键回滚 DLSS Swapper 是一款运行在 Windows 10 64 位系统上桌面应用深入解析 Pigsd-2自定义 TUI 架构组件渲染模型、分层布局与扩展机制深入解析 Pigsd 2自定义 TUI 架构组件渲染模型、分层布局与扩展机制 本文是 gsd 2 项目中 Pi 的终端用户界面TUI系统架构指南。它从人工智能AI Agent代码智能体Agent 编排CLIAI 应用gws CLI 技能体系完全指南从 Skills Index 看四层 AI Agent 技能架构与自动生成机制gws CLI 技能体系完全指南从 Skills Index 看四层 AI Agent 技能架构与自动生成机制 导读本文围绕 docs/skills.md上一篇Python百度搜索API终极指南免费无限制的搜索引擎集成方案下一篇Python百度搜索API终极指南免费无限制的搜索引擎集成方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考