- 人工智能
- AI Agent
- 代码智能体
- Agent 编排
- CLI
- AI 应用
【免费下载链接】gsd-2
A 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
本篇指南系统讲解 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、tier（core/bundled/community）、requires.platform，以及声明能力的provides（tools、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、promptGuidelines（LLM 使用指引）、基于 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.md； - agent 遵循其中指令，并使用相对路径引用脚本/资源。
源码 skill-discovery.ts 印证了 frontmatter 解析逻辑：SKILL.md以---\n开头，通过name:与description:键提取元数据；探测到的新技能会被格式化为<newly_discovered_skills>XML 块注入系统提示词，使后续任务立即可见（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 loader（prompt-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、toolOutput |
| Diff | toolDiffAdded、toolDiffRemoved、toolDiffContext |
| Markdown | mdHeading、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 Templates | Markdown +/name参数展开 | 纯文本提示词 | 需要可复用的静态提示词片段 |
| Skills | SKILL.md+ 脚本/参考文档 | 按需加载的领域指令 | 需要结构化、渐进披露的能力包，且任务驱动触发 |
| Extensions | TypeScript 模块（manifest） | 工具、事件、UI、命令、提供者、覆盖内置行为 | 需要真实程序逻辑或运行时访问 |
| Themes | JSON 颜色定义 | TUI 视觉外观 | 只想调整界面配色，热重载即时生效 |
四层机制可叠加使用：例如以 Themes 美化外观、以 Prompt Templates 沉淀常用提示、以 Skills 注入领域知识、以 Extensions 提供底层工具与 UI 组件。这一分层设计的核心理念是**"用最简单的手段解决问题"**——把文本问题留在文本层，把代码问题交给代码层，从而在保证灵活性的同时控制复杂度。各层的更多细节可继续查阅 Pi 扩展完整指南、Pi 官方文档索引 以及 TUI 主题与样式文档。
- 人工智能
- AI Agent
- 代码智能体
- Agent 编排
- CLI
- AI 应用
【免费下载链接】gsd-2
A 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
相关推荐
DLSS Swapper 完整教程：免费替换游戏中的 DLSS 版本并支持一键回滚
DLSS Swapper 完整教程：免费替换游戏中的 DLSS 版本并支持一键回滚 DLSS Swapper 是一款运行在 Windows 10 64 位系统上
桌面应用深入解析 Pi（gsd-2）自定义 TUI 架构：组件渲染模型、分层布局与扩展机制
深入解析 Pi（gsd 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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
TeX/CSL 输出)