@code4bug/jarvis-agent

v1.4.3

Published

9 days ago

基于 React + TypeScript + Ink 构建的命令行智能体交互界面

0High
0Medium
0Low

code4bug

cli agent ai chatbot ink react typescript terminal

Jarvis

Jarvis 是一个运行在终端里的轻量级 AI Agent，基于 React + TypeScript + Ink 构建，提供多轮对话、工具调用、流式输出、外部 Skill 扩展，以及多智能体协作能力。

它的目标不是做一个“会聊天的命令行”，而是让你在终端里直接完成读取代码、搜索文件、执行命令、拆分子任务、汇总结果这一整套工作流。

核心能力

Agentic Loop：模型可连续推理、调用工具、读取结果并继续决策
流式终端交互：回复与状态实时刷新
内置工具：读写文件、执行命令、目录遍历、文本搜索、语义搜索
外部 Skill：支持从 ~/.jarvis/skills/ 动态加载 Markdown 或 Python Skill
多智能体协作：支持同步子 Agent、后台子 Agent 与消息总线通信
会话持久化：自动保存历史会话、摘要与 Token 统计
长期记忆：支持写入 ~/.jarvis/MEMORY.md
安全围栏：危险命令识别、确认与持久授权
并行执行：多个只读工具可并行运行，提升响应效率

项目结构

src/
├── index.tsx                # 应用入口
├── cli.ts                   # CLI 入口
├── agents/                  # 智能体定义
├── commands/                # 斜杠命令
├── components/              # Ink UI 组件
├── config/                  # 配置、常量、记忆与状态
├── core/                    # QueryEngine、Worker、消息总线、安全围栏
├── hooks/                   # 交互相关 Hooks
├── screens/                 # 主界面
├── services/                # LLM 接口、用户画像、长期记忆服务
├── skills/                  # 外部 Skill 加载器
├── tools/                   # 内置工具实现
└── types/                   # 类型定义

快速开始

方式一：直接使用已发布包

npm i -g @code4bug/jarvis-agent
jarvis

方式二：从源码运行

pnpm install
pnpm dev

也可以使用项目内脚本：

pnpm build
pnpm start

模型配置

Jarvis 会按下面顺序加载配置，后者覆盖前者：

~/.jarvis/config.json
./.jarvis/config.json

示例：

{
  "system": {
    "model": "default",
    "context_token_limit": 18000,
    "context_compress_threshold": 18000,
    "enable_thinking_mode_toggle": false
  },
  "models": {
    "default": {
      "api_url": "https://your-api-endpoint",
      "api_key": "your-api-key",
      "model": "your-model-id",
      "temperature": 0.7,
      "max_tokens": 4096,
      "extra_body": {
        "enable_thinking": true
      }
    }
  }
}

说明：

system.model 对应 models 里的 key
extra_body 会直接合并进请求体，方便兼容不同服务商

首次启动配置

如果未检测到可用的全局配置，Jarvis 启动时会先进入首次配置向导，而不是直接进入主界面。

当前配置向导支持两种接入方式：

OpenAI 兼容接口
Ollama / 本地模型

配置写入位置：

~/.jarvis/config.json

项目目录下的 ./.jarvis/config.json 仍可作为本地覆盖配置使用。

常用命令

CLI

jarvis
jarvis --version

斜杠命令

| 命令 | 说明 | | --- | --- | | /init | 扫描当前项目并生成 JARVIS.md | | /about | 查看 Jarvis 的详细特性、功能与信息 | | /new | 开启新会话 | | /resume | 恢复历史会话 | | /resume <ID> | 直接恢复指定历史会话 | | /rewind | 打开当前会话提问列表并回退到指定位置 | | /agent | 打开智能体切换列表 | | /agent <名称> | 切换智能体，重启后生效 | | /permissions | 查看持久化授权 | | /skills | 查看当前工具与外部 Skill | | /session_clear | 清理非当前会话历史 | | /version | 显示版本 | | /help | 显示帮助 | | /create_skill <描述> | 根据描述创建新的 Skill | | /exit | 退出应用 | | /quit | 退出应用 | | /bye | 退出应用 | | /read <路径> | 以工具方式读取文件 | | /write <路径> | 以工具方式写入文件 | | /bash <命令> | 以工具方式执行命令 | | /ls <路径> | 以工具方式列出目录 | | /search <关键词> | 以工具方式搜索文件内容 |

快捷键

| 快捷键 | 说明 | | --- | --- | | Ctrl + L | 清屏并开始新会话 | | Ctrl + C | 3 秒内连续按两次退出 | | Ctrl + O | 切换详情视图 | | Esc | 中断当前任务；空闲时双击清空输入 | | Alt/Option + Enter | 输入换行 | | Tab | 输入为空时填入提示词；在斜杠菜单中补全当前项 | | ? + Enter | 输出快捷键帮助信息 |

输入与交互

输入 / 可打开斜杠菜单
斜杠菜单中可使用 ↑ / ↓ 切换命令
在斜杠菜单中按 Tab 可补全当前命令
在斜杠菜单中按 Enter 可提交当前命令
输入 /rewind 后可列出当前会话的提问列表，按时间从上到下升序排列
在 /rewind 列表中选择某条提问后，会把该提问回填到输入框，并丢弃该位置之后的上下文
对于多行输入，↑ / ↓ 用于在输入框内移动光标
对于单行输入，↑ / ↓ 用于切换历史输入

内置工具

当前内置工具包括：

| 工具名 | 说明 | | --- | --- | | read_file | 读取文件 | | write_file | 写入文件，支持整文件覆盖或局部修改 | | run_command | 执行命令 | | list_directory | 列出目录内容 | | search_files | 搜索文件内容 | | semantic_search | 语义搜索 | | create_skill | 创建外部 Skill | | run_agent | 同步运行子 Agent | | spawn_agent | 异步启动后台子 Agent | | send_to_agent | 向后台子 Agent 发送消息 | | publish_message | 发布频道消息 | | subscribe_message | 订阅频道消息 | | read_channel | 查看频道历史 | | manage_memory | 读取或维护长期记忆 |

多智能体能力

Jarvis 同时支持两种子 Agent 模式：

run_agent：同步执行，主 Agent 等待结果后继续
spawn_agent：后台执行，主 Agent 通过消息总线持续协作

后台子 Agent 的默认通信频道约定如下：

收件箱：agent-inbox:{task_id}
回复：agent-reply:{task_id}

这套机制适合把复杂任务拆成多个独立子任务，例如代码审查、资料整理、命令执行验证、结果汇总等。

更多设计说明见 AGENT_INSTRUCTIONS.md。

Agent 与 Skill

内置 Agent

内置 Agent 定义位于 src/agents/，当前仓库已包含：

jarvis
code-reviewer
dba
finance-advisor
stock-trader

Agent 通过 Markdown 文件定义元信息与系统提示词，切换结果会持久化到 ~/.jarvis/agent.json。

外部 Skill

外部 Skill 目录：

~/.jarvis/skills/<skill-name>/
├── SKILL.md
└── skill.py   # 可选

支持两种模式：

仅 SKILL.md：作为指令型 Skill 由模型解释执行
SKILL.md + skill.py：作为可执行 Skill 直接运行 Python 脚本

相关说明见 SKILL_INSTRUCTIONS.md。

会话、记忆与安全

会话与日志

会话目录：~/.jarvis/sessions/
日志目录：~/.jarvis/logs/

每次会话会保存消息、摘要、更新时间和累计 Token。

支持能力：

/resume 从列表恢复历史会话
/resume <ID> 直接恢复指定会话
/session_clear 清理除当前会话外的历史记录

长期记忆

记忆文件：~/.jarvis/MEMORY.md
通过 manage_memory 工具进行读取、追加、覆盖和定位

安全围栏

run_command 会经过统一安全校验，内置规则会拦截高风险命令，例如：

递归删除
直接格式化磁盘
修改关键权限
网络下载后直接执行

高风险命令支持会话级或持久化授权，持久化记录保存在 ~/.jarvis/.permissions.json。

开发

pnpm install
pnpm build
pnpm test

当前 test 脚本实际执行的是一次构建校验：

npm run build

License

MIT