Skip to content

Latest commit

 

History

History
227 lines (162 loc) · 4.49 KB

CARD_TEMPLATE_OPTIONAL.md

File metadata and controls

227 lines (162 loc) · 4.49 KB

卡片模板配置说明

概述

ZenOps 的钉钉集成支持两种消息模式:

  1. 流式卡片模式: 需要配置卡片模板ID,提供更好的交互体验
  2. 传统文本模式: 无需配置卡片模板,使用Markdown文本消息(默认模式)

系统会自动检测配置并选择合适的模式,如果卡片创建失败会自动降级为文本模式。

不配置卡片模板(推荐新手)

配置示例

dingtalk:
  enabled: true
  mode: "stream"
  app_key: "你的AppKey"
  app_secret: "你的AppSecret"
  agent_id: "你的AgentID"

  # 不配置卡片模板
  card_template_id: ""
  enable_stream_card: false

优点

  • ✅ 配置简单,无需额外设置
  • ✅ 立即可用,无需创建卡片模板
  • ✅ 稳定可靠,不依赖卡片API

缺点

  • ⚠️ 无法实时流式更新
  • ⚠️ 消息样式较简单

消息示例

🔍 正在查询阿里云 ECS,请稍候...

✅ 阿里云 ECS 查询完成

[查询结果]

配置卡片模板(推荐进阶用户)

步骤 1: 创建卡片模板

  1. 登录 钉钉开放平台
  2. 进入你的应用
  3. 选择 "互动卡片" -> "创建卡片模板"
  4. 选择 "AI流式卡片" 类型

步骤 2: 配置卡片内容

创建一个简单的卡片模板:

{
  "config": {
    "autoLayout": true,
    "enableForward": true
  },
  "header": {
    "title": {
      "type": "text",
      "text": "ZenOps 查询助手"
    },
    "logo": "@lALPDfJ6V_FPDmvNAfTNAfQ"
  },
  "contents": [
    {
      "type": "markdown",
      "text": "{{content}}",
      "id": "markdown_content"
    }
  ]
}

关键点:

  • 必须包含一个名为 content 的变量(通过 {{content}} 引用)
  • 卡片类型选择支持流式更新

步骤 3: 获取模板ID

创建完成后,复制模板ID(格式类似: xxx.schema)

步骤 4: 更新配置

dingtalk:
  enabled: true
  mode: "stream"
  app_key: "你的AppKey"
  app_secret: "你的AppSecret"
  agent_id: "你的AgentID"

  # 配置卡片模板ID
  card_template_id: "你的模板ID.schema"
  enable_stream_card: true

步骤 5: 重启服务

./bin/zenops

优点

  • ✅ 实时流式更新,体验更好
  • ✅ 支持更丰富的样式
  • ✅ 支持进度展示

缺点

  • ⚠️ 需要额外配置
  • ⚠️ 依赖钉钉卡片API稳定性

消息示例

[实时更新的卡片]
查询阿里云 ECS

⏳ 正在查询阿里云 ECS...
↓
✅ 阿里云 ECS 查询完成

[查询结果逐字流式显示]

自动降级机制

系统具有完善的降级机制:

  1. 卡片模板ID未配置 -> 直接使用文本模式
  2. 卡片创建失败 -> 自动降级为文本模式
  3. 卡片更新失败 -> 记录警告,继续执行

无论哪种情况,都不会影响功能的正常使用。

常见问题

Q: 不配置卡片模板能用吗?

A: 可以!默认使用文本模式,功能完全正常。

Q: 如何知道当前使用的是哪种模式?

A: 查看日志:

  • Card template not configured, using text reply - 文本模式
  • Creating stream card - 卡片模式

Q: 卡片创建失败怎么办?

A: 不用担心,系统会自动降级为文本模式,并在日志中提示:

Failed to create card, fallback to text reply

Q: 文本模式和卡片模式可以动态切换吗?

A: 可以!修改配置后重启服务即可。

Q: 推荐使用哪种模式?

A:

  • 新手: 推荐文本模式,简单可靠
  • 进阶: 推荐卡片模式,体验更好

日志说明

文本模式日志

Card template not configured, using text reply
Sent text reply successfully

卡片模式日志

Creating stream card
Card created successfully
Streaming update: 0/1000 chars
Streaming update: finalized

降级日志

Failed to create card, fallback to text reply
Sent text reply successfully

配置建议

开发测试阶段

dingtalk:
  card_template_id: ""        # 不配置,使用文本模式
  enable_stream_card: false

理由: 配置简单,快速验证功能

生产环境

dingtalk:
  card_template_id: "xxx.schema"  # 配置卡片模板
  enable_stream_card: true

理由: 提供更好的用户体验

总结

  • 📌 卡片模板不是必需的,不配置也能正常使用
  • 📌 系统会自动检测配置并选择合适的模式
  • 📌 自动降级机制保证系统稳定性
  • 📌 可以根据需求随时切换模式

建议先使用文本模式验证功能,确认无误后再考虑配置卡片模板。