Servosity/zammad

Zammad - Claude Code 技能

先决条件：安装 CLI

该技能驱动 zammad-cli 二进制文件。在从该技能调用任何命令之前，必须验证 CLI 是否已安装。 如果缺失，请先安装：

1. macOS / Linux：

   bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/zammad/install.sh)
   

2. Windows (PowerShell)：

   iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/zammad/install.ps1 | iex
   

3. 验证：zammad-cli --version
4. 确保 ~/.local/bin (macOS / Linux) 或 %LOCALAPPDATA%\Programs\msp-skills (Windows) 位于 $PATH 中。

安装程序会将 zammad-cli 和 zammad-mcp 二进制文件下载到 ~/.local/bin (macOS / Linux) 或 %LOCALAPPDATA%\Programs\msp-skills (Windows)。它不会 向您的 agent 注册该技能，也不会写入 MCP 客户端配置 - 请参阅 mcp-install.md 了解相关连接设置。

如果安装后 --version 报告“command not found”，则表示运行时无法在 $PATH 上找到二进制文件目录。在验证成功之前，不要继续执行任何技能命令。

一个单一的 Go 二进制文件涵盖了整个 Zammad REST + 知识库表面，并带有一个离线 SQLite 存储、结构化的 --json/--select 输出，以及针对所有写操作的 --dry-run。除了功能对等外，它还增加了一个根据您的同步工单计算得出的团队管理层：agent-load 和 agent-trend 用于工作负载，customer-health 和 churn-risk 用于账户风险，overdue 用于积压老化，escalate 用于情绪分类，以及 feedback 用于挖掘客户的需求。适用于任何 Zammad 实例 - 只需设置您的实例 URL 和令牌。

何时使用此 CLI

当 agent 需要读取、搜索或分类 Zammad 工单和知识库内容，或回答团队管理问题时使用此 CLI - 谁负载过重、哪些客户有风险、哪些工单存在时间过长、哪些客户听起来可能流失、哪些反馈主题反复出现。它非常适合支持运维自动化、每日站会和账户健康审查，这些场景的答案需要跨多个工单进行汇总。

反触发条件

不要将此 CLI 用于：

• 不要使用此 CLI 发送面向客户的营销邮件 - 它管理的是工单文章，而非营销活动。
• 不要使用它来配置 Zammad 触发器、自动化、SLA 或渠道 - 这些是管理控制台功能，此处不公开。
• 不要依赖 escalate/churn/feedback 作为权威情绪分析 - 它们是启发式关键词分类，用于为人类或 agent 提供需要判断的信号。

独特功能

团队管理

• agent-load - 查看每个坐席当前按状态（打开/待处理/积压）划分的工单负载，以便在问题堆积前平衡工作。

  当被问及谁负载过重或支持团队当前工作如何分布时使用此命令。

  zammad-cli agent-load --json
  

• agent-trend - 显示过去 N 周内每个坐席的队列是增长还是缩减，附有打开与关闭的差异。

  当被问及团队随时间推移是否跟上工作进度或落后时使用此命令。

  zammad-cli agent-trend --weeks 2 --json
  

• customer-health - 根据由打开数量、最老打开工单时长、重新打开率、处理速度和最后活动构建的健康信号对组织进行排名。

  使用此命令可在客户抱怨前发现哪些客户遇到问题。

  zammad-cli customer-health --at-risk --json
  

• overdue - 查找仍处于新建/打开/待处理状态且超过阈值的过期工单，按优先级加权，使最严重的工单排在前面。

  使用此命令可捕获即将违反 SLA 或变得陈旧的工单。

  zammad-cli overdue --days 3 --json
  

• escalate - 呈现最近客户消息看起来不满的活跃工单（启发式负面信号扫描），按命中次数、工单年龄和优先级排序 - 并显示匹配的片段。

  使用此命令可查找听起来愤怒并应升级的客户；这是带有片段的关键词分类，因此最终判断由您做出。

  zammad-cli escalate --json
  

• churn-risk - 根据打开的积压、逾期工单、未回复的待处理工单以及客户负面情绪消息，对每个组织的流失风险进行评分，并列出来自贡献因素。

  使用此命令可提前应对流失；它会列出因素供您判断和采取行动。

  zammad-cli churn-risk --json
  

• feedback-scan - 将工单和文章文本分类为功能请求、定价、合规性和错误主题，并附上来源工单引用和片段。

  使用此命令可挖掘客户在功能、定价和合规方面持续要求的内容。

  zammad-cli feedback-scan --bucket pricing --json
  

知识库

• kb browse - 将从初始化包解析的知识库打印为类别/答案树。

  在阅读或搜索答案前查看知识库结构时使用此命令。

  zammad-cli kb browse
  

• kb search - 对来自实时知识库初始化包的答案标题和正文进行文本搜索。

  通过关键词查找正确的知识库答案时使用此命令。

  zammad-cli kb search "restore" --json
  

• kb get - 从初始化包解析知识库答案 ID 到其完整的翻译后正文。

  阅读知识库答案完整内容时使用此命令。

  zammad-cli kb get 42
  

工单便捷操作

• ticket note - 一行内为工单添加内部或合作伙伴可见的备注，具有正确的内容类型默认值。

  在不手动构建文章负载的情况下记录工单工作时使用此命令。

  zammad-cli ticket note 12345 --body "Investigated, awaiting logs" --internal --dry-run
  

Webhook（无需轮询）

Zammad 可以在创建或更新工单或添加文章时调用此机器，因此无需轮询。

# 一次性，使用具有 admin.webhook 和 admin.trigger 权限的令牌
zammad-cli webhooks register --endpoint http://127.0.0.1:8789/zammad --yes
# 在 Zammad 发布到的机器上保持运行
zammad-cli webhooks listen
# 读取到达的事件；将返回的游标作为 --since 传递到下一次
zammad-cli events list --since 0 --json

• register 为每个事件（zammad.ticket.created、zammad.ticket.updated、zammad.article.created）创建一个 Zammad webhook 和一个触发器。它会生成签名密钥并将其存储在您的 API 令牌旁边，仅您可读；ZAMMAD_WEBHOOK_SECRET 可覆盖它。密钥永远不会被打印：webhooks status 仅显示其来源。
• listen 默认仅绑定到本机（127.0.0.1，端口 8789），并且没有密钥则拒绝启动。每个请求必须携带 Zammad 的 X-Hub-Signature，在读取正文之前进行检查；已经处理过的投递将被丢弃，超过 1 MiB 的正文将被拒绝。
• Webhook 仅携带 ID。监听器通过 API 获取工单并记录事件，因此客户文本永远不会在 webhook 中传输。
• Zammad 在大约两分钟内最多尝试五次投递后放弃。每次 listen 启动时，它首先记录其离线期间发生的变化。当 listen 正在运行时，Zammad 因网络中断而无法到达的投递将不会被记录。
• Zammad 必须能够访问监听器。与 Zammad 部署在同一服务器上的自托管 Zammad 可使用默认配置。局域网内另一台机器上的 Zammad 需要 listen --addr <lan-ip>:8789 --tls-cert <file> --tls-key <file> 和一个 https:// 端点。Zammad Cloud 实例无法访问您局域网内的机器。
• 当用户想对新创建或更改的工单做出反应时使用此功能。使用 events list --since <cursor> 读取事件并保留返回的游标；使用 tickets get <id> 获取工单的文本。
• 在 MCP 中，events_list 读取记录的事件（只读，不调用 Zammad）。webhooks_register 和 webhooks_unregister 仅在 confirm: true 时更改 Zammad。listen 是 CLI 专用的。

命令参考

articles - 读取和添加工单文章（备注和邮件）

• zammad-cli articles by-ticket - 列出一个工单的所有文章
• zammad-cli articles create - 向工单添加一篇文章（备注或邮件）
• zammad-cli articles get - 按 ID 获取单篇文章

groups - 工单路由分组

• zammad-cli groups get - 按 ID 获取一个分组
• zammad-cli groups list - 列出所有分组

kb - 知识库类别和答案

• zammad-cli kb answer-create - 创建知识库答案。将 translations_attributes 作为 JSON 传递，然后发布或标记为内部。
• zammad-cli kb answer-delete - 删除知识库答案（需要知识库编辑者权限）
• zammad-cli kb answer-internal - 将知识库答案标记为内部（仅限坐席）
• zammad-cli kb answer-publish - 发布知识库答案（使其公开）
• zammad-cli kb category-create - 创建知识库类别。将 translations_attributes 作为 JSON 传递。
• zammad-cli kb init - 获取完整的知识库包（类别、答案、翻译）。由 'kb browse/search/get' 使用。

organizations - 读取和管理组织（客户/合作伙伴）

• zammad-cli organizations create - 创建一个组织
• zammad-cli organizations get - 按 ID 获取一个组织
• zammad-cli organizations list - 列出组织（分页）
• zammad-cli organizations search - 按名称或自定义字段搜索组织
• zammad-cli organizations update - 更新一个组织

overviews - 坐席工单概览（已保存的视图）

• zammad-cli overviews get - 按 ID 获取一个概览（及其工单）
• zammad-cli overviews list - 列出所有概览

priorities - 工单优先级参考（ID -> 名称映射）

• zammad-cli priorities - 列开工单优先级

states - 工单状态参考（ID -> 名称映射）

• zammad-cli states - 列开工单状态

tags - 工单标签

• zammad-cli tags add - 向一个对象添加标签
• zammad-cli tags all - 列出实例中定义的每个标签（词汇表）
• zammad-cli tags list - 列出一个对象上的标签（默认为一个工单）
• zammad-cli tags remove - 从一个对象移除标签

tickets - 读取、搜索、创建和更改 Zammad 工单

• zammad-cli tickets create - 创建一个工单。提供标题、分组、客户和初始文章。
• zammad-cli tickets delete - 永久删除一个工单（需要管理员/删除权限）
• zammad-cli tickets get - 按 ID 获取一个工单
• zammad-cli tickets list - 列出工单（分页）
• zammad-cli tickets search - 使用 Zammad 查询语法搜索工单（例如 'state:open owner_id:3'）
• zammad-cli tickets update - 更新一个工单（状态、优先级、负责人、标题、组织）

users - 读取和管理用户（坐席和客户）

• zammad-cli users create - 创建一个用户
• zammad-cli users get - 按 ID 获取一个用户
• zammad-cli users list - 列出用户（分页）
• zammad-cli users me - 获取已验证用户（身份验证自检）
• zammad-cli users search - 按电子邮件、名称或查询（例如 organization_id:5）搜索用户
• zammad-cli users update - 更新一个用户

agent-load

• zammad-cli agent-load - 查看每个坐席当前按状态（打开/待处理/积压）划分的工单负载，以便在问题堆积前平衡工作。

agent-trend

• zammad-cli agent-trend - 显示过去 N 周内每个坐席的队列是增长还是缩减，附有打开与关闭的差异。

churn-risk

• zammad-cli churn-risk - 根据打开的积压、逾期工单、未回复的待处理工单以及客户负面情绪消息，对每个组织的流失风险进行评分，并列出来自贡献因素。

customer-health

• zammad-cli customer-health - 根据由打开数量、最老打开工单时长、重新打开率、处理速度和最后活动构建的健康信号对组织进行排名。

escalate

• zammad-cli escalate - 呈现活跃工单，其最近的客户消息看起来不满（启发式负面信号扫描），按命中次数、工单年龄和优先级排序 - 并显示匹配的片段。

feedback-scan

• zammad-cli feedback-scan - 将工单和文章文本分类为功能请求、定价、合规性和错误主题，并附上来源工单引用和片段。

kb

• zammad-cli kb browse - 将从初始化包解析的知识库打印为类别/答案树。

• zammad-cli kb search - 对来自实时知识库初始化包的答案标题和正文进行文本搜索。

• zammad-cli kb get - 从初始化包解析知识库答案 ID 到其完整的翻译后正文。

events

• zammad-cli events list - 列出 webhooks listen 在游标之后记录的 Zammad 事件，从最旧到最新排序（本地，不调用 Zammad）。

webhooks

• zammad-cli webhooks register - 创建用于调用 webhooks listen 的 Zammad webhook 和触发器（仅在添加 --yes 时写入）。
• zammad-cli webhooks listen - 接收、验证并记录 Zammad webhook，直到停止（仅限 CLI）。
• zammad-cli webhooks status - 显示已注册的 webhook 和触发器以及密钥的来源（从不显示密钥本身）。
• zammad-cli webhooks unregister - 移除 webhooks register 创建的内容（仅在添加 --yes 时写入）。

overdue

• zammad-cli overdue - 查找仍处于新建/打开/待处理状态且超过阈值的过期工单，按优先级加权，使最严重的工单排在前面。

ticket

• zammad-cli ticket note - 一行内为工单添加内部或合作伙伴可见的备注，具有正确的内容类型默认值。

查找正确的命令

当您知道想做什么但不知道该用哪个命令时，可以直接询问 CLI：

zammad-cli which "<用您自己的话描述的功能>"

which 将自然语言功能查询解析为此 CLI 精选功能索引中最佳匹配的命令。退出码 0 表示至少有一个匹配；退出码 2 表示没有找到匹配。