claude-lark

claude-lark

Claude Code → 飞书通知

English

Claude Code 完成任务或需要你确认时，自动发送飞书消息提醒——让你可以放心离开终端，回来时不会错过任何事。

---

特性

• 零依赖 — 纯 Python 标准库，不需要 pip install
• 无需服务 — 本地 hook 脚本直接调飞书 API，不用跑任何后台服务
• 轻量快速 — token 自动缓存（2 小时有效），每次通知仅 ~100ms
• 静默失败 — 任何异常都不会阻塞 Claude Code
• 丰富卡片 — 项目、设备、统计（tokens / 工具 / 耗时）、git 信息、Claude 回复
• 多事件支持 — 任务完成、权限确认、等待输入等不同场景使用不同卡片样式
• 手机号/邮箱安装 — 无需手动查 Open ID，安装器自动通过手机号或邮箱获取
• 子 Agent 感知 — 追踪并展示 Claude Code 派生的子 Agent

工作原理

Claude Code 事件 (Stop / Notification)
  → 触发本地 hook 脚本
    → 获取飞书 tenant_access_token（有缓存）
      → 调飞书消息 API 发送卡片
        → 你在飞书收到通知

只有 2 个 HTTP 请求，全部在本地完成，不依赖任何中间服务。

---

快速开始

方式 1：Claude Code 插件安装（推荐）

两条命令搞定，全程不离开 Claude Code：

/plugin install claude-lark from ysyecust/claude-lark
/setup-lark

/setup-lark 会引导你输入 App ID、App Secret 和手机号，自动完成 Open ID 查询、配置写入和测试通知。

如果团队管理员已经给你准备好了配置文件，直接放到 ~/.config/claude-lark/config.json 即可，跳过 /setup-lark。

方式 2：一键安装 (macOS / Linux)

curl -fsSL https://raw.githubusercontent.com/ysyecust/claude-lark/main/scripts/install-remote.sh | bash

方式 3：手动克隆安装

git clone https://github.com/ysyecust/claude-lark.git
cd claude-lark

# macOS / Linux
chmod +x scripts/install.sh && ./scripts/install.sh

# Windows (PowerShell)
.\scripts\install.ps1

安装器会引导你完成：

1. 输入飞书机器人凭证（App ID + App Secret，团队管理员提供）
2. 选择身份验证方式（手机号 / 邮箱 / 直接输入 Open ID）
3. 自动验证 API 连接
4. 发送测试通知到你的飞书
5. 自动配置 Claude Code hooks

3. 完成

之后 Claude Code 每次完成回复，你都会在飞书收到通知卡片。

---

配置

配置文件位于 ~/.config/claude-lark/config.json（macOS/Linux 下权限 600 仅用户可读；Windows 上请确保文件不被其他用户读取）：

{
    "app_id": "cli_xxx",
    "app_secret": "xxx",
    "open_id": "ou_xxx",
    "events": ["Stop", "Notification"]
}

字段	说明	来源
app_id	飞书机器人 App ID	团队管理员提供
app_secret	飞书机器人 App Secret	团队管理员提供
open_id	你的飞书 Open ID	安装器自动获取
events	通知哪些事件（可选）	默认 ["Stop", "Notification"]

事件过滤

通过 events 字段控制通知哪些事件：

{
    "events": ["Stop"]
}

值	含义
Stop	Claude Code 完成回复时通知
Notification	Claude Code 需要确认/输入时通知

如果只想在任务完成时收到通知，去掉 "Notification" 即可。

环境变量

变量	说明	默认值
CLAUDE_LARK_TZ_OFFSET	时区偏移（相对 UTC 的小时数）	8（Asia/Shanghai）
CLAUDE_LARK_DEBUG	开启调试日志，写入 ~/.config/claude-lark/debug.log	关闭

开启调试日志（排查问题时使用）：

export CLAUDE_LARK_DEBUG=1

---

通知卡片

✅ 任务完成 (Stop)

Claude Code 完成回复时发送，turquoise 绿色卡片：

信息	说明
项目	当前工作目录的项目名
设备	运行 Claude Code 的主机名
统计	耗时、tokens（本轮/总计）、工具调用（本轮/总计）、对话轮次、git 分支
子 Agent	本轮新派生的 Agent，显示类型和描述
Git	最近提交、分支、是否有未提交更改
回复	Claude 最后一条回复（markdown 转换后，最长 4000 字）

⚠️ 需要确认 (Notification)

Claude Code 需要你的输入时发送，根据类型使用不同颜色：

类型	颜色	含义
permission_prompt	🟠 橙色	Claude 需要执行权限
idle_prompt	🟡 黄色	Claude 等待你的输入
auth_success	🟢 绿色	认证完成
elicitation_dialog	🔵 蓝色	Claude 需要额外信息

🔧 子 Agent 完成

蓝色卡片，标明来自 worktree/swarm 子 Agent，与主 Agent 通知明确区分。

---

飞书机器人配置（团队管理员操作）

完整指南含常见问题排查：docs/admin-setup.md

创建机器人

1. 打开 飞书开放平台
2. 创建 自建应用
3. 添加应用能力 → 开启 机器人

配置权限

在 权限管理 中开通以下权限：

权限	权限标识	用途
发送消息	im:message:send_as_bot	发送通知卡片（必需）
获取用户 ID	contact:user.id:readonly	安装时通过手机号/邮箱查找用户（推荐）

发布应用

1. 版本管理 → 创建版本 → 发布
2. 在管理后台审批通过

分发给团队（两种方式）

方式 A：分享凭证 — 把 App ID + Secret 发给成员，他们自己运行 ./scripts/install.sh。

方式 B：管理员批量生成配置（推荐，凭证不离开管理员手中）：

./scripts/admin-setup.sh

脚本会：

1. 输入 App ID + Secret（仅管理员可见）
2. 逐个输入成员手机号
3. 批量查询 Open ID
4. 在 team-configs/ 下生成每人的 config-手机号.json

然后分发：

# 把对应的 config 文件发给每个人，他们只需：
mkdir -p ~/.config/claude-lark
cp config-138xxxx.json ~/.config/claude-lark/config.json
chmod 600 ~/.config/claude-lark/config.json
./scripts/install.sh   # 跳过凭证步骤，只安装 hook

---

手动安装

如果不想使用安装器，手动配置：

1. 创建配置文件

mkdir -p ~/.config/claude-lark
cat > ~/.config/claude-lark/config.json << 'EOF'
{
    "app_id": "cli_xxx",
    "app_secret": "xxx",
    "open_id": "ou_xxx",
    "events": ["Stop", "Notification"]
}
EOF
chmod 600 ~/.config/claude-lark/config.json

2. 编辑 Claude Code 设置

在 ~/.claude/settings.json 的 hooks 中添加（Windows 上请用 python 替代 python3）：