yyccli 0.1.0

Python terminal AI agent CLI with ReAct tools, MCP, Runtime API, memory, snapshots, web search, and image input

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
• 可选：ripgrep，用于更快的本地代码搜索
• 可选：Node.js、npx 和 Chrome，用于 Chrome DevTools MCP

安装

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

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

uv tool install yyccli
yyc --help

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

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

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

配置 API Key

以默认的 DeepSeek provider 为例。

Bash：

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

PowerShell：

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

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

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

运行

启动交互模式：

uv run yyccli

执行单次查询：

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

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

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 可以这样配置：

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 写法：

$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 重试。

/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：

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

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

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

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

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。

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

创建线程：

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

发送 turn 并读取事件：

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，支持创建、列表、读取和取消：

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> 引用图片：

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

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

Skill、记忆与代码索引

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

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

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

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

快照与恢复

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

/snapshot
/restore 1
/snapshot clean

Python SDK

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

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.