3bb2f8f1c5
* chore: wire docs/agents config into AGENTS.md Agent skills section
Add the `## Agent skills` discovery block pointing the engineering
skills at the existing docs/agents/{issue-tracker,triage-labels,domain}.md
files (issue tracker, triage label mapping, single-context domain docs).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: rebrand to GSD Core and restructure docs with Diataxis
Reorganise the root README and docs/ around the Diataxis framework
(tutorials, how-to guides, reference, explanation), add new how-to
guides and schema references (STATE.md / CONTEXT.md / PLAN.md /
planning artifacts), and cross-link the whole set. Update the lone
legacy gsd-build reference to open-gsd; keep internal get-shit-done/
filesystem paths unchanged (directory rename tracked separately in
open-gsd/gsd-core#604). Regenerate the ja-JP, ko-KR, pt-BR and zh-CN
localised trees to mirror the new structure.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: backfill changeset PR number (#605)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
292 lines
8.2 KiB
Markdown
292 lines
8.2 KiB
Markdown
# 如何在您的运行时上安装 GSD Core
|
||
|
||
将 GSD Core（`@opengsd/gsd-core`）安装到您日常使用的 AI 编码运行时中。本指南提供各支持运行时的标准安装路径，以及适用于未安装 Node.js 的机器的手动安装路径。
|
||
|
||
**所需条件：** Node.js 18+ 及 npm（或 npx）。如果您没有 Node.js，请跳转至[不使用 Node.js 安装](#不使用-nodejs-安装)。
|
||
|
||
---
|
||
|
||
## 为什么需要安装程序
|
||
|
||
GSD Core 以 Claude Code 原生 frontmatter 格式分发代理和命令文件。每个支持的运行时需要不同的 schema、目录结构和命令调用语法。安装程序负责执行必要的转换——例如，为 OpenCode 转换工具列表和颜色值、为 Codex 写入 TOML 代理条目，以及将所有命令体从连字符格式（`/gsd-update`）重写为冒号格式（`/gsd:update`）以适配 Gemini CLI。
|
||
|
||
**请勿直接从 `agents/` 或 `commands/` 复制文件。** 这样做会绕过转换过程，导致 schema 验证错误或命令缺失。
|
||
|
||
---
|
||
|
||
## 标准安装
|
||
|
||
在任意目录运行安装程序。它会提示您选择运行时，以及是全局安装（所有项目）还是本地安装（仅此项目）。
|
||
|
||
```bash
|
||
npx @opengsd/gsd-core@latest
|
||
```
|
||
|
||
这是全新安装或切换运行时后重新运行安装程序所需的唯一命令。
|
||
|
||
---
|
||
|
||
## 各运行时安装说明
|
||
|
||
### Claude Code
|
||
|
||
```bash
|
||
npx @opengsd/gsd-core@latest --claude --global
|
||
```
|
||
|
||
技能文件存放于 `~/.claude/`。下次 Claude Code 会话中，命令将以 `/gsd-*` 斜杠命令的形式出现。重启 Claude Code 以加载它们。
|
||
|
||
**覆盖安装目录：**
|
||
|
||
```bash
|
||
CLAUDE_CONFIG_DIR=~/.claude-alt npx @opengsd/gsd-core@latest --claude --global
|
||
```
|
||
|
||
---
|
||
|
||
### Gemini CLI
|
||
|
||
```bash
|
||
npx @opengsd/gsd-core@latest --gemini --global
|
||
```
|
||
|
||
技能文件存放于 `~/.gemini/`。安装程序将所有命令体重写为 Gemini 的冒号命名空间格式（`/gsd:update`、`/gsd:config` 等）。安装后重启 Gemini CLI。
|
||
|
||
**覆盖安装目录：**
|
||
|
||
```bash
|
||
GEMINI_CONFIG_DIR=~/.gemini-alt npx @opengsd/gsd-core@latest --gemini --global
|
||
```
|
||
|
||
---
|
||
|
||
### OpenCode
|
||
|
||
```bash
|
||
npx @opengsd/gsd-core@latest --opencode --global
|
||
```
|
||
|
||
技能文件存放于 `~/.config/opencode/`（XDG）或 `~/.opencode/`。安装程序将代理 frontmatter 转换为 OpenCode 的 schema——移除 `tools:` 字段并将颜色值转换为十六进制格式。如需了解具体变更内容，请参阅[不使用 Node.js 安装 — OpenCode 转换](#opencode--必要转换)。
|
||
|
||
**覆盖安装目录：**
|
||
|
||
```bash
|
||
OPENCODE_CONFIG_DIR=~/.config/opencode-alt npx @opengsd/gsd-core@latest --opencode --global
|
||
```
|
||
|
||
---
|
||
|
||
### Kilo
|
||
|
||
```bash
|
||
npx @opengsd/gsd-core@latest --kilo --global
|
||
```
|
||
|
||
技能文件存放于 `~/.config/kilo/`（XDG）或 `~/.kilo/`。使用与 OpenCode 相同的平铺 Markdown 命令格式。
|
||
|
||
**覆盖安装目录：**
|
||
|
||
```bash
|
||
KILO_CONFIG_DIR=~/.config/kilo-alt npx @opengsd/gsd-core@latest --kilo --global
|
||
```
|
||
|
||
---
|
||
|
||
### Codex
|
||
|
||
```bash
|
||
npx @opengsd/gsd-core@latest --codex --global
|
||
```
|
||
|
||
技能文件存放于 `~/.codex/skills/gsd-*/SKILL.md`。代理以每个代理独立的 TOML 条目写入 `config.toml`。安装后重启 Codex（或运行 `codex --reload`）。
|
||
|
||
**最低支持版本：** Codex CLI 0.130.0。更早版本额外扫描技能根目录，可能导致重复列出条目。
|
||
|
||
---
|
||
|
||
### GitHub Copilot
|
||
|
||
```bash
|
||
npx @opengsd/gsd-core@latest --copilot --global
|
||
```
|
||
|
||
技能文件存放于 `~/.copilot/`。GSD 以代理 `.md` 文件和仓库指令文件的形式安装。
|
||
|
||
**覆盖安装目录：**
|
||
|
||
```bash
|
||
COPILOT_CONFIG_DIR=~/.copilot-alt npx @opengsd/gsd-core@latest --copilot --global
|
||
```
|
||
|
||
---
|
||
|
||
### Cursor
|
||
|
||
```bash
|
||
npx @opengsd/gsd-core@latest --cursor --global
|
||
```
|
||
|
||
技能文件存放于 `~/.cursor/`。GSD 安装技能、代理和规则引用。
|
||
|
||
**覆盖安装目录：**
|
||
|
||
```bash
|
||
CURSOR_CONFIG_DIR=~/.cursor-alt npx @opengsd/gsd-core@latest --cursor --global
|
||
```
|
||
|
||
---
|
||
|
||
### Windsurf
|
||
|
||
```bash
|
||
npx @opengsd/gsd-core@latest --windsurf --global
|
||
```
|
||
|
||
技能文件存放于 `~/.codeium/windsurf/`。GSD 安装技能、代理和工作区规则。
|
||
|
||
**覆盖安装目录：**
|
||
|
||
```bash
|
||
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-alt npx @opengsd/gsd-core@latest --windsurf --global
|
||
```
|
||
|
||
---
|
||
|
||
### Cline
|
||
|
||
Cline 使用基于规则的集成方式——GSD 以 `.clinerules` 形式安装，而非斜杠命令。
|
||
|
||
```bash
|
||
# 全局安装（所有项目）
|
||
npx @opengsd/gsd-core@latest --cline --global
|
||
|
||
# 本地安装（仅此项目）
|
||
npx @opengsd/gsd-core@latest --cline --local
|
||
```
|
||
|
||
全局安装写入 `~/.cline/`。本地安装写入 `./.cline/`。规则由 Cline 自动加载——不注册自定义斜杠命令。
|
||
|
||
---
|
||
|
||
### CodeBuddy
|
||
|
||
```bash
|
||
npx @opengsd/gsd-core@latest --codebuddy --global
|
||
```
|
||
|
||
技能文件存放于 `~/.codebuddy/skills/gsd-*/SKILL.md`。
|
||
|
||
---
|
||
|
||
### Qwen Code
|
||
|
||
Qwen Code 使用与 Claude Code 2.1.88+ 相同的开放技能标准。
|
||
|
||
```bash
|
||
npx @opengsd/gsd-core@latest --qwen --global
|
||
```
|
||
|
||
技能文件存放于 `~/.qwen/skills/gsd-*/SKILL.md`。
|
||
|
||
**覆盖安装目录：**
|
||
|
||
```bash
|
||
QWEN_CONFIG_DIR=~/.qwen-alt npx @opengsd/gsd-core@latest --qwen --global
|
||
```
|
||
|
||
---
|
||
|
||
### Augment Code
|
||
|
||
```bash
|
||
npx @opengsd/gsd-core@latest --augment --global
|
||
```
|
||
|
||
技能文件存放于 `~/.augment/`。GSD 安装技能和代理，不拥有 hook 或状态栏所有权。
|
||
|
||
---
|
||
|
||
### Antigravity
|
||
|
||
```bash
|
||
npx @opengsd/gsd-core@latest --antigravity --global
|
||
```
|
||
|
||
安装程序自动检测 Antigravity 配置目录（`~/.gemini/antigravity`、`~/.gemini/antigravity-ide` 或 `~/.gemini/antigravity-cli`）。使用与 Gemini 兼容的设置策略。
|
||
|
||
**覆盖安装目录：**
|
||
|
||
```bash
|
||
ANTIGRAVITY_CONFIG_DIR=~/.gemini/antigravity-alt npx @opengsd/gsd-core@latest --antigravity --global
|
||
```
|
||
|
||
---
|
||
|
||
### Trae
|
||
|
||
```bash
|
||
npx @opengsd/gsd-core@latest --trae --global
|
||
```
|
||
|
||
技能文件存放于 `~/.trae/`。GSD 安装技能、代理和规则引用。
|
||
|
||
---
|
||
|
||
## 本地安装与全局安装
|
||
|
||
上述所有示例均使用 `--global`，即为您的用户账户全局安装 GSD。若要将安装范围限定到单个项目，请将 `--global` 替换为 `--local`：
|
||
|
||
```bash
|
||
npx @opengsd/gsd-core@latest --claude --local
|
||
```
|
||
|
||
本地安装写入项目根目录下的 `.claude/` 目录。当全局安装和本地安装同时存在时，本地安装的设置优先于全局设置。
|
||
|
||
---
|
||
|
||
## 安装预发布版（Next / Nightly / Insiders / Preview）
|
||
|
||
运行时的预发布版（Windsurf Next、Cursor Nightly、VS Code Insiders、Codex 预览通道等）从同级配置目录读取配置。在运行安装程序前设置对应的 `*_CONFIG_DIR` 环境变量：
|
||
|
||
```bash
|
||
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-next npx @opengsd/gsd-core@latest --windsurf --global
|
||
```
|
||
|
||
在安装程序提示中选择对应的稳定版运行时。GSD 不将预发布版作为独立命名运行时枚举——它们通过此环境变量机制提供尽力支持，不在发布 CI 中单独测试。
|
||
|
||
---
|
||
|
||
## 不使用 Node.js 安装
|
||
|
||
如果您无法运行 `npx`（例如在没有 Node.js 的 Windows 机器上），有两种方案可选。
|
||
|
||
**方案 A——使用有 Node.js 的机器。** 任何有 Node.js 的机器均可：WSL、Linux 虚拟机、CI runner 或 Docker 容器。在那台机器上运行安装程序，然后将输出目录复制到目标机器。以 OpenCode 为例：
|
||
|
||
```bash
|
||
npx @opengsd/gsd-core@latest --opencode --global
|
||
# 然后将 ~/.config/opencode/agents/ 复制到 Windows 机器
|
||
```
|
||
|
||
**方案 B——手动转换源文件。** 代理源文件位于 GSD Core 仓库的 `agents/` 目录下，格式为 Claude Code 原生 frontmatter 格式。每个运行时期望不同的结构。有关各运行时的具体字段转换说明，请参阅用户指南中的[手动安装 / 无 Node.js 设置](../USER-GUIDE.md#manual-install--no-nodejs-setup)，其中详细介绍了 OpenCode 的转换内容，并指向安装程序中其他运行时对应的 `convert*Frontmatter` 函数。
|
||
|
||
---
|
||
|
||
## 安装后
|
||
|
||
重启您的运行时以加载新命令和代理。然后启动您的第一个项目：
|
||
|
||
```bash
|
||
/gsd-new-project
|
||
```
|
||
|
||
如果重启后找不到该命令，请确认安装目录与运行时预期的配置路径匹配。上方的预发布版章节介绍了最常见的路径不匹配情况。
|
||
|
||
---
|
||
|
||
## 相关链接
|
||
|
||
- [您的第一个项目](../tutorials/your-first-project.md)
|
||
- [更新 GSD Core](update-gsd.md)
|
||
- [配置](../CONFIGURATION.md)
|
||
- [文档索引](../README.md)
|