内容
# 实验室
`lab` 是 **Labby** 背后的 Rust 工作空间，Labby 是一个本地优先的控制平面，用于代理工具和家庭实验室操作。单个二进制文件 `labby` 通过 CLI、MCP 服务器、HTTP API 和 Labby 网页界面暴露相同的操作能力。
根目录 README 是公共入口点。主题文档在 [docs/](./docs/README.md) 中拥有详细的合约；当此文件与主题文档不一致时，请先修复主题文档，然后刷新此摘要。
## 目录
- [实验室的作用](#实验室的作用)
- [快速开始](#快速开始)
- [核心工作流程](#核心工作流程)
- [运行时界面](#运行时界面)
- [配置](#配置)
- [当前目录](#当前目录)
- [架构](#架构)
- [开发](#开发)
- [文档](#文档)
## 实验室的作用
Labby 以当前的网关/操作员界面为中心：
- **MCP 网关** - 连接 HTTP 和 stdio 上游 MCP 服务器，检查其工具/资源/提示，应用暴露过滤器，发布受保护的 MCP 路由，并可选地将上游目录折叠到代码模式的 `search` 和 `execute`。
- **市场和注册表** - 浏览 Claude/Codex 插件市场、官方 MCP 注册表和 ACP 代理注册表；通过显式目标感知工作流安装插件、MCP 服务器和 ACP 提供程序。
- **暂存工作空间** - 将可安装的工件镜像到 `~/.labby/stash`，编辑和版本化组件快照，预览部署差异，并将保存的工件部署回配置的目标。
- **ACP 聊天** - 运行提供程序支持的代理客户端协议会话，流式传输和持久化事件，并保持名为 `acp` 的后端服务。Labby 网页界面不再为此提供 `/chat` 界面。
- **舰队、设置、日志和部署** - 以控制器或节点的身份运行 `labby serve`，注册设备，搜索本地/舰队日志，审核设置健康状况，并将本地发布二进制部署到 SSH 目标。
- **生成的发现** - 在 [docs/generated](./docs/generated/README.md) 下发布代码拥有的服务、操作、环境、API 路由、OpenAPI、MCP 帮助、CLI 帮助和功能矩阵工件。
## 快速开始
### 安装发行版
Linux/macOS:
```bash
curl -fsSL https://raw.githubusercontent.com/jmagar/lab/main/scripts/install.sh | sh
labby setup
labby serve --host 127.0.0.1 --port 8765
```
MCP 客户端如果更喜欢 npm 启动器，可以通过 Node 包装器运行 Labby：
```bash
npx -y labby-mcp mcp
```
Windows PowerShell:
```powershell
irm https://raw.githubusercontent.com/jmagar/lab/main/scripts/install.ps1 | iex
labby setup
labby serve --host 127.0.0.1 --port 8765
```
安装脚本下载请求的 GitHub 发行版资产，验证其校验和，并将 `labby` 安装到用户路径中。它们 **不** 执行操作员配置或环境设置。脚本仅安装二进制文件（来自发行版或回退源构建）；所有首次运行的配置由 `labby` 通过 `labby serve` 引导和 `labby setup` 处理。
### 从源代码构建
先决条件：
- Rust 1.92 或更新版本。CI/发布目前使用 Rust 1.94.1 进行验证。
- `just` 用于仓库命令。
- `cargo-nextest` 用于主测试套件。
- `pnpm 9.15.9` 用于 Labby 网页界面。仓库在 [.mise.toml](./.mise.toml) 和 [apps/gateway-admin/package.json](./apps/gateway-admin/package.json) 中固定了此版本。
- `openssl` 如果您想手动生成承载令牌。
```bash
git clone https://github.com/jmagar/lab.git
cd lab
just install
just web-build
labby serve --host 127.0.0.1 --port 8765
```
`just install` 构建所有功能的发布二进制文件，并将其符号链接到 `~/.local/bin/labby`。
## 核心工作流程
### 启动 Labby
```bash
labby serve --host 127.0.0.1 --port 8765
labby mcp
```
`labby serve` 启动托管的 HTTP 运行时：`/v1` 产品 API、`/mcp` 可流式传输的 HTTP MCP、身份验证路由、节点运行时端点和静态 Labby 网页资产（如果有导出）。`labby mcp` 是本地 MCP 客户端的标准输入/输出入口点。
### 管理上游 MCP 网关
```bash
labby gateway add \
--name github \
--url https://example.com/mcp \
--bearer-token-env GITHUB_MCP_TOKEN \
-y
labby gateway reload
labby gateway list
```
标准输入/输出上游执行本地命令时进行测试或协调，因此网关测试和配置变更使用共享的破坏性操作确认门户。标准输入/输出生成守护进程允许已知运行时，如 `npx`、`uvx`、`docker`、`node`、`python`、`python3`、`deno`、`pipx` 和 `dnx`；在 `config.toml` 中的 `[gateway]` 中自定义它。
## 运行时界面
| 界面 | 入口点 | 备注 |
| --- | --- | --- |
| CLI | `labby <command>` | 当前命令在 [docs/generated/cli-help.md](./docs/generated/cli-help.md) 中生成。使用 `--json` 获取机器可读输出，使用 `--color auto|plain|color` 获取人类输出样式。 |
| MCP 标准输入/输出 | `labby mcp` | 本地编辑器/桌面 MCP 客户端。 |
| MCP HTTP | `labby serve` 加上 `/mcp` | 可流式传输的 HTTP MCP，带有承载令牌或 OAuth JWT 身份验证。 |
| HTTP API | `labby serve` 加上 `/v1/*` | 通用 `POST /v1/{service}` 操作调度加上专用产品路由。 |
| 网页界面 | `labby serve` 加上导出的资产 | 主路由为 `/` （概览）、`/gateways`、`/snippets`、`/usage`、`/settings`、`/docs` 和 `/design-system`。 |
## 配置
配置被故意分成几部分：
| 数据 | 位置 | 示例 |
| --- | --- | --- |
| 机密和端点值 | `~/.labby/.env` | `LABBY_MCP_HTTP_TOKEN`，`LABBY_GOOGLE_CLIENT_SECRET`，上游承载令牌环境值 |
| 首选项 | `config.toml` | 传输，CORS，身份验证模式，工作区根目录，网关生成守护进程，注册表 URL |
`config.toml` 按以下顺序查找：
1. `./config.toml`
2. `~/.labby/config.toml`
3. `~/.config/labby/config.toml`
启动时加载第一个 `config.toml`，初始化跟踪，然后加载 `~/.labby/.env` 和当前工作目录的 `.env`（如果存在）。运行时优先级为：
1. CLI 标志
2. 环境变量
3. `config.toml`
4. 内置默认值
## 当前目录
请勿在此 README 中手动维护操作、功能、环境或覆盖范围清单。该目录中生成的工件是当前分支的权威来源：
| 工件 | 用途 |
| --- | --- |
| [service-catalog.md](./docs/generated/service-catalog.md) | 注册的服务、暴露、功能、类别和界面。 |
| [action-catalog.md](./docs/generated/action-catalog.md) | 按服务划分的操作和破坏性元数据。 |
| [env-reference.md](./docs/generated/env-reference.md) | 从服务元数据生成的环境变量。 |
| [api-routes.md](./docs/generated/api-routes.md) | 挂载的 HTTP 路由。 |
| [openapi.json](./docs/generated/openapi.json) | OpenAPI 3.1 模式。 |
| [feature-matrix.md](./docs/generated/feature-matrix.md) | Cargo 功能变量。 |
| [mcp-help.md](./docs/generated/mcp-help.md) | MCP 帮助投影。 |
| [cli-help.md](./docs/generated/cli-help.md) | Clap 命令帮助快照。 |
使用以下命令刷新和验证它们：
```bash
just docs-generate
just docs-check
```
`docs-check` 验证生成的工件的新鲜度和不变量。它不是 Markdown 链接检查器、实时健康检查或入职政策审计。
## 架构
工作空间使用 Rust 2024、解析器 3 和单个工作空间版本。
| 路径 | 角色 |
| --- | --- |
| [crates/labby-apis](./crates/labby-apis) | 用于共享模型、身份验证原语、元数据、注册表客户端、ACP 类型、设置/医生/暂存/市场/设备/部署类型的纯 SDK/域 crate。 |
| [crates/labby-auth](./crates/labby-auth) | OAuth/JWT/会话中间件、路由支持和上游 OAuth 运行时。 |
| [crates/labby-runtime](./crates/labby-runtime) | 面向中立的合约和帮助程序：`ToolError`、网关配置 DTO、调度帮助程序、减少、路径安全性和安全帮助程序。 |
| [crates/labby-codemode](./crates/labby-codemode) | 面向中立的代码模式运行内核、代理、结果整形、代码段和 TypeScript 描述符生成。 |
| [crates/labby-gateway](./crates/labby-gateway) | 网关管理器、上游 MCP 代理池、代码模式主机适配器、发现/导入、虚拟服务器、保护路由和 OAuth 生命周期。 |
| [crates/labby-web](./crates/labby-web) | 嵌入式/文件系统网页资产服务，带有符号链接逃逸防御。 |
| [crates/labby](./crates/labby) | 产品二进制 crate：CLI、MCP、HTTP API、配置加载、产品调度、ACP 协调、日志、设置和输出渲染。 |
| [crates/labby-winjob](./crates/labby-winjob) | Windows Job Object 进程树支持，隔离以便主工作空间可以保持 `unsafe_code = "forbid"`。 |
| [apps/gateway-admin](./apps/gateway-admin/README.md) | Labby 网页界面，静态导出并由 `labby serve` 提供服务。 |
| [plugins](./plugins) | Claude/Codex 插件资产、技能、钩子和监视器定义。 |
| [docs](./docs/README.md) | 主题文档和生成的库存。 |
共享行为属于共享执行层。上游/域逻辑属于 `labby-apis`；可重用的网关/运行时/代码模式行为属于提取的 `labby-*` crate；产品调度属于 `crates/labby/src/dispatch`；CLI、MCP、HTTP 和网页适配器保持薄。参见 [Architecture](./docs/ARCH.md) 和 [Dispatch](./docs/dev/DISPATCH.md)。
## 开发
优先使用 `just` 别名：
```bash
just check # cargo check --workspace --all-features
just test # cargo nextest run --workspace --all-features
just test-integration # cargo nextest run --workspace --all-features --run-ignored ignored-only
just lint # skill drift + cargo wrapper smoke + clippy -D warnings + fmt check
just deny # cargo deny check
just build # cargo build --workspace --all-features
just build-release # release build, bin/labby install, ~/.local/bin symlink
labby setup host-service install --install-self -y # install current binary + start system service
labby setup host-service restart --install-self -y # reinstall current binary + restart service
labby setup host-service status --json # inspect the host Labby gateway service
just host-sync # repo dev shortcut: rebuild + install binary + restart host service
just dev-container # explicit Docker compatibility/prod-like smoke path
just dev-container-debug # explicit Docker debug binary path
just web-build # cd apps/gateway-admin && pnpm build
just web-watch # rebuild web assets when frontend files change
just run -- help # cargo run --all-features -- <args>
just chat-local # local Labby admin UI workflow with browser auth disabled
just dev-up # start the explicit Docker compatibility stack
just dev # alias for just dev-container
just dev-debug # alias for just dev-container-debug
just install # build-release + symlink ~/.local/bin/labby
just prod-run # local prod-like image smoke on port 18765
just mcp-token # rotate LABBY_MCP_HTTP_TOKEN in .env
```
权威的 Rust 验证是 all-features：
```bash
cargo check --workspace --all-features
cargo clippy --workspace --all-features -- -D warnings
cargo nextest run --workspace --all-features
cargo build --workspace --all-features
```
CI 使用相同的姿态，并使用其 CI 配置文件运行 nextest。仅在需要时或特定工具需要时使用 `cargo test` 进行本地测试。
前端更改还应运行相关的 `pnpm` 脚本，位于 `apps/gateway-admin` 下，并在导出资产时使用 `just web-build`。
### 主机网关运行时
推荐的自托管网关运行时是 Incus 系统容器，由 `scripts/incus-bootstrap.sh --version vX.Y.Z` 提供，并在盒内与 `labby setup --provision` 收敛。裸金属使用相同的提供程序和系统单元，当主机或虚拟机专用于 Labby 时。默认服务是 `/etc/systemd/system/labby.service`，以 `User=labby`、`Group=labby` 运行，`ExecStart=/usr/local/bin/labby serve`。从源代码 checkout 开始，`just host-sync` 仍然是重建和重启开发人员的快捷方式。Docker 仍然可用于类似生产的镜像烟雾测试和适配器容器工作，但它不再是推荐的代理网关运行时。
### 开发容器
Compose 堆栈是一个受信任的本地操作员环境，而不是一个强化的通用部署环境。它绑定挂载主机 Labby 状态、代理凭证/插件缓存、存储库和构建的 Web 资产；秘密从挂载的 `/home/labby/.labby/.env` 加载。镜像预安装了 ACP 适配器（`claude-agent-acp`、`codex-acp`、`gemini`），因此会话启动使用确定性的本地二进制文件，而不是重复的 `npx` 安装。当更改 Dockerfile 或适配器版本时，请重建镜像；使用 `just dev` 或 `just dev-debug` 进行普通的 Labby 二进制文件交换。
### 版本发布
版本发布准备首先是版本号和变更日志，然后是标签：
1. 提升 [Cargo.toml](./Cargo.toml) 中的工作区版本。
2. 更新 `CHANGELOG.md`（如果存在）。
3. 当相关时，重新生成文档和 Web 资产。
4. 推送 `vX.Y.Z` 标签。
发布工作流构建 Linux 和 Windows 存档，附带校验和，发布 GitHub Release，推送 GHCR 镜像，并包含生成的市场工件。
### ACP 运行时说明
Rust ACP SDK 精确地固定在 [crates/labby/Cargo.toml](./crates/labby/Cargo.toml) 中为 `agent-client-protocol = "=0.13.1"`，具有 `unstable` 功能。模型/配置发现依赖于从原始 `NewSessionResponse` 读取 `session_config_options()`，然后是 `attach_session`，而模型切换使用 `SetSessionConfigOptionRequest`。在升级 SDK 之前，请重新检查这些 API。
### 插件设置钩子
`plugins/labby` 插件提供技能、命令和 MCP 配置，而不是 `labby` 二进制文件。SessionStart 运行 `labby setup plugin-hook --no-repair`，当 `labby` 在 PATH 上时，并打印安装指针。ConfigChange 运行 `labby setup plugin-hook` 以同步设置。钩子应该保持建议：没有二进制文件捆绑，没有自动安装，也没有 Docker/systemd 引导。
## 相关服务器
- [soma](https://github.com/jmagar/soma) - 提供商支持的 MCP 服务器的 RMCP 运行时。
- [unifi-rmcp](https://github.com/jmagar/runifi) - UniFi 控制器 REST API 桥接器。
- [tailscale-rmcp](https://github.com/jmagar/rtailscale) - 设备、用户和 tailnet 操作的 Tailscale API 桥接器。
- [unraid-rmcp](https://github.com/jmagar/runraid) - 用于 NAS 和服务器管理的 Unraid GraphQL 桥接器。
- [apprise-rmcp](https://github.com/jmagar/rapprise) - 用于许多交付后端的 Apprise 通知分发桥接器。
- [gotify-rmcp](https://github.com/jmagar/rgotify) - Gotify 发送通知、消息、应用程序和客户端的推送通知桥接器。
- [arcane-rmcp](https://github.com/jmagar/rarcane) - 用于容器和相关资源的 Arcane Docker 管理桥接器。
- [yarr](https://github.com/jmagar/yarr) - 用于 Sonarr、Radarr、Prowlarr、Plex 和相关服务的媒体栈桥接器。
- [ytdl-rmcp](https://github.com/jmagar/rytdl) - 媒体下载和元数据工作流服务器。
- [synapse-rmcp](https://github.com/jmagar/synapse) - 本地 Synapse 工作流服务器，用于侦察和通量操作。
- [cortex](https://github.com/jmagar/cortex) - Syslog 和 homelab 日志聚合 MCP 服务器。
- [axon](https://github.com/jmagar/axon) - RAG、爬取、抓取、提取和语义搜索项目。
- [lumen](https://github.com/jmagar/lumen) - 本地语义代码搜索 MCP 服务器。
## 文档
从 [docs/README.md](./docs/README.md) 开始。 高价值入口：
- [架构](./docs/ARCH.md)
- [配置](./docs/runtime/CONFIG.md)
- [环境](./docs/runtime/ENV.md)
- [OAuth](./docs/runtime/OAUTH.md)
- [传输](./docs/surfaces/TRANSPORT.md)
- [网关](./docs/services/GATEWAY.md)
- [市场](./docs/services/MARKETPLACE.md)
- [ACP](./docs/acp/README.md)
- [测试](./docs/dev/TESTING.md)
- [操作](./docs/OPERATIONS.md)
## 许可证
工作区元数据声明 `MIT OR Apache-2.0`。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器