slack - SKILL.md Agent Skill

name: slack description: >- Use when AI encounters Slack permalinks (https://*.slack.com/archives/...), Slack IDs (C.../U.../D.../F...), thread 讨论上下文, 搜索 Slack 历史消息, 按邮箱/handle 反查用户, 浏览频道最近动态, 下载 Slack 附件（截图/日志/CSV/PDF), 或需要把 @handle / #name / ^subteam 解析成 ID 时.

Slack Skill

只读 Slack Web API 的 9 个子命令封装，统一入口 scripts/slack.py。 不写消息 / 不加 reaction / 不 mark-read —— 这些动作由调用方 Bot 自己处理，client 层有硬编码白名单拦截。

When to Use

触发信号（AI 看到任一信号即考虑调用）：

https://*.slack.com/archives/... 链接
C[A-Z0-9]{8,} / U[A-Z0-9]{8,} / D[A-Z0-9]{8,} / F[A-Z0-9]{8,} 风格 ID
p123456789012345 风格的消息 ts
用户提到 "Slack" / "thread" / "频道" / "群里" / "@某人在 Slack 说"
Jira/PR 正文里的 Slack permalink（排查类任务需要 QA/RD 讨论上下文）

术语对照：

用户说法	含义
slack / 消息 / DM / 频道 / thread / permalink	本 skill
Slack URL `https://xxx.slack.com/archives/...`	`get` / `replies` / `files_download --url` 入参
`@handle` / `@name` / `#channel` / `^subteam`	`resolve` / `users` / `channels` 入参
`ts` / `thread_ts`	Slack 时间戳 ID（`1234567890.123456`）

Quick Reference

入口：

.agent-slack/skills/slack/scripts/slack.py

查找顺序：./.agent-slack/skills/slack/scripts/slack.py → <git-root>/.agent-slack/skills/slack/scripts/slack.py → <git-root>/slack/scripts/slack.py（仓库开发路径）→ find . -path '*skills/slack/scripts/slack.py'。

所有调用 = python3 <path> <subcommand> [flags]；禁止 import sk.* 绕过入口。

子命令表：

子命令	作用	典型入参
`get`	读单条消息	`--url <permalink>`
`replies`	读整个 thread	`--url <任一消息 permalink>`
`history`	浏览频道最近消息	`--channel <#name\|C...>` `--limit <n\|1d\|2h>`
`search`	全域搜消息（xoxp 专属）	`<query 字符串，原生 modifier>`
`files_download`	下附件	`--file-id F...` 或 `--url <permalink>`
`channels`	搜/列频道（走 cache）	`--query <name>` / `--type public`
`users`	查人（ID/email/name）	`--id U...` / `--email ...` / `--query <name>`
`resolve`	字符串 → 对象	`resolve "#eng"` / `"@alice"` / `"^oncall"` / `U.../C.../F.../email`
`cache_refresh`	刷本地 users/channels/subteams 字典	—

每条都支持 --help。大输出用 --output <file>（stdout 只打 saved: <path>）。

Setup

项	说明
Python	≥ 3.9
依赖	无（只用标准库 `urllib`，零 `pip install`）
配置	复制 `slack/.env.example` → `slack/.env`，至少填 `SLACK_BOT_TOKEN`

Token 路由（client 自动挑）：

操作	Token 优先级
除 `search` 外全部	`SLACK_BOT_TOKEN` → `SLACK_USER_TOKEN` → `SLACK_TOKEN`
`search`	`SLACK_USER_TOKEN` → `SLACK_TOKEN`（必须 xoxp，bot token 会被 Slack 拒）

Cache 自动刷新（Chunk 4）：channels / users --query / resolve "#name|@handle|^handle" 在 cache 不存在或 > TTL 时会同步刷一次；单条 lookup（users --id/--email、resolve U.../C.../email）走 live API，不触发刷新。消息类命令（get/replies/history/search）不会自动刷新，避免高频放大成全量 users.list。

Cache 环境变量：SLACK_SKILL_CACHE_TTL=<秒>（默认 3 天）、SLACK_SKILL_CACHE_NO_AUTO=1（关自动刷新）、SLACK_SKILL_CACHE_DIR=<path>（覆盖默认 $PWD/.agent-slack/cache/slack/）。

Recipes

所有响应形状：消息对象一律含 ts / author / text_raw（保留 <@U> <#C> 原始 token）/ text_rendered（@name #channel 还原，Block Kit 走 Markdown）/ blocks_rendered / files / reactions / raw（原始 payload）。二次处理用 text_raw，喂 AI/人读用 text_rendered。

读消息 / thread

# 单条
python3 slack/scripts/slack.py get --url "<permalink>"

# 整个 thread（permalink 任意一条即可）
python3 slack/scripts/slack.py replies --url "<permalink>" [--limit 20] [--output /tmp/t.json]

replies --limit 算的是 回复数，root 总是返回。

浏览频道

# 按条数
python3 slack/scripts/slack.py history --channel "#eng" --limit 20

# 按时间窗口（m/h/d/w）
python3 slack/scripts/slack.py history --channel "C08P..." --limit 1d

# 连 thread 回复一起抓（适合做"今天频道全景"）
python3 slack/scripts/slack.py history --channel "#eng" --limit 1d --include-thread-replies

--limit 两种语义：纯数字 = 条数；<n>{m|h|d|w} = 时间窗口（不限条数）。

查人 / 查频道 / 一键 resolve

python3 slack/scripts/slack.py channels --query release --sort popularity --limit 10
python3 slack/scripts/slack.py users --email alice@example.com
python3 slack/scripts/slack.py resolve "@alice"       # → user
python3 slack/scripts/slack.py resolve "#eng-release" # → channel
python3 slack/scripts/slack.py resolve "^oncall"      # → subteam
python3 slack/scripts/slack.py resolve U06GM8PAFEX    # → 直接 live lookup

resolve 返回 { kind: user|channel|subteam, resolved, candidates?, cache_refresh? }；拿到 id 再喂 history --channel <id> / replies --url ...。

全域搜索（xoxp 专属）

# query 原样透传给 Slack，原生 modifier 全可用
python3 slack/scripts/slack.py search "deploy in:#eng from:@alice after:2026-01-01" --limit 50
python3 slack/scripts/slack.py search "incident-4712" --sort timestamp --sort-dir asc --limit 200

--limit 跨页自动翻（--max-pages 默认 5，Slack 单页上限 100）。返回的 matches 同样走 render + preload_users。

下载附件

Slack 的 url_private 需要 Bearer token，AI 工具层没有 token → 不下载就看不见图/PDF/CSV。

# 读消息时顺便下（最常用）
python3 slack/scripts/slack.py get --url "<permalink>" --download-files [--types image,pdf]

# 只下单个文件
python3 slack/scripts/slack.py files_download --file-id F012ABC --types all --out /tmp/f/

每个 files[i] 会被填 local_path / download_category / download_status，顶层有 downloads: { total_files, downloaded, skipped, errored, files_dir }。

--types 类别：text（post/snippet/md/csv/log/源码后缀 py/js/ts/go/java/rb/json/yaml/sql …）、image、video、audio、pdf、archive、other、all。--download-files 默认走 SLACK_SKILL_DOWNLOAD_TYPES，缺省是 text（AI 上下文友好）。

幂等：文件名 {file_id}{ext}；再跑一次 → download_status: skipped:already_exists。想重下手动 rm。

Common Mistakes

命令层遇 Slack API 错会打 error: <method>: <code> | <detail> 到 stderr，已知 code 紧跟一行 hint: ...。

Slack error	含义	hint
`channel_not_found`	频道 ID/名不存在或 token 无权	`slack.py channels --query <name>` 找正确 id
`not_in_channel`	Bot 没加该私密频道	Slack 里 `/invite @your-bot`
`user_not_found`	用户不存在或 token 看不到	`slack.py users --query <name>` 或传完整 `U0...`
`not_allowed_token_type`	该接口只收 xoxp	`search` 必须配 `SLACK_USER_TOKEN`
`missing_scope`	scope 不足	对照 `.env.example` 补 scope → 重新 Install to Workspace
`invalid_auth` / `not_authed`	token 无效/过期/未配	检查 `.env`；xoxp 可能被 SSO 失效
`ratelimited`	速率限制	skill 已自动 Retry-After；仍超限说明并发过大
`message_not_found`	permalink 指向消息不存在/已删	thread 回复的 permalink 必须带 `?thread_ts=<root_ts>`；Slack UI 复制出来的天然就有，自己拼 URL 容易漏
`file_not_found`	file id 不存在或 token 看不到	用 `get`/`replies` 响应里的 `files[].id`（F 开头）
`thread_not_found`	该消息不是 thread 首帖 / 还没回复	改用 `get`；或传某条回复的 permalink

退出码：2 = token 缺失 / argparse 错；3 = 触发只读白名单（调用了非白名单方法）；4 = 参数非法（格式错 / channel 不在 SLACK_SKILL_ALLOWED_CHANNELS）；1 = 其他（含未识别的 Slack API error）。

Bearer token 永不出现在任何日志/错误信息（sk/files.py 走 redact()）。

NEVER

❌ 发消息 / 改 reaction / mark-read —— 属于调用方 Bot 的职责
❌ import sk.* 或绕过 slack.py 入口
❌ token 写进命令行 argv —— 放 .env 或 shell env
❌ 拿 text_rendered 做正则提数 —— 用 text_raw
❌ 对超长 thread / history --limit 1d / 批量 search 直接 stdout —— 用 --output <file>，否则 AI 上下文爆炸