插件实验室

homelab MCP生态系统的标准插件开发工具包。包含用于构建、审查、对齐、工具、部署和管道homelab MCP插件的代理、技能、命令、模板、钩子和参考文档。

概述

plugin-lab 是用于在整个homelab中构建和实施插件质量的开发工作区。它不是运行时服务器。它也是规范插件形状的工作示例，因此此仓库中的每个表面都展示了格式良好的插件的外观。

它运送：

插件开发每个阶段的专业代理
编排这些代理的slash命令
定义每个代理在行动前阅读的操作程序的技能
Python、TypeScript和Rust插件的规范模板
用于Claude和Codex环境的钩子脚本
将此仓库安装为Claude Code插件的插件清单
解释完整脚手架合同的参考文件

技能

技能是代理人在行动前阅读的操作程序。每种技能都存在于 skills//SKILL.md 并且有一个 references/ 带有辅助材料的子目录。

技能	击杀命令	描述
`scaffold-lab-plugin`	`/create-lab-plugin`	指导从输入到具体脚手架计划的新MCP插件的创建
`review-lab-plugin`	`/review-lab-plugin`	根据规范合同指导对现有插件的规范审计
`align-lab-plugin`	`/align-lab-plugin`	将审查结果转化为实施变更的指南
`tool-lab-plugin`	`/tool-lab-plugin`	使用动作+子动作模式指导MCP工具的设计和实现
`deploy-lab-plugin`	`/deploy-lab-plugin`	指导容器化：Dockerfile、入口点、Compose、健康端点
`pipeline-lab-plugin`	`/pipeline-lab-plugin`	指南CI/CD：CI.yaml、publish-image.yaml、release-on-main.yaml、预提交钩子、Justfile目标
`lab-research-specialist`	`/research-lab-plugin`	指导MCP、SDK、运行时和协议更改的主要源代码研究
`setup`	`/setup-homelab`	指导交互式凭证设置 `~/.claude-homelab/.env`
`docs`	--	从Claude和Codex代理/技能文档镜像的参考技能文档

每种技能指导你完成什么

脚手架实验室插件 --收集插件名称、语言、描述和文档链接。在编写任何文件之前指导研究。制定一份书面脚手架计划，涵盖工具合同、清单和运输假设。只有在计划连贯一致后才能付诸实施。

审查实验室插件 --读取规范规范规范曲面并将其与目标插件进行比较。将每个偏差标记为发现，将未记录的偏差与合理的记录偏差区分开来，并编写一份持久的报告 docs/reports/plugin-reviews/.

align-lab插件 --从审查报告开始，如果不存在，则执行快速结构审计。在十个界面（清单、Docker、CI、测试、文档、技能、命令、代理、钩子和版本同步）上生成一个优先级对齐计划。以可预测的顺序实施更改，并将摘要写入 docs/reports/plugin-alignments/.

工具实验室插件 --收集资源域的操作集。设计一个动作+子动作合同。生成调度表、处理程序存根和 *_help 配套工具。审查现有的模式漂移工具。

部署实验室插件 --收集端口、环境变量和卷要求。生成一个规范的多阶段Dockerfile，一个符合 entrypoint.sh 通过env-var验证 docker-compose.yaml 通过健康检查，以及 .dockerignore确认或终止 /health 终点。

管道实验室插件 --生成所有四个规范工作流文件： ci.yaml （皮棉→ 类型检查→ 测试门）， publish-image.yaml （图像构建和GHCR推送，采用全标签策略）， release-on-main.yaml （清单版本→ 标签检查→ GitHub发布）和预提交钩子配置。同步Justfile目标以匹配CI步骤。

实验室研究专家 --收集MCP协议、Claude Code插件格式、Codex插件格式、语言SDK模式和相邻运行时指南的当前主要源代码文档。明确标记推理，并写出其他代理可以使用的研究成果。

设置 --检查是否 ~/.claude-homelab/.env 存在。如果缺少，则从模板创建它。交互式地浏览服务凭据组，并在继续之前验证每个条目。

代理

每个代理都有一个YAML前体块，用于控制何时触发以及可以使用哪些工具。特工在行动前会阅读相应的技能。

代理	颜色	技能	由
`ster-the-scaffolder`	蓝色	`scaffold-lab-plugin`	`/create-lab-plugin`
`roddy-reviewer`	红色	`review-lab-plugin`	`/review-lab-plugin`, `ally-the-aligner`
`ally-the-aligner`	绿色	`align-lab-plugin`	`/align-lab-plugin`
`tilly-the-toolsmith`	黄色	`tool-lab-plugin`	`/tool-lab-plugin`
`dex-the-deployer`	绿色	`deploy-lab-plugin`	`/deploy-lab-plugin`
`petra-the-pipeliner`	青色	`pipeline-lab-plugin`	`/pipeline-lab-plugin`
`rex-the-researcher`	洋红色	`lab-research-specialist`	`/research-lab-plugin`，任何需要当前状态研究的代理

代理详情

脚手架工人 --脚手架编排器。收集输入，检查提供的文档和仓库，在堆栈可能发生变化时将并行研究委托给研究人员，将结果综合到具体的脚手架计划中，并产生第一个实施步骤。用途 ~/workspace/plugin-templates/ 共享资产和 ~/workspace/plugin-templates// 针对特定语言的资产。

罗迪评论家 --规范审查代理。检查所有规范曲面，用精确的文件引用标记每一个有意义的错位，将未记录的偏移与合理的偏差分开，并将报告写入 docs/reports/plugin-reviews/.md.

盟友对准器 --校准和修复剂。使用审核报告，如果不存在审核报告，则发送审核报告。按优先级顺序在十个曲面上更改计划（清单第一，文档最后）。保留合理的偏差。将对齐摘要写入 docs/reports/plugin-alignments/.md.

工具匠蒂利 --MCP工具设计代理。设计动作+子动作契约（每个资源域一个工具，子动作是动词）。生成处理程序存根、调度表和所需的 *_help 配套工具。可以将平面工具列表重构为规范的分派形状。

dex部署人员 --容器化和部署代理。生成多阶段的Dockerfiles、带有env-var验证的入口点、带有健康检查的Compose文件，以及 .dockerignore。强制执行没有秘密进入图像且没有硬编码配置的规则。通过图像标签固定处理回滚。

管道工人佩特拉 --CI/CD管道代理。拥有所有四个工作流文件以及预提交钩子配置和Justfile目标。强制执行 just test CI测试是彼此的镜像。发布工作流强制执行版本规则：每次向main推送都必须碰撞清单版本或已经有发布标签。

雷克斯研究员 --现任国家研究专家。回答主要来源的问题（官方文档、协议规范、SDK存储库、发行说明）。区分已证实的事实和推论。标记源之间的冲突。将研究成果写入 docs/research/-.md 供其他代理消费。

命令

命令是调用匹配技能并生成匹配代理的斜线命令。

命令	代理	参数
`/create-lab-plugin`	`ster-the-scaffolder`	`
[short description]`
`/review-lab-plugin`	`roddy-reviewer` （×3平行）	`
`
`/align-lab-plugin`	`ally-the-aligner`	`
`
`/tool-lab-plugin`	`tilly-the-toolsmith`	`
[create\	review\	update] [tool-name]`
`/deploy-lab-plugin`	`dex-the-deployer`	`
[create\	review\	update]`
`/pipeline-lab-plugin`	`petra-the-pipeliner`	`
[create\	review\	update]`
`/research-lab-plugin`	`rex-the-researcher`	``
`/setup-homelab`	（仅限技能）	`[--force]`

命令详细信息

/创建实验室插件 --解析插件名称、描述和可选语言。询问任何缺失的输入。援引 scaffold-lab-plugin 技能，孕育出脚手架工人。Ster最多派遣三名平行的研究人员进行当前状态的研究，将结果综合到一份书面的支架计划中，并返回确切的第一个实施行动。

/审查实验室插件 --在生成之前读取插件树和基线文件（README.md、CLAUDE.md、清单、Dockerfile等）。援引 review-lab-plugin 技能，产生了三个平行的roddy评论员代理。将三个通道合并为一个报告 docs/reports/plugin-reviews/.md.

/align-lab插件 --调用 align-lab-plugin 技能，培养盟友。如果审查报告存在于 docs/reports/plugin-reviews/，艾莉读了一遍。否则，艾莉会派牛仔评论员、研究人员雷克斯和脚手架工并行取证，然后进行比对。将摘要写入 docs/reports/plugin-alignments/.md.

/工具实验室插件 --调用 tool-lab-plugin 技能，造就了工具匠蒂利。模式： create 收集操作并生成完整的合同； review 审核所有工具的合规性； update 补丁模式、调度和处理程序。如果包装服务API可能已更改，Tilly将重新调度搜索器。

/部署实验室插件 --调用 deploy-lab-plugin 技能，培养部署者。模式： create 从头开始生成完整的容器配置； review 漂移审计； update 做出有针对性的改变。Dex证实 /health 端点存在或将其截断。

/管道实验室插件 --调用 pipeline-lab-plugin 技艺，孕育出流水线工人佩特拉。模式： create 生成所有四个工作流文件以及Justfile； review 根据规范形状审核每个文件； update 进行有针对性的更改并保持Justfile同步。输出包括所需的机密列表。

/研究实验室插件 --调用 lab-research-specialist 技能，孕育出研究者雷克斯。Rex将广泛的主题分为平行的研究轨道（MCP协议、Claude插件文档、Codex插件文档、语言SDK更新、Docker/auth指南）。将结果写入 docs/research/-.md.

/设置家庭实验室 --调用 setup 技能。副本 .env.example 到 ~/.claude-homelab/.env 如果不存在（或用 --force)，套 chmod 600，安装 load-env.sh，并提示用户填写服务凭证。

技能→ 代理→ 命令映射

技能	代理	命令	生产
`scaffold-lab-plugin`	`ster-the-scaffolder`	`/create-lab-plugin`	脚手架计划+实施步骤
`review-lab-plugin`	`roddy-reviewer`	`/review-lab-plugin`	`docs/reports/plugin-reviews/.md`
`align-lab-plugin`	`ally-the-aligner`	`/align-lab-plugin`	`docs/reports/plugin-alignments/.md`
`tool-lab-plugin`	`tilly-the-toolsmith`	`/tool-lab-plugin`	工具合同+处理人存根
`deploy-lab-plugin`	`dex-the-deployer`	`/deploy-lab-plugin`	Dockerfile、entrypoint.sh、docker-compose.yaml
`pipeline-lab-plugin`	`petra-the-pipeliner`	`/pipeline-lab-plugin`	四个工作流文件+Justfile目标
`lab-research-specialist`	`rex-the-researcher`	`/research-lab-plugin`	`docs/research/-.md`
`setup`	—	`/setup-homelab`	`~/.claude-homelab/.env`

插件生命周期

一个插件会经历六个阶段。每个阶段都有专门的技能、代理和命令。

scaffold → review → align → tool → deploy → pipeline

脚手架 --从具体计划中创建仓库、清单、传输配置和初始工具存根。
审查 --根据规范审核每个规范表面。制作调查结果报告。
对齐 --落实审查报告中的每一项发现。保留合理的偏差。
工具 --使用动作+子动作模式设计和实现MCP工具契约。
部署 --使用多级Dockerfile、一致性入口点和Compose堆栈进行容器化。
管道 --添加CI/CD：测试门、映像发布、自动发布和预提交挂钩。

阶段不是严格按顺序进行的。跑 /review-lab-plugin 在任何时候对任何现有插件。跑 /align-lab-plugin 在任何审查之后。跑 /research-lab-plugin 在脚手架之前，当目标SDK不熟悉或可能已经更改时。

模板

模板是生成插件仓库的规范脚手架源。脚手架脚本位于 /home/jmagar/claude-homelab/scripts/scaffold-plugin.sh 从这些目录中读取。

templates/
  py/    Python/FastMCP template
  ts/    TypeScript/MCP SDK template
  rs/    Rust/rmcp template

模板选择指南

语言	运行时	何时选择
python`py/`)	FastMCP	服务有Python SDK；团队熟悉Python；现有的homelab插件是Python
TypeScript(`ts/`)	Express+MCP SDK	服务有一个JS/TS SDK；插件主要是异步HTTP调用；JSON密集型API
生锈(`rs/`)	rmcp	插件对性能至关重要；二进制大小很重要；Rust SDK是维护最好的选择

所有三个模板都提供相同的规范形状：

包裹清单(pyproject.toml / package.json / Cargo.toml)
my_plugin_mcp/ 运行时模块目录
Claude和Codex插件清单
钩子和钩子脚本
多级Dockerfile， docker-compose.yaml, entrypoint.sh
Justfile
CI工作流
预提交或左钩配置
.gitignore, .dockerignore, .env.example
面向AI的文件： skills/, agents/, commands/, CLAUDE.md
试验脚手架： tests/test_live.sh

每个模板都是自包含的。切勿在脚手架时添加跨模板依赖关系。如果文件在脚手架过程中被使用，它必须位于模板目录中。每当模板路径更改时，更新脚手架脚本。

传输默认值

所有模板默认为双传输（HTTP+stdio）。HTTP是生产路径；stdio是本地dev和Codex CLI路径。运输由 _MCP_TRANSPORT 有人是。

刀具形状

所有模板默认为操作+子操作模式：每个资源域一个主要工具加一个 *_help 配套工具。在没有充分理由的情况下，不要将多个操作拆分为单独的顶级工具。

存储库布局

agents/                 Lab workflow agents (one .md file per agent)
commands/               Slash commands (one .md file per command)
skills/                 Skill operating procedures
  align-lab-plugin/     SKILL.md + references/
  deploy-lab-plugin/    SKILL.md + references/
  lab-research-specialist/  SKILL.md + references/
  pipeline-lab-plugin/  SKILL.md + references/
  review-lab-plugin/    SKILL.md + references/
  scaffold-lab-plugin/  SKILL.md + references/
  setup/                SKILL.md + references/ + scripts/
  tool-lab-plugin/      SKILL.md + references/
  docs/                 Mirrored Claude and Codex skill/agent documentation
templates/              Canonical scaffold source root
  py/                   Python plugin template (self-contained)
  ts/                   TypeScript plugin template (self-contained)
  rs/                   Rust plugin template (self-contained)
hooks/                  Hook scripts shared across environments
  docs/                 Hook documentation
  scripts/              sync-env.sh, fix-env-perms.sh, ensure-ignore-files.sh
docs/                   Human-facing docs about plugin-lab
  plugin-setup-guide.md Full canonical spec reference
  scaffold-template-mapping.md  Root-to-template mapping decisions
  plans/                Planning artifacts
  reports/              Review and alignment outputs
  research/             Research artifacts from rex-the-researcher
  sessions/             Session notes
  superpowers/          Superpowers skill references
bin/                    Plugin execution helpers added to PATH
output-styles/          Output formatting references
scripts/                Repo maintenance scripts
.claude-plugin/         Claude plugin manifest (plugin.json)
.codex-plugin/          Codex plugin manifest (plugin.json)
gemini-extension.json   Gemini extension manifest
CLAUDE.md               Repo working instructions and single-source-of-truth rules
CHANGELOG.md            Release history

安装

市场

/plugin marketplace add jmagar/claude-homelab
/plugin install plugin-lab @jmagar-claude-homelab

本地安装

# From the repo root, Claude Code will auto-discover the .claude-plugin/plugin.json
cd ~/workspace/plugin-lab

这 .claude-plugin/plugin.json Claude Code指向本地仓库。Claude Code加载插件后，技能、代理和命令立即可用。

用法

构建一个新插件

/create-lab-plugin my-service-mcp "Wraps the My Service API"

在提示时提供到服务API文档的链接。Ster将在编写任何文件之前将研究委托给Rex。

查看现有插件

/review-lab-plugin ~/workspace/my-service-mcp

三个审阅者实例并行运行并合并到一个报告中。

审阅后对齐插件

/align-lab-plugin ~/workspace/my-service-mcp

如果审查报告已存在于 docs/reports/plugin-reviews/，艾莉直接读。否则，Ally会先发送一个新的审核通行证。

添加或更新MCP工具

/tool-lab-plugin ~/workspace/my-service-mcp create applications

Tilly收集了操作集 applications 资源域，并生成动作+子动作契约。

容器化插件

/deploy-lab-plugin ~/workspace/my-service-mcp create

Dex生成Dockerfile、entrypoint.sh、docker-compose.yaml和.dockerinore。存根 /health 如果缺席。

添加CI/CD

/pipeline-lab-plugin ~/workspace/my-service-mcp create

Petra生成所有四个工作流文件，预提交或左钩配置，以及Justfile目标。

脚手架搭设前的研究

/research-lab-plugin "TypeScript MCP server current patterns"

Rex查询主要来源并编写一个研究工件，供脚手架工在下一次脚手架运行时使用。

配置家庭实验室凭据

/setup-homelab

浏览凭据向导 ~/.claude-homelab/.env.

CLAUDE.md规则（摘要）

repo CLAUDE.md执行两条规则，适用于在此repo中工作的每个人：

唯一的真相来源。 每个文件只存在于一个位置。共享插件合约文件位于repo根目录。特定语言的文件位于一个语言目录下。从不将共享文件复制到 py/, ts/，或 rs/.

没有重复。 语言目录下没有重复的共享树。除非脚手架占用了占位符路径，否则没有占位符路径。根文档描述的是此仓库，而不是语言模板。按语言 README.md 和 CLAUDE.md 仅描述该语言层。

如果移动或重命名模板文件，请更新脚手架脚本和中的任何组合说明 claude-homelab 在同样的变化中。

版本碰撞。 每次功能分支推送都必须在所有包含版本的文件中更新版本(Cargo.toml, package.json, pyproject.toml, .claude-plugin/plugin.json, .codex-plugin/plugin.json, gemini-extension.json, README.md, CHANGELOG.md).所有文件必须共享相同的版本字符串。

验证

修改模板或文档后：

rtk rg -n "^#|^##" README.md docs/plugin-setup-guide.md
rtk rg --files agents commands skills templates/py templates/ts templates/rs hooks

构建新插件后，运行 /review-lab-plugin 在提交之前，先在输出上捕捉漂移。

许可证

麻省理工学院

插件	类别	描述
家庭实验室核心	核心	家庭实验室管理的核心代理、命令、技能和设置/健康工作流程。
监督者mcp	media	通过Overseer搜索电影和电视节目、提交请求和监视失败的请求。
unraid mcp	基础设施	查询、监视和管理Unraid服务器：Docker、VM、阵列、奇偶校验和实时遥测。
unifi-mcp	基础设施	监控和管理UniFi设备、客户端、防火墙规则和网络健康状况。
获取mcp	实用程序	通过自托管的Gotify服务器发送和管理推送通知。
swag mcp	基础设施	创建、编辑和管理SWAG nginx反向代理配置。
突触mcp	基础设施	跨家庭实验室主机的Docker管理（Flux）和SSH远程操作（Scout）。
神秘的mcp	基础设施	通过Arcane管理Docker环境、容器、映像、卷、网络和GitOps。
系统日志mcp	基础设施	通过SQLite FTS5从所有家庭实验室主机接收、索引和搜索系统日志流。

Plugin Lab

快速接入

详细介绍