菲梅
为什么是菲姆？
人工智能代理自主运行，但仍需要联系人类：批准、错误警报、状态更新、任务完成。如果没有标准的通知层，每个代理都会重新设计渠道集成。Pheme通过提供：
- 一个接口 --4个MCP工具涵盖所有通知需求
- 100+频道 --Apprise支持什么，Pheme支持什么
- 基于紧迫性的路由 --关键警报分散到多个渠道；低优先级更新保持安静
- 零通道锁定 --通道是通过环境变量而不是代码配置的
- 内置安全功能 --消息长度上限、秘密检测警告、审计日志记录
快速开始
先决条件
- Python 3.10+
- 与Apprise兼容的频道（Slack、Telegram、电子邮件等）
安装
git clone https://github.com/divyekant/pheme.git
cd pheme
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"配置频道
设置一个或多个 PHEME_ 环境变量 识别URL:
# Slack
export PHEME_SLACK="slack://tokenA/tokenB/tokenC/#general"
# Telegram
export PHEME_TELEGRAM="tgram://bot_token/chat_id"
# Email
export PHEME_EMAIL="mailto://user:pass@gmail.com?to=recipient@example.com"
# Discord
export PHEME_DISCORD="discord://webhook_id/webhook_token"
# macOS native notifications
export PHEME_SYSTEM="macosx://"
# Webhooks
export PHEME_WEBHOOK="json://endpoint.example.com/path"看 学习wiki 查看支持的服务及其URL格式的完整列表。
运行MCP服务器
python -m server服务器使用MCP协议通过stdio进行通信，准备好连接任何兼容MCP的客户端。
Claude代码集成
Claude Code从读取MCP服务器配置 三个不同的地点 这取决于客户。您必须为您的客户将Pheme添加到正确的文件中：
| 客户端 | 配置文件 |
|---|---|
Claude 代码命令行工具 (claude 在终端） | ~/.claude.json → mcpServers |
| 克劳德桌面版 （macOS应用程序） | ~/.claude/.mcp.json |
| 项目级别 （每个目录覆盖） | ` |
| /.mcp.json` |
重要提示： 每个客户端都从自己的文件中读取。服务器在 ~/.claude/.mcp.json 是 不 CLI可见，反之亦然。如果工具没有出现，请检查服务器是否在您使用的客户端的正确文件中注册。克劳德代码CLI(~/.claude.json)
添加到顶级 mcpServers key（如果缺少则创建）：
{
"mcpServers": {
"pheme": {
"type": "stdio",
"command": "/path/to/pheme/.venv/bin/python",
"args": ["-m", "server"],
"cwd": "/path/to/pheme",
"env": {
"PHEME_TELEGRAM": "tgram://bot_token/chat_id",
"PHEME_SYSTEM": "macosx://"
}
}
}
}克劳德桌面(~/.claude/.mcp.json)
{
"mcpServers": {
"pheme": {
"command": "/path/to/pheme/.venv/bin/python",
"args": ["-m", "server"],
"cwd": "/path/to/pheme",
"env": {
"PHEME_TELEGRAM": "tgram://bot_token/chat_id",
"PHEME_SYSTEM": "macosx://"
}
}
}
}项目级别(`
/.mcp.json`)
格式与Claude Desktop相同。放置在项目根目录中，使Pheme仅在该目录中可用。
技能符号链接
要使代理技能在全球范围内可用：
mkdir -p ~/.claude/skills
ln -s /path/to/pheme/skills/pheme ~/.claude/skills/pheme配置更改后重新启动Claude Code——MCP服务器在会话开始时连接。
食品法典整合
将Pheme添加到 ~/.codex/config.toml:
[mcp_servers.pheme]
command = "/path/to/pheme/.venv/bin/python"
args = ["-m", "server"]
cwd = "/path/to/pheme"为了在全球范围内推广Codex的技能：
mkdir -p ~/.agents/skills
ln -s /path/to/pheme/skills/pheme ~/.agents/skills/pheme在配置更改后重新启动Codex，以便它能够使用MCP服务器和技能。
详细的食品法典说明： /.codex/INSTALL.md
MCP工具
Pheme通过MCP协议公开了4个工具：
send --发送通知
核心工具。按名称或紧急程度向一个或多个频道发送消息。
send(
message: str, # Required. The notification content (max 4000 chars).
channel: str | None, # Single channel name, e.g. "slack"
channels: list[str] | None, # Multiple channels, e.g. ["slack", "telegram"]
urgency: str | None, # "low", "normal", "high", "critical"
title: str | None, # Optional title/subject line
format: str = "text" # "text", "markdown", or "html"
)路由优先级： channel > channels > urgency >默认值(normal)
答复：
{
"success": true,
"delivered": ["slack", "telegram"],
"failed": []
}list_channels --显示已配置的频道
返回从中发现的所有频道 PHEME_* 环境变量。
{
"channels": [
{"name": "slack", "configured": true},
{"name": "telegram", "configured": true}
]
}get_routes --显示紧急路线
将当前紧急程度返回给通道映射。
{
"critical": ["slack", "telegram", "system"],
"high": ["slack"],
"normal": ["slack"],
"low": ["session"]
}test_channel --验证通道是否正常工作
发送测试通知以确认通道配置正确。
test_channel(channel: str) # e.g. "slack"紧急路由
Pheme根据紧急程度将消息路由到通道。代理可以说“这很关键”，并让路由决定它去哪里，而不是硬编码通道名称。
默认路由
| 紧迫性 | 渠道 | 用例 |
|---|---|---|
critical | 松弛、电报、系统 | 生产中断、安全事件、阻塞问题 |
high | 松弛 | 公关审查、构建失败、重要更新 |
normal | slack | 任务完成、状态更新、信息 |
low | 会议 | 背景活动、总结、仅供参考 |
自定义路线
通过创建YAML文件覆盖路由。Pheme按以下顺序搜索（第一场比赛获胜）：
- 项目级别：
.claude/pheme-routes.yaml（在当前工作目录中） - 项目级别（食品法典委员会）：
.codex/pheme-routes.yaml - 用户级别：
~/.claude/pheme-routes.yaml - 用户级别（Codex）：
~/.codex/pheme-routes.yaml - 违约：
config/default-routes.yaml（与Pheme捆绑在一起）
# .claude/pheme-routes.yaml
routes:
critical:
- slack
- telegram
- email
- system
high:
- slack
- email
normal:
- slack
low:
- session安全
Pheme包括几种在生产代理工作流程中安全使用的强化措施：
消息长度上限
消息的长度限制为4000个字符。较长的消息会被错误拒绝——这可以防止失控的代理将大量有效载荷转储到通知通道中。
秘密侦查
在发送之前，Pheme会扫描消息中看起来像秘密的模式：
- API密钥和令牌(
api_key=,token=等等） - JWTs(
eyJ...) - 条纹风格按键(
sk_live_...,pk_test_...) - Slack代币(
xoxb-...) - GitHub PAT(
ghp_...) - PEM私钥
如果找到匹配项，Pheme会向stderr记录警告，但 不阻塞 消息——代理或用户可能有正当理由包含内容。
审计日志
每个 send 调用被记录到stderr中，并显示：
- 紧急程度
- 目标渠道
- 交付结果（已交付/失败）
- 消息长度
Claude代码插件
Pheme是一个带有斜线命令和代理技能的Claude Code插件。
斜杠命令
| 命令 | 描述 |
|---|---|
/pheme test | 发送测试ping以验证通道 |
/pheme send | 向特定频道发送消息 |
/pheme send --urgency | 使用紧急路由发送 |
/pheme-status | 显示已配置的通道和路由表 |
代理技能
捆绑技能 skills/pheme/SKILL.md 教导代理人何时以及如何使用Pheme。它包括：
- 何时通知（批准、错误、完成）与何时不通知（记录、内部通信）
- 如何选择正确的紧急程度
- 如何编写好的通知消息（发生了什么，在哪里，该怎么办）
- 工具使用示例
建筑
┌─────────────┐ MCP (stdio) ┌──────────────────┐
│ AI Agent │ ──────────────────> │ Pheme Server │
│ (Claude, │ │ │
│ Argos, │ │ ┌────────────┐ │
│ etc.) │ │ │ Router │ │
└─────────────┘ │ │ (urgency → │ │
│ │ channels) │ │
│ └─────┬──────┘ │
│ │ │
│ ┌─────▼──────┐ │
│ │ Apprise │ │
│ │ (delivery) │ │
│ └─────┬──────┘ │
└────────┼─────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
┌────▼────┐ ┌─────▼─────┐ ┌─────▼─────┐
│ Slack │ │ Telegram │ │ Email │
└─────────┘ └───────────┘ └───────────┘项目结构
pheme/
├── server/
│ ├── __init__.py
│ ├── __main__.py # Entry point: python -m server
│ ├── config.py # Channel discovery (env vars) + route loading (YAML)
│ ├── router.py # Urgency-based channel resolution
│ └── server.py # MCP server, tools, security checks
├── config/
│ └── default-routes.yaml
├── skills/
│ └── pheme/
│ └── SKILL.md # Agent skill — when/how to use Pheme
├── commands/
│ ├── pheme.md # /pheme slash command
│ └── pheme-status.md # /pheme-status slash command
├── tests/
│ ├── test_config.py # 7 tests — channel discovery, route loading
│ ├── test_router.py # 8 tests — urgency resolution, fallbacks
│ ├── test_server.py # 16 tests — tools, security, edge cases
│ └── test_integration.py # 1 test — full end-to-end flow
├── .claude-plugin/
│ └── plugin.json # Claude Code plugin manifest
├── pyproject.toml
└── README.md发展
运行测试
source .venv/bin/activate
pytest -v所有32项测试均应通过：
tests/test_config.py — 7 passed
tests/test_router.py — 8 passed
tests/test_server.py — 16 passed
tests/test_integration.py — 1 passed依赖项
| 包装 | 用途 |
|---|---|
mcp[cli] >=1.2.0 | MCP服务器框架（FastMCP） |
apprise >=1.9.0 | 通知传递（100+通道） |
pyyaml >=6.0 | 路由配置解析 |
pytest >=8.0 | 测试（开发） |
pytest-asyncio >=0.24 | 异步测试支持（开发） |
文档
完整的外部文档可在 docs/generated/external/:
- 入门指南 --安装并发送您的第一个通知
- API 参考 --所有4个MCP工具的详细信息
- 配置参考 --Env-vars和YAML路由
- 错误参考 --错误代码和解决方案
- 食谱 --复制粘贴常见场景的食谱
- 教程 --逐步演练
- 通知发送 --深入了解发送工具
- 渠道管理 --通道设置和测试
- 紧急路由 --路由配置指南
许可证
麻省理工学院