catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-03-01 15:03:57 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: add VitePress documentation site

Browse Source 
- Add docs directory with VitePress configuration
- Add GitHub Actions workflow for docs build and deploy
- Support bilingual (English/Chinese) documentation
- Include search, custom theme, and responsive design
This commit is contained in:
catlog22
2026-02-28 16:14:09 +08:00
parent ab65caec45
commit c3ddf7e322
136 changed files with 34486 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

394
docs/zh/features/api-settings.md Normal file
View File

@@ -0,0 +1,394 @@
# API 设置
## 一句话定位
**API 设置是统一的多端点配置管理** — 在一个地方配置所有 AI 服务商的 API Keys 和端点，支持多环境切换和密钥加密存储。
## 解决的痛点
| 痛点 | 现状 | API 设置方案 |
| --- | --- | --- |
| **配置分散** | API Keys 散落在各工具配置中 | 统一配置入口 |
| **安全性弱** | 明文存储密钥 | 支持密钥加密 |
| **切换困难** | 切换服务商需要修改多处 | 一个配置文件管理所有 |
| **环境隔离差** | 开发/生产环境混用 | 支持多环境配置 |
## 核心概念速览
| 概念 | 说明 | 位置 |
| --- | --- | --- |
| **API Keys** | 服务商认证密钥 | `settings.json` / `settings.local.json` |
| **Providers** | AI 服务提供商 | OpenAI, Anthropic, Gemini, LiteLLM |
| **Endpoints** | API 服务端点 | URL + 认证配置 |
| **LiteLLM** | 统一代理服务 | 支持 100+ 模型 |
| **本地配置** | 项目级配置 | `.cw/settings.json` |
| **全局配置** | 用户级配置 | `~/.claude/settings.json` |
## 配置层级
```
┌─────────────────────────────────────────────────────────────┐
│ 配置优先级 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. settings.local.json (最高优先级，不提交) │
│ └─ 本地开发配置，覆盖其他配置 │
│ │ │
│ ▼ │
│ 2. .cw/settings.json (项目配置) │
│ └─ 项目特定配置，团队成员共享 │
│ │ │
│ ▼ │
│ 3. ~/.claude/settings.json (全局配置) │
│ └─ 用户默认配置，所有项目共享 │
│ │ │
│ ▼ │
│ 4. 默认值 (最低优先级) │
│ └─ 系统内置默认配置 │
│ │
└─────────────────────────────────────────────────────────────┘
```
## 配置说明
### settings.json 结构
```json
{
"$schema": "https://cdn.jsdelivr.net/gh/your-repo/schema/settings-schema.json",
"providers": {
"openai": {
"apiKey": "sk-...",
"baseURL": "https://api.openai.com/v1",
"models": {
"gpt-4": "gpt-4-turbo",
"gpt-3.5": "gpt-3.5-turbo"
}
},
"anthropic": {
"apiKey": "sk-ant-...",
"baseURL": "https://api.anthropic.com/v1",
"models": {
"claude-opus": "claude-3-opus-20240229",
"claude-sonnet": "claude-3-sonnet-20240229"
}
},
"gemini": {
"apiKey": "AIza...",
"baseURL": "https://generativelanguage.googleapis.com/v1beta",
"models": {
"gemini-pro": "gemini-pro",
"gemini-flash": "gemini-1.5-flash"
}
},
"litellm": {
"apiKey": "sk-...",
"baseURL": "https://litellm.example.com/v1",
"models": {
"qwen-embed": "qwen/qwen3-embedding-sf"
}
}
},
"cw": {
"defaultTool": "gemini",
"promptFormat": "plain",
"smartContext": {
"enabled": false,
"maxFiles": 10
},
"nativeResume": true,
"recursiveQuery": true,
"cache": {
"injectionMode": "auto",
"defaultPrefix": "",
"defaultSuffix": ""
},
"codeIndexMcp": "ace"
},
"hooks": {
"prePrompt": [],
"postResponse": []
}
}
```
### Providers 配置详解
#### OpenAI
```json
{
"providers": {
"openai": {
"apiKey": "sk-proj-...",
"baseURL": "https://api.openai.com/v1",
"organization": "org-...",
"timeout": 60000,
"maxRetries": 3
}
}
}
```
#### Anthropic (Claude)
```json
{
"providers": {
"anthropic": {
"apiKey": "sk-ant-...",
"baseURL": "https://api.anthropic.com/v1",
"version": "2023-06-01",
"timeout": 60000,
"maxRetries": 3
}
}
}
```
#### Gemini (Google)
```json
{
"providers": {
"gemini": {
"apiKey": "AIza...",
"baseURL": "https://generativelanguage.googleapis.com/v1beta",
"timeout": 60000
}
}
}
```
#### LiteLLM (统一代理)
```json
{
"providers": {
"litellm": {
"apiKey": "sk-...",
"baseURL": "https://litellm.example.com/v1",
"dropParams": ["max_tokens"],
"timeout": 120000
}
}
}
```
### CCW 配置详解
```json
{
"cw": {
"defaultTool": "gemini",
"promptFormat": "plain",
"smartContext": {
"enabled": false,
"maxFiles": 10
},
"nativeResume": true,
"recursiveQuery": true,
"cache": {
"injectionMode": "auto",
"defaultPrefix": "",
"defaultSuffix": ""
},
"codeIndexMcp": "ace"
}
}
```
| 字段 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `defaultTool` | string | `gemini` | 默认 CLI 工具 |
| `promptFormat` | string | `plain` | Prompt 格式: `plain` / `yaml` / `json` |
| `smartContext.enabled` | boolean | `false` | 智能上下文开关 |
| `smartContext.maxFiles` | number | `10` | 最大文件数量 |
| `nativeResume` | boolean | `true` | 本地会话恢复 |
| `recursiveQuery` | boolean | `true` | 递归查询 |
| `cache.injectionMode` | string | `auto` | 缓存注入模式 |
| `codeIndexMcp` | string | `ace` | 代码索引 MCP: `codexlens` / `ace` / `none` |
### Hooks 配置
```json
{
"hooks": {
"prePrompt": [
{
"type": "command",
"command": "ccw",
"args": ["spec", "load", "--stdin"]
},
{
"type": "mcp",
"server": "cw-tools",
"tool": "core_memory",
"args": {
"operation": "search",
"query": "{{userPrompt}}",
"top_k": 5
}
}
],
"postResponse": [
{
"type": "command",
"command": "ccw",
"args": ["memory", "capture"]
}
]
}
}
```
## 操作步骤
### 初始化配置
```bash
# 在项目中初始化配置文件
ccw config init
# 编辑配置
ccw config edit
```
### 设置 API Keys
**方式 1: 编辑配置文件**
```bash
# 编辑项目配置
code .cw/settings.json
# 编辑全局配置
code ~/.claude/settings.json
```
**方式 2: 使用命令**
```bash
# 设置 OpenAI API Key
ccw config set providers.openai.apiKey "sk-proj-..."
# 设置 Anthropic API Key
ccw config set providers.anthropic.apiKey "sk-ant-..."
# 设置默认工具
ccw config set cw.defaultTool "codex"
```
**方式 3: 环境变量**
```bash
# 设置环境变量（优先级最高）
export OPENAI_API_KEY="sk-proj-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GEMINI_API_KEY="AIza..."
```
### 本地配置 (不提交)
```bash
# 创建本地配置（自动添加到 .gitignore）
cat > .cw/settings.local.json << 'EOF'
{
"providers": {
"openai": {
"apiKey": "sk-proj-..."
}
}
}
EOF
```
### 验证配置
```bash
# 验证 API Keys
ccw config verify
# 测试连接
ccw cli -p "Hello" --tool gemini --mode analysis
```
## 配置文件位置
| 配置文件 | 位置 | 用途 | Git |
| --- | --- | --- | --- |
| 项目配置 | `.cw/settings.json` | 项目共享配置 | 提交 |
| 本地配置 | `.cw/settings.local.json` | 个人开发配置 | **不提交** |
| 全局配置 | `~/.claude/settings.json` | 用户默认配置 | 不适用 |
| CLI 工具配置 | `~/.claude/cli-tools.json` | CLI 工具定义 | 不适用 |
| CLI 设置 | `.cw/cli-settings.json` | CLI 行为配置 | 提交 |
## 常见问题
### Q1: API Key 存储安全吗？
A: 建议使用 `settings.local.json` 存储敏感信息：
- `settings.local.json` 自动被 `.gitignore` 排除
- 永不提交到仓库
- 优先级最高，覆盖其他配置
### Q2: 如何切换不同环境？
A: 使用多配置文件：
```bash
# 开发环境
.cw/settings.dev.json
# 生产环境
.cw/settings.prod.json
# 切换环境
cp .cw/settings.dev.json .cw/settings.local.json
```
### Q3: LiteLLM 如何配置？
A: 配置 LiteLLM 端点：
```json
{
"providers": {
"litellm": {
"apiKey": "sk-...",
"baseURL": "https://your-litellm-proxy.com/v1"
}
},
"cw": {
"defaultTool": "litellm"
}
}
```
### Q4: 配置不生效怎么办？
A: 检查优先级和语法：
```bash
# 验证配置语法
ccw config validate
# 查看有效配置
ccw config show
# 查看配置来源
ccw config --debug
```
## 相关功能
- [CLI 调用系统](./cli.md) — 使用 API Keys 执行命令
- [系统设置](./system-settings.md) — cli-tools.json 配置
- [Dashboard 面板](./dashboard.md) — 可视化配置管理
## 进阶阅读
- 配置加载: `ccw/src/config/settings-loader.ts`
- 配置验证: `ccw/src/config/settings-validator.ts`
- CLI 配置: `ccw/src/tools/claude-cli-tools.ts`
- Hooks 执行: `ccw/src/core/hooks/`

308
docs/zh/features/cli.md Normal file
View File

@@ -0,0 +1,308 @@
# CLI 调用系统
## 一句话定位
**CLI 调用系统是统一的多模型 AI 执行框架** — 一个命令调用多个 AI 工具 (Gemini、Qwen、Codex、Claude)，支持 analysis/write/review 模式，自动处理流式输出和错误恢复。
## 解决的痛点
| 痛点 | 现状 | CLI 调用系统方案 |
| --- | --- | --- |
| **多工具分散** | 不同 AI 工具命令格式不一致 | 统一 `ccw cli` 入口 |
| **模型切换困难** | 换模型要查文档记参数 | `--tool` + `--model` 简化切换 |
| **输出格式混乱** | 各工具输出格式不统一 | 统一 JSON Lines 流式输出 |
| **错误恢复缺失** | 工具失败只能手动重试 | 自动 fallback 到备用模型 |
| **上下文管理弱** | 多轮对话上下文不连贯 | Native Resume 自动管理 |
## 核心概念速览
| 概念 | 说明 | 示例 |
| --- | --- | --- |
| **Tool (工具)** | AI 执行端点 | `gemini`, `qwen`, `codex`, `claude`, `opencode` |
| **Mode (模式)** | 执行权限级别 | `analysis` (只读), `write` (读写), `review` (代码审查) |
| **Model (模型)** | 工具使用的具体模型 | `gemini-2.5-flash`, `gpt-5.2`, `coder-model` |
| **Fallback (备用)** | 主模型失败时的自动切换 | secondaryModel 配置 |
| **Resume (恢复)** | 多轮对话上下文管理 | `--resume` 参数 |
| **Session (会话)** | 命令执行的对话上下文 | Native UUID / 消息历史 |
## 使用场景
| 场景 | 推荐工具 | 推荐模式 |
| --- | --- | --- |
| **代码分析** | `gemini` / `qwen` | `analysis` |
| **代码生成** | `codex` / `gemini` | `write` |
| **代码审查** | `codex` | `review` |
| **架构设计** | `gemini` + `codex` 并行 | `analysis` |
| **Bug 调试** | `gemini` (分析) -> `codex` (修复) | `analysis` -> `write` |
| **文档生成** | `qwen` / `gemini` | `write` |
## 操作步骤
### 基础用法
```bash
# 分析代码（默认 analysis 模式）
ccw cli -p "分析 auth 模块的代码结构" --tool gemini
# 生成代码（write 模式）
ccw cli -p "创建一个 JWT 认证中间件" --tool codex --mode write
# 代码审查（review 模式，仅 codex）
ccw cli -p "审查本次提交的代码变更" --tool codex --mode review
# 指定模型
ccw cli -p "分析性能瓶颈" --tool gemini --model "gemini-2.5-pro" --mode analysis
```
### 从文件读取 Prompt
```bash
# 使用 -p @file 语法
ccw cli -p @prompt.txt --tool gemini
# 使用 -f 参数
ccw cli -f prompt.md --tool qwen --mode write
```
### 工作目录控制
```bash
# 在特定目录执行
ccw cli -p "分析当前项目" --tool gemini --cd /path/to/project
# 包含额外目录（用于跨项目分析）
ccw cli -p "分析 shared 和 current 项目的关系" \
--tool gemini \
--cd /path/to/current \
--includeDirs /path/to/shared
```
### 多轮对话 (Resume)
```bash
# 启动新会话
ccw cli -p "设计一个用户认证系统" --tool gemini
# 继续上一轮对话
ccw cli -p "现在实现登录接口" --tool gemini --resume
# 继续指定会话
ccw cli -p "修改登录接口返回 JWT" --tool gemini --resume abc123-def456
# 合并多个会话上下文
ccw cli -p "整合之前的讨论" --tool gemini --resume abc123,def456
```
### 代码审查模式 (Codex 专用)
```bash
# 审查未提交的变更
ccw cli --tool codex --mode review
# 审查与指定分支的差异
ccw cli --tool codex --mode review --base main
# 审查指定提交
ccw cli --tool codex --mode review --commit abc123
# 带标题的审查
ccw cli -p "关注安全性问题" --tool codex --mode review --uncommitted
```
### 使用规则模板
```bash
# 加载预定义模板
ccw cli -p "分析代码安全性" \
--tool gemini \
--mode analysis \
--rule analysis-assess-security-risks
# 查看可用模板
ccw cli --help
```
## 配置说明
### 配置文件结构
**全局配置**: `~/.claude/cli-tools.json`
```json
{
"version": "3.3.0",
"tools": {
"gemini": {
"enabled": true,
"primaryModel": "gemini-2.5-flash",
"secondaryModel": "gemini-2.5-flash",
"availableModels": [
"gemini-3-pro-preview",
"gemini-2.5-pro",
"gemini-2.5-flash",
"gemini-2.0-flash"
],
"tags": ["分析", "Debug"],
"type": "builtin"
},
"codex": {
"enabled": true,
"primaryModel": "gpt-5.2",
"secondaryModel": "gpt-5.2",
"tags": [],
"type": "builtin"
}
}
}
```
**设置文件**: `.cw/cli-settings.json`
```json
{
"$schema": "../cli-tools-schema.json",
"version": "1.0.0",
"defaultTool": "gemini",
"promptFormat": "plain",
"smartContext": {
"enabled": false,
"maxFiles": 10
},
"nativeResume": true,
"recursiveQuery": true,
"cache": {
"injectionMode": "auto",
"defaultPrefix": "",
"defaultSuffix": ""
},
"codeIndexMcp": "ace"
}
```
### 工具类型 (Type)
| 类型 | 说明 | 可用模型 | 支持 |
| --- | --- | --- | --- |
| `builtin` | 内置 CLI 工具 | 完整模型列表 | 分析 + 写入 |
| `cli-wrapper` | Claude CLI 包装 | settings.json 中的模型 | 分析 + 写入 |
| `api-endpoint` | LiteLLM 端点 | 端点配置的模型 | **仅分析** |
### 标签 (Tags) 路由
标签用于工具选择和路由：
| 标签 | 说明 | 适用工具 |
| --- | --- | --- |
| `分析` | 代码分析、架构审查 | gemini, qwen |
| `Debug` | 调试、错误诊断 | gemini, qwen |
| `实现` | 代码生成、功能实现 | codex, gemini |
## 输出格式
### JSON Lines 流式输出
所有工具统一使用 JSON Lines 输出：
```json
{"type": "status", "message": "Connecting to API..."}
{"type": "delta", "content": "基于代码分析"}
{"type": "delta", "content": "，auth 模块包含以下组件"}
{"type": "usage", "prompt_tokens": 1000, "completion_tokens": 500}
{"type": "error", "message": "API timeout, retrying..."}
{"type": "done", "finish_reason": "stop"}
```
### 输出类型
| 类型 | 说明 |
| --- | --- |
| `status` | 状态更新 |
| `delta` | 内容增量 |
| `usage` | Token 使用量 |
| `error` | 错误信息 |
| `done` | 完成标记 |
## Dashboard 中的 CLI 终端
### 终端面板功能
```
┌─────────────────────────────────────────────────────────────┐
│ CLI 终端面板 │
├─────────────────────────────────────────────────────────────┤
│ ┌───────────────────────────────────────────────────────┐ │
│ │ 工具选择: [gemini ▼] 模式: [analysis ▼] 模型: [...] │ │
│ │ 目录: /path/to/project 包含: [shared] │ │
│ └───────────────────────────────────────────────────────┘ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ Prompt 输入区 (支持多行) │ │
│ │ [执行] [规则模板] [恢复会话] │ │
│ └───────────────────────────────────────────────────────┘ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ 输出区 (流式显示，支持 Markdown 渲染) │ │
│ │ - 代码高亮 │ │
│ │ - 错误高亮 │ │
│ │ - Token 统计 │ │
│ └───────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### 功能按钮
- **工具选择**: 下拉选择可用工具
- **模式选择**: analysis / write / review
- **模型选择**: 工具可用模型列表
- **规则模板**: 快速加载预定义模板
- **恢复会话**: 选择历史会话继续
## 常见问题
### Q1: analysis 和 write 模式的区别？
A:
- **analysis**: 只读模式，AI 只能读取文件，不能创建/修改/删除
- **write**: 读写模式，AI 可以完整操作文件系统
- **review**: 仅 Codex 支持，Git 感知的代码审查模式
### Q2: 如何选择合适的工具？
A: 基于场景推荐：
- **代码分析/架构设计**: `gemini` (速度快，上下文大)
- **代码生成/Bug 修复**: `codex` (代码能力强)
- **中文任务**: `qwen` (中文优化)
- **长上下文**: `claude` (200K+ tokens)
### Q3: Fallback 机制如何工作？
A: 当主工具失败时：
1. 尝试 `secondaryModel` (同工具)
2. 尝试下一个启用的工具
3. 回退到默认工具
### Q4: 如何调试 CLI 调用？
A: 使用 `-d, --debug` 参数：
```bash
ccw cli -p "分析代码" --tool gemini -d
```
输出详细诊断信息，包括：
- 工具可用性检查
- 命令构建过程
- API 调用详情
- 错误堆栈
## 相关功能
- [Spec 规范系统](./spec.md) — 规范自动注入到 Prompt
- [Memory 记忆系统](./memory.md) — Resume 上下文管理
- [API 设置](./api-settings.md) — API Keys 配置
- [系统设置](./system-settings.md) — cli-tools.json 配置
## 进阶阅读
- CLI 执行核心: `ccw/src/tools/cli-executor-core.ts`
- CLI 工具管理: `ccw/src/tools/claude-cli-tools.ts`
- 命令路由: `ccw/src/commands/cli.ts`
- 前端终端: `ccw/frontend/src/components/terminal-dashboard/`

320
docs/zh/features/codexlens.md Normal file
View File

@@ -0,0 +1,320 @@
# CodexLens 代码索引
## 一句话定位
**CodexLens 是语义代码搜索引擎** — 基于向量嵌入和 LSP 集成，让 AI 理解代码语义而非仅匹配关键词，支持混合检索和实时引用分析。
## 解决的痛点
| 痛点 | 现状 | CodexLens 方案 |
| --- | --- | --- |
| **搜索不精确** | 关键词搜不到语义相关代码 | 向量嵌入语义搜索 |
| **无上下文** | 搜索结果缺少调用上下文 | LSP 引用链分析 |
| **类型信息缺失** | 不知道符号的定义和引用 | 全局符号索引 |
| **跨文件关联弱** | 看不到模块间依赖关系 | 图扩展搜索 |
| **搜索速度慢** | 大项目搜索响应慢 | HNSW 近似最近邻 |
## 核心概念速览
| 概念 | 说明 | 位置/命令 |
| --- | --- | --- |
| **索引 (Index)** | 代码向量化存储 | `~/.codexlens/indexes/{project}/` |
| **混合检索 (Hybrid)** | 向量 + 关键词 + 结构 | `HybridSearchEngine` |
| **级联搜索 (Cascade)** | 多阶段优化搜索 | `cascade_search()` |
| **全局符号索引** | 跨项目符号数据库 | `GlobalSymbolIndex` |
| **LSP 集成** | 编辑器功能增强 | `codexlens lsp` |
| **嵌入器 (Embedder)** | 向量生成引擎 | `qwen3-embedding-sf` via LiteLLM |
## 使用场景
| 场景 | 搜索方式 | 示例 |
| --- | --- | --- |
| **查找函数** | 语义搜索 | "如何验证用户身份" → `authenticate()` |
| **查找用法** | 引用搜索 | 找到 `Token` 类的所有引用 |
| **查找依赖** | 图扩展 | 找到调用 `AuthService` 的所有模块 |
| **代码审查** | 关键词 + 向量 | "安全问题" → 搜索 `auth`, `password`, `encrypt` |
| **重构支持** | 符号索引 | 找到接口的所有实现 |
## 操作步骤
### 初始化索引
```bash
# 初始化项目索引
codexlens init /path/to/project
# 更新索引（增量）
codexlens update /path/to/project
# 清理索引
codexlens clean /path/to/project
```
### 语义搜索
```bash
# 基础语义搜索
codexlens search "如何验证用户身份"
# 指定项目路径
codexlens search --path /path/to/project "authentication flow"
# 设置结果数量
codexlens search --limit 10 "API endpoint design"
# 纯向量搜索（语义最强）
codexlens search --pure-vector "database connection pool"
# 启用 LSP 图扩展
codexlens search --enable-lsp-graph "auth service"
```
### 级联搜索
```bash
# 二进制级联（默认，最快）
codexlens cascade "auth" --strategy binary
# 二进制 + 重排（平衡）
codexlens cascade "auth" --strategy binary_rerank
# 密集 + 重排（质量最高）
codexlens cascade "auth" --strategy dense_rerank
# 四阶段管道（完整）
codexlens cascade "auth" --strategy staged
```
### LSP 服务器
```bash
# 启动 LSP 服务器
codexlens lsp start /path/to/project
# 查看状态
codexlens lsp status
# 停止服务器
codexlens lsp stop
```
### 向量嵌入
```bash
# 生成嵌入
codexlens embeddings generate /path/to/project
# 使用集中式元数据存储（推荐）
codexlens embeddings generate --centralized /path/to/project
# 检查嵌入状态
codexlens embeddings status /path/to/project
# 删除嵌入
codexlens embeddings delete /path/to/project
```
## 配置说明
### 搜索策略对比
| 策略 | 速度 | 质量 | 适用场景 |
| --- | --- | --- | --- |
| `binary` | 最快 | 中等 | 快速查找，代码意图明确 |
| `binary_rerank` | 快 | 高 | 平衡速度和质量（推荐） |
| `dense_rerank` | 中 | 很高 | 复杂查询，语义模糊 |
| `staged` | 慢 | 最高 | 深度分析，需要上下文 |
| `hybrid` | 中 | 高 | 综合检索（RRF 融合） |
### 融合权重配置
```python
weights = {
"vector": 0.5, # 向量相似度权重
"structural": 0.3, # 结构相似度权重
"keyword": 0.2 # 关键词匹配权重
}
```
### 嵌入配置
```python
# codexlens/config.py
embedding_backend = "litellm" # 嵌入后端
embedding_model = "qwen3-embedding-sf" # 嵌入模型
embedding_use_gpu = True # 使用 GPU 加速
chunk_size = 500 # 分块大小
chunk_overlap = 50 # 分块重叠
```
## 索引结构
### 目录结构
```
~/.codexlens/
├── indexes/ # 索引存储
│ └── {project_hash}/
│ └── codex-lens/
│ ├── _index.db # 主索引数据库
│ ├── _vectors_meta.db # 向量元数据（集中式）
│ ├── _vectors/ # HNSW 向量索引
│ │ ├── dir1/
│ │ │ └── hnsw_index.bin
│ │ └── dir2/
│ │ └── hnsw_index.bin
│ └── _symbols.db # 全局符号索引
├── venv/ # Python 虚拟环境
└── config.yaml # 全局配置
```
### 数据库结构
**_index.db** (主索引):
- `chunks`: 代码块表
- `files`: 文件表
- `symbols`: 符号表
- `relationships`: 关系表
**_vectors_meta.db** (向量元数据):
- `chunk_metadata`: 向量块元数据
- `embedding_stats`: 嵌入统计
**_symbols.db** (全局符号):
- `global_symbols`: 跨项目符号
- `symbol_references`: 符号引用
## 搜索流程
### 混合检索流程
```
┌─────────────────────────────────────────────────────────────┐
│ 混合检索流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. 查询分析 │
│ └─ 检测意图: KEYWORD / SEMANTIC / MIXED │
│ │
│ 2. 并行检索 │
│ ├─ 精确关键词 (BM25) │
│ ├─ 模糊关键词 (Fuzzy) │
│ └─ 向量相似度 (HNSW ANN) │
│ │
│ 3. 结果融合 (RRF) │
│ └─ Reciprocal Rank Fusion │
│ │
│ 4. (可选) LSP 图扩展 │
│ └─ 扩展引用链 │
│ │
│ 5. 重排序 │
│ └─ Cross-encoder / 规则调整 │
│ │
│ 6. 返回结果 │
│ │
└─────────────────────────────────────────────────────────────┘
```
### 级联搜索流程
```
┌─────────────────────────────────────────────────────────────┐
│ 级联搜索流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ Stage 1: 粗检索 (Coarse Retrieval) │
│ ├─ 二进制哈希快速筛选 │
│ └─ 返回 top-k 候选 (k=100) │
│ │ │
│ ▼ │
│ Stage 2: 精排序 (Fine Reranking) │
│ ├─ 密集向量重算相似度 │
│ ├─ (可选) Cross-encoder 重排 │
│ └─ 返回 top-k 结果 (k=20) │
│ │ │
│ ▼ │
│ Stage 3: LSP 扩展 (Graph Expansion, staged 策略) │
│ ├─ 查找符号引用 │
│ ├─ 扩展调用链 │
│ └─ 聚合去重 │
│ │ │
│ ▼ │
│ Stage 4: 聚类 (Clustering, staged 策略) │
│ └─ 按文件/模块聚类结果 │
│ │
└─────────────────────────────────────────────────────────────┘
```
## LSP 集成
### 支持的 LSP 功能
| 功能 | 说明 | 命令 |
| --- | --- | --- |
| **跳转到定义** | 跳转到符号定义 | `textDocument/definition` |
| **查找引用** | 查找所有引用 | `textDocument/references` |
| **自动完成** | 代码补全 | `textDocument/completion` |
| **悬停提示** | 显示类型和文档 | `textDocument/hover` |
| **工作区符号** | 搜索所有符号 | `workspace/symbol` |
### 启动 LSP 服务器
```bash
# CLI 启动
codexlens lsp start /path/to/project
# VS Code 集成
# 在 settings.json 中配置:
{
"codexlens.enabled": true,
"codexlens.lsp.port": 4389
}
```
## 常见问题
### Q1: 索引速度慢怎么办？
A: 优化策略：
- 使用 GPU 加速 (`embedding_use_gpu = True`)
- 减少分块大小 (`chunk_size = 300`)
- 限制索引范围（排除 `node_modules/`, `dist/` 等）
### Q2: 搜索结果不准确？
A: 调整搜索策略：
- 使用 `dense_rerank` 或 `staged` 策略
- 调整融合权重 (`--vector-weight`, `--structural-weight`)
- 使用纯向量搜索 (`--pure-vector`)
### Q3: LSP 功能不工作？
A: 检查：
```bash
# 检查 LSP 状态
codexlens lsp status
# 查看日志
codexlens lsp start --verbose /path/to/project
```
### Q4: 内存占用过高？
A: 优化配置：
- 减少并发索引数
- 使用增量更新 (`codexlens update`)
- 清理旧索引 (`codexlens clean`)
## 相关功能
- [Memory 记忆系统](./memory.md) — 向量嵌入共享
- [CLI 调用系统](./cli.md) — ccw search 命令
- [Dashboard 面板](./dashboard.md) — 搜索可视化
## 进阶阅读
- 搜索引擎: `codex-lens/src/codexlens/search/`
- 混合检索: `codex-lens/src/codexlens/search/hybrid_search.py`
- 级联搜索: `codex-lens/src/codexlens/search/chain_search.py`
- LSP 服务器: `codex-lens/src/codexlens/lsp/server.py`
- 嵌入器: `codex-lens/src/codexlens/semantic/`

338
docs/zh/features/dashboard.md Normal file
View File

@@ -0,0 +1,338 @@
# Dashboard 面板
## 一句话定位
**Dashboard 是 VS Code 内置的可视化管理中心** — 一个 Webview 界面统一管理 Specs、Skills、Memory、会话历史和 CLI 终端，无需离开编辑器。
## 解决的痛点
| 痛点 | 现状 | Dashboard 方案 |
| --- | --- | --- |
| **分散管理** | Specs、Skills、Memory 各自独立管理 | 统一界面集中管理 |
| **命令行操作** | 需要记住命令和参数 | 点击式 GUI 操作 |
| **状态不可见** | 后台任务执行状态不透明 | 实时状态展示 |
| **上下文切换** | 在终端和编辑器间频繁切换 | 集成在 VS Code 侧边栏 |
## 核心概念速览
| 概念 | 说明 | 入口 |
| --- | --- | --- |
| **首页** | 项目概览、快速入口 | Dashboard 主页 |
| **CLAUDE.md Manager** | 项目指令管理 | Specs 页面 |
| **Skills Manager** | 技能市场和管理 | Skills 页面 |
| **Core Memory 视图** | 记忆浏览和搜索 | Memory 页面 |
| **CLI 终端** | 统一命令执行 | Terminal 面板 |
| **会话历史** | 历史会话浏览 | Session 侧边栏 |
| **Graph Explorer** | 项目依赖可视化 | Graph 面板 |
## 使用场景
| 场景 | 使用页面 |
| --- | --- |
| **管理项目规范** | CLAUDE.md Manager |
| **安装/管理技能** | Skills Manager (Skill Hub) |
| **查看项目记忆** | Core Memory 视图 |
| **执行 CLI 命令** | CLI 终端 |
| **浏览会话历史** | Session 侧边栏 |
| **查看项目结构** | Graph Explorer |
## 操作步骤
### 启动 Dashboard
```bash
# 启动 Dashboard（默认端口 3456）
ccw view
# 指定端口
ccw view --port 8080
# 指定主机
ccw view --host 0.0.0.0
# 不自动打开浏览器
ccw view --no-browser
```
### Dashboard 布局
```
┌─────────────────────────────────────────────────────────────────┐
│ Dashboard 主界面 │
├───────────────────┬─────────────────────────────────────────────┤
│ │ │
│ 侧边栏导航 │ 主内容区 │
│ ┌─────────────┐ │ ┌─────────────────────────────────────┐ │
│ │ 首页 │ │ │ │ │
│ │ Specs │ │ │ 动态内容区域 │ │
│ │ Skills │ │ │ (根据导航变化) │ │
│ │ Memory │ │ │ │ │
│ │ Terminal │ │ │ │ │
│ │ Settings │ │ │ │ │
│ └─────────────┘ │ └─────────────────────────────────────┘ │
│ │ │
├───────────────────┴─────────────────────────────────────────────┤
│ 浮动面板 (可切换) │
│ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────────┐ │
│ │ Queue 面板 │ │ Inspector 面板 │ │ File 侧边栏 │ │
│ │ (任务队列) │ │ (对象检查) │ │ │ │
│ └─────────────────┘ └─────────────────┘ └──────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
### CLAUDE.md Manager (Specs 页面)
管理项目规范文档 (`.cw/specs/` 和 `~/.cw/personal/`)
**功能**:
- 浏览所有规范文件
- 按维度/类别/关键词筛选
- 编辑规范内容
- 创建新规范
- 重建索引缓存
**操作**:
```
1. 导航到 Specs 页面
2. 选择维度筛选器: all / specs / personal
3. (可选) 按类别筛选: general / exploration / planning / execution
4. (可选) 搜索框输入关键词
5. 点击规范卡片查看详情
6. 编辑内容并保存
7. 点击 "重建索引" 更新缓存
```
### Skills Manager (Skills 页面)
统一管理 Claude Skills 和 Codex Skills
**功能**:
- 浏览已安装技能
- 技能市场 (Skill Hub)
- 安装/卸载技能
- 启用/禁用技能
- 技能详情查看
**Skill Hub**:
- 远程技能库
- 本地技能发现
- 一键安装
- 版本管理
**操作**:
```
1. 导航到 Skills 页面
2. 切换 CLI 模式: Claude / Codex
3. 筛选: 类别 / 来源 / 状态
4. 点击 "Skill Hub" 浏览市场
5. 选择技能点击 "安装"
6. 使用开关启用/禁用技能
7. 点击技能卡片查看详情
```
### Core Memory 视图 (Memory 页面)
浏览和搜索项目记忆
**功能**:
- 记忆列表分页浏览
- 标签筛选
- 语义搜索
- 查看记忆详情
- 生成 AI 摘要
- 管理标签
**操作**:
```
1. 导航到 Memory 页面
2. (可选) 输入标签筛选
3. (可选) 输入搜索查询
4. 点击记忆卡片查看详情
5. 点击 "生成摘要" 调用 AI
6. 添加/删除标签
7. 查看提取任务状态
```
### CLI 终端 (Terminal 页面)
统一的 CLI 执行界面
**功能**:
- 工具选择下拉
- 模式选择 (analysis/write/review)
- 模型选择
- 工作目录配置
- Prompt 输入 (支持多行)
- 流式输出显示
- 规则模板快速加载
- 会话恢复管理
**操作**:
```
1. 导航到 Terminal 页面
2. 选择工具: gemini / qwen / codex / claude
3. 选择模式: analysis / write
4. (可选) 选择具体模型
5. (可选) 设置工作目录
6. 输入 Prompt (支持多行)
7. 点击 "执行" 或按 Ctrl+Enter
8. 查看流式输出
9. (可选) 使用规则模板
10. (可选) 恢复历史会话
```
### 浮动面板
#### Queue 面板
显示任务队列状态:
- 当前执行任务
- 等待中任务
- 已完成任务
- 失败任务
#### Inspector 面板
检查对象详情:
- 文件元数据
- 符号信息
- 依赖关系
#### File 侧边栏
项目文件浏览:
- 文件树
- 快速打开
- 文件搜索
### 会话侧边栏
浏览历史会话：
```
┌─────────────────────────────┐
│ Sessions [清空历史] │
├─────────────────────────────┤
│ ┌───────────────────────┐ │
│ │ 今天 │ │
│ │ • 会话 1 │ │
│ │ • 会话 2 │ │
│ │ │ │
│ │ 昨天 │ │
│ │ • 会话 3 │ │
│ │ • 会话 4 │ │
│ └───────────────────────┘ │
└─────────────────────────────┘
```
### Graph Explorer
可视化项目依赖：
```
┌─────────────────────────────────────────┐
│ Graph Explorer │
├─────────────────────────────────────────┤
│ │
│ ┌─────┐ ┌─────┐ │
│ │ API │ ───> │ Auth│ │
│ └─────┘ └─────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────┐ ┌─────┐ │
│ │ DB │ <────│User │ │
│ └─────┘ └─────┘ │
│ │
└─────────────────────────────────────────┘
```
**功能**:
- 模块依赖图
- 调用关系图
- 缩放/平移
- 节点搜索
## 配置说明
### Dashboard 配置 (settings.json)
```json
{
"dashboard": {
"port": 3456,
"host": "127.0.0.1",
"openBrowser": true,
"immersiveMode": false
},
"panels": {
"queue": {
"enabled": true,
"width": 400
},
"inspector": {
"enabled": true,
"width": 360
}
}
}
```
### 功能开关
```typescript
const featureFlags = {
dashboardQueuePanelEnabled: boolean, // Queue 面板
dashboardInspectorEnabled: boolean, // Inspector 面板
dashboardGraphEnabled: boolean, // Graph Explorer
};
```
## 常见问题
### Q1: Dashboard 无法启动？
A: 检查端口是否被占用：
```bash
# 检查端口占用
lsof -i :3456 # macOS/Linux
netstat -ano | findstr :3456 # Windows
# 使用其他端口
ccw view --port 8080
```
### Q2: Dashboard 内容不刷新？
A: Dashboard 使用缓存，手动刷新：
- 点击页面刷新按钮
- 或使用 `ccw view --restart`
### Q3: 如何在全屏模式下使用？
A: 使用沉浸式模式：
- 点击工具栏的全屏按钮
- 或按 `F11` 键
### Q4: Skills Hub 无法连接？
A: 检查网络连接和 Hub 地址：
```json
{
"skillHub": {
"url": "https://skill-hub.example.com",
"timeout": 10000
}
}
```
## 相关功能
- [Spec 规范系统](./spec.md) — CLAUDE.md Manager 管理的内容
- [Memory 记忆系统](./memory.md) — Core Memory 视图的数据
- [CLI 调用系统](./cli.md) — Terminal 面板的功能
## 进阶阅读
- Dashboard 主页: `ccw/frontend/src/pages/TerminalDashboardPage.tsx`
- Specs 页面: `ccw/frontend/src/pages/SpecsSettingsPage.tsx`
- Skills 页面: `ccw/frontend/src/pages/SkillsManagerPage.tsx`
- 路由配置: `ccw/src/core/routes/`

289
docs/zh/features/memory.md Normal file
View File

@@ -0,0 +1,289 @@
# Memory 记忆系统
## 一句话定位
**Memory 记忆系统是跨会话知识持久化引擎** — 让 AI 记住项目架构、编码规范和过往决策，新会话自动继承上下文，避免重复解释项目背景。
## 解决的痛点
| 痛点 | 现状 | Memory 记忆系统方案 |
| --- | --- | --- |
| **AI 不理解项目** | 新会话要重新解释项目背景 | Memory 持久化项目上下文 |
| **决策丢失** | AI 的架构决策下次会话就忘了 | Memory 记录架构决策和设计模式 |
| **规范重复** | 每次都要强调编码规范 | CLAUDE.md 自动加载到 Memory |
| **搜索困难** | 找不到之前的讨论内容 | 向量搜索语义相关记忆 |
## 核心概念速览
| 概念 | 说明 | 命令/位置 |
| --- | --- | --- |
| **Core Memory** | 核心记忆，存储项目级知识 | `ccw core-memory` |
| **Memory ID** | 记忆唯一标识，格式 `CMEM-YYYYMMDD-HHMMSS` | 自动生成 |
| **Memory Cluster** | 记忆集群，相关记忆分组 | `.cw/memory/clusters/` |
| **Embedding** | 向量嵌入，支持语义搜索 | `core_memory(operation="embed")` |
| **Stage1 Output** | 会话原始输出，用于提取 | Memory V2 管道 |
| **Extraction Job** | 记忆提取任务，后台异步执行 | `ccw core-memory jobs` |
## 使用场景
| 场景 | 说明 | 操作 |
| --- | --- | --- |
| **架构决策** | 记录重要技术决策 | `core_memory(operation="import", text="决策内容")` |
| **编码规范** | 持久化 CLAUDE.md | 自动导入 |
| **设计模式** | 记录项目使用的设计模式 | 手动添加带标签的记忆 |
| **跨会话上下文** | 新会话加载项目记忆 | 自动加载（通过 hook） |
## 操作步骤
### Memory V2 管道
Memory V2 采用两阶段提取管道：
```
┌─────────────────────────────────────────────────────────────┐
│ Memory V2 提取管道 │
├─────────────────────────────────────────────────────────────┤
│ │
│ Phase 1: 会话结束后提取 (Rollout Extraction) │
│ ┌─────────────┐ ┌──────────────┐ ┌────────────────┐ │
│ │ 会话结束 │ -> │ 压缩 Transcript│ -> │ Stage1 Output │ │
│ └─────────────┘ └──────────────┘ └────────────────┘ │
│ │ │
│ ▼ │
│ 提取任务调度器 │
│ │ │
│ Phase 2: 后台合并 (Consolidation) │
│ ┌───────────────┐ ┌──────────────┐ ┌─────────────┐│
│ │ 多个 Stage1 │ -> │ LLM 合并提取 │ -> │ Core Memory ││
│ └───────────────┘ └──────────────┘ └─────────────┘│
│ │
└─────────────────────────────────────────────────────────────┘
```
### 基础 Memory 操作
```bash
# 列出所有记忆
ccw core-memory list
# 列出特定标签的记忆
ccw core-memory list --tags "auth,api"
# 导入新记忆
ccw core-memory import --text "项目使用 JWT 进行身份验证，Token 有效期 24 小时"
# 导出记忆内容
ccw core-memory export --id CMEM-20240215-143000
# 生成 AI 摘要
ccw core-memory summary --id CMEM-20240215-143000 --tool gemini
# 搜索记忆（语义搜索）
ccw core-memory search --query "身份验证" --top-k 5
# 删除记忆
ccw core-memory delete --id CMEM-20240215-143000
```
### Memory 管理
```bash
# 查看提取任务状态
ccw core-memory jobs
# 查看特定类型的任务
ccw core-memory jobs --type phase1_extraction
# 按状态筛选
ccw core-memory jobs --status pending
# 手动触发提取
ccw core-memory extract --max-sessions 10
# 手动触发合并
ccw core-memory consolidate
```
### MCP 工具调用
在 Claude Code 中使用 MCP 工具：
```typescript
// 列出记忆
core_memory(operation="list")
// 带标签筛选
core_memory(operation="list", tags=["auth", "security"])
// 导入记忆
core_memory(operation="import", text="重要内容")
// 导出记忆
core_memory(operation="export", id="CMEM-xxx")
// 生成摘要
core_memory(operation="summary", id="CMEM-xxx", tool="gemini")
// 生成嵌入
core_memory(operation="embed", source_id="CMEM-xxx")
// 语义搜索
core_memory(operation="search", query="authentication", top_k=10, min_score=0.3)
// 检查嵌入状态
core_memory(operation="embed_status")
// 触发提取
core_memory(operation="extract", max_sessions=10)
// 检查提取状态
core_memory(operation="extract_status")
// 触发合并
core_memory(operation="consolidate")
// 检查合并状态
core_memory(operation="consolidate_status")
// 列出任务
core_memory(operation="jobs", kind="extraction", status_filter="pending")
```
## 配置说明
### Memory V2 配置 (memory-v2-config.ts)
| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| `MAX_RAW_MEMORY_CHARS` | 300,000 | Stage1 原始记忆最大字符数 |
| `MAX_SUMMARY_CHARS` | 1,200 | 摘要最大字符数 |
| `MAX_ROLLOUT_BYTES_FOR_PROMPT` | 1,000,000 | 发送给 LLM 的最大字节数 |
| `MAX_RAW_MEMORIES_FOR_GLOBAL` | 64 | 合并时包含的原始记忆数量 |
### 存储路径
```
.cw/
├── memory/
│ ├── core-memory.db # SQLite 数据库
│ ├── clusters/ # 记忆集群
│ └── embeddings/ # 向量嵌入
```
### Memory 数据结构
```typescript
interface CoreMemory {
id: string; // CMEM-YYYYMMDD-HHMMSS
content: string; // 记忆内容
summary: string | null; // AI 生成摘要
raw_output?: string; // 原始输出（V2）
created_at: string; // ISO timestamp
updated_at: string; // ISO timestamp
archived: boolean; // 是否归档
metadata?: string; // JSON 元数据
tags?: string[]; // 标签数组
}
```
## Dashboard 中的 Memory 管理
### Core Memory 视图
Dashboard 提供 Memory 可视化管理界面：
```
┌─────────────────────────────────────────────────────────────┐
│ Core Memory 视图 │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 记忆列表 │ │ 记忆详情/编辑 │ │
│ │ - 搜索 │ │ - 内容显示 │ │
│ │ - 标签筛选 │ │ - 标签管理 │ │
│ │ - 排序 │ │ - 摘要生成 │ │
│ └─────────────────┘ └─────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 提取任务状态 │ │
│ │ - Pending/Running/Done/Error 计数 │ │
│ │ - 任务列表 │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### 操作功能
- **浏览记忆**: 分页列表，支持搜索和标签筛选
- **编辑记忆**: 直接修改内容，自动更新时间戳
- **生成摘要**: 一键调用 AI 生成摘要
- **管理标签**: 添加/删除标签
- **删除记忆**: 软删除（归档）或硬删除
## 常见问题
### Q1: Memory 和 CLAUDE.md 的区别？
A:
- **CLAUDE.md**: 静态配置文件，手动编写，每次会话完整加载
- **Memory**: 动态数据库，自动/手动积累，按需搜索和加载
### Q2: 如何让 AI 在新会话中自动加载 Memory？
A: 在 `settings.json` 中配置 hook：
```json
{
"hooks": {
"prePrompt": [
{
"type": "mcp",
"server": "cw-tools",
"tool": "core_memory",
"args": {
"operation": "search",
"query": "{{userPrompt}}",
"top_k": 5
}
}
]
}
}
```
### Q3: Memory V2 管道何时触发？
A: 管道自动触发时机：
- **Phase 1**: 会话结束时自动提取（如果启用）
- **Phase 2**: 当 Stage1 outputs 数量达到阈值时自动合并
手动触发：
```bash
ccw core-memory extract
ccw core-memory consolidate
```
### Q4: 嵌入搜索需要什么条件？
A: 需要安装 CodexLens Python 环境：
```bash
# 检查嵌入状态
ccw core-memory embed-status
# 生成嵌入
ccw core-memory embed --source-id CMEM-xxx
```
## 相关功能
- [Spec 规范系统](./spec.md) — 规范自动注入
- [CLI 调用系统](./cli.md) — ccw core-memory 命令
- [CodexLens 代码索引](./codexlens.md) — 向量嵌入引擎
## 进阶阅读
- Memory 存储实现: `ccw/src/core/core-memory-store.ts`
- 提取管道: `ccw/src/core/memory-extraction-pipeline.ts`
- 任务调度器: `ccw/src/core/memory-job-scheduler.ts`
- 嵌入桥接: `ccw/src/core/memory-embedder-bridge.ts`
- MCP 工具: `ccw/src/tools/core-memory.ts`

283
docs/zh/features/spec.md Normal file
View File

@@ -0,0 +1,283 @@
# Spec 规范系统
## 一句话定位
**Spec 规范系统是项目约束的自动注入机制** — 通过 YAML 前置元数据定义的规范文档，在 AI 会话开始时自动加载相关约束，让 AI 遵守项目编码规范和架构要求。
## 解决的痛点
| 痛点 | 现状 | Spec 规范系统方案 |
| --- | --- | --- |
| **AI 不遵守规范** | CLAUDE.md 写了规范，AI 经常忽略 | 规范按 `readMode: required` 自动强制加载 |
| **规范难以维护** | 所有约束堆在一个文件里 | 按维度 (specs/personal) 和类别 (exploration/planning/execution) 分离 |
| **规范加载不智能** | 每次会话都要手动复制粘贴 | 根据用户 Prompt 关键词自动匹配相关规范 |
| **规范粒度太粗** | 只能全项目或全无 | 支持分类 (general/exploration/planning/execution) 按需加载 |
## 核心概念速览
| 概念 | 说明 | 位置/命令 |
| --- | --- | --- |
| **Dimension (维度)** | 规范所属的分类空间 | `specs` (项目规范) / `personal` (个人偏好) |
| **Category (类别)** | 工作流阶段分类 | `general` / `exploration` / `planning` / `execution` |
| **readMode (读取模式)** | 加载策略 | `required` (强制加载) / `optional` (关键词匹配时加载) |
| **priority (优先级)** | 规范展示顺序 | `critical` / `high` / `medium` / `low` |
| **keywords (关键词)** | 用于自动匹配的标签 | YAML 数组，与用户 Prompt 关键词取交集 |
| **Spec Index** | 规范索引缓存 | `.ccw/.spec-index/{dimension}.index.json` |
## Spec 文件结构
### 规范文件模板
```markdown
---
title: "文档标题"
dimension: "specs" # 规范维度: specs | personal
category: "general" # 工作流类别: general | exploration | planning | execution
keywords:
- keyword1
- keyword2
readMode: "required" # 读取模式: required | optional
priority: "high" # 优先级: critical | high | medium | low
---
# 规范内容（Markdown 正文）
这里是规范的具体内容...
```
### 规范目录结构
```
.cw/
├── specs/ # 项目规范（维度：specs）
│ ├── coding-conventions.md
│ ├── architecture-constraints.md
│ └── api-design-guidelines.md
├── personal/ # 个人偏好（维度：personal）
│ ├── coding-style.md
│ └── review-preferences.md
└── .spec-index/ # 索引缓存（自动生成）
├── specs.index.json
└── personal.index.json
```
## 使用场景
| 场景 | 说明 | 配置示例 |
| --- | --- | --- |
| **编码规范** | 强制 AI 遵守项目代码风格 | `dimension: specs`, `readMode: required` |
| **架构约束** | 定义模块边界和依赖规则 | `dimension: specs`, `category: planning` |
| **API 设计** | 规范 API 设计原则 | `dimension: specs`, `keywords: [api, rest, graphql]` |
| **个人偏好** | 个人的代码风格偏好 | `dimension: personal`, `readMode: optional` |
## 操作步骤
### 初始化 Spec 系统
```bash
# 在项目根目录初始化规范系统
ccw spec init
```
**输出**:
```
Initializing spec system...
Directories created:
+ .cw/specs/
+ .cw/personal/
+ .cw/.spec-index/
Seed files created:
+ .cw/specs/coding-conventions.md
+ .cw/specs/architecture-constraints.md
```
### 创建规范文件
```bash
# 手动创建规范文件
cat > .cw/specs/api-design.md << 'EOF'
---
title: "API Design Guidelines"
dimension: "specs"
category: "planning"
keywords:
- api
- rest
- endpoint
- http
readMode: "optional"
priority: "high"
---
# API 设计规范
## RESTful 约定
- 使用名词表示资源
- 使用 HTTP 方法表示操作
- 统一错误响应格式
## 命名约定
- 路径使用 kebab-case
- 查询参数使用 camelCase
EOF
```
### 加载规范
**CLI 模式**（查看规范内容）:
```bash
# 列出所有规范
ccw spec list
# 按维度列出
ccw spec list --dimension specs
# 加载特定类别的规范
ccw spec load --category planning
# 按关键词加载规范
ccw spec load --keywords "api rest"
# 重建索引缓存
ccw spec rebuild
```
**Hook 模式**（自动注入到 AI 上下文）:
在 `settings.json` 中配置 hook:
```json
{
"hooks": {
"prePrompt": [
{
"type": "command",
"command": "ccw",
"args": ["spec", "load", "--stdin"]
}
]
}
}
```
## 配置说明
### YAML 前置元数据字段
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `title` | string | 是 | 规范文档标题 |
| `dimension` | string | 是 | 维度：`specs` 或 `personal` |
| `category` | string | 否 | 类别：`general` / `exploration` / `planning` / `execution` |
| `keywords` | string[] | 是 | 关键词列表，用于自动匹配 |
| `readMode` | string | 是 | `required`（强制）或 `optional`（可选） |
| `priority` | string | 否 | 优先级：`critical` / `high` / `medium` / `low` |
### 类别 (category) 说明
| 类别 | 加载时机 | 适用场景 |
| --- | --- | --- |
| `general` | 始终加载（当 readMode=required） | 通用规范，如编码风格、命名约定 |
| `exploration` | 探索阶段 | 架构探索、技术选型指南 |
| `planning` | 规划阶段 | 设计模式、模块划分原则 |
| `execution` | 执行阶段 | 具体实现规范、测试要求 |
## 规范加载机制
### 加载流程
```
┌─────────────────────────────────────────────────────────────┐
│ Spec 加载流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. 用户输入 Prompt │
│ │ │
│ ▼ │
│ 2. 关键词提取 (extractKeywords) │
│ │ │
│ ▼ │
│ 3. 读取索引缓存 (getDimensionIndex) │
│ │ │
│ ▼ │
│ 4. 过滤规范 (filterSpecs) │
│ ├─ required: 全部加载 │
│ └─ optional: 关键词匹配时加载 │
│ │ │
│ ▼ │
│ 5. 加载内容 (loadSpecContent) │
│ │ │
│ ▼ │
│ 6. 按优先级合并 (mergeByPriority) │
│ │ │
│ ▼ │
│ 7. 格式化输出 (CLI markdown / Hook JSON) │
│ │
└─────────────────────────────────────────────────────────────┘
```
### 关键词匹配规则
- **英文关键词**: 转小写，移除停用词，取长度 >= 3 的词
- **中文关键词**: 提取连续 CJK 字符序列
- **匹配逻辑**: 用户关键词与规范关键词取交集，有交集即匹配
### 优先级合并顺序
```
critical > high > medium > low
```
同优先级内按 `dimension` 优先级：`specs` > `personal`
## 常见问题
### Q1: 规范文件修改后没有生效？
A: 规范内容通过索引缓存加载，修改后需要重建索引：
```bash
ccw spec rebuild
```
### Q2: 如何调试规范加载过程？
A: 使用 `--debug` 参数查看加载详情：
```bash
ccw spec load --keywords "auth" --debug
```
输出示例：
```
[specs] scanned=5 required=2 matched=1
Loaded: coding-conventions (required)
Loaded: auth-security (matched: auth)
Total: scanned=10 loaded=3
```
### Q3: required 和 optional 的区别？
A:
- `required`: 无论用户输入什么，都会加载（适用于通用规范）
- `optional`: 只有当用户 Prompt 包含匹配关键词时才加载（适用于特定场景规范）
### Q4: 个人偏好和项目规范冲突怎么办？
A: 优先级顺序为 `specs` > `personal`。项目规范会覆盖个人偏好。
## 相关功能
- [Memory 记忆系统](./memory.md) — 跨会话知识持久化
- [CLI 调用系统](./cli.md) — ccw spec 命令
- [系统设置](./system-settings.md) — Hook 配置
## 进阶阅读
- 规范索引实现: `ccw/src/tools/spec-index-builder.ts`
- 规范加载器: `ccw/src/tools/spec-loader.ts`
- 关键词提取: `ccw/src/tools/spec-keyword-extractor.ts`
- Dashboard Spec 管理: `ccw/frontend/src/pages/SpecsSettingsPage.tsx`

475
docs/zh/features/system-settings.md Normal file
View File

@@ -0,0 +1,475 @@
# 系统设置
## 一句话定位
**系统设置是 CCW 的全局配置中心** — 管理 CLI 工具定义、Hooks、代理、Agent 和行为偏好，控制整个 CCW 工作流的运行方式。
## 解决的痛点
| 痛点 | 现状 | 系统设置方案 |
| --- | --- | --- |
| **配置分散** | 配置散落多个文件 | 集中在 `~/.claude/` 目录 |
| **工具定义复杂** | 添加新工具需要修改代码 | JSON 配置定义工具 |
| **自动化困难** | 手动执行重复任务 | Hooks 自动化 |
| **行为不一致** | 不同项目行为差异大 | 全局配置统一行为 |
## 核心概念速览
| 概念 | 说明 | 位置 |
| --- | --- | --- |
| **cli-tools.json** | CLI 工具定义 | `~/.claude/cli-tools.json` |
| **settings.json** | 项目设置 | `.cw/settings.json` |
| **CLAUDE.md** | 项目指令 | `.cw/CLAUDE.md` |
| **Hooks** | 自动化钩子 | `settings.json` hooks |
| **Agents** | 智能代理配置 | `~/.claude/agents/` |
| **Proxy** | 网络代理配置 | `settings.json` proxy |
## 配置文件总览
```
~/.claude/ # 全局配置目录
├── cli-tools.json # CLI 工具定义
├── settings.json # 默认设置
├── agents/ # Agent 配置
│ ├── cli-execution-agent.md
│ └── ...
└── workflows/ # 工作流配置
└── ...
.cw/ # 项目配置目录
├── settings.json # 项目设置
├── settings.local.json # 本地设置（不提交）
├── CLAUDE.md # 项目指令
├── cli-settings.json # CLI 行为配置
├── specs/ # 项目规范
│ ├── coding-conventions.md
│ └── ...
└── personal/ # 个人偏好
└── ...
```
## 配置详解
### cli-tools.json (CLI 工具定义)
定义可用的 AI 工具及其配置：
```json
{
"version": "3.3.0",
"tools": {
"gemini": {
"enabled": true,
"primaryModel": "gemini-2.5-flash",
"secondaryModel": "gemini-2.5-flash",
"availableModels": [
"gemini-3-pro-preview",
"gemini-2.5-pro",
"gemini-2.5-flash",
"gemini-2.0-flash"
],
"tags": ["分析", "Debug"],
"type": "builtin"
},
"qwen": {
"enabled": true,
"primaryModel": "coder-model",
"secondaryModel": "coder-model",
"tags": [],
"type": "builtin"
},
"codex": {
"enabled": true,
"primaryModel": "gpt-5.2",
"secondaryModel": "gpt-5.2",
"tags": [],
"type": "builtin"
},
"claude": {
"enabled": true,
"primaryModel": "sonnet",
"secondaryModel": "haiku",
"tags": [],
"type": "builtin",
"settingsFile": "D:\\settings-glm5.json"
},
"opencode": {
"enabled": true,
"primaryModel": "opencode/glm-4.7-free",
"secondaryModel": "opencode/glm-4.7-free",
"tags": [],
"type": "builtin"
}
}
}
```
#### 字段说明
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `version` | string | 配置文件版本 |
| `tools` | object | 工具定义集合 |
| `enabled` | boolean | 是否启用 |
| `primaryModel` | string | 主模型 |
| `secondaryModel` | string | 备用模型 |
| `availableModels` | string[] | 可用模型列表 |
| `tags` | string[] | 能力标签 |
| `type` | string | 工具类型: `builtin` / `cli-wrapper` / `api-endpoint` |
### cli-settings.json (CLI 行为配置)
```json
{
"$schema": "../cli-tools-schema.json",
"version": "1.0.0",
"defaultTool": "gemini",
"promptFormat": "plain",
"smartContext": {
"enabled": false,
"maxFiles": 10
},
"nativeResume": true,
"recursiveQuery": true,
"cache": {
"injectionMode": "auto",
"defaultPrefix": "",
"defaultSuffix": ""
},
"codeIndexMcp": "ace"
}
```
#### 字段说明
| 字段 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `defaultTool` | string | `gemini` | 默认 CLI 工具 |
| `promptFormat` | string | `plain` | Prompt 格式 |
| `smartContext.enabled` | boolean | `false` | 智能上下文开关 |
| `smartContext.maxFiles` | number | `10` | 最大文件数 |
| `nativeResume` | boolean | `true` | 本地会话恢复 |
| `recursiveQuery` | boolean | `true` | 递归查询 |
| `cache.injectionMode` | string | `auto` | 缓存注入模式 |
| `codeIndexMcp` | string | `ace` | 代码索引 MCP |
### CLAUDE.md (项目指令)
全局项目指令：
```markdown
# Claude Instructions
## Coding Philosophy
- **Pursue good taste** - Eliminate edge cases
- **Embrace extreme simplicity**
- **Be pragmatic** - Solve real problems
## CLI Endpoints
- **CLI Tools Usage**: @~/.ccw/workflows/cli-tools-usage.md
- **CLI Endpoints Config**: @~/.claude/cli-tools.json
## Tool Execution
- **Always use `run_in_background: false`** for Task tool agent calls
- **Default: Use Bash `run_in_background: true`** for CLI calls
## Code Diagnostics
- **Prefer `mcp__ide__getDiagnostics`** for code error checking
```
### CLAUDE.md 结构
```markdown
# 全局指令 (~/)
├── Coding Philosophy # 编码哲学
├── CLI Endpoints # CLI 配置
├── Tool Execution # 工具执行规则
├── Code Diagnostics # 诊断规则
└── ...
# 项目指令 (.cw/)
├── Project Overview # 项目概述
├── Architecture # 架构说明
├── Conventions # 编码约定
└── Module Specifics # 模块特定规则
```
## Hooks 配置
### Hook 类型
| 类型 | 触发时机 | 用途 |
| --- | --- | --- |
| `prePrompt` | 发送 Prompt 前 | 注入上下文、规范 |
| `postResponse` | 收到响应后 | 捕获记忆、更新状态 |
| `preCommand` | 执行命令前 | 验证、修改参数 |
| `postCommand` | 执行命令后 | 清理、通知 |
### Hook 配置示例
```json
{
"hooks": {
"prePrompt": [
{
"type": "command",
"command": "ccw",
"args": ["spec", "load", "--stdin"],
"timeout": 5000
},
{
"type": "mcp",
"server": "cw-tools",
"tool": "core_memory",
"args": {
"operation": "search",
"query": "{{userPrompt}}",
"top_k": 5
}
},
{
"type": "file",
"path": ".cw/prompts/system-prefix.md"
}
],
"postResponse": [
{
"type": "command",
"command": "ccw",
"args": ["memory", "capture", "--auto"]
},
{
"type": "mcp",
"server": "cw-tools",
"tool": "core_memory",
"args": {
"operation": "import",
"text": "{{response}}",
"tags": ["auto-capture"]
}
}
]
}
}
```
## Agents 配置
### Agent 定义
Agent 定义文件位于 `~/.claude/agents/`：
```markdown
---
name: cli-execution-agent
version: "1.0.0"
description: Execute CLI tools with intelligent fallback
---
# CLI Execution Agent
## Phase 1: Intent Analysis
Analyze user prompt to determine:
- Task type (analyze/plan/execute/discuss)
- Tool selection (gemini/qwen/codex/claude)
- Mode (analysis/write/review)
## Phase 2: Tool Selection
| Task Type | Primary Tool | Fallback |
|-----------|--------------|----------|
| analyze | gemini | qwen |
| plan | gemini | codex |
| execute (simple) | gemini | qwen |
| execute (complex) | codex | gemini |
| discuss | multi | - |
## Phase 3: Execution
Build and execute CLI command with:
- Proper mode selection
- Model configuration
- Error handling
- Output formatting
```
### Agent 调用
```bash
# 调用 Agent
ccw agent execute cli-execution-agent \
--prompt "分析代码结构" \
--context @src/**/*.ts
```
## 代理配置
### HTTP 代理
```json
{
"proxy": {
"http": "http://proxy.example.com:8080",
"https": "https://proxy.example.com:8080",
"noProxy": ["localhost", "127.0.0.1", "*.local"]
}
}
```
### SOCKS 代理
```json
{
"proxy": {
"socks": "socks5://127.0.0.1:1080"
}
}
```
### 环境变量
```bash
# 设置代理环境变量
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="https://proxy.example.com:8080"
export NO_PROXY="localhost,127.0.0.1"
```
## 操作步骤
### 初始化系统配置
```bash
# 初始化全局配置
ccw config init --global
# 初始化项目配置
ccw config init
# 查看当前配置
ccw config show
# 验证配置
ccw config validate
```
### 添加新工具
```bash
# 编辑 cli-tools.json
code ~/.claude/cli-tools.json
# 添加新工具定义
{
"tools": {
"new-tool": {
"enabled": true,
"primaryModel": "model-name",
"secondaryModel": "fallback-model",
"tags": ["tag1", "tag2"],
"type": "builtin"
}
}
}
```
### 配置 Hooks
```bash
# 编辑项目 settings.json
code .cw/settings.json
# 添加 prePrompt hook
{
"hooks": {
"prePrompt": [
{
"type": "command",
"command": "ccw",
"args": ["spec", "load", "--stdin"]
}
]
}
}
```
### 配置代理
```bash
# 编辑全局配置
code ~/.claude/settings.json
# 添加代理配置
{
"proxy": {
"http": "http://proxy.example.com:8080",
"https": "https://proxy.example.com:8080"
}
}
```
## 配置优先级
```
1. 环境变量 (最高)
2. settings.local.json
3. settings.json (项目)
4. settings.json (全局)
5. 默认值 (最低)
```
## 常见问题
### Q1: cli-tools.json 和 cli-settings.json 的区别？
A:
- **cli-tools.json**: 定义可用的工具（工具商店）
- **cli-settings.json**: 配置 CLI 的行为（偏好设置）
### Q2: Hooks 执行顺序？
A: 按数组顺序依次执行：
1. 数组前面的先执行
2. 失败会中断后续 Hook
3. 使用 `continueOnError: true` 忽略失败
### Q3: 如何调试配置？
A: 使用 debug 模式：
```bash
# 查看配置加载过程
ccw config show --debug
# 验证配置语法
ccw config validate
# 查看有效配置
ccw config effective
```
### Q4: 配置修改后不生效？
A: 检查：
1. 配置文件位置是否正确
2. JSON 语法是否正确
3. 配置优先级是否被覆盖
4. 是否需要重启服务
## 相关功能
- [API 设置](./api-settings.md) — API Keys 配置
- [CLI 调用系统](./cli.md) — CLI 工具使用
- [Spec 规范系统](./spec.md) — 规范文件配置
## 进阶阅读
- 配置加载器: `ccw/src/config/settings-loader.ts`
- CLI 工具管理: `ccw/src/tools/claude-cli-tools.ts`
- Hooks 执行: `ccw/src/core/hooks/hook-executor.ts`
- 代理处理: `ccw/src/utils/proxy-agent.ts`