customer-card-render

客户卡片渲染技能

将规范的 Design Thinking Markdown 文档转换为 PowerPoint 技能的 content.yaml 幻灯片定义，并通过共享的 PowerPoint 构建管线生成最终演示文稿。

概述

此技能是实验性 PowerPoint 技能的姊妹技能，负责 Design Thinking 专属的映射层：从规范的 Markdown 文档中提取章节，并填充由模板驱动的 content.yaml 文件。PowerPoint 技能则负责布局渲染、主题设置、导出和验证。

将这些职责分开意味着：

• 客户卡片映射逻辑独立于通用 PowerPoint 功能。
• 此技能可以单独纳入软件包。
• 此处不会重新实现布局基元、Invoke-PptxPipeline.ps1、主题设置和验证行为。

如需完整的 PowerPoint 管线文档，请按名称激活 powerpoint 技能。如果无法解析该技能，请告知用户管线文档和构建行为不可用，并停止操作，而不要在此处重新实现这些功能。

先决条件

• Python 3.11+

• uv 包管理器，通过会验证下载内容与已发布哈希值是否匹配的包管理器安装：

  # Windows
  winget install --id astral-sh.uv -e
  
  # macOS / Linux (Homebrew)
  brew install uv
  

  若要从发行归档安装，请从 uv 发行页面下载，并在解压前将其与对应的 .sha256 文件进行校验。

• 实验性 powerpoint 技能，需按名称激活，以执行 Invoke-PptxPipeline.ps1 构建步骤。如果无法解析该技能，请告知用户构建步骤不可用，并停止操作。

目录结构

.github/skills/experimental/customer-card-render/
├── SKILL.md
├── pyproject.toml
├── references/
│   └── mapping-spec.md
├── scripts/
│   └── generate_cards.py
├── templates/
│   ├── global-style.yaml
│   ├── persona.content.yaml
│   ├── problem.content.yaml
│   ├── scenario.content.yaml
│   ├── use-case-slide1.content.yaml
│   ├── use-case-slide2.content.yaml
│   ├── use-case-slide3.content.yaml
│   └── vision.content.yaml
└── tests/
    ├── fuzz_harness.py
    └── test_generate_cards.py

支持的文档类型

文档类型	幻灯片布局
愿景陈述	单页幻灯片
问题陈述	单页幻灯片
场景	单页幻灯片
用例	4 页（见下文）
用户画像	单页幻灯片

用例 4 页布局

每个用例扩展为连续的 4 页幻灯片，每页包含不同的部分：

幻灯片	内容
幻灯片 1	用例描述、用例概览、业务价值、主要用户
幻灯片 2	次要用户、前提条件、步骤、数据要求
幻灯片 3	设备要求、运行环境、成功标准、痛点
幻灯片 4	扩展内容、证据

卡片按文档类型排序（愿景 → 问题 → 场景 → 用例 → 用户画像），每种类型内再按标题的字母顺序排序。每个用例连续显示为 4 页幻灯片（第 N 页、第 N+1 页、第 N+2 页、第 N+3 页）。

两步命令流程

步骤 1：根据规范的 Markdown 生成幻灯片 YAML

python "<customer-card-render-skill-root>/scripts/generate_cards.py" \
  --canonical-dir .copilot-tracking/dt/<project-slug>/canonical \
  --output-dir .copilot-tracking/dt/<project-slug>/render/content

运行命令前，请根据已加载的技能位置解析 <customer-card-render-skill-root>。

generate_cards.py CLI 参考

标志	必填	默认值	描述
--canonical-dir	否	<skill-root>/canonical	包含规范 DT Markdown 文件的目录
--output-dir	否	<skill-root>/scripts/content	写入生成的 content.yaml 文件的目录
-v, --verbose	否	—	启用调试级别日志记录

该脚本会读取 --canonical-dir 中的每个 Markdown 文件，根据 frontmatter 检测产物类型，提取必需章节，并生成 content.yaml 文件。Vision、Problem、Scenario 和 Persona 产物各生成一张幻灯片。Use Case 产物会为每个用例生成连续的 4 张幻灯片。

有关章节到字段的映射约定以及 Use Case 的 4 张幻灯片布局详情，请参阅 references/mapping-spec.md。

步骤 2：使用 PowerPoint 技能管线构建 PPTX

按名称激活 powerpoint 技能，并将以下三个输入交给该技能进行构建：

• 内容目录：.copilot-tracking/dt/<project-slug>/render/content
• 样式路径：.copilot-tracking/dt/<project-slug>/render/content/global/style.yaml
• 输出路径：.copilot-tracking/dt/<project-slug>/render/output/customer-cards.pptx

powerpoint 技能负责管理 Invoke-PptxPipeline.ps1 编排器、其参数参考、模板用法、验证和导出选项，并通过 uv sync 自动设置虚拟环境和安装依赖。如果该技能不可用，请告知用户无法运行构建步骤并停止，不要从猜测的位置调用管线。

DT Coach 集成

dt-coaching-foundation 技能的 canonical-deck 参考为 Design Thinking 辅导 Agent 提供可选的工作流集成。用户选择启用后，辅导 Agent 会在方法流程的退出节点提供构建客户卡片的选项。上述两条命令会作为该工作流的一部分运行，并根据 .copilot-tracking/dt/ 中当前 DT 项目的 slug 解析 --canonical-dir 和 --output-dir。

规范产物由 DT coach 生成，并存放在 .copilot-tracking/dt/<project-slug>/canonical/ 下。

运行测试

cd "<customer-card-render-skill-root>"
uv sync --group dev
uv run pytest tests/

测试覆盖解析、模板选择、YAML 输出和回归问题。tests/fuzz_harness.py 文件是一个用于满足 OSSF Scorecard 合规要求的 Atheris 多语言模糊测试框架。

内容忠实度说明：Use Case 卡片

Use Case 卡片分为 3 张具有明确侧重点的幻灯片，每张都包含专门的章节：

• 幻灯片 1：介绍用例，包括 Description、Overview、Business Value 和 Primary User
• 幻灯片 2：详细说明执行过程，包括 Secondary User、Preconditions、Steps 和 Data Requirements
• 幻灯片 3：呈现质量标准，包括 Equipment Requirements、Operating Environment、Success Criteria、Pain Points 和 Evidence

此结构确保所有 16 个 Use Case 章节都能清晰地排布在 4 张幻灯片中，无需压缩。每个章节都放在独立的文本框中，并应用恰当的样式和标题。

完整的映射详情请参阅 references/mapping-spec.md。

故障排查

问题	原因	解决方案
找不到 uv	未安装 uv	运行 winget install --id astral-sh.uv -e（Windows）或 brew install uv（macOS/Linux）
uv 找不到 Python	PATH 中没有 Python 3.11+	运行 uv python install 3.11
找不到模板	--canonical-dir 包含未知类型	检查 frontmatter 中的 type: 字段是否为受支持的制品类型
输出目录为空	未找到规范 Markdown 文件	确认 --canonical-dir 路径正确，且文件包含 --- frontmatter
生成后 PPTX 构建失败	缺少或未激活 PowerPoint 技能	按名称激活 powerpoint 技能。如果未收到其内容，请停止并报告构建步骤不可用