从零打通 super-xiaoe：工单自动排查与评论闭环

从零打通 super-xiaoe：工单自动排查与评论闭环

---

背景

小鹅通内部产研答疑大量落在 Coding 缺陷工单上：标题里写现象、描述里是 HTML 模板、截图挂在 KM、关键字段散落在自定义列里。人工处理一条工单的典型路径是：

1. 打开工单 → 复制 app_id / 用户 ID / 复现步骤
2. 翻知识库、查日志、跑 SQL、搜代码
3. 在工单里写结论 → 决定是否沉淀到 team-knowledge

这条链路重复度高、格式不统一，且「查过了什么、置信度如何」很难被后来者复用。

目标 ：在 team-knowledge 仓库落地的 super-xiaoe Skill 中，打通：

• 输入 ：排查工单63387 一句话触发
• 过程：自动拉工单 → 结构化上下文 → 知识库定向 → MCP 取证 → 分路径输出
• 输出 ：双视角结论 → 用户确认后 一键评论回工单 → 可选沉淀知识库

---

架构设计

┌──────────────────────────────────────────────────────────────────────┐
│                     super-xiaoe（team-knowledge）                      │
│                                                                       │
│  用户: /super-xiaoe 排查工单63387                                      │
│       │                                                               │
│       ▼                                                               │
│  ┌─────────────┐   ┌──────────────┐   ┌─────────────────────────┐  │
│  │ §0 知识库校验 │──▶│ §0.1 拉工单   │──▶│ 结构化字段 + 截图分析     │  │
│  │ $KB/catalog │   │ Coding Web API│   │ 评论去重（CTT/super-xiaoe）│  │
│  └─────────────┘   └──────────────┘   └─────────────────────────┘  │
│       │                                      │                        │
│       ▼                                      ▼                        │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │ §2 三路分流：产品疑问(A) | Bug排查(B) | 数据推理(C)            │    │
│  └─────────────────────────────────────────────────────────────┘    │
│       │                                                               │
│       ├─ A: 知识库 + sg 佐证 → 产品解释模板                            │
│       ├─ B: meta-mcp / db-proxy / sg → 链路表 + 双视角 + 根因归类      │
│       └─ C: 全景 JSON + db-proxy → 数据推理模板                        │
│       │                                                               │
│       ▼                                                               │
│  ┌─────────────┐   ┌──────────────┐   ┌─────────────────────────┐  │
│  │ 用户确认     │──▶│ §9 评论工单   │──▶│ §5 沉淀 biz-wiki / MCP   │  │
│  │ 「评论」/跳过 │   │ Open API     │   │ save_team_knowledge      │  │
│  └─────────────┘   └──────────────┘   └─────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────┘
         ▲                    ▲                    ▲
         │                    │                    │
   team-knowledge      CODING_TOKEN          meta-mcp / db-proxy / sg
   biz-wiki + 全景 JSON   Python urllib

设计原则（与日志自愈文一脉相承）：

1. 复用已有基础设施 --- Coding、知识库、MCP，不另起一套工单系统
2. 渐进式处理 --- 拉单 → 分类 → 取证 → 输出 → 评论，每步可停、可回退
3. 安全优先 --- 不自动评论、不自动改工单状态、不未经确认写库

---

核心模块

1. 工单详情自动拉取（§0.1）

触发词：排查工单{编号}、排查{编号}（工单场景）。

为什么不用 Open API 的 DescribeIssue？

在该 Coding 项目下，Open API 的 DescribeIssue 会返回 UnauthorizedOperation；Web API 稳定可用：

GET https://xiaoe.coding.net/api/project/10926144/issues/defects/{IssueCode}
Authorization: token {CODING_TOKEN}

Python 拉取模板（必须用 Python，避免 PowerShell 下中文与 JSON 转义问题）：

import json, os, urllib.request, re, sys

CODING_TOKEN = os.environ.get('CODING_TOKEN', '')
ISSUE_CODE = sys.argv[1]

url = f'https://xiaoe.coding.net/api/project/10926144/issues/defects/{ISSUE_CODE}'
req = urllib.request.Request(url, headers={
    'Authorization': f'token {CODING_TOKEN}',
    'Content-Type': 'application/json',
})
with urllib.request.urlopen(req) as resp:
    issue = json.loads(resp.read().decode('utf-8'))['data']
    # 标题、优先级、状态、负责人、customFields、description HTML...

评论列表用 Open API（此接口可用）：

POST https://e.coding.net/open-api/DescribeIssueCommentList?Action=DescribeIssueCommentList

用于扫描是否已有自动排查标记，避免重复劳动。

---

2. 结构化字段提取

从工单里稳定抽出后续取证需要的「业务主键」，优先级：

字段	来源	用途
app_id	customFields「店铺」或描述正则 app[a-zA-Z0-9]{11}	db-proxy 分表、日志 topic
user_id	customFields「用户」或描述	用户态、绑定关系
resource_id	标题/描述/短链	课程、商品、直播等资源
phenomenon	描述纯文本	分类、日志关键字

本步结论：没有 app_id 和时间窗时，Skill 会走「信息不足暂停」或反查链路，而不是空转全库扫描。

---

3. 三路分流排查（§2）

不再对所有问题一刀切「技术 + 客服双视角」，而是先 判定类型 再加载 references（控制 token 与噪音）：

路径	信号	步骤	典型 MCP
A 产品疑问	「为什么」「设计意图」、无报错	3 步	sg 佐证即可
B Bug 排查	报错、堆栈、功能不可用	6 步	meta-mcp → db-proxy → sg
C 数据推理	指标/数值异常、无报错	4 步	db-proxy + 全景 JSON

Bug 路径在输出前强制 根因归类 （代码缺陷 / 产品逻辑 / 数据异常 / 需求缺失），并要求 ≥2 方证据 才能标「已证实」。

db-proxy 前置约束（踩坑高发区）：

每次 SQL 前必须读 $KB/team-conventions/业务模块数据库表检索.json，确认：表是否存在、是否废弃、是否分表、实例与库名。

例如推广员表 t_distributor 按 app_id 末两位分表，查 t_distributor_94 而不是扫全分表。

---

4. 评论回写工单（§9）

排查结束后 不自动发送。Skill 会固定询问：

排查已完成。是否将结论评论到工单 #63387？
回复「评论」发送，「跳过」不评论，「修改：xxx」调整后再评论。

用户说「评论到工单63387」时，走 Open API：

POST https://e.coding.net/open-api/CreateIssueComment?Action=CreateIssueComment

payload = json.dumps({
    'ProjectName': 'xianwangjishugongdan',
    'IssueCode': ISSUE_CODE,
    'Content': CONTENT  # Markdown，ensure_ascii=False
}, ensure_ascii=False)

评论体结构（与 CTT 扫描规则对齐，便于去重）：

🔍 super-xiaoe 自动排查结论

--- 时间：2026-05-21 14:30:00
--- 工单：#63387
--- MCP：meta-mcp ✗ | sg ✓ | db-proxy ✓
--- 店铺信息：已附带

---

## 技术视角
...

## 产品客服视角
...

## 沉淀建议
...

---

_由 super-xiaoe skill 自动生成_

刻意不做的事：

• 评论成功后 不 自动把工单标为已解决
• 未收到「评论」触发词 绝不 调用 CreateIssueComment
• 禁止 curl -d 传中文（Windows 下乱码高发）

---

技术选型

组件	选型	原因
Agent 编排	Cursor + SKILL.md	团队已在用；Skill 可版本化在 team-knowledge
知识库	team-knowledge 本地 $KB + meta-mcp search_team_knowledge	离线 biz-wiki + 线上语义检索
表路由	业务模块数据库表检索.json	131 模块 / 4.8 万有效表，避免连错库、查废弃表
工单读	Coding Web API	项目内 Open API 读单不可用
工单写	Coding Open API + Python urllib	评论接口稳定；UTF-8 可控
代码搜索	Sourcegraph MCP (sg)	定向搜服务仓库，避免全仓漫搜
日志	meta-mcp (get_log_topics + search_log)	必须带毫秒时间窗，禁止 start_time=0
数据库	db-proxy	只读；强制 LIMIT、禁止 SELECT *、分表须指定后缀

---

仓库内文件结构

Skill 落在 team-knowledge 仓库，与知识库同仓，方便 PR 一起评审：

team-knowledge/
├── knowledge-catalog.md              # 业务域入口
├── biz-wiki/{domain}/                # 实体 / 踩坑 / catalog
├── team-conventions/
│   └── 业务模块数据库表检索.json      # db-proxy 决策必读本
├── log.md                            # 知识变更流水
└── .claude/skills/super-xiaoe/
    ├── SKILL.md                      # 主路由（§0~§9）
    └── references/
        ├── coding-ticket-fetch.md    # 拉单 API + 脚本模板
        ├── coding-comment.md         # 评论 API + 格式 + 反模式
        ├── knowledge-routing.md      # 知识库定向
        ├── db-safety.md              # SQL 安全
        ├── mcp-specs.md              # 日志/监控参数
        ├── chain-tracker.md          # 链路追踪表
        ├── output-templates.md       # A/B/C 分模板输出
        └── anti-patterns.md          # MUST NOT 清单

个人环境通过全局记忆 team_knowledge_path.md 指向 $KB，Agent 启动时先校验 knowledge-catalog.md 是否存在。

---

降级与安全策略

场景	处理
$KB 路径无效	提示克隆 team-knowledge，阻塞后续（知识库强依赖）
CODING_TOKEN 未设置	拉单/评论前提示配置 API Token（project:issue）
Open API 读工单 Unauthorized	降级 Web API 读详情（已固化在 references）
db-proxy 实例名错误	使用「脱敏-DB-xxx(cdb-xxx)」完整实例名
MCP/日志为空	写明查过什么、为何不足以定论；禁止编造根因（§8 推理失败披露）
工单已有 super-xiaoe/CTT 评论	提示可能已处理，询问是否继续
用户未确认「沉淀」	不写 biz-wiki、不调 save_team_knowledge

推理失败 比错误结论更安全：Skill 明确要求用「推理失败」模板替代瞎编，且 不产生沉淀提议。

---

实战片段：工单 #63387

现象：推广员分组 102 人，用户列表「指定推广员」只显示 100 人。

拉单结果：

• 店铺：校长来了，app8sem1tqn3194
• 分组：南京波比-团队长组

取证摘要：

1. db-proxy ：t_distribution_group → group_id=87027；t_distributor_94 有效推广员 cnt=102
2. sg ：用户列表筛选走 drp_go 的 /xe.drp.search_distributor_list/1.0.0；eboss/drp 多处 page_size 校验 max=100；接口 无 group_id 参数

结论类型：Bug（代码缺陷）--- 前端/接口分页上限导致第 101、102 人不可选。

这条链路从「排查工单63387」到结论，全程可在 Cursor 里用一条 Skill 跑完；是否评论到 Coding，由研发在对话里回复「评论」决定。

---

与「日志自愈」方案的差异

维度	日志监控自愈（参考文）	super-xiaoe 工单闭环
触发	定时轮询 ERROR 日志	人工/指令触发指定工单
存储	SQLite incident	知识库 + Coding 评论
自动修复	worktree + MR	不自动改代码（仅给修复方向）
人工闸门	MR 不自动合并	评论、沉淀均需确认
核心价值	缩短 MTTR	统一排查格式 + 可沉淀知识资产

两者可并存：日志系统发现异常 → 建工单 → 排查工单{id} 做深度根因与评论。

---

环境准备（一次性）

1. 克隆知识库：git clone ssh://git@talkcheap.xiaoeknow.com/eboss/team-knowledge.git
2. 配置 team_knowledge_path.md 指向本地路径
3. 在系统环境变量中设置 CODING_TOKEN（Coding → 个人设置 → API Token，勾选 project:issue）
4. Cursor 中启用 MCP：meta-mcp、user-db-proxy、user-sourcegraph-mcp 等

使用示例：

/super-xiaoe 排查工单63387

排查结束后：

评论

或跳过、或「修改：xxx」后再评论。

---

总结

在 team-knowledge 里打通 super-xiaoe 的工单能力，本质是把 「会排查的人」 拆成可执行的 Skill 步骤：

1. 工单可读 --- Web API 拉详情 + Open API 拉评论 + 结构化字段
2. 排查可路由 --- 产品 / Bug / 数据三条路径，references 按需加载
3. 证据可交叉 --- 知识库、代码、DB、日志四方印证，推理失败要坦白
4. 结论可回写 --- 标准 Markdown 评论进 Coding，带来源标记
5. 经验可沉淀 --- 用户确认后才写入 biz-wiki，避免污染知识库

后续可演进方向（尚未实现，仅作规划）：

• Webhook：工单创建自动 @Agent 排查
• 与 CTT（Coding Ticket Tool）统一 header/footer，工单列表展示「已 AI 初筛」
• 按业务域自动选路径的 few-shot 示例进 references/

如果你也在做内部答疑/工单体系，欢迎把 「拉单 → 取证 → 评论 → 沉淀」 四段拆进 Skill，比堆一个「万能 prompt」更稳、也更省 token。

---

作者：内部实践总结 · 基于 team-knowledge 仓库 super-xiaoe Skill（2026-05）