# 安装手册

## 环境准备

### 1. 安装 superpowers 插件（前置依赖，仅 Claude Code）

adspecs 的编码阶段依赖 `superpowers` 插件提供的 `subagent-driven-development`、`test-driven-development` 等通用 Skill，必须先安装：

**方式 A：官方市场（推荐）**

```txt
/plugin install superpowers@claude-plugins-official
```

**方式 B：第三方市场**

```txt
# 第一步：注册市场
/plugin marketplace add obra/superpowers-marketplace

# 第二步：从该市场安装插件
/plugin install superpowers@superpowers-marketplace
```

> **注意**：Qoder / WorkBuddy 平台无需安装 superpowers，adspecs 的 Skills 在 Qoder / WorkBuddy 中可独立运行。

---

## 在 WorkBuddy 中安装

adspecs 通过 `.workbuddy-plugin/plugin.json` 提供 WorkBuddy 原生插件支持。

### 方式 A：CLI 自动安装（推荐）

```bash
# 全局安装 adspecs CLI
npm install -g adspecs

# 注册为 WorkBuddy 插件（自动检测平台）
adspecs plugin install --platform workbuddy

# 或指定项目级安装
adspecs plugin install --platform workbuddy --scope project
```

### 方式 B：通过 CodeBuddy CLI 安装

WorkBuddy 共享 CodeBuddy 的插件基础设施，可直接使用 CodeBuddy CLI：

```bash
# 从本地目录安装（开发测试用）
codebuddy plugin install /path/to/adspecs --scope user

# 或从 Git 仓库安装
codebuddy plugin install https://gitee.com/yuebon/adspecs --scope user
```

### 方式 C：手工配置（无 CLI 时）

编辑 `~/.workbuddy/settings.json`，在 `enabledPlugins` 中添加：

```json
{
  "enabledPlugins": {
    "adspecs@local": true
  }
}
```

确保 WorkBuddy 可访问 adspecs 技能目录后重启。

### 卸载

```bash
adspecs plugin uninstall --platform workbuddy --scope project
```

---

## 在 Qoder 中安装

adspecs 通过 `.qoder-plugin/plugin.json` 提供 Qoder 原生插件支持。

### 方式 A：CLI 自动安装（推荐）

```bash
# 全局安装 adspecs CLI
npm install -g adspecs

# 注册为 Qoder 插件（自动检测平台）
adspecs plugin install --platform qoder

# 或指定项目级安装
adspecs plugin install --platform qoder --scope project
```

### 方式 B：手动安装

1. 将 adspecs 插件目录放置到 Qoder 可访问的路径
2. 确保目录中包含 `.qoder-plugin/plugin.json`
3. 在 Qoder 插件设置中添加该目录路径
4. 重启 Qoder 使插件生效

### 方式 C：项目级安装（团队协作）

```bash
# 进入项目根目录
cd /path/to/your/project

# 注册为项目级 Qoder 插件
adspecs plugin install --platform qoder --scope project
```

此命令会在项目中创建 `.qoder-plugin/` 链接，使插件随项目版本控制。

### 卸载

```bash
adspecs plugin uninstall --platform qoder --scope project
```

---

## 在 Claude Code 中安装

adspecs 插件提供**用户级**和**项目级**两种安装方式，按需选择：

| 安装方式   | 作用范围           | 存储位置                             | 适用场景                         |
| ---------- | ------------------ | ------------------------------------ | -------------------------------- |
| **用户级** | 当前用户的所有项目 | `~/.claude/plugins/adspecs/`         | 个人开发者，多个项目共用同一插件 |
| **项目级** | 仅当前项目         | `{project}/.claude/plugins/adspecs/` | 团队协作，插件随项目版本控制     |

#### 方式 A：用户级安装（推荐个人开发者）

插件安装到用户主目录，所有项目均可使用，无需每个项目重复安装。

```txt
# 第一步：注册用户级 marketplace
claude plugins marketplace add <adspecs-marketplace-path> --scope user

# 第二步：安装插件（用户级）
claude plugins install adspecs --scope user
```

**效果**：安装完成后，任意目录下启动 Claude Code 均可使用 adspecs 的全部 Skill。

**卸载**：

```txt
claude plugins uninstall adspecs --scope user
```

#### 方式 B：项目级安装（推荐团队协作）

插件安装到当前项目目录，仅在当前项目中生效，可随项目代码一起纳入版本控制。

```txt
# 第一步：进入项目根目录
cd /path/to/your/project

# 第二步：注册项目级 marketplace
claude plugins marketplace add <adspecs-marketplace-path> --scope project

# 第三步：安装插件（项目级）
claude plugins install adspecs --scope project
```

**效果**：仅在当前项目目录下可使用 adspecs 的 Skill，其他项目不受影响。

**版本控制**（可选）：如需团队共享插件配置，将 `.claude/plugins/` 目录提交到 Git 仓库：

```bash
# .gitignore 中不要忽略 .claude/plugins/ 目录
git add .claude/plugins/
git commit -m "chore: add adspecs plugin configuration"
```

**卸载**：

```txt
claude plugins uninstall adspecs --scope project
```

#### 方式 C：从 Git 仓库安装

若未配置 adspecs marketplace，可直接从 Git 拉取插件源码后按本地 marketplace 安装。

Git 地址：`https://gitee.com/yuebon/adp-plugins`

**用户级安装示例**：

```txt
# 第一步：克隆仓库到本地（示例目录）
git clone https://gitee.com/yuebon/adp-plugins ~/.claude/plugins/adspecs

# 第二步：注册用户级 marketplace（指向仓库内 .claude-plugin）
claude plugins marketplace add ~/.claude/plugins/adspecs --scope user

# 第三步：安装 adspecs 插件（用户级）
claude plugins install adspecs --scope user
```

**项目级安装示例**：

```txt
# 第一步：进入项目根目录
cd /path/to/your/project

# 第二步：将插件仓库拉取到项目内（示例目录）
git clone https://gitee.com/yuebon/adp-plugins ./.claude/plugins/adspecs

# 第三步：注册项目级 marketplace（指向仓库内 .claude-plugin）
claude plugins marketplace add ./.claude/plugins/adspecs --scope project

# 第四步：安装 adspecs 插件（项目级）
claude plugins install adspecs --scope project

# 用户级升级
claude plugins update adspecs --scope user

# 项目级升级
claude plugins update adspecs --scope project
```

#### 选择建议

- **个人开发者，维护多个项目** → 选**用户级**，一次安装全局生效
- **团队协作，需要统一插件版本** → 选**项目级**，插件随代码版本控制
- **同时存在两种需求** → 两种可同时安装，项目级优先于用户级（就近原则）

> **注意**：安装完成后，建议重启 AI 平台（Claude Code / Qoder）以确保所有 Skill 被正确加载。如遇到 Skill 未生效，可执行 `/plugins` 查看当前已加载的插件列表。

---

## 跨平台支持

### 平台自动检测

adspecs 通过 `hooks/platform.js` 模块自动检测运行环境，无需手动配置：

| 检测方式 | 说明 |
|----------|------|
| `ADSPECS_PLATFORM` 环境变量 | 显式指定平台（优先级最高） |
| `CLAUDE_PLUGIN_ROOT` 环境变量 | Claude Code 自动注入 |
| `QODER_PLUGIN_ROOT` 环境变量 | Qoder 自动注入 |
| `CODEBUDDY_PLUGIN_ROOT` 环境变量 | WorkBuddy / CodeBuddy 自动注入 |

### 环境变量

| 环境变量 | 说明 | 可选值 |
|----------|------|--------|
| `ADSPECS_PLATFORM` | 显式指定运行平台 | `claude` / `qoder` / `workbuddy` |
| `CLAUDE_PLUGIN_ROOT` | Claude Code 注入的插件根路径 | 自动 |
| `QODER_PLUGIN_ROOT` | Qoder 注入的插件根路径 | 自动 |
| `CODEBUDDY_PLUGIN_ROOT` | WorkBuddy/CodeBuddy 注入的插件根路径 | 自动 |

通常无需手动设置，平台会自动注入。若 hooks 执行异常，可尝试设置 `ADSPECS_PLATFORM=qoder`。

### Hooks 系统

adspecs 的 hooks 脚本（`hooks/*.js`）已适配双平台，通过统一的 `platform.js` 模块获取：

- 平台类型（`claude` / `qoder` / `workbuddy`）
- 状态目录（`.claude/` / `.qoder/` / `.workbuddy/`）
- 工具输出文件路径

hooks 配置位于 `hooks/hooks.json`，支持以下事件：

| 事件 | 说明 |
|------|------|
| `SessionStart` | 会话启动时注入上下文 |
| `PreCompact` | 上下文压缩前保存提醒 |
| `PostToolUse` | 文件变更后追踪队列 |
| `Stop` | 会话结束时建议操作 |