PaiCLI Python

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

LLM Mart 12 views 457k listing impressions

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 的配置优先级如下:

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

可以像 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_KEY
  • ZAI_API_KEY(GLM 官方推荐)
  • GLM_API_KEY
  • STEP_API_KEY
  • KIMI_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>

From the project's README.

Comments (0)

Sign in to join the conversation.

No comments yet.