mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-01 15:03:57 +08:00
c3ddf7e322
- 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
476 lines
10 KiB
Markdown
476 lines
10 KiB
Markdown
# 系统设置
|
||
|
||
## 一句话定位
|
||
|
||
**系统设置是 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`
|