authoring-analysis

编写方式分析

确定每个内容序列的编写方式：默认内容或特定区块。

何时使用此技能

在以下情况下使用此技能：

• 你已获得包含内容序列的页面结构（来自 identify-page-structure）
• 你已获得区块清单（本地 + Block Collection）
• 准备按照 David's Model 做出编写决策

调用方： page-import 技能（步骤 3）

前置条件

你需要从 identify-page-structure 技能获得：

• ✅ 带样式说明的区段边界
• ✅ 每个区段的内容序列（中性描述）
• ✅ 区块清单（本地 + Block Collection，含用途）
• ✅ 用于视觉参考的 screenshot.png

相关技能

• page-import - 调用此技能的编排器
• identify-page-structure - 提供区段结构和区块清单
• content-modeling - 区块选择不明确时，此技能会调用它
• block-collection-and-party - 此技能会调用它来验证区块
• generate-import-html - 使用此技能的输出创建 HTML

重要：步骤 3e 执行触发条件

完成步骤 3（分析所有序列）后，如果符合以下条件，必须执行步骤 3e：

• ✅ 至少有一个区段仅包含一个最终采用区块的序列
• ✅ 根据 identify-page-structure，该区段具有独特的背景样式

如果没有区段符合这些条件 → 跳过步骤 3e 如果有任何区段符合这些条件 → 对每个符合条件的区段执行步骤 3e

编写方式分析工作流

上下文： 你现在已经有：

• 带样式的区段边界
• 每个区段的内容序列
• 可用区块集合

对于每个内容序列，遵循以下强制流程：

---

步骤 3a：必须执行 - 检查默认内容（第一步！）

问题：“作者能否在 Word/Google Docs 中通过正常输入创建此内容？”

默认内容包括：

• ✅ 标题、段落、列表
• ✅ 文本中的行内图像
• ✅ 简单引用
• ✅ 只是……输入内容

不属于默认内容的情况：

• ❌ 重复的结构化模式（卡片网格、功能列表）
• ❌ 交互组件（手风琴、标签页、轮播）
• ❌ 复杂布局（并排列、分栏内容）
• ❌ 需要特定结构来实现装饰效果

决策：

• 如果是（可以正常输入）→ 标记为默认内容，完成 ✅
• 如果否（需要结构）→ 继续步骤 3b

示例：

"Large centered heading, paragraph, two buttons"
→ Can author just type heading, paragraph, links? YES
→ Decision: DEFAULT CONTENT ✅

"Two centered buttons"
→ Can author just type two links? YES
→ Decision: DEFAULT CONTENT ✅

"Four items in grid, each with image, heading, description"
→ Can author just type this? NO - requires grid structure
→ Decision: Proceed to Step 3b ➡️

"Expandable questions and answers"
→ Can author just type this? NO - requires interaction/decoration
→ Decision: Proceed to Step 3b ➡️

---

步骤 3b：选择区块（仅当不是默认内容时）

结合区块清单，询问：“作者会为此选择哪个可用区块？”

决策树：何时调用 content-modeling

明显匹配（不要调用 content-modeling）：

模式与区块用途完全匹配：

• “带图像/文本的项目网格” + 看到“cards”区块 → 使用它 ✅
• “可展开的问题” + 看到“accordion”区块 → 使用它 ✅
• “带标签页的内容面板” + 看到“tabs”区块 → 使用它 ✅
• “并排内容” + 看到“columns”区块 → 使用它 ✅
• “旋转图像” + 看到“carousel”区块 → 使用它 ✅

明显匹配的判断标准：

• 内容描述与区块用途完全匹配
• 结构没有歧义
• 清单中存在该区块

匹配不明确（调用 content-modeling）：

不确定使用哪个区块：

• “三个带图像的项目”——可以用 cards？也可以用 columns？→ 调用
• “带图标的功能列表”——用 cards？自定义列表区块？→ 调用
• “带照片的客户引言”——用引用区块？cards？testimonial 区块？→ 调用

清单中缺少对应区块：

• 内容需要结构，但没有匹配的区块 → 调用
• content-modeling 可以推荐规范模型，或建议创建自定义区块

复杂的编写方式考量：

• “类似主视觉的内容，但位于页面中部” → 调用
• “类似卡片的项目，但只有两个” → 调用
• 需要验证作者的心智模型 → 调用

匹配不明确的判断标准：

• 多个区块都可行
• 没有明显匹配的区块
• 需要从编写者角度进行验证
• 可能需要创建自定义区块

步骤 3c：验证区块是否存在（如需要）

仅当区块不在区块集合的常见集合中时：

调用 block-collection-and-party 技能以：

• 确认区块存在
• 获取实时示例 URL
• 查看内容模型

---

步骤 3d：获取区块 HTML 结构（生成 HTML 之前）

**重要：**在下一个技能中生成任何 HTML 之前，先获取你将使用的所有区块的装饰前 HTML 结构。

# Get structure examples for each block
node .claude/skills/block-collection-and-party/scripts/get-block-structure.js cards
node .claude/skills/block-collection-and-party/scripts/get-block-structure.js tabs
node .claude/skills/block-collection-and-party/scripts/get-block-structure.js accordion
node .claude/skills/block-collection-and-party/scripts/get-block-structure.js columns

这有助于避免错误：

• 显示准确的行／列结构（例如：卡片：每张卡片 = 1 行，包含 2 列）
• 展示所有变体（例如：“Cards”和“Cards (no images)”）
• 显示不带装饰的干净 HTML
• 避免最常见的 HTML 生成错误：结构错误

使用输出以便：

1. 了解每行应包含多少列
2. 查看图片和内容分别放置的位置
3. 将内容匹配到正确的变体
4. 生成与预期结构完全一致的 HTML

---

步骤 3 输出格式

所有序列的完整分析：

Section 1 (light):
  - Sequence 1: "Large centered heading, paragraph, two call-to-action buttons"
    → Decision: DEFAULT CONTENT
    → Reason: Author can type heading, paragraph, links normally
    → Note: Prominent styling is a CSS concern

  - Sequence 2: "Two images side-by-side"
    → Decision: Columns block (2 columns)
    → Reason: Side-by-side layout requires structure
    → Obvious match with "columns" block in inventory

Section 2 (light):
  - Sequence 1: "Centered heading"
    → Decision: DEFAULT CONTENT
    → Reason: Just a heading - author types it

  - Sequence 2: "Grid of 8 items, each with icon and short text"
    → Decision: Cards block
    → Reason: Repeating structured pattern, needs block
    → Obvious match with "cards" block in inventory

  - Sequence 3: "Two centered buttons"
    → Decision: DEFAULT CONTENT
    → Reason: Just two links - author types them

Section 3 (grey):
  - Sequence 1: "Eyebrow text, heading, paragraph, button stacked vertically"
    → Decision: DEFAULT CONTENT
    → Reason: Author types text and link normally

  - Sequence 2: "Four items in grid, each with image, category tag, heading, description"
    → Decision: Cards block
    → Reason: Repeating structured pattern
    → Obvious match with "cards" block in inventory

Section 4 (dark):
  - Sequence 1: "Tab navigation with three switchable content panels"
    → Decision: Tabs block
    → Reason: Interactive component, needs decoration
    → Obvious match with "tabs" block in inventory

---

第 3e 步：验证区块样式（仅适用于单区块部分）

⚠️ 执行条件： 此步骤在完成第 3 步后执行。当且仅当满足以下条件时，才执行此步骤：

• ✅ 已完成第 3 步（确定哪些序列会成为区块）
• ✅ 至少有一个部分恰好包含一个成为区块的序列
• ✅ 该部分具有与 identify-page-structure 中不同的背景样式

如果没有任何部分符合这些条件 → 完全跳过第 3e 步，并继续下一项技能

如果有任何部分符合这些条件 → 必须对每个符合条件的部分执行以下所有子步骤

---

为什么此验证很重要：

当一个部分只包含一个区块时，背景样式可能是：

• 区块专属设计（例如，带深色背景图的主视觉区块）→ 不要添加 section-metadata
• 部分容器样式（例如，带标签页区块的深色部分）→ 添加 section-metadata

如果不进行验证，我们可能会添加不必要的 section-metadata，与区块样式冲突，或增加创作复杂度。

包含多个序列的部分： 始终保留 section-metadata（样式适用于所有内容，不在第 3e 步中验证）

---

对于每个恰好包含一个区块的部分，执行以下所有子步骤：

子步骤 1：确定候选部分

查看第 3 步的输出。找出符合以下条件的部分：

• 部分恰好包含 1 个内容序列
• 该序列成为了区块（而非默认内容）
• 该部分具有与 identify-page-structure 中不同的背景样式

示例：

Section 1 (dark blue):
  - Sequence 1: Large centered heading, paragraph, two buttons
    → Decision: Hero block

Section 3 (grey):
  - Sequence 1: Tab navigation with three switchable panels
    → Decision: Tabs block

---

子步骤 2：检查每个候选部分的截图

打开 screenshot.png，并目视检查该部分。

请回答以下问题：

Q1：背景是图片吗（照片、渐变、插图）？

• 如果是 → 可能是区块专属设计
• 如果不是（纯色）→ 继续回答 Q2

Q2：内容是否铺满整个有色区域，还是能看到部分内边距？

• 内容延伸到边缘（全出血）→ 可能是区块专属设计
• 内容周围有可见的内边距 → 可能是部分容器样式

Q3：这种区块类型通常有自己的背景样式吗？

• Hero、横幅、全宽 CTA → 通常有自己的背景
• 标签页、手风琴、卡片、分栏 → 通常使用部分背景

---

子步骤 3：做出决定

根据分析，为每个单区块部分做出决定：

如果符合以下条件，则跳过 section-metadata：

• 背景是图片或渐变（区块专属）
• 内容为全出血／延伸到边缘（看不到部分内边距）
• 区块类型通常自带背景（Hero、横幅）

如果符合以下条件，则保留 section-metadata：

• 背景为纯色，且能看到部分内边距
• 区块类型通常继承部分样式（标签页、卡片、手风琴）
• 样式明显提供了容器上下文（而非区块设计）

---

子步骤 4：记录决定

对于每个经过验证的部分，记录：

• 部分编号
• 区块类型
• 背景分析（图片或纯色、全出血或有内边距）
• 决定（保留或跳过 section-metadata）
• 原因

示例输出：

VALIDATED SECTIONS:

Section 1 (dark blue):
  - Block: Hero
  - Background: Full-width dark blue gradient image
  - Layout: Edge-to-edge, no visible section padding
  - Decision: SKIP section-metadata
  - Reason: Background is hero's design, not section styling

Section 3 (grey):
  - Block: Tabs
  - Background: Solid grey (#f5f5f5)
  - Layout: Content centered with visible padding (~80px on sides)
  - Decision: KEEP section-metadata style="grey"
  - Reason: Section provides container styling for tabs block

---

如果无法确定：

如果不确定背景是区块专属还是适用于整个部分：

• 默认保留 section-metadata（更安全，也更容易让作者删除，而非添加）
• 在文档中添加备注，说明存在歧义
• 可以考虑向用户寻求指引

---

第 3e 步完成检查清单：

继续下一项技能前，请确认已完成以下事项：

• ✅ 找出所有带背景样式的单区块部分
• ✅ 检查每个候选部分的原始截图
• ✅ 回答每个候选部分的 Q1、Q2、Q3
• ✅ 为每个候选部分决定跳过或保留
• ✅ 记录每项决定的理由
• ✅ 更新部分样式备注，记录验证后的决定

---

最终输出

此技能提供完整的创作分析：

1. 所有序列的创作决策：

• 将每个序列标记为 DEFAULT CONTENT 或特定区块名称
• 记录决策理由

2. 获取的区块结构：

• 所有将使用区块的 HTML 结构示例

3. 区段样式验证（如适用）：

• 更新区段列表，并附上经过验证的样式决策
• 某些区段可能会标记为“no section-metadata”

**下一步：**将这些输出传递给 generate-import-html 技能