YouTrack

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

快速开始

认证

生成永久令牌的步骤：

1. 从主导航菜单中，选择 Administration > Access Management > Users
2. 找到您的用户并点击以打开设置
3. 生成新的永久 API 令牌
4. 将令牌设置为环境变量：

export YOUTRACK_TOKEN=your-permanent-token-here

重要： 通过向 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='your-token')

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

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

# 创建问题
api.create_issue('project-id', 'Summary', 'Description')

# 工作项（时间跟踪）
work_items = api.get_work_items('issue-id')
issue_with_time = api.get_issue_with_work_items('issue-id')

# 知识库
articles = api.get_articles()
article = api.get_article('article-id')
api.create_article('project-id', 'Title', 'Content')

命令行使用：

python3 scripts/youtrack_api.py --url https://your-instance.youtrack.cloud \
    --token YOUR_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='your-token')
generator = InvoiceGenerator(api, hourly_rate=100.0)

# 获取项目的工时数据
project_data = generator.get_project_time_data('project-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='Task title',
    description='Task 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('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=your-token 设置

API 详细信息

参见 REFERENCES.md 获取：

• 完整的 API 端点文档
• 查询语言示例
• 字段 ID 和结构说明

错误处理

脚本会在以下情况抛出错误：

• 缺失或无效的令牌
• 网络问题
• API 错误（如 404、403 等）

请检查 stderr 以获取错误详情。