guide-authoring

Guide Authoring

为 Console 已有功能编写引导流程的标准 SOP：场景识别 → YAML 编排 → 标签标注 → 注册发现 → 测试验证。

When to Use

• 需要为 Console 已有功能新增一条可触发的引导流程
• 需要维护 guides/flows/*.yaml、guides/tag-manifest.yaml、guides/registry.yaml
• 需要给已有功能补引导标签或补 registry 发现规则

Not for：

• 用户正在实际使用引导流程时的交互处理，用 guide-interaction
• Guide Engine / callback route / overlay 的代码实现与 bug 修复，用 tdd
• 纯视觉稿、动效或高保真设计稿，用 pencil-design

核心知识

原则	说明
编排即产品	Flow YAML 是终态产物，不是脚手架
页面零侵入	只加 data-guide-id 标签，不改业务逻辑
自动推进	用户操作即推进，无手动导航按钮（v2 KD-9）
平台内聚焦	聚焦 Console 已有功能的引导（KD-13），外部平台配置改为独立页签

前置依赖：F155 Guide Engine Phase A 已验收。

流程

Step 1: 场景识别

确认需要引导的场景，产出"场景卡片"：

# 场景卡片
scene_id: api-provider-setup
scene_name: 配置 API Provider
target_user: 新部署用户 / 需要配置 LLM 的团队
pain_point: Provider 配置字段多，不同 provider 参数差异大
complexity: medium  # low / medium / high
estimated_steps: 4
estimated_time: 3min
related_features: [F155]

判断标准：

• complexity=high → 必须做引导
• complexity=medium → 评估用户卡点频率再定
• complexity=low → 不做引导，文档即可

Step 2: 步骤拆分 + YAML 编排

按 v2 自动推进模式编排，4 种 advance mode：

advance	用途	说明
click	点击目标元素	用户点击后自动前进
visible	目标元素出现	页面切换/展开后自动前进
input	输入填充	用户填写输入框后前进
confirm	操作确认	需要 guide:confirm 事件触发（如保存成功）

Flow YAML 模板（v2 schema）：

id: {scene_id}
name: {scene_name}
description: {一句话描述}

steps:
  - id: step-1
    target: "namespace.element"    # data-guide-id 值
    tips: "点击这里开始配置"       # 引导文案
    advance: click                  # click / visible / input / confirm

  - id: step-2
    target: "namespace.form-field"
    tips: "填写 API 密钥"
    advance: input

  - id: step-final
    target: "namespace.save-button"
    tips: "点击保存完成配置"
    advance: confirm               # 保存成功后 guide:confirm 触发

编排规则：

• 每个 flow 必须有退出路径（HUD 退出按钮始终可用）
• target 值必须匹配 data-guide-id，命名空间式（如 hub.trigger）
• target 必须通过 whitelist：/^[a-zA-Z0-9._-]+$/
• 最后一步建议用 confirm 类型，确保操作真正成功后才完成
• 全局 Esc 键已禁用（KD-14），防止误退出