Helmdeck

helmdeck

今天安装的 helmdeck 使用 gpt-oss-120b 完成了一轮完整的 6 步代码编辑循环（克隆、读取、修补、测试、提交、推送），费用为 $0.07。通过 Cursor 或 Claude Code 直接使用 Sonnet 执行同样的循环，费用会达到 $0.30+。结果相同，价格便宜约 5 倍——而且“昂贵”的技术栈甚至不是最贵的选择。

工作流	前沿模型方案	Helmdeck（gpt-oss-120b）
浏览器抓取 + GitHub 评论	$0.25（Anthropic Computer Use）	$0.005
代码编辑循环（6 步）	$0.35（Cursor / Aider）	$0.07
多步浏览器测试	$0.20（Browser-use NL）	$0.03
PDF → 结构化 Markdown	$1.00（直接使用 Sonnet 视觉能力）	$0.003

大多数浏览器 Agent 都需要 GPT-4o 或 Claude Sonnet 才能可靠运行。Helmdeck 为其余 99% 的部署场景而构建——本地 7B 模型、气隙环境，以及无法将凭据发送到云 API 的团队。 它将每项浏览器、桌面、git 和代码操作封装成一个类型化 JSON 调用，即使小模型也能正确填写。由此得出的结果显而易见：当工具包承担了 LLM 原本会耗费 token 重新探索的工作时，廉价或本地模型也能胜任 Agent 式工作，而前沿模型 API 的收费要高出 10 倍。

这是一个可自托管、容器化的平台，面向 AI Agent，并以 能力包（经过架构验证、一次性使用的 JSON 工具）和原生 MCP 的形式提供服务。其标志性指标是：在 7B–30B 级别的开放权重模型上，工具包成功率达到 ≥90%；没有任何面向前沿模型的竞品在以此为优化目标。

📊 https://helmdeck.dev/explanation/why-helmdeck 提供了完整的单任务对比及复现步骤。这些是维护者个人的发现；欢迎社区复现。

为什么要做这个项目

强大的模型在 bash 和 README 的帮助下如鱼得水。较弱的模型则会被开放式接口难住。Helmdeck 将浏览器会话、桌面操作、凭据和多步工作流隐藏在单个类型化 REST / MCP 调用之后，弥合了这一差距。

主要面向以下三类用户：

• 自托管 AI 团队：无法离开自己的 VPC，需要不会向外发送数据的原生 MCP 基础设施。
• LocalLLaMA / Ollama 用户群体：运行 7B–30B 模型——工具包契约能让小模型保持可靠，而开放式工具接口则难以做到这一点。
• 对安全敏感的组织：需要 Agent 登录 SaaS 应用，同时确保模型完全看不到凭据（由保险库支持的占位令牌 + MCP 层级审计）。

状态

v0.22.0 已发布——让 Agent 在免费模型上运行，并具备记忆功能。 此版本完成了 ADR 047–050：

• 流水线路由 + 路由记忆（ADR 047）——helmdeck.route 元工具包会根据意图推荐最合适的工具包/流水线（如果没有匹配项，则发出结构化的能力缺口警告），并通过 helmdeck://routing-guide 和 helmdeck://my-defaults MCP 资源展示按调用方学习到的默认设置，同时提供路由记忆管理界面。
• 记忆写入接口 + OpenClaw 桥接（ADR 048）——helmdeck.memory_store 用于持久保存用户事实（可通过 helmdeck://my-memory 读取），可选的嵌入侧车为 OpenClaw 的 memory_search 提供支持，而 QMD 语料库桥接则向 OpenClaw 暴露 helmdeck 记忆。
• 意图分解（ADR 049）——helmdeck.plan 会将包含多个操作的提示词转换为有序、感知流水线的步骤计划，并生成 rewritten_prompt。
• LLM 上下文管理器（ADR 050）——internal/llmcontext 会压缩包含大量目录内容的提示词，以适应小模型的上下文预算（按模型分级的预算、级联选择 + 词汇排序、可选的两轮筛选），并通过 helmdeck://context-budgets 和 helmdeck://my-plans 对外提供。

控制平面二进制文件内置 57 个能力工具包（未配置 AI 网关时可用 47 个），此外还包括 21 条内置流水线、社区工具包市场（helmdeck pack install <name>）以及由运维人员提供的 cmd.* 子进程工具包。此前的重点功能仍然保留：端到端内容串联（image.generate 会自动将结果传给 podcast/slides/blog 封面）、helmdeck://image-models MCP 资源、图像模式安装（./scripts/install.sh --image-mode）以及工具包测试运行器界面。Helmdeck 已发布到 官方 MCP 注册表，注册名为 io.github.tosin2013/helmdeck，可在支持注册表的客户端中一键安装。第 1–6.5 阶段已完成；当前里程碑为 v1.0 — Kubernetes 与正式发布（第 7 阶段），待办事项已整理为带有 good first issue 和 help wanted 标签的 GitHub issue。

• docs/adrs/ 中的 49 份 ADR——每项架构决策均附有 PRD 交叉引用
• docs/TASKS.md 中的任务拆分——8 个阶段约 85 项任务，并标注关键路径
• docs/MILESTONES.md 中的 GitHub 里程碑——可直接使用的 issue 检查清单，附有当前发布状态
• docs/PACKS.md 中的工具包参考——每个已发布工具包的输入/输出约定

快速开始

git clone https://github.com/tosin2013/helmdeck
cd helmdeck
./scripts/install.sh

就是这样。脚本会运行预检（docker、node ≥20、go ≥1.26、make、openssl、curl），并根据平台提供安装提示；将新生成的密钥写入 deploy/compose/.env.local（chmod 600）；构建管理界面资源包、Go 二进制文件和浏览器侧车镜像；启动 Compose 栈；最后输出 URL 和新生成的管理员密码。

✓ helmdeck is up

  URL:       http://localhost:3000
  Username:  admin
  Password:  <generated; printed once — save it now>

实用选项：

• ./scripts/install.sh --reset — 停止并移除服务、重新生成密钥并重新安装（生成新的管理员密码）
• ./scripts/install.sh --no-build — 跳过构建步骤，仅启动服务栈
• ./scripts/install.sh --help — 查看完整选项参考

也可以通过 make 执行：make install。

连接客户端

运行中的堆栈只是平台——真正的价值在于由 Agent 调用的套件。将受支持的 MCP 客户端连接到全新安装：

客户端	状态	设置指南
OpenClaw	✅ 已完成端到端验证	docs/integrations/openclaw.md
Claude Code	🟡 已编写文档	docs/integrations/claude-code.md
Claude Desktop	🟡 已编写文档	docs/integrations/claude-desktop.md
Gemini CLI	🟡 已编写文档	docs/integrations/gemini-cli.md
Hermes Agent	🟡 已编写文档	docs/integrations/hermes-agent.md

连接客户端后，请按照 pack-demo-playbook.md 操作——其中包含 20 多条可直接复制粘贴的提示词，可用于测试每个套件。各套件参考文档介绍了每个套件的契约、错误代码和串联工作流。

高级：手动设置

如果你希望自己逐步操作，而不是运行安装脚本：

# 1. Build the Management UI bundle (needs Node 20+)
make web-deps && make web-build

# 2. Build the control-plane binary with the UI embedded
make build

# 3. Run the control plane with admin credentials
HELMDECK_JWT_SECRET=$(openssl rand -hex 32) \
HELMDECK_VAULT_KEY=$(openssl rand -hex 32) \
HELMDECK_ADMIN_PASSWORD=changeme \
./bin/control-plane

或者直接使用 Compose 堆栈（控制平面 + Garage 对象存储 + 捆绑的初始化程序）：

cp deploy/compose/.env.example deploy/compose/.env.local
# …edit deploy/compose/.env.local and fill in real secrets…
docker compose -f deploy/compose/compose.yaml --env-file deploy/compose/.env.local up -d

登录管理 UI

登录端点接受通过控制平面进程的 HELMDECK_ADMIN_PASSWORD 环境变量设置的静态管理员密码。 适用于开发环境／单节点 Compose 部署层级；生产部署的 OIDC SSO 将在后续阶段推出。

设置	默认值	覆盖方式
用户名	admin	HELMDECK_ADMIN_USERNAME 环境变量
密码	（无 — UI 登录已禁用）	HELMDECK_ADMIN_PASSWORD 环境变量（必需）
会话时长	12 小时	在 internal/api/auth_login.go 中硬编码

**更改密码：**停止控制平面，将 HELMDECK_ADMIN_PASSWORD 设置为新值，然后重启。目前 UI 中没有“更改密码”流程——密码由运行控制平面的编排工具（Compose、systemd、Kubernetes Secret 等）在带外管理。

如果未设置 HELMDECK_ADMIN_PASSWORD，登录端点会返回 503 login_disabled。控制平面仍会运行，API 也仍然可用——运维人员可以直接通过 CLI 创建 JWT：

./bin/control-plane -mint-token=alice -mint-token-scopes=admin -mint-token-ttl=12h

生成的令牌可以粘贴到任何支持 Authorization: Bearer <token> 的工具中。

**生产环境说明：**静态密码路径使用恒定时间比较，因此能够抵御时序攻击，但它仍然是一个必须手动轮换的共享密钥。对于有多名运维人员的生产部署，通过现有身份提供商使用 OIDC SSO 才是正确选择——请参阅 Phase 6 后续路线图。

架构概览

• Sidecar 模式——浏览器在独立容器中运行，不会嵌入 Agent（ADR 001）
• Golang 控制平面——单个静态二进制文件、distroless 镜像，并内嵌 React UI（ADR 002）
• 能力套件——主要产品界面；用户可通过 Go 或 WASM 编写（ADR 003、012、024）
• 兼容 OpenAI 的 AI 网关——支持 Anthropic、Gemini、OpenAI、Ollama、Deepseek，提供加密密钥和故障转移路由（ADR 005）
• MCP 服务注册表——支持 stdio/SSE/WebSocket 传输；内置 MCP 服务由套件目录自动生成（ADR 006）
• 凭证保险库——使用 AES-256-GCM 和占位令牌注入；Agent 永远不会看到机密信息（ADR 007）
• 双层部署——Docker Compose 用于开发／单节点部署，Helm chart 用于 Kubernetes 生产环境（ADR 009、010、011）
• 一等 MCP 客户端支持——Claude Code、Claude Desktop、OpenClaw、Gemini CLI 均通过单个共享的 helmdeck-mcp 桥接二进制文件接入（ADR 025、030）
• 捆绑的对象存储——Compose 堆栈内置 Garage，作为默认制品后端；生产环境可插接任意兼容 S3 的端点（AWS S3、R2、B2、SeaweedFS）（ADR 031）

内置能力包

开箱即用，包含 57 个能力包（未配置 AI 网关时为 47 个）。每个能力包都将多步工作流封装为一次带类型的 JSON-Schema 调用，让能力较弱的开放权重模型也能像前沿模型一样可靠地驱动它们。每个能力包的完整输入／输出契约见 docs/PACKS.md。 重点如下：

能力包	封装的内容
浏览器与 Web
browser.screenshot_url	会话生命周期、导航、等待渲染、清理
browser.interact	确定性的多步 CDP（navigate、click、type、scroll、screenshot、assert_text）——无需 LLM
web.scrape / web.scrape_spa	基于 Firecrawl 的 Markdown 抓取，或由架构驱动的 SPA 提取
web.test	通过 Playwright MCP + LLM 循环执行自然语言浏览器测试
research.deep	多来源 Firecrawl 搜索 + 按来源抓取 + 带行内引用的 LLM 综合
content.ground	解析 Markdown 文件中的主张、查找权威来源，并在原处插入真实的 [link](url) 引用
文档与视觉
slides.render	Marp + Chromium + 格式标志
slides.narrate	配音 MP4 视频（每张幻灯片使用 ElevenLabs TTS）+ YouTube 互动元数据 + 附属 SRT 字幕 + 结构化 validation 字段（默认启用的后置步骤）
av.validate	结构化 AV 产物验证（faststart、固定编码格式、数据包连续性、RMS 扫描、LUFS、时长一致性、SRT 格式）——默认作为 slides.narrate/podcast.generate 的后置步骤启用；也可独立用于临时检查
doc.parse	Docling 布局感知解析——PDF 表格、多格式支持、OCR 回退
doc.ocr	简单图像的 Tesseract 回退
desktop.run_app_and_screenshot	Xvfb + xdotool + scrot + 窗口聚焦
vision.click_anywhere	原生计算机使用路由（Anthropic/OpenAI/Gemini 架构），并为 Ollama/Deepseek 提供 JSON 提示词回退
vision.extract_visible_text / vision.fill_form_by_label	截图 → 视觉模型 → 操作循环
代码编辑循环
repo.fetch / repo.push	从保险库选择 SSH 密钥、使用 known_hosts、退出时销毁密钥；返回的信封包含 tree/readme/entrypoints/signals，让 Agent 能在第一轮就掌握方向
repo.map	Aider 风格的结构化符号映射，并受令牌预算限制
fs.read / fs.write / fs.patch / fs.list / fs.delete	在克隆目录中进行路径安全的文件操作
cmd.run	在克隆目录路径中运行任意命令
git.commit / git.diff / git.log	暂存、提交并审查归属为 helmdeck-agent 的变更
GitHub
github.create_issue / github.list_issues / github.list_prs / github.post_comment / github.create_release / github.search	PAT 存储在保险库中，Agent 永远无法查看
语言侧车
python.run	Python 侧车镜像中的 CPython 3 + pytest + ruff + mypy
node.run	Node 侧车镜像中的 Node 20 LTS + npm + pnpm + yarn + tsc
HTTP 与凭据
http.fetch	使用占位符令牌进行出口访问：在 URL／标头／请求体中替换 ${vault:NAME}

请参阅 ADR 014–036，了解各能力包的契约；添加新的语言侧车（Rust、Go、Ruby 等）的操作手册见 docs/SIDECAR-LANGUAGES.md。 CONTRIBUTING.md 中的贡献指南介绍了如何编写自己的能力包——目前最有用的贡献是 SaaS API 封装器（Slack、Linear、Stripe、Notion 等）。

许可证

本项目依据 Apache License, Version 2.0 授权。请参阅 NOTICE，了解随附项目及依赖项目的归属信息；贡献指南和 SPDX 标头约定见 CONTRIBUTING.md。

提交拉取请求即表示你同意依据相同条款授权你的贡献（Apache 2.0 第 5 节涵盖贡献授权——无需另行签署 CLA）。

作者

Tosin Akinosho (@tosin2013)