requirements-gathering

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Requirements Gathering

需求收集

Gather and structure requirements from any source into a standardized brief that downstream skills (

schema-explorer

datasource-creator

report-creator

) can consume.

从任意来源收集并结构化需求，生成可供下游技能（

schema-explorer

、

datasource-creator

、

report-creator

）使用的标准化简报。

When to Use

使用场景

Before creating a report (
```
report-creator
```
invokes this as Phase 1)
Before creating a datasource (
```
datasource-creator
```
invokes this when requirements are unclear)
Whenever the user provides a work item ID, mockup, spec, or description and you need to extract structured requirements before building anything

创建报告之前（
```
report-creator
```
会将本技能作为第一阶段调用）
创建数据源之前（当需求不明确时，
```
datasource-creator
```
会调用本技能）
每当用户提供工作项ID、原型图、规格说明或描述，且需要先提取结构化需求再进行构建工作时

Output Contract

输出约定

Regardless of source, produce a requirements brief with these sections:

markdown

undefined

无论来源如何，生成的需求简报需包含以下部分：

markdown

undefined

Requirements Brief

Title: [name of the report/datasource/feature] Purpose: [1-2 sentence summary] Source: [work item #ID / user conversation / document / existing report]

Data Requirements

Fields with Semantic Roles

For each field, identify WHAT it is and WHERE it belongs:

Field	Semantic Role	Report Section / Usage
ownerName	Goods principal name	Shipper/Consignor header
accountName	Customer name	Consignee header
materialLookupCode	Product identifier	Line item grid
tareWeight	Packaging weight	Calculated: gross = raw + qty * tare

For each field, identify WHAT it is and WHERE it belongs:

Field	Semantic Role	Report Section / Usage
ownerName	Goods principal name	Shipper/Consignor header
accountName	Customer name	Consignee header
materialLookupCode	Product identifier	Line item grid
tareWeight	Packaging weight	Calculated: gross = raw + qty * tare

Entity Keywords

[List of OData entity search terms derived from requirements]

Layout Expectations

Report category: [Label / Official Documentation / Work Detail / Inventory-Operations]
- Labels: high visibility, scannable barcodes, tight margins
- Official Documentation: branded, legally compliant, standard margins
- Work Detail: key info only, minimal distractions
- Inventory/Operations: data comparison tables (consider if an app component would serve better)
Page size: [letter/legal/A4/custom]
Orientation: [portrait/landscape]
Key sections: [header, detail grid, footer, etc.]
Special elements: [barcodes, logos, signatures, images]

Report category: [Label / Official Documentation / Work Detail / Inventory-Operations]
- Labels: high visibility, scannable barcodes, tight margins
- Official Documentation: branded, legally compliant, standard margins
- Work Detail: key info only, minimal distractions
- Inventory/Operations: data comparison tables (consider if an app component would serve better)
Page size: [letter/legal/A4/custom]
Orientation: [portrait/landscape]
Key sections: [header, detail grid, footer, etc.]
Special elements: [barcodes, logos, signatures, images]

Business Rules

[Calculated fields with formulas]
[Conditional visibility rules]
[Date null-guard requirements]
[Filtering/exclusion rules]

[Calculated fields with formulas]
[Conditional visibility rules]
[Date null-guard requirements]
[Filtering/exclusion rules]

Parameters

[Input parameters with types]

[Input parameters with types]

Reference Materials

[List of attachments, screenshots, documents consulted]

undefined

[List of attachments, screenshots, documents consulted]

undefined

Source Routing

来源处理流程

DevOps work item

DevOps工作项

When the user provides a work item ID or URL:

Invoke the
devops-requirements
skill — it handles fetching, relations, attachments, and extraction
Enhance the output with semantic field mapping (see below)
Save the brief to the artifact directory

当用户提供工作项ID或URL时：

调用
devops-requirements
技能——该技能负责获取工作项、关联内容、附件并提取信息
增强输出内容——添加语义字段映射（见下文）
将简报保存至制品目录

Mockup or screenshot

原型图或截图

When the user provides an image (mockup, screenshot, PDF):

Read every visible element — labels, column headers, data values, section boundaries, logos, barcodes
Map labels to data fields — each visible label implies a field. "SHIPPER" is not just text, it's a data source (who is the shipper entity?)
Identify sections — header, address blocks, detail grid, footer, signatures
Ask clarifying questions about ambiguous elements before finalizing the brief

当用户提供图片（原型图、截图、PDF）时：

识别所有可见元素——标签、列标题、数据值、区域边界、Logo、条形码
将标签映射至数据字段——每个可见标签都对应一个字段。例如“SHIPPER”不只是文本，而是一个数据源（发货方实体是谁？）
识别区域划分——页眉、地址块、详情表格页脚、签名区等
针对模糊元素询问澄清问题，再最终确定简报

Natural language description

自然语言描述

When the user describes what they want in conversation:

Extract nouns as candidate entities — "customer shipping address" → Account, ShippingAddress
Extract qualifiers as candidate fields — "the warehouse phone number" → Warehouse.Contact.Phone
Ask structured questions to fill gaps:
- What data does this show? (entities + fields)
- Who uses this? (determines layout: print vs screen, page size)
- What filters/parameters drive it? (input params)
- Are there calculations or business rules? (expressions)
- Is there a similar existing report? (reference)
Present the draft brief for confirmation before proceeding

当用户通过对话描述需求时：

提取名词作为候选实体——例如“客户收货地址”→ Account、ShippingAddress
提取限定词作为候选字段——例如“仓库电话号码”→ Warehouse.Contact.Phone
提出结构化问题以填补信息空白：
- 该需求展示哪些数据？（实体+字段）
- 谁会使用该制品？（决定布局：打印版还是屏幕版、页面尺寸）
- 哪些筛选条件/参数会影响它？（输入参数）
- 是否存在计算逻辑或业务规则？（表达式）
- 是否有类似的现有报告？（参考资料）
提交草稿简报供确认，之后再继续推进

Existing report (.rdl or .rdlx-json)

现有报告（.rdl或.rdlx-json格式）

When the user provides an existing report file:

For .rdlx-json: Use
```
dxs report inspect
```
to extract structure, DataSets, field names, and expressions
For .rdl (SSRS): Scan for
```
<CommandText>
```
elements containing SQL — the SELECT columns and FROM/JOIN tables map to OData entities and fields
Map extracted fields to semantic roles based on element names and positions in the layout

当用户提供现有报告文件时：

对于.rdlx-json格式：使用
```
dxs report inspect
```
提取结构、数据集、字段名称和表达式
对于.rdl（SSRS）格式：扫描包含SQL的
```
<CommandText>
```
元素——SELECT列和FROM/JOIN表对应OData实体和字段
将提取的字段映射至语义角色——依据元素名称和在布局中的位置进行映射

Document or spec

文档或规格说明

When the user provides a document (Word, PDF, Excel):

Extract field lists — look for tables, SQL queries, column definitions
Extract layout sketches — any visual representation of the output
Extract business rules — formulas, conditions, filtering logic

当用户提供文档（Word、PDF、Excel）时：

提取字段列表——查找表格、SQL查询、列定义
提取布局草图——任何关于输出的可视化表示
提取业务规则——公式、条件、筛选逻辑

Semantic Field Mapping

语义字段映射

This is the critical step that prevents downstream errors. After extracting raw fields from any source, assign each field a semantic role — what it means in the domain context.

How to assign roles:

From SQL field names: Read prefixes as domain clues
- ```
owner*
```
  → goods principal / shipper (in BOL context)
- ```
account*
```
  → customer / bill-to party
- ```
shipTo*
```
  → delivery destination / consignee
- ```
warehouse*
```
  → facility / 3PL location
- ```
carrier*
```
  → transport provider
- ```
material*
```
  /
```
lot*
```
  → inventory item details
- ```
order*
```
  → order-level data (reference numbers, dates, notes)
From mockup labels: Map visual labels to data entities
- "SHIPPER/CONSIGNOR" → Owner entity (NOT Account)
- "CONSIGNED TO" → Account / Ship-To entity
- "CARRIER" → Carrier entity
- "FREIGHT BILL NUMBER" → may be BOL, or may be a reference number — ask
From natural language: Map described concepts to entities
- "the customer's address" → Account.Address or ShipToContact.Address
- "who shipped it" → Owner (the goods principal, not the carrier)
When ambiguous: Flag the ambiguity and ask the user. Do NOT guess — a wrong semantic assignment cascades into wrong datasource fields and wrong report layout.

这是避免下游错误的关键步骤。从任意来源提取原始字段后，需为每个字段分配语义角色——即该字段在业务领域中的含义。

分配角色的方法：

从SQL字段名称提取线索：前缀可作为领域提示
- ```
owner*
```
  → 货主/发货方（在提单场景中）
- ```
account*
```
  → 客户/账单接收方
- ```
shipTo*
```
  → 交货目的地/收货方
- ```
warehouse*
```
  → 仓储设施/第三方物流地点
- ```
carrier*
```
  → 运输提供商
- ```
material*
```
  /
```
lot*
```
  → 库存商品详情
- ```
order*
```
  → 订单级数据（参考编号、日期、备注）
从原型图标签映射：将可视化标签对应至数据实体
- "SHIPPER/CONSIGNOR" → Owner实体（而非Account）
- "CONSIGNED TO" → Account / Ship-To实体
- "CARRIER" → Carrier实体
- "FREIGHT BILL NUMBER" → 可能是提单编号或参考编号——需询问用户确认
从自然语言描述映射：将描述的概念对应至实体
- "客户的地址" → Account.Address 或 ShipToContact.Address
- "谁发货的" → Owner（货主，而非运输商）
存在歧义时：标记歧义并询问用户。请勿猜测——错误的语义分配会导致下游技能选择错误的数据源字段和报告布局。

Anti-Patterns

反模式

Flat field list without roles — listing fields without semantic mapping causes downstream skills to guess which field goes where. Always assign roles.
Skipping fields that seem "obvious" —
```
packUOM
```
,
```
tareWeight
```
,
```
vlDescription
```
may not be in the report title or main columns, but they're required. List ALL fields from the source.
Assuming SQL = OData — SQL views pre-flatten joined data. The same data in OData may require multiple
```
$expand
```
levels or linked datasources. Note complex join paths in the brief.
Generic legal text — if the source includes specific legal language (e.g., carrier liability clauses), capture it verbatim. Don't substitute generic boilerplate.
Ignoring images/signatures — if the source shows a logo, signature, or image field, note it. These require special handling (embedded images, database-sourced images, or flow datasources).

无角色的扁平字段列表——仅列出字段而不进行语义映射会导致下游技能猜测字段的用途。务必为所有字段分配角色。
忽略看似“显而易见”的字段——
```
packUOM
```
、
```
tareWeight
```
、
```
vlDescription
```
可能不在报告标题或主列中，但它们是必需的。请列出来源中的所有字段。
假设SQL等同于OData——SQL视图会预先扁平化关联数据。而OData中的相同数据可能需要多层
```
$expand
```
或关联数据源。请在简报中注明复杂的关联路径。
通用法律文本——如果来源包含特定法律语言（例如运输商责任条款），请原文保留。不要替换为通用模板文本。
忽略图片/签名——如果来源显示Logo、签名或图片字段，请予以记录。这些元素需要特殊处理（嵌入图片、数据库源图片或流数据源）。