Yapcli

YapCLI

> 从零实现的 Java Agent CLI — 对标 Claude Code，支持 ReAct / Plan / Multi-Agent / MCP / 微信通道

Table of Contents

• [Features](#features)
• [Quick Start](#quick-start)
• [Usage Examples](#usage-examples)
• [Commands](#commands)
• [Available Tools](#available-tools)
• [Tech Stack](#tech-stack)
• [Project Structure](#project-structure)
• [Contributing](#contributing)
• [License](#license)

Features

Multi-Agent System

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

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

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 回滚
• 图片输入：@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  --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/configuration.md](docs/configuration.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 | 管理单个 MCP server | | /policy | 查看安全策略状态 | | /audit [N] | 查看最近 N 条审计记录 | | /snapshot | 查看 Side-Git 快照 | | /restore | 恢复到第 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

    ████████    YapCLI YAP  v16.1.0
     ██  ██    Model glm-5.1 (glm)
     ██  ██    MCP 4/4 · 61 tools · 2/2 skills · ReAct
     ██  ██    ReAct · Plan · MCP · Browser · Image
     ██  ██

Tips for getting started:
1. Type / for commands and Tab completion
2. Ask coding questions, edit code or run commands
3. Attach context with @path or @image:

* 你好，请列出当前目录的文件

🧠 思考过程:
用户想了解当前目录结构。我先读取目录，再基于结果做归类说明...

🤖 最终结果:
当前目录包含 src、target、pom.xml、README.md 等文件，
这是一个标准的 Java Maven 项目。

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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: TobeMagic
• Source: TobeMagic/yapcli
• License: Apache-2.0
• Homepage: https://tobemagic.github.io/yapcli/

Install and usage instructions live in the source repository linked above.