Zulip 集成

与 Zulip 聊天平台交互，实现团队沟通。

设置

1. 安装 Python 客户端

bash
pip install zulip

2. 创建配置文件

创建 ~/.config/zulip/zuliprc：

ini
[api]
email=bot@example.zulipchat.com
key=在此处填写您的API密钥
site=https://example.zulipchat.com

从 Zulip 管理面板（设置 → 机器人）获取凭证。

3. 验证连接

bash
python scripts/zulip_client.py streams

快速入门

使用辅助脚本

scripts/zulip_client.py 提供常用操作：

列出频道：
bash
python scripts/zulip_client.py streams
python scripts/zulip_client.py streams --json

读取消息：
bash

最近的频道消息（按名称）

python scripts/zulip_client.py messages --stream General --num 10

按频道ID（更可靠，使用streams查找ID）

python scripts/zulip_client.py messages --stream-id 42 --num 10

特定话题

python scripts/zulip_client.py messages --stream General --topic Updates

私信

python scripts/zulip_client.py messages --type private --num 5

提及消息

python scripts/zulip_client.py messages --type mentioned

注意： 频道名称可能包含看起来像名称一部分的描述。使用 --stream-id 进行明确标识。

发送消息：
bash

发送到频道

python scripts/zulip_client.py send --type stream --to General --topic Updates --content 你好！

私信（用户ID）

python scripts/zulip_client.py send --type private --to 123 --content 你好

列出用户：
bash
python scripts/zulip_client.py users
python scripts/zulip_client.py users --json

直接使用 Python 客户端

python
import zulip

client = zulip.Client(config_file=~/.config/zulip/zuliprc)

读取消息

result = client.get_messages({ anchor: newest, num_before: 10, num_after: 0, narrow: [{operator: stream, operand: General}] })

发送到频道

client.send_message({ type: stream, to: General, topic: Updates, content: 消息文本 })

发送私信

client.send_message({ type: private, to: [user_id], content: 私信内容 })

使用 curl

bash

列出频道

curl -u bot@example.com:KEY https://example.zulipchat.com/api/v1/streams

获取消息

curl -u bot@example.com:KEY -G \ https://example.zulipchat.com/api/v1/messages \ --data-urlencode anchor=newest \ --data-urlencode num_before=20 \ --data-urlencode num_after=0 \ --data-urlencode narrow=[{operator:stream,operand:General}]

发送消息

curl -X POST https://example.zulipchat.com/api/v1/messages \ -u bot@example.com:KEY \ --data-urlencode type=stream \ --data-urlencode to=General \ --data-urlencode topic=Updates \ --data-urlencode content=你好！

常见工作流程

监控频道新消息

python
def getlatestmessages(client, streamname, lastseen_id=None):
narrow = [{operator: stream, operand: stream_name}]

if lastseenid:
# 仅获取上次查看后的消息
request = {
anchor: lastseenid,
num_before: 0,
num_after: 100,
narrow: narrow
}
else:
# 获取最近消息
request = {
anchor: newest,
num_before: 20,
num_after: 0,
narrow: narrow
}

result = client.get_messages(request)
return result[messages]

回复话题

python
def replytomessage(client, originalmessage, replytext):
在原始消息所在的同一频道/话题中回复。
client.send_message({
type: stream,
to: originalmessage[displayrecipient],
topic: original_message[subject],
content: reply_text
})

搜索消息

python
def search_messages(client, keyword, stream=None):
narrow = [{operator: search, operand: keyword}]

if stream:
narrow.append({operator: stream, operand: stream})

result = client.get_messages({
anchor: newest,
num_before: 50,
num_after: 0,
narrow: narrow
})

return result[messages]

通过邮箱获取用户ID

python
def getuserid(client, email):
通过邮箱地址查找用户ID。
result = client.get_members()

for user in result[members]:
if user[email] == email:
return user[user_id]

return None

消息格式

Zulip 使用 Markdown：

• - 粗体： 文本
• 斜体： 文本
• 代码： 代码
• 代码块： 语言\n代码\n
• 引用： > 引用文本
• 提及用户： @全名
• 链接频道： #频道名称
• 链接： 文本

高级功能

上传和分享文件

python
with open(file.pdf, rb) as f:
result = client.upload_file(f)
file_url = result[uri]

在消息中分享

client.send_message({ type: stream, to: General, topic: Files, content: f查看此文件 })

对消息做出反应

python

添加反应

client.add_reaction({
message_id: 123,
emojiname: thumbsup
})

移除反应

client.remove_reaction({ message_id: 123, emojiname: thumbsup })

参考

完整 API 文档、端点和示例请参见 references/api-quick-reference.md。

故障排除

找不到配置文件：

• - 确保 ~/.config/zulip/zuliprc 存在且格式正确
• 检查文件权限（应为可读）

身份验证失败：

• - 验证 API 密钥是否正确
• 检查机器人在 Zulip 管理面板中是否处于活动状态
• 确保站点 URL 与组织 URL 匹配

消息数组为空：

• - 机器人可能未订阅该频道
• 使用 client.get_subscriptions() 检查订阅情况
• 管理员可能需要将机器人添加到私有频道

速率限制错误：

• - 标准限制：200 次请求/分钟
• 消息限制：约 20-30 条/分钟
• 在批量操作之间添加延迟
• 检查 429 响应中的 Retry-After 头信息