setup

# /setup - 项目初始化

初始化 Claude Code 项目配置。支持 **Plugin 模式** 和 **Clone 模式**。

## 使用方式

```bash
# 完整初始化（默认）
/cc-best:setup

# 仅配置 hooks（修复插件 hooks 问题）
/cc-best:setup --hooks

# 配置 hooks 到全局
/cc-best:setup --hooks --global

# 配置 hooks 到项目
/cc-best:setup --hooks --project

# 验证 hooks 配置是否正确
/cc-best:setup --verify

# 交互式配置向导
/cc-best:setup --interactive
```

---

## 参数说明

| 参数            | 说明                                     |
| --------------- | ---------------------------------------- |
| `--hooks`       | 仅配置 hooks，跳过其他初始化步骤         |
| `--global`      | 配置到全局 `~/.claude/settings.json`     |
| `--project`     | 配置到项目 `.claude/settings.local.json` |
| `--verify`      | 验证 hooks 配置是否正确（诊断模式）      |
| `--interactive` | 交互式配置向导，按需选择安装组件         |

---

## 执行步骤

### 0. 检查 --verify 参数

如果使用 `--verify` 参数，执行验证模式：

```bash
# 运行 hooks 验证脚本
node <SCRIPT_PATH>/verify-hooks.js
```

验证脚本会检查：

- ✅ 脚本路径是否存在
- ✅ timeout 是否在合理范围 (1ms - 10min)
- ✅ matcher 语法是否正确
- ✅ 生命周期事件是否有效

验证完成后输出诊断报告和修复建议，然后退出。

### 1. 检测运行模式

```
如果存在 scripts/node/hooks/ 目录：
  → Clone 模式
否则：
  → Plugin 模式，定位插件缓存目录
```

### 2. 运行初始化脚本

使用 Node.js 脚本（跨平台兼容）执行初始化：

```bash
# 检测并运行初始化脚本
# Plugin 模式：脚本位于插件目录
# Clone 模式：脚本位于项目目录

# 优先使用 Node.js（跨平台）
if command -v node &> /dev/null; then
    # 查找脚本位置（Plugin 或 Clone 模式）
    if [ -f "scripts/node/init.js" ]; then
        node scripts/node/init.js
    fi
else
    # 回退到 Bash（仅 Unix）
    if [ -f "scripts/shell/init.sh" ]; then
        bash scripts/shell/init.sh
    fi
fi
```

初始化脚本会自动：

- 检测运行模式（Plugin/Clone）
- 创建 `.claude/settings.local.json`
- 创建必要目录结构
- 初始化 Memory Bank 文件
- Plugin 模式下从插件目录复制模板
- Clone 模式下创建 Hookify 规则文件

### 3. 清理旧版本 Hooks 配置

> ⚠️ **v0.6.3 升级**: 如果从旧版本升级，全局 settings.json 可能有冗余的 hooks 配置需要清理。

**检查并清理**：

1. 读取全局配置 `~/.claude/settings.json`
2. 检查是否存在 `hooks` 字段，且包含 `${CLAUDE_PLUGIN_ROOT}/scripts/node/hooks/` 路径
3. 如果存在，这是旧版本遗留配置，应该删除 `hooks` 字段
4. 告知用户：「已清理旧版本 hooks 配置，现在通过插件内置 hooks/hooks.json 自动生效」

```javascript
// 清理逻辑示例
const settingsPath = path.join(os.homedir(), ".claude/settings.json");
const settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));

if (settings.hooks) {
  const hasOldHooks = JSON.stringify(settings.hooks).includes(
    "scripts/node/hooks/",
  );
  if (hasOldHooks) {
    delete settings.hooks;
    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
    console.log("✅ 已清理旧版本 hooks 配置");
  }
}
```

### 4. 配置 Hooks（Plugin 模式）

> ℹ️ **v0.6.3+**: Hooks 现在通过插件内置 `hooks/hooks.json` 自动生效，无需手动配置。
> 如果需要自定义或覆盖，可以使用 `/cc-best:setup --hooks` 手动配置。

**自动生效的 Hooks**：

插件安装后，以下 hooks 自动启用：

| Hook                   | 触发条件        | 功能         |
| ---------------------- | --------------- | ------------ |
| `validate-command.js`  | Bash 命令执行前 | 阻止危险命令 |
| `pause-before-push.js` | git push 前     | 推送确认     |
| `protect-files.js`     | 文件写入前      | 保护敏感文件 |
| `format-file.js`       | 文件写入后      | 自动格式化   |
| `session-check.js`     | 会话启动时      | 项目健康检查 |

**手动配置（可选）**：

如果插件内置 hooks 不生效，可以运行 `/cc-best:setup --hooks` 手动配置。

配置位置选择：

1. 全局配置 (`~/.claude/settings.json`) - 所有项目生效（推荐）
2. 项目配置 (`.claude/settings.local.json`) - 仅当前项目生效

**路径获取方式**（跨平台）：

```javascript
const os = require("os");
const path = require("path");

// 获取插件绝对路径（推荐使用 CLAUDE_PLUGIN_ROOT 环境变量）
const pluginPath = process.env.CLAUDE_PLUGIN_ROOT;
// 如果不在 hook 上下文中，可手动查找：
const homeDir = os.homedir();
const cacheDir = path.join(homeDir, ".claude/plugins/cache/cc-best/cc-best");
// 缓存目录下按版本号存放，如 0.8.2/、0.9.0/ 等
```

**Hooks 配置模板**：

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node <PLUGIN_PATH>/scripts/node/hooks/validate-command.js",
            "timeout": 5
          }
        ]
      }
    ]
  }
}
```

⚠️ **注意**: 路径**不要用引号包裹**（如 `\"...\"`），否则 Windows 下会失败

### 5. 更新 CLAUDE.md

将模板占位符替换为实际项目信息：

- `{{PROJECT_NAME}}` → 项目名称
- `{{PROJECT_DESCRIPTION}}` → 项目描述
- `{{DATE}}` → 当前日期 (YYYY-MM-DD)
- `{{CURRENT_PHASE}}` → 当前阶段（如"开发中"、"MVP"）

**询问用户**获取这些信息，然后使用 Edit 工具更新 CLAUDE.md。

### 6. 选择运行模式

**询问用户**选择 iterate 运行模式：

| 模式   | 管线                            | 适用场景         |
| ------ | ------------------------------- | ---------------- |
| `full` | PM → Lead → Designer → Dev → QA | 完整项目开发     |
| `lite` | Dev → Verify → Commit           | 快速编码、小改动 |

根据选择写入 `memory-bank/config.json`：

```json
{
  "mode": "full"
}
```

> **默认**: 如果用户跳过选择，使用 `full` 模式。

---

## 输出

初始化完成后输出：

```
✅ 项目初始化完成

已创建/检查：
- [x] .claude/settings.local.json
- [x] .claude/screenshots/
- [x] .claude/logs/
- [x] memory-bank/
- [x] docs/

Hooks 配置：
- [x] 已写入 ~/.claude/settings.json（全局）
- 包含：validate-command, pause-before-push, protect-files, format-file, session-check

下一步：
1. 确认 CLAUDE.md 中的项目信息
2. 编辑 memory-bank/tech-stack.md 定义技术栈
3. 运行 /cc-best:pm 开始第一个需求
```

---

## 模式差异

| 模式   | settings.local.json 来源 | Hooks 配置                     | Hookify 规则       |
| ------ | ------------------------ | ------------------------------ | ------------------ |
| Plugin | 插件目录模板             | 需要手动配置（此命令自动处理） | 由 hooks.json 提供 |
| Clone  | 项目目录模板             | 使用相对路径                   | 复制 .example 文件 |

---

## 配置层次

```
优先级（高 → 低）：
1. .claude/settings.local.json（项目本地，不提交）
2. .claude/settings.json（项目级，可提交）
3. ~/.claude/settings.json（全局用户配置）
```

**推荐策略**：

- **安全类 hooks**（validate-command, protect-files）→ 全局配置
- **格式化 hooks**（format-file）→ 项目配置（不同项目可能有不同格式化规则）

---

## --interactive 交互式配置向导

交互模式提供分步引导，按需选择安装组件。

### 第 1 步：选择安装级别

```
请选择安装级别:
  [1] 全局安装 (~/.claude/settings.json) - 所有项目生效
  [2] 项目安装 (.claude/settings.local.json) - 仅当前项目
  [3] 两者都安装 - 安全 hooks 全局 + 格式化 hooks 项目
```

### 第 2 步：选择 Rules 集

根据项目技术栈选择要启用的规则集（多选）：

```
通用规范（默认启用）:
  [✓] common/ - 方法论、编码标准、代码风格、安全、测试、性能

语言专属规范（根据项目选择）:
  [ ] frontend/  - 前端: 样式、测试、安全、性能
  [ ] java/      - Java: 样式、测试、安全、性能
  [ ] csharp/    - C#: 样式、测试、安全、性能
  [ ] cpp/       - C++: 样式、测试、安全、性能
  [ ] embedded/  - 嵌入式: ESP32 样式、测试、安全、性能
  [ ] ui/        - UI 设计: 设计规范、无障碍
```