Supermap YouTrack 工作报告技能

概述

本技能用于从 YouTrack 项目管理平台获取指定时间范围内的工作时间记录，自动生成结构化的工作总结报告。

触发条件

当用户表达以下意图时自动调用：

• "总结[时间]的YouTrack工作内容"
• "生成[时间]的工作报告"
• "查看[时间]的工作统计"
• "youtrack总结 [时间]"

时间格式支持：

• 月份：2026-01、2026年1月
• 日期范围：2026-01-01到2026-01-31
• 相对时间：本月、上个月、上周

工作流程

1. 解析时间范围

将用户输入的自然语言时间转换为具体的起止日期：

• 2026年1月 → 2026-01-01 到 2026-02-01
• 本月 → 当前月份的第一天到第一天
• 上周 → 上周一到周日

2. 获取工作项数据

通过 YouTrack API 获取时间跟踪数据：

GET /api/timetracking/workitems
参数:
  - startDate: 开始时间戳
  - endDate: 结束时间戳
  - fields: id,date,duration(minutes,presentation),issue(id,idReadable,summary),text,author

3. 分析父任务关系

通过 /api/issues/{task_id}/links API 获取每个任务的实际父任务：

• 识别 parent for → subtask of 类型的链接关系
• 根据 direction 字段判断父子方向（INWARD=子任务）
• 统计最常见的父任务作为报告的主分类

4. 分组与统计

• 按子任务 ID 分组，合并多日的工作记录
• 计算每个子任务的总工作时间、工作天数、工作项数
• 提取工作内容描述

5. 生成报告

按照标准格式输出：

<父任务描述>:
  <子任务ID>: <子任务标题>
    - 工作时间: X小时
    - 工作天数: Y天 (日期列表)
    - 任务链接: http://yt.ispeco.com:8099/issue/<ID>
    - 工作内容: <描述>

配置要求

必需配置

• API Token: 设置环境变量 SUPERMAP_YOUTRACK_TOKEN
• API 地址: http://yt.ispeco.com:8099 （默认，可通过环境变量覆盖）

可选环境变量

export SUPERMAP_YOUTRACK_TOKEN="your-token-here"
export YOUTRACK_URL="http://yt.ispeco.com:8099"

使用示例

示例 1：总结某个月份

用户：总结2026年1月的YouTrack工作
→ 生成 2026-01-01 到 2026-02-01 的工作报告

示例 2：总结自定义日期范围

用户：总结2026-01-15到2026-01-28的工作
→ 生成指定日期范围的工作报告

示例 3：总结上周工作

用户：总结上周的YouTrack工作
→ 自动计算上周一到周日的时间范围

输出格式

报告头部

• 生成时间
• 查询的时间范围
• 父任务描述（基于API分析）

子任务详情

每个子任务包含：

• 任务 ID 和标题
• 总工作时间（小时）
• 工作天数及具体日期列表
• 工作项数量
• 任务链接
• 工作内容摘要

汇总信息

• 父任务总数
• 子任务总数
• 工作项总数
• 总工作时间
• 工作天数统计

边界情况处理

场景	处理方式
无工作记录	提示"指定时间范围内无工作记录"
单个子任务	正常输出，显示该任务的详细信息
多个父任务	选择关联子任务最多的父任务作为主分类
无父任务的任务	归类到"其他任务"或单独列出
API 调用失败	显示错误信息，建议检查网络和令牌

注意事项

1. 网络访问：需要能够访问 YouTrack 服务器（yt.ispeco.com:8099）
2. 权限要求：Token 需要有读取工作项和任务链接的权限
3. 时间精度：工作时间的最小单位是分钟，报告中转换为小时显示
4. 父任务推断：基于实际的父子任务链接关系，而非文本分析
5. 数据隐私：报告仅包含工作时间和任务信息，不包含敏感内容

依赖工具

• Python 3.7+
• requests 库
• 标准库：datetime, json, os, sys, argparse

相关文件

• scripts/youtrack_summary.py - 核心脚本