AI Agent 实战：用飞书任务卡片让后台任务「可见」

AI Agent 实战：用飞书任务卡片让后台任务"可见"

背景：AI 在干什么，你知道吗？

当 AI Agent 开始处理复杂任务时，你盯着对话框等待——它在干什么？进展如何？卡住了还是还在跑？

这是 AI Agent 落地的一个真实痛点：任务不透明。

我在构建自己的 AI 助手系统（基于 OpenClaw）时，遇到了这个问题。特别是把任务拆给多个 subagent 并行处理时，主 agent 在等、我也在等，整个过程像个黑盒。

feishu-task-card 就是我为了解决这个问题做的工具——让 AI 在执行多步骤任务时，实时向飞书推送进度卡片，全程可见。

工具介绍

feishu-task-card 是一个命令行工具，核心能力：

• 创建进度卡片：任务开始时发一张卡片到飞书，列出所有步骤
• 实时更新进度：每个步骤完成/失败时更新卡片状态
• 完成标记：任务结束时汇总结果，自动取消置顶

卡片状态用颜色直观表示：

快速上手

安装

# 脚本路径（OpenClaw workspace）
/Users/arvin/.openclaw/workspace/task_card/task_card.py

# 依赖
pip install requests

三个核心命令

1. 创建卡片

MSG=$(python3 task_card.py create "部署后端服务" \\
'[{"name":"拉取代码"},{"name":"构建镜像"},{"name":"推送到仓库"},{"name":"重启服务"}]' \\
–user-id ou_39f130f8fa1b499c91dee8bdb1eff90a \\
–goal "将最新代码部署到生产环境" \\
–source "CI/CD" \\
–updater "Jarvis" \\
–priority P1 \\
–tags "部署,生产" \\
–pin)

echo "卡片ID: $MSG"

执行后飞书会收到一张灰色卡片，列出4个待完成步骤，并自动置顶。

2. 更新进度

# 步骤0完成，步骤1进行中
python3 task_card.py update $MSG '[0]' \\
–in-progress '[1]' \\
–details "代码已拉取，开始构建 Docker 镜像…"

# 步骤1完成，步骤2进行中
python3 task_card.py update $MSG '[0,1]' \\
–in-progress '[2]' \\
–details "镜像构建成功（3m42s），正在推送到 registry…"

# 某步骤失败
python3 task_card.py update $MSG '[0,1]' \\
–failed '[2]' \\
–details "推送失败：registry 连接超时，正在重试…"

3. 完成任务

python3 task_card.py done $MSG \\
"部署完成。服务版本 v2.3.1，健康检查通过，响应时间 42ms。"

完整示例：AI Agent 多步骤任务追踪

这是我实际使用的场景——AI 处理"发布技术文章到 CSDN"这个任务：

#!/bin/bash

# 1. 任务开始，创建卡片
MSG=$(python3 task_card.py create "发布文章到CSDN" \\
'[{"name":"收集素材"},{"name":"撰写文章"},{"name":"发布到CSDN"}]' \\
–user-id ou_39f130f8fa1b499c91dee8bdb1eff90a \\
–goal "把飞书任务卡片工具的使用方法写成技术文章并发布" \\
–priority P2 \\
–pin)

# 2. 步骤1：收集素材（派 subagent 并行处理）
python3 task_card.py update $MSG '[]' \\
–in-progress '[0]' \\
–details "正在读取 README 和 SKILL.md 提取素材…"

# … subagent 执行 …

python3 task_card.py update $MSG '[0]' \\
–in-progress '[1]' \\
–details "素材收集完成（README 238行 + SKILL.md 96行），开始撰写…"

# 3. 步骤2：撰写文章
# … 写作过程 …

python3 task_card.py update $MSG '[0,1]' \\
–in-progress '[2]' \\
–details "文章撰写完成（2100字），正在发布到 CSDN…"

# 4. 发布完成
python3 task_card.py done $MSG \\
"文章发布成功：https://blog.csdn.net/xxx/article/xxx"

飞书实时呈现整个流程，全程可追踪。

架构设计：主 Agent 是协调者

在多 agent 系统中，task_card 有一个重要的设计原则：

卡片由主 agent 创建和更新，worker 只执行和汇报。

用户
↓ 下达任务
主 Agent（Jarvis）
├── 创建 task_card（用户可见）
├── 拆分子任务
├── 派发给 worker1、worker2…（并行）
├── 收集 worker 汇报结果
└── 更新 task_card 进度
↓
飞书卡片（实时可见）

这样的好处：

最佳实践

1. –goal 写详细

# ❌ 不好
–goal "处理数据"

# ✅ 好
–goal "从 S3 下载昨日日志，过滤 ERROR 级别，生成日报发送到群组"

2. 用优先级 + Pin 管理注意力

# P0 紧急任务：立即置顶
–priority P0 –pin

# 普通任务：不置顶
–priority P2

3. –details 描述当前状态

每次 update 都写 –details，说明：当前在做什么、遇到什么、下一步是什么。这是卡片对观看者最有价值的信息。

4. 记好 msg_id

状态存在 /tmp/task_cards/，机器重启会丢失。长期任务建议把 msg_id 写入文件备份：

MSG=$(python3 task_card.py create ...)
echo $MSG > /tmp/current_task_id.txt

总结

feishu-task-card 解决的核心问题是：让 AI 的后台执行对人可见。

在 AI Agent 越来越复杂（多 agent 并行、长时间任务、跨系统调用）的今天，可观测性变得和功能本身一样重要。任务卡片是 AI 系统和人之间的一个简单但有效的可视化桥梁。

如果你也在构建 AI Agent 系统，不妨考虑给每个复杂任务配一张进度卡片——你的用户（和你自己）会感谢你的。

工具地址：基于 OpenClaw agent 框架，源码在 workspace/task_card/ 目录