Metadata-Version: 2.4
Name: yyccli
Version: 0.1.0
Summary: Python terminal AI agent CLI with ReAct tools, MCP, Runtime API, memory, snapshots, web search, and image input
Author: YycCLI Contributors
License: MIT
License-File: LICENSE
Keywords: agent,ai,cli,llm,mcp,react,terminal
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp<2,>=1.27
Requires-Dist: pillow>=10.0
Requires-Dist: prompt-toolkit>=3.0.43
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.3
Provides-Extra: dev
Requires-Dist: pytest>=8.2.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Description-Content-Type: text/markdown

# YycCLI

YycCLI 是一个使用 Python 构建的终端 AI Agent CLI，面向真实项目中的代码阅读、文件修改、命令执行、联网检索和多 Agent 协作。它既可以作为交互式终端使用，也可以通过单次查询、Python SDK、MCP server 或 Runtime API 接入其他工作流。

## 项目定位

- 提供交互式终端与单次 prompt 两种运行方式
- 使用 OpenAI-compatible 流式模型客户端和 ReAct 工具调用循环
- 支持 Plan-and-Execute DAG 调度与 Multi-Agent Planner、Worker、Reviewer 协作
- 内置文件、Shell、代码搜索、网页搜索和网页抓取工具
- 支持连接 MCP server，也可以将自身工具通过 MCP 暴露
- 提供 Runtime API、持久化后台任务和 Python SDK
- 支持 Skill、SQLite 长期记忆、本地代码索引与运行快照
- 支持本地及远程图片输入，并按模型能力自动降级
- 通过路径限制、命令限制、HITL 和 JSONL 审计保护危险操作

## 快速开始

### 环境要求

- Python 3.11 或更高版本
- [uv](https://docs.astral.sh/uv/)
- 可选：[ripgrep](https://github.com/BurntSushi/ripgrep)，用于更快的本地代码搜索
- 可选：Node.js、npx 和 Chrome，用于 Chrome DevTools MCP

### 安装

```bash
git clone https://github.com/itwanger/PaiCLI-Python.git YycCLI
cd YycCLI
uv sync
uv run yyccli --help
```

发布到 PyPI 后，用户可以将 YycCLI 安装为全局工具：

```bash
uv tool install yyccli
yyc --help
```

也可以直接安装 GitHub 上的最新版本：

```bash
uv tool install git+https://github.com/itwanger/PaiCLI-Python.git
yyc
```

`yyc` 是推荐的短命令，`yyccli` 作为兼容命令继续保留。

### 配置 API Key

以默认的 DeepSeek provider 为例。

Bash：

```bash
export YYCCLI_PROVIDER=deepseek
export YYCCLI_MODEL=deepseek-v4-flash
export DEEPSEEK_API_KEY=your_key_here
```

PowerShell：

```powershell
$env:YYCCLI_PROVIDER = "deepseek"
$env:YYCCLI_MODEL = "deepseek-v4-flash"
$env:DEEPSEEK_API_KEY = "your_key_here"
```

也可以将相同变量写入项目根目录的 `.env` 文件：

```dotenv
YYCCLI_PROVIDER=deepseek
YYCCLI_MODEL=deepseek-v4-flash
DEEPSEEK_API_KEY=your_key_here
```

### 运行

启动交互模式：

```bash
uv run yyccli
```

执行单次查询：

```bash
uv run yyccli -p "帮我总结这个项目"
```

检查 Python、uv、Node.js、ripgrep、API Key 和当前模型配置：

```bash
uv run yyccli doctor --cwd .
```

## 配置说明

YycCLI 按以下顺序加载配置，后加载的值会覆盖先前的值：

1. 内置默认配置
2. 用户级 `~/.yyccli/config.json`
3. 项目级 `.yyccli/config.json`
4. 项目级 `.env`
5. CLI 参数
6. 当前进程环境变量

常用环境变量：

| 变量 | 说明 |
| --- | --- |
| `YYCCLI_API_KEY` | 通用模型 API Key |
| `YYCCLI_PROVIDER` | 模型 provider，默认值为 `deepseek` |
| `YYCCLI_MODEL` | 模型名称 |
| `YYCCLI_BASE_URL` | OpenAI-compatible API 地址 |
| `YYCCLI_MAX_TOKENS` | 单次生成的最大 token 数 |
| `YYCCLI_TEMPERATURE` | 模型 temperature |
| `YYCCLI_RENDER_MODE` | 输出模式：`inline` 或 `plain` |
| `YYCCLI_HITL` | 人工确认模式：`always`、`auto` 或 `never` |
| `YYCCLI_MCP` | 是否启用 MCP：`true` 或 `false` |
| `YYCCLI_SKILL` | 是否启用 Skill：`true` 或 `false` |
| `YYCCLI_MEMORY` | 是否启用长期记忆：`true` 或 `false` |

provider-specific API Key 包括：

- `DEEPSEEK_API_KEY`
- `GLM_API_KEY`
- `STEP_API_KEY`
- `KIMI_API_KEY`
- `FREELLMAPI_API_KEY`
- `XFYUN_API_KEY`
- `AGNES_API_KEY`

还可以使用 `<PROVIDER>_MODEL` 和 `<PROVIDER>_BASE_URL` 覆盖当前 provider 的模型与 API 地址，例如 `DEEPSEEK_MODEL` 和 `DEEPSEEK_BASE_URL`。

连接本地或其他 OpenAI-compatible 服务时，Bash 可以这样配置：

```bash
export YYCCLI_PROVIDER=openai-compatible
export YYCCLI_BASE_URL=http://127.0.0.1:11434/v1
export YYCCLI_MODEL=qwen2.5-coder
export YYCCLI_API_KEY=your_key_here
uv run yyccli -p "解释这个仓库"
```

PowerShell 写法：

```powershell
$env:YYCCLI_PROVIDER = "openai-compatible"
$env:YYCCLI_BASE_URL = "http://127.0.0.1:11434/v1"
$env:YYCCLI_MODEL = "qwen2.5-coder"
$env:YYCCLI_API_KEY = "your_key_here"
uv run yyccli -p "解释这个仓库"
```

## 常用参考

### CLI

| 命令 | 用途 |
| --- | --- |
| `uv run yyccli` | 启动交互式终端 |
| `uv run yyccli -p "<prompt>"` | 执行单次查询 |
| `-m, --model <name>` | 临时覆盖模型 |
| `--provider <name>` | 临时覆盖 provider |
| `--plain` | 使用纯文本输出 |
| `--cwd <path>` | 指定工作目录 |
| `--version` | 显示版本 |
| `doctor` | 检查运行环境和配置 |
| `serve` | 启动 Runtime API |
| `mcp` | 管理或启动 MCP server |

### REPL 命令

| 命令 | 用途 |
| --- | --- |
| `/help` | 显示命令列表 |
| `/exit` | 退出 REPL |
| `/clear` | 清空会话历史和终端 |
| `/context` | 查看工作目录、模型、上下文和工具状态 |
| `/memory [search <query>\|clear]` | 列出、搜索或清空长期记忆 |
| `/save <fact>` | 保存一条长期记忆 |
| `/config` | 查看已脱敏的当前配置 |
| `/tools` | 列出已注册工具 |
| `/hitl on\|off\|always\|auto\|never` | 调整人工确认模式 |
| `/policy` | 查看安全策略 |
| `/audit [N]` | 查看最近 N 条审计记录 |
| `/index [path]` | 重建本地代码索引 |
| `/search <query>` | 搜索代码索引 |
| `/plan <task>` | 使用 Plan-and-Execute 执行任务 |
| `/team <task>` | 使用 Multi-Agent 协作执行任务 |
| `/model [<model>\|<provider> <model>]` | 查看或修改当前模型配置 |
| `/skill [list\|show\|on\|off\|reload]` | 管理 Skill |
| `/mcp` | 查看 MCP CLI 使用提示 |
| `/task [add\|cancel\|log]` | 管理持久化后台任务 |
| `/snapshot [clean]` | 列出或清理快照 |
| `/restore <snapshot-id-or-index>` | 恢复指定快照 |

### 内置工具与安全

YycCLI 默认注册以下工具：

- 文件：`read_file`、`write_file`、`list_dir`
- 文件匹配：`glob`、`glob_files`
- 内容搜索：`grep`、`grep_code`、`search_code`
- 命令执行：`bash`、`execute_command`
- 联网访问：`web_search`、`web_fetch`
- Agent 能力：`save_memory`、`load_skill`、`revert_turn`

`web_search` 使用 DuckDuckGo HTML 搜索。`web_fetch` 只抓取公开 HTTP/HTTPS 页面，并拒绝本地文件、loopback、私有网络和内网地址。

文件写入、命令执行、远程 MCP 写操作和快照恢复等危险操作会经过路径限制、命令限制、HITL 人工确认和 JSONL 审计。非交互环境中的确认请求默认拒绝。

## 高级能力

### Plan-and-Execute 与 Multi-Agent

Plan-and-Execute 使用 Planner 生成带依赖关系的 DAG，再按依赖批次执行任务；同一批次内的独立任务可以并行运行。Multi-Agent 模式使用 Planner、Worker 和 Reviewer 分工，并支持依赖调度、并行 worker 与有上限的 review 重试。

```text
/plan 读取关键模块并总结数据流
/team 让多个 Agent 检查项目中的潜在问题
```

### MCP

YycCLI 可以从 `~/.yyccli/mcp.json` 和项目级 `.yyccli/mcp.json` 加载 stdio 或 Streamable HTTP MCP server。项目级同名配置会覆盖用户级配置，远端工具注册为 `mcp__<server-name>__<tool-name>`。

初始化 Chrome DevTools MCP 配置需要 Node.js、npx 和 Chrome：

```bash
uv run yyccli mcp init-chrome --scope project
uv run yyccli mcp list
```

连接已经开启远程调试的 Chrome：

```bash
uv run yyccli mcp init-chrome --scope project --browser-url http://127.0.0.1:9222
```

也可以将 YycCLI 的内置工具作为 MCP server 暴露：

```bash
uv run yyccli mcp serve --transport stdio
uv run yyccli mcp serve --transport http --port 3000
```

Chrome DevTools MCP 可以访问浏览器页面和 DevTools 状态，不要向 Agent 授权包含敏感数据或生产后台的浏览器会话。

### Runtime API

Runtime API 使用独立的访问密钥。创建线程不需要调用模型，但发送 turn 和执行后台任务还需要有效的模型 API Key。

```bash
uv run yyccli serve --http --port 8080 --api-key dev-key
```

创建线程：

```bash
curl -sS -X POST http://127.0.0.1:8080/v1/threads \
  -H "x-api-key: dev-key"
```

发送 turn 并读取事件：

```bash
curl -sS -X POST http://127.0.0.1:8080/v1/threads/<thread_id>/turns \
  -H "content-type: application/json" \
  -H "x-api-key: dev-key" \
  -d '{"message":"总结这个项目"}'

curl -sS http://127.0.0.1:8080/v1/threads/<thread_id>/events \
  -H "x-api-key: dev-key"
```

后台任务使用 `/v1/tasks`，支持创建、列表、读取和取消：

```text
POST /v1/tasks
GET  /v1/tasks
GET  /v1/tasks/<task_id>
POST /v1/tasks/<task_id>/cancel
```

除了 `x-api-key`，Runtime API 也接受 `Authorization: Bearer <key>`。

### 图片输入

在 prompt 中使用 `@image:<path-or-url>` 引用图片：

```text
分析这张截图 @image:./screenshots/page.png
解释这张图片 @image:https://example.com/image.png
```

本地图片会自动缩放和压缩；透明图片会在需要时铺设白色背景。如果当前 provider 或模型不支持图片输入，YycCLI 会降级为文本元信息。

### Skill、记忆与代码索引

Skill 可以来自内置目录、用户目录或项目目录，并支持启用、禁用和运行时懒加载：

```text
/skill list
/skill show web-access
/skill off web-access
/skill reload
```

长期记忆和代码索引使用本地 SQLite 存储：

```text
/save 这个项目使用 uv 管理依赖
/memory search uv
/index .
/search RuntimeApiServer
```

### 快照与恢复

Agent 运行前后会尽力创建 `pre-turn` 和 `post-turn` 快照，保存在 `~/.yyccli/snapshots/`，不会写入项目 Git 历史。

```text
/snapshot
/restore 1
/snapshot clean
```

### Python SDK

SDK 使用与 CLI 相同的配置加载方式。真实调用需要有效的模型 API Key。

```python
from yyccli.sdk import create_default_engine

engine = create_default_engine(cwd=".")

result = engine.ask_complete("解释这个项目")
print(result.text)

plan_result = engine.plan_complete("读取核心模块并总结数据流")
team_result = engine.team_complete("让多个 Agent 检查项目中的潜在问题")
```

MIT License. See [LICENSE](LICENSE).
