slack-output-format

name	slack-output-format
description	Slack 频道结构化输出规范 + Web API 写法——标题主消息、Block Kit thread、6 档 markdown、跨调用 anchor、curl/token/读写消息命令。Use when 准备向非 DM 频道推送 cron 报告/审批卡/反思/周报/持仓/书签/调研，或需要用 Slack API 读写消息、管理 thread、发送 Block Kit/attachment、更新并回读验证。

Slack 输出格式规范

所有向 Slack 频道（非 DM、非 thread 内回复）推送的结构化内容统一采用「标题主消息 + Block Kit thread」两步走。Slack Web API 主要通过 curl + Bot token 调用；token 存在 ~/Orb/.env，不要直接 source ~/Orb/.env，而是单独提取变量。

When to Use

• 准备向非 DM 频道推送 cron 报告、审批卡片、反思、周报、持仓、书签、调研等结构化内容
• 需要设计 Slack 主消息、thread Block Kit、markdown 层级或跨调用 thread 聚合
• 需要用 Slack Web API 读写消息、管理 thread、发送 Block Kit / attachment、更新或回读消息

频道主消息（1 条，text only）

格式：{emoji} {任务名} MM/DD｜{一句话总结}

• emoji 选取按任务性质：🪞 反思、📈 持仓、📋 汇总、🔭 周报、📚 书签、🧘 冥想、🔀 路由、🔍 调研
• 一句话总结必须有信息量（核心发现 / 关键数据），不能是"完成"/"成功"
• 示例：🪞 夜间反思 04/15｜8 条要点｜知识提取见 thread
• 主消息禁用 markdown 标题（# 留给 thread reply）
• 主消息 text 段 ≤ 300 字（Slack 通知预览截断点）。超出的内容必须放 thread。

Thread 正文（Block Kit）

结构：

header  : "{任务名} MM/DD"
section : "• 概况数据（窗口 / 会话数 / 消息数 / 标的数 等）"
divider
section : "## :emoji: 段标题
正文..."
divider
section : "## :emoji: 段标题
正文..."
divider

规则：

• 第 1 block 必须是 header 类型
• 每个正文 section 用 ## :emoji: 标题 + 换行 + 正文（adapter 自动转成 *xxx* 独立行 + 上空行）
• 段与段之间用 divider 分隔
• 风格：短句、高密度、可扫读
• 不要文档感，不要长段落

语义 → markdown 对照表（核心）

完整 6 档映射见 ~/Orb/profiles/<your-profile>/workspace/CLAUDE.md § Slack 输出格式。这里只列 cron / 反思类高频用法：

需要的视觉	写	渲染成
段标题	## :emoji: 标题	*:emoji: 标题* 独立行
子段	### 子段	*子段* 独立行
备注 / metadata	#### 备注	_备注_ 独立行
句内重点	**关键词**（一段 ≤1 个）	*关键词* 行内
数字 / ID / 路径 / 命令	`xxx`	灰底
弱强调 / 引用 / 术语	*xxx*	_xxx_ 行内

铁律：

• 段标题写 ## :emoji: 标题，禁止直接写 *标题* 充当段标题
• 一段最多一个 **bold**；多了改用 `code` / 「中文引号」 / emoji 前缀（▸ → ✅）替代

小字（italic / context 灰字）使用频次

目标：把正常字号的信噪比拉高。Karry 一眼能 grep 到「需要回应的部分」，辅助信息全沉到小字。

默认走小字（*xxx* → 渲染成 _xxx_ italic；多行可用 context block）：

• 来源标注：_来源：plaud bc4b8b1d / canon L1 / commit ce0fe16_
• 时间戳 / 路径 / 文件名（非链接的）：_2026-05-14 08:34 JST_ / _src/adapters/slack-format.js:601_
• 工具 / API 副作用回执：_freee PUT 200 · receipt 关联完成_
• 推理链 / 思考路径（「我先 X 再 Y」类的过程交代）
• 备选方案 / Plan B / 可选项的展开
• 兜底说明 / 「如需展开说一声」
• cron 身份戳 / window 元数据
• 引用片段 / 节录原文（Karry 已经知道是引用的）

正常字号留给（信号位）：

• 结论 / 判断 / 推荐
• 下一步动作 / 待 Karry 决策
• 反问 / AskUserQuestion 之外的关键追问
• 风险 / 警告 / 失败原因
• 改动结果 ≤ 2 行的核心摘要

禁忌：

• 任何「写完就行」的回执（diff、日记、scratchpad）→ 完全静默，不写小字（runtime 已关掉 dailyNotes/diff context 自动注入，2026-05-14）
• 一条消息 ≥ 3 段连续灰字 → 折叠合并为一段，或干脆删掉
• 结论藏小字 = 没说

Slack API 写法

1. 提取 token

SLACK_BOT_TOKEN=$(grep -E '^SLACK_BOT_TOKEN=' ~/Orb/.env | head -1 | cut -d= -f2- | tr -d "'" '"')

2. 发最小消息

curl -s "https://slack.com/api/chat.postMessage" \
  -d "channel=C01ABC123" \
  -d "text=Hello, Slack!" \
  -H "Authorization: Bearer $SLACK_BOT_TOKEN"

发 thread reply、update、delete、schedule、unfurl 时同样使用 Bot token 和对应 Web API。发完消息后，优先用 conversations.replies 或 conversations.history 回读验证，不要只看 ok=true。

3. 读取一个 Thread

curl -s "https://slack.com/api/conversations.replies" \
  -d "channel=C01ABC123" \
  -d "ts=1775307969.013919" \
  -H "Authorization: Bearer $SLACK_BOT_TOKEN"

4. 列频道

curl -s "https://slack.com/api/conversations.list" \
  -d "limit=200" \
  -d "types=public_channel,private_channel" \
  -H "Authorization: Bearer $SLACK_BOT_TOKEN"

5. 查用户

curl -s "https://slack.com/api/users.info" \
  -d "user=U01ABC123" \
  -H "Authorization: Bearer $SLACK_BOT_TOKEN"

6. 添加 Reaction（任务完成 / 确认标记）

curl -s https://slack.com/api/reactions.add \
  -d "channel=C01ABC123" \
  -d "timestamp=1775308000.100001" \
  -d "name=white_check_mark" \
  -H "Authorization: Bearer $SLACK_BOT_TOKEN"

name = 不带冒号的 emoji slug（thumbsup / white_check_mark / eyes / x）。需要 Bot scope reactions:write。

收到用户附件时的处理

Orb adapter 对不同文件类型的处理结果：

文件类型	agent 拿到	应对方式
.txt / .md / .json / .py 等文本类	--- 文件: xxx ---\n内容\n--- EOF --- 注入 prompt	直读，正常响应
图片（.png / .jpg / .gif 等）	imagePaths，作为多模态 image block	直接视觉分析
PDF	[附件: xxx (application/pdf, N bytes)]	调 pdf skill：pymupdf 提取文本
docx	[附件: xxx (application/vnd.openxmlformats..., N bytes)]	调 ocr-and-documents skill：python-docx
xlsx / csv	[附件: xxx (application/vnd.openxmlformats..., N bytes)]	调 xlsx skill：openpyxl / pandas
超 100KB 文本	[附件: xxx — 超出大小限制]	告知用户文件过大，建议拆分或提供关键片段

铁律：收到 [附件: xxx] 格式提示时，不能沉默——必须明确告知用户「已收到文件，正在用工具提取内容」，并主动调对应 skill，不要假装没看见或只输出文件名。

跨调用 Anchor 持久化

触发场景：同一类项目在一天内会被多次产出（new seed、bookmark 卡、cron 推送等），但希望它们聚合到同一个 main thread（首条创建、后续作为 thread reply 追加），跨日自动轮换到新 thread。

反例（踩过的坑）：依赖运行时猜测「今天有没有发过」——拉 conversations.history、对比时间戳、按文本匹配——任意一个都不可靠（频道有别人消息、time skew、文案变动），最终散成多个 main thread。已知案例：seeds_importers.py 早期实现散发，2026-04-27 才补 data/seeds-daily-anchor.json 闭环。

正解：把 anchor 持久化为显式 JSON 状态文件。

文件位置：~/Orb/profiles/<your-profile>/data/<task>-daily-anchor.json

最小 schema：

{
  "date": "2026-04-28",
  "channel": "C0123456789",
  "main_ts": "1777306842.573899"
}

调用流程（每次要发新内容时）：

1. 读 anchor JSON，比对 date 字段：
   • 与今天（JST）一致 + channel 匹配 → 复用 main_ts 作为 thread_ts，发 thread reply
   • 不一致（跨日 / 切频道） → 走步骤 2
2. chat.postMessage 发 main 消息 → 拿到新 ts
3. 覆盖 anchor JSON：{"date":"<today JST>","channel":"<C…>","main_ts":"<新 ts>"}
4. 当天后续投递回到步骤 1

铁律：

• anchor 文件名必须含 <task>- 前缀，避免不同任务串台
• 跨日判定用 JST 日历日（TZ=Asia/Tokyo date +%Y-%m-%d），不要用 UTC
• 写 anchor 必须先发消息拿到 ts、再写文件，反过来会留下坏 anchor 指向不存在的 ts
• 不要靠扫频道历史「猜」今天是不是已经发过——历史会被别人插话污染

适用任务清单（已用 / 待补）：

• ✅ seeds_importers.py（new seed 当日聚合 → seeds-daily-anchor.json）
• ⏳ bookmark 卡片（如果想要当天书签都进同一个 thread）
• ⏳ cron 报告（多个 cron 想共享日级 anchor 时）

Assistant Thread / Stream API（只读参考，不要直接调）

以下 API 归 Orb adapter/scheduler 独占管理，外部脚本和 agent 不要直接调用，否则会踩 message_not_owned_by_app / message_not_in_streaming_state：

API	归属	说明
assistant.threads.setStatus	adapter	显示 "Cooking…" / 工具名等气泡，turn 期间自动刷新（每 20s re-arm）
assistant.threads.setTitle	adapter	设置 assistant thread 标题
assistant.threads.setSuggestedPrompts	adapter	设置建议提示词
chat.startStream	scheduler	启动 task card timeline stream
chat.appendStream	scheduler	向 stream 追加 task_update chunks
chat.stopStream	scheduler	关闭 stream 并写入最终 markdown/blocks

handler 脚本（profiles/<your-profile>/scripts/handlers/）收到 block_action 回调后用 chat.update 更新审批卡，不要尝试用 stream API 改 bot 发的消息——stream 所有权归 daemon，handler 拿不到。

Stream chunks 双发陷阱（写 stream renderer / 改 stopStream 前必读）

Slack stream 的 task_update.details 对同一个 id 的 chunk 会跨 appendStream concat 累积——这是官方未明文但实测稳定的行为。

事故签名：finalize 后文本重复，例如 Distilled from N probesDistilled from N probes。

根因：result/finalize 路径先 appendStream(chunks) 再 stopStream({ chunks }) 发送同一批 final chunks，Slack 把 details 又拼了一次。

正确姿势：

• 实时增量只通过 appendStream 发 delta
• result/finalize 只调用 stopStream({ chunks: lastChunks })——不在 stop 前再 append 同一批
• catch / fallback / abnormal exit 路径也别补发 final chunks

审查 stream renderer 时盯这几条路径：

• cc_event result
• abnormal exit finalize
• deferred stream stop
• 任何 catch/fallback 里补发 final chunks 的逻辑

参考 lesson：profiles/<your-profile>/data/lessons/slack-stream-stopstream-chunks-pitfall.md

Reference 索引

命令语法、URL→ts 转换、reactions.add、文件上传 v2（getUploadURLExternal）、chat.getPermalink、频道/用户查询、cursor 分页、常见报错全集，见 skill slack-cli-api-reference（搜索关键词 invalid_blocks / reactions.add / getUploadURLExternal / chat.getPermalink / conversations.replies 时自动触发）。

Gotchas

• 默认优先 top-level blocks，只有明确需要色条时才用 attachments。
• 长内容优先拆成多条 thread reply，不要把风险压在一条超长消息上。
• 用户反馈"没发全"时，先回读 Slack 实际落地结果，再决定补发或更新。
• 跨调用聚合发布必须用磁盘 anchor，禁止靠运行时猜测。
• 收到 [附件: xxx (mime, size)] 时必须主动调对应 skill 提取内容，不能忽略或只输出文件名。
• 遇到 invalid_blocks、只剩首行、空壳消息、source ~/Orb/.env 失败等问题，查 slack-cli-api-reference skill。