mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-04 01:40:45 +08:00
39d070eab6
- #54: Add API endpoint configuration documentation to DASHBOARD_GUIDE.md - #50: Add brainstorm context overflow protection with output size limits Note: #72 and #53 not changed per user feedback - existing behavior is sufficient (users can configure envFile themselves; default Python version is appropriate)
465 lines
13 KiB
Markdown
465 lines
13 KiB
Markdown
# CCW Dashboard 用户指南
|
||
|
||
**版本**: 6.2.0
|
||
**更新日期**: 2025-12-20
|
||
|
||
CCW Dashboard 是 Claude Code Workflow 的可视化控制面板，提供项目管理、会话监控、代码索引、记忆管理等功能的统一界面。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [快速启动](#快速启动)
|
||
2. [界面布局](#界面布局)
|
||
3. [导航结构](#导航结构)
|
||
4. [核心视图详解](#核心视图详解)
|
||
5. [实时功能](#实时功能)
|
||
6. [快捷键](#快捷键)
|
||
7. [个性化设置](#个性化设置)
|
||
8. [API 端点参考](#api-端点参考)
|
||
|
||
---
|
||
|
||
## 快速启动
|
||
|
||
```bash
|
||
# 启动 Dashboard（自动打开浏览器）
|
||
ccw view
|
||
|
||
# 指定项目路径
|
||
ccw view -p /path/to/project
|
||
|
||
# 指定端口
|
||
ccw serve --port 8080
|
||
|
||
# 仅启动服务器（不打开浏览器）
|
||
ccw serve
|
||
```
|
||
|
||
Dashboard 默认运行在 `http://localhost:3456`。
|
||
|
||
---
|
||
|
||
## 界面布局
|
||
|
||
CCW Dashboard 是一个单页应用（SPA），界面由四个核心部分组成：
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 顶部操作栏 (Header) │
|
||
├──────────────┬──────────────────────────────────────────────┤
|
||
│ │ │
|
||
│ 侧边栏 │ 主内容区 │
|
||
│ 导航 │ (Main Content) │
|
||
│ (Sidebar) │ │
|
||
│ │ │
|
||
│ │ │
|
||
├──────────────┴──────────────────────────────────────────────┤
|
||
│ 页脚 (Footer) │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 顶部操作栏
|
||
|
||
| 元素 | 功能 |
|
||
|------|------|
|
||
| 品牌标识 | 显示 "Claude Code Workflow" |
|
||
| 项目路径选择器 | 切换最近项目或浏览新项目 |
|
||
| 刷新按钮 | 重新加载当前视图数据 |
|
||
| 语言切换 (EN/ZH) | 切换界面语言 |
|
||
| 主题切换 (☀/🌙) | 切换浅色/深色主题 |
|
||
|
||
### 侧边栏导航
|
||
|
||
侧边栏可折叠，按功能分组：
|
||
|
||
- **项目 (Project)**: 概览、文件浏览器、CLI 状态、历史记录、图谱
|
||
- **会话 (Sessions)**: 全部、活跃、已归档的工作流会话
|
||
- **轻量任务 (Lite Tasks)**: Lite Plan 和 Lite Fix 会话
|
||
- **配置**: MCP 服务器、Hooks 配置
|
||
- **记忆 (Memory)**: 上下文、核心记忆、提示历史、技能、规则、CLAUDE.md
|
||
|
||
---
|
||
|
||
## 导航结构
|
||
|
||
### 项目组 (Project)
|
||
|
||
| 视图 | 说明 |
|
||
|------|------|
|
||
| **概览** | 项目统计数据、会话总数、任务完成度 |
|
||
| **文件浏览器** | 文件树视图，支持预览文件内容 |
|
||
| **状态** | CLI 工具安装状态和配置 |
|
||
| **历史** | CLI 命令执行历史记录 |
|
||
| **图谱** | 代码关系可视化 |
|
||
|
||
### 会话组 (Sessions)
|
||
|
||
| 过滤器 | 说明 |
|
||
|--------|------|
|
||
| **全部** | 显示所有工作流会话 |
|
||
| **活跃** | 仅显示进行中的会话 |
|
||
| **已归档** | 仅显示已完成/归档的会话 |
|
||
|
||
### 轻量任务 (Lite Tasks)
|
||
|
||
| 类型 | 说明 |
|
||
|------|------|
|
||
| **Lite Plan** | 轻量级规划任务会话 |
|
||
| **Lite Fix** | 快速修复任务会话 |
|
||
|
||
### 配置组
|
||
|
||
| 视图 | 说明 |
|
||
|------|------|
|
||
| **MCP 服务器** | 管理 MCP 服务器配置 |
|
||
| **Hooks** | 配置工具生命周期钩子 |
|
||
|
||
### 记忆组 (Memory)
|
||
|
||
| 视图 | 说明 |
|
||
|------|------|
|
||
| **上下文** | 文件读写热点和活动热图 |
|
||
| **核心记忆** | 战略知识库和会话聚类 |
|
||
| **提示历史** | AI 交互历史记录 |
|
||
| **技能** | 可重用能力包管理 |
|
||
| **规则** | AI 交互指令规则 |
|
||
| **CLAUDE.md** | 项目配置文件管理 |
|
||
|
||
---
|
||
|
||
## 核心视图详解
|
||
|
||
### 1. 项目概览 (Project Overview)
|
||
|
||
显示项目的核心统计信息：
|
||
|
||
- **会话统计**: 总数、活跃数、已归档数
|
||
- **任务进度**: 完成率、进行中任务数
|
||
- **活跃会话轮播**: 快速预览当前活跃的会话
|
||
|
||
### 2. CLI 工具管理 (CLI Manager)
|
||
|
||
集中管理所有命令行工具的配置。
|
||
|
||
#### CLI 工具面板
|
||
- **状态显示**: Gemini、Qwen、Codex 的安装状态
|
||
- **默认工具**: 设置默认使用的 CLI 工具
|
||
- **模型配置**: 配置每个工具的主要和次要模型
|
||
- **安装/卸载**: 通过向导安装或卸载工具
|
||
|
||
#### API Endpoint 配置（无需安装 CLI）
|
||
|
||
如果您没有安装 Gemini/Qwen CLI，但有 API 访问权限（如反向代理服务），可以在 `~/.claude/cli-tools.json` 中配置 `api-endpoint` 类型的工具：
|
||
|
||
```json
|
||
{
|
||
"version": "3.2.0",
|
||
"tools": {
|
||
"gemini-api": {
|
||
"enabled": true,
|
||
"type": "api-endpoint",
|
||
"id": "your-api-id",
|
||
"primaryModel": "gemini-2.5-pro",
|
||
"secondaryModel": "gemini-2.5-flash",
|
||
"tags": ["analysis"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**配置说明**：
|
||
- `type: "api-endpoint"`: 表示使用 API 调用而非 CLI
|
||
- `id`: API 端点标识符，用于路由请求
|
||
- API Endpoint 工具仅支持**分析模式**（只读），不支持文件写入操作
|
||
|
||
**使用示例**：
|
||
```bash
|
||
ccw cli -p "分析代码结构" --tool gemini-api --mode analysis
|
||
```
|
||
|
||
#### CodexLens 管理
|
||
- **索引路径**: 查看和修改索引存储位置
|
||
- **索引操作**:
|
||
- 初始化索引（向量模式/FTS 模式）
|
||
- 清理当前项目索引
|
||
- 清理所有索引
|
||
- **语义依赖**: 安装 Python 依赖
|
||
- **模型管理**: 下载/删除嵌入模型
|
||
- **测试搜索**: 验证索引功能
|
||
|
||
#### 索引统计
|
||
- 总索引大小
|
||
- 项目数量
|
||
- 向量索引数
|
||
- FTS 索引数
|
||
|
||
### 3. 代码图谱浏览器 (Graph Explorer)（隐藏）
|
||
|
||
基于 Cytoscape.js 的交互式代码关系可视化工具。
|
||
|
||
#### 数据源切换
|
||
- **代码关系**: 基于 CodexLens 索引的文件/类/函数关系
|
||
- **核心记忆**: 记忆条目和实体关系图
|
||
|
||
#### 交互功能
|
||
- **拖拽/缩放/平移**: 自由探索图谱
|
||
- **节点着色**: 根据类型和重要性区分
|
||
- **过滤器**:
|
||
- 范围: 所有文件 / 按模块 / 按文件
|
||
- 类型: CLASS / FUNCTION / IMPORTS / CALLS 等
|
||
|
||
#### 节点详情
|
||
- 点击节点显示详细信息
|
||
- 类型、路径、行号
|
||
- **影响分析**: 分析变更可能影响的文件和符号
|
||
|
||
### 4. MCP 服务器管理 (MCP Manager)
|
||
|
||
管理项目级和全局的 MCP 服务器配置。
|
||
|
||
#### 功能
|
||
- **服务器列表**: 查看已配置的服务器
|
||
- **创建服务器**: 新建服务器配置
|
||
- **编辑/删除**: 修改或移除服务器
|
||
- **模板安装**: 从预设模板安装服务器
|
||
- **状态监控**: 查看服务器运行状态
|
||
|
||
### 5. Hook 管理 (Hook Manager)
|
||
|
||
配置工具执行生命周期钩子。
|
||
|
||
#### 支持的钩子类型
|
||
- **PreToolUse**: 工具使用前触发
|
||
- **PostToolUse**: 工具使用后触发
|
||
- **Notification**: 通知类钩子
|
||
|
||
#### 配置方式
|
||
- 项目级钩子 (`.claude/settings.local.json`)
|
||
- 全局钩子 (`~/.claude/settings.json`)
|
||
- 向导创建复杂钩子
|
||
- 模板快速配置
|
||
|
||
### 6. 核心记忆 (Core Memory)
|
||
|
||
战略知识库管理系统。
|
||
|
||
#### 记忆列表
|
||
- 创建/编辑/归档/删除记忆条目
|
||
- 结构化的知识存储
|
||
- 标签和分类管理
|
||
|
||
#### 集群视图
|
||
- **自动聚类**: 语义分析相关会话
|
||
- **集群管理**:
|
||
- 查看集群成员
|
||
- 合并/拆分集群
|
||
- 删除集群
|
||
- **时间线**: 会话活动时间线
|
||
|
||
#### 嵌入管理
|
||
- 生成语义嵌入向量
|
||
- 嵌入状态监控
|
||
- 批量嵌入操作
|
||
|
||
### 7. 技能管理 (Skills Manager)
|
||
|
||
管理可重用的 AI 能力包。
|
||
|
||
#### 技能分类
|
||
- **项目技能**: `./.claude/skills/`
|
||
- **用户技能**: `~/.claude/skills/`
|
||
|
||
#### 技能卡片信息
|
||
- 名称和描述
|
||
- 版本号
|
||
- 包含的工具数量
|
||
- 支持文件数量
|
||
|
||
#### 技能创建
|
||
- **导入模式**: 从现有文件夹导入
|
||
- **CLI 生成**: 通过描述让 AI 生成
|
||
|
||
### 8. 帮助视图 (Help View)
|
||
|
||
国际化帮助文档系统。
|
||
|
||
- 动态加载帮助内容
|
||
- 支持中英文切换
|
||
- 快速查找功能指南
|
||
|
||
---
|
||
|
||
## 实时功能
|
||
|
||
Dashboard 通过 WebSocket 连接提供实时数据同步。
|
||
|
||
### WebSocket 连接
|
||
|
||
- 端点: `/ws`
|
||
- 自动重连机制
|
||
- 心跳保活
|
||
|
||
### 实时事件类型
|
||
|
||
| 事件 | 说明 |
|
||
|------|------|
|
||
| `SESSION_CREATED` | 新会话创建 |
|
||
| `SESSION_UPDATED` | 会话状态更新 |
|
||
| `TASK_UPDATED` | 任务进度更新 |
|
||
| `CLI_EXECUTION_STARTED` | CLI 执行开始 |
|
||
| `CLI_EXECUTION_COMPLETED` | CLI 执行完成 |
|
||
| `CODEXLENS_INDEX_PROGRESS` | 索引进度更新 |
|
||
| `MEMORY_UPDATED` | 记忆数据更新 |
|
||
| `CLAUDE_FILE_SYNCED` | CLAUDE.md 同步 |
|
||
| `REFRESH_REQUIRED` | 需要刷新数据 |
|
||
|
||
### 静默刷新
|
||
|
||
对于非关键事件，Dashboard 会在后台静默更新数据，无需用户干预。
|
||
|
||
---
|
||
|
||
## 快捷键
|
||
|
||
| 快捷键 | 功能 |
|
||
|--------|------|
|
||
| `Escape` | 关闭当前打开的模态框或侧边栏 |
|
||
|
||
---
|
||
|
||
## 个性化设置
|
||
|
||
### 主题
|
||
|
||
Dashboard 支持两种主题：
|
||
|
||
- **浅色模式 (Light)**: 默认主题，适合明亮环境
|
||
- **深色模式 (Dark)**: 护眼主题，适合暗光环境
|
||
|
||
点击顶部操作栏的太阳/月亮图标切换。
|
||
|
||
### 语言
|
||
|
||
Dashboard 支持两种语言：
|
||
|
||
- **English (EN)**: 英文界面
|
||
- **中文 (ZH)**: 简体中文界面
|
||
|
||
点击顶部操作栏的 EN/ZH 按钮切换。语言设置会保存到本地存储。
|
||
|
||
---
|
||
|
||
## API 端点参考
|
||
|
||
### 仪表盘数据
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/api/dashboard-data` | GET | 获取仪表盘主数据 |
|
||
| `/api/workspace/switch` | POST | 切换工作区 |
|
||
|
||
### 会话管理
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/api/sessions` | GET | 获取会话列表 |
|
||
| `/api/sessions/{id}` | GET | 获取会话详情 |
|
||
| `/api/sessions/{id}/tasks` | GET | 获取会话任务 |
|
||
|
||
### 核心记忆
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/api/core-memory/list` | GET | 获取记忆列表 |
|
||
| `/api/core-memory/embed-status` | GET | 嵌入状态 |
|
||
| `/api/core-memory/embed` | POST | 生成嵌入 |
|
||
| `/api/core-memory/clusters` | GET | 获取集群列表 |
|
||
| `/api/core-memory/clusters` | POST | 创建集群 |
|
||
| `/api/core-memory/clusters/{id}` | GET | 获取集群详情 |
|
||
| `/api/core-memory/clusters/{id}` | PATCH | 更新集群 |
|
||
| `/api/core-memory/clusters/{id}` | DELETE | 删除集群 |
|
||
| `/api/core-memory/clusters/auto` | POST | 自动聚类 |
|
||
| `/api/core-memory/graph` | GET | 获取记忆图谱 |
|
||
|
||
### CodexLens
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/api/codexlens/config` | GET | 获取配置 |
|
||
| `/api/codexlens/config` | POST | 更新配置 |
|
||
| `/api/codexlens/indexes` | GET | 获取索引列表 |
|
||
| `/api/codexlens/init` | POST | 初始化索引 |
|
||
| `/api/codexlens/clean` | POST | 清理索引 |
|
||
| `/api/codexlens/semantic/status` | GET | 语义依赖状态 |
|
||
| `/api/codexlens/models` | GET | 获取模型列表 |
|
||
|
||
### 代码图谱
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/api/graph/nodes` | GET | 获取图谱节点 |
|
||
| `/api/graph/edges` | GET | 获取图谱边 |
|
||
| `/api/graph/impact` | POST | 影响分析 |
|
||
|
||
### 技能管理
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/api/skills` | GET | 获取技能列表 |
|
||
| `/api/skills/{name}` | GET | 获取技能详情 |
|
||
| `/api/skills/create` | POST | 创建技能 |
|
||
| `/api/skills/{name}` | DELETE | 删除技能 |
|
||
|
||
### MCP 服务器
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/api/mcp/servers` | GET | 获取服务器列表 |
|
||
| `/api/mcp/servers` | POST | 创建服务器 |
|
||
| `/api/mcp/servers/{id}` | PATCH | 更新服务器 |
|
||
| `/api/mcp/servers/{id}` | DELETE | 删除服务器 |
|
||
|
||
### CLI 工具
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/api/cli/status` | GET | 工具状态 |
|
||
| `/api/cli/history` | GET | 执行历史 |
|
||
| `/api/cli/config` | GET/POST | 工具配置 |
|
||
|
||
---
|
||
|
||
## 故障排除
|
||
|
||
### Dashboard 无法启动
|
||
|
||
1. 检查端口是否被占用: `netstat -ano | findstr :3456`
|
||
2. 尝试使用其他端口: `ccw serve --port 8080`
|
||
3. 检查 Node.js 版本: `node --version` (需要 >= 16.0.0)
|
||
|
||
### WebSocket 连接失败
|
||
|
||
1. 检查防火墙设置
|
||
2. 确保后端服务正在运行
|
||
3. 刷新页面重新建立连接
|
||
|
||
### 数据不更新
|
||
|
||
1. 点击刷新按钮手动刷新
|
||
2. 检查 WebSocket 连接状态
|
||
3. 查看浏览器控制台是否有错误
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
- [README.md](README.md) - 项目总览
|
||
- [GETTING_STARTED.md](GETTING_STARTED.md) - 快速入门
|
||
- [COMMAND_REFERENCE.md](COMMAND_REFERENCE.md) - 命令参考
|
||
- [CHANGELOG.md](CHANGELOG.md) - 更新日志
|
||
|
||
---
|
||
|
||
**CCW Dashboard** - Claude Code Workflow 的可视化控制中心
|