Purple CLI

Purple CLI

状态：暂停（2026年4月）。 开发工作暂停，而紫色指令侧重于创收产品。代码库将被保留，并在适当的时候恢复。模型训练管道存档于 拥抱脸 （私人）。

具有本地推理+MCP工具调用的本地AI代理。7个核心文件中约5000行Python。没有框架，没有OpenAI垫片，你和模型之间没有抽象。

它的作用

• 双重推理后端：奥拉马(/api/chat)对于GGUF型号，vllm-mlx(/v1/chat)适用于Apple Metal（启动时自动检测）
• 通过FastMCP STDIO传输调用MCP工具
• 从配置文件加载MCP服务器——在一行中添加您自己的服务器
• 在生成令牌时逐令牌流式传输输出令牌
• 当模型从JSON回退时捕获XML格式的工具调用（Qwen3 Coder解决方法）
• 使用自动修剪旧消息的滑动窗口管理上下文
• 从Markdown标识文件中注入当前日期+系统提示
• 规划模式(/plan, /build)用于编码前的结构化问题解决
• 运行交互式或一次性(python purple.py "your prompt")

v0.4中的新功能

• 系统服务器 --文件操作、shell执行、grep和网络工具作为MCP服务器。使工具数量达到19个。
• 代理身份 --6个代理身份文件（Violet、Evolution、Improvement、Keenness、Research Coordinator、A1 Clinical）用于特定领域的系统提示。
• V7/V8 eval电池 --使用Claude API比较基线扩展测试套件。
• 教学管道 --隔夜验证、人工审查摄入和QLoRA微调脚本。
• PHI扫描仪 --基于正则表达式的扫描程序，用于会话记录中受保护的健康信息。
• 看门狗 --使用ntfy推送通知进行转录监控。
• 基础架构脚本 --用于多设备部署的备份、同步和状态管理。

v0.3中的新功能

• vllm-mlx后端 --通过MLX进行Apple Metal推理，在MoE架构上速度提高2倍。启动时自动检测到。
• 统一大脑服务器 --在一个MCP服务器中存储、知识、网络搜索和教学（8个工具）。替换单独的内存+知识服务器。
• 日期感知搜索 --将当前日期注入系统提示，以便网络搜索使用正确的年份。
• 计划模式 -- /plan 思考一个问题， /build 切换到执行。
• 评估框架 --V6测试电池（15个测试，215个断言）+用于教学工件的增量测试。
• Vega微调管道 --数据集构建器、QLoRA训练、abliteration、服务脚本。
• SearXNG集成 --自托管多引擎搜索（Docker on purpleroom）。
• 会话挂钩 --预压缩上下文保护程序、秘密扫描仪、会话结束转录存档器。

v0.2中的新功能

• 会话记录 --每个对话都保存为JSONL
• 终端仪表板 --256色ANSI显示屏，带圆形框、进度条和指标
• 试验场分级系统 --跟踪模型性能（TCR、FTA、UOR），自动升级/降级
• 工具预算执行 --限制顺序思维和空查找
• 新命令： /knowledge, /history, /model, /sessions

内置电池

附带4台MCP服务器（19个工具）：

紫色系统 --文件操作+shell+搜索（4个工具）

• read_file / write_file --带路径验证的文件I/O
• run_command --带超时和输出捕获的Shell执行
• grep_files --递归内容搜索

紫脑 --统一记忆+知识+搜索（8个工具）

• store_memory / search / forget_memory --混合搜索的持久记忆（FTS5+向量相似性）
• store_knowledge / log_outcome --具有有效性跟踪的教学知识库
• store_training_example --积累微调数据
• web_search / fetch_page --通过SearXNG（多引擎）进行网络搜索，并回退到DuckDuckGo

紫色文档 --文件处理（6个工具）

• read_pdf --从PDF中提取文本和表格（支持页面范围）
• read_excel --阅读电子表格（所有表格或特定表格）
• create_excel --从JSON构建样式化工作簿
• create_word --生成带有标题、列表、表格的Word文档
• create_powerpoint --使用多种布局创建演示文稿
• list_directory --浏览包含大小和类型信息的文件

顺序思维 --扩展推理（1个工具，通过NPX）

• 预算执行复杂问题的多步推理

所有服务器都强制执行路径验证——文件操作仅限于主目录和 /tmp.

先决条件

• Python 3.11+ --检查一下 python3 --version
• 奥拉玛 --安装并开始 ollama serve
• 工具调用模型 --例如。 ollama pull qwen3-coder:30b （或任何支持函数调用的模型）
• 可选： vllm-mlx 用于更快的Apple Metal推理

快速开始

一个命令设置

git clone https://github.com/PurpleDirective/purple-cli.git ~/.purple
cd ~/.purple
bash setup.sh
source venv/bin/activate
python cli/purple.py

手动设置

# Clone
git clone https://github.com/PurpleDirective/purple-cli.git ~/.purple
cd ~/.purple

# Create virtual environment and install dependencies
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Set up config files
cp config/mcp.example.json config/mcp.json
cp identity/identity.example.md identity/identity.md

# Create the default model (or use your own -- see below)
ollama create purple -f config/Modelfile

# Run
python cli/purple.py

注： 该项目位于 ~/.purple （隐藏目录）。使用 cd ~/.purple 克隆后访问它。

或者跳过自定义模型，直接使用任何工具调用模型：

OLLAMA_MODEL=qwen3-coder:30b python cli/purple.py "summarize this PDF"

记忆是如何工作的

内存存储在SQLite数据库中 ~/.purple/brain/purple_brain.db数据库在首次使用时自动创建。

• 记忆在会话中持续存在——关闭Purple，重新打开它，你的记忆仍然存在
• 每个内存都有一个类型(fact, preference, experience, correction)以及可选标签
• 搜索使用混合匹配（FTS5全文+通过句子嵌入的向量相似性）
• 数据库使用WAL模式进行安全的并发访问
• 文件权限自动设置为仅限所有者（chmod 600）
• 数据库被排除在git（in .gitignore)--你的记忆留在你的机器上

建筑

you --> Purple CLI --> Ollama /api/chat  --> your model (GGUF)
            |     \-> vllm-mlx /v1/chat --> your model (MLX)
            |
            +--> MCP Servers (STDIO) --> tools
                    |
                    +-- purple-system (file ops, shell, grep)
                    +-- purple-brain (SQLite: memory + knowledge + search)
                    +-- purple-docs (PDF, Excel, Word, PowerPoint)
                    +-- sequential-thinking (extended reasoning)
                    +-- [your servers here]

CLI是编排器。它将您的消息与工具定义一起发送到推理后端，返回文本或工具调用，通过MCP执行工具，将结果发送回模型，并重复直到模型以文本响应。每回合最多10次工具调用回合。

配置

config/mcp.json --声明MCP服务器。每个条目都有一个命令数组和一个启用的标志。创建于 config/mcp.example.json 在安装过程中（或首次运行时自动创建）：

{
  "servers": {
    "purple-brain": {
      "command": ["python3", "brain/server.py"],
      "enabled": true
    }
  }
}

服务器命令从运行 ~/.purple 目录。如果您安装到虚拟环境中，请更新命令以使用您的venv Python：

"command": ["/home/you/.purple/venv/bin/python3", "brain/server.py"]

config/Modelfile --Ollama模型定义。使用工具使用规则设置上下文窗口、温度和系统提示。

identity/identity.md --启动时加载系统提示。这就是你模特的个性。在这里写下你想写的任何东西。创建于 identity/identity.example.md 在安装过程中（或首次运行时自动创建）。

环境变量

比较

|---|---|---|---| |推理|Ollama+vllm-mlx（自动检测）|Ollama SDK |多提供商（OpenAI、Groq、llama.cpp）| |MCP传输|STDIO|STDIO、SSE、流式HTTP |STDIO，HTTP| |工具调用回退|对损坏的JSON进行XML解析|无|无| |流媒体|是|是|有| |上下文管理|滑动窗口修剪|保留令牌+历史导出|令牌跟踪+会话持久性| |捆绑工具| 19个工具（系统、大脑、文档、思维）|无（自带）|无| |网络搜索|内置（SearXNG+DuckDuckGo）|无|无| |评估框架| V6电池（15次测试，215次断言）|无|无| |配置格式|JSON|TOML|JSON| |代码库|~5000行，7个核心文件|更大，完整的TUI |更小，多LLM重点|

这些是成熟的、积极开发的项目，拥有更大的社区。Purple的角度是不同的：它附带了开箱即用的有用工具，处理了开放权重模型所需的XML回退，并使整个代码库足够小，可以一次阅读。如果你想要一个功能齐全的TUI，请使用ollmcp。如果您需要多提供商支持，请使用mcp-client-cli。如果你想要一个下午就能理解和破解的东西，可以使用Purple。

故障排除

“无法打开需求文件” --确保你在 ~/.purple 目录： cd ~/.purple 然后 pip install -r requirements.txt.

“没有名为'fastmcp'的模块” --未安装依赖项。跑 pip install -r requirements.txt 在您的虚拟环境中。

启动时“无法连接到Ollama” --Ollama没有跑。从以下内容开始 ollama serve 或者检查它是否在监听 http://localhost:11434.

“找不到配置：mcp.json” --快跑 cp config/mcp.example.json config/mcp.json，或让CLI在下次运行时自动创建它。

MCP服务器无法启动 --如果您安装在venv中，请更新 config/mcp.json 使用venv Python的完整路径（例如。， "/home/you/.purple/venv/bin/python3").

“未找到型号‘紫色：最新’” --要么创建它 ollama create purple -f config/Modelfile，或设置不同的模型： OLLAMA_MODEL=qwen3-coder:30b python cli/purple.py.

项目结构

~/.purple/
  cli/
    purple.py                # CLI + inference client + MCP orchestrator
    dashboard.py             # 256-color terminal display renderer
    tracker.py               # SQLite tier tracker + metrics
  system/server.py           # File ops + shell + grep MCP server
  brain/server.py            # Unified memory + knowledge + search MCP server
  docs/server.py             # Document handling MCP server
  agents/                    # Agent identity files (Violet, Evolution, Improvement, etc.)
  eval/
    v6_tests.py, v6_runner.py    # V6 eval battery (15 tests, 215 assertions)
    v7_tests.py, v7_runner.py    # V7 eval battery (expanded + Claude baselines)
    v8_tests.py, v8_runner.py    # V8 eval battery (latest)
    delta_test.py                # Teaching artifact delta test
  teaching/
    verify/overnight.py          # Overnight fragment verification pipeline
    verify/ingest_approved.py    # Ingest human-approved fragments
    finetune/train.py            # QLoRA fine-tuning via Unsloth
    finetune/eval.py             # Post-training evaluation
  scripts/                   # Vega fine-tuning, PHI scanner, backup, sync, watchdog
  hooks/                     # Session hooks (pre-compact, scan-secrets, session-start/end)
  watchdog/                  # Transcript monitoring + ntfy notifications
  search/                    # SearXNG config (docker-compose + settings)
  config/                    # MCP config, Ollama Modelfile
  identity/                  # System prompt (created from example, not committed)
  sessions/                  # JSONL transcripts (not committed)
  requirements.txt
  setup.sh

运行测试

source venv/bin/activate
python -m pytest tests/ -v

所有测试都在没有Ollama的情况下运行——外部依赖关系被嘲笑了。

许可证

麻省理工学院

构建于

建于 克劳德代码.