PaiCLI-Python: 터미널 기반 AI Agent CLI

PaiCLI Python은 파일 읽기/쓰기, 코드 검색, 명령어 실행, 네트워크 검색, MCP 도구 호출, 메모리 저장, 스냅샷 생성, 현장 복원 등 실제 프로젝트 개발 시나리오를 겨냥하여 터미널에서 작동하는 AI Agent CLI입니다. 또한 Runtime API를 통해 스레드(thread), 턴(turn), 이벤트(event) 및 백그라운드 작업 능력을 외부로 제공합니다.

이 저장소는 PaiCLI의 Python 버전이며, 단순한 빈껍데기 데모가 아닙니다. 실제 CLI 제품처럼 제작되었으며, 핵심 경로는 테스트 커버리지를 갖추고 있고 로컬 스모크(smoke) 및 실제 터미널 실행 검증을 거쳤습니다.

만약 Agent 엔지니어링 학습, 이력서 준비 또는 면접 준비가 목적이라면, 다음 튜토리얼 경로를 먼저 참고할 수 있습니다:

이 경로는 단순히 '첫 줄 소스 코드부터 마지막 줄까지' 배우는 것이 아니라, 실제 학습 및 취업 경로에 맞춰 구성되었습니다:

• PaiCLI를 로컬에서 실행하여 ReAct, 도구 호출(tool call), Plan 모드, 네트워크 검색 등이 어떻게 작동하는지 직관적으로 확인합니다.
• 프로젝트 기능을 이력서에 작성할 수 있는 모듈들로 분해합니다. 예: ReAct, Plan-and-Execute, Memory, RAG, MCP, HITL, 멀티모달 및 Runtime API
• 이후 이력서에 기재한 모듈을 중심으로 소스 코드를 깊이 파고들고, 이에 맞춰 대응하는 Agent 면접 질문도 준비합니다.
• 마지막으로 디버깅(debug), 버그 수정, 도구 추가, 장애물 기록 정리 등을 통해 프로젝트를 진정한 자신의 엔지니어링 경험으로 만듭니다.

튜토리얼 목차는 실전 편, 이력서 편, 면접 편을 모두 다루고 있으며, PaiCLI Java 버전 학습 및 본 Python 버전의 설계 차이점을 이해하는 데 적합한 로드맵입니다.

• Rich와 prompt-toolkit 기반의 대화형 터미널 Agent 렌더링
• 단일 프롬프트 모드(Single prompt mode): 스크립트, 파이프라인 및 자동 호출에 적합
• OpenAI 호환 스트리밍 LLM 클라이언트: 기본적으로 DeepSeek 설정을 지향
  DEEPSEEK_API_KEY 등 제공업체별 API 키 지원 - ReAct 도구 호출 루프: thinking, tool call, tool result, final output 및 usage 이벤트 지원
• Plan-and-Execute 모드: 독립적인 Planner를 사용하여 DAG(Directed Acyclic Graph)를 생성하고, 의존성에 따라 배치로 병렬 작업을 실행합니다.
• Multi-Agent 협업 모드: Planner, Worker, Reviewer, 의존성 스케줄링, 병렬 worker, review 재시도 기능 등을 포함하며, 독립적인 Plan-and-Execute로 전환 가능한 서브 Agent를 포함합니다.
• 내장 파일, Shell, grep, glob, 메모리, 웹 검색, 웹 크롤링, 코드 검색 등 다양한 도구 지원
• HITL(Human-in-the-Loop) 수동 확인, 명령어/경로 보안 정책 및 JSONL 감사 로그 기능
• MCP client: stdio 및 Streamable HTTP MCP 서버를 지원합니다.
• Skill 시스템: 내장형, 사용자 레벨, 프로젝트 레벨의 계층 구조를 지원하며, 입력 Top-K 매칭과 load_skill (현재 턴 지연 로딩), 그리고 HITL 확인을 거친 save_skill 기능을 제공합니다.

프로세스 축적 - Chrome DevTools MCP 설정 도우미

• PaiCLI 자체도 내장 도구를 노출하는 MCP 서버로 작동할 수 있습니다.

• Runtime API: 이력(history)이 있는 thread, turn, 이벤트 로그를 지원하며, 원자성 점유(atomic preemption), 임대 복구(lease recovery), 취소 보호(cancellation protection), 프로젝트 격리 및 react|plan|team 모드의 영속적인 백그라운드 작업을 지원합니다.

• 정적 프로젝트 메모리 + SQLite 동적 장기 메모리: 메타데이터, 중복 제거, TTL(Time To Live), 용량 관리 및 관련성 검색을 지원합니다.

• 컨텍스트 예산 및 압축: 사용 가능한 입력 예산의 80%에 도달하면 이전 턴을 압축하여 최근 메시지와 완전한 도구 호출만 보존합니다.

• 전체 usage, 캐시 적중/미적중 토큰, 추론(reasoning) 토큰 및 설정 가능한 비용 추정 기능을 제공합니다.

• Agent 실행 전후 자동 스냅샷 생성으로 현장 복원을 지원합니다.

• 로컬 이미지와 원격 이미지 입력을 모두 지원하며, 모델 능력에 따라 자동으로 다운그레이드됩니다.

• 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

단일 질의:

`uv run paicli -p

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별 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로 진입한 후, 다음 슬래시 명령어(slash commands)를 사용할 수 있습니다:

/help
/exit
/clear
... 

/model은 대화형 모델 선택기를 열어줍니다: Tab 키나 방향키로 Default, Custom 사이를 전환하고, 위아래 방향키로 모델을 선택한 후 Enter 키를 눌러 현재 Agent를 즉시 변경할 수 있습니다. Custom에서는 저장된 BYOK(Bring Your Own Key) 모델을 선택하거나, 새로운 DeepSeek/GLM/OpenAI-compatible 설정을 생성할 수 있으며, d를 누르면 설정을 삭제합니다. 사용자 정의 설정은 권한이 0600인 ~/.paicli/models.json에 저장됩니다. 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(Human-in-the-Loop), 그리고 audit 처리를 거칩니다. save_skill 역시 반드시 HITL을 거쳐야 합니다. 모델이 지식을 축적할 것을 제안하더라도 후속 행동이 조용히 변경되지는 않습니다.

대화형 모드에서는 Shift+Tab 키를 눌러 두 가지 세션 권한 모드 사이를 전환할 수 있습니다:

Default: 시작 시의 HITL, 작업 공간 경로 및 명령어 보안 정책을 사용합니다.
Auto (full access): 현재 세션 내에서 더 이상 승인 요청을 하지 않으며, 경로 및 명령어 가드를 비활성화합니다. 다시 Shift+Tab을 누르면 시작 시의 기본 정책으로 복구됩니다.

Skill은 builtin -> user -> project 순서로 로드되며, 이름이 같으면 후층(project)이 전층(builtin)을 덮어씁니다:

• 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을 호출할 수 있습니다.

이는 프로젝트 또는 사용자 레벨에 기록되며, 이 도구는 기본적으로 기존 Skill 덮어쓰기를 거부하고 강제로 수동 확인을 요구합니다.

PaiCLI는 메모리를 세 가지 계층으로 나눕니다:

• 단기 기억 (Short-term memory): 현재 thread/session의 원본 메시지, 도구 호출 및 도구 결과
• 정적 장기 기억 (Static long-term memory):
  AGENTS.md,
  PAI.md,
  .paicli/PAI.md
  및 사용자 정의 프롬프트 파일; 수동으로 유지 관리되며 버전 관리가 가능합니다.
• 동적 장기 기억 (Dynamic long-term memory): 프로젝트 범위(scope)별로 격리된 SQLite 기록입니다. kind, source, importance, confidence, TTL, 접근 횟수 및 내용 해시를 포함합니다.

동적 메모리는 더 이상 무조건 '최근 8개' 항목을 가져오지 않습니다. 모든 요청은 현재 질문에 따라 Top-K를 자동으로 검색하고 그 결과를 untrusted data로 명확히 표시된 동적 Prompt에 넣습니다. 모델이 후보군이 부족하다고 판단할 경우, search_memory를 호출하여 심층 검색을 수행할 수 있습니다.

쓰기(Write) 측면에서는 공백 값/초장문 값을 거부하고, 표준화된 해시로 중복을 제거하며, 프로젝트 용량에 따라 가치가 낮은 기록을 폐기합니다.

Prompt는 캐싱 가능한 정적 접두사(prefix)와 요청별 재구축되는 동적 접미사(suffix)로 나뉩니다. 정적 접두사는 신원, 규칙 및 프로젝트 지침을 담고 있으며; 동적 접미사는 현재 시간, cwd, 모델, 도구 및 현재 질문과 관련된 메모리를 담습니다.

사용 가능한 입력 예산은 context_window - max_output_tokens - reserve_tokens로 계산됩니다. 기본적으로 이 예산의 80%에서 압축을 트리거하여 약 55% 수준으로 낮추고, 후속 출력, 도구 결과 및 토크나이저 추정 오차를 위한 공간을 확보합니다. 압축 요약은 단기 세션에만 속하며 장기 기억으로 자동 승격되지 않습니다.

기본 provider/model은 deepseek/deepseek-v4-flash입니다. DeepSeek V4 Flash/Pro의 내장 프로필은 1M 컨텍스트를 사용하며, 2026-07-17 기준 공식 백만 토큰당 가격이 포함되어 있습니다. 가격은 변동되므로 llm.context_window와 llm.prices로 덮어쓸 수 있으며, 알 수 없는 OpenAI 호환 모델은 명시적으로 구성해야 합니다.

스트리밍 요청 시 stream_options.include_usage를 활성화하고, choices=[]의 usage-only 블록, 캐시 적중/미스(hit/miss) 및 추론 토큰을 분석합니다. REPL에서는 /usage로 최근 일반 ReAct 사용량을 확인하고, 단일 CLI에서는 --json으로 전체 사용량/비용을 가져옵니다. 비용은 공급업체가 반환하는 실제 토큰을 기준으로 하며, 단순히 '코드 라인 수'로 정확히 추산할 수 없습니다.

web_search는 DuckDuckGo HTML 검색을 사용하여 제목, URL 및 요약을 반환합니다.

web_fetch는 공개 HTTP/HTTPS 페이지를 크롤링하고 기본적인 본문 추출을 수행할 수 있습니다. 이는 file://, 루프백(loopback), 사설 네트워크 및 내부망 주소를 거부하여 SSRF 위험을 낮춥니다.

로그인 상태, 브라우저 상태 또는 JS 렌더링이 필요한 페이지의 경우 Chrome DevTools MCP 사용을 권장합니다.

PaiCLI는 MCP 서버에 연결하여 원격 도구를 다음과 같이 동적으로 등록할 수 있습니다:

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

프로젝트 레벨의 Chrome DevTools MCP를 초기화하려면 다음을 사용합니다:

uv run paicli mcp init-chrome --scope project

이는 .paicli/mcp.json에 다음과 같은 내용으로 기록됩니다:

{

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에게 권한을 부여하지 마십시오.

PaiCLI에는 외부 시스템 연결에 적합한 경량 Runtime API가 내장되어 있으며, 이를 통해 스레드(thread), 턴(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'

턴 전송:

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' \
...

이벤트 읽기:

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' \
...

HTTP 노출 없이 큐 소비자(queue consumer)만 시작할 수도 있습니다:

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

작업 큐는 프로젝트 디렉터리별로 격리됩니다. worker는 SQLite 원자 트랜잭션(atomic transaction)을 사용하여 작업을 가져오고, lease/heartbeat를 통해 충돌한 작업을 복구합니다. 실행 중 취소하면 worker가 지연된 결과를 'completed' 상태로 다시 덮어쓰는 것을 방지할 수 있습니다.

PaiCLI는 프롬프트 내에서 이미지 참조를 지원합니다:

분석这张截图 @image:./screenshots/page.png

절대 경로 및 원격 이미지도 지원합니다:

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

로컬 이미지는 자동으로 압축되고 축소되며, 필요할 때 투명 배경을 흰색 배경으로 변환한 후 data URL로 변환됩니다. 현재 provider/model이 멀티모달 입력(multimodal input)을 지원하지 않는 경우, PaiCLI는 자동으로 텍스트 메타 정보로 다운그레이드하여 지원되지 않는 이미지 페이로드(payload)를 모델에 전송하지 않습니다.

Agent run마다 프로젝트 스냅샷(snapshot)을 생성하려고 시도합니다:

pre-turn

post-turn

스냅샷은 ~/.paicli/snapshots/에 저장되며, 프로젝트의 .git에는 기록되지 않습니다.

REPL에서는 다음 명령어를 사용할 수 있습니다:

/snapshot
/restore 1
/snapshot clean

from paicli.sdk import create_default_engine
engine = create_default_engine(cwd=".")
result = engine.ask_complete("解释这个项目")
...

개발 의존성 설치:

uv sync --extra dev

실행 검사:

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

자주 사용되는 smoke 테스트:

uv run paicli --version
uv run paicli --help
uv run paicli doctor --cwd .
...

Python 버전은 Java / TypeScript 버전에서 공개된, 개방 프로토콜 관련 주요 Agent CLI 기능을 모두 포함하고 있습니다. 여기에는 CLI, REPL, ReAct, Plan-and-Execute, Multi-Agent, Skill, SDK, 도구 호출(tool calling), MCP, Runtime API, 메모리(memory), 스냅샷(snapshot), 인터넷 연결 도구, 이미지 입력 기능이 포함됩니다.

Java 버전에는 사적인 WeChat iLink 채널도 있습니다. Python 저장소에는 이 사적 채널이 내장되어 있지 않은데, 이는 계정, QR 코드 로그인 및 프로토콜 자격 증명에 의존하기 때문에 가짜 구현으로 모방해서는 안 되기 때문입니다.

더 자세한 기능 동등성(parity) 상황은 docs/parity.md를 참조하십시오.

MIT. LICENSE 참고.