# Yapcli

> 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.

- **Type:** MCP server
- **Install:** `agentstack add mcp-tobemagic-yapcli`
- **Verified:** Pending review
- **Seller:** [TobeMagic](https://agentstack.voostack.com/s/tobemagic)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [TobeMagic](https://github.com/TobeMagic)
- **Source:** https://github.com/TobeMagic/yapcli
- **Website:** https://tobemagic.github.io/yapcli/

## Install

```sh
agentstack add mcp-tobemagic-yapcli
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 审批流**：危险操作（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 ` 回滚
- **图片输入**：`@image:` 引用本地 / MCP 图片，`supportsImageInput()` 按 provider 自动降级

## Quick Start

```bash
# 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
```

### 快速配置

```bash
# 运行时切换模型
/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 目录

```bash
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 配置。手动配置示例：

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

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

详细信息见 [`docs/configuration.md`](docs/configuration.md)。

## Usage Examples

### ReAct

```text
* 创建一个 Java 项目叫 myapp

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

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

### Plan-and-Execute

```text
* /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

```text
* 帮我查一下 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

```text
    ████████    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

```bash
# 常规回归
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](https://github.com/TobeMagic)
- **Source:** [TobeMagic/yapcli](https://github.com/TobeMagic/yapcli)
- **License:** Apache-2.0
- **Homepage:** https://tobemagic.github.io/yapcli/

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-tobemagic-yapcli
- Seller: https://agentstack.voostack.com/s/tobemagic
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.