devops-requirements

DevOps 需求提取

从 Azure DevOps 工作项中提取并整理可执行的需求，形成结构化需求简报。

输入 / 输出

• 输入： 工作项 ID 或 Azure DevOps URL
• 输出： 需求简报（Markdown 格式，可在上下文中提供或保存到产物目录）

适用场景

需要从 DevOps 工作项中提取结构化信息时，可使用此技能：

• 获取工作项的描述、设计字段和验收标准
• 查看父子关系并下载附件
• 根据工作项内容整理需求简报

此技能负责提取和整理信息，不会创建报告、数据源或其他产物。如果目标是根据工作项创建内容，请使用相应的创建技能作为入口；需要工作项数据时，该技能会调用此技能。

步骤 1：获取工作项

dxs devops workitem <ID> --full --expand All

--full 可避免长字段被截断。--expand All 会包含关联关系（父项、子项、附件）。

需要提取的关键字段：

字段	说明
title	报告名称和用途
description	高层需求，通常包含预期输出的嵌入式截图
design	详细规格，例如 SQL 查询、列清单、业务规则。这通常是字段和数据需求最丰富的来源
relations.parent	更广泛的项目背景（如需了解背景，可获取父项）
relations.children	实施子任务，可能包含其他规格
relations.attachments	现有报告、示例输出 PDF、BRD
tags	Sprint / 优先级背景

description 和 design 字段会自动从 HTML 转换为 Markdown。对于较长的设计字段，请查找 SQL SELECT 语句和列清单，它们可直接映射到架构发现所需的 OData 字段。

步骤 2：查看关联关系

向用户展示工作项的关联关系：

This work item has:
- Parent: #218666
- Children: #218813
- Attachments: 4 files (ValleyWarehouseReceiptInvoice.rdlx-json, Order 96269-20250041 - Receiving report.pdf, ...)

Would you like me to fetch any of the child items for additional context?

要批量获取选定的子项：

dxs devops workitems <ID1>,<ID2> --description --discussions

--description 会包含完整描述；--discussions 会包含评论 / 历史记录。每次请求最多可获取 200 个条目。

不要自动遍历所有子项——请询问用户哪些子项与需求相关。类型为“Wavelength Component”的子项通常包含实施细节，而“Bug”或“Task”类型的子项可能与报告设计无关。

临时查询：dxs devops wiql（dxs ≥ 0.4.18）

当所需工作项无法从已有 ID 访问时，例如“此区域路径下所有 Active 项”“分配给我的项目”或“#218666 下的整个层级”，请直接运行 WIQL，而不要猜测 ID 或翻查 devops search 的分页结果：

# Flat: one row per work item. Columns named in SELECT are fetched for each match.
dxs devops wiql "SELECT [System.Id],[System.Title],[System.State] FROM WorkItems \
  WHERE [System.State] = 'Active' ORDER BY [System.ChangedDate] DESC" --limit 25

# Tree / one-hop: one row per source→target link, target fields merged in.
dxs devops wiql "SELECT [System.Id],[System.Title] FROM WorkItemLinks \
  WHERE [Source].[System.Id] = 218666 \
    AND [System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward' \
  MODE (Recursive)" --project FootPrint

-Q/--query-file 可从文件读取较长的查询；如果只需要 ID 以供 dxs devops workitems 使用，--ids-only 可跳过字段获取。请对照 metadata.total_count（查询匹配到的数量）与 metadata.count（应用 --limit 后返回的数量，默认值为 200），并检查 truncated——结果受上限限制时并不完整；对于返回的结果，同样应遵循“询问用户哪些子项与需求相关”的规则。

步骤 3：与用户确认范围

在下载附件或整理需求简报之前，请先向用户确认需要关注的内容。 工作项中的附件、评论和设计说明会随时间不断累积，其中一些可能已过时、关联错误，或完全属于另一份报告。

先提供摘要并询问：

This work item has:
- Description: [1-sentence summary]
- Design field: [1-sentence summary — e.g., "SQL views for 3 datasets"]
- Attachments: [list filenames]
- Children: [list if any]

Which of these should I focus on for the report requirements?
Are any of the attachments not relevant to this report?

重要原因： 工作项可能包含其他相关报告的附件、与当前需求不符的示例 PDF，或已被取代的设计说明。将错误的附件用作布局参考，可能会使整个设计偏离方向。务必先让用户确认，再将任何附件视为权威依据。

第 4 步：下载附件

列出附件：

dxs devops attachments <ID>

按索引（更快）或文件名下载：

dxs devops attachments <ID> --download 1 --out <artifact_dir>/requirements/report.rdlx-json
dxs devops attachments <ID> --download "Valley Cold HC BRD.pdf" --out <artifact_dir>/requirements/brd.pdf

要下载哪些附件（用户确认相关性后）：

扩展名	操作	原因
.rdlx-json	下载并读取	现有报表——提取布局、DataSet 和字段映射
.rdl	下载并读取	SSRS 源文件——提取用于迁移的 SQL 查询和字段映射
.pdf	仅下载	可能与当前报表匹配，也可能不匹配——用作布局参考前先询问用户
.docx、.xlsx	如果是 BRD/规格说明则下载	可能包含详细字段列表或业务规则
.png、.jpg	跳过	通常是描述中已显示的嵌入式截图

对于下载的 .rdlx-json 文件，使用 dxs report inspect 快速了解结构：

dxs report inspect <artifact_dir>/requirements/report.rdlx-json

对于 .rdl 文件（SSRS XML），查找包含 SQL 的 <CommandText> 元素——SELECT 列以及 FROM/JOIN 表对应 OData 实体和字段。

如果 PDF 读取失败（例如缺少 poppler）：在需求简报中将这些文件标记为“已下载但无法读取”，并根据工作项的 description 和 design 字段继续工作，这些字段通常包含最具可操作性的信息。对于 .pdf 示例输出，请让用户口头描述预期布局，作为备用方案。无论如何都要将 PDF 下载到制品目录——用户可以手动查看。

第 5 步：编写需求简报

收集工作项数据和附件后，编写需求简报。该简报将用于下游技能（例如 schema-explorer、datasource-creator、report-creator）。

模板：

## Requirements Brief

**Report:** [title from work item]
**Purpose:** [1-2 sentence summary from description]
**Work Item:** #[ID] ([state])

### Data Requirements
- **Primary entity:** [derived from SQL FROM clause or description]
- **Key fields:** [from SQL SELECT or design field]
- **Filters/parameters:** [from SQL WHERE or description]
- **Related entities:** [from SQL JOINs or $expand needs]

### Filtering & Exclusion Rules
- [Extract EVERY filtering rule from the design notes, SQL WHERE clauses, and business requirements]
- [For each rule, note the original SQL/description AND the proposed OData equivalent]
- [Flag rules involving collection checks (subqueries) — these likely need lambda operators: `any()`/`all()`]
- [Flag rules involving string patterns (LIKE) — these likely need `startswith`/`endswith`/`contains`]
- [Example: "Exclude -10 locations in zones 04-06" → `not (endswith(Name,'-10') and (startswith(Name,'04') or ...))` ]

### Layout Expectations
- **Page size:** [from existing report or description]
- **Orientation:** [portrait/landscape]
- **Key sections:** [header, detail grid, footer, etc.]
- **Special elements:** [barcodes, logos, multi-column layout]

### Entity Keywords for Schema Search
[List of OData entity search terms derived from SQL table names or description nouns]

### Reference Materials
- [List downloaded attachments and what each provides]

如果启用了制品，将简报保存到 <artifact_dir>/requirements/requirements-brief.md。

反模式

• 不要将工作项原始内容直接倾倒到上下文中——总结描述和设计字段，只提取可操作的内容（字段列表、SQL、布局规格）
• 不要自动获取整个工作项树——父项和子项可能无关；请询问用户
• 不要跳过 design 字段——其中通常包含最详细的规格，包括可映射到 OData 字段的精确 SQL 查询
• 不要忽略现有的 .rdlx-json 附件——它们提供具体的字段映射和布局，可加快架构发现和原型设计