init doc

2026-02-19 15:10:49 +08:00 · 2025-12-27 07:58:01 +08:00
parent 085ee97cdc
commit 160594a8d6
64 changed files with 17205 additions and 15 deletions
--- a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/advanced/agents.md
+++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/advanced/agents.md
@@ -0,0 +1,112 @@
+---
+id: advanced/agents
+title: Agent 系统
+sidebar_position: 2
+---
+
+# Agent 系统
+
+使用 Agent 系统扩展功能。
+
+## 什么是 Agent？
+
+Agent 是可插拔的功能模块，可以：
+- 检测是否应处理请求
+- 修改请求
+- 提供自定义工具
+
+## 内置 Agent
+
+### Image Agent
+
+通过检测请求中的图像 URL 或文件路径来处理图像相关任务。
+
+当检测到图像相关内容时，Image Agent 会：
+1. 标记请求需要图像处理
+2. 添加图像分析工具到请求中
+3. 拦截工具调用事件
+4. 执行图像分析并返回结果
+
+## Agent 配置
+
+Agent 在服务器配置中配置并自动加载。
+
+### 启用 Image Agent
+
+Image Agent 内置于服务器中，无需额外配置。当请求包含图像内容时自动激活。
+
+### 强制使用 Image Agent
+
+如果您的模型不支持工具调用，可以在配置中设置 `config.forceUseImageAgent` 为 `true`：
+
+```json
+{
+  "Router": {
+    "image": "gemini,gemini-2.5-pro"
+  },
+  "forceUseImageAgent": true
+}
+```
+
+## Agent 工具调用流程
+
+1. **检测阶段**：在 `preHandler` 钩子中检测并标记 agents
+2. **准备阶段**：将 agent 工具添加到请求中
+3. **拦截阶段**：在 `onSend` 钩子中拦截工具调用事件
+4. **执行阶段**：执行 agent 工具并发起新的 LLM 请求
+5. **返回阶段**：将结果流式返回
+
+## Agent 类型定义
+
+```typescript
+interface IAgent {
+  name: string;
+  shouldHandle: (req: any, config: any) => boolean;
+  reqHandler: (req: any, config: any) => void;
+  tools: Map<string, ITool>;
+}
+
+interface ITool {
+  name: string;
+  description: string;
+  input_schema: object;
+  handler: (args: any, context: any) => Promise<any>;
+}
+```
+
+## 创建自定义 Agent
+
+自定义 Agent 支持正在开发中！
+
+## 使用示例
+
+### 图像分析请求
+
+当您发送包含图像的请求时：
+
+```
+请分析这张图片：/path/to/image.png
+```
+
+Image Agent 将：
+1. 检测到图像路径
+2. 添加图像分析工具
+3. 调用配置的图像处理模型
+4. 返回分析结果
+
+### 路由到支持图像的模型
+
+在配置中指定用于图像任务的模型：
+
+```json
+{
+  "Router": {
+    "image": "gemini,gemini-2.5-pro"
+  }
+}
+```
+
+## 下一步
+
+- [预设](/zh/docs/advanced/presets) - 使用预定义配置
+- [自定义路由器](/zh/docs/advanced/custom-router) - 编写自定义路由逻辑
--- a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/advanced/custom-router.md
+++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/advanced/custom-router.md
@@ -0,0 +1,149 @@
+---
+id: advanced/custom-router
+title: 自定义路由器
+sidebar_position: 1
+---
+
+# 自定义路由器
+
+使用 JavaScript 编写自己的路由逻辑。
+
+## 创建自定义路由器
+
+创建一个导出路由函数的 JavaScript 文件：
+
+```javascript
+// custom-router.js
+module.exports = async function(req, config) {
+  // 获取用户消息
+  const userMessage = req.body.messages.find(m => m.role === 'user')?.content;
+
+  // 自定义逻辑
+  if (userMessage && userMessage.includes('解释代码')) {
+    return 'openrouter,anthropic/claude-3.5-sonnet';
+  }
+
+  // 返回 null 以使用默认路由
+  return null;
+};
+```
+
+## 参数说明
+
+路由函数接收以下参数：
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `req` | object | 来自 Claude Code 的请求对象，包含请求体 |
+| `config` | object | 应用程序的配置对象 |
+
+## 配置
+
+在 `config.json` 中设置 `CUSTOM_ROUTER_PATH` 以使用您的自定义路由器：
+
+```json
+{
+  "CUSTOM_ROUTER_PATH": "/path/to/custom-router.js"
+}
+```
+
+## 返回格式
+
+路由函数应返回以下格式的字符串：
+
+```
+{provider-name},{model-name}
+```
+
+示例：
+
+```
+deepseek,deepseek-chat
+```
+
+如果返回 `null`，则回退到默认路由配置。
+
+## 错误处理
+
+如果路由函数抛出错误或返回无效格式，路由器将回退到默认路由配置。
+
+## 示例：基于时间的路由
+
+```javascript
+module.exports = async function(req, config) {
+  const hour = new Date().getHours();
+
+  // 工作时间使用更快的模型
+  if (hour >= 9 && hour <= 18) {
+    return 'groq,llama-3.3-70b-versatile';
+  }
+
+  // 非工作时间使用更强大的模型
+  return 'deepseek,deepseek-chat';
+};
+```
+
+## 示例：成本优化
+
+```javascript
+module.exports = async function(req, config) {
+  const userMessage = req.body.messages.find(m => m.role === 'user')?.content;
+
+  // 简单任务使用较便宜的模型
+  if (userMessage && userMessage.length < 100) {
+    return 'groq,llama-3.3-70b-versatile';
+  }
+
+  // 复杂任务使用默认模型
+  return null;
+};
+```
+
+## 示例：任务类型路由
+
+```javascript
+module.exports = async function(req, config) {
+  const userMessage = req.body.messages.find(m => m.role === 'user')?.content;
+
+  if (!userMessage) return null;
+
+  // 代码相关任务
+  if (userMessage.includes('代码') || userMessage.includes('code')) {
+    return 'deepseek,deepseek-coder';
+  }
+
+  // 解释任务
+  if (userMessage.includes('解释') || userMessage.includes('explain')) {
+    return 'openrouter,anthropic/claude-3.5-sonnet';
+  }
+
+  // 默认
+  return null;
+};
+```
+
+## 测试您的路由器
+
+通过检查日志来测试您的自定义路由器：
+
+```bash
+tail -f ~/.claude-code-router/claude-code-router.log
+```
+
+查找路由决策以查看正在选择哪个模型。
+
+## 子代理路由
+
+对于子代理内的路由，您必须在子代理提示词的**开头**包含 `<CCR-SUBAGENT-MODEL>provider,model</CCR-SUBAGENT-MODEL>` 来指定特定的提供商和模型。
+
+**示例：**
+
+```
+<CCR-SUBAGENT-MODEL>openrouter,anthropic/claude-3.5-sonnet</CCR-SUBAGENT-MODEL>
+请帮我分析这段代码是否存在潜在的优化空间...
+```
+
+## 下一步
+
+- [Agent](/zh/docs/advanced/agents) - 使用 Agent 扩展功能
+- [预设](/zh/docs/advanced/presets) - 使用预定义配置
--- a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/advanced/presets.md
+++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/advanced/presets.md
@@ -0,0 +1,174 @@
+---
+id: advanced/presets
+title: 预设配置
+sidebar_position: 3
+---
+
+# 预设配置
+
+使用预定义配置进行快速设置。
+
+## 什么是预设？
+
+预设是预配置的设置，包括针对特定用例优化的提供商配置、路由规则和转换器。
+
+## 可用预设
+
+### Development（开发）
+
+针对软件开发任务优化：
+- 快速响应时间
+- 适合代码生成
+- 成本效益高
+
+配置特点：
+- 使用轻量级模型处理后台任务
+- 为代码任务选择专用模型
+- 优化的超时设置
+
+### Research（研究）
+
+针对研究和分析优化：
+- 支持长上下文
+- 高质量响应
+- 更强大的模型
+
+配置特点：
+- 使用具有大上下文窗口的模型
+- 为分析任务选择高级模型
+- 较长的超时时间
+
+### Balanced（平衡）
+
+在速度和质量之间取得平衡：
+- 良好的通用性能
+- 合理的成本
+- 广泛的模型支持
+
+配置特点：
+- 混合使用快速和高质量的模型
+- 适合大多数日常任务
+- 平衡的成本效益
+
+## 使用预设
+
+使用 CLI 应用预设：
+
+```bash
+ccr preset apply development
+```
+
+列出可用预设：
+
+```bash
+ccr preset list
+```
+
+## 创建自定义预设
+
+您可以通过保存配置并稍后重新加载来创建自定义预设：
+
+```bash
+# 将当前配置保存为预设
+ccr preset save my-preset
+
+# 加载已保存的预设
+ccr preset apply my-preset
+```
+
+## 预设管理
+
+### 列出所有预设
+
+```bash
+ccr preset list
+```
+
+输出示例：
+
+```
+可用预设:
+  development    - 开发优化配置
+  research       - 研究优化配置
+  balanced       - 平衡配置
+  my-preset      - 自定义预设
+```
+
+### 应用预设
+
+```bash
+ccr preset apply <预设名称>
+```
+
+应用预设后，服务器将自动重启以加载新配置。
+
+### 删除预设
+
+```bash
+ccr preset delete <预设名称>
+```
+
+## 预设文件位置
+
+预设保存在：
+
+```
+~/.claude-code-router/presets/
+```
+
+每个预设都是一个 JSON 文件，包含完整的配置。
+
+## 预设文件示例
+
+```json
+{
+  "name": "development",
+  "description": "针对软件开发优化的配置",
+  "Providers": [
+    {
+      "name": "deepseek",
+      "api_base_url": "https://api.deepseek.com/chat/completions",
+      "api_key": "$DEEPSEEK_API_KEY",
+      "models": ["deepseek-chat", "deepseek-coder"]
+    },
+    {
+      "name": "groq",
+      "api_base_url": "https://api.groq.com/openai/v1/chat/completions",
+      "api_key": "$GROQ_API_KEY",
+      "models": ["llama-3.3-70b-versatile"]
+    }
+  ],
+  "Router": {
+    "default": "deepseek,deepseek-chat",
+    "background": "groq,llama-3.3-70b-versatile",
+    "think": "deepseek,deepseek-chat"
+  }
+}
+```
+
+## 导出和导入预设
+
+### 导出当前配置
+
+```bash
+ccr config show > my-config.json
+```
+
+### 导入配置
+
+```bash
+ccr config edit
+# 然后粘贴导入的配置
+```
+
+## 最佳实践
+
+1. **为不同项目创建预设**：为不同的工作流程创建专门的预设
+2. **版本控制**：将常用预设保存在版本控制中
+3. **文档化**：为自定义预设添加描述
+4. **测试**：在应用预设后验证配置
+
+## 下一步
+
+- [CLI 参考](/zh/docs/cli/start) - 完整的 CLI 命令参考
+- [配置](/zh/docs/config/basic) - 详细配置指南