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