pheme (Divyekant)

菲梅

为什么是菲姆？

人工智能代理自主运行，但仍需要联系人类：批准、错误警报、状态更新、任务完成。如果没有标准的通知层，每个代理都会重新设计渠道集成。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/.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根据紧急程度将消息路由到通道。代理可以说“这很关键”，并让路由决定它去哪里，而不是硬编码通道名称。

默认路由

自定义路线

通过创建YAML文件覆盖路由。Pheme按以下顺序搜索（第一场比赛获胜）：

1. 项目级别： .claude/pheme-routes.yaml （在当前工作目录中）
2. 项目级别（食品法典委员会）： .codex/pheme-routes.yaml
3. 用户级别： ~/.claude/pheme-routes.yaml
4. 用户级别（Codex）： ~/.codex/pheme-routes.yaml
5. 违约： 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插件。

斜杠命令

代理技能

捆绑技能 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

依赖项

文档

完整的外部文档可在 docs/generated/external/:

• 入门指南 --安装并发送您的第一个通知
• API 参考 --所有4个MCP工具的详细信息
• 配置参考 --Env-vars和YAML路由
• 错误参考 --错误代码和解决方案
• 食谱 --复制粘贴常见场景的食谱
• 教程 --逐步演练
• 通知发送 --深入了解发送工具
• 渠道管理 --通道设置和测试
• 紧急路由 --路由配置指南

许可证

麻省理工学院