内容
# Synology ActiveProtect 管理器 (APM) — Python 软件开发工具包、命令行工具和 MCP 服务器
[](https://github.com/synology-apm/apm-sdk-python/actions/workflows/ci.yml)
[](https://synology-apm.github.io/apm-sdk-python/)
[](https://pypi.org/project/synology-apm-sdk/)
[](https://pypi.org/project/synology-apm-cli/)
[](https://pypi.org/project/synology-apm-mcp/)
用于 [Synology ActiveProtect 管理器 (APM)](https://www.synology.com/products/ActiveProtectAppliance) 的 Python 软件开发工具包、命令行工具和 MCP 服务器。
- **synology-apm-sdk** (`synology_apm.sdk`) — 异步原生、完全类型化的 Python 接口，用于 APM REST API。
- **synology-apm-cli** (`synology_apm.cli`) — 命令行前端，基于 `synology-apm-sdk` 构建，用于从终端操作 APM（`synology-apm` 命令）。
- **synology-apm-mcp** (`synology_apm.mcp`) — MCP 服务器，基于 `synology-apm-sdk` 构建，将 APM 操作暴露为 AI 代理的工具（Claude Desktop、ChatGPT Desktop 和其他 MCP 兼容客户端）。
本页面是一个起点。有关产品背景、使用指南和命令参考，请参见下面的[文档](#文档)。
---
## 本仓库的内容
本仓库是一个 [uv](https://docs.astral.sh/uv/) 工作空间，从共享源代码发布 **三个** PyPI 软件包：
| 路径 | 描述 |
|------|-------------|
| `packages/synology-apm-sdk/` | `synology-apm-sdk` PyPI 软件包（`synology_apm.sdk` 导入） |
| `packages/synology-apm-cli/` | `synology-apm-cli` PyPI 软件包（`synology_apm.cli` 导入；依赖于 `synology-apm-sdk`） |
| `packages/synology-apm-mcp/` | `synology-apm-mcp` PyPI 软件包 — 用于 AI 代理集成的 MCP 服务器（依赖于 `synology-apm-sdk`） |
| `skills/` | MCP 服务器的工作流技能 — 教导 AI 代理如何使用 MCP 工具实现领域目标 |
| `examples/` | 基于 `synology_apm.sdk` 构建的示例自动化脚本 |
| `docs/` | Sphinx API 参考源代码 — 发布到 [GitHub Pages](https://synology-apm.github.io/apm-sdk-python/)（参见 [API 参考](#api-参考)） |
---
## 文档
| 文档 | 描述 |
|----------|-------------|
| [`APM_PRODUCT_OVERVIEW.md`](APM_PRODUCT_OVERVIEW.md) | APM 产品/领域知识：工作负载类别、保护计划、备份副本和其他核心概念 |
| [`packages/synology-apm-sdk/README.md`](packages/synology-apm-sdk/README.md) | SDK 开发人员指南 — 快速入门和每个模块的使用示例 |
| [API 参考](https://synology-apm.github.io/apm-sdk-python/) | 完整的 SDK API 参考 — 每个公共类、方法和类型签名（Sphinx，在 GitHub Pages 上托管） |
| [`packages/synology-apm-cli/README.md`](packages/synology-apm-cli/README.md) | CLI 命令参考 — 身份验证、输出格式、完整的命令列表 |
| [`packages/synology-apm-mcp/README.md`](packages/synology-apm-mcp/README.md) | MCP 服务器指南 — Claude Desktop / ChatGPT Desktop 设置、操作模式、可用工具和工作流技能 |
| [`examples/README.md`](examples/README.md) | 示例自动化脚本（库存、报告、批量导入/导出等） |
| [`CLAUDE.md`](CLAUDE.md) | 开发指南 — 测试标准、约定和常用命令 |
### API 参考
完整的 SDK API 参考（每个公共类、方法和类型签名）使用 Sphinx 从源代码生成，并在以下位置发布：
**https://synology-apm.github.io/apm-sdk-python/**
要在本地构建（例如，预览文档字符串更改）：
```bash
uv sync --group docs # 仅第一次运行
make docs
```
然后在浏览器中打开 `docs/_build/html/index.html`。
---
## 需求
- Python 3.11 或更高版本
---
## 安装
### 选项 A — 从 PyPI 安装
```bash
pip install synology-apm-sdk # 仅限库
pip install synology-apm-cli # CLI（依赖于 synology-apm-sdk），提供 `synology-apm` 命令
```
### 选项 B — 从源代码安装（开发）
该仓库是一个 uv 工作空间，包含三个成员：`packages/synology-apm-sdk`、`packages/synology-apm-cli` 和 `packages/synology-apm-mcp`。
```bash
git clone https://github.com/synology-apm/apm-sdk-python.git
cd apm-sdk-python
# 以可编辑模式安装两个软件包，以及开发工具（pytest、mypy、ruff 等）
uv sync
# 运行 CLI
uv run synology-apm config set --host apm.corp.com --username admin
```
### 选项 C — 构建和安装轮文件
```bash
make whl # → dist/synology-apm-sdk/*.whl + *.tar.gz, dist/synology-apm-cli/*.whl + *.tar.gz, dist/synology-apm-mcp/*.whl + *.tar.gz
pip install dist/synology-apm-sdk/synology_apm_sdk-<version>-py3-none-any.whl
pip install dist/synology-apm-cli/synology_apm_cli-<version>-py3-none-any.whl
```
将 `<version>` 替换为文件名中的实际版本号（例如 `0.1.0`）。
这三个选项都安装了 `synology_apm.sdk` 软件包，并且当安装了 `synology-apm-cli` 时，还安装了 `synology-apm` 命令（在 `packages/synology-apm-cli/pyproject.toml` 中定义 → `[project.scripts]`）。
`make whl` 还构建了 `dist/synology-apm-mcp/*.whl`。运行 MCP 服务器的推荐方法是 `uvx synology-apm-mcp` 或 Claude/ChatGPT Desktop 插件（参见下面的 [AI 代理集成](#ai-代理集成)），而非手动 `pip install`，但如果您想要直接使用 `synology-apm-mcp` 命令，也可以运行 `pip install dist/synology-apm-mcp/synology_apm_mcp-<version>-py3-none-any.whl`。
### AI 代理集成
`packages/synology-apm-mcp/` 是一个 MCP 服务器，它将整个 SDK 暴露为 MCP 工具，供 AI 代理（Claude Desktop、ChatGPT Desktop 和其他 MCP 兼容客户端）使用，以及教导代理领域目标的工作流技能 — 每日备份报告、存储容量分析、故障调查等。
有关安装（Claude Desktop、ChatGPT Desktop）和完整设置指南，请参见 [`packages/synology-apm-mcp/README.md`](packages/synology-apm-mcp/README.md)。
---
## 快速入门
> 有关 MCP 服务器设置（AI 代理集成），请参见上面的 [AI 代理集成](#ai-代理集成)。
### CLI
```bash
synology-apm config set --host apm.corp.com --username admin
synology-apm infra info
```
有关身份验证选项、输出格式和完整命令参考，请参见 [`packages/synology-apm-cli/README.md`](packages/synology-apm-cli/README.md)。
### SDK
```python
import asyncio
from synology_apm.sdk import APMClient
async def main():
async with APMClient("apm.corp.com", "admin", "password") as apm:
workloads, _ = await apm.machine.workloads.list()
for wl in workloads:
print(f"{wl.name} last backup: {wl.last_backup_at}")
asyncio.run(main())
```
有关完整的数据模型和使用示例，请参见 [`packages/synology-apm-sdk/README.md`](packages/synology-apm-sdk/README.md)。
---
## 开发
有关开发指南，请参见 [`CLAUDE.md`](CLAUDE.md)：测试标准、代码约定和常用命令（测试、 linting、类型检查、文档、技能生成）。
