Installation

Add to your Claude Code skills directory:

# Add to your Claude Code skills
git clone https://github.com/itwanger/PaiCLI-Python

Security Report

Verified

Last scanned: —

{
  "status": "PASSED",
  "issues": []
}

README.md

PaiCLI Python

Name: PaiCLI-Python
Author: itwanger

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

/model 会打开交互式模型选择器：Tab 或左右方向键在 Default、Custom 之间切换，上下方向键选择模型，Enter 立即切换当前 Agent。Custom 中可以选择已保存的 BYOK 模型、创建新的 DeepSeek/GLM/OpenAI-compatible 配置，或按 d 删除配置。自定义配置保存在权限为 0600 的 ~/.paicli/models.json；建议填写 API Key 环境变量名，只有显式输入 API Key 时才会把密钥写入该文件。

内置工具

PaiCLI 内置了一组 Agent 可以调用的本地工具和联网工具：

read_file
write_file
list_dir
glob / glob_files
grep / grep_code
bash / execute_command
web_search
web_fetch
save_memory
search_memory
load_skill
save_skill
search_code
revert_turn

写文件、执行命令、远程 MCP 写操作、恢复快照等危险动作，会经过 policy、HITL 和 audit 处理。 save_skill 也必须经过 HITL；模型可以提议沉淀，但不会静默改变后续行为。

交互模式下按 Shift+Tab 可在两种会话权限模式间切换：

Default：使用启动时的 HITL、工作区路径和命令安全策略。
Auto (full access)：当前会话内不再请求审批，并关闭路径与命令守卫；再次按 Shift+Tab 会恢复启动时的默认策略。

Skill 匹配与沉淀

Skill 按 builtin -> user -> project 加载，同名时后层覆盖前层：

builtin：产品默认能力
user：~/.paicli/skills/*/SKILL.md，跨项目复用
project：.paicli/skills/*/SKILL.md，最贴近当前仓库并拥有最高优先级

每次用户输入先用 name、description、tags 做中英文词法/字符 n-gram Top-K 匹配，再把候选交给模型决定是否调用 load_skill。Skill 正文只在真正加载后进入当前 ReAct 的下一模型轮；每个并发子 Agent 都有独立 Skill 缓冲区，不会串线。

当一次成功流程具备稳定输入、明确步骤和可复用边界时，模型可以调用 save_skill 提议写入 project 或 user 层。该工具默认拒绝覆盖已有 Skill，并强制人工确认。

记忆、动态 Prompt 与上下文压缩

PaiCLI 把记忆分成三层：

短期记忆：当前 thread/session 的原始消息、工具调用和工具结果
静态长期记忆：AGENTS.md、PAI.md、.paicli/PAI.md 及自定义 prompt 文件；人工维护、可版本控制
动态长期记忆：按项目 scope 隔离的 SQLite 记录；包含 kind、source、importance、confidence、TTL、访问次数和内容哈希

动态记忆不会再无条件取“最近 8 条”。每个请求会按当前问题自动召回 Top-K，并把结果放进明确标注为 untrusted data 的动态 Prompt；模型觉得候选不足时，还可以调用 search_memory 深搜。写入端会拒绝空值/超长值，通过规范化哈希去重，并按项目容量淘汰低价值记录。

Prompt 分为可缓存的静态前缀和逐请求重建的动态后缀。静态前缀承载身份、规则和项目指令；动态后缀承载当前时间、cwd、模型、工具以及与当前问题相关的记忆。

可用输入预算按 context_window - max_output_tokens - reserve_tokens 计算。默认在该预算的 80% 触发压缩，压到 55% 左右，为后续输出、工具结果和无 tokenizer 估算误差留出空间。压缩摘要只属于短期会话，不会自动晋升为长期记忆。

模型、Token 与费用

默认 provider/model 是 deepseek/deepseek-v4-flash。DeepSeek V4 Flash/Pro 的内置 profile 使用 1M 上下文，并带有截至 2026-07-17 的官方每百万 Token 价格；价格会变化，因此可以用 llm.context_window 和 llm.prices 覆盖，未知 OpenAI-compatible 模型应显式配置。

流式请求开启 stream_options.include_usage，并解析 choices=[] 的 usage-only 块、cache hit/miss 和 reasoning Token。REPL 用 /usage 查看最近一次普通 ReAct，单次 CLI 用 --json 获取完整 usage/cost。成本以供应商返回的实际 Token 为准，不能只用“代码行数”精确推算。

联网工具

web_search 使用 DuckDuckGo HTML 搜索，返回标题、URL 和摘要。

web_fetch 可以抓取公开 HTTP/HTTPS 页面，并做基础正文提取。它会拒绝 file://、loopback、私有网络和内网地址，降低 SSRF 风险。

如果需要登录态、浏览器状态或 JS 渲染页面，建议使用 Chrome DevTools MCP。

MCP

PaiCLI 可以连接 MCP server，并把远端工具动态注册为：

mcp__<server-name>__<tool-name>

初始化项目级 Chrome DevTools MCP 配置：

uv run paicli mcp init-chrome --scope project

它会写入 .paicli/mcp.json，内容类似：

{
  "mcpServers": {
    "chrome-devtools": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--no-usage-statistics"
      ]
    }
  }
}

连接已有 remote-debugging Chrome：

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

查看已配置的 MCP server：

uv run paicli mcp list

把 PaiCLI 自身作为 MCP server 暴露：

uv run paicli mcp serve --transport stdio
uv run paicli mcp serve --transport http --port 3000

HTTP smoke：

curl -sS -X POST http://127.0.0.1:3000 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Chrome DevTools MCP 会把浏览器页面和 DevTools 状态暴露给 Agent。不要随意把包含个人账号、敏感数据或生产后台的 Chrome 会话授权给 Agent。

Runtime API

PaiCLI 内置轻量 Runtime API，适合外部系统接入线程、turn、事件和后台任务。

启动服务：

PAICLI_RUNTIME_API_KEY=dev-key \
uv run paicli serve --http --port 8080

创建线程：

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'

创建并查看后台任务：

curl -sS -X POST http://127.0.0.1:8080/v1/tasks \
  -H 'content-type: application/json' \
  -H 'x-api-key: dev-key' \
  -d '{"message":"后台总结这个仓库","mode":"plan"}'

curl -sS http://127.0.0.1:8080/v1/tasks \
  -H 'x-api-key: dev-key'

也可以只启动队列消费者，不暴露 HTTP：

uv run paicli worker --workers 2 --cwd .

任务队列按项目目录隔离；worker 使用 SQLite 原子事务领取任务，并通过 lease/heartbeat 恢复崩溃任务。运行中取消会阻止 worker 把迟到结果重新覆盖为 completed。

图片输入

PaiCLI 支持在 prompt 里引用图片：

分析这张截图 @image:./screenshots/page.png

也支持绝对路径和远程图片：

解释这张图 @image:/Users/me/Desktop/diagram.png
看看这个图片 @image:https://example.com/image.png

本地图片会自动压缩、缩放，并在需要时把透明底铺成白底，再转为 data URL。如果当前 provider/model 不支持多模态输入，PaiCLI 会自动降级为文本元信息，不会把不支持的图片 payload 发给模型。

快照

每次 Agent run 都会尽力创建项目快照：

pre-turn
post-turn

快照保存在 ~/.paicli/snapshots/，不会写入项目 .git。

REPL 中可以使用：

/snapshot
/restore 1
/snapshot clean

SDK

from paicli.sdk import create_default_engine

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

plan_result = engine.plan_complete("先读取 README，再总结项目结构")
team_result = engine.team_complete("让多个 Agent 并行检查核心模块")

开发

安装开发依赖：

uv sync --extra dev

运行检查：

uv run python -m ruff check .
uv run python -m ruff format --check .
uv run python -m pytest
uv build

常用 smoke：

uv run paicli --version
uv run paicli --help
uv run paicli doctor --cwd .
uv run paicli --plain -p hello

和 Java / TypeScript 版本的关系

Python 版覆盖了 Java / TypeScript 版本里公开、开放协议相关的主要 Agent CLI 能力，包括 CLI、REPL、ReAct、Plan-and-Execute、Multi-Agent、Skill、SDK、工具调用、MCP、Runtime API、记忆、快照、联网工具和图片输入。

Java 版本里还有一个私有的微信 iLink 通道。Python 仓库没有内置这个私有通道，因为它依赖账号、扫码登录和协议凭证，不应该用假实现冒充。

更详细的实现对齐情况见 docs/parity.md。

License

MIT. See LICENSE.

Frequently Asked Questions

What is PaiCLI-Python?⌄

PaiCLI-Python is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by itwanger. Python terminal AI agent CLI with ReAct tools, MCP, Runtime API, memory, snapshots, web search, and image input. It has 57 GitHub stars.

Is PaiCLI-Python safe to use?⌄

Yes. PaiCLI-Python passed SkillsLLM's automated security scan — a dependency vulnerability audit plus prompt-injection heuristics — with no high-severity issues. You can read the full report in the Security Report section on this page.

How do I install PaiCLI-Python?⌄

Clone the repository with "git clone https://github.com/itwanger/PaiCLI-Python" and add it to your Claude Code skills directory (see the Installation section above).

What programming language is PaiCLI-Python written in?⌄

PaiCLI-Python is primarily written in Python. It is open-source under itwanger on GitHub, so you can review or fork the full source.

Are there alternatives to PaiCLI-Python?⌄

Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh PaiCLI-Python against similar tools.

PaiCLI-Python