# 8. 常见问题 (FAQ)

本章收集了用户在使用 Jarvis 过程中最常遇到的一些问题及其解决方案。

---

## Q1: Jarvis的提交命令(Ctrl+J)与VSCode的显示/隐藏快捷键冲突怎么办？

**A1:** Jarvis使用Ctrl+J作为提交命令，这与VSCode的显示/隐藏面板默认快捷键冲突。

**解决方案:**
修改VSCode快捷键配置:

1. 打开VSCode快捷键设置: `Ctrl+K Ctrl+S`
2. 搜索"Toggle Panel"
3. 右键点击当前快捷键绑定(Ctrl+J)，选择"Remove Keybinding"移除绑定
4. 或者可以重新绑定到其他快捷键组合(如Ctrl+`)

---

### Q2: 在多行输入模式下，为什么按回车键无法提交？

**A2:** 这是因为Jarvis在多行输入模式下，回车键被设计为输入换行符，以便用户可以方便地输入多行文本（例如粘贴代码、编写详细描述等）。

**解决方案:**
使用 `Ctrl + J` 快捷键来提交您的多行输入。这个快捷键提示通常会显示在多行输入框的上方。

---

### Q3: 如何使用自定义的 OpenAI 接口（API Base URL）？

**A3:** 通过设置环境变量 `OPENAI_API_BASE` 来指定自定义的 OpenAI 接口地址。Jarvis 默认使用官方地址 `https://api.openai.com/v1`，如果你使用代理或第三方服务，请将其设置为对应的 Base URL。

**设置方法示例:**

- Linux/macOS（Bash/Zsh）:
  - 临时设置（当前终端会话有效）:
    - `export OPENAI_API_BASE="https://your-proxy.example.com/v1"`
  - 永久设置（写入 shell 配置文件，如 ~/.bashrc 或 ~/.zshrc）:
    - 在配置文件中添加上述 `export` 行并重新加载或重启终端
- Windows PowerShell:
  - 当前会话: `"$env:OPENAI_API_BASE = 'https://your-proxy.example.com/v1'"`

**说明:**

- 变更环境变量后，重启 Jarvis 以使配置生效。
- `OPENAI_API_BASE` 仅影响 OpenAI 平台的请求地址，不影响其他平台。

---

### Q4: 如何向 OpenAI 客户端传入自定义的 HTTP 头（headers）？

**A4:** 设置环境变量 `OPENAI_EXTRA_HEADERS` 为一个 JSON 对象，Jarvis 会在初始化 OpenAI 客户端时将其作为默认 HTTP 头传入（若当前 SDK 版本不支持，则会给出警告但不影响基本功能）。

**示例:**

- Linux/macOS（推荐使用单引号包裹，避免转义问题）:
  - `export OPENAI_EXTRA_HEADERS='{"User-Agent":"Jarvis/1.0","X-Source":"jarvis"}'`
- Windows PowerShell:
  - `"$env:OPENAI_EXTRA_HEADERS = '{\"User-Agent\":\"Jarvis/1.0\",\"X-Source\":\"jarvis\"}'"`

**注意事项:**

- `OPENAI_EXTRA_HEADERS` 的值必须是 JSON 对象（形如 `{"Key":"Value"}`），键和值会按字符串处理。
- 如需取消自定义头，删除或清空该环境变量即可（Linux/macOS 可用 `unset OPENAI_EXTRA_HEADERS`）。
- 常见用途包括：自定义 User-Agent、添加追踪头（如 `X-Trace`）、满足企业代理的额外认证需求等。

---

### Q5: 如何配置多个模型并在不同场景下切换使用？

**A5:** Jarvis 支持通过 `llm_groups` 配置多个模型组，并通过 `llm_group` 切换。

**配置方法:**

在 `~/.jarvis/config.yaml` 中定义模型组：

```yaml
# 1. 定义可复用的模型配置
llms:
  gpt-5:
    platform: openai
    model: gpt-5
    max_input_token_count: 128000
    llm_config:
      openai_api_key: "your-api-key"
  claude-4:
    platform: openai
    model: claude-opus-4-5-20251101
    max_input_token_count: 200000
    llm_config:
      openai_api_key: "your-api-key"

# 2. 定义模型组
llm_groups:
  power:
    normal_llm: claude-4
    cheap_llm: gpt-5
  speed:
    normal_llm: gpt-5

# 3. 选择要使用的模型组
llm_group: power
```

**使用方式:**

- 通过配置文件：修改 `llm_group` 的值
- 通过命令行：使用 `-g` 或 `--llm-group` 参数临时切换，如 `jvs -g speed`

---

### Q6: 工具没有被加载或找不到工具怎么办？

**A6:** 工具加载失败通常由以下原因导致：

**可能原因和解决方案:**

1. **文件名与工具名不匹配**
   - 检查工具文件名（不含 `.py` 后缀）是否与类中的 `name` 属性完全一致
   - 例如：文件 `my_tool.py` 中的类必须有 `name = "my_tool"`

2. **工具文件位置不正确**
   - 检查工具文件是否在正确的目录：
     - 用户工具：`~/.jarvis/tools/`
     - 额外目录：`tool_load_dirs` 配置指定的目录
     - 中心工具库：`central_tool_repo` 配置指定的仓库

3. **工具类缺少必需属性**
   - 确保工具类包含：`name`、`description`、`parameters` 属性和 `execute` 方法

4. **工具加载目录配置错误**
   - 检查 `tool_load_dirs` 配置是否正确（列表格式）
   - 检查路径是否正确（支持 `~` 和环境变量展开）

5. **查看工具列表**
   - 使用 `jt list` 命令查看所有已加载的工具
   - 使用 `jt list --detailed` 查看详细信息

---

### Q7: 规则没有被加载或规则不生效怎么办？

**A7:** 规则加载问题可能由以下原因导致：

**可能原因和解决方案:**

1. **规则文件位置不正确**
   - 全局规则：`~/.jarvis/rules` 或 `~/.jarvis/rules/<规则名>`
   - 项目规则：`.jarvis/rules` 或 `.jarvis/rules/<规则名>`
   - 命名规则：`.jarvis/rules.yaml` 或 `~/.jarvis/rules.yaml`

2. **规则名称不匹配**
   - 使用 `--rule-names` 时，确保规则名称与 YAML 文件中的键名或文件名完全匹配（区分大小写）

3. **规则加载优先级**
   - 检查是否有同名规则被高优先级来源覆盖
   - 优先级顺序：中心规则仓库 > 项目规则目录 > 项目 rules.yaml > 配置的规则目录 > 全局 rules.yaml > 内置规则

4. **规则格式错误**
   - YAML 格式的规则文件必须符合 YAML 语法
   - 独立规则文件应为纯文本格式

5. **中心规则仓库未配置**
   - 如果使用中心规则仓库，确保 `central_rules_repo` 配置正确
   - 检查仓库是否已成功克隆到 `~/.jarvis/central_rules_repo`

---

### Q8: 如何配置和使用自定义工具组？

**A8:** 通过 `tool_groups` 配置可以定义不同的工具集合，并在需要时切换。

**配置方法:**

```yaml
# ~/.jarvis/config.yaml

# 1. 定义工具组
tool_groups:
  - coding: # 代码开发组
      use: # 只使用这些工具
        - execute_script
        - read_code
        - edit_file
        - save_memory
  - document: # 文档处理组
      use:
        - save_memory
        - retrieve_memory
  - restricted: # 受限组（只读）
      use:
        - read_code

# 2. 选择要使用的工具组
tool_group: coding
```

**使用方式:**

- 通过配置文件：修改 `tool_group` 的值
- 通过命令行：使用 `-G` 或 `--tool-group` 参数临时切换，如 `jvs -G restricted`

**注意事项:**

- 如果配置了 `use` 列表，则只有列表中的工具可用
- 如果配置了 `dont_use` 列表，则排除列表中的工具
- 如果同时配置了 `use` 和 `dont_use`，`use` 优先级更高
- 默认情况下（不设置工具组），所有工具都可用

---

### Q9: 如何配置 MCP 工具？

**A9:** MCP (Model Context Protocol) 工具通过 `mcp` 配置列表进行配置。

**配置方法:**

在 `~/.jarvis/config.yaml` 中添加 `mcp` 配置：

```yaml
mcp:
  # stdio 类型：本地命令行程序
  - type: "stdio"
    name: "my_cli_tools"
    command: "/path/to/your/tool_program"
    args: ["--json-rpc"]
    env:
      CUSTOM_VAR: "value"
    enable: true

  # sse 类型：Server-Sent Events 远程服务
  - type: "sse"
    name: "realtime_service"
    base_url: "https://api.example.com/mcp"
    auth_token: "your-secret-token"
    headers:
      X-Custom-Header: "value"
    enable: true

  # streamable 类型：流式 HTTP 服务
  - type: "streamable"
    name: "large_file_processor"
    base_url: "https://stream.example.com/api"
    auth_token: "your-secret-token"
    endpoint_path: "mcp" # 可选，默认为 "mcp"
    timeout: [10, 300] # 可选，[连接超时, 读取超时] 秒
    enable: true
```

**注意事项:**

- 每个 MCP 配置必须包含 `type` 字段
- `name` 字段可选，但建议为每个配置指定唯一名称
- `enable` 字段可选，默认为 `true`
- **sse/streamable 类型**：必须提供 `base_url`，可选 `auth_token`、`headers`、`endpoint_path`（仅 streamable）、`timeout`（仅 streamable）
- **stdio 类型**：必须提供 `command`，可选 `args`、`env`
- 配置后重启 Jarvis 以使配置生效
- 可以通过 `jt list` 查看 MCP 工具是否成功加载

---

### Q10: 如何配置中心仓库（方法论、工具、规则）？

**A10:** 中心仓库配置允许团队共享资源，支持自动克隆和每日更新。

**配置方法:**

在 `~/.jarvis/config.yaml` 中添加：

```yaml
# 中心方法论仓库
central_methodology_repo: "https://github.com/your-org/jarvis-methodologies.git"

# 中心工具仓库
central_tool_repo: "https://github.com/your-org/jarvis-tools.git"

# 中心规则仓库
central_rules_repo: "https://github.com/your-org/jarvis-rules.git"
```

**工作机制:**

1. 首次使用时，Jarvis 会自动克隆仓库到数据目录
2. 每日启动时自动执行 `git pull` 更新最新内容
3. 资源按优先级加载（中心仓库优先级最高）

**分享资源到中心仓库:**

```bash
# 分享方法论
jarvis --share-methodology

# 分享工具
jarvis --share-tool
```

**注意事项:**

- 中心仓库支持本地目录路径或 Git URL
- 如果是 Git URL，会自动克隆到 `~/.jarvis/` 目录下
- 如果是本地目录，将直接使用该目录

---

### Q11: 如何在新配置方式（llm_groups/llms）和旧配置方式（platform/model）之间迁移？

**A11:** Jarvis 支持两种配置方式，推荐使用新的配置方式以获得更好的灵活性。

**新配置方式（推荐）:**

```yaml
llms:
  my_model:
    platform: openai
    model: gpt-5
    max_input_token_count: 128000
    llm_config:
      openai_api_key: "your-key"

llm_groups:
  default:
    normal_llm: my_model

llm_group: default
```

**旧配置方式（仍支持）:**

```yaml
platform: openai
model: gpt-5
ENV:
  OPENAI_API_KEY: "your-key"
```

**迁移步骤:**

1. 在 `llms` 中定义模型配置
2. 在 `llm_groups` 中创建模型组，引用 `llms` 中的配置
3. 设置 `llm_group` 选择要使用的组
4. 旧的 `platform` 和 `model` 配置可以保留作为后备，但建议迁移到新方式

**注意:** 新配置方式提供了更灵活的模型管理能力，支持定义多个模型组并在不同场景下切换。

---

### Q12: 如何调试 Jarvis 的行为？

**A12:** Jarvis 提供了多种调试选项来帮助诊断问题。

**调试方法:**

1. **打印完整提示（Prompt）**

   ```yaml
   # ~/.jarvis/config.yaml
   print_prompt: true
   ```

   启用后会在终端打印发送给 LLM 的完整提示，用于调试模型输入。

2. **打印错误回溯**

   ```yaml
   # ~/.jarvis/config.yaml
   print_error_traceback: true
   ```

   启用后会在错误输出时自动打印完整的调用栈。

3. **查看工具列表**

   ```bash
   # 查看所有工具
   jt list

   # 查看详细信息
   jt list --detailed
   ```

4. **查看工具使用统计**

   ```bash
   jt stat
   ```

5. **查看配置**

   ```bash
   # 编辑配置文件
   jvs -e

   # 或直接查看
   cat ~/.jarvis/config.yaml
   ```

6. **查看日志**
   - 日志文件位置：`~/.jarvis/logs/` 或环境变量 `JARVIS_LOG_DIR` 指定的目录
   - 每次会话会生成独立的日志文件

---

### Q13: 如何解决"工具执行确认"频繁弹出问题？

**A13:** 如果启用了 `execute_tool_confirm`，每次工具执行前都会要求确认。

**解决方案:**

1. **禁用工具执行确认**

   ```yaml
   # ~/.jarvis/config.yaml
   execute_tool_confirm: false
   ```

2. **使用工具组限制工具**
   通过配置 `tool_groups`，只启用必要的工具，减少需要确认的工具数量。

3. **使用非交互模式**
   在自动化场景中使用 `-n` 或 `--non-interactive` 参数，会自动处理确认。

**注意:** `execute_tool_confirm` 是一个安全特性，禁用前请确保您了解将要执行的命令。

---

### Q14: 如何设置 OpenAI 的推理努力程度（Reasoning Effort）？

**A14:** OpenAI 的 o1 系列模型支持通过 `reasoning_effort` 参数控制推理努力程度，影响模型的思考和回答质量。

**设置方法:**

通过环境变量设置：

- Linux/macOS:
  - `export OPENAI_REASONING_EFFORT="medium"`
- Windows PowerShell:
  - `$env:OPENAI_REASONING_EFFORT = "medium"`

或通过配置文件设置：

```yaml
# ~/.jarvis/config.yaml
llms:
  o1-model:
    platform: openai
    model: o1-preview
    llm_config:
      openai_api_key: "your-api-key"
      openai_reasoning_effort: "medium" # 可选值: low, medium, high, xhigh
```

**可选值:**

- `low`: 最低推理努力，响应速度快
- `medium`: 中等推理努力（默认）
- `high`: 高推理努力，更深入思考
- `xhigh`: 最高推理努力，适用于复杂问题

---

### Q15: 如何使用自定义的 Anthropic API 地址？

**A15:** 类似于 OpenAI 的 `OPENAI_API_BASE`，您可以通过设置环境变量 `ANTHROPIC_BASE_URL` 来指定自定义的 Anthropic API 地址。

**设置方法:**

- Linux/macOS:
  - `export ANTHROPIC_BASE_URL="https://your-proxy.example.com/v1"`
- Windows PowerShell:
  - `$env:ANTHROPIC_BASE_URL = "https://your-proxy.example.com/v1"`

或通过配置文件设置：

```yaml
# ~/.jarvis/config.yaml
llms:
  claude-model:
    platform: openai
    model: claude-opus-4-5-20251101
    llm_config:
      anthropic_api_key: "your-api-key"
      anthropic_base_url: "https://your-proxy.example.com/v1"
```

**说明:**

- 变更环境变量或配置后，重启 Jarvis 以使配置生效
- `ANTHROPIC_BASE_URL` 仅影响 Anthropic 平台的请求地址

---

### Q16: 如何配置 Web Gateway 的密码认证？

**A16:** Web Gateway 支持通过配置文件或环境变量设置密码认证，保护您的 Jarvis Web 界面。

**设置方法:**

#### 方法1：通过环境变量（推荐）

```bash
# Linux/macOS
export JARVIS_GATEWAY_PASSWORD="your-secure-password"

# Windows PowerShell
$env:JARVIS_GATEWAY_PASSWORD = "your-secure-password"
```

#### 方法2：通过配置文件

```yaml
# ~/.jarvis/config.yaml
gateway_auth:
  enable: true
  password: "your-secure-password"
  allow_unset: false # 禁止未设置密码时访问
```

**说明:**

- 环境变量的优先级高于配置文件
- 设置密码后，访问 Web Gateway 时需要输入密码
- 建议使用强密码并定期更换

---
