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. 生成报告

按照标准格式输出，支持多父任务分组：

# YouTrack 工作内容总结

**时间范围**: {time_range}
**生成时间**: {generated_at}

---

## 📁 {父任务1 ID}: {父任务1标题}
**子任务数量**: {N} 个 | **工时合计**: {X} 小时

### {子任务ID}: {子任务标题}
- **工作时间**: X小时
- **工作天数**: Y天 (日期列表)
- **工作项数**: N个
- **任务链接**: {url}/issue/{ID}
- **工作内容**: {描述}

### {子任务ID}: {子任务标题}
...

---

## 📁 {父任务2 ID}: {父任务2标题}
...

---

## 📁 其他任务（无父任务）
**子任务数量**: {N} 个 | **工时合计**: {X} 小时

### {子任务ID}: {子任务标题}
...

---

## 📊 总体汇总

| 统计项 | 数值 |
|--------|------|
| 父任务数 | X 个 |
| 子任务数 | Y 个 |
| 工作项数 | Z 个 |
| 总工时 | H 小时 |
| 工作天数 | D 天 |

### 各父任务工时分布

| 父任务 | 工时 | 占比 |
|--------|------|------|
| CS-XXX | XXh | XX% |
| CS-YYY | XXh | XX% |
| 其他任务 | XXh | XX% |

配置要求

必需配置

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工作
→ 自动计算上周一到周日的时间范围

输出格式

报告头部

生成时间
查询的时间范围

父任务分组

每个父任务独立显示一个分组：

## 📁 {父任务ID}: {父任务标题}
**子任务数量**: N 个 | **工时合计**: X 小时

子任务详情

每个子任务包含：

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

其他任务分组

无父任务的任务单独归入"其他任务"分组：

## 📁 其他任务（无父任务）
**子任务数量**: N 个 | **工时合计**: X 小时

总体汇总

以表格形式展示统计数据：

统计项	数值
父任务数	X 个
子任务数	Y 个
工作项数	Z 个
总工时	H 小时
工作天数	D 天

各父任务工时分布

父任务	工时	占比
CS-XXX	XXh	XX%
其他任务	XXh	XX%

边界情况处理

场景	处理方式
无工作记录	提示"指定时间范围内无工作记录"
单个子任务	正常输出，显示该任务的详细信息
多个父任务	每个父任务独立分组显示，所有子任务按真实父任务关系归类
无父任务的任务	单独归入"其他任务（无父任务）"分组
API 调用失败	显示错误信息，建议检查网络和令牌

注意事项

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

依赖工具

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

supermap:youtrack-work-report