名称： youtrack
描述： 通过 REST API 与 YouTrack 项目管理系统交互。功能包括：读取项目和问题、创建任务、根据时间跟踪数据生成发票、管理知识库文章。适用于读取项目和工作项、创建或更新问题、根据时间跟踪生成客户发票以及处理知识库文章。

YouTrack

用于项目管理、时间跟踪和知识库的 YouTrack 集成。

快速开始

认证

生成永久令牌的步骤：
1. 在主导航菜单中，选择 管理 > 访问管理 > 用户
2. 找到您的用户并点击打开设置
3. 生成一个新的永久 API 令牌
4. 将令牌设置为环境变量：

export YOUTRACK_TOKEN=你的永久令牌

重要提示： 通过向 invoice_generator.py 传递 --rate 参数或在代码中更新 hourly_rate 参数来配置您的小时费率（默认为 100 美元/小时）。

然后即可使用任何 YouTrack 脚本：

# 列出所有项目
python3 scripts/youtrack_api.py --url https://your-instance.youtrack.cloud --list-projects

# 列出项目中的问题
python3 scripts/youtrack_api.py --url https://your-instance.youtrack.cloud --list-issues "project: MyProject"

# 为项目生成发票
python3 scripts/invoice_generator.py --url https://your-instance.youtrack.cloud --project MyProject --month "January 2026" --from-date "2026-01-01"

Python 脚本

scripts/youtrack_api.py

用于所有 YouTrack 操作的核心 API 客户端。

在 Python 代码中使用：

from youtrack_api import YouTrackAPI

api = YouTrackAPI('https://your-instance.youtrack.cloud', token='你的令牌')

# 项目
projects = api.get_projects()
project = api.get_project('项目ID')

# 问题
issues = api.get_issues(query='project: MyProject')
issue = api.get_issue('问题ID')

# 创建问题
api.create_issue('项目ID', '摘要', '描述')

# 工作项（时间跟踪）
work_items = api.get_work_items('问题ID')
issue_with_time = api.get_issue_with_work_items('问题ID')

# 知识库
articles = api.get_articles()
article = api.get_article('文章ID')
api.create_article('项目ID', '标题', '内容')

命令行用法：

python3 scripts/youtrack_api.py --url https://your-instance.youtrack.cloud \
    --token 你的令牌 \
    --list-projects

python3 scripts/youtrack_api.py --url https://your-instance.youtrack.cloud \
    --get-issue ABC-123

python3 scripts/youtrack_api.py --url https://your-instance.youtrack.cloud \
    --get-articles

scripts/invoice_generator.py

根据时间跟踪数据生成客户发票。

在 Python 代码中使用：

from youtrack_api import YouTrackAPI
from invoice_generator import InvoiceGenerator

api = YouTrackAPI('https://your-instance.youtrack.cloud', token='你的令牌')
generator = InvoiceGenerator(api, hourly_rate=100.0)

# 获取项目的时间数据
project_data = generator.get_project_time_data('项目ID', from_date='2026-01-01')

# 生成发票
invoice_text = generator.generate_invoice_text(project_data, month='January 2026')
print(invoice_text)

命令行用法：

python3 scripts/invoice_generator.py \
    --url https://your-instance.youtrack.cloud \
    --project MyProject \
    --from-date 2026-01-01 \
    --month "January 2026" \
    --rate 100 \
    --format text

将文本输出保存并打印为 PDF 发送给客户。

常用工作流

1. 列出所有项目

python3 scripts/youtrack_api.py --url https://your-instance.youtrack.cloud --list-projects

2. 查找项目中的问题

# 项目中的所有问题
python3 scripts/youtrack_api.py --url https://your-instance.youtrack.cloud --list-issues "project: MyProject"

# 自某日期后更新的问题
python3 scripts/youtrack_api.py --url https://your-instance.youtrack.cloud --list-issues "project: MyProject updated >= 2026-01-01"

# 分配给你的问题
python3 scripts/youtrack_api.py --url https://your-instance.youtrack.cloud --list-issues "assignee: me"

3. 创建新问题

from youtrack_api import YouTrackAPI

api = YouTrackAPI('https://your-instance.youtrack.cloud')
api.create_issue(
    project_id='MyProject',
    summary='任务标题',
    description='任务描述'
)

4. 生成月度发票

# 为 2026 年 1 月生成发票
python3 scripts/invoice_generator.py \
    --url https://your-instance.youtrack.cloud \
    --project ClientProject \
    --from-date 2026-01-01 \
    --month "January 2026" \
    --rate 100 \
    --format text > invoice.txt

将文本输出保存并打印为 PDF 发送给客户。

5. 读取知识库

from youtrack_api import YouTrackAPI

api = YouTrackAPI('https://your-instance.youtrack.cloud')

# 所有文章
articles = api.get_articles()

# 特定项目的文章
articles = api.get_articles(project_id='MyProject')

# 获取特定文章
article = api.get_article('文章ID')

计费逻辑

发票生成器使用以下计算规则：

1. 汇总每个问题跟踪的总时间（以分钟计）
2. 转换为 30 分钟增量（向上取整）
3. 最低收费为 30 分钟（按配置费率的一半计算）
4. 乘以费率（默认为 100 美元/小时，即每半小时 50 美元）

示例：
- 15 分钟 → 50 美元（30 分钟最低收费）
- 35 分钟 → 100 美元（向上取整至 60 分钟）
- 60 分钟 → 100 美元
- 67 分钟 → 150 美元（向上取整至 90 分钟）

环境变量

• YOUTRACK_TOKEN：您的永久 API 令牌（建议使用此方式，而非通过参数传递）
• 设置方式：export YOUTRACK_TOKEN=你的令牌

API 详情

请参阅 REFERENCES.md 获取：
- 完整的 API 端点文档
- 查询语言示例
- 字段 ID 和结构

错误处理

脚本会在以下情况下引发错误：
- 缺少或无效的令牌
- 网络问题
- API 错误（404、403 等）

请检查 stderr 以获取错误详细信息。