slack

Slack 技能

完整的 Slack 工作区集成，包含三种模式：

1. 脚本 — 9 个 Python 脚本，用于按需执行 Slack 操作
2. 会话桥接 — 将此 Claude Code 会话连接到 Slack（后台监听器 + 收件箱文件，无额外 API 费用）
3. 统一启动器 — 使用 Claude Agent SDK、灵魂引擎和按频道划分的会话的 claudicle.py（需要 SDK API 密钥）

何时使用此技能

脚本（按需）

• 向 Slack 频道或话题串发送消息（可选带有 AI 反馈按钮）
• 读取频道历史记录或话题串回复
• 通过 RTS API 搜索消息、文件、频道或用户（RTS API 不可用时回退到旧版 API）
• 通过聊天流式 API 实时流式传输消息
• 为消息添加或管理表情回应
• 上传文件或代码片段
• 列出频道、获取频道信息或加入频道（包括批量加入）
• 按姓名、ID 或电子邮件查找用户

会话桥接（推荐）

• 将任何正在运行的 Claude Code 会话连接到 Slack
• 使用完整工具访问权限回复 @提及和私信（此会话就是大脑）
• 无额外 API 费用 — 消息在当前会话上下文中处理
• 通过 UserPromptSubmit hook 自动通知新消息
• 通过 soul.md 指令塑造 Claudicle 个性（无需 XML 机制）

统一启动器（持久运行，需要 SDK API 密钥）

• 在单个进程中将 Claudicle 作为交互式终端 + Slack 机器人运行
• 实时以“Claudicle, Artifex Maximus”的身份回复 @提及和私信
• 在话题串中进行多轮对话（通过 Claude Agent SDK 按频道保持会话连续性）
• 按用户进行个性建模（学习沟通风格、兴趣和专业知识）
• 跨话题串灵魂状态（追踪当前项目、任务、主题和情绪状态）
• 三层记忆：工作记忆（按话题串）、用户模型（按用户）、灵魂记忆（全局）
• 所有 Slack 活动都会与直接终端交互一同显示在终端中

前置条件

所有脚本都需要 SLACK_BOT_TOKEN 环境变量（以 xoxb- 开头的 Bot User OAuth Token）。脚本还需要 requests（uv pip install --system requests）。

可选：SLACK_USER_TOKEN（xoxp-）可在 RTS API 不可用时，通过旧版 search.messages/search.files 启用工作区范围搜索。其他所有操作均使用机器人令牌。

# Verify tokens
echo $SLACK_BOT_TOKEN
echo $SLACK_USER_TOKEN  # optional, for legacy search fallback

首次设置

1. 前往 api.slack.com/apps → Create New App → From Scratch
2. 将其命名为 "Claude Code" → 选择你的工作区
3. OAuth & Permissions → Bot Token Scopes → 添加以下所有权限：
   • app_mentions:read
   • channels:history、groups:history、im:history、mpim:history
   • channels:read、groups:read、im:read、im:write
   • channels:join — 允许机器人以编程方式加入公开频道
   • chat:write
   • files:write、files:read
   • reactions:write、reactions:read
   • search:read — 旧版搜索（仅限机器人可见的频道）
   • search:read.public、search:read.private、search:read.im、search:read.mpim、search:read.files、search:read.users — RTS API（统一搜索，2026 年 2 月及之后）
   • users:read、users:read.email
   • users:write（可选 — 启用绿色在线状态圆点）
4. Settings → Socket Mode → 切换为 ON → 生成 App-Level Token：
   • 名称：socket-mode
   • Scope：connections:write
   • 复制 xapp- 令牌
5. Event Subscriptions → 切换为 ON（使用 Socket Mode 无需 Request URL）→ Subscribe to Bot Events → 添加：
   • app_mention — 频道 @提及
   • message.im — 直接消息（收发私信必需）
   • app_home_opened — App Home 标签页渲染
6. App Home → Show Tabs → 启用 "Allow users to send Slash commands and messages from the messages tab"
7. Install to Workspace → 批准权限 → 复制 Bot User OAuth Token
8. 设置环境变量（添加到 shell 配置文件）：

   export SLACK_BOT_TOKEN=xoxb-...   # Bot User OAuth Token
   export SLACK_APP_TOKEN=xapp-...   # App-Level Token (Socket Mode)
   export SLACK_USER_TOKEN=xoxp-...  # (optional) User Token for legacy workspace-wide search
   

9. 邀请机器人加入频道：/invite @Claude Code

更改任何权限范围或事件订阅后：重新安装应用（Install App → Reinstall to Workspace）并重启启动器。

---

快速开始

# Post a message
python3 ~/.claude/skills/slack/scripts/slack_post.py "#general" "Hello from Claude"

# Post with AI feedback buttons
python3 ~/.claude/skills/slack/scripts/slack_post.py "#general" "Here's my analysis" --ai

# Read recent messages
python3 ~/.claude/skills/slack/scripts/slack_read.py "#general" -n 10

# Search the workspace (auto-detects RTS API, falls back to legacy)
python3 ~/.claude/skills/slack/scripts/slack_search.py "deployment status"

# Search with RTS API (messages, files, channels, users)
python3 ~/.claude/skills/slack/scripts/slack_search.py "deployment" --rts --type channels

# Stream a message in real-time
python3 ~/.claude/skills/slack/scripts/slack_stream.py "#general" "Streaming message..."

# Join all public channels
python3 ~/.claude/skills/slack/scripts/slack_channels.py --join-all-public

# Connect this session to Slack (recommended)
cd ~/.claude/skills/slack/daemon && python3 slack_listen.py --bg
python3 ~/.claude/skills/slack/scripts/slack_check.py

# Start the unified launcher (requires SDK API key)
cd ~/.claude/skills/slack/daemon && python3 claudicle.py

---

会话桥接（推荐）

将任何正在运行的 Claude Code 会话连接到 Slack。后台监听器会捕获 @提及和私信 → inbox.jsonl。此会话读取收件箱、使用完整工具访问权限处理消息，并将回复发回。无需额外 API 费用。

# Connect
cd ~/.claude/skills/slack/daemon && python3 slack_listen.py --bg

# Check messages
python3 ~/.claude/skills/slack/scripts/slack_check.py

# Respond to thread, remove hourglass, mark handled
python3 ~/.claude/skills/slack/scripts/slack_post.py "C12345" "response" --thread "TS"
python3 ~/.claude/skills/slack/scripts/slack_react.py "C12345" "TS" "hourglass_flowing_sand" --remove
python3 ~/.claude/skills/slack/scripts/slack_check.py --ack 1

# Disconnect
python3 ~/.claude/skills/slack/daemon/slack_listen.py --stop

Soul Formatter（可选）：scripts/slack_format.py 添加 Open Souls 认知步骤格式化 — 感知框架、对话提取、独白记录。

python3 slack_format.py perception "Tom" "What's the status?"   # → Tom said, "..."
echo "$raw" | python3 slack_format.py extract                   # → external dialogue only
echo "$raw" | python3 slack_format.py extract --narrate --log   # → narrated + logged
python3 slack_format.py instructions                            # → cognitive step XML format

自动回复：/slack-respond 会将所有待处理消息作为 Claudicle 处理，并执行完整认知步骤 — 感知、独白、对话、发布、确认 — 一次调用即可完成。参见 ~/.claude/skills/slack-respond/SKILL.md。

灵魂激活：/ensoul 可在任意 Claude Code 会话中激活 Claudicle 身份，并通过压缩/恢复持续注入 soul.md。随后，/slack-sync #channel 会将已注入灵魂的会话绑定到 Slack 频道。两者均需在每个会话中选择启用。灵魂注册表（~/.claude/hooks/soul-registry.py）会追踪所有活动会话及其频道绑定情况，无论是否已注入灵魂。

有关完整安装、架构、收件箱格式、自动通知钩子和故障排除，请参阅 references/session-bridge.md。

App Home：用户打开 Claudicle 的个人资料时，Home 标签页会自动渲染（通过监听器中的 app_home_opened）。显示实时状态、工具包、认知架构和记忆系统。手动刷新：

python3 ~/.claude/skills/slack/scripts/slack_app_home.py "USER_ID"
python3 ~/.claude/skills/slack/scripts/slack_app_home.py --all
python3 ~/.claude/skills/slack/scripts/slack_app_home.py --debug   # print blocks, no publish

---

脚本选择指南

任务	脚本	示例
发送消息	slack_post.py	slack_post.py "#general" "Hello"
回复消息串	slack_post.py	slack_post.py "#ch" "reply" --thread TS
安排消息发送时间	slack_post.py	slack_post.py "#ch" "msg" --schedule ISO
读取频道历史记录	slack_read.py	slack_read.py "#general" -n 20
读取消息串	slack_read.py	slack_read.py "#ch" --thread TS
搜索（RTS，自动）	slack_search.py	slack_search.py "query"
仅搜索消息	slack_search.py	slack_search.py "query" --type messages
搜索文件	slack_search.py	slack_search.py "query" --files
搜索频道/用户	slack_search.py	slack_search.py "query" --rts --type channels
流式发送消息	slack_stream.py	slack_stream.py "#ch" "text" --chunk-size 50
从 stdin 流式发送	slack_stream.py	echo "text" | slack_stream.py "#ch" --stdin
发送带 AI 按钮的消息	slack_post.py	slack_post.py "#ch" "msg" --ai
删除消息	slack_delete.py	slack_delete.py "#ch" TS1 TS2
清理消息串（机器人消息）	slack_delete.py	slack_delete.py "#ch" --thread TS
添加回应	slack_react.py	slack_react.py "#ch" TS emoji
上传文件	slack_upload.py	slack_upload.py "#ch" ./file.pdf
分享代码片段	slack_upload.py	slack_upload.py "#ch" --snippet CODE
列出频道	slack_channels.py	slack_channels.py
加入频道	slack_channels.py	slack_channels.py --join "#ch"
加入所有公开频道	slack_channels.py	slack_channels.py --join-all-public
按电子邮件查找用户	slack_users.py	slack_users.py --email [email protected]

完整的脚本文档（所有参数、示例、测试套件和常见工作流）请参阅 references/scripts-reference.md。

---

速率限制须知

层级	速率	关键方法
层级 1	1/min	conversations.history, conversations.replies
层级 2	20/min	conversations.list, users.list, search.messages, assistant.search.context
层级 3	50/min	reactions.*, conversations.info, chat.update, chat.startStream, chat.appendStream, chat.stopStream
层级 4	100+/min	files.getUploadURLExternal, files.completeUploadExternal
特殊	1/sec/channel	chat.postMessage

所有脚本都会通过 _slack_utils.py 自动处理速率限制（本地冷却 + 使用 Retry-After 重试）。完整详情请参阅 references/rate-limits.md。

---

Claudicle 统一启动器

通过 Claude Agent SDK 在一个进程中运行交互式终端和 Slack 机器人。支持按频道维持会话连续性，配备三层记忆的完整 soul 引擎，所有 Slack 活动均可在终端中查看。

# Install
cd ~/.claude/skills/slack/daemon
uv pip install --system slack-bolt claude-agent-sdk

# Launch (terminal + Slack)
python3 claudicle.py

# Verbose / terminal-only
python3 claudicle.py --verbose
python3 claudicle.py --no-slack

要求：PATH 中需包含 claude CLI，并提供 SLACK_BOT_TOKEN、SLACK_APP_TOKEN，以及 claude-agent-sdk。

流式传输：设置 SLACK_DAEMON_STREAMING=true，即可通过 chat.startStream/chat.appendStream/chat.stopStream 启用实时流式响应。仅在 soul 引擎关闭时启用（带 XML 标签的响应无法进行有意义的流式传输）。

AI 区块：设置 SLACK_DAEMON_AI_BLOCKS=true，即可在响应中加入反馈按钮。

完整的安装、架构、SDK 集成、按频道划分的会话、配置、数据流和线程模型，请参阅 references/unified-launcher-architecture.md。

---

旧版守护进程（bot.py）

独立的 bot.py 守护进程作为备用方案保留。它使用 claude -p 子进程，而不是 Agent SDK。如果不需要统一启动器，或要通过 launchd 部署，可使用此方案。

cd ~/.claude/skills/slack/daemon && python3 bot.py --verbose

生产环境（launchd）

cd ~/.claude/skills/slack/daemon
./launchd/install.sh install    # load LaunchAgent
./launchd/install.sh status     # check if running
./launchd/install.sh logs       # tail logs
./launchd/install.sh restart    # reload
./launchd/install.sh uninstall  # stop and remove

---

Soul Monitor TUI

一个独立的 Textual 终端应用，可实时展示 Claudicle 的内在状态——认知流、灵魂状态、用户模型、会话和原始日志。在启动器或守护进程运行时，可在单独的终端中运行。

cd ~/.claude/skills/slack/daemon
uv run python monitor.py

面板、颜色编码、按键绑定和数据来源详见 references/daemon-architecture.md。

查看记忆

cd ~/.claude/skills/slack/daemon
sqlite3 memory.db "SELECT key, value FROM soul_memory"
sqlite3 memory.db "SELECT user_id, display_name, interaction_count FROM user_models"
sqlite3 memory.db "SELECT entry_type, verb, content FROM working_memory ORDER BY created_at DESC LIMIT 20"
sqlite3 sessions.db "SELECT channel, thread_ts, session_id FROM sessions"

---

新用户引导

通过让 Claudicle 采访新用户，构建用户模型并生成 CLAUDE.md 文件，以初始化个性化配置。完整工作流详见 references/onboarding-guide.md。

---

故障排查

问题	解决方法
机器人未响应 @mentions	启用 Socket Mode；确认已导出 SLACK_APP_TOKEN（xapp-）
“missing_scope” 错误	在 OAuth & Permissions 中添加缺少的权限范围 → 重新安装应用
没有搜索结果	为 RTS API 添加 search:read.* 权限范围，或邀请机器人加入频道，或设置 SLACK_USER_TOKEN 以使用旧版搜索
RTS 搜索出现 “missing_scope”	添加细粒度的 search:read.* 权限范围 → 重新安装应用；脚本会自动回退到旧版搜索
流式传输无法正常工作	设置 SLACK_DAEMON_STREAMING=true；启用灵魂引擎时会禁用流式传输
channels:join 被拒绝	添加 channels:join 权限范围 → 重新安装应用
触发速率限制（429）	脚本会自动重试；减小批次大小
启动器/守护进程立即退出	确认 which claude 返回了路径
“Credit balance is too low”	检查 Anthropic 账单；错误现已显示在 Slack 响应中
灵魂引擎 XML 解析失败	检查 daemon/logs/claudicle.log；将返回原始文本作为回退
“Sending messages turned off”	App Home → 启用 “Allow users to send Slash commands and messages from the messages tab”
没有绿色在线状态圆点	添加 users:write 权限范围 → 重新安装应用
App Home 标签页为空白	订阅 app_home_opened 事件
监控 TUI 无法启动	cd daemon && uv pip install textual psutil
SDK 导入错误	uv pip install --system claude-agent-sdk

---

文件结构

daemon/
├── slack_listen.py      # Session Bridge: background Socket Mode listener
├── inbox.jsonl          # Session Bridge: incoming messages (auto-created)
├── claudicle.py          # Unified launcher (terminal + Slack, requires SDK)
├── slack_adapter.py     # Socket Mode event handling (extracted from bot.py)
├── terminal_ui.py       # Async terminal input + activity log
├── claude_handler.py    # Claude invocation (subprocess + SDK async)
├── soul_engine.py       # Cognitive prompt wrapping + XML parsing
├── working_memory.py    # Per-thread metadata store
├── user_models.py       # Per-user personality profiles
├── soul_memory.py       # Global soul state
├── session_store.py     # Thread → session ID mapping
├── config.py            # All settings (env var overrides)
├── bot.py               # Legacy standalone daemon (fallback)
├── monitor.py           # Soul Monitor TUI (Textual)
├── watcher.py           # DB file watcher for monitor
├── soul.md              # Claudicle personality blueprint
├── skills.md            # Capabilities reference
├── launchd/             # macOS LaunchAgent scripts
├── logs/                # Runtime logs
├── memory.db            # SQLite: soul_memory, user_models, working_memory
└── sessions.db          # SQLite: session_id mappings

scripts/
├── slack_check.py       # Session Bridge: read/ack inbox messages
├── slack_inbox_hook.py  # Session Bridge: UserPromptSubmit auto-check hook
├── slack_format.py      # Soul formatter: perception/extract/instructions (Open Souls paradigm)
├── slack_post.py        # Post messages to channels/threads
├── slack_read.py        # Read channel history or threads
├── slack_delete.py      # Delete messages (single, batch, thread cleanup)
├── slack_search.py      # Search messages, files, channels, users (RTS + legacy)
├── slack_stream.py      # Stream messages in real-time via chat streaming API
├── slack_react.py       # Add/remove reactions
├── slack_upload.py      # Upload files or snippets
├── slack_memory.py      # CLI wrapper for three-tier memory system
├── slack_app_home.py    # Build + publish App Home tab via Block Kit
├── slack_channels.py    # List/join channels
├── slack_users.py       # Look up users
└── _slack_utils.py      # Shared auth, rate limiting, API calls

---

参考索引

参考文档	内容
references/session-bridge.md	Session Bridge：安装、架构、收件箱格式、使用工作流、灵魂格式化器、故障排查
references/unified-launcher-architecture.md	统一启动器：安装、架构、按频道划分的会话、SDK 集成、数据流、线程模型
references/daemon-architecture.md	灵魂引擎认知步骤、记忆层级、XML 格式、App Home、Soul Monitor TUI
references/scripts-reference.md	全部 8 个脚本的完整文档、测试套件、常见工作流
references/onboarding-guide.md	用户模型访谈、CLAUDE.md 生成、导出命令
references/rate-limits.md	Slack API 速率限制级别和处理策略

资源

• assets/app-icon.png — 用于机器人配置的 Slack 应用图标