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

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

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

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

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

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

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

工具介绍

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

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

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

状态	颜色	含义
0%	灰色	尚未开始
1-99%	黄色	进行中
100%	绿色	全部完成
有失败	红色	某步骤出错

快速上手

安装

bash 复制代码

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

# 依赖
pip install requests

三个核心命令

1. 创建卡片

bash 复制代码

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. 更新进度

bash 复制代码

# 步骤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. 完成任务

bash 复制代码

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

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

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

bash 复制代码

#!/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 进度
      ↓
    飞书卡片（实时可见）

这样的好处：

可见性集中：用户只看主 agent 的卡片，不被多个 worker 的输出淹没
主 agent 有评判权：worker 汇报 → 主 agent 判断成功/失败 → 再更新卡片
容错处理：某个 worker 失败，主 agent 可以标红该步骤并重试

最佳实践

1. --goal 写详细

bash 复制代码

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

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

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

bash 复制代码

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

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

3. --details 描述当前状态

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

4. 记好 msg_id

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

bash 复制代码

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/ 目录