localharness Skill 技能

技能简介

localharness 是一个为本地大模型（vLLM、llama.cpp、Ollama、LM Studio 任何 OpenAI 兼容端点）打造的"Agent Harness 中间层"——它本身不 serve 模型，而是连接你已经跑起来的本地模型，给它配上 YAML 描述的 Agent、内置 read / write / edit / glob / grep / bash / python / web search / web fetch 工具、每次工具调用前的权限闸门，以及在独立 context 里运行的辅助 Agent。手机 App、Discord、图像生成、自改进回路全部以插件形式存在，用一条命令开关即可。一个小型核心负责 Agent 循环，所有扩展都是同一个插件 API——意味着你写的第三方插件与官方插件享受同等待遇。整个项目在 NVIDIA DGX Spark 真机上做了端到端验证。

核心能力

• 跨本地运行时统一接入：vLLM（docker/binary）、llama.cpp（拉起 llama-server）、Ollama（拉起 ollama serve）、LM Studio（驱动无头 lms），全部走一套 OpenAI 兼容客户端
• Agent YAML 化：每个 Agent 通过 YAML 定义工具集、权限、上下文窗口、子 Agent 拓扑
• 强权限闸门：所有 Agent（含子 Agent）的所有工具调用都必须过同一个权限闸门；不可信内容（网页、MCP 结果）默认不允许接触能改机器的工具
• 子 Agent 隔离上下文：每个子 Agent 在全新 context 里跑，只看到被授权的工具，调用失败不会污染主 Agent 上下文
• MCP 服务器接入：内置 MCP 客户端，可加载任意 MCP 服务器扩展工具集
• 五大官方插件：image（接 ComfyUI 生成图片）/ mobile（手机 web 控制台）/ memory（持久记忆）/ dispatch（Discord chat）/ autoresearch（实验回路）
• 插件式 CLI 扩展：插件可以新增 tools、commands、slash commands、doctor 检查项、settings、chat channel
• 细粒度开关：localharness plugins enable image --set comfyui_url=... 单插件启用；overrides.yaml 与 config.yaml 分离，绝不污染用户配置

安装配置

1. 环境前置：Python 3.12+ 与 uv 必须安装；确保 vLLM / llama.cpp / Ollama / LM Studio 至少有一个在跑
2. 标准安装（含 memory 嵌入模型 + 手机 App）：uv tool install 'localharness[embeddings,mobile]'
3. 极简安装（仅核心）：uv tool install localharness
4. 接入 Discord 插件：uv tool install 'localharness[dispatch]'
5. 初始化配置：localharness init，自动探测模型服务器、写出 config.yaml、列出每个插件及启用命令
6. 查看插件状态：localharness plugins list，按需开关：localharness plugins disable autoresearch / localharness plugins enable image --set comfyui_url=http://127.0.0.1:8188

使用步骤

1. 跑首次会话：localharness start，无配置会自动跑 init 的设置流程然后进入 REPL
2. 会话内启用插件：输入 /plugins enable image，首次或未配置时它会问插件所需的额外信息，检查通过后会保留对话历史地重启会话
3. 查看插件能力：在会话中直接调用插件提供的工具（如 image 插件的 generate_image）；或在 CLI 跑 localharness generate-image "a cyberpunk cat"
4. 用手机控制：localharness mobile 启动移动端 web 控制台，配合 Tailscale 可在外网访问
5. 接 Discord：localharness plugins enable dispatch，按提示配置 token，然后在 Discord 服务器里直接对话触发 Agent
6. 写自己的插件：参考官方五个插件的代码（同套 plugin API），用 localharness plugins enable ./my-plugin 加载
7. 单项目覆盖：加 --workspace 参数让插件只在当前项目生效，不污染全局

适用场景

• 本地模型玩生产级 Agent：不想把代码/对话发给 OpenAI/Anthropic，但又要 Claude Code / Cursor 级别的工具能力
• 隐私敏感的代码工作流：律师、医生、金融从业者处理合规文件，需要本地 Agent 自动化
• NVIDIA DGX Spark / Apple Silicon 强机的日常 Agent 平台：充分利用本地算力
• Agent Harness 开发者：研究 Agent 循环 / 权限闸门 / 插件机制的二次开发基础
• Discord 机器人 + 本地 LLM：在 Discord 频道里直接召唤本地 Agent，不需要任何云 API
• 图像生成 + 编程 Agent：用 ComfyUI 生图后让 Agent 直接嵌入 README / 文档

适用人群

• 已有 vLLM / Ollama / llama.cpp / LM Studio 跑本地模型的开发者
• 对数据出境敏感的企业 / 律所 / 医疗机构
• Agent Harness 框架研究者、想搭自定义 Agent 平台的工程师
• 想用本地 LLM 做 Discord 机器人 / 手机 App 控制台的玩家

工作原理

localharness 把 Agent 拆成"核心 + 插件"两层。核心运行 Agent 循环：每次 LLM 调用把消息历史 + 工具定义 + 权限策略打包发给 OpenAI 兼容端点，收到 tool_calls 时按插件注册的工具表匹配并经权限闸门过滤后才执行；执行结果回写到消息历史进入下一轮。Agent 拓扑通过 YAML 描述，子 Agent 启动时获得全新 context 和被裁剪的工具集。权限闸门是中央化的——任何插件的工具调用都经过它；只在插件直接通过 tool registry 注册（不通过 tools() 返回）时才跳过，这是已知设计取舍（详见 SECURITY.md）。插件通过统一 plugin API 接入：可注册 tools、commands、slash commands、doctor 检查、settings、chat channel；关闭插件会自动移除它注入的所有内容（关闭 memory / autoresearch 保留磁盘文件）。所有运行时（vLLM / llama.cpp / Ollama / LM Studio）通过一个统一的 OpenAI 客户端抽象层接入，工具调用支持原生、XML/Hermes fallback、token 计数支持精确 / 估算两档，每种运行时的设置文档都列了优缺点。

官方链接

• PyPI：https://pypi.org/project/localharness/
• GitHub：https://github.com/ahwurm/localharness
• 插件总览：https://github.com/ahwurm/localharness/blob/main/docs/plugins
• 安全模型：https://github.com/ahwurm/localharness/blob/main/SECURITY.md
• 官方站点：https://localharness.dev