IT工单管理

概述

IT 工单管理技能 1.1

装了这个技能 = 在飞书 / 钉钉 / 企业微信任意一个平台得到一套完整 IT 工单管理系统：事件（Incident）、服务请求（Service Request）、变更（Change）、问题（Problem）四类工单全生命周期（提交→分派→诊断→解决→关闭）、优先级×严重度矩阵、SLA 时效管理、知识库、经营看板。核心规格平台无关（§1–§5），平台落地看适配器（§0 索引 + §6/§8）。全部配方与坑位来自三平台真实生产环境的搭建与逐项对账实测。

0. 你能得到什么

• 完整 IT 工单表结构（§1）：工单主表、处理记录、SLA 时效、知识库、变更窗口、问题根因
• 工单状态机配方（§2）：事件/服务请求/变更/问题四类工单的完整生命周期与状态流转
• 优先级×严重度矩阵（§3）：P1-P4 优先级与 S1-S4 严重度的组合判定 SLA 时效
• 引擎坑位库（§6）：飞书 / 钉钉 / 企微三平台公式与工作流引擎的实测限制与绕法，价值最高的部分
• 演示数据与对账基准（§5）：待处理工单=12、处理中=8、已解决=45、SLA 达成率=92%

0.5 第 0 步：平台选择弹窗（先于一切操作，强制流程）

当本技能被触发、且用户消息中没有明确指定目标平台时，Agent 必须先调用 AskUserQuestion 工具弹出单选问题「你想在哪个平台搭建 IT 工单管理系统？」，提供三个选项及说明：

• 飞书 · 多维表格 —— 全流程脚本现成（§1–§5 + scripts/BUILD_WORKORDER.md 一键复建），适合已在用飞书的团队
• 钉钉 · AI 表格 —— 自带审批自动化：分派/解决/关闭卡片按钮、SLA 临期工作流（走 adapters/dingtalk/）
• 企业微信 · 智能表格 —— 公式引擎最强、API 写入最顺；无原生自动化，SLA 提醒用定时任务补偿（走 adapters/wecom/）

规则：

• 用户已明确平台，或消息中出现平台特征（飞书分享链接、dingtalk.com/alidocs 链接、doc.weixin.qq.com 链接）时跳过弹窗，直接路由
• 做出选择后只执行该平台流程；本文档其他平台的命令、字段格式、ID 一律不得混用（平台差异速查见 §8）
• 连接器检测：获取付费方案后、搭建前，必须先检测目标平台 CLI 可用性（§1.1）。不可用时引导用户到「设置 → 连接器」安装对应连接器，不得降级伪造、不得擅改到其他平台
• Base 自动创建：连接器可用后，通过 CLI 自动创建 Base（§1.2），不需要用户手动新建或提供 Base token

0.7 付费服务调用流程（Pay Skill）

本技能为付费技能（¥9.90/次），调用服务端获取定制化 IT 工单管理系统搭建方案前需完成微信支付。

透明披露：

• 服务端点：https://lanjingshuzi.cn/skillhub/it-workorder-management/api/v1/skill/invoke
• 端点运营主体：蓝鲸数字（lanjingshuzi.cn）
• 数据处理范围：请求体仅包含用户的搭建需求描述（平台类型、工单分类、是否需要 SLA 等），不含用户个人隐私数据
• 付费方式：微信支付（WeChat Pay）
• 在发起支付前，必须向用户明确告知本次调用将产生 ¥9.90 费用，并获得用户确认后才可继续

前置检查：当前智能体是否支持微信 AI 支付

发起下单前，先检查你的可用工具列表中是否存在名称包含 weixinpay_ 的工具（如 mcp__weixinpay__weixinpay_register，工具名带前缀也算；存在任意一个即视为支持）。

• 支持：向用户透明告知本技能为付费技能（¥9.90/次，微信支付），端点由蓝鲸数字（lanjingshuzi.cn）运营，继续本 Skill 的后续流程。
• 不支持：终止流程且不要发起下单。只向用户说明结论与解决办法（无需解释你如何检查、不要出现具体工具名），按智能体类型提示：
  • 合作智能体（如 WorkBuddy）：请升级智能体到最新版本后重试。
  • 开放智能体（如 OpenClaw / DeepSeek Harness）：请根据 https://skillhub.cn/install/skillhub.md，安装 @tencent-adm/weixinpay-installer。
  • 无法判断类型：请升级智能体或安装微信支付 AI 支付插件后重试。

工作流程

第一步：请求资源

POST https://lanjingshuzi.cn/skillhub/it-workorder-management/api/v1/skill/invoke
Content-Type: application/json

{
  "query": "用户的查询内容（如：帮我搭建一个 IT 服务台系统，需要 SLA 管理）",
  "platform": "feishu | dingtalk | wecom",
  "ticket_types": ["incident", "service_request"],
  "need_sla": true,
  "need_knowledge_base": true
}

第二步：处理 402 响应

服务端返回 HTTP 402，提取以下两个值并必须保存：

• Header WeixinPay-Required：支付码（payment_code）
• Header X-Out-Trade-No：订单号（out_trade_no）

响应体示例：

{
  "code": "PAYMENT_REQUIRED",
  "message": "需要支付后才能获取 IT 工单管理系统定制化搭建方案",
  "WeixinPay": {
    "WeixinPay-Required": "xY9zAbc123def456",
    "prompt": "本次使用微信支付，请将 WeixinPay-Required 的值作为 paymentCode 交给 weixinpay_pay，以向用户申请支付授权。"
  },
  "out_trade_no": "WX402_20260923120000abcdef123456",
  "amount": "9.90",
  "currency": "CNY"
}

第三步：发起支付（必须获得用户确认）

在调用支付前，必须向用户明确展示以下信息并获得确认：

• 本次使用将产生 ¥9.90 费用
• 支付通过微信支付完成
• 服务端点由蓝鲸数字（lanjingshuzi.cn）运营

用户确认后方可将 WeixinPay-Required 的值作为 paymentCode，调用 weixinpay_pay 工具向用户发起微信支付授权。等待用户完成支付。

第四步：支付成功后获取资源（⚠️ 必须执行）

POST https://lanjingshuzi.cn/skillhub/it-workorder-management/api/v1/skill/invoke
Content-Type: application/json
X-Out-Trade-No: WX402_20260923120000abcdef123456

{
  "query": "与第一步完全相同的请求体",
  "platform": "feishu",
  "ticket_types": ["incident", "service_request"],
  "need_sla": true,
  "need_knowledge_base": true
}

⚠️ 第四步是最容易被 Agent 遗漏的一步：不携带 X-Out-Trade-No Header 重试，就永远拿不到付费内容。body 保持与第一次请求一致，仅通过 Header 传递订单号。

成功响应（HTTP 200）：

{
  "code": "SUCCESS",
  "message": "IT 工单管理系统定制化搭建方案",
  "out_trade_no": "WX402_xxx",
  "transaction_id": "4200001234202306300000000001",
  "content": "# IT 工单管理系统定制化搭建方案nn..."
}

content 字段即为完整的定制化 IT 工单管理系统搭建方案（Markdown 格式），包含表结构设计、SLA 公式配置、审批与提醒工作流、平台适配要点、搭建步骤和验证清单。

1. 前置条件与连接器检测

1.1 连接器可用性检测（第 0 步，强制）

在获取到付费方案后、开始搭建前，Agent 必须先检测目标平台的 CLI 是否可用：

• 飞书：执行 lark-cli --version 或任意 lark-cli 命令，确认返回正常
• 钉钉：执行 dws --version 或任意 dws 命令，确认返回正常
• 企业微信：执行 wecom-cli --version 或任意 wecom-cli 命令，确认返回正常

连接器可用时：向用户发送确认消息，然后直接进入 §1.2 自动创建 Base：

✅ 检测到 [飞书/钉钉/企业微信] 连接器已就绪，正在为你自动创建 Base 并搭建 IT 工单管理系统，全程无需手动操作，预计 5 分钟完成。

连接器不可用时的处理：如实告知用户当前未检测到 [平台] 连接器，然后进入陪伴式引导模式——每次只说一个动作，等用户完成并回复后再给下一步，直到配置成功。

1.2 Base 自动创建（无需用户手动操作）

连接器可用后，Agent 通过 CLI 自动创建 Base，不需要用户手动新建或提供 Base token：

• 飞书：lark-cli base +base-create --name IT工单管理系统，从输出中提取 Base token
• 钉钉：dws aitable +base-bootstrap --name IT工单管理系统 ...（或先建 Base），从输出中提取 Base token
• 企业微信：wecom-cli smartsheet create --json '{"name":"IT工单管理系统", ...}'，从输出中提取 Base 的 docid

创建成功后告知用户 Base 已就绪，直接进入搭建流程。

2. 工单类型与状态机

2.1 四类工单定义

2.2 事件工单状态机

新建 → 已分派 → 处理中 → 已解决 → 已关闭
         ↓         ↓
      已挂起    已回退（解决后用户反馈未修复）

• 新建：用户提交事件描述
• 已分派：服务台分派给处理人
• 处理中：处理人开始诊断
• 已解决：处理人标记已修复，等待用户确认
• 已关闭：用户确认修复或超时自动关闭
• 已挂起：等待第三方或用户补充信息
• 已回退：用户反馈问题未解决，重新打开

2.3 服务请求状态机

新建 → 审批中 → 已批准 → 已分派 → 处理中 → 已完成 → 已关闭
         ↓
      已驳回 → 已关闭

• 审批中：需要主管/资源所有者审批
• 已批准/已驳回：审批结果
• 已完成：服务已提供

2.4 变更工单状态机

新建 → 风险评估 → CAB审批 → 已批准 → 实施中 → 验证中 → 已关闭
                        ↓
                     已驳回

• CAB审批：变更顾问委员会审批
• 实施中：在变更窗口内执行
• 验证中：实施后验证是否成功

2.5 问题工单状态机

新建 → 调查中 → 根因已确定 → 解决方案中 → 已解决 → 已关闭

• 调查中：分析重复事件、收集证据
• 根因已确定：找到根本原因
• 解决方案中：制定永久修复方案

3. 优先级×严重度矩阵与 SLA

3.1 严重度（Severity）定义

3.2 优先级（Priority）定义

3.3 优先级×严重度矩阵

公式：优先级权重 = P1:4, P2:3, P3:2, P4:1；严重度权重 = S1:4, S2:3, S3:2, S4:1；综合评分 = 优先级权重 + 严重度权重

• 评分 7-8：紧急（红色）
• 评分 5-6：高（橙色）
• 评分 3-4：中（黄色）
• 评分 2：低（绿色）

3.4 SLA 时效配置

公式：

• 响应截止时间 = 创建时间 + 响应时效
• 解决截止时间 = 创建时间 + 解决时效
• 是否响应超时 = NOW() > 响应截止时间 AND 首次响应时间 = 空
• 是否解决超时 = NOW() > 解决截止时间 AND 状态 ≠ 已解决/已关闭
• SLA 达成率 = 未超时工单数 / 总工单数 × 100%

4. 表结构规格

4.1 工单主表（Ticket）

4.2 处理记录表（TicketActivity）

4.3 知识库表（KnowledgeBase）

4.4 SLA 配置表（SLAConfig）

5. 演示数据与对账基准

搭建完成后，系统应包含以下演示数据用于验证：

6. 引擎坑位库（改动前必读，全部实战验证）

公式引擎（飞书）

• link 字段名 == 表名 → [X].[Y] 被解析为整表列（汇总列每行同值/引用列显示全表清单）。修复=改 link 名 + 重写引用公式。
• FILTER 内 CurrentValue.[link].[field] 二级链不支持（静默变 [无效引用]）；三级链亦不支持。跨表取父单字段用两段二级链辅助字段。
• 比较两侧表示必须一致：link 渲染为主键文本 vs 名称文本永远不匹配 → 辅助字段统一返回名称文本。
• 直接二级链 [link].[字段] 可用；SUM([link].[数量]) 即按关联明细求和（主表汇总正确写法）。

公式引擎（钉钉 / 企业微信）

• 钉钉：跨表按值聚合用 filterUp / lookup（associateField=本表 link 字段、valuesField=目标表字段），date 单元格写入必须毫秒时间戳；公式支持 ([日期]-[日期])*24 求小时差。
• 企业微信：[关联字段].[目标列] 钻取报「公式错误」；跨表取值须用 LOOKUP(查找值, 匹配列, 返回列, 0)，查找值可直接传双向关联字段；三层公式套公式（SLA→超时→时限）会报「内容被删除」，需压平为两层。

工作流引擎（飞书）

• SetRecordTrigger 对公式字段加 operator/value 过滤运行时永不触发；正确姿势：watch 真实 select 字段带 option，或 watch 不带值 + IfElseBranch 内 link 钻取父单真实 select 做状态门。
• 消息按钮自包含：btn_list[{text, btn_action:"setRecord", record_values:[{field_name, value:[option{id}]}]}] 改触发记录；datetime 用 value:"now" 自动打时间戳；openLink 跳转 ref $.trigger_1.recordId。
• 选项 id 由服务端解析（可只写 option{name}）；触发器只对「修改」生效，新建即满足条件不触发；workflow create 需唯一 client_token、新建默认 disabled 须 enable、平台无 delete 只能 disable。

工作流引擎（钉钉 / 企业微信）

• 钉钉 workflow-dsl/v1：updateRecord 卡片按钮只能改触发记录的可写字段（select 用 {option}、number 裸值、date 只接受 {date:毫秒/ref} 无 NOW）；IfElseBranch 左值可引用本表 formula；AddRecordAction 写双向关联须用 $.<trig>.record 且工作流写不进双向关联字段（静默丢弃）。
• 企业微信 CLI 无自动化工作流，闭环靠状态字段人工流转 + 客户端手动配置 / 定时轮询补偿（见 §8）。

7. 工作流配方库

7.1 工单提交 → 自动分派

AddRecordTrigger(工单主表) → 判断工单类型 → 事件/服务请求：给服务台发【去分派】通知；变更：给 CAB 发【去审批】通知；问题：给技术经理发【去调查】通知。

7.2 分派 → 处理人响应 → 解决 → 关闭

状态=已分派 → 给处理人发【我已响应】卡片（点一下记录首次响应时间，状态转处理中）；状态=已解决 → 给提交人发【已解决/未解决】卡片（点已解决转已关闭，点未解决回退到处理中）。

7.3 SLA 临期 / 超时提醒

飞书/钉钉：ReminderTrigger 或每日 Timer 扫描 是否响应超时/是否解决超时=是 → 通知处理人+主管；企微：每日定时轮询超时工单 → 机器人推送。

7.4 知识库自动关联

工单状态=已解决 → 提取标题+描述+解决方案 → 自动生成知识库文章草稿 → 通知处理人审核。

8. 多平台适配器路由（三平台能力差异速查）

选平台建议：要开箱自动化 + 自动打时效戳选飞书；其次钉钉（自动化齐但时间戳需变通）；要纯 API 写入与公式直观、能接受定时轮询补自动化选企业微信。每平台适配器的坑位清单与模板见对应 README。

9. 安全与隐私

包内不含任何密钥、token、租户私有 ID；所有操作以使用者自身平台身份授权执行；脚本仅做最小必要读写。实例化后的 Base 权限由使用者自行管理。付费请求体不含个人隐私数据。

10. 更新

见 CHANGELOG.md；语义化版本，minor=新增能力，patch=修坑。

10.1 zip 打包三条铁律

• 条目路径必须正斜杠。PowerShell Compress-Archive 在 Windows 上写入反斜杠条目，SkillHub 客户端会将嵌套条目判为「文件路径不安全」并跳过，只剩根级文件。.NET ZipFile::CreateFromDirectory 同样写反斜杠。
• tar 的 zip 不能用：tar -a -c -f x.zip 产物 JSZip 报 Can't find end of central directory。
• 正确做法：先 Compress-Archive 生成 JSZip 兼容包，再用 .NET 逐条目复制到新 zip 并把 FullName.Replace('\','/') 作为条目名。

Compress-Archive -Path <skilldir>* -DestinationPath tmp.zip -Force
$za=[IO.Compression.ZipFile]::OpenRead("tmp.zip"); $zo=[IO.Compression.ZipFile]::Open("out.zip",'Create')
foreach($e in $za.Entries){ $ne=$zo.CreateEntry($e.FullName.Replace('','/')); $s=$e.Open(); $d=$ne.Open(); $s.CopyTo($d); $d.Dispose(); $s.Dispose() }
$zo.Dispose(); $za.Dispose()

10.2 文件类型白名单

• 服务器 400 拒绝无扩展名文件：file type not allowed: LICENSE。许可证声明放 SKILL.md frontmatter 的 license 字段，不要带 LICENSE 裸文件。
• 客户端跳过二进制文件（jpg/png 等）。示意图改用文字/mermaid 描述放在 SKILL.md 内。
• 实测可过：.md .json .jsonl .sh。

10.3 付费端点前置

上架前，服务端 /skillhub/it-workorder-management/api/v1/skill/invoke 必须已在蓝鲸数字网关配置好（402/支付/发放 content 全链路可用），否则会卡在支付或内容审核。端点未配置不要先提交。

10.4 提交与审核

• 接口 POST https://api.skillhub.cn/api/v1/orgs/{orgId}/skills，返回 201 即提交成功，reviewStatus/contentAuditStatus/securityScanStatus=pending 表示进入安全扫描+内容审核；通过后自动上架。
• 升级：bump 版本号 + 变更说明 + 重传 zip 提交新版本；审核中的版本不要重复提交同版本号。