PaiCLI Python 是一个运行在终端里的 AI Agent CLI,面向真实项目开发场景:读写文件、搜索代码、执行命令、联网检索、调用 MCP 工具、保存记忆、生成快照、恢复现场,并通过 Runtime API 对外提供线程、turn、事件和后台任务能力。

这个仓库是 PaiCLI 的 Python 版本。它不是一个空壳 Demo,而是按真实 CLI 产品来做:核心路径有测试覆盖,也经过本地 smoke 和真实终端运行验证。
配套教程路线
如果你是为了学习 Agent 工程、准备简历或准备面试,可以先看这条教程路线:
PaiCLI 学习路线:手搓一个 Java 版 Claude Code
这篇路线不是单纯教你“从第一行源码看到最后一行”,而是按真实学习和求职路径来组织:
- 先把 PaiCLI 在本地跑起来,直观看到 ReAct、工具调用、Plan 模式和联网搜索是怎么工作的
- 再把项目能力拆成可以写进简历的模块,比如 ReAct、Plan-and-Execute、Memory、RAG、MCP、HITL、多模态和 Runtime API
- 然后围绕简历里写到的模块去深挖源码,并同步准备对应的 Agent 面试题
- 最后通过 debug、改 bug、加工具、整理踩坑笔记,把项目真正变成自己的工程经验
教程目录覆盖实战篇、简历篇和面试篇,适合作为学习 PaiCLI Java 版和理解本 Python 版设计取舍的路线图。

功能特性
- 交互式终端 Agent,基于 Rich 和 prompt-toolkit 渲染
- 单次 prompt 模式,适合脚本、管道和自动化调用
- OpenAI-compatible 流式 LLM 客户端,默认面向 DeepSeek 配置
- 支持
DEEPSEEK_API_KEY等 provider-specific API Key - ReAct 工具调用循环,支持 thinking、tool call、tool result、final output 和 usage 事件
- Plan-and-Execute 模式,使用独立 Planner 生成 DAG,并按依赖批次执行可并行任务
- Multi-Agent 协作模式,包含 Planner、Worker、Reviewer、依赖调度、并行 worker、review 重试,以及可切换到独立 Plan-and-Execute 的子 Agent
- 内置文件、Shell、grep、glob、记忆、网页搜索、网页抓取、代码搜索等工具
- HITL 人工确认、命令/路径安全策略和 JSONL 审计日志
- MCP client,支持 stdio 和 Streamable HTTP MCP server
- Skill 系统,支持内置、用户级和项目级分层、输入 Top-K 匹配、
load_skill当前回合懒加载, 以及经 HITL 确认的save_skill流程沉淀 - Chrome DevTools MCP 配置助手
- PaiCLI 自身也可以作为 MCP server 暴露内置工具
- Runtime API,支持有历史的 thread、turn、事件日志,以及带原子抢占、租约恢复、取消保护、
项目隔离和
react|plan|team模式的持久化后台任务 - 静态项目记忆 + SQLite 动态长期记忆,支持元数据、去重、TTL、容量治理和相关性召回
- 上下文预算与压缩:达到可用输入预算的 80% 后压缩旧轮次,保留近期消息和完整工具调用对
- 完整 usage、缓存命中/未命中 Token、reasoning Token 和可配置成本估算
- Agent run 前后自动创建快照,支持恢复现场
- 支持本地图片和远程图片输入,并根据模型能力自动降级
环境要求
- Python 3.11 或更新版本
- uv
- 可选:
rg,用于更快的本地搜索 - 可选:Chrome DevTools MCP 需要 Node.js 20.19.0 LTS 或更新版本、npm/npx 和 Chrome
快速开始
git clone https://github.com/itwanger/PaiCLI-Python.git
cd PaiCLI-Python
uv sync --extra dev
uv run paicli --help
启动交互模式:
uv run paicli
单次查询:
uv run paicli -p "帮我总结这个项目"
选择运行模式并输出机器可读的 usage/cost:
uv run paicli --mode plan -p "先读取 README,再验证项目" --json
uv run paicli --mode team --worker-mode plan -p "并行审计核心模块" --json
检查当前环境:
uv run paicli doctor --cwd .
配置
PaiCLI 的配置优先级如下:
- 内置默认配置
~/.paicli/config.json- 项目级
.paicli/config.json - 项目级
.env - CLI 参数
- 当前进程环境变量
可以像 Java 项目一样,把 DeepSeek Key 写到项目 .env 里:
PAICLI_PROVIDER=deepseek
PAICLI_MODEL=deepseek-v4-flash
DEEPSEEK_API_KEY=your_key_here
也可以使用 PaiCLI 通用 Key:
PAICLI_PROVIDER=deepseek
PAICLI_MODEL=deepseek-v4-flash
PAICLI_API_KEY=your_key_here
当前支持的 provider-specific API Key 包括:
DEEPSEEK_API_KEYZAI_API_KEY(GLM 官方推荐)GLM_API_KEYSTEP_API_KEYKIMI_API_KEY
通过命令行临时覆盖 provider 和 model:
uv run paicli --provider deepseek --model deepseek-v4-flash
连接本地 OpenAI-compatible 服务:
PAICLI_PROVIDER=openai-compatible \
PAICLI_BASE_URL=http://127.0.0.1:11434/v1 \
PAICLI_MODEL=qwen2.5-coder \
uv run paicli -p "解释这个仓库"
交互命令
进入 uv run paicli 后,可以使用这些 slash commands:
/help
/exit
/clear
/context
/memory
/memory search <query>
/memory stats
/memory delete <id>
/memory clear
/save <fact>
/config
/tools
/hitl default|auto
/policy
/audit [N]
/index [path]
/search <query>
/plan <task>
/team <task>
/team --plan <task>
/model
/model <model-id>
/model <provider> <model-id>
/usage
/skill
/skill list
/skill show <name>
/skill on <name>
/skill off <name>
/skill reload
/mcp
/task
/task add [--mode react|plan|team] <task>
/task cancel <task_id>
/task log <task_id>
/snapshot
/snapshot clean
/restore <snapshot-id-or-index>
No comments yet.