sinapse-ai 5.0.8 → 6.0.1

package/docs/zh/guides/llm-routing.md

@@ -1,306 +0,0 @@
-# LLM 路由指南
-
-> [EN](../../guides/llm-routing.md) | [PT](../../pt/guides/llm-routing.md) | [ES](../../es/guides/llm-routing.md) | **ZH**
-
----
-
-**版本:** 1.0.0
-**更新:** 2025-12-14
-
-Claude Code 的成本效益 LLM 路由。在保持完整功能的同时节省高达 99% 的 API 成本。
-
----
-
-## 概述
-
-LLM 路由为不同用例提供两个命令:
-
-| 命令          | 提供者            | 成本           | 用例                   |
-| ------------- | ----------------- | -------------- | ---------------------- |
-| `claude-max`  | Claude Max (OAuth) | 订阅           | 高级体验，复杂任务      |
-| `claude-free` | DeepSeek          | ~$0.14/M tokens | 开发，测试，简单任务    |
-
----
-
-## 快速开始
-
-### 安装
-
-**选项 1: 如果您已克隆 sinapse-ai**
-```bash
-# 从 sinapse-ai 目录
-node .sinapse-ai/infrastructure/scripts/llm-routing/install-llm-routing.js
-```
-
-**选项 2: 全新安装**
-```bash
-# 克隆仓库
-git clone https://github.com/SinapseAI/sinapse-ai.git
-cd sinapse-ai
-
-# 运行安装程序
-node .sinapse-ai/infrastructure/scripts/llm-routing/install-llm-routing.js
-```
-
-### 设置 DeepSeek API 密钥
-
-1. 在此获取 API 密钥: <https://platform.deepseek.com/api_keys>
-2. 添加到项目的 `.env` 文件:
-
-```bash
-DEEPSEEK_API_KEY=sk-your-key-here
-```
-
-### 使用
-
-```bash
-# 高级 Claude 体验 (使用您的 Claude Max 订阅)
-claude-max
-
-# 成本效益开发 (使用 DeepSeek ~$0.14/M tokens)
-claude-free
-```
-
----
-
-## 命令
-
-### claude-max
-
-通过 OAuth 使用您的 Claude Max 订阅 (claude.ai 登录)。
-
-**功能:**
-- 完整 Claude 能力
-- 无需 API 密钥
-- 使用现有 Claude 登录
-- 最适合复杂推理任务
-
-**使用:**
-```bash
-claude-max
-```
-
-**何时使用:**
-- 复杂代码分析
-- 架构决策
-- 需要高准确性的任务
-- 生产关键工作
-
----
-
-### claude-free
-
-使用 DeepSeek API 和 Anthropic 兼容端点。
-
-**功能:**
-- 工具调用支持 ✅
-- 流式传输支持 ✅
-- ~99% 成本降低
-- 项目 `.env` 文件支持
-
-**使用:**
-```bash
-claude-free
-```
-
-**何时使用:**
-- 开发和测试
-- 简单代码任务
-- 学习和实验
-- 高量操作
-
----
-
-## 成本比较
-
-| 提供者       | 输入 Tokens   | 输出 Tokens   | 每月 (1M tokens) |
-| ------------ | ------------- | ------------- | ---------------- |
-| Claude API   | $15.00/M      | $75.00/M      | $90.00           |
-| Claude Max   | 包含          | 包含          | $20/月           |
-| **DeepSeek** | **$0.07/M**   | **$0.14/M**   | **$0.21**        |
-
-**使用 DeepSeek 的节省:** 与 Claude API 相比高达 99.7%
-
----
-
-## 配置
-
-### API 密钥来源
-
-`claude-free` 按此顺序查找 DeepSeek API 密钥:
-
-1. **项目 `.env` 文件** (推荐)
-   ```bash
-   # 项目根目录的 .env
-   DEEPSEEK_API_KEY=sk-your-key-here
-   ```
-
-2. **环境变量**
-   ```bash
-   # Windows
-   setx DEEPSEEK_API_KEY "sk-your-key-here"
-
-   # Unix (添加到 ~/.bashrc 或 ~/.zshrc)
-   export DEEPSEEK_API_KEY="sk-your-key-here"
-   ```
-
-### 安装位置
-
-| 操作系统      | 安装目录                      |
-| ------------- | ----------------------------- |
-| Windows       | `%APPDATA%\npm\`              |
-| macOS/Linux   | `/usr/local/bin/` 或 `~/bin/` |
-
----
-
-## 工作原理
-
-### claude-max
-1. 清除所有替代提供者设置
-2. 使用 Claude 的默认 OAuth 认证
-3. 使用您的 Max 订阅启动 Claude Code
-
-### claude-free
-1. 搜索 `.env` 文件 (当前目录 → 父目录)
-2. 从 `.env` 或环境加载 `DEEPSEEK_API_KEY`
-3. 设置 DeepSeek 的 Anthropic 兼容端点
-4. 使用 DeepSeek 后端启动 Claude Code
-
-**DeepSeek 端点:**
-```text
-https://api.deepseek.com/anthropic
-```
-
-此端点提供:
-- Anthropic API 兼容性
-- 工具/函数调用支持
-- 流式响应
-
-### 安全说明: 权限绕过
-
-`claude-max` 和 `claude-free` 命令默认使用 `--dangerously-skip-permissions` 标志。这:
-
-- **跳过确认提示** 用于文件操作、命令执行等
-- **应仅在受信任的仓库/环境中使用**
-- **不推荐用于不受信任的代码库**
-
-每次运行这些命令时会显示警告。如果您更喜欢交互式确认，请直接运行 `claude` 而不是使用路由命令。
-
----
-
-## 故障排除
-
-### 命令未找到
-
-**Windows:**
-```powershell
-# 检查 npm 全局是否在 PATH 中
-echo $env:PATH | Select-String "npm"
-
-# 如果没有，添加它:
-$env:PATH += ";$env:APPDATA\npm"
-```
-
-**Unix:**
-```bash
-# 检查 PATH
-echo $PATH | grep -E "(local/bin|~/bin)"
-
-# 如果 ~/bin 不在 PATH 中，添加到 ~/.bashrc:
-export PATH="$HOME/bin:$PATH"
-```
-
-### DEEPSEEK_API_KEY 未找到
-
-1. 验证 `.env` 文件存在于项目根目录
-2. 检查密钥格式: `DEEPSEEK_API_KEY=sk-...`
-3. `=` 周围没有空格
-4. 值周围不需要引号
-
-### API 错误
-
-| 错误               | 原因             | 解决方案                      |
-| ------------------ | ---------------- | ----------------------------- |
-| 401 Unauthorized   | 无效 API 密钥    | 在 DeepSeek 仪表盘验证密钥     |
-| 429 Rate Limited   | 请求太多         | 等待并重试                     |
-| Connection refused | 网络问题         | 检查互联网连接                 |
-
-### 工具调用不工作
-
-DeepSeek 的 `/anthropic` 端点支持工具调用。如果工具不工作:
-1. 验证端点是 `https://api.deepseek.com/anthropic`
-2. 检查 API 密钥有足够额度
-3. 先尝试不带工具的简单测试
-
----
-
-## 高级配置
-
-### 自定义模型
-
-如果需要不同模型，编辑模板文件:
-
-**Windows:** `.sinapse-ai/infrastructure/scripts/llm-routing/templates/claude-free.cmd`
-**Unix:** `.sinapse-ai/infrastructure/scripts/llm-routing/templates/claude-free.sh`
-
-更改:
-```bash
-export ANTHROPIC_MODEL="deepseek-chat"
-```
-
-### 环境变量
-
-| 变量                 | 描述          | 默认值                                |
-| -------------------- | ------------- | ------------------------------------- |
-| `ANTHROPIC_BASE_URL` | API 端点      | `https://api.deepseek.com/anthropic`  |
-| `ANTHROPIC_API_KEY`  | API 密钥      | 来自 DEEPSEEK_API_KEY                  |
-| `ANTHROPIC_MODEL`    | 模型名称      | `deepseek-chat`                       |
-| `API_TIMEOUT_MS`     | 请求超时      | `600000` (10 分钟)                    |
-
----
-
-## 卸载
-
-### Windows
-```powershell
-Remove-Item "$env:APPDATA\npm\claude-free.cmd"
-Remove-Item "$env:APPDATA\npm\claude-max.cmd"
-```
-
-### Unix
-```bash
-rm /usr/local/bin/claude-free
-rm /usr/local/bin/claude-max
-# 或如果安装在 ~/bin:
-rm ~/bin/claude-free
-rm ~/bin/claude-max
-```
-
----
-
-## 相关资源
-
-- **工具定义:** `.sinapse-ai/infrastructure/tools/cli/llm-routing.yaml`
-- **安装脚本:** `.sinapse-ai/infrastructure/scripts/llm-routing/install-llm-routing.js`
-- **任务定义:** `.sinapse-ai/development/tasks/setup-llm-routing.md`
-- **DeepSeek API:** <https://platform.deepseek.com/api_keys>
-
----
-
-## 常见问题
-
-**Q: DeepSeek 和 Claude 一样好吗?**
-A: DeepSeek 对大多数编码任务表现出色，但在复杂问题上可能不及 Claude 的推理能力。重要工作使用 `claude-max`。
-
-**Q: 我可以在同一会话中使用两个命令吗?**
-A: 可以! 每个命令设置自己的环境。您可以在它们之间切换。
-
-**Q: claude-free 可以离线工作吗?**
-A: 不能，它需要互联网访问来连接 DeepSeek 的 API。
-
-**Q: 我的 API 密钥安全吗?**
-A: 密钥从 `.env` 文件 (不要提交!) 或环境变量加载。永远不要硬编码密钥。
-
----
-
-*由 SINAPSE Framework 生成 - Story 6.7*

package/docs/zh/guides/mcp/desktop-commander.md

@@ -1,368 +0,0 @@
-# Desktop Commander MCP
-
-> **EN** | **ZH**
-
----
-
-使用 Desktop Commander MCP 服务器和 Claude Code 的指南，用于高级终端和进程管理功能。
-
-**版本：** 1.0.0
-**最后更新：** 2026-01-28
-
----
-
-## 概述
-
-Desktop Commander 是一个 MCP 服务器，使用高级功能扩展 Claude Code，用于本地环境管理。它提供 Claude Code 的本机工具无法做到的功能，使其对某些工作流程至关重要。
-
-### 何时使用 Desktop Commander
-
-| 用例                            | 原生 Claude Code | Desktop Commander |
-| ------------------------------- | ---------------- | ----------------- |
-| 持久会话（SSH、REPL）           | 不支持           | **推荐**          |
-| 交互式进程                      | 限制             | **推荐**          |
-| 模糊文件编辑                    | 不支持           | **推荐**          |
-| 读取文件尾部（负偏移）          | 不支持           | **推荐**          |
-| 内存中代码执行                  | 不支持           | **推荐**          |
-| 简单文件操作                    | **首选**         | 较慢              |
-| Git 操作                        | **首选**         | 不必要            |
-| 文件搜索（Glob、Grep）          | **首选**         | 不必要            |
-
----
-
-## 能力比较
-
-### Desktop Commander 可以做而 Claude Code 不能做的事
-
-| 功能                     | Claude Code 原生                           | Desktop Commander                            |
-| ------------------------ | ------------------------------------------ | -------------------------------------------- |
-| **持久会话**             | Shell 状态在调用之间不持久（仅工作目录）   | 维护活动会话（SSH、数据库、REPL）            |
-| **内存中代码执行**       | 需要 Write → Bash                          | 直接 REPL 执行（Python、Node.js、R）         |
-| **模糊编辑**             | Edit 需要 old_string 精确匹配               | 智能回退并模糊搜索                          |
-| **负偏移（tail）**       | Read 仅具有正偏移                          | 从文件末尾读取（如 Unix tail）                |
-| **交互式进程**           | 限制（后台无 stdin）                      | 双向 stdin/stdout                            |
-| **动态配置**             | 需要重启                                   | 动态更改 shell、目录、阻止的命令              |
-| **审计日志**             | ~/.claude.json 中的基本信息                | 完整的工具历史和使用统计                      |
-
-### Claude Code 原生足够的地方
-
-| 功能                     | Claude Code 原生        | 注释                           |
-| ------------------------ | ----------------------- | ------------------------------ |
-| **分页搜索**             | Grep 有 `head_limit` 和 `offset` | 已经能够流式传输 |
-| **多会话管理**           | Task 工具 + TaskOutput + /tasks | 不同的方法但功能齐全 |
-| **CSV/JSON 分析**        | Read + Bash with jq/python | 对大多数情况都适用 |
-
----
-
-## 安装
-
-### 前置要求
-
-- Node.js 18+
-- Claude Code CLI 已安装
-- MCP 支持已启用
-
-### 设置
-
-```bash
-# 全局安装 desktop-commander
-npm install -g @anthropic/desktop-commander
-
-# 或添加到 Claude Code MCP 配置
-claude mcp add desktop-commander
-```
-
-### 配置
-
-添加到 `~/.claude.json`：
-
-```json
-{
-  "mcpServers": {
-    "desktop-commander": {
-      "command": "npx",
-      "args": ["-y", "@anthropic/desktop-commander"]
-    }
-  }
-}
-```
-
----
-
-## 可用工具
-
-### 终端管理
-
-| 工具              | 描述                       |
-| ----------------- | -------------------------- |
-| `execute_command` | 使用持久会话运行 shell 命令 |
-| `read_output`     | 从运行进程读取输出          |
-| `send_input`      | 向交互式进程发送输入        |
-| `force_terminate` | 杀死运行的进程              |
-| `list_sessions`   | 列出所有活动会话            |
-| `list_processes`  | 列出运行的进程              |
-
-### 文件操作
-
-| 工具             | 描述                               |
-| ---------------- | ---------------------------------- |
-| `read_file`      | 读取文件，支持负偏移（tail）       |
-| `write_file`     | 写入文件内容                       |
-| `edit_block`     | 使用模糊匹配回退编辑               |
-| `search_files`   | 搜索带有流式传输/分页              |
-| `get_file_info`  | 获取文件元数据                     |
-| `list_directory` | 列出目录内容                       |
-
-### 代码执行
-
-| 工具           | 描述                            |
-| -------------- | ------------------------------- |
-| `execute_code` | 内存中运行代码（Python、Node.js、R） |
-| `create_repl`  | 创建持久 REPL 会话              |
-| `repl_execute` | 在现有 REPL 中执行              |
-
-### 配置
-
-| 工具               | 描述                  |
-| ------------------ | --------------------- |
-| `get_config`       | 获取当前配置          |
-| `set_config_value` | 动态更新配置          |
-
----
-
-## 使用示例
-
-### 持久 SSH 会话
-
-```
-# 创建 SSH 会话
-execute_command: ssh user@server.com
-
-# 向会话发送命令
-send_input: ls -la
-read_output: [session_id]
-
-# 保持会话活动以进行多次交互
-send_input: cd /var/log
-send_input: tail -f syslog
-```
-
-### 内存中 Python 分析
-
-```
-# 执行 Python 而不创建文件
-execute_code:
-  language: python
-  code: |
-    import pandas as pd
-    df = pd.read_csv('/path/to/data.csv')
-    print(df.describe())
-    print(df.head(10))
-```
-
-### 模糊文件编辑
-
-```
-# 使用近似匹配编辑（当精确匹配失败时）
-edit_block:
-  file_path: /path/to/file.py
-  old_text: "def process_data(data)"  # 近似匹配
-  new_text: "def process_data(data: dict) -> dict"
-  fuzzy: true
-```
-
-### 读取文件尾部
-
-```
-# 读取大日志文件的最后 100 行
-read_file:
-  path: /var/log/application.log
-  offset: -100  # 负 = 从末尾
-  lines: 100
-```
-
-### 交互式 REPL
-
-```
-# 创建 Node.js REPL
-create_repl:
-  language: nodejs
-
-# 在 REPL 中执行（维护状态）
-repl_execute: const data = require('./config.json')
-repl_execute: Object.keys(data).length
-repl_execute: data.settings.enabled
-```
-
----
-
-## 最佳实践
-
-### 1. 尽可能使用原生工具
-
-Desktop Commander 增加延迟。优先使用原生工具：
-
-```
-# 好的 - 使用原生 Read
-Read 工具用于简单的文件读取
-
-# 好的 - 使用原生 Bash
-Bash 工具用于快速命令
-
-# 好的 - 使用原生 Grep
-Grep 工具用于文件搜索
-```
-
-### 2. 对以下情况使用 Desktop Commander
-
-```
-# 持久会话
-- SSH 连接
-- 数据库连接（psql、mysql、mongo shell）
-- REPL 会话（python、node、irb）
-
-# 交互式进程
-- 长时间运行的命令，监控输出
-- 需要 stdin 输入的进程
-
-# 高级文件操作
-- 需要 tail 的大文件（负偏移）
-- 不精确匹配的编辑（模糊）
-```
-
-### 3. 会话管理
-
-```
-# 创建新会话前始终列出会话
-list_sessions
-
-# 清理未使用的会话
-force_terminate: [old_session_id]
-
-# 为清晰起见命名会话
-execute_command:
-  command: ssh prod-server
-  session_name: prod-ssh
-```
-
-### 4. 错误处理
-
-```
-# 发送输入前检查进程状态
-list_processes
-
-# 为长时间运行的操作使用超时
-execute_command:
-  command: long-running-task
-  timeout: 300000  # 5 分钟
-```
-
----
-
-## 与 SINAPSE 集成
-
-### 工具选择优先级
-
-根据 `.claude/rules/mcp-usage.md`：
-
-| 任务           | 使用这个             | 不使用 desktop-commander |
-| -------------- | -------------------- | ----------------------- |
-| 读取本地文件   | `Read` 工具          | 较慢                    |
-| 写入本地文件   | `Write` / `Edit` 工具 | 较慢                    |
-| 运行 shell 命令 | `Bash` 工具         | 除非需要持久会话         |
-| 搜索文件       | `Glob` 工具          | 较慢                    |
-| 搜索内容       | `Grep` 工具          | 较慢                    |
-
-### 何时需要 Desktop Commander
-
-1. 用户明确要求持久会话
-2. 任务需要 REPL 执行
-3. 需要读取大文件的尾部
-4. 编辑需要模糊匹配
-5. 带有 stdin/stdout 的交互式进程
-
-### 代理职责
-
-| 代理              | Desktop Commander 用例                |
-| ----------------- | ------------------------------------- |
-| **@dev**          | REPL 会话、调试、实时编码             |
-| **@devops**       | SSH 会话、服务器管理、日志分析        |
-| **@data-engineer** | 数据分析 REPL、数据库连接            |
-| **@qa**           | 交互式测试、进程监控                  |
-
----
-
-## 故障排除
-
-### 会话未持久化
-
-```bash
-# 检查 desktop-commander 是否正在运行
-claude mcp status
-
-# 重启 MCP 服务器
-claude mcp restart desktop-commander
-```
-
-### 模糊编辑不工作
-
-```
-# 确保设置了 fuzzy 标志
-edit_block:
-  fuzzy: true
-  threshold: 0.8  # 调整相似度阈值
-```
-
-### 进程超时
-
-```
-# 增加长操作的超时时间
-execute_command:
-  timeout: 600000  # 10 分钟
-
-# 或使用后台模式
-execute_command:
-  background: true
-```
-
-### 无法连接到服务器
-
-```bash
-# 检查 MCP 配置
-cat ~/.claude.json | grep -A 10 desktop-commander
-
-# 验证 npm 包
-npm list -g @anthropic/desktop-commander
-
-# 如需要重新安装
-npm install -g @anthropic/desktop-commander@latest
-```
-
----
-
-## 相关文档
-
-- [Docker Gateway 教程](./docker-gateway-tutorial.md)
-- [MCP 全局设置指南](../mcp-global-setup.md)
-- [Docker MCP 设置](../../docker-mcp-setup.md)
-- [MCP 使用规则](../../../.claude/rules/mcp-usage.md)
-- [代理工具集成](../../architecture/agent-tool-integration-guide.md)
-
----
-
-## 总结
-
-| 特性               | 原生 Claude Code | Desktop Commander |
-| ------------------- | --------------- | --------------------
-| 速度                | 快              | 较慢（MCP 开销）  |
-| 持久会话            | 否              | 是                |
-| 内存中执行          | 否              | 是                |
-| 模糊编辑            | 否              | 是                |
-| 负偏移              | 否              | 是                |
-| 交互式进程          | 限制            | 完全              |
-
-**经验法则：** 默认使用原生工具。仅当需要其独特功能时才切换到 Desktop Commander。
-
----
-
-_Desktop Commander MCP 指南 v1.0.0 - SINAPSE 框架_