多运行时支持与安装体系 - 和平哥的学习笔记

这是「GSD 全景代码解析」专题的第 4 篇。在本系列中，我们将逐层拆解 Get Shit Done (GSD) 这一 56K+ stars 的 Meta-Prompting 框架，从命令系统到工作流编排，从 Agent 设计到上下文工程，带你一览上下文驱动开发的工程全貌。

一、为什么需要多运行时支持

GSD 的定位是**"AI 编程工具的上下文工程层"**。但 AI 编程工具的生态正处于爆发期——Claude Code、Cursor、Copilot、Windsurf、Codex、Gemini CLI……每个工具都有自己的命令格式、上下文管理方式和工具调用协议。

如果 GSD 只支持单一运行时，它的价值将大打折扣。作者 TÂCHES 的设计决策很明确：GSD 应该是一套与运行时无关的元提示框架，通过适配层将统一的 Prompt 体系映射到不同的 AI IDE。

这就引出了 GSD 架构中最具工程挑战的部分——运行时抽象层和安装体系。

二、支持的运行时全景

截至当前版本，GSD 支持 15 个 AI 编程运行时：

运行时	命令前缀	安装路径（全局）	特殊适配
Claude Code	`/gsd-*`	`~/.claude/`	原生支持，Custom Slash Commands
OpenCode	`/gsd-*`	`~/.config/opencode/`	与 Claude Code 类似
Gemini CLI	`/gsd-*`	`~/.gemini/`	原生支持
Kilo	`/gsd-*`	`~/.config/kilo/`	轻量级运行时
Codex	`$gsd-*`	`~/.codex/`	Skills 格式，TOML 配置
Copilot	`/gsd-*`	`~/.github/`	工具名映射（Read→read, Bash→execute）
Cursor	`/gsd-*`	`~/.cursor/`	基于 `.cursor/rules` 的适配
Windsurf	`/gsd-*`	`~/.codeium/windsurf/`	Codeium 旗下编辑器
Antigravity	`/gsd-*`	`~/.gemini/antigravity/`	基于 Gemini 的变体
Augment	`/gsd-*`	项目级配置	企业级 AI 编程工具
Trae	`/gsd-*`	项目级配置	字节跳动出品
Qwen Code	`/gsd-*`	`~/.qwen/`	阿里通义千问
Cline	集成到 `.clinerules`	项目根目录	规则文件集成方式
CodeBuddy	`/gsd-*`	项目级配置	新兴运行时

这种广泛的运行时支持是 GSD 获得 56K+ stars 的关键因素之一——无论你使用哪款 AI 编程工具，都能找到对应的集成方案。

三、安装器架构：bin/install.js

安装器 bin/install.js 是整个 GSD 仓库中最大的单个文件（~275KB，约 3,000 行），它承担了运行时检测 → 路径解析 → 内容转换 → 文件写入的完整安装流程。

3.1 安装流程总览

flowchart TD
    A[用户执行安装命令] --> B{交互式 or 非交互式?}
    B -->|交互式| C[提示选择运行时]
    B -->|非交互式| D[解析 CLI flags]
    C --> E[选择全局/本地安装]
    D --> E
    E --> F[解析安装路径]
    F --> G[运行时内容转换]
    G --> H[写入文件系统]
    H --> I[安装 Hooks]
    I --> J[安装 SDK]
    J --> K[验证安装结果]

3.2 核心功能模块

安装器的职责可以分解为 5 个核心模块：

1. 运行时检测（Runtime Detection）

// 从 install.js 中提取的运行时检测逻辑
const args = process.argv.slice(2);
const hasClaude = args.includes('--claude');
const hasCodex = args.includes('--codex');
const hasCopilot = args.includes('--copilot');
const hasCursor = args.includes('--cursor');
// ... 共 15 个运行时的 flag

let selectedRuntimes = [];
if (args.includes('--all')) {
  selectedRuntimes = ['claude', 'kilo', 'opencode', 'gemini', 'codex', 
    'copilot', 'antigravity', 'cursor', 'windsurf', 'augment', 
    'trae', 'qwen', 'codebuddy', 'cline'];
}

交互式安装会通过 readline 模块提示用户多选运行时，非交互式安装则通过 CLI flags 直接指定。

2. 路径解析（Path Resolution）

每个运行时有不同的配置目录约定：

~/.claude/                    # Claude Code
~/.config/opencode/           # OpenCode
~/.gemini/                    # Gemini CLI
~/.config/kilo/               # Kilo
~/.codex/                     # Codex (Skills)
~/.github/                    # Copilot
~/.cursor/                    # Cursor
~/.codeium/windsurf/          # Windsurf
~/.gemini/antigravity/        # Antigravity
~/.qwen/                      # Qwen Code

安装器还需要处理全局安装（~/.xxx/）和本地安装（./.xxx/）两种模式，以及 WSL + Windows Node.js 的特殊路径兼容。

3. 运行时内容转换（Runtime Adaptation）

这是安装器最复杂的部分。同一套 GSD Prompt 文件需要根据不同运行时的协议进行转换：

运行时	转换策略	关键差异
Claude Code	原样使用	直接复制 `.md` 命令文件
Codex	TOML + Skills	生成 `config.toml` + 技能文件
Copilot	工具名映射	`Read→read`, `Bash→execute`, `Task→agent`
Cline	规则文件	集成到 `.clinerules`
其他	路径适配	保持内容不变，调整安装路径

Copilot 的工具名映射是典型例子：

// Copilot 工具名映射 —— Claude Code 工具 → GitHub Copilot 工具
const claudeToCopilotTools = {
  Read: 'read',
  Write: 'edit',
  Edit: 'edit',
  Bash: 'execute',
  Grep: 'search',
  Glob: 'search',
  Task: 'agent',
  WebSearch: 'web',
  WebFetch: 'web',
  TodoWrite: 'todo',
  AskUserQuestion: 'ask_user',
  SlashCommand: 'skill',
};

Codex 的适配更为复杂，需要为每个 Agent 生成 TOML 格式的技能配置和沙箱权限：

const CODEX_AGENT_SANDBOX = {
  'gsd-executor': 'workspace-write',
  'gsd-planner': 'workspace-write',
  'gsd-verifier': 'workspace-write',
  'gsd-debugger': 'workspace-write',
  'gsd-plan-checker': 'read-only',
  'gsd-integration-checker': 'read-only',
  // ... 更多 Agent
};

4. 安装模式：全局 vs 本地 vs Skills

GSD 支持三种安装模式：

模式	命令	安装位置	适用场景
全局安装	`--global` / `-g`	`~/.xxx/`	个人开发机，所有项目可用
本地安装	`--local` / `-l`	`./.xxx/`	团队协作，项目专属配置
Skills 安装	`--skills-root`	`~/.xxx/skills/`	Claude Code 2.1.88+、Codex、Qwen Code

Skills 模式是较新的安装方式，Claude Code 从 2.1.88 版本开始支持将 GSD 命令作为 Skills（技能）安装，而非传统的 Custom Commands。Skills 的优势在于更好的上下文隔离和版本管理。

3.3 安装后的目录结构

以 Claude Code 全局安装为例：

~/.claude/
├── commands/gsd/              # 80+ 命令文件
│   ├── new-project.md
│   ├── plan-phase.md
│   ├── execute-phase.md
│   └── ...
├── get-shit-done/             # 工作流 + 参考文档
│   ├── workflows/
│   ├── references/
│   ├── contexts/
│   └── bin/lib/
├── agents/                    # 33 个 Agent 定义
├── hooks/                     # 运行时钩子
│   ├── gsd-context-monitor.js
│   ├── gsd-prompt-guard.js
│   └── ...
├── sdk/                       # TypeScript SDK
│   └── src/
└── VERSION                    # 安装的版本号

四、运行时抽象层设计

安装器之上，GSD 的核心运行时抽象层定义在 bin/lib/core.cjs 中。它解决了更深层的问题：如何让同一套 Workflows 和 Agents 在不同运行时下表现一致？

4.1 运行时配置文件（Runtime Profile）

每个运行时在 bin/lib/core.cjs 中都有一个 Profile，定义了：

上下文窗口大小：Claude Code 200K，Gemini 1M+
支持的 Tools：Claude Code 有 Read/Write/Edit/Bash/Grep/Glob/Task 等 12+ 个工具
命令触发方式：Slash command (/) vs Skill invocation ($)
Hooks 支持：PreToolUse / PostToolUse 等钩子点
文件系统隔离：Workspace-write vs Read-only

4.2 模型配置文件（Model Profile）

GSD 还维护了一套模型配置文件（bin/lib/model-profiles.cjs），因为即使同一运行时，不同模型（Claude 3.5 Sonnet vs Claude 3.7 Sonnet vs GPT-4o）的能力也有差异：

思考类模型（o3, o4-mini, Gemini 2.5 Pro）需要特殊的 thinking-models 参考文档
长上下文模型可以加载更大的 workflows
工具调用能力决定了 Agent 可以执行的操作范围

五、安装方式实战

5.1 交互式安装（推荐）

# 通过 npx 运行安装器（推荐方式）
npx get-shit-done-cc

# 或从源码安装
node bin/install.js

安装器会依次提示：

选择运行时（可多选）
选择全局/本地安装
确认安装路径
是否安装 SDK
是否安装 Hooks

5.2 非交互式安装（CI/Docker/脚本）

# Claude Code 全局安装
npx get-shit-done-cc --claude --global

# Codex 本地安装
npx get-shit-done-cc --codex --local

# 同时安装到多个运行时
npx get-shit-done-cc --claude --opencode --global

# 安装到所有支持的运行时
npx get-shit-done-cc --all --global

# 仅安装命令，不安装 SDK
npx get-shit-done-cc --claude --global --no-sdk

5.3 验证安装

安装完成后，可以通过以下方式验证：

# Claude Code / Gemini / Copilot / Qwen Code
/gsd-help

# Codex
$gsd-help

# Cline
# 检查 .clinerules 文件是否存在
ls .clinerules

六、多运行时维护的挑战

支持 15 个运行时的代价是维护复杂度指数级增长。GSD 通过以下策略应对：

6.1 单一源码，多目标编译

Commands、Workflows、Agents 的内容以运行时无关的 Markdown 形式维护在源码仓库中。安装器在安装时进行运行时适配转换，而非维护多套内容。

6.2 抽象核心，适配边缘

flowchart LR
    subgraph "运行时无关层"
        A[commands/gsd/*.md]
        B[workflows/*.md]
        C[agents/*.md]
    end
    subgraph "运行时适配层"
        D[bin/install.js]
        E[bin/lib/core.cjs]
        F[bin/lib/model-profiles.cjs]
    end
    subgraph "目标运行时"
        G[Claude Code]
        H[Codex]
        I[Copilot]
        J[Cursor]
    end
    A --> D --> G
    B --> D --> H
    C --> D --> I
    A --> E --> J

6.3 版本管理与自动更新

gsd-check-update.js 钩子会在每次会话开始时检查 GSD 版本，提示用户更新。版本信息保存在每个运行时的 VERSION 文件中。

七、运行时选择指南

面对 15 个运行时，新用户应该如何选择？

场景	推荐运行时	理由
个人开发，追求极致体验	Claude Code	最完整的工具集，GSD 原生优化
团队共享配置	Codex + Copilot	企业级支持，版本控制友好
IDE 内集成	Cursor / Windsurf	与编辑器深度集成
轻量级使用	Gemini CLI / Kilo	启动快，资源占用低
开源项目	Cline	免费，社区活跃
多运行时并行	`--all`	一套配置，多处使用

八、总结

GSD 的多运行时支持不是简单的"复制粘贴到不同目录"，而是一个经过精心设计的运行时抽象体系：

安装器（bin/install.js）处理运行时检测、路径解析和内容转换
运行时 Profile（core.cjs）定义各运行时的能力差异
模型 Profile（model-profiles.cjs）处理不同模型的特性
统一源码确保内容一致性，适配层处理运行时差异

这种设计让 GSD 能够同时服务于使用 Claude Code 的独立开发者和使用 Copilot 的企业团队，而不需要维护多套内容。

下一篇预告： 第 05 篇《快速上手：第一条 GSD 命令》

我们将从零开始安装 GSD 并执行第一条 /gsd-new-project 命令的完整实战指南。敬请期待。