work-with-llamacpp

Pi extension that bridges your local llama.cpp server to the agent — vision, translation, and general text tasks without cloud tokens. / Pi 扩展：让 agent 调用本地 llama.cpp（看图、翻译、通用文本任务），不消耗云端 token。

Packages

Package details

extension

Install work-with-llamacpp from npm and Pi will load the resources declared by the package manifest.

npm report
$ pi install npm:work-with-llamacpp
Package
work-with-llamacpp
Version
1.0.2
Published
Aug 18, 2026
Downloads
513/mo · 11/wk
Author
n7ght
License
MIT
Types
extension
Size
50.1 KB
Dependencies
0 dependencies · 2 peers
Pi manifest JSON
{
  "extensions": [
    "./extensions"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

work-with-llamacpp

🌐 English: README.en.md

让 pi（AI 编程助手）调用本地 llama.cpp server 的桥接扩展：看图、翻译、跑通用文本任务，以减少token使用。

✨ 功能特性

  • 🔍 自动检测：会话启动和每轮对话前自动探测 llama.cpp server（HTTP /props，失败兜底查进程）
  • 🧠 类型识别：自动判断视觉模型（挂了 mmproj）还是文本模型，也可手动指定
  • 🖼️ 看图（llama_cpp_vision）：把图片（本地路径或 URL）发给本地视觉模型分析
  • 🌐 翻译（llama_cpp_translate）：翻译优化 prompt，支持多语言互译
  • ⚙️ 通用跑活（llama_cpp_chat）：摘要、改写、纠错、提取关键词等
  • 💉 隐性状态注入：每轮向系统提示注入一句模型状态（LLM 可见、界面不可见、不占累积上下文）
  • 🔑 apiKey 支持：兼容 llama-server --api-key 设置的密码，请求自动带鉴权头
  • 🖥️ 状态条 + 通知：常驻状态条，状态变化只通知一次（不重复刷屏）

📦 安装

# npm 包安装（推荐）
pi install npm:work-with-llamacpp

# 或 git 源安装
pi install git:github.com/kikilloy/work-with-llamacpp

安装后执行 /reload 生效。

🚀 使用

命令

命令 说明
/work-llamacpp-status [refresh] 查看/刷新 llamacpp 检测状态
/work-llamacpp-mode [auto|vision|text|full] 切换模型模式（无参=循环切换）
/work-llamacpp-config 交互式设置端口和 apiKey（密码）
/work-llamacpp-config port 8080 直接设端口（0=自动探测）
/work-llamacpp-config apikey <密码> 直接设密码（- 清除）

工具（agent 按需自动调用）

工具 用途
llama_cpp_vision 本地视觉模型分析图片
llama_cpp_translate 本地文本模型翻译
llama_cpp_chat 本地文本模型通用任务

⚙️ 配置

配置文件 ~/.pi/agent/extensions/work-with-llamacpp/config.json：

{
  "port": 0,                 // 端口，0=自动探测 commonPorts
  "commonPorts": [8080, 8081, 1234, 8000],
  "cacheMs": 30000,          // 检测结果缓存毫秒
  "probeTimeoutMs": 2500,    // 单端口探测超时毫秒
  "modelType": "auto",       // auto | vision | text | full（full=全能力：看图+翻译+文本）
  "capabilities": [],        // vision/translate/chat，留空按类型推断（mode 命令会清空此项）
  "apiKey": "",              // llama-server --api-key 设置的密码
  "maxImageBytes": 20971520, // 图片大小上限（默认 20MB）
  "maxTokens": 8192          // 本地模型输出长度上限（工具可用 max_tokens 参数覆盖）
}

配置优先级：配置文件 > 环境变量 LLAMACPP_PORT > 代码默认值。

💡 模式说明：/work-llamacpp-mode 切换 auto/vision/text/full 四种模式——auto 自动检测（挂 mmproj → 视觉）；vision 强制视觉（看图+文本任务）；text 强制文本（翻译+文本任务）；full 全能力（看图+翻译+文本任务）。状态栏会显示当前类型与能力组合。

🔧 启动 llama.cpp

# 文本模型（翻译/通用任务）
llama-server -m /path/to/model.gguf

# 视觉模型（看图，需 mmproj）
llama-server -m /path/to/model.gguf --mmproj /path/to/mmproj.gguf

# 带密码启动
llama-server -m /path/to/model.gguf --api-key 你的密码

⚠️ 安全提示

Pi 扩展拥有完整系统权限，请只安装可信来源的包。apiKey 以明文保存在本地配置文件中，请妥善保管。

📄 License

MIT

made by DEEPSEEK