Jarvis Agent 使用指南

项目地址:https://github.com/skyfireitdiy/Jarvis
4. 使用指南
本章是 Jarvis 的实用操作手册,将详细介绍主要命令的用法、参数和常见场景示例。
在阅读本章之前,我们建议您先通过 https://xie.infoq.cn/article/66251dc719136ca1d58af468e 了解 Jarvis 的基本安装和配置。
4.1 通用交互技巧
无论您使用哪个 Jarvis 工具,掌握以下交互技巧都将极大提升您的效率。
1. 快捷键 (多行输入模式)
在需要您输入多行文本(如 jvs
或 jca
的交互模式)时,可以使用以下快捷键:

2. 提示词技巧 (Prompting)
编写高质量的提示词是让 Jarvis 发挥最大潜能的关键。
明确角色与目标: 在任务开始时,清晰地告诉 Jarvis 它应该扮演什么角色,以及最终要达成的目标是什么。
例: "你现在是一个资深的运维专家。我的目标是排查并解决一个 Kubernetes Pod 启动失败的问题。"
提供上下文与特殊指令 (
@
): 使用@
符号可以触发强大的上下文补全和快捷指令功能。提供文件上下文: 输入
@
后跟文件名(支持模糊搜索和自动补全),可以将文件内容注入到对话中,为 AI 提供充足的分析背景。例: "请分析
@./src/main.py
这个文件中的代码,并找出潜在的性能瓶颈。"执行特殊指令: 输入
@
后,补全菜单还会显示一系列内置指令,用于快速控制对话或执行常用操作。例: 输入
@Summary
并提交,可以要求 Jarvis 对之前的对话进行总结。以下是所有可用的内置特殊指令:

分解复杂任务: 对于复杂的任务,将其分解为更小、更具体的步骤,并引导 Jarvis 逐步完成。
3. 人工介入与控制 (Human-in-the-Loop)
Jarvis 的一个核心特性是支持在任务执行的任意阶段进行人工介入。
执行前确认: 在执行可能产生影响的操作(如运行脚本、修改文件)之前,Jarvis 会暂停并请求您的确认
[Y/n]
。这是第一层防护。思考后介入 (
Ctrl+C
): 这是最关键的介入方式。当 AI 正在“思考”(即大模型正在生成下一步计划)时,您可以随时按下
Ctrl+C
。Jarvis 不会立即打断模型的思考,而是会等待当前思考步骤完成(即 API 返回结果)。
在执行模型生成的计划(如调用工具)之前,系统会检测到中断信号,暂停执行并提示您:
"模型交互期间被中断,请输入用户干预信息:"
。这为您提供了一个审查并否决 AI 下一步行动的宝贵机会。您可以输入新指令来纠正它,或直接拒绝它即将执行的工具调用。
工具调用裁决: 这是“思考后介入”的具体体现。当您中断了一个即将发生的工具调用时,系统会询问您是否继续处理该工具。这让您拥有对每一步具体操作的最终决定权。
强制退出 (多次
Ctrl+C
): 如果您希望立即终止整个 Jarvis 程序,而不想等待当前思考步骤完成,可以快速连续按下Ctrl+C
五次以上(或长按)。这将触发系统的强制退出机制。
4.2 通用代理 (jarvis
/ jvs
)
jvs
是您的通用 AI 助手,适用于各种开放式、非特异性的任务。
核心能力
任务分析与规划: 理解复杂目标并拆解为执行步骤。
多工具协同: 智能选择并组合使用文件读写、代码执行、网页搜索等工具。
系统交互: 能够执行 Shell 命令与您的操作系统进行交互。
预定义任务: 支持从配置文件加载预设任务,简化重复性工作。
常用参数

示例
1. 交互式对话与预定义任务直接运行 jvs
会进入交互模式。如果存在预定义任务文件(~/.jarvis/pre-command
或 ./.jarvis/pre-command
),jvs
会首先列出这些任务供您选择,极大方便了日常操作的复用。
2. 直接执行任务让 Jarvis 分析当前项目结构并生成一份报告。
3. 解决环境问题当您遇到一个复杂的环境问题时,可以请求 Jarvis 帮助。
4.3 代码代理 (jarvis-code-agent
/ jca
)
jca
是专为软件开发任务设计的代理,是您日常编码、重构和调试的得力助手。
核心能力
深度代码集成: 自动分析代码库结构、依赖关系和最近的提交历史,为任务提供全面的上下文。
自动化 Git 工作流:
自动检查点: 在执行任务前,自动将任何未提交的本地修改创建为一个检查点(CheckPoint)提交。
增量式变更: 在 AI 的每一步操作(如修改文件)后,都会生成一个包含
diff
的补丁,并引导您确认是否将其 commit。任务后审查: 整个任务完成后,
jca
会列出所有由 AI 产生的提交,并让您最终确认是接受这些变更还是将代码库完全重置回任务开始前的状态。静态代码分析: 在生成代码修改后,会自动推荐并可运行
lint
工具进行静态分析,以确保代码质量。
常用参数

示例
1. 添加新功能在项目中添加一个新功能,jca
会自动查找相关文件并进行修改。
2. 修复 Bug 根据 Bug 描述修复问题。
3. 代码重构优化现有代码。
4.4 平台管理器 (jarvis-platform-manager
/ jpm
)
jpm
是您与底层大模型平台交互和管理的工具。
子命令
info
: 列出所有支持的平台和模型。chat
: 与指定的平台和模型进行交互式对话。service
: 将指定的模型以 OpenAI 兼容的 API 形式暴露出来。role
: 加载预定义的角色配置文件,选择角色后进行对话。
示例
1. 查看可用模型
2. 与特定模型聊天首先,使用 jpm info
查找您想使用的平台和模型名称。然后,通过 -p
和 -m
参数指定它们来开始对话。
在 chat
模式中,您还可以使用以下命令:
/bye
: 退出对话。/clear
: 清空当前会话历史。/upload <文件路径>
: 上传文件供 AI 分析(需要平台支持)。/shell <命令>
: 在本地执行 Shell 命令。/save <文件名>
: 将 AI 的最后一条回复保存到文件。/saveall <文件名>
: 将整个对话历史保存到文件。/save_session <文件名>
: 保存当前会话状态(可用于后续加载)。/load_session <文件名>
: 加载之前保存的会话状态。
3. 启动本地 API 服务将腾讯元宝模型封装为本地 API,供其他应用调用。当客户端请求未指定模型时,将默认使用元宝模型。
4. 加载角色进行对话使用角色配置文件(默认为 ~/.jarvis/roles.yaml
)来启动一个特定角色的对话。
4.5 Git 提交助手 (jarvis-git-commit
/ jgc
)
jgc
能自动分析您的代码变更,并生成符合规范的 Git 提交信息。
核心能力
自动分析
git diff
:jgc
会自动暂存 (git add .
) 您工作区中的所有变更,并分析其diff
内容。智能处理大型变更: 如果代码变更非常大,
jgc
会自动将diff
保存为临时文件并上传,而不是直接注入到提示词中,避免超出模型上下文限制。生成规范的提交信息: 基于代码变更,AI 会生成符合约定式提交(Conventional Commits)规范的提交信息。
完全可定制: 您可以通过配置文件自定义
jgc
的所有行为,包括提交信息模板和前后缀。
常用参数

示例与定制
1. 基本用法当您完成了一些代码修改后,只需在项目根目录运行:
Jarvis 将会分析变更,生成一条类似 feat(auth): add password reset endpoint
的提交信息,并自动执行 git commit
。
2. 添加前缀和后缀如果您希望在提交信息中包含任务 ID 或特定的标记,可以使用 --prefix
和 --suffix
:
生成的提交信息会变成类似:
3. 自定义提交模板 (高级)jgc
最强大的功能之一是允许您完全重写用于生成提交信息的提示词模板。您可以在 ~/.jarvis/config.yaml
文件中通过设置 JARVIS_GIT_COMMIT_PROMPT
变量来定义自己的模板。
首先,通过 jvs -e
打开配置文件,然后添加 JARVIS_GIT_COMMIT_PROMPT
变量:
通过自定义此模板,您可以让 jgc
完全遵循您团队的特定提交规范。
4.6 本地知识库 (jarvis-rag
/ jrg
)
jrg
用于构建和查询基于您自己文档的本地知识库。
工作原理
jrg
会读取您指定的文本文件,使用嵌入模型(Embedding Model) 将其内容转换为向量,并存储在本地的向量数据库中。当您提问时,它会:
将您的问题也转换为向量。
在数据库中检索与问题向量最相关的文档片段。
将这些文档片段和您的原始问题一起提交给大语言模型(LLM),由 LLM 生成最终的、基于上下文的答案。
子命令
add
: 添加文档(文件、目录、通配符)到知识库。list-docs
: 列出知识库中的所有文档。query
: 向您的知识库提问。
核心功能与定制
1. 智能文件过滤在添加文档时,jrg
会自动执行以下操作:
递归扫描: 自动遍历您指定的目录。
二进制文件检测: 自动跳过图片、可执行文件等非文本内容。
忽略规则: 默认情况下,
jrg
会遵循项目根目录下的.gitignore
规则。为了更精细地控制,您可以在项目根目录创建.jarvis/rag/.ragignore
文件,其优先级高于.gitignore
。这对于排除测试数据、大型日志文件或不想被索引的文档非常有用。
2. 构建知识库jrg add
命令支持递归地添加整个目录和多个文件。
您还可以使用 --collection
参数来管理多个独立的知识库,例如:
3. 查询知识库使用 jrg query
向知识库提问。默认情况下,它会查询名为 jarvis_rag_collection
的主知识库。
如果要查询特定知识库,或使用特定的 LLM(而非默认配置的思考模型)来生成答案,可以使用相应参数:
4. 列出已索引文档使用 jrg list-docs
可以查看指定知识库中包含了哪些源文件。
5. 自定义 RAG 模型jrg
默认使用 BAAI/bge-base-zh-v1.5
作为嵌入模型和 BAAI/bge-reranker-base
作为重排模型。您可以通过 config.yaml
文件来覆盖这些默认设置,以使用更适合您数据或硬件的模型。
例如,要切换到 moka-ai/m3e-base
嵌入模型,可以这样配置:
这个配置会让 jrg
在下一次构建或查询知识库时使用您指定的新模型。
4.7 智能 Shell (jarvis-smart-shell
/ jss
)
jss
是一个强大的工具,可以将您的自然语言指令转换为可执行的 Shell 命令,极大降低了在终端中执行复杂操作的门槛。
子命令
request [需求]
: 将自然语言需求转换为 Shell 命令。如果未提供需求,则进入交互式输入模式。install
: 为fish
shell 安装“命令未找到”处理器。uninstall
: 卸载fish
shell 的处理器。
示例
1. 直接转换命令当您不确定某个操作的命令时,可以直接向 jss
提问。它会打印出对应的 Shell 命令,但不会执行。
2. 交互式执行命令如果您直接运行 jss request
而不带任何参数,它会启动一个交互式输入界面。在这种模式下,您输入需求后,生成的命令将被立即执行。
3. 安装“命令未找到”处理器 (仅支持 Fish Shell)这是 jss
的一个强大功能,它能让您像使用自然语言一样操作终端。
安装后,当您在 fish
终端中输入一个系统不认识的命令(且长度大于 10 个字符,以防误触)时,jss
会自动拦截这个输入,将其转换为有效的 Shell 命令并执行。
4. 卸载处理器
4.8 代码审查 (jarvis-code-review
/ jcr
)
jcr
是您的自动化代码审查员,可以针对单个提交、文件或当前工作区的变更提供深入的分析和改进建议。
工作原理
jcr
的审查流程高度自动化和智能化:
变更提取: 根据您指定的模式(如单个提交、范围或文件),
jcr
会自动提取相应的代码diff
。语言检测: 它会分析变更文件的扩展名,自动识别涉及的编程语言(如 Python, Go, Java, TypeScript 等)。
注入审查清单: 对于每种识别出的语言,
jcr
会加载一个专门的审查清单(Checklist),并将其与代码变更一起注入到提示词中。全面审查框架 (SCRIPPPS): AI 会遵循一个名为 SCRIPPPS 的内置框架进行审查,该框架覆盖七个维度:Security(安全)、Correctness(正确性)、Reliability(可靠性)、Interface(接口)、Performance(性能)、Portability(可移植性)和 Structure(结构)。
生成报告: 最终,AI 会生成一份详细的 Markdown 格式的审查报告,其中包含对每个问题的分类、严重程度评级、详细描述和具体的修复建议。
子命令
commit <commit-sha>
: 审查指定的单个提交。current
: 审查您当前git
工作区中已暂存和未暂存的变更。range <commit1>..<commit2>
: 审查指定范围内的所有提交。file <文件路径...>
: 审查一个或多个文件。所有命令都支持
--root-dir <路径>
参数,允许您在项目外部对指定目录进行审查。
示例
1. 审查上一个提交
2. 审查当前所有变更在提交代码前,进行一次自我审查。jcr
会自动分析 git diff HEAD
的结果。
3. 审查指定范围的提交审查从 main
分支切出新功能分支以来的所有变更。
4. 审查单个或多个文件
4.9 高级 Git 工具
除了 jgc
,Jarvis 还提供了一系列高级 Git 工具来简化复杂操作。
交互式 Squash (jarvis-git-squash
/ jgs
)
jgs
可以帮助您将从某个指定提交之后的所有提交,自动合并(squash)成一个全新的、独立的提交,并为其生成一条清晰的、总结性的提交信息。这在合并多个小的功能提交或修复提交时非常有用。
工作原理
确认操作:
jgs
会首先请求您确认 squash 操作。重置(Reset): 它会执行
git reset --mixed <您指定的基础提交>
。这个操作会将HEAD
指针移回您指定的提交,同时保留这期间所有的代码变更在您的工作区。重新提交: 最后,
jgs
会调用jgc
(Git 提交助手),将工作区中所有的变更作为一个全新的提交,并由 AI 分析这些变更,生成一条高质量的总结性提交信息。
参数

示例
假设您的提交历史如下,您想将 feat-a
, feat-b
, fix-c
这三个提交合并成一个。
运行以下命令,其中 c1a2b3d
是您希望保留的最后一个提交的哈希值:
jgs
会自动完成上述的 reset
和重新提交工作,最终您的提交历史会变成:
4.10 多智能体协作 (jarvis-multi-agent
/ jma
)
jma
是一个强大的多智能体(Multi-Agent)协作框架,它允许您定义一组具有不同角色和能力的 AI 智能体,并通过自动化的消息路由机制,让它们协同工作以完成复杂任务。
工作原理
jma
的核心是一个基于 YAML 配置的协作系统:
定义智能体: 您在一个 YAML 文件中定义多个智能体,每个智能体都有自己的
name
(名称)、description
(描述)和system_prompt
(系统提示词),这决定了它的角色和能力。指定主智能体: 在配置中,您需要指定一个
main_agent
,作为整个任务的入口和协调者。消息驱动的协作: 当一个智能体需要另一个智能体的帮助时,它会生成一个特殊的
<SEND_MESSAGE>
消息块。jma
框架会自动捕获此消息,并将其路由给指定的目标智能体。自主运行: 这个过程会持续进行,直到主智能体认为任务完成,不再发送新的消息为止。
核心参数

示例:构建一个市场研究团队
假设我们想创建一个由“市场研究员”和“报告撰写者”组成的团队,来分析一个产品的市场潜力。
1. 创建配置文件 market_research.yaml
首先,我们定义两个智能体和它们的工作流程:
2. 运行 jma 现在,我们可以使用这个配置文件来启动多智能体系统,并给它分配一个任务:
执行流程:
任务首先被发送给
MarketResearcher
。MarketResearcher
会调用search_web
工具搜索“AI 代码助手”的相关信息。完成研究后,
MarketResearcher
会生成一条<SEND_MESSAGE>
发送给ReportWriter
,内容是它的研究总结。ReportWriter
接收到信息后,会撰写并输出最终的市场分析报告。
4.11 工具管理 (jarvis-tool
/ jt
)
jt
是与 Jarvis 工具系统交互的命令行界面,它不仅能让您查看和调用现有工具,更是您扩展 Jarvis 能力的重要入口。
子命令
list
: 列出所有 AI 可用的工具。call <工具名>
: 直接从命令行调用一个工具。stat
: 显示每个工具被 AI 调用的频率统计。
核心功能与示例
1. 查看工具list
命令是探索 Jarvis 能力的起点。
2. 调用工具call
命令允许您直接测试或使用任何一个工具。
3. 查看工具使用统计stat
命令可以帮助您了解哪些工具被 AI 使用得最频繁。
扩展 Jarvis 工具
jt
真正的强大之处在于其可扩展性。Jarvis 会从以下位置自动加载工具,让您可以轻松添加新功能:
方式一:通过 Python 文件添加工具您可以将自定义的工具脚本(遵循特定的类结构)放置在以下目录中,Jarvis 启动时会自动加载它们:
~/.jarvis/tools/
在
config.yaml
中由JARVIS_TOOL_LOAD_DIRS
变量指定的其他目录。
如果这些目录是 Git 仓库,Jarvis 还会每日自动执行 git pull
来保持工具更新。
方式二:通过 MCP (Model Context Protocol) 添加工具 MCP (模型上下文协议) 是一种更高级的集成方式,它允许 Jarvis 与外部服务(如另一个 AI 模型、API 服务等)进行通信,并将该服务的能力封装为 Jarvis 工具。您可以通过在 ~/.jarvis/mcp/
目录下创建 .yaml
配置文件,或直接在主 config.yaml
中定义 JARVIS_MCP
列表来注册 MCP 工具。
通过这两种方式,您可以不断地为 Jarvis 赋予新的能力,使其能解决更多领域的问题。
4.12 方法论管理 (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 从中学习,并形成自己的方法论。
执行后,如果您再次向 Jarvis 提出类似“我的 Pod 启动不了”的问题,它就会优先参考刚刚学到的这套方法论来解决问题。
2. 查看、备份和分享方法论
版权声明: 本文为 InfoQ 作者【SkyFire】的原创文章。
原文链接:【http://xie.infoq.cn/article/8705bc205f22a068ad750e85a】。
本文遵守【CC-BY 4.0】协议,转载请保留原文出处及本版权声明。
评论