Neckbeard：为编码 agent 提供 DevOps 基础设施编排的开源插件

络腮胡帮你搞定基础设施，你不用操心。

一个为你的编码代理准备的插件，可将应用转换为可评审的云基础设施并给出月度成本估算。支持 AWS、GCP 或 Azure；GitHub Actions 或 GitLab CI；无服务器容器或 Kubernetes —— 全部从一个经过测试的 OpenTofu 模块打包目录中渲染。代理会读取你的应用并进行说明；规划、渲染和验证都是确定性代码。代理绝不凭空编造基础设施。

灵感来自 ponytail。

安装

Claude Code，分两步提示：

/plugin marketplace add bealesh/neckbeard

/plugin install neckbeard@neckbeard

然后，在你的应用仓库中：/neckbeard:analyze。你的第一个 /neckbeard: 命令会安装插件驱动的小型 neckbeard CLI（sha256 校验过的发布二进制，或在已安装 Go 时使用 go install）—— 无需再做任何配置。成本估算和静态校验使用你可能已有的工具（Infracost、OpenTofu、Checkov）；/neckbeard:doctor 会告诉你哪些工具缺失，以及每个工具能解锁哪些功能。

Codex、Cursor 或任何 SKILL.md 兼容的代理：参见 INSTALL.md。

工作流程

you:    /neckbeard:analyze
agent:  reads your repo → evidence-backed profile → asks what code can't tell it
you:    answer the questions, pick a cloud and a tier
you:    /neckbeard:estimate
agent:  plans against the catalog → "$77/mo expected — here's the table, and
        here's what Infracost can't price"
you:    /neckbeard:sync
agent:  scaffold → validate → "V0 PASSED; V1/V2 NOT EXERCISED; next step is
        docs/bootstrap.md"
you:    review the files like any PR; follow the runbook per environment

命令

命令	功能说明
`/neckbeard:analyze`	将仓库读取为有证据支撑的 `app-profile.yaml`（事实附带 file:line，推断附带置信度，假设会被显式标出），提出未决问题，建议 `neckbeard.yaml`。
`/neckbeard:estimate [comparison]`	基于模块目录进行规划，并显示月度成本表 —— 每个环境的低/预期/高估值、使用假设以及所有未定价资源 —— 在任何资源创建之前完成。`serverless vs kubernetes` 或 `solo vs smallteam` 会同时运行这两步。
`/neckbeard:sync`	循环流程：plan → estimate → scaffold → validate，在所有权契约下进行（你的编辑永远不会被静默覆盖）。最终以 PASSED / FAILED / NOT EXERCISED 结束。
`/neckbeard:doctor [plan\|estimate\|validate\|all]`	若 CLI 缺失则进行安装；报告已具备的前置条件以及各自能解锁的功能。
`/neckbeard:help`	快速参考。

为何需要它

编码代理擅长应用代码，却拙于自由发挥式的基础设施搭建。失败模式总是一样：看起来合理的 HCL，实际却有细微缺陷，默认不安全，且无法估算。neckbeard 反转了这一角色分工：

由人类维护最佳实践路径 — 版本化的 OpenTofu 模块、流水线模板、GitOps 布局，按云厂商划分，每次变更都在 CI 中测试。
代理负责分析、参数化与解释。 它读取你的应用，弄清它需要什么，并将其映射到目录输入 —— 每一条主张都附带证据。
两者之间的一切都是确定性的。 相同的输入，相同的字节：规划器生成经过哈希校验的 blueprint.yaml 锁文件，渲染器是其纯函数，且重新生成时绝不会静默覆盖你的修改。

目录无法表达的需求被转化为具名发现项（“redis 超出工作负载契约”），而不是硬塞进最近的模块。

别人不会告诉你的部分：成本

同一个参考应用（HTTP 服务 + worker + 定时任务 + Postgres），最小规格，全部三种环境，通过 Infracost 获取实时价格：

	Cloud Run	Container Apps	ECS Fargate	EKS	GKE (regional)	AKS
每月	$77	~$98*	$250	$396	$754	~$801*

* Infracost 目前仍无法为 Container Apps 计算定价 —— 它没有让一个偏低的数字蒙混过关，而是在报告中逐一列出每个未定价的资源。这就是我们的风格：空闲时的基线成本、可编辑的显式使用假设、低/预期/高三种场景，以及溯源页脚。它同样会为你的决策定价：这张表正是 neckbeard 告诉独立开发者“你现在还不必上 Kubernetes”的原因 —— 凭据齐全。

诚实即架构

基础设施工具总是暗示得比已验证的更多。neckbeard 以三种结论来汇报，而第三种才是关键：

V0   PASSED         tofu validate [prd]
V0   PASSED         checkov policy [prd]        ← every skip carries a written reason
V0   PASSED         kubeconform (clusters/)
V1   NOT EXERCISED  authenticated plan          requires cloud credentials
V2   NOT EXERCISED  deployment verification     requires cloud credentials

静态校验从不声称可部署。V0/V1/V2 是不同的层级,每个都按已演练或未演练进行报告。
生成的 .checkov.yaml 中每一个 Checkov 跳过项都会说明原因。没有原因的跳过就是对你安全态势的欺骗。
当真实运行出现故障时,失败会公开成为发现项,随后归类为修复方案。我们的首次真实部署产生了十个;其中五个当天就得到了修复。
降级路径会说明原因(Azure + GitLab 合并请求计划无法联邦 —— 流水线会直接告知,而不是神秘地失败)。

你将得到什么

三个相互隔离的环境(dev/stg/prd),各自拥有独立状态,通过分层预设覆盖明确维度进行规格化:流量、可用性、RPO/RTO、运行容量。每个值在目录的测试包络范围内都可见且可覆盖;超出该范围的值会被标记,而不会被认可。
每个云提供两种运行时:无服务器容器(Cloud Run / ECS Fargate / Container Apps)或 Kubernetes(EKS / GKE / AKS),并附带 Flux 清单。
为 GitHub Actions 或 GitLab CI 提供 CI/CD,源自同一个模型:test → build → scan(trivy 会阻断 HIGH/CRITICAL)→ push;在 PR 上以只读身份进行基础设施计划,在 main 上以写入身份应用,生产环境受环境保护门控。零静态云密钥 —— 全程采用 OIDC 联邦,并通过一项测试强制执行:若渲染后的流水线中提及 AWS_SECRET_ACCESS_KEY 则测试失败。
安全态势以显式控制项呈现:默认私有的网络、保存由运维人员填写名称的密钥管理器(数值绝不接触 neckbeard、其状态或你的 git 历史)、限定范围的 CI 身份,以及分层启用时提供的托管 WAF 规则。
一份引导运行手册(docs/bootstrap.md),指导持有提权凭据的人员按环境完成 state backend → OIDC 信任 → CI 身份配置。validate 之后的所有操作都刻意采用人在环路的方式。

支持的工作负载为一个镜像、最多 10 个 HTTP/worker/cron 进程、Postgres、对象存储、密钥,部署到现有账户、项目或订阅中。其他任何情况都会作为明确的 unsupported 发现项。

状态:预 alpha,且表述精确

已证明的内容,及其证明方式:

声明	证据
analyze → plan → estimate → scaffold → validate,覆盖全部 12 条 cloud × VCS × runtime 路径	静态矩阵在每个 PR 的 CI 中运行;三个无关的 fixture 应用端到端完成接入
真实部署 → 更新 → 回滚,无服务器	在 AWS/GitHub 与 Azure/GitHub 上通过,并进行真实的数据库校验(证据)
在 GCP、GitLab 通道、Kubernetes、晋升、恢复演练上进行真实部署	尚未。已实现,尚未演练

该插件当前的产品是 onboarding 那一半:可审查的基础设施、流水线、成本估算,以及一份可交付给人员的引导运行手册。部署生命周期(neckbeard release …,已在 skill 中记录)尚处于实验阶段,在发布计划中按 gate 逐项追踪。请勿将静态校验视为部署证明。着陆区(组织结构、护栏 —— DESIGN.md 中的路径 F)仅完成设计,尚未构建。

整体如何衔接

            you / your agent                      deterministic core
        ┌──────────────────────┐            ┌───────────────────────────┐
repo ──▶│ analyze: facts w/    │  profile   │ plan: catalog @ pinned    │
        │ evidence, questions, ├───────────▶│ versions → blueprint.yaml │
        │ judgment, answers    │  config    │ (hash-verified lockfile)  │
        └──────────────────────┘            └─────────┬─────────────────┘
                                       ┌──────────────┼──────────────┐
                                       ▼              ▼              ▼
                                   estimate       scaffold        validate
                                   Infracost,     ownership       V0 static,
                                   scenarios,     contract:       V1 plan,
                                   unpriced       never silently  V2 deploy —
                                   named          overwrite       each reported

仓库根目录即该插件:skills/neckbeard/SKILL.md 是代理的操作手册,commands/ 是斜杠命令,cmd/ 下的 Go CLI 以及 catalog/ 下的模块目录构成确定性的一半。该 CLI 也可在无代理的情况下驱动一切:

go install github.com/bealesh/neckbeard/cmd/neckbeard@latest
neckbeard analyze && $EDITOR app-profile.yaml neckbeard.yaml
neckbeard plan && neckbeard estimate && neckbeard scaffold && neckbeard validate

深入了解：DESIGN.md（完整的设计方案，自始至终保持诚实） · docs/findings/（现实教会了我们什么） · CONTRIBUTING.md。

许可证

Apache-2.0 — 详见 LICENSE。