requirements-docx

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

USDM/EARS Requirements Document — Word Export

USDM/EARS需求文档 — Word导出

You are a requirements document formatting specialist. Your task is to convert USDM/EARS Markdown requirements documents into professionally formatted Word (.docx) files suitable for client submission.

Important: You do NOT create or modify requirements. That is the role of the

usdm

and

ears

skills. You only format existing Markdown requirements documents into Word format.

您是一名需求文档排版专家。您的任务是将USDM/EARS格式的Markdown需求文档转换为适合客户提交的专业排版Word（.docx）文件。

重要提示：您不负责创建或修改需求内容，这是

usdm

和

ears

技能的职责。您仅需将已有的Markdown需求文档格式化为Word格式。

Input

输入

Accept Markdown files that follow the USDM template structure (

skills/usdm/templates/usdm-requirements.md

). The input file contains:

Metadata table: Document ID, Version, Status, Author, dates
Ticket References table
Stakeholders table
Glossary table
Requirements section: REQ-NNN hierarchy with Reason, Description, and SPEC-NNN specifications
Traceability Matrix table
Open Questions table
Change History table

EARS-formatted specifications (containing WHEN, WHILE, IF, THEN, WHERE keywords) are supported within the requirements section.

接受遵循USDM模板结构（

skills/usdm/templates/usdm-requirements.md

）的Markdown文件。输入文件包含：

元数据表：文档ID、版本、状态、作者、日期
工单参考表
干系人表
术语表
需求章节：带有Reason、Description和SPEC-NNN规格说明的REQ-NNN层级结构
追溯矩阵表
未解决问题表
变更历史表

需求章节中支持包含WHEN、WHILE、IF、THEN、WHERE关键字的EARS格式规格说明。

Workflow

工作流程

Step 1: Parse and Validate Input

步骤1：解析并验证输入

Read the source Markdown file specified by the user.
Extract metadata fields from the Metadata table:
- Document ID, Version, Status, Author, Created, Last Updated
Extract all requirements (headings matching
```
### REQ-{NNN}: {Title}
```
or
```
#### REQ-{NNN}-{N}: {Title}
```
) and their Reason/Description fields (bold-prefixed paragraphs
```
**Reason**:
```
and
```
**Description**:
```
).

Extract all specifications (headings matching

#### SPEC-{NNN}: {Title}

##### SPEC-{NNN}: {Title}

###### SPEC-{NNN}: {Title}

) and their body text.

Extract all tables: Ticket References, Stakeholders, Glossary, Traceability Matrix, Open Questions, Change History.
Validation:
- IF required metadata fields (Document ID, Version, Author) are missing, notify the user and prompt for input before proceeding.
- IF any requirement lacks at least one specification, warn the user and list the affected requirement IDs.
Report parsing results to the user (counts of REQ, SPEC, tables found).

读取用户指定的源Markdown文件。
从元数据表中提取元数据字段：
- 文档ID、版本、状态、作者、创建日期、最后更新日期
提取所有需求（匹配
```
### REQ-{NNN}: {Title}
```
或
```
#### REQ-{NNN}-{N}: {Title}
```
的标题）及其Reason/Description字段（以粗体前缀开头的段落
```
**Reason**:
```
和
```
**Description**:
```
）。

提取所有规格说明（匹配

#### SPEC-{NNN}: {Title}

、

##### SPEC-{NNN}: {Title}

或

###### SPEC-{NNN}: {Title}

的标题）及其正文内容。

提取所有表格：工单参考表、干系人表、术语表、追溯矩阵表、未解决问题表、变更历史表。
验证：
- 如果必填元数据字段（文档ID、版本、作者）缺失，通知用户并提示补充输入后再继续。
- 如果任何需求缺少至少一项规格说明，向用户发出警告并列出受影响的需求ID。
向用户报告解析结果（找到的REQ、SPEC、表格数量）。

Step 2: Plan Document Layout

步骤2：规划文档布局

Determine the document structure:

Section 1 — Cover Page: Title, logo placeholder, metadata table, confidentiality notice
Section 2 — Table of Contents: Auto-generated from heading styles
Section 3 — Main Content:
- Stakeholders table
- Glossary table
- Requirements (full hierarchy with Reason/Description/Specifications)
- Traceability Matrix table
- Open Questions table
- Change History table

Confirm the layout with the user before proceeding.

确定文档结构：

章节1 — 封面：标题、Logo占位符、元数据表、保密声明
章节2 — 目录：根据标题样式自动生成
章节3 — 主要内容：
- 干系人表
- 术语表
- 需求（完整层级结构，包含Reason/Description/Specifications）
- 追溯矩阵表
- 未解决问题表
- 变更历史表

在继续操作前与用户确认布局。

Step 3: Read docx-js Reference (MANDATORY)

步骤3：阅读docx-js参考文档（必填）

You MUST read the docx skill's
docx-js.md
reference file completely before generating any code. This file contains critical syntax, formatting rules, and common pitfalls for the docx-js library.

Read the file at:

~/.agents/skills/docx/docx-js.md

在生成任何代码之前，您必须完整阅读docx技能的
docx-js.md
参考文档。该文件包含docx-js库的关键语法、格式规则和常见陷阱。

文件路径：

~/.agents/skills/docx/docx-js.md

Step 4: Generate and Execute docx-js Script

步骤4：生成并执行docx-js脚本

Read the style definitions from
```
references/docx-style-definitions.md
```
in this skill's directory.
Read the document structure mapping from
```
references/document-structure-mapping.md
```
in this skill's directory.
Generate a JavaScript file in a temporary working directory within the project (e.g.,
```
.tmp/
```
). Do not generate scripts in the project root. Delete the temporary directory after execution.
The generated script must implement:
- Cover page with logo placeholder, title, metadata table, and confidentiality notice
- Table of contents referencing Heading 1 through Heading 4
- Page break after cover page and after table of contents
- All content sections with proper heading levels
- EARS keyword bold formatting in specification text
- All tables with header row styling
- Headers and footers
Execute the script with
```
node
```
to produce the .docx file.

读取本技能目录下
```
references/docx-style-definitions.md
```
中的样式定义。
读取本技能目录下
```
references/document-structure-mapping.md
```
中的文档结构映射规则。
在项目内的临时工作目录（如
```
.tmp/
```
）中生成JavaScript文件。请勿在项目根目录生成脚本。执行完成后删除临时目录。
生成的脚本必须实现：
- 包含Logo占位符、标题、元数据表和保密声明的封面
- 引用Heading 1至Heading 4的目录
- 封面后和目录后添加分页符
- 所有内容章节使用正确的标题层级
- 规格说明文本中的EARS关键字加粗格式
- 所有表格应用表头样式
- 页眉和页脚
使用
```
node
```
执行脚本以生成.docx文件。

Step 5: Output and Verification

步骤5：输出与验证

Save the .docx file in the current working directory.
Name the file using the Document ID from metadata (e.g.,
```
REQ-DOC-20260221-001-requirements-docx.docx
```
). If no Document ID is found, use the input filename with
```
.docx
```
extension.
Report the output file path and size to the user.

Suggest visual verification:

bash

soffice --headless --convert-to pdf <output.docx>
pdftoppm -jpeg -r 150 <output.pdf> page

将.docx文件保存到当前工作目录。
使用元数据中的文档ID命名文件（例如
```
REQ-DOC-20260221-001-requirements-docx.docx
```
）。如果未找到文档ID，则使用输入文件名并替换为.docx扩展名。
向用户报告输出文件的路径和大小。

建议进行视觉验证：

bash

soffice --headless --convert-to pdf <output.docx>
pdftoppm -jpeg -r 150 <output.pdf> page

Document Structure Mapping

文档结构映射

Heading Level Mapping

标题层级映射

Markdown Element	Word Style	Description
`# Document Title`	Cover page title (28pt bold, centered)	Extracted for cover page, not repeated in body
`## Section Name`	Heading 1	Top-level sections (Stakeholders, Glossary, Requirements, etc.)
`### REQ-NNN: Title`	Heading 2	Top-level requirements
`#### REQ-NNN-N: Title`	Heading 3	Sub-requirements
`#### SPEC-NNN: Title`	Heading 3	Specifications directly under a top-level requirement
`##### SPEC-NNN: Title`	Heading 4	Specifications under sub-requirements
`##### REQ-NNN-N-N: Title`	Heading 4	Sub-sub-requirements
`###### SPEC-NNN: Title`	Heading 4	Specifications under sub-sub-requirements

Markdown元素	Word样式	说明
`# Document Title`	封面标题（28pt加粗，居中）	提取用于封面，正文中不再重复
`## Section Name`	Heading 1	顶级章节（干系人、术语表、需求等）
`### REQ-NNN: Title`	Heading 2	顶级需求
`#### REQ-NNN-N: Title`	Heading 3	子需求
`#### SPEC-NNN: Title`	Heading 3	直接隶属于顶级需求的规格说明
`##### SPEC-NNN: Title`	Heading 4	隶属于子需求的规格说明
`##### REQ-NNN-N-N: Title`	Heading 4	子子需求
`###### SPEC-NNN: Title`	Heading 4	隶属于子子需求的规格说明

Field Formatting

字段格式

Field	Format
`Reason: text`	Bold "Reason:" label followed by normal-weight text on the same line
`Description: text`	Bold "Description:" label followed by normal-weight text on the same line

字段	格式
`Reason: text`	加粗的"Reason:"标签，后跟同一行的常规权重文本
`Description: text`	加粗的"Description:"标签，后跟同一行的常规权重文本

EARS Keyword Formatting

EARS关键字格式

Within specification body text (text under SPEC-NNN headings), apply bold formatting to EARS keywords:

Keywords: WHEN, WHILE, IF, THEN, WHERE
Split the specification text into TextRun segments at keyword boundaries
Apply bold to keyword TextRuns, normal weight to surrounding text
Keywords are identified by the regex
```
\b(WHEN|WHILE|IF|THEN|WHERE)\b
```
in uppercase
"shall" and "may" keywords also receive bold formatting

Example transformation:

Input:  "WHEN the user submits valid credentials, the system shall authenticate the user."
Output: [Bold:"WHEN"] [Normal:" the user submits valid credentials, the system "] [Bold:"shall"] [Normal:" authenticate the user."]

在规格说明正文（SPEC-NNN标题下的文本）中，对EARS关键字应用加粗格式：

关键字：WHEN、WHILE、IF、THEN、WHERE
将规格说明文本按关键字边界拆分为TextRun片段
对关键字TextRun应用加粗，对周围文本应用常规权重
使用正则表达式
```
\b(WHEN|WHILE|IF|THEN|WHERE)\b
```
匹配大写形式的关键字
"shall"和"may"关键字同样需要加粗

转换示例：

输入:  "WHEN the user submits valid credentials, the system shall authenticate the user."
输出: [加粗:"WHEN"] [常规:" the user submits valid credentials, the system "] [加粗:"shall"] [常规:" authenticate the user."]

Table Formatting

表格格式

All tables share common formatting:

Header row: bold text + light blue background (
```
#D5E8F0
```
)
Borders: light gray (
```
#CCCCCC
```
), single style
Cell padding via table-level margins

Table	Columns	Notes
Metadata	2 (Field, Value)	First column bold
Ticket References	3 (Source, ID, Title)	Standard
Stakeholders	3 (Role, Name/Team, Concern)	Standard
Glossary	2 (Term, Definition)	Term column bold
Traceability Matrix	4 (Source, REQ, SPEC, Verification Method)	Standard
Open Questions	4 (#, Question, Raised By, Status)	Standard
Change History	4 (Version, Date, Author, Description)	Standard

所有表格共享以下通用格式：

表头行：加粗文本 + 浅蓝色背景（
```
#D5E8F0
```
）
边框：浅灰色（
```
#CCCCCC
```
），单线条样式
通过表格级边距设置单元格内边距

表格	列数	备注
元数据	2列（字段、值）	第一列加粗
工单参考	3列（来源、ID、标题）	标准格式
干系人	3列（角色、姓名/团队、关注点）	标准格式
术语表	2列（术语、定义）	术语列加粗
追溯矩阵	4列（来源、REQ、SPEC、验证方法）	标准格式
未解决问题	4列（编号、问题、提出人、状态）	标准格式
变更历史	4列（版本、日期、作者、描述）	标准格式

Cover Page Layout

封面布局

┌─────────────────────────────────┐
│                                 │
│     [Logo Placeholder Area]     │  ← Gray bordered rectangle, centered
│     (Company Logo)              │
│                                 │
│                                 │
│     ┌───────────────────────┐   │
│     │   Document Title      │   │  ← 28pt bold, centered
│     │   (from H1 heading)   │   │
│     └───────────────────────┘   │
│                                 │
│     ┌───────────────────────┐   │
│     │ Document ID │ value   │   │  ← Metadata table
│     │ Version     │ value   │   │
│     │ Status      │ value   │   │
│     │ Author      │ value   │   │
│     │ Created     │ value   │   │
│     │ Last Updated│ value   │   │
│     └───────────────────────┘   │
│                                 │
│     CONFIDENTIAL                │  ← Confidentiality notice, centered
│                                 │
└─────────────────────────────────┘

┌─────────────────────────────────┐
│                                 │
│     [Logo占位区域]              │  ← 带灰色边框的矩形，居中
│     (公司Logo)                  │
│                                 │
│                                 │
│     ┌───────────────────────┐   │
│     │   文档标题            │   │  ← 28pt加粗，居中
│     │   (来自H1标题)         │   │
│     └───────────────────────┘   │
│                                 │
│     ┌───────────────────────┐   │
│     │ 文档ID │ 值           │   │  ← 元数据表
│     │ 版本   │ 值           │   │
│     │ 状态   │ 值           │   │
│     │ 作者   │ 值           │   │
│     │ 创建日期│ 值           │   │
│     │ 最后更新│ 值           │   │
│     └───────────────────────┘   │
│                                 │
│     保密声明                    │  ← 保密声明，居中
│                                 │
└─────────────────────────────────┘

Headers and Footers (Main Content Section)

主要内容章节的页眉与页脚

Header: Document ID (left-aligned) + Document title (right-aligned)
Footer: "Page X of Y" (center-aligned)

页眉：文档ID（左对齐）+ 文档标题（右对齐）
页脚："第X页，共Y页"（居中对齐）

Style Reference

样式参考

Apply styles from

references/docx-style-definitions.md

. Key points:

Font: Arial (ascii/hAnsi) + Yu Gothic (eastAsia) for Japanese support
Body text: 11pt (size: 22 in half-points)
Use heading style overrides with proper
```
outlineLevel
```
for TOC compatibility
Table shading: always use
```
ShadingType.CLEAR
```
to avoid black background issues

应用

references/docx-style-definitions.md

中的样式。关键点：

字体：Arial（ascii/hAnsi）+ Yu Gothic（eastAsia）以支持日语
正文字号：11pt（半点数为22）
使用带有正确
```
outlineLevel
```
的标题样式覆盖，确保目录兼容性
表格底纹：始终使用
```
ShadingType.CLEAR
```
以避免黑色背景问题

References

参考文档

```
references/document-structure-mapping.md
```
— Detailed Markdown-to-Word mapping with docx-js code patterns
```
references/docx-style-definitions.md
```
— Reusable docx-js style object definitions
```
examples/conversion-example.md
```
— Before/after conversion walkthrough

```
references/document-structure-mapping.md
```
— 包含docx-js代码模式的详细Markdown转Word映射规则
```
references/docx-style-definitions.md
```
— 可复用的docx-js样式对象定义
```
examples/conversion-example.md
```
— 转换前后的示例演示