# 4. 使用指南

本章是 Jarvis 的实用操作手册，将详细介绍主要命令的用法、参数和常见场景示例。

在阅读本章之前，我们建议您先通过 [快速开始](./2.快速开始.md) 了解 Jarvis 的基本安装和配置。

## 4.1 首次运行配置

在您第一次运行任何 `jarvis` 命令之前，需要进行一次简单的配置，以连接到 AI 大模型平台。

### 快速配置（推荐）

我们提供了交互式配置命令 `jqc` (jarvis-quick-config)，它可以引导您快速完成配置：

```bash
# 运行交互式配置向导
jqc
```

该命令会引导您：

1. 选择 AI 平台（OpenAI 或 Claude）
2. 输入 API 基础 URL 和 API 密钥
3. 选择可用的模型
4. 配置 Normal/Smart/Cheap 模型
5. 测试 API 连接性
6. 自动保存配置到 `~/.jarvis/config.yaml`

### 生成配置文件

首次运行任何 jarvis 命令（例如 `jarvis` 或 `jpm info`），系统会自动在您的用户主目录下创建 `~/.jarvis/` 文件夹，以及一个默认的配置文件 `config.yaml`。

### 编辑配置文件

打开 `~/.jarvis/config.yaml` 文件。您会看到类似如下的结构：

**推荐使用新的配置方式（llm_groups 和 llms）**：

```yaml
# yaml-language-server: $schema=https://raw.githubusercontent.com/skyfireitdiy/Jarvis/main/docs/schema/config.schema.json

# ====== 基础配置 ======
# 设置默认使用的模型组
llm_group: default

# 多行输入提交快捷键配置（可选）
# 支持数组格式或字符串格式（逗号分隔）
# 默认值为 Ctrl+J 和 Ctrl+]
# 常用快捷键：c-j (Ctrl+J), c-] (Ctrl+]), c-enter (Ctrl+Enter)
submit_keys:
  - c-j
  - c-]

# ====== 模型组配置 ======
# 可以定义多个模型组，通过llm_group切换
llm_groups:
  default: # 默认模型组
    normal_llm: gpt-5 # 引用下面llms中定义的模型
    # 可选配置廉价模型和智能模型
    # cheap_llm: gpt-3.5-turbo
    # smart_llm: gpt-5

# ====== 模型定义 ======
llms:
  gpt-5:
    platform: openai # 平台类型
    model: gpt-5 # 模型名称
    max_input_token_count: 128000 # 模型最大输入token数

    # 模型特定配置 (llm_config)
    llm_config:
      openai_api_key: "your-api-key-here" # 替换为你的API密钥
      openai_api_base: "https://api.openai.com/v1" # API基础地址，可用于代理
      openai_extra_headers: '{"X-Source": "jarvis"}' # 额外的HTTP头（可选）

# ====== 环境变量配置 ======
# 旧版配置方式（仍支持，但推荐使用上面的 llm_config）
ENV:
  # OpenAI
  OPENAI_API_KEY: ""
  OPENAI_API_BASE: ""
```

**旧版配置方式（仍支持）**：

```yaml
# yaml-language-server: $schema=...
# ... 其他配置 ...
ENV:
  # OpenAI
  OPENAI_API_KEY: ""
  OPENAI_API_BASE: ""

  # Claude
  ANTHROPIC_API_KEY: ""
  ANTHROPIC_API_BASE: ""
```

### 填入凭证

**使用新配置方式（推荐）**：

1. 在 `llms` 部分定义您的模型，并在 `llm_config` 中填入相应的凭证。

**使用旧配置方式**：

直接在 `ENV` 部分填入您的 API Key 或其他凭证信息即可。

> **注意**: 新版本推荐使用 `llm_groups` 和 `llms` 配置方式，它提供了更灵活的模型管理能力。`ENV` 配置方式仍然支持，但建议迁移到新的配置方式。

保存文件后，Jarvis 便已配置完成，可以正常使用了。

## 4.2 提示词自动优化

Jarvis 提供了系统提示词自动优化功能，可以根据您的具体任务需求，自动优化 Agent 的系统提示词，使其更加贴合任务场景，提升任务执行效率。

### 功能说明

当您使用 `-o` 或 `--optimize-system-prompt` 参数时，系统会在首次运行时：

1. **分析用户需求**：使用 LLM 分析您的任务描述，理解任务意图和场景
2. **优化系统提示词**：在保持原有核心功能和架构不变的前提下，有针对性地增强或调整相关部分的描述
3. **应用优化结果**：将优化后的提示词应用到 Agent，使其更好地理解和执行您的任务

### 使用场景

- **特定领域任务**：当任务涉及特定领域（如代码开发、数据分析、安全审计等）时，优化后的提示词会强调相关的最佳实践
- **复杂任务定制**：对于复杂的多阶段任务，优化后的提示词能够更好地指导 Agent 的执行策略
- **任务场景适配**：根据不同的任务场景（如代码生成、代码审查、问题诊断等），自动调整提示词的重点

### 使用示例

```bash
# 通用代理启用提示词优化
jvs -o -T "分析 Kubernetes Pod 启动失败的问题，并提供解决方案"

# 代码代理启用提示词优化
jca -o -r "实现一个完整的微服务架构，包括服务注册、配置中心和API网关"

# 组合使用多个参数
jca -o --worktree -r "重构整个用户管理模块，使用新的设计模式"
```

### 注意事项

- 提示词优化仅在首次运行时执行一次，避免重复优化
- 优化过程会消耗额外的 LLM 调用，但通常能显著提升任务执行质量
- 如果优化失败，系统会自动回退到原始系统提示词，不影响任务执行
- 优化后的提示词会保持原有核心功能不变，确保向后兼容

## 4.3 通用交互技巧

无论您使用哪个 Jarvis 工具，掌握以下交互技巧都将极大提升您的效率。

### 1. 快捷键 (多行输入模式)

在需要您输入多行文本（如 `jvs` 或 `jca` 的交互模式）时，可以使用以下快捷键：

| 快捷键     | 功能                                                                          |
| ---------- | ----------------------------------------------------------------------------- |
| `@`        | 触发“Git 文件模式”的文件/指令补全；若安装 fzf，将弹出 Git 文件选择器。        |
| `#`        | 触发“全量文件模式”的文件补全（排除 .git）；若安装 fzf，将弹出全量文件选择器。 |
| `Tab`      | 在弹出的补全建议列表中进行选择。                                              |
| `Enter`    | 在补全列表打开时应用选中项，否则用于换行。                                    |
| `Ctrl + J` | 提交您的多行输入，开始执行任务。                                              |
| `Ctrl + ]` | 同样可用于提交您的多行输入。                                                  |
| `Ctrl + C` | 取消当前的输入操作。                                                          |
| `Ctrl + O` | 复制AI的上一条回复到系统剪贴板，方便您使用。                                  |

### 2. 提示词技巧 (Prompting)

编写高质量的提示词是让 Jarvis 发挥最大潜能的关键。

- 明确角色与目标: 在任务开始时，清晰地告诉Jarvis它应该扮演什么角色，以及最终要达成的目标是什么。
  > 例: "你现在是一个资深的运维专家。我的目标是排查并解决一个 Kubernetes Pod 启动失败的问题。"
- 提供上下文与特殊指令 (`@`/`#`): 使用 `@` 或 `#` 符号可以触发强大的上下文补全和快捷指令功能。
  - 提供文件上下文: 输入 `@` 或 `#` 后跟文件名（支持模糊搜索和自动补全），可将文件内容注入到对话中，为 AI 提供充足的分析背景。
    - `@` Git 文件模式：仅在 Git 跟踪的文件中进行补全/选择，列表干净、速度更快。
    - `#` 全量文件模式：在整个工作目录中进行补全/选择，自动排除 `.git`，适合未纳入 Git 的文件。
    - 若系统安装了 fzf，按下 `@`/`#` 会弹出对应的文件选择器；否则使用内置补全列表。
    - 选择后会将路径以单引号包裹插入；若光标前存在以该前导符开头、且不含空格的片段，会被整体替换为所选路径。
      > 例: "请分析 `@./src/main.py` 这个文件中的代码，并找出潜在的性能瓶颈。"
      > 例: "请分析 `#./logs/latest.log` 这个文件中的内容，定位错误栈来源。"
  - 执行特殊指令: 输入 `@` 或 `#` 后，补全菜单还会显示一系列内置指令，用于快速控制对话或执行常用操作。

    > 例: 输入 `'<Summary>'` 并提交，可以要求 Jarvis 对之前的对话进行总结。

    以下是所有可用的内置特殊指令：

    | 指令                 | 功能描述                                                                                                                                                                                         |
    | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | `'<Summary>'`        | 让 AI 总结当前的对话历史，并将摘要作为新的上下文，这有助于在长对话中保持焦点。                                                                                                                   |
    | `'<Clear>'`          | 清空当前的对话历史记录，开始一个全新的对话。                                                                                                                                                     |
    | `'<ToolUsage>'`      | 显示所有可用工具的列表和详细说明，帮助你了解 AI 能做什么。                                                                                                                                       |
    | `'<ReloadConfig>'`   | 重新加载 Jarvis 的配置文件。如果你在运行时修改了配置，可以使用此指令使其生效。                                                                                                                   |
    | `'<SaveSession>'`    | 保存当前的对话状态（包括历史记录）。会话文件会以时间戳命名（格式：saved_session_YYYYMMDD_HHMMSS.json）。之后可以通过 `jvs --restore-session` 来恢复。**注意**：此指令仅在 jvs/jca 主程序中可用。 |
    | `'<RestoreSession>'` | 恢复之前保存的会话。系统会自动查找最新的会话文件（按时间戳排序）。**注意**：此指令仅在 jvs/jca 主程序中可用。                                                                                    |
    | `'<ListSessions>'`   | 列出所有已保存的会话文件，包括文件名、时间戳和大小，帮助你快速找到需要恢复的会话。                                                                                                               |
    | `'<Pin>'`            | 固定内容到后续对话。`'<Pin>'` 之后的内容会被固定，自动追加到后续每次用户输入的开头，适合用于需要反复提醒的上下文信息。                                                                           |
    | `'<Quiet>'`          | 切换到非交互模式（无人值守模式）。在此模式下，所有需要确认的操作都会自动继续，不会暂停等待用户输入。                                                                                             |
    | `'<rule:规则名>'`    | 动态加载指定的规则。规则会从项目规则目录（`.jarvis/rules/`）、规则文件（`.jarvis/rules.yaml`）或中心规则仓库中查找，并注入到对话中。                                                             |
    | `'<自定义标签>'`     | 你可以在 `~/.jarvis/config.yaml` 中通过 `replace_map` 定义自己的标签，用于插入预设的模板文本。这对于重复性的输入非常有用。                                                                       |

- 分解复杂任务: 对于复杂的任务，将其分解为更小、更具体的步骤，并引导 Jarvis 逐步完成。

### 3. 人工介入与控制 (Human-in-the-Loop)

Jarvis 的一个核心特性是支持在任务执行的任意阶段进行人工介入。

- 执行前确认: 在执行可能产生影响的操作（如运行脚本、修改文件）之前，Jarvis 会暂停并请求您的确认 `[Y/n]`。这是第一层防护。

- 思考后介入 (`Ctrl+C`): 这是最关键的介入方式。
  - 当 AI 正在“思考”（即大模型正在生成下一步计划）时，您可以随时按下 `Ctrl+C`。
  - Jarvis 不会立即打断模型的思考，而是会等待当前思考步骤完成（即API返回结果）。
  - 在执行模型生成的计划（如调用工具）之前，系统会检测到中断信号，暂停执行并提示您："模型交互期间被中断，请输入用户干预信息："。
  - 这为您提供了一个审查并否决 AI 下一步行动的宝贵机会。您可以输入新指令来纠正它，或直接拒绝它即将执行的工具调用。

- 工具调用裁决: 这是“思考后介入”的具体体现。当您中断了一个即将发生的工具调用时，系统会询问您是否继续处理该工具。这让您拥有对每一步具体操作的最终决定权。

- 强制退出 (多次`Ctrl+C`): 如果您希望立即终止整个 Jarvis 程序，而不想等待当前思考步骤完成，可以快速连续按下 `Ctrl+C` 五次以上（或长按）。这将触发系统的强制退出机制。

### 4. 非交互模式 (自动化)

对于需要在自动化环境（如 CI/CD 流水线、定时任务脚本）中运行 Jarvis 的场景，可以使用 `-n` 或 `--non-interactive` 参数来启用非交互模式。

该模式具有以下特点：

- 无用户提示: 在此模式下，Jarvis 不会提出任何需要用户输入 `[Y/n]` 确认或进行选择的问题。所有交互式环节都会被跳过。
- 强制任务输入: 由于无法在运行时交互式地输入任务，因此必须在启动命令中通过参数（如 `jvs -T "..."`, `jca -r "..."`）提供初始任务。如果未提供，程序将报错退出。
- 禁用交互功能: 会自动禁用一些纯交互式的功能，例如 `jvs` 启动时检测 Git 仓库并询问是否切换到 `jca` 的功能。
- 脚本执行超时: 为了防止自动化脚本被意外挂起，在非交互模式下，由 `execute_script` 工具执行的脚本默认有 5分钟 的超时限制。

此参数是实现 Jarvis 自动化的关键，适用于所有需要无人值守执行的场景。

---

## 4.4 通用代理 (`jarvis` / `jvs`)

`jvs` 是您的通用AI助手，适用于各种开放式、非特异性的任务。

### 核心能力

- 任务分析与规划: 理解复杂目标并拆解为执行步骤。
- 多工具协同: 智能选择并组合使用文件读写、代码执行、网页搜索等工具。
- 系统交互: 能够执行 Shell 命令与您的操作系统进行交互。
- 预定义任务: 支持从配置文件加载预设任务，简化重复性工作。

### 常用参数

| 参数                                   | 描述                                                                                                                   |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `-T`, `--task`                         | 直接从命令行提供初始任务。                                                                                             |
| `-f`, `--config`                       | 指定自定义配置文件的路径。                                                                                             |
| `-g`, `--llm-group`                    | 临时指定模型组，覆盖默认配置。                                                                                         |
| `-G`, `--tool-group`                   | 临时指定工具组，覆盖默认配置。                                                                                         |
| `-r`, `--restore-session`              | 从 `.jarvis/saved_session.json` 恢复会话。                                                                             |
| `-e`, `--edit`                         | 快速编辑默认的 `~/.jarvis/config.yaml` 配置文件。                                                                      |
| `--share-methodology`                  | 分享本地方法论到中心方法论仓库。                                                                                       |
| `--share-tool`                         | 分享本地工具到中心工具仓库。                                                                                           |
| `--share-rule`                         | 分享本地规则到中心规则仓库。                                                                                           |
| `-I`, `--interactive-config`           | 启动交互式配置向导：基于当前配置补充设置。                                                                             |
| `-D`, `--disable-methodology-analysis` | 禁用方法论和任务分析（覆盖配置文件设置）。                                                                             |
| `-o`, `--optimize-system-prompt`       | 启用系统提示词自动优化。系统会根据用户需求使用大模型优化系统提示词，使其更贴合具体任务场景。详见"提示词自动优化"章节。 |
| `--backup-data [目录]`                 | 备份 Jarvis 数据目录。可选传入备份目录；默认使用 `~/jarvis_backups`。                                                  |
| `--restore-data <路径>`                | 从指定的压缩包恢复 Jarvis 数据。此操作会覆盖现有数据，请谨慎使用。                                                     |
| `-n`, `--non-interactive`              | 启用非交互模式：用户无法与命令交互，脚本执行超时限制为 5 分钟。                                                        |
| `-d`, `--dispatch`                     | 将任务派发到新的 tmux 窗口中执行（仅在 tmux 环境中有效），当前进程退出。                                               |
| `--rule-names <名称列表>`              | 指定规则名称列表（逗号分隔），用于加载指定规则。                                                                       |
| `--quick-config`                       | 启动快速配置向导：快速配置 LLM 平台信息（Claude/OpenAI）。详见"快速配置"章节。                                         |

### 示例

1. 交互式对话与预定义任务
   直接运行 `jvs` 会进入交互模式。如果存在预定义任务文件（`~/.jarvis/pre-command` 或 `./.jarvis/pre-command`），`jvs` 会首先列出这些任务供您选择，极大方便了日常操作的复用。

```bash
# 启动交互式会话，并可能会提示选择预定义任务
jvs
```

1. 直接执行任务
   让 Jarvis 分析当前项目结构并生成一份报告。

```bash
jvs -T "分析当前目录下的代码，总结项目的主要模块和功能"
```

1. 使用系统提示词自动优化
   对于特定领域的任务，可以使用 `-o` 参数启用系统提示词自动优化，让 Agent 更好地理解任务场景。

```bash
# 启用提示词优化，针对代码开发任务
jvs -o -T "实现一个用户认证系统，包括登录、注册和密码重置功能"

# 启用提示词优化，针对数据分析任务
jvs -o -T "分析销售数据，找出最受欢迎的产品类别和销售趋势"
```

1. 解决环境问题
   当您遇到一个复杂的环境问题时，可以请求 Jarvis 帮助。

```bash
jvs -T "我的 docker 服务无法启动，请帮我诊断问题并尝试修复。相关日志在 /var/log/docker.log"
```

1. 使用特定工具组
   通过 `--tool-group` 参数临时切换到特定的工具集。

```bash
# 使用只读的受限工具组进行代码分析
jvs --tool-group restricted -T "分析这个项目的代码结构"

# 使用文档处理工具组
jvs --tool-group document -T "搜索关于 Python asyncio 的最佳实践"
```

1. 交互式配置
   在启动前基于当前配置补充设置；保存后需重新运行命令以使用新配置：

```bash
# 使用默认配置文件进行交互式配置
jvs -I

# 或对指定配置文件进行交互式配置
jvs -I -f ./myconfig.yaml
```

1. 数据备份与恢复
   您可以轻松地备份和恢复您的所有 Jarvis 数据，包括配置、记忆、历史记录等。

备份您的数据：

```bash
# 这将在 ~/jarvis_backups/ 目录下创建一个带时间戳的 zip 压缩包
jvs --backup-data
```

从备份恢复数据：

````bash
# 恢复操作会覆盖 ~/.jarvis 目录，请务必小心
# 程序会请求您二次确认
jvs --restore-data ~/jarvis_backups/jarvis_data_20231026_103000.zip

1. 快速配置 LLM 平台
   使用 `--quick-config` 参数快速配置 Claude 或 OpenAI 平台：

```bash
# 启动快速配置向导
jvs --quick-config
```

该命令会引导您完成以下步骤：

- 输入 LLM 平台类型（claude/openai）
- 输入 API 基础 URL 和密钥
- 自动获取可用模型；获取失败时支持手动输入模型名称
- 选择要配置的模型
- 分别选择 normal / smart / cheap 三类默认模型
- 测试所选 normal 模型的 API 连通性
- 输入模型组名称（提供默认值建议）
- 设置默认最大 token 数
- 自动生成并保存配置到 `~/.jarvis/config.yaml`

```

## 4.5 代码代理 (`jarvis-code-agent` / `jca`)

`jca` 是专为软件开发任务设计的代理，是您日常编码、重构和调试的得力助手。

### 核心能力

- **深度代码集成**: 自动分析代码库结构、依赖关系和最近的提交历史，为任务提供全面的上下文。
- **智能上下文推荐**: 在任务启动时自动推荐相关代码上下文，提高代码理解效率。
- **自动化 Git 工作流**:
  - **自动检查点（预处理）**: 进入任务前，如检测到未提交更改，将通过 GitCommitTool 进行一次规范化提交（支持 --prefix/--suffix 自定义），或按配置仅告警继续。
  - **增量式变更（交互式补丁）**: 在 AI 的每一步操作（如修改文件）后，都会生成一个包含 `diff` 的补丁，并引导您确认是否将其 commit。
  - **任务后审查（最终归并）**: 整个任务完成后将列出本次会话内的提交；您可选择"接受"（系统会先重置回任务起点，然后由 GitCommitTool 生成一条统一且规范的最终提交）或直接重置回任务开始前的状态。
- **自动化构建验证**: 自动检测构建系统（Rust/Cargo、Python、Node.js、Java/Maven/Gradle、Go、CMake/Makefile 等）并验证构建，确保代码可编译。
- **静态代码分析**: 在生成代码修改后，会自动执行静态检查（ruff、mypy、clippy、eslint 等），以确保代码质量。
- **影响范围分析**: 自动分析代码修改的影响范围，包括依赖链和接口变更，评估风险等级。
- **代码审查与验证**: 通过独立的 ReviewAgent 和 VerificationAgent 进行代码审查和任务完成验证，解决大模型幻觉问题。
- **任务列表管理**: 支持复杂任务的模块化执行，自动创建子任务、管理依赖关系、跟踪任务状态。
- **虚拟终端支持**: CodeAgent 支持虚拟终端工具，允许执行交互式操作，扩展代码代理的能力边界。
- **规则系统**: 支持加载项目规则和命名规则，指导代码生成和修改行为。

### 常用参数

| 参数                             | 描述                                                                                                                                      |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `-T`, `--task`                   | 要处理的任务描述（可直接在命令行提供任务内容）。                                                                                          |
| `--task-file`                    | 从文件读取任务描述（支持纯文本或 JSON 格式）。                                                                                            |
| `-g`, `--llm-group`              | 临时指定模型组，覆盖默认配置。                                                                                                            |
| `-G`, `--tool-group`             | 临时指定工具组，覆盖默认配置。                                                                                                            |
| `-f`, `--config`                 | 指定自定义配置文件的路径。                                                                                                                |
| `--append-tools`                 | 追加的工具列表，多个工具用逗号分隔，如：`read_webpage,file_analyzer`。                                                                    |
| `-r`, `--restore-session`        | 从 `.jarvis/saved_session.json` 恢复会话状态。                                                                                            |
| `--prefix <文本>`                | 为生成的提交信息主题添加前缀（用空格分隔）。                                                                                              |
| `--suffix <文本>`                | 为生成的提交信息末尾添加后缀（用换行分隔）。                                                                                              |
| `--rule-names <名称列表>`        | 指定规则名称列表，用逗号分隔，用于加载指定规则。详见"项目规则"章节。                                                                     |
| `--disable-review`               | 禁用代码审查：在代码修改完成后不进行自动代码审查。                                                                                        |
| `--review-max-iterations <次数>` | 代码审查最大迭代次数，达到上限后停止审查（默认 0，表示无限）。                                                                            |
| `-o`, `--optimize-system-prompt` | 启用系统提示词自动优化。系统会根据用户需求使用大模型优化系统提示词。详见"提示词自动优化"章节。                                           |
| `-n`, `--non-interactive`        | 启用非交互模式：用户无法与命令交互，脚本执行超时限制为 5 分钟。                                                                            |
| `-w`, `--worktree`               | 启用 git worktree 模式，在独立分支上开发。                                                                                                |
| `-d`, `--dispatch`               | 将任务派发到新的 tmux 窗口中执行（仅在 tmux 环境中有效），当前进程退出。                                                                  |

### 示例

1. 添加新功能
   在项目中添加一个新功能，`jca` 会自动查找相关文件并进行修改。

```bash
jca -T "在用户认证模块中，增加一个'忘记密码'的功能。需要创建一个新的API端点 /api/forgot-password，并实现发送重置邮件的逻辑。"
```

1. 修复 Bug
   根据 Bug 描述修复问题。

```bash
jca -T "修复 src/utils/calculator.py 中的除零错误。当除数为零时，应该返回一个错误提示而不是抛出异常。"
```

1. 代码重构
   优化现有代码。

```bash
jca -T "重构 src/services/user_service.py 文件，将其中过长的 'create_user' 方法拆分为多个更小的私有方法，提高代码可读性。"
```

1. 使用规则指导代码生成
   加载特定的规则来指导代码生成行为。

```bash
# 使用 TDD 和代码清洁规则
jca --rule-names tdd,clean_code -T "实现用户登录功能"

# 使用项目特定的规则
jca --rule-names project_style -T "添加新的 API 端点"
```

1. 禁用代码审查（快速模式）
   如果不需要自动代码审查，可以禁用以加快执行速度。

```bash
jca --disable-review -T "快速修复一个简单的 bug"
```

1. 限制代码审查迭代次数
   控制代码审查的最大迭代次数，避免无限循环。

```bash
# 最多进行 2 次审查迭代
jca --review-max-iterations 2 -T "实现复杂功能"
```

1. 追加额外工具
   为 CodeAgent 添加额外的工具以扩展功能。

```bash
# 添加文件分析工具
jca --append-tools file_analyzer -T "分析项目依赖"
```

1. 使用系统提示词自动优化
   对于复杂的代码任务，可以使用 `-o` 参数启用系统提示词自动优化，让 CodeAgent 更好地理解任务场景和代码规范。

```bash
# 启用提示词优化，针对代码重构任务
jca -o -T "重构用户认证模块，使用新的加密算法，确保向后兼容"

# 启用提示词优化，针对新功能开发任务
jca -o -T "实现一个完整的支付系统，包括订单处理、支付网关集成和退款功能"
```

1. 非交互模式（CI/CD）
   在自动化环境中使用非交互模式。

```bash
jca -n -T "修复所有 clippy 警告"
```

### 项目规则（.jarvis/rules 和 rules.yaml）

为了在团队或项目中统一 AI 修改行为，jca 支持两种方式定义规则：纯文本规则文件和 YAML 格式的命名规则文件。

#### 纯文本规则文件（.jarvis/rules）

- 什么是项目规则
  - 位于项目根目录的纯文本文件：`./.jarvis/rules`
  - 用于约束与指导 CodeAgent 的具体行为（如修改范围、风格规范、工具使用策略等）

- 生效机制
  - jca 启动后会先读取"全局规则"：数据目录中的 `~/.jarvis/rules`（或 `data_path/rules`），以及"项目规则"：当前仓库 `.jarvis/rules`
  - 系统按"先全局、后项目"的顺序将两者内容进行拼接合并
  - 合并结果以单一的 `<rules>...</rules>` 块注入到系统提示词中；项目规则用于覆盖或补充全局规则，建议在项目规则中明确覆盖条目
  - 注入后将影响"本次会话内"的所有操作与决策

- 适用范围
  - 全局规则：作用于所有项目（存放于数据目录 `~/.jarvis/rules` 或 `data_path/rules`）
  - 项目规则：仅作用于当前项目仓库（所在 git 根目录）；用于覆盖或补充全局规则

- 建议写法
  - 简洁、明确、可执行，优先使用条目式规则清单
  - 聚焦与当前项目相关的规范，避免冗长背景描述
  - 与团队现有规范（代码风格、提交规范、目录约定）保持一致

- 示例规则文件（`.jarvis/rules`）

  ```
  # 修改范围与约束
  - 仅允许修改 src/ 和 docs/ 目录内文件
  - 禁止创建/删除数据库表与迁移：不得编辑 migrations/、database/schema.sql
  - 对 .env、secrets/*、证书/密钥等敏感文件的一切改动一律拒绝

  # 风格与质量
  - Python 统一使用 Black 与 isort；命名遵循 PEP 8
  - 新增函数必须提供 docstring 与必要的类型标注
  - 复杂变更提供最小可复现示例与必要单元测试

  # 工具与流程
  - 文件编辑优先使用 PATCH；仅在需要整文件重写时使用 REWRITE
  - 任何修改前先使用 read_code 阅读目标文件与上下文
  - 生成补丁后优先一次性执行静态检查（如 flake8/mypy/ruff 等）

  # Git 提交
  - 使用 Angular 提交规范，必须包含 scope
  - 允许使用 --prefix/--suffix 统一注入任务ID与签名
  ```

- 使用步骤
  1. 在项目根目录创建目录与文件：`mkdir -p .jarvis && touch .jarvis/rules`
  2. 将上述或团队自定义的规则写入 `.jarvis/rules`
  3. 提交到仓库，便于团队共享与审阅
  4. 运行 `jca ...`，规则将自动生效；如修改了规则，重新运行 `jca` 以应用最新内容

- 注意事项
  - 空文件不生效；读取失败会被安全忽略（不会阻断任务）
  - 仅在本地项目级生效，不会影响全局；全局偏好可使用"记忆系统"保存
  - 路径与大小写需与项目实际一致；Windows/Linux 路径差异请按实际书写
  - 规则应避免与项目已有工具链冲突（如 pre-commit、格式化器、CI 规范）

#### 命名规则文件（rules.yaml 和 .jarvis/rules/ 目录）

除了纯文本规则文件，jca 还支持通过 YAML 格式的命名规则文件和独立规则文件来管理多个可复用的规则集合。

**规则来源与优先级**：

命名规则可以从多个来源加载，遵循严格的优先级顺序：

1. **中心规则仓库**（优先级最高）：可配置的 Git 仓库，支持自动克隆和每日更新
2. **项目 `rules/` 目录**：项目根目录 `.jarvis/rules/` 目录下的独立规则文件
3. **项目 `rules.yaml`**：项目根目录 `.jarvis/rules.yaml` 文件
4. **配置的规则目录**：用户在配置文件中指定的额外规则加载目录
5. **全局 `rules.yaml`**：全局数据目录下的 `rules.yaml` 文件
6. **全局规则目录**：全局数据目录下的 `rules/` 目录
7. **内置规则**（优先级最低）：Jarvis 系统内置的规则

**规则文件格式**：

- **YAML 格式**（`rules.yaml`）：键值对格式，每个键代表一个规则名称，值为规则内容
- **独立文件**（`.jarvis/rules/` 目录）：每个规则一个文件，文件名（不含扩展名）即为规则名称

**生效机制**：

- 当使用 `--rule-names <名称列表>` 参数时，jca 会从上述所有来源查找指定的规则
- 系统会按照优先级顺序查找规则，找到即停止（高优先级覆盖低优先级）
- 所有找到的规则内容会被合并，与纯文本规则（`.jarvis/rules`）一起注入到系统提示词中
- 规则内容使用 `<rules>...</rules>` 标签包裹，注入到 CodeAgent 的系统提示词中

**示例规则文件**：

**全局规则文件**（`~/.jarvis/rules.yaml`）：

```yaml
python_best_practices: |
  - Python 代码必须遵循 PEP 8 规范
  - 所有函数必须包含类型注解和 docstring
  - 使用 Black 进行代码格式化
  - 使用 isort 进行导入排序

security_guidelines: |
  - 禁止使用 eval() 和 exec()
  - 所有用户输入必须进行验证和转义
  - 敏感信息不得硬编码在代码中
```

**项目规则文件**（`./.jarvis/rules.yaml`，会覆盖全局同名规则）：

```yaml
python_best_practices: |
  - Python 代码必须遵循 PEP 8 规范
  - 所有函数必须包含类型注解和 docstring
  - 使用 Black 进行代码格式化
  - 使用 isort 进行导入排序
  - 本项目额外要求：所有异步函数必须使用 asyncio.create_task() 管理任务
```

**项目独立规则文件**（`./.jarvis/rules/tdd.md`）：

```markdown
# TDD 规则

- 所有新功能必须先写测试
- 测试必须覆盖主要功能路径和边界情况
- 禁止使用 todo!() 宏
- 测试代码与实现代码必须分离
```

**使用步骤**：

1. 创建规则文件（可选）：
   - 全局规则：`touch ~/.jarvis/rules.yaml`
   - 项目规则：在 git 根目录创建 `.jarvis/rules.yaml` 或 `.jarvis/rules/` 目录
2. 在文件中定义规则，格式为键值对（YAML）或独立文件（目录）
3. 运行 `jca --rule-names <规则名称列表> -T "<任务描述>"` 来使用指定的规则

```bash
# 使用多个规则（逗号分隔）
jca --rule-names tdd,clean_code -T "实现用户登录功能"

# 使用项目特定的规则
jca --rule-names project_style -T "添加新的 API 端点"

# 规则会自动从所有来源查找并按优先级加载
```

**动态规则注入**：

除了通过 `--rule-names` 参数加载规则，您还可以在用户输入中使用 `'<rule:rule_name>'` 标记动态注入特定规则：

```bash
# 在交互式输入中使用
jca
# 然后输入：'<rule:tdd>' 实现用户登录功能
```

`builtin_input_handler` 会拦截此标记，查找对应的规则内容，并将其替换为 `<rule>...</rule>` 标签包裹的格式，直接插入到用户输入中。

### 规则占位符（Jinja2 模板）

规则文件支持使用 Jinja2 模板语法，可以动态插入以下内置变量：

- `{{ current_dir }}`：当前工作目录
- `{{ script_dir }}`：脚本所在目录
- `{{ jarvis_data_dir }}`：jarvis 数据目录
- `{{ jarvis_src_dir }}`：jarvis 源码目录
- `{{ git_root_dir }}`：git 根目录
- `{{ rule_file_dir }}`：当前规则文件所在目录

**示例**：

```yaml
project_paths: |
  - 仅允许修改 {{ current_dir }}/src/ 目录
  - 配置文件位于 {{ rule_file_dir }}/config/
  - 项目根目录：{{ git_root_dir }}
```

如果渲染失败（如语法错误），系统会自动返回原始内容，保证向后兼容。

**注意事项**：

- 规则名称区分大小写，必须与文件中的键或文件名完全匹配
- 如果指定的规则名称不存在，会安全忽略（不会阻断任务）
- 高优先级来源的规则会覆盖低优先级来源的同名规则
- 规则值可以是多行字符串（使用 YAML 的 `|` 或 `>` 语法）
- 命名规则与纯文本规则（`.jarvis/rules`）可以同时使用，它们会被合并在一起
- 中心规则仓库需要先在配置文件中配置 `central_rules_repo` 配置项

## 4.6 平台管理器 (`jarvis-platform-manager` / `jpm`)

`jpm` 是您与底层大模型平台交互和管理的工具。

### 子命令

- `info`: 列出所有支持的平台和模型。
- `chat`: 与指定的平台和模型进行交互式对话。
- `service`: 将指定的模型以 OpenAI 兼容的 API 形式暴露出来。
- `role`: 加载预定义的角色配置文件，选择角色后进行对话。

### 示例

1. 查看可用模型

```bash
jpm info
```

1. 与特定模型聊天
   首先，使用 `jpm info` 查找您想使用的平台和模型名称。然后，通过 `-p` 和 `-m` 参数指定它们来开始对话。

```bash
# 示例：假设您通过 jpm info 查到并想使用 "zhipu" 平台的 "glm-4" 模型
jpm chat -p zhipu -m glm-4
```

在 `chat` 模式中，您还可以使用以下命令：

- `/bye`: 退出对话。
- `/clear`: 清空当前会话历史。
- `/upload <文件路径>`: 上传文件供 AI 分析（需要平台支持）。
- `/shell <命令>`: 在本地执行 Shell 命令。
- `/save <文件名>`: 将 AI 的最后一条回复保存到文件。
- `/saveall <文件名>`: 将整个对话历史保存到文件。
- `/save_session <文件名>`: 保存当前会话状态（可用于后续加载）。
- `/load_session <文件名>`: 加载之前保存的会话状态。

1. 启动本地API服务
   将指定模型封装为本地 API，供其他应用调用。当客户端请求未指定模型时，将默认使用指定的模型。

```bash
# 示例：使用 OpenAI 平台
jpm service --host 0.0.0.0 --port 8000 -p openai -m gpt-4o
```

1. 加载角色进行对话
   使用角色配置文件（默认为 `~/.jarvis/roles.yaml`）来启动一个特定角色的对话。

```bash
# 1. jpm会首先列出 roles.yaml 中定义的所有角色
# 2. 用户选择一个角色后，jpm会使用该角色预设的平台、模型和系统提示开始对话
jpm role

# 你也可以通过参数临时覆盖角色配置中的平台和模型
# 使用 jpm info 查找可用的 platform_name 和 model_name
jpm role -c ./my_roles.yaml -p <platform_name> -m <model_name>
```

## 4.7 Git提交助手 (`jarvis-git-commit` / `jgc`)

`jgc` 能自动分析您的代码变更，并生成符合规范的 Git 提交信息。

### 核心能力

- 自动分析 `git diff`: `jgc` 会自动暂存 (`git add .`) 您工作区中的所有变更，并分析其 `diff` 内容。
- 智能处理大型变更: 如果代码变更非常大，`jgc` 会自动将 `diff` 保存为临时文件并上传，而不是直接注入到提示词中，避免超出模型上下文限制。
- 生成规范的提交信息: 基于代码变更，AI 会生成符合约定式提交规范的提交信息。
- 完全可定制: 您可以通过配置文件自定义 `jgc` 的所有行为，包括提交信息模板和前后缀。

### 常用参数

| 参数                    | 描述                                                   |
| ----------------------- | ------------------------------------------------------ |
| `--prefix <文本>`       | 在生成的提交信息主题前添加一个固定的前缀。             |
| `--suffix <文本>`       | 在生成的提交信息末尾添加一个固定的后缀（换行后追加）。 |
| `--root-dir <路径>`     | 指定要操作的 Git 仓库根目录（默认为当前目录）。        |
| `-g/--llm-group <组名>` | 使用的模型组，覆盖配置文件中的设置。                   |

### 示例与定制

1. 基本用法
   当您完成了一些代码修改后，只需在项目根目录运行：

```bash
# jgc 会自动暂存所有变更，无需手动 git add
jgc
```

Jarvis 将会分析变更，生成一条类似 `feat(auth): add password reset endpoint` 的提交信息，并自动执行 `git commit`。

1. 添加前缀和后缀
   如果您希望在提交信息中包含任务ID或特定的标记，可以使用 `--prefix` 和 `--suffix`：

```bash
jgc --prefix "JIRA-123:" --suffix "Reviewed-by: @YourName"
```

生成的提交信息会变成类似：

```
JIRA-123: feat(auth): add password reset endpoint

Reviewed-by: @YourName
```

1. 自定义提交模板 (高级)
   `jgc` 最强大的功能之一是允许您完全重写用于生成提交信息的提示词模板。您可以在 `~/.jarvis/config.yaml` 文件中通过设置 `git_commit_prompt` 配置项来定义自己的模板。

首先，通过 `jvs -e` 打开配置文件，然后添加 `git_commit_prompt` 配置项：

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

# ... 其他配置 ...

git_commit_prompt: |
  请为以下代码变更生成一条符合【Angular提交规范】的中文提交信息。

  # 规则
  1. 必须包含类型、范围和主题。
  2. 类型只能是：'新功能', '修复', '文档', '格式', '重构', '测试', '构建', '持续集成'。
  3. 范围必须是代码中被修改的模块名。
  4. 详细描述部分要解释修改的原因和带来的好处。

  # 变更内容
  {diff}
```

通过自定义此模板，您可以让 `jgc` 完全遵循您团队的特定提交规范。

### 工具配置组

Jarvis 支持通过 `tool_groups` 和 `tool_group` 来定义和切换不同的工具组合。这对于不同类型的任务（例如，代码开发 vs. 文档处理 vs. 系统管理）非常有用，可以通过配置快速切换可用的工具集。

示例：定义和使用工具组

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

# 1. 定义不同的工具配置组
tool_groups:
  - coding: # 代码开发组
      use: # 只使用这些工具
        - execute_script
        - read_code
        - clear_memory
        - save_memory
        - retrieve_memory
  - document: # 文档处理组
      use:
        - save_memory
        - retrieve_memory
  - system: # 系统管理组
      dont_use: # 排除这些工具
  - restricted: # 受限组
      use:
        - read_code
      # 只允许使用read_code，适合只读场景

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

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

通过工具配置组，您可以：

- 提高安全性：在某些场景下限制可用工具，避免误操作
- 优化体验：为特定任务类型提供精简的工具集
- 快速切换：通过修改 `tool_group` 快速切换工作模式

## 4.9 智能Shell (`jarvis-smart-shell` / `jss`)

`jss` 是一个强大的工具，可以将您的自然语言指令转换为可执行的 Shell 命令，极大降低了在终端中执行复杂操作的门槛。

### 子命令

- `request [需求]`: 将自然语言需求转换为 Shell 命令。如果未提供需求，则进入交互式输入模式。
- `install`: 为 `fish` shell 安装“命令未找到”处理器。
- `uninstall`: 卸载 `fish` shell 的处理器。

### 示例

1. 直接转换命令
   当您不确定某个操作的命令时，可以直接向 `jss` 提问。它会打印出对应的 Shell 命令，但不会执行。

```bash
jss request "查找当前目录下所有大于1MB的.log文件"
# 输出: find . -type f -name "*.log" -size +1M
```

1. 交互式执行命令
   如果您直接运行 `jss request` 而不带任何参数，它会启动一个交互式输入界面。在这种模式下，您输入需求后，生成的命令将被立即执行。

```bash
# 启动交互模式
jss request

# 在提示符后输入: 查找当前目录下所有大于1MB的.log文件，然后按 Ctrl+J
# jss 会打印并执行 find 命令
```

1. 安装“命令未找到”处理器 (仅支持 Fish Shell)
   这是 `jss` 的一个强大功能，它能让您像使用自然语言一样操作终端。

```bash
# 1. 安装处理器
jss install

# 2. 使配置生效 (只需执行一次)
source ~/.config/fish/config.fish
```

安装后，当您在 `fish` 终端中输入一个系统不认识的命令（且长度大于10个字符，以防误触）时，`jss` 会自动拦截这个输入，将其转换为有效的 Shell 命令并执行。

```fish
# 在安装了处理器的 fish shell 中，直接输入:
> 在当前目录创建一个名为 'backup' 的文件夹

# jss 会自动将其转换为并执行: mkdir backup
```

1. 卸载处理器

```bash
# 1. 卸载处理器
jss uninstall

# 2. 使配置生效
source ~/.config/fish/config.fish
```

## 4.10 代码审查 (`jca` 内置)

代码审查功能已集成到 `jca`（代码代理）中。在代码修改完成后，`jca` 会自动进行代码审查，发现问题则自动修复。您可通过以下参数控制：

- `--disable-review`：禁用代码审查（快速模式）
- `--review-max-iterations <次数>`：限制代码审查最大迭代次数

详见 [4.5 代码代理](#45-代码代理-jarvis-code-agent--jca) 章节。

## 4.11 高级Git工具

除了 `jgc`，Jarvis 还提供了一系列高级 Git 工具来简化复杂操作。

### 交互式 Squash (`jarvis-git-squash` / `jgs`)

`jgs` 可以帮助您将从某个指定提交之后的所有提交，自动合并（squash）成一个全新的、独立的提交，并为其生成一条清晰的、总结性的提交信息。这在合并多个小的功能提交或修复提交时非常有用。

#### 工作原理

1. 确认操作: `jgs` 会首先请求您确认 squash 操作。
2. 重置（Reset）: 它会执行 `git reset --mixed <您指定的基础提交>`。这个操作会将 `HEAD` 指针移回您指定的提交，同时保留这期间所有的代码变更在您的工作区。
3. 重新提交: 最后，`jgs` 会调用 `jgc` (Git 提交助手)，将工作区中所有的变更作为一个全新的提交，并由 AI 分析这些变更，生成一条高质量的总结性提交信息。

#### 参数

| 参数          | 描述                                                                 |
| ------------- | -------------------------------------------------------------------- |
| `commit_hash` | 必需。您希望作为合并基础的提交哈希。此提交之后的所有提交都将被合并。 |
| `--lang`      | 指定生成提交信息时使用的语言（默认为中文）。                         |

#### 示例

假设您的提交历史如下，您想将 `feat-a`, `feat-b`, `fix-c` 这三个提交合并成一个。

```
* 2d3d4d5 (HEAD -> main) fix-c
* a1b2c3d feat-b
* f9e8d7c feat-a
* c1a2b3d (base-commit) initial structure  <-- 这是我们的合并基础
```

运行以下命令，其中 `c1a2b3d` 是您希望保留的最后一个提交的哈希值：

```bash
jgs c1a2b3d
```

`jgs` 会自动完成上述的 `reset` 和重新提交工作，最终您的提交历史会变成：

```
* 3e4f5g6 (HEAD -> main) feat(new-feature): add a, b and fix c
* c1a2b3d (base-commit) initial structure
```

## 4.13 工具管理 (`jarvis-tool` / `jt`)

`jt` 是与 Jarvis 工具系统交互的命令行界面，它不仅能让您查看和调用现有工具，更是您扩展 Jarvis 能力的重要入口。

### 子命令

- `list`: 列出所有AI可用的工具。
- `call <工具名>`: 直接从命令行调用一个工具。
- `stat`: 显示每个工具被AI调用的频率统计。

### 核心功能与示例

1. 查看工具
   `list` 命令是探索 Jarvis 能力的起点。

```bash
# 查看所有工具的名称和描述
jt list

# 以 JSON 格式输出，方便脚本处理
jt list --json

# 显示工具的详细信息，包括其参数定义
jt list --detailed
```

1. 调用工具
   `call` 命令允许您直接测试或使用任何一个工具。

```bash
# 示例：调用read_code工具
jt call read_code --args '{"files": [{"path": "README.md"}]}'

# 对于复杂参数，可以从文件加载
# 1. 创建 a.json 文件，内容为: {"files": [{"path": "README.md"}]}
# 2. 通过 --args-file 参数调用
jt call read_code --args-file ./a.json
```

1. 查看工具使用统计
   `stat` 命令可以帮助您了解哪些工具被 AI 使用得最频繁。

```bash
jt stat
```

### 扩展 Jarvis 工具

`jt` 真正的强大之处在于其可扩展性。Jarvis 会从以下位置自动加载工具，让您可以轻松添加新功能：

方式一：通过 Python 文件添加工具
您可以将自定义的工具脚本（遵循特定的类结构）放置在以下目录中，Jarvis 启动时会自动加载它们：

- `~/.jarvis/tools/`
- 在 `config.yaml` 中由 `tool_load_dirs` 配置项指定的其他目录。

如果这些目录是 Git 仓库，Jarvis 还会每日自动执行 `git pull` 来保持工具更新。

方式二：通过 MCP (Model Context Protocol) 添加工具
MCP (模型上下文协议) 是一种更高级的集成方式，它允许 Jarvis 与外部服务（如另一个AI模型、API服务等）进行通信，并将该服务的能力封装为 Jarvis 工具。您可以通过在 `~/.jarvis/mcp/` 目录下创建 `.yaml` 配置文件，或直接在主 `config.yaml` 中定义 `mcp` 列表来注册 MCP 工具。

通过这两种方式，您可以不断地为 Jarvis 赋予新的能力，使其能解决更多领域的问题。

## 4.14 记忆系统

Jarvis 内置了强大的记忆系统，帮助您在多次交互中保持上下文连续性，并积累知识和经验。记忆系统通过 `save_memory` 和 `retrieve_memory` 两个核心工具提供服务。

### 记忆类型

Jarvis 支持三种不同的记忆类型，每种都有其特定用途：

1. 短期记忆 (short_term)

- 用途：存储当前任务相关的临时信息
- 生命周期：仅在当前会话期间有效，不会持久化
- 适用场景：任务执行过程中的中间结果、临时决策、当前上下文

1. 项目长期记忆 (project_long_term)

- 用途：存储与当前项目相关的持久信息
- 存储位置：`.jarvis/memory/` 目录
- 适用场景：项目架构说明、技术栈信息、项目特定约定、API文档等

1. 全局长期记忆 (global_long_term)

- 用途：存储跨项目的通用知识和偏好
- 存储位置：`~/.jarvis/memory/global_long_term/` 目录
- 适用场景：编程最佳实践、个人偏好设置、通用解决方案、技术笔记等

### 使用示例

保存记忆

```bash
# 在交互过程中，告诉 Jarvis 保存重要信息
jvs -T "这个项目使用 FastAPI 框架，数据库是 PostgreSQL，请记住这个信息"
# Jarvis 会自动调用 save_memory 工具，选择合适的记忆类型

# 保存编程技巧到全局记忆
jvs -T "记住这个 Python 性能优化技巧：使用列表推导式比 for 循环更快"
```

检索记忆

```bash
# 查询项目相关信息
jvs -T "这个项目使用什么技术栈？"
# Jarvis 会自动从项目长期记忆中检索相关信息

# 查询编程知识
jvs -T "我之前保存过哪些 Python 性能优化的技巧？"
```

### 对话记录

Jarvis 会自动记录所有用户与模型的交互历史，保存为 JSONL 格式的会话文件：

- **存储位置**: `~/.jarvis/data/dialogues/` 目录
- **文件格式**: 每个会话对应一个 `.jsonl` 文件，每行一个消息记录（包含时间戳、角色、内容和元数据）
- **自动管理**: 系统会自动清理旧会话，避免占用过多存储空间
- **用途**: 大模型可以读取会话文件了解完整的对话历史，便于在长对话中保持上下文连续性

在会话结束时，系统会提示会话文件的保存位置，您也可以让大模型读取该文件以了解完整的对话历史。

### 高级用法

批量导入知识

```bash
# 将文档内容导入为记忆
jvs -T "请阅读 ./docs/api_reference.md 文件，并将重要的 API 信息保存到项目记忆中"
```

记忆关联

```bash
# 建立相关概念之间的联系
jvs -T "记住：当使用 Redis 缓存时，要考虑数据一致性问题，可以使用发布订阅模式同步缓存"
```

记忆总结

```bash
# 让 Jarvis 总结某个主题的所有相关记忆
jvs -T "总结一下我保存的所有关于数据库优化的记忆"
```

通过有效使用记忆系统，您可以让 Jarvis 成为一个真正了解您和您的项目的智能助手，大大提升工作效率。

### 4.5.1 自定义构建、静态检查和修改后处理配置

除了使用默认的构建系统、静态检查工具和格式化工具外，`jca` 还支持通过配置文件自定义这些工具的行为，以适应不同项目的特殊需求。

#### 自定义构建系统配置

您可以在项目根目录的 `.jarvis/build_validation_config.yaml` 文件中自定义构建系统的行为。

**配置文件位置**：

- 项目级配置：`.jarvis/build_validation_config.yaml`

**主要配置项**：

```yaml
# 自定义构建命令（优先级最高）
custom_build_command: "make && make test"

# 指定使用的构建系统（如 rust, python, nodejs, go, java_maven, java_gradle, cmake, makefile）
selected_build_system: "rust"

# 禁用构建验证（仅进行静态检查）
disable_build_validation: false

# 禁用原因（可选）
disable_reason: "项目使用特殊的构建系统"

# 是否已经询问过用户（内部使用）
has_been_asked: false
```

**使用示例**：

1. **自定义构建命令**

   如果您的项目使用特殊的构建流程，可以通过 `custom_build_command` 指定完整的构建命令：

   ```yaml
   custom_build_command: "cmake -B build && cmake --build build && ctest --test-dir build"
   ```

2. **指定构建系统**

   如果项目同时包含多种构建系统（如同时有 Cargo.toml 和 setup.py），可以明确指定使用哪一个：

   ```yaml
   selected_build_system: "rust"
   ```

3. **禁用构建验证**

   对于无法自动构建的项目，可以禁用构建验证，仅进行静态检查：

   ```yaml
   disable_build_validation: true
   disable_reason: "项目需要特定的环境变量，无法自动构建"
   ```

**注意事项**：

- `custom_build_command` 的优先级最高，如果设置了该选项，将直接使用该命令进行构建验证
- 如果 `selected_build_system` 指定的构建系统不存在，会回退到自动检测
- 禁用构建验证后，系统仍会执行静态检查

#### 自定义静态检查工具配置

您可以通过配置文件自定义静态检查工具，支持全局配置和项目级配置。项目级配置会覆盖全局配置。

**配置文件位置**：

- 全局配置：`~/.jarvis/lint_tools.yaml`
- 项目级配置：`.jarvis/lint_tools.yaml`

**配置格式**：

```yaml
# 文件扩展名/文件名 -> 命令模板列表
.py:
  - "ruff check {file_path}"
  - "mypy {file_path}"

.ts:
  - "eslint {file_path}"
  - "tsc --noEmit {file_path}"

.rs:
  - "cargo clippy --message-format=short"

# 也支持特定文件名匹配
dockerfile:
  - "hadolint {file_path}"
```

**支持的占位符**：

- `{file_path}`: 文件的完整路径（绝对路径）
- `{file_name}`: 文件名（不含路径）
- `{config}`: 配置文件路径（需要手动指定）

**使用示例**：

1. **全局配置（~/.jarvis/lint_tools.yaml）**

   为所有项目设置统一的静态检查工具：

   ```yaml
   # Python 项目
   .py:
     - "ruff check {file_path}"
     - "mypy --strict {file_path}"

   # TypeScript 项目
   .ts:
     - "eslint {file_path}"
     - "tsc --noEmit {file_path}"
   ```

2. **项目级配置（.jarvis/lint_tools.yaml）**

   为特定项目覆盖全局配置：

   ```yaml
   # 使用更严格的 ruff 配置
   .py:
     - "ruff check {file_path} --config=pyproject.toml"
     - "mypy {file_path} --config-file=mypy.ini"

   # 添加额外的检查工具
   .go:
     - "go vet {file_path}"
     - "golangci-lint run {file_path}"
   ```

3. **配置项目级工具**

   某些工具（如 `cargo clippy`）不需要文件路径，是项目级别的：

   ```yaml
   # Rust 项目级工具（整个项目只执行一次）
   .rs:
     - "cargo clippy --message-format=short"
   ```

4. **使用配置文件**

   如果工具需要配置文件，可以在模板中直接指定：

   ```yaml
   .py:
     - "ruff check {file_path} --config=.ruff.toml"
     - "mypy {file_path} --config-file=mypy.ini"
   ```

**注意事项**：

- 项目级配置会覆盖全局配置中的同名项
- 配置文件支持两种格式：命令模板列表 `["cmd1", "cmd2"]` 或工具-模板对列表 `[["tool1", "cmd1"], ["tool2", "cmd2"]]`
- 文件名匹配优先级高于文件扩展名匹配
- 对于不需要文件路径的工具（如 `cargo clippy`），每个项目只会执行一次

#### 自定义修改后命令配置

修改后命令（默认为格式化工具）会在代码修改后自动执行，用于保持代码风格一致。您可以通过配置文件自定义这些命令。

**配置文件位置**：

- 全局配置：`~/.jarvis/after_change_tools.yaml`
- 项目级配置：`.jarvis/after_change_tools.yaml`

**配置格式**：

```yaml
# 文件扩展名/文件名 -> 命令模板列表
.py:
  - "ruff format {file_path}"

.ts:
  - "prettier --write {file_path}"

.rs:
  - "rustfmt {file_path}"

.go:
  - "gofmt -w {file_path}"
```

**支持的占位符**：

- `{file_path}`: 文件的完整路径（绝对路径）
- `{file_name}`: 文件名（不含路径）

**使用示例**：

1. **全局配置（~/.jarvis/after_change_tools.yaml）**

   为所有项目设置统一的格式化工具：

   ```yaml
   # Python 使用 black
   .py:
     - "black {file_path}"

   # JavaScript/TypeScript 使用 prettier
   .ts:
     - "prettier --write {file_path}"
   ```

2. **项目级配置（.jarvis/after_change_tools.yaml）**

   为特定项目覆盖全局配置：

   ```yaml
   # 使用 ruff format 替代 black
   .py:
     - "ruff format {file_path}"

   # 添加额外的处理步骤
   .ts:
     - "prettier --write {file_path}"
     - "eslint --fix {file_path}"
   ```

3. **使用特定配置文件**

   如果工具需要配置文件，可以在模板中直接指定：

   ```yaml
   .py:
     - "black {file_path} --config=pyproject.toml"

   .ts:
     - "prettier --write {file_path} --config=.prettierrc"
   ```

**注意事项**：

- 项目级配置会覆盖全局配置中的同名项
- 配置文件支持两种格式：命令模板列表 `["cmd1", "cmd2"]` 或工具-模板对列表 `[["tool1", "cmd1"], ["tool2", "cmd2"]]`
- 文件名匹配优先级高于文件扩展名匹配
- 默认情况下，修改后命令主要是格式化工具，但您也可以配置其他工具（如 `eslint --fix`）

#### 配置优先级总结

对于静态检查工具和修改后命令，配置的优先级为：

1. **项目级配置**（`.jarvis/lint_tools.yaml` 或 `.jarvis/after_change_tools.yaml`）- 优先级最高
2. **全局配置**（`~/.jarvis/lint_tools.yaml` 或 `~/.jarvis/after_change_tools.yaml`）
3. **内置默认配置** - 优先级最低

对于构建系统，配置的优先级为：

1. **自定义构建命令**（`custom_build_command`）- 优先级最高
2. **指定的构建系统**（`selected_build_system`）
3. **自动检测**（基于文件分析）

通过合理使用这些配置文件，您可以让 `jca` 完美适配不同项目的特殊需求，提高开发效率。

### 4.4.2 记忆整理工具 (`jarvis-memory-organizer` / `jmo`)

随着时间推移，记忆系统中可能会积累大量相似或重复的记忆。`jmo` 工具提供了整理、合并、导入导出等功能，帮助您高效管理记忆库。

功能特点

- 自动识别具有相似标签的记忆并智能合并
- 支持记忆的导入导出，便于备份和迁移
- 使用 AI 智能合并相关记忆，保留所有重要信息
- 优先保留最新的记忆内容（时间权重）
- 支持项目长期记忆和全局长期记忆的管理

子命令

1. organize - 整理和合并记忆

```bash
# 整理项目长期记忆（默认）
jmo organize

# 整理全局长期记忆
jmo organize --type global_long_term

# 设置最小标签重叠数为 3
jmo organize --min-overlap 3

# 模拟运行，查看将要合并的记忆但不实际执行
jmo organize --dry-run
```

1. export - 导出记忆

```bash
# 导出所有记忆到文件
jmo export memories.json

# 只导出项目长期记忆
jmo export project_memories.json -t project_long_term

# 导出带特定标签的记忆
jmo export python_memories.json --tag Python --tag API

# 导出多种类型的记忆
jmo export all_memories.json -t project_long_term -t global_long_term
```

1. import - 导入记忆

```bash
# 导入记忆文件
jmo import memories.json

# 导入并覆盖已存在的记忆
jmo import memories.json --overwrite
```

工作原理

整理功能：

1. 扫描指定类型的所有记忆文件
2. 找出标签重叠度高的记忆组
3. 使用 AI 将相似记忆合并成一个综合性记忆
4. 删除原始记忆，保存合并后的新记忆

导入导出功能：

1. 导出：将指定类型和标签的记忆序列化为 JSON 文件
2. 导入：从 JSON 文件恢复记忆到相应的存储位置

最佳实践

- 定期运行整理功能（如每周一次）以保持记忆库整洁
- 在整理前使用 export 功能备份重要记忆
- 首次整理建议使用 `--dry-run` 预览效果
- 可以根据项目特点调整 `--min-overlap` 参数
- 使用导入导出功能在不同环境间迁移记忆

## 4.15 方法论管理 (`jarvis-methodology` / `jm`)

`jm` 是用于管理和维护 Jarvis 方法论库的工具。

### 什么是方法论？

在 Jarvis 中，方法论（Methodology）是一套针对特定 问题类型（Problem Type） 的、标准化的、可复用的解决方案流程。当 Jarvis 遇到一个新任务时，它会首先尝试匹配已有的方法论。如果找到匹配项，它就会参考这个方法论来制定计划，而不是从零开始思考，从而大大提高解决问题的效率和成功率。

所有的方法论都以“问题类型”为核心，存储在 `~/.jarvis/methodologies` 目录下的独立 JSON 文件中。

### 子命令

- `import <文件>`: 从一个导出的 JSON 文件中导入方法论，它会与现有的方法论进行合并（新的会覆盖同名的旧的）。
- `export <文件>`: 将当前所有的方法论导出到一个单一的 JSON 文件中，方便备份和分享。
- `list`: 列出当前所有方法论的“问题类型”。
- `extract <文件>`: 从本地的一个文本文件（如一篇技术文章、教程）中，利用 AI 提取并生成新的方法论。
- `extract-url <URL>`: 从一个网页链接中，利用 AI 读取内容、提取并生成新的方法论。

### 示例

1. 让 Jarvis 从外部知识中学习
   假设您找到一篇非常好的关于“排查 Kubernetes Pod 启动失败”的博客文章，您可以让 Jarvis 从中学习，并形成自己的方法论。

```bash
# Jarvis 会读取该 URL 的内容，并自动提取和保存相关的解决方案流程
jm extract-url "https://some-blog.com/k8s-pod-troubleshooting"
```

执行后，如果您再次向 Jarvis 提出类似“我的 Pod 启动不了”的问题，它就会优先参考刚刚学到的这套方法论来解决问题。

1. 查看、备份和分享方法论

```bash
# 查看您已经积累了哪些方法论
jm list

# 将所有方法论备份到一个文件中
jm export my_methodologies.json

# 在另一台机器上，或者分享给同事后，可以轻松导入
jm import my_methodologies.json
```

1. 分享方法论到中心仓库

Jarvis 支持将本地的方法论分享到团队的中心方法论仓库，实现知识共享：

```bash
# 分享本地方法论到中心仓库
jarvis --share-methodology
```

这个功能需要先配置中心方法论仓库地址（参见 [5.功能扩展](5.功能扩展.md) 中的方法论共享配置）。执行后会：

- 自动克隆/更新中心方法论仓库
- 检测并排除已存在的重复方法论
- 允许您选择要分享的方法论（支持批量选择）
- 自动提交并推送到远程仓库

### 中心方法论库使用场景

1. 团队知识沉淀

```bash
# 场景：团队成员解决了一个复杂的性能问题，想将解决方案分享给全团队
# 步骤1：先让 Jarvis 学习这个解决方案
jm extract performance_optimization.md

# 步骤2：分享到中心库
jarvis --share-methodology
# 选择刚才生成的"性能优化"方法论
```

1. 新人快速上手

```bash
# 场景：新加入的团队成员需要快速了解项目的最佳实践
# 配置中心方法论库后，Jarvis 会自动加载所有团队方法论
# 在 ~/.jarvis/config.yaml 中设置
# central_methodology_repo: "https://github.com/team/methodologies.git"

# 新人可以直接使用团队积累的所有方法论
jvs -T "如何进行代码审查？"  # Jarvis 会自动应用团队的代码审查方法论
```

1. 跨项目经验复用

```bash
# 场景：在新项目中遇到类似问题，想复用之前项目的解决方案
# 中心库中已有"微服务部署"、"数据库迁移"等方法论
jvs -T "我需要将这个单体应用拆分为微服务"
# Jarvis 会自动匹配并应用"微服务拆分"方法论
```

### 中心工具库使用场景

1. 企业内部工具集成

```bash
# 场景：企业有内部的发布系统、监控平台等
# 步骤1：开发适配工具并测试
# 创建 ~/.jarvis/tools/deploy_tool.py

# 步骤2：分享到中心工具库
jarvis --share-tool
# 选择 deploy_tool.py，工具会被移动到中心库

# 团队其他成员配置中心工具库后即可使用
# 在 ~/.jarvis/config.yaml 中设置
# central_tool_repo: "https://github.com/company/jarvis-tools.git"
jvs -T "部署应用到生产环境"  # 可以直接调用内部部署工具
```

1. 领域专用工具包

```bash
# 场景：数据科学团队需要专门的数据处理工具
# 中心工具库包含：data_cleaning, model_evaluation, dataset_split 等工具

# 配置数据科学工具库
# 在 ~/.jarvis/config.yaml 中设置
# central_tool_repo: "https://github.com/team/ml-tools.git"

# 使用专用工具进行数据处理
jvs -T "清洗 dataset.csv 中的异常数据并划分训练集"
```

1. 安全合规场景

```bash
# 场景：某些环境需要限制工具使用，只允许经过审核的工具

# 步骤1：配置只使用中心工具库的工具
cat >> ~/.jarvis/config.yaml << EOF
central_tool_repo: "https://github.com/company/approved-tools.git"
tool_groups:
  - secure:
      use: []  # 不使用任何内置工具
      # 只使用中心工具库中经过审核的工具
tool_group: secure
EOF

# 步骤2：这样配置后，Jarvis 只能使用中心库中的受信任工具
```

1. 工具版本管理

```bash
# 场景：需要确保团队使用统一版本的工具

# 中心工具库使用 Git 标签管理版本
cd ~/.jarvis/central_tool_repo
git tag -l  # 查看所有版本
# v1.0.0
# v1.1.0
# v2.0.0

# 切换到特定版本
git checkout v1.1.0

# 或者在 CI/CD 中锁定版本
# git clone --branch v1.1.0 <central_tool_repo_url>
```

### 最佳实践建议

1. 建立审核机制：中心库应有代码审核流程，确保质量
2. 文档规范：每个方法论和工具都应有清晰的文档
3. 定期更新：利用 Jarvis 的自动更新功能保持同步
4. 分类管理：使用目录结构对方法论和工具进行分类
5. 版本控制：使用 Git 标签标记重要版本，便于回滚

---

## 4.16 安全分析套件 (`jarvis-sec` / `jsec`)

`jsec` 是 Jarvis 的安全分析套件，专门用于对代码工程进行安全扫描和分析。它采用**配置驱动**的设计理念，通过配置文件管理扫描参数，支持启发式扫描和 AI 深度验证，能够识别潜在的安全漏洞和风险。

### 核心特性

- **配置驱动**：通过配置文件（`.jarvis/jsec/config.json`）管理扫描目标、语言过滤、输出格式等参数，便于复用和版本控制
- **命令行参数覆盖**：支持在 `scan` 命令中通过命令行参数临时覆盖配置，灵活便捷
- **启发式快速扫描**：基于正则表达式的快速扫描，支持 C/C++ 和 Rust 语言，无需依赖外部服务
- **AI 深度分析**：使用 Agent 对候选问题进行深度分析，推导完整的漏洞触发路径
- **多阶段验证流程**：直扫 → 聚类 → 分析 → 验证 → 复核，确保结果准确性
- **结构化报告**：生成 JSON + Markdown/CSV 格式的详细报告，包含问题分类、严重程度、修复建议等
- **外部工具集成**：支持从外部工具的 JSON 输出进行安全分析，自动学习非标准格式

### 工作流程

```
配置管理（jsec config）→ 执行扫描（jsec scan）→
直扫（direct_scan）→ 聚类（Cluster Agent）→ 分析（Analysis Agent）→
验证（Verification Agent）→ 复核（Review Agent）→ 报告聚合
```

1. **配置管理**：使用 `jsec config` 命令设置扫描目标、语言过滤、排除目录、输出格式等参数
2. **直扫（Direct Scan）**：使用预定义的正则表达式模式快速识别潜在安全问题
3. **聚类（Clustering）**：使用 LLM 将相似的安全问题聚类，减少重复分析
4. **分析（Analysis）**：为每个候选问题创建独立的 Agent 任务进行深度分析
5. **验证（Verification）**：使用独立的验证 Agent 对分析结果进行二次验证
6. **复核（Review）**：最终复核和报告聚合

### 子命令

`jsec` 提供三个主要子命令：

- `config`：管理扫描配置文件
- `scan`：执行安全扫描（从配置文件读取）
- `analyze`：从外部 JSON 文件分析安全问题

#### `config` - 管理配置文件

配置文件位于 `.jarvis/jsec/config.json`，包含以下主要配置项：

- `target`：扫描目标（文件路径或目录路径）
- `languages`：语言过滤列表（如 `c`, `cpp`, `rust`）
- `exclude_dirs`：排除目录列表
- `output`：输出配置（format 和 file）
- `analysis`：分析参数（cluster_limit、enable_verification、force_save_memory）
- `runtime`：运行时配置（llm_group）

**参数**：

| 参数                                | 描述                                                                 |
| ----------------------------------- | -------------------------------------------------------------------- |
| `--target <路径>`                   | 设置扫描目标（文件路径或目录路径）                                    |
| `--languages <语言列表>`            | 设置语言过滤（逗号分隔，如 c,cpp,rust）                               |
| `--exclude-dirs <目录列表>`         | 设置排除目录（逗号分隔）                                             |
| `--output-format <格式>`            | 设置输出格式（csv/markdown）                                         |
| `--output-file <路径>`              | 设置输出文件路径                                                     |
| `--cluster-limit <数量>`            | 设置聚类限制（每批最多处理的告警数）                                  |
| `--enable-verification/--no-verification` | 是否启用二次验证                                                 |
| `--force-save-memory/--no-force-save-memory` | 是否强制使用记忆                                             |
| `--llm-group <组名>`                | 设置模型组                                                           |
| `--show`                            | 显示当前配置                                                         |
| `--clear`                           | 清空配置（重置为默认值）                                             |

**使用示例**：

```bash
# 设置扫描目标为当前目录
jsec config --target .

# 设置扫描目标为指定目录
jsec config --target ./src

# 设置扫描目标为指定文件
jsec config --target ./src/main.c

# 设置语言过滤和输出格式
jsec config --languages c,cpp,rust --output-format csv

# 设置分析参数
jsec config --cluster-limit 30 --enable-verification

# 设置模型组
jsec config --llm-group deep_seek_v3

# 查看当前配置
jsec config --show

# 清空配置
jsec config --clear
```

#### `scan` - 执行安全扫描

从配置文件读取所有配置并执行扫描。如果配置文件不存在，会给出友好提示引导用户使用 `config` 命令。

**支持扫描模式**：
- **目录扫描**：扫描指定目录下的所有文件
- **文件扫描**：扫描指定文件（会扫描文件所在目录，然后过滤只保留该文件的问题）

**使用示例**：

```bash
# 执行扫描（使用配置文件中的设置）
jsec scan

# 配置并扫描的完整流程
# 1. 设置扫描目标
jsec config --target ./src

# 2. 设置输出格式
jsec config --output-format markdown --output-file report.md

# 3. 执行扫描
jsec scan

# 扫描单个文件
jsec config --target ./src/main.c
jsec scan
```

#### `analyze` - 分析外部JSON文件

从外部扫描工具的 JSON 输出进行安全分析，支持自动学习非标准格式。

**参数**：

| 参数                                | 描述                                                                 |
| ----------------------------------- | -------------------------------------------------------------------- |
| `input`                             | 外部 JSON 文件路径（必需参数）                                        |
| `--output-format <格式>`            | 输出格式（csv/markdown）                                             |
| `--output-file <路径>`              | 输出文件路径                                                         |
| `--cluster-limit <数量>`            | 聚类限制（每批最多处理的告警数，默认50）                              |
| `--enable-verification/--no-verification` | 是否启用二次验证（默认启用）                                    |
| `--force-save-memory/--no-force-save-memory` | 是否强制使用记忆（默认关闭）                                   |

**标准格式示例**：

```json
{
    "issues": [
        {
            "language": "c",
            "category": "memory",
            "pattern": "strcpy",
            "file": "src/main.c",
            "line": 42,
            "evidence": "strcpy(dest, src)",
            "description": "Unsafe string copy",
            "suggestion": "Use strncpy instead",
            "confidence": 0.8,
            "severity": "high"
        }
    ]
}
```

**使用示例**：

```bash
# 分析标准格式文件
jsec analyze external_issues.json

# 分析非标准格式文件（自动转换）
jsec analyze custom_tool_output.json

# 指定输出格式
jsec analyze issues.json --output-format csv --output-file report.csv

# 禁用二次验证（快速模式）
jsec analyze issues.json --no-verification

# 调整聚类批次大小
jsec analyze issues.json --cluster-limit 100
```

### 输出说明

`jsec` 会生成以下输出：

- **Markdown 报告**（默认）：人类可读的详细报告，包含问题描述、严重程度、修复建议等
- **CSV 报告**（当配置为 csv 格式时）：结构化的 CSV 格式报告，便于导入 Excel 等工具分析
- **控制台输出**：分析过程的实时输出和最终报告摘要

### 注意事项

- 首次使用需要先运行 `jsec config` 配置扫描参数
- 首次运行可能需要较长时间，特别是对于大型代码库
- 建议在 CI/CD 流程中集成，定期进行安全扫描
- 对于误报，可以通过复核流程进行过滤
- 支持 C/C++ 和 Rust 语言的安全分析
- 如果 Agent 分析过程出错或无输出，会自动回退到直扫基线（fast 模式）
- 使用 `analyze` 命令分析外部工具输出时，如果格式不符合标准，系统会自动创建 Agent 学习格式并转换

## 4.17 C→Rust 迁移套件 (`jarvis-c2rust` / `jc2r`)

`jc2r` 是 Jarvis 的 C→Rust 迁移套件，专门用于将 C/C++ 代码智能迁移到 Rust。它采用渐进式迁移策略，支持断点续跑，确保迁移过程安全可控。

### 核心特性

- **智能代码扫描**：基于 libclang 的精确 AST 解析，提取函数、类型和调用关系
- **库替代评估**：使用 LLM 评估 C 函数是否可用 Rust 标准库或第三方 crate 替代
- **模块规划**：使用 Agent 智能规划 Rust crate 的模块结构
- **代码转译**：使用 CodeAgent 进行代码生成和修复，支持依赖检查和自动实现
- **保守优化**：在确保代码正确性的前提下进行优化
- **渐进式迁移**：支持断点续跑，可以分批次完成迁移
- **可回退机制**：构建检测与 git_guard 确保迁移过程可回退

### 工作流程

```
扫描（scan）→ 库替代（lib-replace）→ 模块规划（prepare）→
转译（transpile）→ 优化（optimize）
```

1. **扫描（scan）**：使用 libclang 解析 C/C++ 代码，生成符号表和调用图
2. **库替代（lib-replace）**：评估哪些 C 函数可以用 Rust 库替代
3. **模块规划（prepare）**：使用 Agent 规划 Rust crate 的模块结构
4. **转译（transpile）**：使用 CodeAgent 进行代码生成和修复
5. **优化（optimize）**：在确保正确性的前提下进行保守优化

### 子命令

`jc2r` 提供两个主要子命令：

#### 1. `config` - 管理转译配置文件

管理转译配置文件（`.jarvis/c2rust/config.json`），可以设置根符号列表、禁用库列表和附加说明。

**参数**：

| 参数                          | 描述                                                                                  |
| ----------------------------- | ------------------------------------------------------------------------------------- |
| `--files <文件...>`           | 头文件（.h/.hh/.hpp/.hxx）或函数名列表文件（每行一个函数名，忽略空行与以#开头的注释） |
| `--root-list-syms <符号列表>` | 根符号列表内联（逗号分隔）                                                            |
| `--disabled-libs <库列表>`    | 禁用库列表（逗号分隔）                                                                |
| `--additional-notes <说明>`   | 附加说明（将在所有 agent 的提示词中追加）                                             |
| `--show`                      | 显示当前配置内容                                                                      |
| `--clear`                     | 清空配置（重置为默认值）                                                              |

**使用示例**：

```bash
# 从头文件自动提取函数名并设置根符号列表
jc2r config --files bzlib.h

# 从多个头文件提取函数名
jc2r config --files a.h b.hpp c.hxx

# 从函数名列表文件设置根符号列表
jc2r config --files roots.txt

# 从命令行设置根符号列表
jc2r config --root-list-syms "func1,func2,func3"

# 设置禁用库列表
jc2r config --disabled-libs "libc,libm"

# 设置附加说明
jc2r config --additional-notes "注意：所有函数必须处理错误情况，避免 panic"

# 同时设置多个参数
jc2r config --files bzlib.h --disabled-libs "libc" --additional-notes "特殊要求说明"

# 查看当前配置
jc2r config --show

# 清空配置
jc2r config --clear
```

#### 2. `run` - 执行完整的转译流水线

依次执行流水线：scan → lib-replace → prepare → transpile → optimize，支持断点续跑。

**参数**：

| 参数                      | 描述                                                                |
| ------------------------- | ------------------------------------------------------------------- |
| `-g/--llm-group <组名>`   | 用于 LLM 相关阶段（lib-replace/prepare/transpile/optimize）的模型组 |
| `-m/--max-retries <次数>` | transpile 构建/修复与审查的最大重试次数（0 表示不限制）             |
| `--interactive`           | 启用交互模式（默认非交互模式）                                      |
| `--reset`                 | 重置状态，从头开始执行所有阶段                                      |

**使用示例**：

```bash
# 执行完整的转译流水线（使用默认配置）
jc2r run

# 指定模型组
jc2r run -g deep_seek_v3

# 设置最大重试次数
jc2r run -m 3

# 启用交互模式
jc2r run --interactive

# 重置状态，从头开始执行
jc2r run --reset

# 组合使用多个参数
jc2r run -g deep_seek_v3 -m 5 --interactive
```

### 断点续跑机制

`jc2r run` 支持断点续跑，根据状态文件（`.jarvis/c2rust/run_state.json`）自动跳过已完成的阶段：

- 如果某个阶段已完成，会自动跳过并继续下一个阶段
- 使用 `--reset` 可以重置状态，从头开始执行所有阶段
- 状态文件记录每个阶段的完成状态和时间戳

### 配置文件说明

转译配置保存在 `.jarvis/c2rust/config.json`，包含：

- **root_symbols**：根符号列表，用于确定转译的入口函数
- **disabled_libraries**：禁用库列表，指定不使用哪些库进行替代
- **additional_notes**：附加说明，会在所有 agent 的提示词中追加

### 技术特点

- **精确解析**：使用 libclang 提供准确的 AST 解析，保留完整的类型信息
- **依赖管理**：自动提取函数调用关系，确保转译顺序符合依赖关系
- **测试保护**：基于事件订阅机制，确保测试代码不会被意外删除
- **记忆保存**：代码生成 Agent 启用强制保存记忆，记录关键信息
- **依赖检查**：在实现函数时自动检查并补齐依赖函数的实现

### 输出说明

`jc2r` 会在 `.jarvis/c2rust/` 目录下生成以下文件：

- **symbols.jsonl**：统一符号表（后续流程的主输入）
- **symbols_raw.jsonl**：原始符号表
- **translation_order.jsonl**：函数转译的先后顺序
- **library_replacements.jsonl**：库替代映射关系
- **run_state.json**：运行状态文件（用于断点续跑）
- **config.json**：转译配置文件
- **symbol_map.jsonl**：符号映射关系

### 注意事项

- 需要安装 libclang（clang.cindex），支持 libclang 16-21 版本
- 建议使用 compile_commands.json 提高解析准确性
- 迁移过程会自动进行构建检测，确保代码可编译
- 支持大规模项目的分批转译，可以中断后继续
- 迁移后的代码需要人工审查和测试
- 根符号列表和禁用库列表需要先通过 `config` 命令设置

---

## 4.20 Tmux 任务派发系统

Jarvis 提供了 tmux 任务派发功能，可将任务派发到新的 tmux 窗格中执行。**需在配置中设置 `enable_tmux: true` 才能使用**。适用于需要将任务分离到独立窗格或监控长时间运行任务的场景。

### 4.20.1 核心功能

Tmux 任务派发系统提供了以下核心功能：

1. **任务派发**：将任务派发到新的 tmux 窗格中执行，主会话可继续其他操作
2. **自动会话管理**：自动检测和管理 tmux 会话，无需手动启动
3. **布局优化**：自动调整窗格布局为 `tiled` 模式，优化显示效果
4. **降级支持**：不在 tmux 环境中时，会寻找或创建 Jarvis 会话作为降级方案

### 4.20.2 基本使用方法

#### 使用 --dispatch 参数

最直接的使用方法是在支持的命令中使用 `--dispatch` 或 `-d` 参数：

```bash
# 派发一个通用代理任务到新的 tmux 窗格
jvs --dispatch --task "分析当前项目的安全问题"

# 派发一个代码代理任务到新的 tmux 窗格
jca --dispatch --task "重构 src/utils 目录下的代码"

# 使用短参数形式
jvs -d -T "检查代码中的潜在错误"
```

当使用 `--dispatch` 参数时，任务会在新的 tmux 窗格中启动，主进程立即退出，允许您继续在原窗格中执行其他操作。

### 4.20.3 专用派发工具

Jarvis 提供了专门的派发工具以提升使用便捷性：

#### jvsd - Jarvis Agent Dispatcher

`jvsd` 是通用代理的便捷派发工具，专门用于任务派发：

```bash
# 直接派发任务
jvsd "分析当前项目结构并生成报告"

# 交互模式输入任务（Ctrl+J确认）
jvsd
```

#### jcad - Jarvis Code Agent Dispatcher

`jcad` 是代码代理的便捷派发工具：

```bash
# 直接派发代码任务
jcad "重构用户认证模块，使用新的加密算法"

# 交互模式输入代码任务
jcad
```

这两个工具会自动启用非交互模式 (`-n`)、工作树模式 (`--worktree`，对于 jcad) 和任务派发 (`--dispatch`)，简化了并行任务的启动过程。

### 4.20.4 高级用法

#### 任务文件支持

除了直接输入任务，还可以从文件读取任务内容：

```bash
# 创建任务文件
cat > my_task.txt << EOF
任务描述：重构用户管理模块
1. 将用户验证逻辑提取到独立的服务类
2. 实现用户权限的缓存机制
3. 添加用户操作的审计日志
背景信息：用户反馈当前模块响应速度较慢
EOF

# 派发任务文件
jvsd < my_task.txt
```

#### 工作树模式 (仅 jca)

当使用 `jcad` 时，会自动启用 Git 工作树 (worktree) 模式，确保任务在独立的分支上开发，避免与主分支冲突：

```bash
# 在独立的 worktree 中执行代码任务
jcad "实现新的支付功能"
```

Git 工作树 (worktree) 模式是 Jarvis 提供的一种强大的开发模式，允许在独立的分支上进行开发，避免与主分支冲突。

##### 核心功能

1. **隔离开发**：在独立的分支上进行开发，不会影响主分支的稳定性
2. **自动分支管理**：自动生成和清理 worktree 分支，支持仓库初始提交自动创建
3. **软链接支持**：自动将原仓库的 `.jarvis` 目录软链接到 worktree 中，确保配置和数据的一致性
4. **自动提交未保存更改**：在 worktree 模式下自动处理未提交的代码变更，确保任务执行前工作区干净
5. **智能合并**：使用 rebase 策略将 worktree 分支合并回原分支，保持线性历史

##### 使用方法

`jcad` 命令默认会启用 worktree 模式，确保代码修改在独立的分支上进行：

```bash
# 在独立的 worktree 中执行代码任务
jcad "实现新的支付功能"

# 交互模式下使用 worktree
jcad
# 然后输入任务描述
```

对于 `jca` 命令，也可以通过 `--worktree` 参数启用 worktree 模式：

```bash
# 启用 worktree 模式执行代码任务
jca --worktree -r "重构用户认证模块，使用新的加密算法"
```

##### 工作流程

1. **创建 worktree**：系统会自动生成一个唯一的分支名（格式：`jarvis-{project_name}-{timestamp}-{random_suffix}`），并在该分支上创建 git worktree。如果仓库还没有初始提交，会自动创建初始提交
2. **链接配置**：将原仓库的 `.jarvis` 目录软链接到 worktree 中
3. **自动提交未保存更改**：如果检测到未提交的代码变更，会自动提交这些更改，确保任务执行前工作区干净
4. **执行任务**：在 worktree 目录中执行代码修改任务
5. **合并回主分支**：任务完成后，使用 rebase 策略将 worktree 分支变基到原分支，然后通过 fast-forward 合并
6. **清理资源**：自动删除 worktree 目录和对应的分支

##### 分支命名规范

worktree 分支采用以下命名格式：

```
jarvis-{project_name}-{YYYYMMDD}-{HHMMSS}-{4位随机字符}
```

例如：`jarvis-myproject-20231201-143052-abcd`

这种命名方式确保了分支名称的唯一性，避免命名冲突。

##### 安全机制

1. **路径安全验证**：在创建软链接时，系统会验证目标路径是否在 worktree 目录下，防止目录穿越攻击
2. **冲突处理**：在合并分支时，如果出现冲突，系统会提示用户手动解决
3. **状态检查**：在合并前会检查主仓库状态，确保是干净的，避免意外的修改被合并

### 4.20.5 注意事项

1. **启用/禁用tmux**：通过 `enable_tmux` 配置项控制是否启用tmux功能

   ```yaml
   # config.yaml
   enable_tmux: false # 默认为false，设置为true可启用tmux
   ```

   当设置为 `false` 时，系统将禁用所有tmux相关功能，包括自动启动tmux会话、任务派发到tmux窗口等。这对于不希望使用tmux的用户特别有用。

2. **tmux 安装**：确保系统已安装 tmux

   ```bash
   # Ubuntu/Debian
   sudo apt install tmux
   # CentOS/RHEL
   sudo yum install tmux
   # macOS
   brew install tmux
   ```

3. **自动启动**：当不在 tmux 环境中但使用 `--dispatch` 参数时，系统会自动创建新的 tmux 会话并执行任务

4. **资源管理**：派发任务会消耗额外系统资源，请根据系统能力合理安排

5. **会话管理**：派发的任务会在独立的窗格中运行，可以使用 tmux 命令 (如 `tmux attach`) 管理会话

## 4.21 配置管理工具 (`jarvis-config` / `jcfg`)

`jarvis-config` 是 Jarvis 的配置管理工具，它基于 JSON Schema 动态生成配置 Web 页面，提供友好的可视化配置界面，让配置管理变得简单直观。

### 核心特性

- **动态 Web 界面**：根据 JSON Schema 自动生成表单页面，无需手动编写配置文件
- **实时验证**：基于 Schema 的实时配置验证，确保配置正确性
- **可视化操作**：通过浏览器界面进行配置，支持下拉选择、开关、文本输入等多种表单控件
- **灵活配置**：支持自定义 Schema 文件和输出路径，适用于不同场景
- **自动保存**：配置完成后自动保存为 YAML 格式，兼容 Jarvis 的配置系统

### 常用参数

| 参数                  | 描述                                                       |
| --------------------- | ---------------------------------------------------------- |
| `--schema`, `-s`      | JSON Schema 文件路径（默认：Jarvis 的 config_schema.json） |
| `--output`, `-o`      | 输出的配置文件路径（默认：~/.jarvis/config.yaml）          |
| `--port`, `-p`        | Web 服务端口（默认：8080）                                 |
| `--no-browser`, `/nb` | 启动后不自动打开浏览器                                     |

### 示例

1. 默认配置
   使用默认配置启动 Web 界面，自动使用 Jarvis 的 config_schema.json 和输出到 ~/.jarvis/config.yaml：

```bash
jarvis-config
```

1. 自定义 Schema 文件
   使用自定义的 JSON Schema 文件生成配置页面：

```bash
jarvis-config --schema custom.json
```

1. 指定输出路径
   将配置保存到指定路径：

```bash
jarvis-config --output /path/to/custom_config.yaml
```

1. 自定义端口
   使用指定端口启动 Web 服务：

```bash
jarvis-config --port 3000
```

1. 不自动打开浏览器
   启动服务但不自动打开浏览器：

```bash
jarvis-config --no-browser
```

1. 组合使用多个参数
   完整示例：使用自定义 Schema、输出路径和端口：

```bash
jarvis-config -s my_schema.json -o my_config.yaml -p 9000 --no-browser
```

### 工作流程

1. **启动服务**：运行 `jarvis-config` 命令，系统会根据指定的 JSON Schema 文件生成 Web 配置页面
2. **浏览器访问**：默认自动在浏览器中打开配置页面（如 <http://localhost:8080）>
3. **填写配置**：在 Web 界面中填写各项配置，表单会根据 Schema 自动生成对应的输入控件
4. **实时验证**：输入时会根据 Schema 进行实时验证，确保配置格式正确
5. **保存配置**：点击保存按钮，系统会将配置自动保存为 YAML 文件
6. **停止服务**：按 Ctrl+C 停止 Web 服务

### 适用场景

- **首次配置**：首次使用 Jarvis 时，通过可视化界面快速完成配置
- **配置迁移**：从旧版本迁移到新版本时，使用新的 Schema 生成配置
- **团队配置**：为团队成员提供统一的配置模板，确保配置一致性
- **复杂配置**：对于复杂的配置项，可视化界面比手动编辑 YAML 更直观
- **自定义场景**：为特定项目或应用创建自定义的配置页面
````
