generate-status-report

生成状态报告

关键词

状态报告、项目状态、每周更新、每日站会、Jira 报告、项目摘要、阻碍因素、进度更新、Confluence 报告、冲刺报告、项目更新、发布到 Confluence、写入 Confluence、发布报告

自动查询 Jira 项目状态、分析问题，并生成格式规范的状态报告，发布到 Confluence。

重要：此技能应当具有交互性。生成报告之前或之后，始终与用户确认范围（时间段、受众、Confluence 目标位置）。不要默默跳过 Confluence 发布——始终主动询问用户是否需要发布。

工作流

生成状态报告需要遵循以下步骤：

1. 确认范围 - 确定项目、时间段和目标受众
2. 查询 Jira - 使用 JQL 查询获取相关问题
3. 分析数据 - 对问题分类并找出关键信息
4. 整理报告 - 根据受众和用途组织内容
5. 发布到 Confluence - 使用报告创建或更新页面

步骤 1：确认范围

重要：如果用户的请求缺少关键信息，请先询问，再执行查询。未经确认，不要假设 Confluence 发布的默认设置。

请确认以下信息：

项目标识：

• Jira 项目键是什么？（例如，“PROJ”“ENG”“MKTG”）
• 如果用户提到项目名称但未提供项目键，请搜索 Jira 以查找项目键

时间段：

• 如果未指定，请询问：“这份报告应涵盖哪个时间段？（默认：过去 7 天）”
• 选项：每周（7 天）、每日（24 小时）、基于冲刺（2 周）、自定义时间段

目标受众：

• 如果未指定，请询问：“这份报告面向谁？（高管/交付经理、团队成员，还是每日站会）”
• 高管/交付经理：提供高层次摘要，包括关键指标和阻碍因素
• 团队成员：按问题逐项提供详细状态
• 每日站会：简要更新昨天、今天的工作和阻碍因素

报告目标位置：

• 如果未指定，始终询问：“您希望我将这份报告发布到 Confluence 吗？如果希望，请问应该使用哪个空间？”
• 如果用户回答“是”：询问空间名称，或提议列出可用空间
• 确定是创建新页面，还是更新现有页面
• 如果要在特定版块下创建，请询问父页面

步骤 2：查询 Jira

使用 searchJiraIssuesUsingJql 工具获取问题。根据报告需求构建 JQL 查询。

常见查询模式

对于综合查询，请使用 scripts/jql_builder.py 实用程序以编程方式构建 JQL 字符串。对于快速查询，请参考 references/jql-patterns.md 中的示例。

项目中的所有未解决问题：

project = "PROJECT_KEY" AND status != Done ORDER BY priority DESC, updated DESC

过去一周更新的问题：

project = "PROJECT_KEY" AND updated >= -7d ORDER BY priority DESC

高优先级和受阻问题：

project = "PROJECT_KEY" AND (priority IN (Highest, High) OR status = Blocked) AND status != Done ORDER BY priority DESC

报告期内已完成的问题：

project = "PROJECT_KEY" AND status = Done AND resolved >= -7d ORDER BY resolved DESC

查询策略

对于大多数报告，执行多个有针对性的查询，而不是一个大型查询：

1. 已完成的问题：获取近期已解决的工单
2. 进行中的问题：获取正在处理的工作项
3. 受阻问题：获取需要关注的阻碍项
4. 高优先级未解决问题：获取即将开展的关键工作

初始查询使用 maxResults: 100。如果需要分页，请使用结果中的 nextPageToken。

要提取的数据

对每个问题，记录：

• key（例如，“PROJ-123”）
• summary（问题标题）
• status（当前状态）
• priority（重要程度）
• assignee（负责人）
• created / updated / resolved 日期
• description（如果需要了解阻碍因素的背景）

第 3 步：分析数据

处理检索到的问题，识别：

指标：

• 按状态统计的问题总数（已完成、进行中、受阻等）
• 完成率（如有历史数据）
• 高优先级事项数量
• 未分配问题数量

关键见解：

• 重大成果（近期完成的高价值事项）
• 关键阻塞项（受阻的高优先级问题）
• 风险事项（已逾期或进展停滞的问题）
• 资源瓶颈（某位受派人负责的问题过多）

分类： 按逻辑对问题进行分组：

• 按状态（已完成、进行中、受阻）
• 按优先级（最高 → 低）
• 按受派人或团队
• 按组件或史诗（如适用）

第 4 步：整理报告

根据受众选择合适的模板。模板位于 references/report-templates.md。

面向高管和交付经理

使用高管摘要格式：

• 简要说明总体状态（🟢 进展顺利 / 🟡 存在风险 / 🔴 受阻）
• 关键指标（总数、已完成、进行中、受阻）
• 3 项亮点（重大成果）
• 关键阻塞项及其影响
• 后续重点事项

保持简洁——最多 1–2 页。聚焦决策者关心的内容。

面向团队的报告

使用详细技术格式：

• 列出已完成的问题及其键值
• 列出进行中的问题及受派人和优先级
• 列出受阻的问题、阻塞项说明及所需采取的行动
• 风险和依赖项
• 下一阶段的重点事项

包含更多细节——团队需要了解问题级别的进展。

每日更新

使用每日站会格式：

• 昨天完成了什么
• 今天计划做什么
• 当前阻塞项
• 简要备注

保持简短——这是快速同步，而非全面分析。

步骤 5：发布到 Confluence

生成报告后，始终主动提出将其发布到 Confluence（除非用户明确表示不要发布）。

如果用户尚未提供 Confluence 详情，请询问：

• “您希望我将这份报告发布到 Confluence 吗？”
• “我应该使用哪个 Confluence 空间？”
• “是否应将其嵌套在某个指定的父页面下？”

使用 createConfluenceContent 工具发布报告。

撰写正文之前，请先加载撰写指南。getContentFormatGuide 不是主要工具，因此请通过 execute 运行（参见调用非主要工具）。 请注意，toolName 接受的是内容键 createConfluencePage，而不是即将调用的工具名称：

executeRead(   # or execute(...) if your client exposes a single execute tool
    name="getContentFormatGuide",
    inputs={"toolName": "createConfluencePage"}
)

即使指南加载失败，也绝不要跳过正文；先加载指南，再撰写完整正文。

然后加载空间说明。 空间可能包含持久有效的撰写指南；这些指南具有权威性，与默认撰写规则冲突时应以其为准。按以下规则判断：

1. 只有当针对目标空间内容的 getConfluenceContent 调用返回 metadata.hasSpaceInstructions=false 时，才跳过此步骤。
2. 否则——无论结果为 true 还是未知——都应在撰写前调用一次 getConfluenceSpace：

executeRead(   # or execute(...) if your client exposes a single execute tool
    name="getConfluenceSpace",
    cloudId="...",
    inputs={"spaceIdOrKey": "[space ID or key]"}
)

3. 应用返回的任何 spaceInstructions。如果成功响应中未包含该字段，则表示未配置说明；请使用默认规则撰写，不要因此受阻。

在任务剩余过程中复用该结果：不要再次对同一空间调用 getConfluenceSpace，也不要随后单独调用 getConfluenceSpaceInstructions。

创建页面：

createConfluenceContent(
    cloudId="[obtained from listConfluenceSpaces or URL]",
    parent={"spaceId": "[numerical space ID]"},
    contentType="page",
    title="[Project Name] - Status Report - [Date]",
    body={"format": "markdown", "value": "[formatted report]"}
)

若要将报告嵌套在现有页面下，请在 parent 中添加 parentContentId：

    parent={"spaceId": "[numerical space ID]", "parentContentId": "[parent page ID]"},

标题格式示例：

• “Project Phoenix - 每周状态 - 2025 年 12 月 3 日”
• “Engineering Sprint 23 - 状态报告”
• “Q4 Initiatives - 状态更新 - 第 49 周”

正文格式： 以 Markdown 编写报告内容，并将其作为 body={"format": "markdown", "value": ...} 传入，同时遵循 getContentFormatGuide 返回的规范。请使用：

• 标题（#、##、###）组织内容结构
• 项目符号列出条目
• 粗体（**text**）突出重点
• 必要时使用表格展示指标
• Jira 工单链接：PROJ-123

最佳实践：

• 在显眼位置注明报告日期
• 直接链接到相关 Jira 工单
• 为定期报告使用一致的命名规范
• 可考虑将报告放在“状态报告”父页面下，以便组织管理

查找合适的空间

如果用户未指定 Confluence 空间：

1. 使用 listConfluenceSpaces 列出可用空间。这不是主要工具，因此请通过 execute 运行：executeRead(name="listConfluenceSpaces", cloudId="...")
2. 查找与项目相关的空间（名称或键与项目匹配）
3. 如果不确定，请询问用户要使用哪个空间
4. 默认在最相关的团队或项目空间中创建

更新现有报告

如果要更新现有页面，而非创建新页面：

1. 获取当前页面内容。detail="full" 会返回正文（默认的 summary 仅返回标题、摘要和计数），而文档类型的响应会包含必须在更新时传回的 snapshotToken，以及步骤 3 所需的 metadata.hasSpaceInstructions：

getConfluenceContent(
    cloudId="...",
    content_id="123456",
    content_format="markdown",
    detail="full",
    include_metadata=True
)

2. 加载编辑所需的撰写指南（toolName 是内容键，而不是要调用的工具）：

executeRead(   # or execute(...) if your client exposes a single execute tool
    name="getContentFormatGuide",
    inputs={"toolName": "updateConfluencePage"}
)

3. 除非步骤 1 返回 metadata.hasSpaceInstructions=false，否则加载空间说明。如果本任务期间已加载该空间的说明，则复用已有结果：

executeRead(   # or execute(...) if your client exposes a single execute tool
    name="getConfluenceSpace",
    cloudId="...",
    inputs={"spaceIdOrKey": "[space ID or key]"}
)

4. 使用新内容更新页面。编辑文档时必须提供 snapshotToken——传入步骤 1 响应中的值。省略此项将导致更新失败：

updateConfluenceContent(
    cloudId="...",
    contentId="123456",
    snapshotToken="[snapshotToken from the step 1 response]",
    body={"format": "markdown", "value": "[updated report content]"},
    versionMessage="Updated with latest status - Dec 8, 2025"
)

并发说明：snapshotToken 会将你的编辑绑定到所读取的版本。不要在多次编辑中重复使用过期令牌；每次更新前，都应使用 getConfluenceContent 重新读取内容。

完整示例工作流

用户请求：“生成 Project Phoenix 的状态报告并发布到 Confluence”

第 1 步 - 确定范围：

• 项目：Phoenix（需要查找项目键）
• 时间段：上周（默认）
• 受众：未指定，假设为高管
• 目标位置：Confluence，需要查找合适的空间

第 2 步 - 查询 Jira：

# Find project key first
searchJiraIssuesUsingJql(
    cloudId="...",
    jql='project = "PHOENIX" OR project = "PHX"',
    maxResults=1
)

# Query completed issues
searchJiraIssuesUsingJql(
    cloudId="...",
    jql='project = "PHX" AND status = Done AND resolved >= -7d',
    maxResults=50
)

# Query blocked issues
searchJiraIssuesUsingJql(
    cloudId="...",
    jql='project = "PHX" AND status = Blocked',
    maxResults=50
)

# Query in-progress high priority
searchJiraIssuesUsingJql(
    cloudId="...",
    jql='project = "PHX" AND status IN ("In Progress", "In Review") AND priority IN (Highest, High)',
    maxResults=50
)

第 3 步 - 分析：

• 已完成 15 个问题（指标）
• 3 个严重阻塞项（关键洞察）
• 重大成果：API 集成已完成（亮点）

第 4 步 - 排版： 使用模板中的高管摘要格式。创建简洁的报告，包含指标、亮点和阻塞项。

第 5 步 - 发布：

# Find appropriate space (not a primary tool - run it through execute)
executeRead(name="listConfluenceSpaces", cloudId="...")

# Load authoring guidance before composing the body
executeRead(name="getContentFormatGuide", inputs={"toolName": "createConfluencePage"})

# Load space instructions (skip only if hasSpaceInstructions was false for this space)
executeRead(name="getConfluenceSpace", cloudId="...", inputs={"spaceIdOrKey": "PHX"})

# Create page
createConfluenceContent(
    cloudId="...",
    parent={"spaceId": "12345"},
    contentType="page",
    title="Project Phoenix - Weekly Status - Dec 3, 2025",
    body={"format": "markdown", "value": "[formatted markdown report]"}
)

优质报告技巧

以数据为依据：

• 纳入具体数字和指标
• 直接引用问题键
• 尽可能展示趋势（例如，“本周完成 15 个，上周完成 12 个”）

突出重要内容：

• 将最重要的信息放在开头
• 显著标出阻塞项
• 庆祝重要成果

确保可执行：

• 对于阻塞项，说明需要采取什么行动以及由谁采取
• 对于风险，提供缓解方案
• 对于优先事项，明确后续步骤

保持一致：

• 定期报告使用相同格式
• 保持结构可预测
• 纳入可按周比较的指标

提供背景信息：

• 链接到 Jira 以查看详情
• 说明阻塞项的影响
• 尽可能将工作与业务目标关联起来

资源

scripts/jql_builder.py

用于以编程方式构建 JQL 查询的 Python 工具。需要构建复杂或动态查询时请使用此工具。请导入并使用辅助函数，而不要手动拼接 JQL 字符串。

references/jql-patterns.md

状态报告常用 JQL 查询模式的快速参考。可用于标准查询，也可作为自定义查询的起点。

references/report-templates.md

适用于不同报告类型和受众的详细模板。请参考此文件，为报告选择合适的格式和结构。

---

调用非主要工具

Atlassian Rovo MCP 服务仅会在工具列表中直接公开少量主要工具。其他工具都位于目录中，需要通过元工具调用：

• discover — 不知道操作名称时，用自然语言描述目标。它会返回要使用的确切 name 和 inputs。如果某个操作已作为主要工具提供，请勿对其调用 discover。
• 执行系列工具 — 按名称运行目录中的操作。请查看工具列表：有些客户端会公开单个 execute，其他客户端则会公开 executeRead / executeWrite / executeDestructive，并要求选择与操作匹配的级别。参数完全相同：

executeRead(   # or execute(...) if your client exposes a single execute tool
  name="<operationName>",
  cloudId="...",
  inputs={"param": "value"}
)

重要规则：

• cloudId 是顶层参数，与 name 和 inputs 同级；绝不可将其放入 inputs。声明了 omitCloudId 的操作（例如 getContentFormatGuide）不需要 cloudId。
• **inputs 是扁平对象。**服务会自行将每个参数路由到路径、查询或请求正文。
• **使用实时工具架构中的确切参数名称。**无法识别的参数会被丢弃，而不是作为错误报告，因此参数名称错误会静默失败——调用会成功，但你的值会被忽略。如有疑问，请先查看架构或 discover 结果。
• 如果调用报告操作未知，请使用不同关键词运行 discover，并使用其返回的名称，而不要猜测。