shield_lock
JinDaGe
Contact
← Back to skills
extension
Category: OtherAPI key required

发布变更分析助手

release-analytics

personAuthor: user_3086da4fhubcommunity
downloadDownload package

智研发布数据分析

概述

本技能用于从智研平台获取导航技术中心和服务架构中心的发布数据，进行多维度分析，生成可视化报告。

前置准备

首次使用时需要配置以下Token，配置一次后会持久化到本地文件，后续使用无需再配。

1. 智研Token（必须，用于拉取发布数据）

检查 ~/.zhiyan_token 是否存在。如果没有，引导用户：

请访问 https://zhiyan.woa.com/permission/#/access-token/private ，登录智研平台 → 右上角头像 → 访问控制 → Token权限管理 → 个人账号 → 查看个人令牌，将令牌贴给我。

用户贴回Token后，自动写入 ~/.zhiyan_token。

Token验证：拿到Token后，立即对6个项目空间各查1条数据验证权限：

# 验证逻辑：对每个project_id查page_size=1
for pid in [10323, 10988, 10990, 9259, 8934, 9251]:
    # 调用 query_order_list，检查返回 total > 0
  • 全部通过 → 告知用户"Token验证通过，6个项目空间均可访问"
  • 部分失败 → 告知用户哪些项目无权限，引导用户在智研平台申请对应项目空间的查看权限

2. TAPD Token（L3报告需要，用于计算Lead Time）

检查 ~/.tapd_token 是否存在。如果没有，引导用户：

请访问 https://tapd.woa.com/platform/myhome?not_direct=1&from=mcp#tab=tab-mytoken ，点击"创建个人访问令牌"。令牌仅显示一次，请妥善保存，然后贴给我。

用户贴回Token后，自动写入 ~/.tapd_token。

Token验证：拿到Token后，立即对发布量最大的TAPD workspace各查1条验证权限：

# 验证逻辑：对每个workspace_id调用 GET /stories?workspace_id={ws}&limit=1
# 导航Top 6 + 服务架构Top 4
for ws in ['20423769', '20415762', '10133271', '70158606', '70144814', '10111831',
           '69991854', '10026301', '70106726', '70094753']:
    # 检查返回 status=1
  • 全部通过 → 告知用户"TAPD Token验证通过，发布量最大的10个TAPD空间均可访问。实际发布关联的TAPD空间较多，如后续遇到个别需求标记为'无权限'，可按提示单独申请对应空间的权限"
  • 部分失败 → 告知用户哪些TAPD空间无权限，这些空间的需求Lead Time将标记为"无权限"，引导用户在TAPD申请对应项目的成员权限

注意：如果用户只使用L1（快速查数）和L2（标准报告），不需要TAPD Token。仅在用户要求Lead Time分析时才需要。

核心流程

用户提问 → 意图识别 → 参数确认 → 数据获取 → 数据分析 → 产物输出

Step 1：意图识别与参数提取

从用户提问中提取三个关键参数：

1.1 时间范围

| 用户表述 | 解释 | |---------|------| | "过去一周" | 最近 7 天 | | "过去一个月" | 最近 30 天 | | "昨天" | 昨天那一天 | | 模糊表述 | 必须和用户确认 |

1.2 查询范围

场景A — 整体查询：用户问"导航整体/导航中心"→ 查询导航的4个智研项目（10323/10988/10990/9259）；用户问"服务架构"→ 查询服务架构的2个项目（8934/9251）；用户问"地图网关"→ 仅查8934；用户问"引擎后台"→ 仅查9251。

场景B — 按业务方向查询：用户指定了业务板块（如"诱导""路线"）→ 需要映射到具体的项目和 plm_app[].name。

映射策略：静态表打底 + 动态查询兜底。

  1. 先查静态映射表（见 references/数据分析字段映射.md §4.2），用用户口语匹配业务方向
  2. 精确命中（用户口语完全等于映射表中的某个口语关键词）→ 直接使用，无需确认
  3. 模糊命中（用户说的词接近但不完全等于，如"ETA""诱导服务"）→ 列出最接近的方向，和用户确认
  4. 完全匹配不上 → 从智研 API 动态拉取 plm_app 列表让用户选
  5. 确认后，将 plm_app 列表以逗号分隔传入 --plm_filter，project_id 列表传入 --project_ids

注意：无 plm_app 字段的审批单类型（交付流紧急部署单、发布评审单）会被 plm_filter 过滤掉，应在报告中提示用户此限制。

场景C — 按人查询：用户指定了发布人 → 按 creator 过滤。

场景D — 按类型过滤：用户指定了发布类型或变更意图 → 按对应字段过滤。

场景E — 时间对比：用户要对比两个时间段 → 分别拉取两段数据。

1.3 产物级别

| 级别 | 产物 | 包含内容 | 适用场景 | |:---:|------|---------|---------| | L1 | 快速查数 | 直接回答数字/列表，不生成报告 | 场景C/D/F，或用户只要数字 | | L2 | 标准报告 | 完整 HTML 分析报告，不含 Lead Time | 场景A/B/E，用户要报告但不想等太久 | | L3 | 完整报告 | 完整 HTML 分析报告，含 Lead Time | 用户明确要求 Lead Time 分析 |

产物级别判断规则：

  • 用户说"快速看看""多少次""谁最多"等 → 默认L1
  • 用户说"发布情况""分析一下""生成报告"等 → 默认L2，但要告知用户：

    "我将为你生成完整的发布分析报告。默认不包含需求Lead Time分析（因为需要逐条查询TAPD，耗时较长）。如果你需要研发效能/Lead Time数据，告诉我，我可以一并计算。"

  • 用户明确提到"Lead Time""研发效能""完整报告"等 → L3
  • 不确定时才询问用户

L1 场景下 --skip_detail 使用规则：

变更意图分类依赖"标题+发布详情"做关键词匹配，skip_detail会导致意图分类严重不准。因此：

| 查询类型 | 是否可用 skip_detail | |---------|:---:| | 按人过滤/排名（不涉及意图） | ✅ 可以 | | 按审批单类型过滤（不涉及意图） | ✅ 可以 | | 按变更意图过滤/统计/分布 | ❌ 禁止 | | 生成报告（L2/L3，含意图分析） | ❌ 禁止 |

L1 追问升级（全局规则）：

L1 场景下如果使用了 --skip_detail，用户可能在看到L1结果后追问更多细节，此时需要无缝升级：

| 用户追问 | 升级动作 | |---------|---------| | "第X条的详情是什么" | 对该条审批单调 get 接口获取发布详情，直接回答 | | "展开看看具体内容" | 不带 --skip_detail 重新拉取数据，补全详情后回答 | | "帮我生成一份报告" | 从 L1 升级到 L2，不带 --skip_detail 重新拉取数据，生成 HTML 报告 | | "加上 Lead Time" | 从 L1/L2 升级到 L3，补算 Lead Time 后生成报告 |

升级时不需要重新询问时间范围和查询条件，复用当前会话中已确认的参数。

Step 2：数据获取

执行 scripts/fetch_release_data.py 从智研API拉取数据。

2.1 智研API

  • list 接口：POST http://openapi.zhiyan.woa.com/workflow/api/order/query_order_list — 按项目ID+时间范围批量查询审批单
  • get 接口：POST http://openapi.zhiyan.woa.com/workflow/api/order/get — 单条查询，获取发布详情（data字段中的impactDetails）

鉴权方式：HTTP Header token: {用户的智研个人令牌}

Token配置详见上方「前置准备」章节。执行脚本时传入：

ZHIYAN_TOKEN="$(cat ~/.zhiyan_token)" python3 scripts/fetch_release_data.py ...

2.2 脚本用法

# 查询全部4个项目
python3 scripts/fetch_release_data.py \
  --project_ids 10323,10988,10990,9259 \
  --start 2026-03-23 --end 2026-03-29 \
  --output release_data.csv

# 按业务板块过滤
python3 scripts/fetch_release_data.py \
  --project_ids 10323 \
  --start 2026-03-23 --end 2026-03-29 \
  --plm_filter "导航技术中心导航组-路线诱导" \
  --output release_data.csv

# 快速模式（跳过详情获取，无发布详情字段）
python3 scripts/fetch_release_data.py \
  --project_ids 10323 --start 2026-03-23 --end 2026-03-29 \
  --skip_detail --output release_data.csv

2.3 智研项目

当前覆盖 6 个智研项目：

| project_id | 项目名称 | 分析字段取值 | 所属业务 | |:---:|---------|------------|:---:| | 10323 | 导航技术中心-导航组 | 路线排序/车道级/诱导/吸附 | 导航 | | 10988 | 导航技术中心路况组 | 路况 | 导航 | | 10990 | 导航技术中心-3X实验室 | 诱导动态方向 | 导航 | | 9259 | 导航技术中心-公共出行-taf | 步骑行/电动车/公交 | 导航 | | 8934 | 服务架构中心 | 地图网关 | 服务架构 | | 9251 | 引擎研发中心-引擎后台组 | 底图服务/异源/同源 | 服务架构 |

2.4 数据字段

通过智研 API 获取审批单数据后，按 references/数据分析字段映射.md 的映射规则提取分析字段。审批单有 4 种类型（A/B/Bu/C），不同类型的字段取值来源不同，详见 references/审批单字段定义.md。

2.5 变更意图分类

基于发布标题和发布详情进行语义分析，归入以下四类：

| 分类 | 典型特征 | |------|---------| | AB实验 | AB、实验、灰度放量、横评 | | 策略优化 | 优化、调整、阈值、参数、配置、缩容、扩容 | | 问题修复 | 修复、fix、bugfix、异常、兜底 | | 新特性 | 新增、支持、接入、上线、一期、专项 |

Step 3：分析与输出（按产物级别分流）

L1 — 快速查数

直接基于 CSV 数据回答用户问题，不生成报告文件。例如：发布总次数、发布人排行、某人的发布列表等。

L2 — 标准报告（不含 Lead Time）

执行 scripts/gen_report.py 生成 HTML 报告：

python3 scripts/gen_report.py --input data.csv --output report.html --title "导航组"

title命名规则："{查询范围} {时间范围简称}"，例如：

  • 整体查询昨天 → "导航中心 3/30"
  • 诱导方向过去一周 → "路线诱导 3/24-3/30"
  • 整体查询过去一个月 → "导航中心 3月"

输出路径：默认输出到用户当前工作目录，文件名为 {title}_发布分析报告.html。

end日期说明：--start 和 --end 均为包含当天，如查昨天（3/30），则 --start 2026-03-30 --end 2026-03-30。

脚本自动检测 CSV 中是否有「需求Lead Time」列来决定报告模式。L2 模式包含 6 章 + 附录：

  1. 全局概览 — KPI卡片 + 环形图 + 服务条形图
  2. 发布节奏 — 按日汇总 + 折线图 + 洞察卡片
  3. 变更方向 — 变更意图总览 + 按模块拆解 + 主题归类
  4. 团队贡献 — 按人排行 + 人员-模块矩阵 + 单点风险
  5. 总结与建议 — 双栏正反总结 + P0/P1/P2 改进建议表
  6. 附录 — 完整发布记录明细

L3 — 完整报告（含 Lead Time）

在 L2 的基础上，插入一步 Lead Time 计算，流程为：

fetch_release_data.py 输出 CSV（基础13列）
        ↓
  calc_leadtime.py 计算（追加2列：需求Lead Time、Lead Time备注）
        ↓
gen_report.py 输出 HTML（含第五章：研发效能分析）

Lead Time 计算脚本：scripts/calc_leadtime.py

python3 scripts/calc_leadtime.py data.csv data_l3.csv

计算步骤：

  1. 遍历 CSV 中每行的「需求单」字段，用正则解析出 TAPD 的 workspace_id、object_type（story/bug）、object_id
  2. 无需求单链接的行标记"无TAPD链接"，跳过
  3. 通过 TAPD OpenAPI（http://apiv2.tapd.woa.com）查询需求/缺陷基本信息，获取 created 时间
  4. 通过 TAPD OpenAPI 查询状态变更历史，找到最终到达终态的时间（非首次，因为bug可能被reopen）
  5. 计算 Lead Time = 需求创建时间 → 最终到达终态时间
  6. 按判定规则标注备注，追加到 CSV

story 和 bug 的终态判定差异：

| 类型 | API路径 | 终态判定方式 | |------|---------|------------| | bug | bug_changes?field=status | 直接匹配英文key：resolved、closed | | story | story_changes（不加field过滤） | 从 field_changes 数组中找 field=="status" 的变更，用 value_after_parsed（中文名）匹配：待发布、已发布、已实现、已验证、已关闭 |

story的状态key是项目自定义的（如 status_23），不同项目不同，因此必须用API返回的 value_after_parsed 中文名来匹配终态。

鉴权：使用 TAPD Token（同MCP配置中的 X-Tapd-Access-Token），通过 HTTP Header Authorization: Bearer {token} 传入。

缓存机制：同一需求单被多行引用时，只查一次API，结果复用。

权限限制：部分TAPD项目当前Token无权限，标记为"无权限"，在报告中统计并提示。

Lead Time 判定规则：

| 分类 | 条件 | 备注标记 | 判定方式 | |------|------|---------|---------| | 疑似补录 | Lead Time < 24小时 | 疑似补录 | 脚本自动判定 | | 待判定 | Lead Time ≥ 24小时 | 待判定 | 脚本标记，由大模型根据「状态变更时间线」判定 | | 无权限 | TAPD API返回422 | 无权限 | 脚本自动判定 | | 未到达终态 | 需求未到达待发布/已发布/resolved/closed | 未到达终态 | 脚本自动判定 |

大模型判定流程（针对"待判定"的记录）：

脚本输出CSV中包含「状态变更时间线」列，格式如：新→需求已评审(13s)→开发中(6s)→产研自测中(3h2m)→待发布(3s)。

大模型在生成L3报告时，逐条审查"待判定"记录的时间线，判定为：

  • 正常：状态变更间隔合理，反映真实研发过程
  • 状态扭转不规范：多个状态变更在极短时间内连续发生（如数秒内跳过多个中间状态），说明TAPD状态未按节点及时更新，而是事后一次性补点

L3 报告比 L2 多一章： 5. 研发效能（Lead Time） — Lead Time 分类统计 + 明细表 + 补录/不规范洞察

默认输出 HTML。 用户要 PDF 时，用 Playwright 将 HTML 转为 PDF（每个章节从新页开始，首页 Header 与全局概览合并）。

参考文档

按需加载，不要预先全部读入：

  • references/审批单字段定义.md — 4 种审批单类型的字段结构和判定条件。当需要理解数据模型或字段取值来源时读取。
  • references/数据分析字段映射.md — 分析字段与原始字段的映射关系、枚举值映射表。当需要做字段映射或业务板块匹配时读取。
  • references/发布分析报告框架.md — 报告的 7 章结构定义、每章的分析逻辑和数据依赖。当生成报告时读取。