Skip to content
BranchesTags

Repository files navigation

YapCLI product loop — terminal-first Java Agent IDE showing ReAct, Plan-and-Execute, MCP tools, memory, browser control, and reversible code changes in one terminal

YapCLI

面向开发者的 Terminal-First Java Agent IDE，在一个终端中完成 ReAct、Plan-and-Execute、Multi-Agent、MCP 工具调用、代码验证与可恢复快照。

CI Java 17 Apache 2.0 GitHub Pages Javadoc

Landing · 快速开始 · 终端界面

Table of Contents

Features

Multi-Agent System

三种执行模式，覆盖从简单对话到复杂协作的全场景：

  • ReAct 循环：思考 → 行动 → 观察，单轮对话驱动的默认模式
  • Plan-and-Execute：DAG 拆解复杂任务，按依赖顺序执行，带人工确认环节
  • Multi-Agent 协作：规划者（Planner）+ 执行者（Worker）+ 检查者（Reviewer）三角色主从架构，审查未通过时自动重试（最多 2 次）
  • HITL 审批流：危险操作（write_file / execute_command / create_project / revert_turn）三级危险等级，支持批准 / 全部放行 / 拒绝 / 跳过 / 修改参数

MCP 协议

原生支持 MCP（Model Context Protocol），接入外部工具生态：

  • stdio 子进程 + Streamable HTTP 远程 server
  • 双层配置：用户级 ~/.yapcli/mcp.json + 项目级 .yapcli/mcp.json
  • 工具自动注册为 mcp__{server}__{tool}，schema 自动清洗 $ref / anyOf
  • Resources 支持：@server:protocol://path 显式引用，自动注册虚拟工具
  • 被动处理 notifications（tools/resources list_changed, resources/updated）
  • 内置 step_search 远程 MCP（检测到 STEP_API_KEY 时自动注册）

Memory & RAG & 长上下文

  • 短期记忆：管理当前对话与工具结果
  • 长期记忆：/save <事实> 保存跨会话稳定事实，项目级作用域
  • 项目记忆：YAP.md / .yapcli/YAP.md 团队规则自动注入 system prompt
  • RAG 语义检索：代码向量化（Ollama / 远程 API）、SQLite 持久化、AST 代码关系图谱
  • 长上下文工程：按模型窗口动态预算（GLM 200k / DeepSeek 1M / StepFun 256k），short / balanced / long 三种模式，prompt cache 可见化

Web & Browser

  • web_search：支持四条路径 — StepSearch MCP 优先 / 智谱 Web Search / SerpAPI / SearXNG
  • web_fetch：OkHttp + Jsoup + readability 提取正文 Markdown
  • Chrome DevTools MCP：SPA / JS 渲染 / 防爬墙页面 fallback
  • CDP 会话复用：/browser connect 切 shared 模式复用登录态 Chrome
  • 内置安全策略：屏蔽内网 / loopback / file://，30 秒超时，5MB 上限，每分钟 30 次限流

WeChat iLink 通道

  • 进程级入口：yapcli wechat setup|start|status|daemon
  • 交互式入口：/wechat 扫码绑定并后台启动
  • 260px PNG 终端二维码 / 字符二维码 fallback
  • iLink 长轮询 + 分片消息，独立通道（非 SSE）
  • 非交互式安全策略：只读工具放行，写入 / 命令 / MCP 黑名单
  • 纯文本 MVP，图片 / 文件延后

Security

  • PathGuard 路径围栏：文件类工具强制限定项目根内
  • CommandGuard 命令黑名单：sudo / rm -rf / mkfs / fork bomb 等 fast-fail
  • AuditLog 结构化审计：按天 JSONL，含 outcome + approver 维度
  • write_file 单文件 5MB 上限

安全模型是 HITL + 路径校验 + 命令快速拒绝 + 审计，不是沙箱。生产级沙箱需要 microVM-level（Firecracker / gVisor）。

Terminal UI

三种渲染形态共享同一套 Agent / ToolRegistry / Memory / MCP / Skill / HITL：

形态 启用方式 视觉风格
inline 流式 TUI（默认） 直接运行 / YAPCLI_RENDERER=inline Claude Code 风格：彩色开屏、底部 dock（MCP / Skill / model / ctx / token）、折叠工具块、行内 diff、HITL 单字符提示
lanterna 全屏 TUI YAPCLI_RENDERER=lanterna 三栏全屏：文件树 + 对话流 + 状态栏 + 输入栏
plain 兜底 YAPCLI_RENDERER=plain 纯 println，无折叠 / 状态栏

LSP 诊断 + Side-Git 快照 + 图片输入

  • LSP 诊断：write_file 后触发 post-edit 诊断（JavaParser 轻量），不阻塞主流程
  • Git Side-History 快照：JGit 纯 Java，每 turn 自动创建快照，/snapshot 管理，/restore <N> 回滚
  • 图片输入：@image: 引用本地 / MCP 图片，supportsImageInput() 按 provider 自动降级

Quick Start

# 1. 配置 API Key
cp .env.example .env
# 编辑 .env 填入 GLM / DeepSeek / StepFun / Kimi API Key

# 2. 编译（默认跳过测试）
mvn clean package

# 3. 运行
java -jar target/yapcli-1.0-SNAPSHOT.jar

快速配置

# 运行时切换模型
/model glm-5.1
/model deepseek
/model step
/model kimi
/model freellmapi
/model agnes

# 持久化配置
/config provider agnes --api-key <key> --model agnes-2.0-flash --default

可选：日志 / 记忆 / RAG 目录

java -Dyapcli.log.dir=/tmp/yapcli-logs \
     -Dyapcli.log.level=DEBUG \
     -jar target/yapcli-1.0-SNAPSHOT.jar

或通过环境变量 YAPCLI_LOG_LEVEL=DEBUG、YAPCLI_LOG_DIR=~/.yapcli/logs。

可选：MCP 配置

~/.yapcli/mcp.json 不存在时自动创建默认 chrome-devtools 配置。手动配置示例：

{
  "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}"} }
  }
}

${PROJECT_DIR} / ${HOME} 是内置变量，其他 ${VAR} 从环境变量读取。项目级 .yapcli/mcp.json 按 server 名覆盖用户级。

详细信息见 docs/agents-reference.md。

Usage Examples

ReAct

* 创建一个 Java 项目叫 myapp

🧠 思考过程:
用户要创建一个 Java 项目。我先调用 create_project 工具生成基础结构...

🤖 最终结果:
已成功创建 Java 项目 "myapp"，包含基本的 Maven 结构。

Plan-and-Execute

* /plan 创建一个名为 demoapp 的 Java 项目，然后读取 pom.xml，最后验证项目结构

📋 执行计划:
  1. ⏳ task_1  [COMMAND]    创建 demoapp 项目结构
  2. ⏳ task_2  [FILE_READ]  读取 demoapp/pom.xml
  3. ⏳ task_3  [VERIFICATION] 验证项目结构与 Maven 配置

Web Search

* 帮我查一下 Java 21 的新特性

🌐 web_search query=Java 21 新特性
→ 获取到最新信息...

Commands

进程级入口：

命令 说明
yapcli wechat setup 绑定微信 iLink 通道
yapcli wechat start 前台启动微信通道
yapcli wechat daemon start|stop|restart|status|logs 管理后台进程

交互式斜杠命令：

命令 说明
/plan [任务] Plan-and-Execute 模式
/team [任务] Multi-Agent 协作模式
/cancel 取消运行中任务
/hitl on|off 启用/关闭 HITL 审批
/mcp 查看 MCP server 状态
/mcp restart|logs|disable|enable <name> 管理单个 MCP server
/policy 查看安全策略状态
/audit [N] 查看最近 N 条审计记录
/snapshot 查看 Side-Git 快照
/restore <N> 恢复到第 N 个 pre-turn 快照
/memory / /save 记忆系统管理
/init 生成精简项目级记忆 YAP.md
/export 导出当前会话为 Markdown
/index [路径] 索引代码库
/search <查询> 语义检索代码
/clear 清空对话历史与短期记忆
/exit / /quit 退出

Available Tools

工具 说明
read_file 读取文件内容
write_file 写入文件内容（5MB 上限）
list_dir 列出目录内容
glob_files 按文件名 glob 查找（自动跳过构建目录）
grep_code 正则搜索代码（优先 ripgrep）
execute_command 执行 Shell 命令（60 秒超时）
create_project 创建项目结构（java / python / node）
search_code 语义检索代码库
web_search 搜索互联网
web_fetch 抓取 URL 提取正文
revert_turn 恢复到最近 pre-turn 快照
mcp__{server}__{tool} MCP server 动态工具
mcp__{server}__{list|read}_resource MCP Resources 虚拟工具

同一轮多工具调用并行执行。路径强制限定项目根内，黑名单拦截破坏性命令。

Launcher Screens

Ready State

YapCLI v16.1.0 launcher with model, MCP, Skill, ReAct, command completion, context attachment, and bottom status dock

启动界面只保留模型、MCP、Skill、执行模式与三条 getting-started 提示；输入行和底部 dock 始终处于同一终端上下文。

Agent Flow

YapCLI plan mode demonstrating research, reviewed plan, regression test, code edit, verification, and reversible Side-Git snapshot

这张演示图使用 YapCLI 已交付的工作流语义，展示从意图、研究、Plan 审阅到测试、修改、验证与 Side-Git 快照的完整路径。可编辑视觉源位于 docs/assets/readme-visual/。

Tech Stack

  • Java 17 + Maven
  • OkHttp + Jackson（HTTP & JSON）
  • JLine 4（终端交互、Status、输入 widgets）
  • SQLite（向量存储 & 任务持久化）
  • JavaParser（AST 代码分析）
  • JGit（Side-History 快照）
  • Jsoup（HTML 解析）
  • Ollama（可选本地 Embedding）

Project Structure

src/main/java/com/yapcli/
├── agent/         ReAct / PlanExecute / Multi-Agent 执行器
├── cli/           Main 入口、命令解析、Plan 审核输入
├── llm/           6 个 Provider 客户端（GLM / DeepSeek / Step / Kimi / FreeLLM / Agnes）
├── context/       上下文模式与 Token 预算
├── memory/        短期 / 长期记忆、压缩与检索
├── plan/          DAG 任务与执行计划
├── rag/           代码向量化、索引、语义检索
├── mcp/           MCP 客户端、Server 管理、transport、resources
├── browser/       Chrome DevTools 会话与敏感页面策略
├── wechat/        iLink 微信通道客户端
├── web/           搜索与抓取 Provider
├── policy/        路径围栏、命令黑名单、审计日志
├── skill/         Skill 注册与上下文注入
├── render/        TUI 渲染器（inline / lanterna / plain）
├── snapshot/      Git Side-History 快照
├── lsp/           LSP 诊断注入
├── runtime/       Runtime API + 异步后台任务
├── image/         图片输入引用解析
├── hitl/          HITL 审批流
└── tool/          工具注册表

Contributing

# 常规回归
mvn test -Pquick

# 发版前全量回归
mvn test -DskipTests=false

# 针对性测试
mvn test -Dtest=XxxTest -DskipTests=false

请确保：

  1. 不提交 .env / 真实 API Key / target/ 产物
  2. 改行为同步更新文档（AGENTS.md / README.md）
  3. 改命令入口联动 Main.java + CliCommandParser + 测试
  4. 详细行为描述见 AGENTS.md

License

Apache 2.0

About

A Java Agent CLI built from scratch — ReAct, Plan-and-Execute, Multi-Agent, MCP protocol, WeChat iLink. Like Claude Code, but you can read every line.

tobemagic.github.io/yapcli/

Topics

agentchatglmclideepseekjavallmmcpmulti-agentreactwechat

Resources

Readme
Apache-2.0 license

Code of conduct

Code of conduct

Contributing

Contributing
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages