mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-04 01:40:45 +08:00
e464d93e29
- Added the crucial `ccw install` step after npm installation in both English (INSTALL.md) and Chinese (INSTALL_CN.md) documentation - Included detailed explanation of what ccw install does: * Installs workflows, scripts, templates to ~/.claude/ * Installs skill definitions to ~/.codex/ * Configures shell integration (optional) This step is essential for the complete installation of CCW system files. Co-Authored-By: Claude (Kimi-K2-Instruct-0905) <noreply@anthropic.com>
181 lines
5.3 KiB
Markdown
181 lines
5.3 KiB
Markdown
# Claude Code Workflow (CCW) - 安装指南
|
||
|
||
[English](INSTALL.md) | **中文**
|
||
|
||
Claude Code Agent 工作流协调和分布式内存系统的安装指南。
|
||
|
||
> **版本 6.3.18：原生 CodexLens 与 Dashboard 革新** - 内置代码索引引擎（FTS + 语义搜索 + HNSW 向量索引），全新 Dashboard 视图，TypeScript 后端，会话聚类智能记忆管理。
|
||
|
||
## ⚡ 快速安装（推荐）
|
||
|
||
### NPM 全局安装
|
||
|
||
```bash
|
||
npm install -g claude-code-workflow
|
||
```
|
||
|
||
### 完成安装
|
||
|
||
安装 npm 包后，需要运行安装命令来设置工作流、脚本和模板：
|
||
|
||
```bash
|
||
# 安装 CCW 系统文件（工作流、脚本、模板）
|
||
ccw install
|
||
```
|
||
|
||
`ccw install` 命令将会：
|
||
- 安装工作流定义到 `~/.claude/workflows/`
|
||
- 安装实用脚本到 `~/.claude/scripts/`
|
||
- 安装提示模板到 `~/.claude/templates/`
|
||
- 安装技能定义到 `~/.codex/skills/`
|
||
- 配置 shell 集成（可选）
|
||
|
||
### 验证安装
|
||
|
||
```bash
|
||
# 检查 ccw 命令
|
||
ccw --version
|
||
|
||
# 启动 Dashboard
|
||
ccw dashboard
|
||
|
||
# 启动 View 界面（替代 UI）
|
||
ccw view
|
||
```
|
||
|
||
## 📂 从源码安装
|
||
|
||
如果你想从源码安装或参与开发：
|
||
|
||
```bash
|
||
# 克隆仓库
|
||
git clone https://github.com/catlog22/Claude-Code-Workflow.git
|
||
cd Claude-Code-Workflow
|
||
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 全局链接（开发模式）
|
||
npm link
|
||
```
|
||
|
||
## 平台要求
|
||
|
||
- **Node.js**: 16.0.0 或更高版本
|
||
- **操作系统**: Windows、Linux、macOS
|
||
|
||
检查 Node.js 版本：
|
||
```bash
|
||
node --version # 应该 >= 16.0.0
|
||
```
|
||
|
||
## ⚙️ 配置
|
||
|
||
### 工具控制系统
|
||
|
||
CCW 使用**基于配置的工具控制系统**，使外部 CLI 工具成为**可选**而非必需。这允许你：
|
||
|
||
- ✅ **从仅 Claude 模式开始** - 无需安装额外工具即可立即使用
|
||
- ✅ **渐进式增强** - 按需选择性添加外部工具
|
||
- ✅ **优雅降级** - 工具不可用时自动回退
|
||
- ✅ **灵活配置** - 每个项目控制工具可用性
|
||
|
||
**配置文件**：`~/.claude/workflows/tool-control.yaml`
|
||
|
||
```yaml
|
||
tools:
|
||
gemini:
|
||
enabled: false # 可选：AI 分析和文档
|
||
qwen:
|
||
enabled: true # 可选：AI 架构和代码生成
|
||
codex:
|
||
enabled: true # 可选：AI 开发和实现
|
||
```
|
||
|
||
**行为**：
|
||
- **禁用时**：CCW 自动回退到其他已启用的工具或 Claude 的原生能力
|
||
- **启用时**：使用专门工具发挥其特定优势
|
||
- **默认**：所有工具禁用 - 仅 Claude 模式开箱即用
|
||
|
||
### 可选 CLI 工具（增强功能）
|
||
|
||
虽然 CCW 仅使用 Claude 即可工作，但安装这些工具可提供增强的分析和扩展上下文：
|
||
|
||
#### 系统工具
|
||
|
||
| 工具 | 用途 | 安装方式 |
|
||
|------|------|----------|
|
||
| **ripgrep (rg)** | 快速代码搜索 | **macOS**: `brew install ripgrep`<br>**Linux**: `apt install ripgrep`<br>**Windows**: `winget install ripgrep` |
|
||
| **jq** | JSON 处理 | **macOS**: `brew install jq`<br>**Linux**: `apt install jq`<br>**Windows**: `winget install jq` |
|
||
|
||
#### 外部 AI 工具
|
||
|
||
在 `~/.claude/workflows/tool-control.yaml` 中配置这些工具：
|
||
|
||
| 工具 | 用途 | 安装方式 |
|
||
|------|------|----------|
|
||
| **Gemini CLI** | AI 分析和文档 | 遵循[官方文档](https://ai.google.dev) - 免费配额，扩展上下文 |
|
||
| **Codex CLI** | AI 开发和实现 | 遵循[官方文档](https://github.com/openai/codex) - 自主开发 |
|
||
| **Qwen Code** | AI 架构和代码生成 | 遵循[官方文档](https://github.com/QwenLM/qwen-code) - 大上下文窗口 |
|
||
|
||
### 推荐：MCP 工具（增强分析）
|
||
|
||
MCP（模型上下文协议）工具提供高级代码库分析。**推荐安装** - 虽然 CCW 有回退机制，但不安装 MCP 工具可能导致某些工作流的意外行为或性能下降。
|
||
|
||
| MCP 服务器 | 用途 | 安装指南 |
|
||
|------------|------|----------|
|
||
| **Exa MCP** | 外部 API 模式和最佳实践 | [安装指南](https://smithery.ai/server/exa) |
|
||
| **Chrome DevTools MCP** | ⚠️ **UI 工作流必需** - URL 模式设计提取 | [安装指南](https://github.com/ChromeDevTools/chrome-devtools-mcp) |
|
||
|
||
> **注意**：Code Index MCP 已被 CCW 内置的 **CodexLens** (`mcp__ccw-tools__codex_lens`) 替代。无需额外安装代码索引工具。
|
||
|
||
## ✅ 验证安装
|
||
|
||
安装后，在 **Claude Code** 中检查工作流命令是否可用：
|
||
|
||
```bash
|
||
/workflow:session:list
|
||
```
|
||
|
||
此命令应在 Claude Code 界面中被识别。如果看到工作流斜杠命令（如 `/workflow:*`、`/cli:*`），则安装成功。
|
||
|
||
## 故障排除
|
||
|
||
### 权限错误（npm 全局安装）
|
||
|
||
**Linux/macOS**：
|
||
```bash
|
||
# 选项 1：使用 nvm 管理 Node.js（推荐）
|
||
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
|
||
|
||
# 选项 2：修复 npm 权限
|
||
mkdir ~/.npm-global
|
||
npm config set prefix '~/.npm-global'
|
||
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
|
||
source ~/.bashrc
|
||
```
|
||
|
||
**Windows**：以管理员身份运行命令提示符或 PowerShell
|
||
|
||
### 工作流命令无效
|
||
|
||
- 验证安装：`ls ~/.claude`（应显示 agents/、commands/、workflows/）
|
||
- 安装后重启 Claude Code
|
||
- 检查 `/workflow:session:list` 命令是否被识别
|
||
|
||
### ccw 命令未找到
|
||
|
||
```bash
|
||
# 检查全局安装位置
|
||
npm list -g --depth=0
|
||
|
||
# 确保 npm bin 目录在 PATH 中
|
||
npm bin -g
|
||
```
|
||
|
||
## 支持
|
||
|
||
- **问题**：[GitHub Issues](https://github.com/catlog22/Claude-Code-Workflow/issues)
|
||
- **快速入门**：[快速入门指南](GETTING_STARTED_CN.md)
|
||
- **文档**：[主 README](README_CN.md)
|