# jace-cli

**Repository Path**: SapientialM/jace-cli

## Basic Information

- **Project Name**: jace-cli
- **Description**: 一个成熟的 Java Agent CLI 产品，但更偏向于 Agent 框架学习与搭建。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-13
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# JaceCLI

一个面向商业使用的 Java Agent CLI 产品,Java 17 + Maven,内置 11 个工具 + 6 个 LLM provider,支持 MCP / Skill / HITL / Side-History 快照 / LSP 诊断 / JACE.md 项目记忆 / Prompt 分层 / TUI 三形态。

详细的演进路线见 [`ROADMAP.md`](ROADMAP.md),按 14 个功能领域(F01-F14)组织;每个领域的开发任务在 `docs/feature-*.md`。

## 功能速览(按领域)

- **F01 Agent Loop**:ReAct / Plan-and-Execute / Multi-Agent(Planner + Worker + Reviewer)/ Fork Agent / Session 持久化
- **F02 Memory & Context**:短期 + 长期记忆、四级压缩引擎、长/短上下文双模式、JACE.md 项目记忆、Prompt 分层架构(`PromptAssembler` + 13 个 markdown 资源)
- **F03 Tool System**:11 个内置工具 + 并行执行 + 路径围栏 + 命令黑名单 + JSONL 审计 + Git Side-History 快照 + LSP 诊断注入
- **F04 Codebase Understanding**:Ollama / 远程 API embedding + SQLite 向量存储 + AST 关系图谱
- **F05 LLM Providers**:6 个 provider(GLM / DeepSeek / Step / Kimi / FreeLLMAPI / Xfyun)+ 共享 `PromptCache`
- **F06 Web & Network**:`web_search`(智谱 / SerpAPI / SearXNG)+ `web_fetch` + `NetworkPolicy`(SSRF 围栏 / 限流 / 5MB 上限)
- **F07 MCP Protocol**:stdio + Streamable HTTP + resources 双轨 + prompts 查看 + 被动通知;OAuth / sampling 延后
- **F08 Browser & CDP**:Chrome DevTools MCP + 登录态复用 + `/browser` CLI
- **F09 Safety**:HITL 审批(y/a/n/s/m)+ `PathGuard` / `CommandGuard` / `AuditLog` JSONL
- **F10 Skill System**:三级加载 + L1 元数据 + L2 触发 + 7 个内置 skill(6 站点经验)
- **F11 TUI Renderer**:inline / lanterna / plain 三形态
- **F12 Runtime API & Background Tasks**:`/task` CLI + DurableTaskManager
- **F13 Image Input & Channel**:`@image:` / `@clipboard` 解析 + Channel 抽象
- **F14 Session Export**:`/export` 把会话导出为 Markdown

## 快速开始

### 1. 配置 API Key

复制 `.env.example` 为 `.env`,并填入你的 API Key:

```bash
cp .env.example .env
# 编辑 .env 文件,填入你的 API Key
```

或者在环境变量中设置:

```bash
export GLM_API_KEY=your_api_key_here
# 其他 provider 可选
export DEEPSEEK_API_KEY=...
export STEP_API_KEY=...
export KIMI_API_KEY=...
export FREELLMAPI_API_KEY=...
export XFYUN_MAAS_API_KEY=...
```

启动界面会按 `.env` → 用户 `~/.env` → 环境变量 → 配置文件 `~/.jacecli/config.json` 的顺序读取。

也可以在 CLI 内用命令写入 `~/.jacecli/config.json`,不会覆盖其他 provider:

```text
/config provider kimi --api-key <key> --model kimi-k2.6
/model kimi
```

### 2. 启动 Ollama(可选,RAG 用)

```bash
nohup ollama serve > /tmp/ollama.log 2>&1 &
ollama pull nomic-embed-text
```

### 3. 可选:配置 MCP server

`MCP` 子系统默认开启。`~/.jacecli/mcp.json` 不存在时,不会启动外部 server;创建文件后重启即可加载:

```json
{
  "mcpServers": {
    "fetch": {"command": "uvx", "args": ["mcp-server-fetch"]},
    "git": {"command": "uvx", "args": ["mcp-server-git", "--repository", "${PROJECT_DIR}"]},
    "remote-demo": {"url": "https://mcp.example.com/v1", "headers": {"Authorization": "Bearer ${REMOTE_TOKEN}"}}
  }
}
```

`command` 表示 stdio server,`url` 表示 Streamable HTTP server。`${PROJECT_DIR}` / `${HOME}` 是内置变量,其他 `${VAR}` 从环境变量读取。

### 4. 编译运行

```bash
# 编译(默认跳过测试,产出可手工验收的 jar)
mvn clean package

# 运行
java -jar target/jacecli-1.0-SNAPSHOT.jar

# 或直接运行
mvn clean compile exec:java -Dexec.mainClass="com.jacecli.cli.Main"
```

### 5. 常用斜杠命令(全部命令)

| 命令 | 用途 |
|---|---|
| `/plan` / `/plan <任务>` | 下一条任务用 Plan-and-Execute 模式 |
| `/team` / `/team <任务>` | 下一条任务用 Multi-Agent 协作模式 |
| `/cancel` | 任务运行中请求取消 |
| `/hitl on` / `/hitl off` / `/hitl` | 启用 / 关闭 / 查看 HITL 审批 |
| `/mcp` | 查看所有 MCP server 状态 |
| `/mcp add` | 交互式添加 MCP server |
| `/mcp remove` / `/mcp restart` / `/mcp logs` / `/mcp disable` / `/mcp enable` / `/mcp resources` / `/mcp prompts` | MCP server 管理 |
| `/policy` / `/audit [N]` | 安全策略状态 / 最近审计 |
| `/snapshot` / `/snapshot list` / `/snapshot status` / `/restore <N>` | Side-History 快照与回滚 |
| `/browser` / `/browser connect` / `/browser disconnect` / `/browser tabs` | 浏览器会话 |
| `/memory` / `/mem` / `/memory clear` / `/save <事实>` | 长期记忆 |
| `/init` / `/init --force` | 生成 JACE.md(项目级 LLM 记忆) |
| `/index [路径]` / `/search <查询>` / `/graph <类名>` | RAG 索引 / 语义检索 / 关系图 |
| `/context` / `/ctx` | 上下文状态(分类占比、阈值、cache) |
| `/session [list\|save\|load\|new]` | 会话持久化 |
| `/compress [micro\|summary\|full]` | 手动压缩 |
| `/fork status` | 活跃 Fork Agent |
| `/skill` / `/skill on\|off <name>` / `/skill reload` / `/skill show <name>` | Skill 系统 |
| `/task` / `/task add\|cancel\|log` | 后台任务 |
| `/export` | 导出当前会话为 Markdown |
| `/clear` | 清空对话历史 |
| `/exit` / `/quit` | 退出程序 |

### 6. 如何进入 Plan 模式

默认模式是 `ReAct`。进入 `Plan-and-Execute` 用 `/plan`:

1. 输入 `/plan`
2. 下一条任务会用计划模式执行
3. 执行完成后自动回到默认 `ReAct`

如果想一条命令切模式并执行任务,可以直接输入:

```text
/plan 创建一个 demo 项目,然后读取 pom.xml,最后验证项目结构
```

计划生成后,CLI 会先停下来等待确认:

- 按 `Enter`:按当前计划执行
- 按 `Ctrl+O`:展开完整计划
- 按 `ESC`:折叠完整计划或取消本次计划
- 按 `I`:输入补充要求并重新规划
- 按方向键不会触发取消;只有单独按下 `ESC` 才会取消待执行 plan

## 可用工具

11 个内置工具 + MCP 动态:

- `read_file` - 读取文件(支持 `offset/limit` 按行分片)
- `write_file` - 写入文件
- `list_dir` - 列出目录
- `execute_command` - 在当前项目目录执行短时 Shell 命令(默认 60 秒超时,黑名单拦截)
- `create_project` - 创建项目结构(java/python/node)
- `glob_files` - 按 glob 模式定位文件(自动跳过 `.git/` `target/` `node_modules/`)
- `grep_code` - 按关键字/正则搜索(优先 ripgrep)
- `search_code` - 语义检索代码(RAG)
- `web_search` - 联网搜索
- `web_fetch` - 抓取 URL 提取 Markdown
- `mcp__{server}__{tool}` - MCP server 动态提供的工具

同一轮模型返回多个工具调用时,JaceCLI 会并行执行;如果工具之间有依赖关系,模型应分多轮调用。

文件类工具路径强制限定在项目根之内,越界请求会被策略层拒绝;`execute_command` 通过命令黑名单拦截 `sudo` / `rm -rf 全盘` / `mkfs` / `dd of=/dev` 等。所有 `mcp__` 前缀工具默认触发 HITL 和审计。详见 `/policy`。

## 技术栈

- **Java 17** + **Maven** — 语言与构建
- **OkHttp 4.12** — HTTP 客户端,SSE 流式响应
- **Jackson 2.16** — JSON 序列化 / 反序列化
- **JLine 3.26** — 终端交互、raw mode、自动补全、ANSI
- **SQLite** — 向量存储、代码图谱持久化
- **JavaParser 3.28** — Java AST 解析与代码关系分析
- **Jsoup 1.18** — HTML 正文提取(`web_fetch`)
- **Jieba** — 中文分词(记忆检索与 RAG 查询)
- **JGit 7.6** — Side-History 快照
- **Lanterna 3.1** — 全屏 TUI 渲染
- **ZXing 3.5** — 终端二维码(通道扫码)
- **Logback 1.5** — 日志滚动落盘
- **JUnit 5 + Mockito 5.11** — 单元测试(75+ 测试文件,607 通过 / 0 失败 / 4 skipped)

## 项目结构

```text
src/main/java/com/jacecli/
├── agent/             # F01 ReAct / Plan / Team / Fork
├── cli/               # Main / CliCommandParser / PlanReviewInputParser / SlashCommandCompleter
├── config/            # JaceCliConfig
├── hitl/              # F09 审批
├── llm/               # F05 6 个 provider + PromptCache
├── memory/            # F02 短期/长期/压缩/Token 预算
├── plan/              # 任务 DAG
├── policy/            # F09 路径围栏 / 命令黑名单 / 审计
├── prompt/            # F02 JACE.md / PromptAssembler / PromptRepository
├── rag/               # F04 RAG / 嵌入 / 分块
├── render/            # F11 TUI Renderer 三形态
├── runtime/           # F12 DurableTaskManager / (F12 RuntimeApiServer 待实现)
├── skill/             # F10 Skill 加载 / 状态 / 上下文缓冲
├── snapshot/          # F03 Side-Git 快照
├── lsp/               # F03 LSP 诊断
├── browser/           # F08 浏览器会话
├── image/             # F13 图片输入
├── channel/           # F13 通道抽象
├── export/            # F14 Session 导出
├── tool/              # F03 工具注册 + 并行执行
├── util/              # AnsiStyle / TerminalMarkdownRenderer / JiebaSegmenterFactory
├── web/               # F06 搜索 / 抓取 / 网络策略
└── mcp/               # F07 MCP 协议
```

测试代码在 `src/test/java/com/jacecli/` 下,75+ 测试文件覆盖 23 个模块。

## 贡献

欢迎提交 Issue 与 Pull Request。改动前请先阅读 `AGENTS.md` 了解协作规则与联动要求:

- **改行为不只改代码** — 同步检查 `README.md`、`AGENTS.md`、`ROADMAP.md` 是否需更新
- **改工具集联动提示词** — 新增 / 删除 / 修改工具要同步更新 4 个 Agent 系统提示词(由 `PromptAssembler` 接管时直接改 markdown 资源即可)
- **不提交敏感信息** — `.env`、真实 API Key、`target/` 产物不进入版本控制
- **提交前跑测试** — `mvn test` 应全部通过(607 通过 / 4 skipped)

## 致谢

本项目部分代码基于 [itwanger](https://gitee.com/itwanger) 的开源作品开发,原作品采用 [Apache 2.0] 许可证,特此感谢。

## License

[Apache 2.0](LICENSE) © 2026 SapientialM