# 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-05-15 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # JaceCLI 一个成熟的 Java Agent CLI 产品。 ## 演进历程 ### 第一期：ReAct Agent CLI - 单轮对话驱动的 `ReAct` 循环 - 支持工具调用：读文件、写文件、列目录、执行命令、创建项目、代码语义检索、联网搜索、MCP 动态工具 - 更适合简单任务或单步操作 ### 第二期：Plan-and-Execute + DAG - 在保留 `ReAct` 模式的基础上新增复杂任务规划能力 - 支持先拆解任务，再按照依赖顺序执行 - 新增 `/plan` 入口，以一次性计划执行方式增强默认的 `ReAct` - 计划生成后，会先与用户确认再执行 - 更适合多步骤、带依赖关系的复杂任务 ### 第三期：Memory + 上下文工程 - 短期记忆管理当前对话与工具结果 - 长期记忆通过 `/save <事实>` 手动保存关键事实，跨会话复用 - 注入给模型的相关记忆只使用长期稳定事实，不把当前轮短期对话误当成“历史记忆” - 对话接近预算时自动做摘要压缩 - 新增 `/memory` 查看状态、`/memory clear` 清空长期记忆、`/save` 手动保存事实 ### 第四期：RAG 检索 + 代码库理解 - 代码向量化（Embedding），支持本地 Ollama 和远程 API - SQLite 持久化 + 余弦相似度语义检索 - 代码分块（文件/类/方法粒度）与 AST 解析 - 代码关系图谱（extends/implements/imports/calls/contains） - 新增 `/index`、`/search`、`/graph` CLI 命令 - Agent 自动调用 `search_code` 工具理解代码库 ### 第五期：Multi-Agent 协作 + 角色分工 - 三个角色：规划者（Planner）、执行者（Worker）、检查者（Reviewer） - 主从架构：编排器（Orchestrator）协调子代理（SubAgent） - 规划者拆解任务 -> 执行者执行 -> 检查者审查质量 - 审查未通过时带反馈重试（最多 2 次），冲突自动解决 - 新增 `/team` CLI 命令，进入多 Agent 协作模式 ### 第六期：Human-in-the-Loop + 审批流 - 危险操作静态规则识别：`write_file`、`execute_command`、`create_project` - 三级危险等级：高危（`execute_command`）、中危（`write_file` / `create_project`） - 审批决策：批准 / 全部放行 / 拒绝 / 跳过 / 修改参数后执行 - HITL 默认关闭，通过 `/hitl on` 启用 - 新增 `/hitl` CLI 命令，支持 `/hitl on`、`/hitl off`、`/hitl`（查看状态） ### 第七期：异步执行 + 并行工具调用 - 同一轮 LLM 返回多个 `tool_calls` 时，工具层会并行执行 - ReAct、Plan-and-Execute、Multi-Agent Worker 都复用统一的批量工具执行入口 - 工具结果仍按原始 `tool_call` 顺序回灌，保证消息历史协议稳定 - 批量工具调用有统一超时与取消兜底，单个 `execute_command` 仍保留 60 秒命令级超时 - Plan-and-Execute 与 Multi-Agent 已支持按依赖批次并行执行独立任务 ### 第八期：多模型适配 + 运行时切换 - `LlmClient` 接口抽象 + `AbstractOpenAiCompatibleClient` 模板基类 - 内置 `GLMClient`、`DeepSeekClient` 两个瘦实现，各约 20 行 - `/model glm` / `/model deepseek` 运行时切换当前对话模型 - 配置持久化到 `~/.jacecli/config.json`，API Key 从 `.env` 回退读取 ### 第九期：联网能力 + Web 工具 - `web_search` 抽象成 `SearchProvider` 接口，内置三个实现：智谱 Web Search（默认，与 GLM 共用 Key，0.01–0.05 元/次）、SerpAPI（国际通用付费）、SearXNG（开源自托管免费） - `web_fetch` 新工具：URL → OkHttp 抓取 → Jsoup 解析 → 简易 readability → Markdown 正文 - 默认安全策略：屏蔽 `file://` / 内网 / loopback；30 秒超时；5MB 响应上限；每分钟 30 次限流 - 边界明确：SPA / 防爬墙站点会返回空正文 + 已知边界提示，不反复重试，留给后续 CDP 路线 ### 第十期：MCP 协议核心 - 新增 `com.jacecli.mcp` 模块，支持 stdio 子进程 server 与 Streamable HTTP 远程 server - 启动时读取 `~/.jacecli/mcp.json` 与 `.jacecli/mcp.json`，项目级配置按 server 名覆盖用户级配置 - MCP 工具自动注册为 `mcp__{server}__{tool}`，参数 schema 会清洗 `$ref` / `anyOf` / 超长 description，降低模型调用失败率 - 所有 MCP 工具默认走 HITL 审批和审计，审计参数会脱敏 token / key / password / Authorization / Bearer 凭证 - CLI 命令：`/mcp`、`/mcp restart `、`/mcp logs `、`/mcp disable `、`/mcp enable ` - 没有 MCP 配置文件时不会启动外部 server；子系统保持开启，创建配置后重启 JaceCLI 即可加载 ### 第十一期：MCP 高级能力（resources 双轨） - 支持 MCP resources：server 声明 `resources` capability 后，自动注册 `mcp__{server}__list_resources` / `mcp__{server}__read_resource` 两个虚拟工具 - 普通输入支持 `@server:protocol://path` 显式引用 resource，提交给 Agent 前展开为 `` 内联块 - JLine 自动补全会基于启动时缓存的 resources 提供 `@...` 候选，不干扰 Plan / Team 的 raw-mode 单键交互 - 新增 `/mcp resources ` 查看资源列表，`/mcp prompts ` 查看 prompt 模板 - 被动处理 `notifications/tools/list_changed`、`notifications/resources/list_changed`、`notifications/resources/updated` - 运行中输入 `/cancel` 并回车可请求取消当前 Agent run；ReAct、Plan、Team、工具批次和 `execute_command` 会协同检查取消信号 - OAuth 与 `sampling/createMessage` 已确认延后，不属于本期交付 ### 第十二期：长上下文工程（256K–1M + Fork Agent + 四级压缩）✅ - **动态上下文窗口**：默认 256K，按模型能力动态设定（GLM-5.1=200K，DeepSeek V4 Pro=1M） - **ModelCapabilities**：`LlmClient.getCapabilities()` 声明 contextWindow、maxOutputTokens、cachingType - **Fork Agent 机制**：独立 LlmClient 实例 + 共享 PromptCache 对象，最大化服务端 cache 命中 - **PromptCache**：管理 `provider:model:systemPromptHash` cache key、system prompt 一致性校验、GLM `enable_prompt_cache` / DeepSeek auto_prefix 标记注入 - **四级压缩策略**（`CompressionEngine`）： - L1 微量压缩：清理超过 3 条的旧工具结果，按实际字符数估算节省量，零 API 调用 - L2 会话记忆压缩：后台 `SessionSummarizer`(ForkAgent) 预生成摘要，压缩时直接复用 - L3 传统压缩：Fork 子 Agent 调用 LLM 生成高质量摘要 - L4 反应式压缩：API 返回 `prompt_too_long` 时滑动窗口剥离旧消息组 - **上下文滥用防护**：`read_file` 单次 30K chars 上限、`list_dir` 10K 上限；所有工具结果注入对话前截断至 30K chars - **有效窗口公式**：`contextWindow - min(min(maxOutputTokens, 8K), 20K)`（预留输出空间 ≤ 8K） - **四级阈值**：AutoCompact(有效-13K) / Warning(AutoCompact-20K) / Blocking(有效-3K) - **断路器**：连续 3 次整链失败 → 停止自动压缩；手动 `/compress full` 成功 → 重置 - **长/短双模式**：≥ 100K 为长模式，RAG top-K 5→20，代码片段 800→3000 chars - **动态内容注入**：MCP resources + 长期记忆作为独立低位 user message 注入（保持 system prompt 稳定，最大化 PromptCache 命中） - **后台 SessionSummarizer**：长模式自动启动，每 5 分钟/10 轮用 ForkAgent 生成会话摘要 - **上下文成本可见化**：每轮打印 `📊 {in}/{out}/{total} | cached: {N} | {used}/{effective} ({pct}%)`，所有 token 数值统一 K 单位（XXX.XK） - **上下文可视化**：`/context` 显示分类占比（系统提示/注入消息/工具定义/用户消息/助手消息/工具结果/空闲空间），带可视化进度条 - **`/help`**：列出所有可用命令（含斜杠命令 Tab 自动补全） - **`/session`**：会话持久化到 `~/.jacecli/sessions/`（save/load/list/new），上限 50 个 - **`/compress [micro|summary|full]`**：手动触发指定级别压缩 - **`/fork status`**：查看后台 Fork Agent 活跃状态 - **CLI 分隔线**：`── jace input ──` / `── jace ──` 动态适配终端宽度 ### 第六期 HITL 增强（路径围栏 / 命令快速拒绝 / 操作审计） `com.jacecli.policy` 包，作为 HITL 之外的辅助层（不是沙箱、不提供进程隔离）： - `PathGuard` 路径围栏：文件类工具强制限定在项目根之内，拦截绝对路径外逃 / `..` 穿越 / 符号链接逃逸 - `CommandGuard` 命令快速拒绝：HITL 之前的 fast-fail 黑名单（`sudo` / `rm -rf 全盘` / `mkfs` / `dd of=/dev` / fork bomb / `curl|sh` / `find /` / `chmod 777 /` / `shutdown`），减少 HITL 弹窗骚扰 - `AuditLog` 结构化审计：危险工具调用按天写 JSONL 到 `~/.jacecli/audit/`，含 `outcome (allow|deny|error)` 与 `approver (hitl|policy|none)` - `write_file` 单文件 5MB 上限 - CLI 命令：`/policy` 查看安全策略状态、`/audit [N]` 看最近 N 条审计 **为什么不叫沙箱**：本地 Agent CLI（参考 Claude Code / Cursor / Aider）默认都不做容器/VM 沙箱——沙箱削弱 Agent 能力、给虚假安全感、体验更差。生产级 Agent 沙箱实际是 microVM-level（Devin / Modal / Anthropic Computer Use 用 Firecracker / gVisor）。JaceCLI 的安全模型是 **HITL + 路径校验 + 命令快速拒绝 + 审计**，不是隔离。 ## 启动界面 ### 当前启动界面 当前启动输出以命令行实际产物为准： ```text ╔══════════════════════════════════════════════════════════╗ ║ ║ ║ ██╗ █████╗ ██████╗███████╗██████╗ ██╗ ██╗ ║ ║ ██║██╔══██╗██╔════╝██╔════╝██╔═══╝ ██║ ██║ ║ ║ ██║███████║██║ █████╗ ██║ ██║ ██║ ║ ║██╗ ██║██╔══██║██║ ██╔══╝ ██║ ██║ ██║ ║ ║███████║██║ ██║╚██████╗███████╗╚██████╗███████╗██║ ║ ║╚══════╝╚═╝ ╚═╝ ╚═════╝╚══════╝ ╚═════╝╚══════╝╚═╝ ║ ║ ║ ║ Long-Context Agent CLI v12.0.0 ║ ║ ║ ╚══════════════════════════════════════════════════════════╝ 🔄 Using ReAct mode ``` ## 功能 ### 第一期 - 🤖 基于 GLM-5.1 的智能对话 - 🔄 ReAct Agent 循环（思考-行动-观察） - 🛠️ 工具调用（文件操作、Shell命令、项目创建、代码语义检索、联网搜索、MCP 动态工具） - 💬 交互式命令行界面 - 🧠 默认通过流式接口获取模型输出；ReAct 与用户可见的 Plan 阶段都会按流式展示思考过程与最终回复；ReAct 同一次用户输入只打印一次 `🧠 思考过程` 标题，工具调用前后的后续推理继续归在同一块下 - 🖥️ 终端会对常见 Markdown（标题、列表、表格、代码块）做渲染后再显示，避免直接暴露原始标记符号 ### 第二期 - 📋 Plan-and-Execute + DAG 任务拆解与顺序执行 - ⌨️ `/plan` 一次性进入计划执行 - 🧭 更清晰的复杂任务执行顺序与依赖展示 - ⚖️ 简单任务会自动生成最小计划，不再为了凑步数扩展无关步骤 ### 第三期 - 🧠 短期记忆、长期记忆与相关记忆检索 - 📦 长对话摘要压缩与 Token 预算管理 - 💾 `/memory` 与 `/save` 记忆管理入口 ### 第四期 - 🔍 代码库语义检索（自然语言搜代码） - 🕸️ 代码关系图谱（类继承、接口实现、方法调用） - 📡 本地 Ollama Embedding + 远程 API 可配置 - 🗃️ SQLite 向量存储与持久化 ### 第五期 - 👥 多 Agent 协作（规划者 + 执行者 + 检查者） - 🎯 主从架构编排器自动分配任务 - 🔍 检查者审查质量，未通过自动重试 - 🛠️ 执行者共享工具集，支持文件操作与代码检索 ### 第六期 - 🔒 危险操作静态规则识别（`write_file` / `execute_command` / `create_project`） - ⚠️ 三级危险等级展示（高危 / 中危 / 安全） - ✅ 审批决策：批准、全部放行、拒绝、跳过、修改参数后执行 - 🔓 HITL 默认关闭，`/hitl on` 启用、`/hitl off` 关闭 ### 第七期 - ⚡ 同一轮多个工具调用会并行执行，适合同时读取多个文件、同时列目录、同时跑独立检查 - 🧵 ReAct、Plan-and-Execute、Multi-Agent Worker 共用同一套并行工具执行机制 - ⏱️ 工具批次有统一超时，超时工具会被取消并把超时结果回灌给模型 - 📋 Plan-and-Execute 与 Multi-Agent 会按 DAG 依赖批次并行推进独立任务 ### 第八期 - 🔄 GLM-5.1 与 DeepSeek V4 双模型，`/model glm` / `/model deepseek` 运行时切换 - 🧱 `LlmClient` 接口 + 模板方法基类，新增 provider 只需 ~20 行 - 💾 默认模型持久化到 `~/.jacecli/config.json` ### 第九期 - 🌐 `web_search` 工具支持三条路：智谱 Web Search（与 GLM 共用 Key 默认推荐）、SerpAPI（国际通用付费）、SearXNG（开源自托管免费） - 📰 `web_fetch` 工具：抓 URL → readability 提取 → 返回 Markdown 正文 - 🛡️ 内置网络访问策略：屏蔽内网、loopback、`file://`；5MB 响应上限；每分钟 30 次限流 - 🚧 边界明确：SPA / 防爬墙返回空正文 + 已知边界提示，不重试 ### 第六期 HITL 增强 - 🛡️ 路径围栏：文件类工具强制限定在项目根之内，绝对路径外逃 / `..` 穿越 / 符号链接逃逸全部拦截 - 🧯 命令快速拒绝：HITL 之前的 fast-fail 黑名单（`sudo` / `rm -rf 全盘` / `mkfs` / `dd of=/dev` / fork bomb / `curl|sh` / `find /` / `chmod 777 /` / `shutdown`），减少 HITL 弹窗骚扰 - 📦 资源上限：`write_file` 5MB；`execute_command` 60 秒超时 + 8KB 输出截断 - 📋 结构化审计：危险工具调用按天写一行 JSONL 到 `~/.jacecli/audit/`，可通过 `/audit [N]` 查看 - 🧱 定位：HITL 之外的辅助层，不是沙箱、不提供进程隔离 ### 第十一期 - 📚 MCP resources 双轨：模型可调用 `mcp__{server}__list_resources` / `mcp__{server}__read_resource`，用户也可手动输入 `@server:protocol://path` - ⌨️ 普通输入支持 resource 自动补全，Plan / Team 审阅的 raw-mode 单键交互保持不变 - 🧩 `/mcp prompts ` 查看 server 暴露的 prompts，但不自动注入对话 - 🔄 被动响应 MCP list_changed / resources updated 通知，刷新工具列表或让 resource cache 失效 ## 快速开始 ### 1. 配置 API Key 复制 `.env.example` 为 `.env`，并填入你的 GLM API Key： ```bash cp .env.example .env # 编辑 .env 文件，填入你的 API Key ``` 或者在环境变量中设置： ```bash export GLM_API_KEY=your_api_key_here ``` 长期记忆默认保存在用户目录下的 `~/.jacecli/memory/long_term_memory.json`。 长期记忆只保存你显式通过 `/save` 写入的稳定事实，不应包含一次性任务请求或临时文件名/目录名。 代码索引默认保存在 `~/.jacecli/rag/codebase.db`。 调试日志默认滚动写入 `~/.jacecli/logs/jacecli.log`，旧日志会按保留天数和总容量自动清理。 如果你想为某次运行指定单独目录，可以额外传入： ```bash # 指定记忆目录 java -Djacecli.memory.dir=/tmp/jacecli-memory -jar target/jacecli-1.0-SNAPSHOT.jar # 指定 RAG 索引目录 java -Djacecli.rag.dir=/tmp/jacecli-rag -jar target/jacecli-1.0-SNAPSHOT.jar # 指定日志目录与保留策略 java -Djacecli.log.dir=/tmp/jacecli-logs \ -Djacecli.log.level=DEBUG \ -Djacecli.log.maxHistory=3 \ -Djacecli.log.maxFileSize=5MB \ -Djacecli.log.totalSizeCap=20MB \ -jar target/jacecli-1.0-SNAPSHOT.jar ``` 也可以放到 `.env` 或环境变量中： ```bash JACECLI_LOG_LEVEL=DEBUG JACECLI_LOG_DIR=/Users/yourname/.jacecli/logs JACECLI_LOG_MAX_HISTORY=7 JACECLI_LOG_MAX_FILE_SIZE=10MB JACECLI_LOG_TOTAL_SIZE_CAP=100MB ``` ### 2. 可选：配置 MCP server && 启动 Ollama MCP 子系统默认开启。没有配置文件时不会启动外部 server；需要接入时创建 `~/.jacecli/mcp.json` 或项目内 `.jacecli/mcp.json`： ```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}` 从环境变量读取；缺失会在启动时直接提示。 如果 server 支持 resources，可以直接查看或引用： ```text /mcp resources filesystem /mcp prompts filesystem 帮我看下 @filesystem:file://README.md 这份文档 ``` OAuth 和 `sampling/createMessage` 当前未实现；远程 server 需要鉴权时仍使用 `headers` + 环境变量注入 Bearer token。 Ollama `nohup ollama serve > /tmp/ollama.log 2>&1 &`。 ### 3. 编译运行 ```bash # 编译 mvn clean package # 运行（需要本地 Ollama 已启动且拉取了 nomic-embed-text） java -jar target/jacecli-1.0-SNAPSHOT.jar ``` 或者直接运行： ```bash mvn clean compile exec:java -Dexec.mainClass="com.jacecli.cli.Main" ``` ### 4. 如何进入 Plan 模式 当前默认模式是 `ReAct`。进入 `Plan-and-Execute` 的方式只有 `/plan`： 1. 输入 `/plan` 2. 下一条任务会用计划模式执行 3. 执行完成后自动回到默认 `ReAct` 如果想一条命令切模式并执行任务，可以直接输入： ```text /plan 创建一个 demo 项目，然后读取 pom.xml，最后验证项目结构 ``` 这条命令执行完成后，会自动回到默认的 `ReAct` 模式。 计划生成后，CLI 会先停下来等待确认： - 按 `Enter`：按当前计划执行 - 按 `Ctrl+O`：展开完整计划 - 按 `ESC`：折叠完整计划或取消本次计划 - 按 `I`：输入补充要求并重新规划 - 按方向键不会触发取消；只有单独按下 `ESC` 才会取消待执行 plan ## 使用示例 ### 第一期：ReAct 示例 ```text 👤 你: 创建一个Java项目叫myapp 🧠 思考过程: 用户要创建一个 Java 项目。我先调用 create_project 工具生成基础结构，再根据工具返回结果确认是否创建成功。 🤖 最终结果: 已成功创建 Java 项目 "myapp"，包含基本的 Maven 结构。 ``` ### 第二期：Plan-and-Execute 示例 ```text 💡 提示: - 输入你的问题或任务 - 输入 '/plan' 后，下一条任务使用 Plan-and-Execute 模式 - 输入 '/plan 任务内容' 直接用计划模式执行这条任务 - 输入 '/team' 后，下一条任务使用 Multi-Agent 协作模式 - 输入 '/team 任务内容' 直接用多 Agent 协作执行这条任务 - 计划生成后可直接执行、补充要求重规划，或取消 - 输入 '/index [路径]' 为代码库建立向量索引 - 输入 '/search <查询>' 语义检索代码 - 输入 '/graph <类名>' 查看代码关系图谱 - 输入 '/memory' 查看记忆状态 - 输入 '/memory clear' 清空长期记忆 - 输入 '/save 事实内容' 手动保存关键事实 - 未识别的 `/xxx` 命令会直接提示“未知命令”，不会再交给 Agent 当普通对话处理 - 输入 '/clear' 清空对话历史 - 输入 '/exit' 或 '/quit' 退出 👤 你: /plan 创建一个名为 demoapp 的 java 项目，然后读取 pom.xml，最后验证项目结构 📋 使用 Plan-and-Execute 模式 📋 正在规划任务: 创建一个名为 demoapp 的 java 项目，然后读取 pom.xml，最后验证项目结构 ╔══════════════════════════════════════════════════════════╗ ║ 执行计划: 创建一个名为 demoapp 的 java 项目，然后读取... ║ ╠══════════════════════════════════════════════════════════╣ ║ 1. ⏳ task_1 [COMMAND ] 依赖: 无 ║ ║ 创建 demoapp 项目结构 ║ ║ 2. ⏳ task_2 [FILE_READ ] 依赖: task_1 ║ ║ 读取 demoapp/pom.xml 内容 ║ ║ 3. ⏳ task_3 [VERIFICATION] 依赖: task_2 ║ ║ 验证项目结构与 Maven 配置 ║ ╚══════════════════════════════════════════════════════════╝ 📝 计划已生成。 - 回车：按当前计划执行 - ESC：取消本次计划 - I：输入补充要求后重新规划 I 补充> 请在执行前先检查 README 📝 已收到补充要求，正在重新规划... 🚀 开始执行计划... ``` ## 可用工具 - `read_file` - 读取文件内容 - `write_file` - 写入文件内容 - `list_dir` - 列出目录内容 - `execute_command` - 在当前项目目录执行短时 Shell 命令（默认 60 秒超时，黑名单拦截破坏性命令） - `create_project` - 创建项目结构（java/python/node） - `search_code` - 语义检索代码库（自然语言查询） - `web_search` - 搜索互联网获取实时信息 - `web_fetch` - 抓取已知 URL 并提取正文 Markdown - `mcp__{server}__{tool}` - MCP server 动态提供的外部工具 - `mcp__{server}__list_resources` / `mcp__{server}__read_resource` - 支持 resources 的 MCP server 自动注册的虚拟工具 同一轮模型返回多个工具调用时，JaceCLI 会并行执行这些工具；如果工具之间有依赖关系，模型应分多轮调用。 文件类工具（`read_file` / `write_file` / `list_dir` / `create_project`）路径强制限定在项目根之内，越界请求会被策略层拒绝；`execute_command` 通过命令黑名单拦截 `sudo` / `rm -rf 全盘` / `mkfs` / `dd of=/dev` / fork bomb / `curl|sh` 等。所有 `mcp__` 前缀工具默认触发 HITL 和审计。详见 `/policy`。 ## 命令 - `/help` 或 `/h` - 列出所有可用命令 - `/plan` - 下一条任务使用 Plan-and-Execute 模式 - `/plan <任务>` - 直接用 Plan-and-Execute 模式执行这条任务 - `/team` - 下一条任务使用 Multi-Agent 协作模式 - `/team <任务>` - 直接用 Multi-Agent 协作模式执行这条任务 - `/cancel` - 运行中请求取消当前任务；空闲时会提示当前没有正在运行的任务 - `/hitl on` - 启用危险操作人工审批（HITL） - `/hitl off` - 关闭 HITL 审批 - `/hitl` - 查看 HITL 当前状态 - `/mcp` - 查看所有 MCP server 状态 - `/mcp restart ` - 重启单个 MCP server - `/mcp logs ` - 查看 MCP server 最近 200 行 stderr 日志 - `/mcp disable ` - 运行时禁用 MCP server 并移除其工具 - `/mcp enable ` - 运行时启用 MCP server - `/mcp resources ` - 查看 MCP server 暴露的 resources - `/mcp prompts ` - 查看 MCP server 暴露的 prompts（只查看，不注入对话） - `/policy` - 查看安全策略状态（路径围栏 / 命令黑名单 / 资源上限 / 审计目录） - `/audit [N]` - 查看今日最近 N 条危险工具审计记录（默认 10） - `/memory` / `/mem` - 查看记忆系统状态 - `/memory clear` - 清空长期记忆 - `/save <事实>` - 手动保存关键事实到长期记忆 - `/index [路径]` - 索引代码库（默认当前目录） - `/search <查询>` - 语义检索代码 - `/graph <类名>` - 查看代码关系图谱 - `/context` - 查看上下文状态（分类占比、可视化进度条、四级阈值、cache 命中） - `/session` 或 `/session list` - 列出所有持久化会话 - `/session save [名称]` - 保存当前对话为会话 - `/session load <名称>` - 加载指定会话 - `/session new` - 开启新会话 - `/compress` - 手动触发压缩链（L1→L2→L3） - `/compress micro` - 仅执行微量压缩（L1） - `/compress summary` - 仅执行会话记忆压缩（L2） - `/compress full` - 仅执行传统压缩（L3） - `/fork` 或 `/fork status` - 查看后台 Fork Agent 状态 - `/clear` - 清空对话历史 - `/exit` / `/quit` - 退出程序 ## 运行效果 ```text ╔══════════════════════════════════════════════════════════╗ ║ ║ ║ ██╗ █████╗ ██████╗███████╗██████╗ ██╗ ██╗ ║ ║ ██║██╔══██╗██╔════╝██╔════╝██╔═══╝ ██║ ██║ ║ ║ ██║███████║██║ █████╗ ██║ ██║ ██║ ║ ║██╗ ██║██╔══██║██║ ██╔══╝ ██║ ██║ ██║ ║ ║███████║██║ ██║╚██████╗███████╗╚██████╗███████╗██║ ║ ║╚══════╝╚═╝ ╚═╝ ╚═════╝╚══════╝ ╚═════╝╚══════╝╚═╝ ║ ║ ║ ║ Long-Context Agent CLI v12.0.0 ║ ║ ║ ╚══════════════════════════════════════════════════════════╝ ✅ Model loaded: deepseek-v4-flash (deepseek) 🔌 MCP server：未配置（可创建 ~/.jacecli/mcp.json 或 .jacecli/mcp.json） 🔄 Using ReAct mode 💡 Hints: - Enter your question or task - Enter '/help' or '/h' to see all available commands - Enter '/model' to view current model, '/model glm' or '/model deepseek' to switch - Enter '/plan [task]' to use Plan-and-Execute mode - Enter '/team [task]' to use Multi-Agent collaboration mode - Press ESC during task execution to cancel - Enter '/hitl on|off' to toggle human-in-the-loop approval - Enter '/context' or '/ctx' to view context window, cache, compression, fork status - Enter '/compress [micro|summary|full]' to manually trigger compression - Enter '/fork status' to view active background Fork Agent tasks - Enter '/session [list|save|load|new]' to manage persistent sessions - Enter '/mcp' to view MCP servers, '/mcp restart|logs|disable|enable ' to manage - Enter '/mcp resources ' to view MCP resources, '/mcp prompts ' to view prompts - Enter '@server:protocol://path' to explicitly reference an MCP resource - Enter '/policy' to view security policy, '/audit [N]' to view audit records - Enter '/index [path]' to build vector index, '/search ' for semantic code search - Enter '/graph ' to view code relation graph - Enter '/memory' to view memory status, '/memory clear' to clear long-term memory - Enter '/save ' to manually save key facts - Enter '/clear' to clear conversation history - Enter '/exit' or '/quit' to exit ──────────────────────────────────────────────────────────────── jace input ───────────────────────────────────────────────────────────────── ``` ## 技术栈 - **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 查询） - **Logback 1.5** — 日志滚动落盘（按大小 + 按天） - **JUnit 5** — 单元测试（60+ 测试类） ## 项目结构 ``` src/main/java/com/jacecli ├── agent/ │ ├── Agent.java # ReAct Agent 主循环 │ ├── AgentBudget.java # Agent 退出预算（动态 80% × window） │ ├── AgentMessage.java # Agent 间通信消息 │ ├── AgentOrchestrator.java # Multi-Agent 编排器 │ ├── AgentRole.java # Agent 角色枚举 │ ├── CompressionCircuitBreaker.java # 压缩断路器 │ ├── CompressionEngine.java # 四级压缩调度引擎 │ ├── CompressionLevel.java # 压缩级别枚举 │ ├── CompressionResult.java # 压缩结果 │ ├── ForkAgent.java # Fork Agent（独立 client + 共享 PromptCache） │ ├── ForkContext.java # Fork 上下文（状态隔离定义） │ ├── ForkRegistry.java # Fork Agent 生命周期管理 │ ├── PlanExecuteAgent.java # Plan-and-Execute Agent │ ├── SessionSummarizer.java # 后台会话摘要生成器 │ └── SubAgent.java # 可配置子代理 ├── cli/ │ ├── Main.java # CLI 入口 │ ├── CliCommandParser.java # 命令解析 │ ├── PlanReviewInputParser.java # 计划审核输入 │ └── SlashCommandCompleter.java # Tab 补全 ├── config/ │ └── JaceCliConfig.java # 运行时配置持久化 ├── hitl/ │ ├── ApprovalPolicy.java # 审批策略 │ ├── ApprovalRequest.java # 审批请求 │ ├── ApprovalResult.java # 审批结果 │ ├── HitlHandler.java # HITL 处理器接口 │ ├── HitlToolRegistry.java # HITL 工具注册拦截层 │ └── TerminalHitlHandler.java # 终端审批交互 ├── llm/ │ ├── LlmClient.java # LLM 客户端接口 │ ├── LlmClientFactory.java # 客户端工厂 │ ├── AbstractOpenAiCompatibleClient.java # OpenAI 兼容协议基类 │ ├── GLMClient.java # GLM-5.1 API 客户端（200K window） │ ├── DeepSeekClient.java # DeepSeek V4 客户端（1M window） │ ├── ModelCapabilities.java # 模型能力表（contextWindow / caching） │ ├── PromptCache.java # Cache 共享核心（前缀一致性管理） │ └── PromptCachingConfig.java # 缓存标记配置 ├── mcp/ │ ├── McpClient.java # MCP 客户端封装 │ ├── McpServer.java # MCP Server 模型 │ ├── McpServerManager.java # Server 生命周期管理 │ ├── McpToolBridge.java # 工具调用桥接 │ ├── config/ # MCP 配置加载 │ ├── jsonrpc/ # JSON-RPC 2.0 实现 │ ├── mention/ # @-mention 资源引用 │ ├── notifications/ # 被动通知路由 │ ├── protocol/ # MCP 协议模型 + schema 清洗 │ ├── resources/ # MCP resources 双轨 │ └── transport/ # stdio + Streamable HTTP ├── memory/ │ ├── MemoryManager.java # 记忆门面类 │ ├── MemoryEntry.java # 记忆条目 │ ├── MemoryRetriever.java # 记忆检索 │ ├── MemoryQueryTokenizer.java # 中文分词 │ ├── ConversationMemory.java # 短期记忆 │ ├── LongTermMemory.java # 长期记忆 │ ├── ContextCompressor.java # 上下文压缩（L3 内部实现） │ ├── TokenBudget.java # Token 预算管理 │ ├── Session.java # 会话数据模型 │ ├── SessionMetadata.java # 会话元数据 │ └── SessionManager.java # 会话持久化 CRUD ├── plan/ │ ├── ExecutionPlan.java # DAG 执行计划 │ ├── Planner.java # 规划器 │ └── Task.java # 任务定义 ├── policy/ │ ├── PathGuard.java # 路径围栏 │ ├── CommandGuard.java # 命令快速拒绝 │ ├── AuditLog.java # 结构化审计 │ └── PolicyException.java # 策略异常 ├── rag/ │ ├── CodeAnalyzer.java # AST 关系分析 │ ├── CodeChunk.java # 代码块模型 │ ├── CodeChunker.java # 代码分块器 │ ├── CodeIndex.java # 索引管理器 │ ├── CodeRelation.java # 代码关系模型 │ ├── CodeRetriever.java # 检索入口 │ ├── EmbeddingClient.java # Embedding API 客户端 │ ├── SearchResultFormatter.java # 搜索结果格式化 │ ├── RagQueryTokenizer.java # 查询分词 │ └── VectorStore.java # SQLite 向量存储 ├── runtime/ │ ├── CancellationContext.java # 取消上下文 │ └── CancellationToken.java # 取消令牌 ├── tool/ │ └── ToolRegistry.java # 工具注册表 + 并行执行 ├── util/ │ ├── AnsiStyle.java # ANSI 终端样式 │ ├── JiebaSegmenterFactory.java # 分词工厂 │ ├── TerminalMarkdownRenderer.java # Markdown 渲染 │ └── TerminalSpinner.java # 终端 spinner └── web/ ├── FetchResult.java # 抓取结果模型 ├── HtmlExtractor.java # HTML → Markdown 提取 ├── NetworkPolicy.java # 网络安全策略 ├── SearchProvider.java # 搜索 provider 接口 ├── SearchProviderFactory.java # Provider 工厂 ├── SearchResult.java # 搜索结果模型 ├── WebFetcher.java # URL 抓取 ├── ZhipuSearchProvider.java # 智谱搜索 ├── SerpApiSearchProvider.java # SerpAPI 搜索 └── SearxngSearchProvider.java # SearXNG 搜索 ``` 测试代码在 `src/test/java/com/jacecli/` 下，覆盖 agent、cli、hitl、llm、mcp、memory、plan、policy、rag、runtime、tool、util、web 共 13 个模块，60+ 测试文件。 ## 贡献 欢迎提交 Issue 与 Pull Request。改动前请先阅读 `AGENTS.md` 了解协作规则与联动要求： - **改行为不只改代码** — 同步检查 README、AGENTS.md、ROADMAP.md 是否需更新 - **改工具集联动提示词** — 新增/删除/修改工具要同步更新 Agent、PlanExecuteAgent、SubAgent 的系统提示词 - **不提交敏感信息** — `.env`、真实 API Key、`target/` 产物不进入版本控制 - **提交前跑测试** — `mvn test` 应全部通过 ## 致谢 本项目部分代码基于 [itwanger](https://gitee.com/itwanger) 的开源作品开发，原作品采用 [Apache 2.0] 许可证，特此感谢。 ## License [Apache 2.0](LICENSE) © 2026 SapientialM