feat(F155): ship Phase A scene-based guidance engine

cat-cafe-skills/guide-authoring/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: guide-authoring
+description: >
+  标准引导流程设计 SOP：场景识别 → YAML 编排 → 标签标注 → 注册发现 → 测试验证。
+  Use when: 新建引导流程、添加场景引导、维护 Guide Catalog、编写引导 YAML。
+  Not for: 使用引导（用户侧）、Guide Engine 代码实现（用 tdd）、视觉设计（用 pencil-design）。
+  Output: Flow YAML + tag-manifest 更新 + registry 注册 + CI 校验通过。
+triggers:
+  - "新建引导"
+  - "添加场景引导"
+  - "写引导流程"
+  - "guide authoring"
+  - "引导 YAML"
+---
+
+# 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），外部平台配置改为独立页签 |
+
+**前置依赖**：F150 Guide Engine Phase A 已验收。
+
+## 流程
+
+### Step 1: 场景识别
+
+确认需要引导的场景，产出"场景卡片"：
+
+```yaml
+# 场景卡片
+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: [F150]
+```
+
+**判断标准**：
+- complexity=high → 必须做引导
+- complexity=medium → 评估用户卡点频率再定
+- complexity=low → 不做引导，文档即可
+
+### Step 2: 步骤拆分 + YAML 编排
+
+按 v2 自动推进模式编排，4 种 advance mode：
+
+| advance | 用途 | 说明 |
+|---------|------|------|
+| `click` | 点击目标元素 | 用户点击后自动前进 |
+| `visible` | 目标元素出现 | 页面切换/展开后自动前进 |
+| `input` | 输入填充 | 用户填写输入框后前进 |
+| `confirm` | 操作确认 | 需要 `guide:confirm` 事件触发（如保存成功） |
+
+**Flow YAML 模板**（v2 schema）：
+
+```yaml
+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），防止误退出
+
+### Step 3: 元素标签标注
+
+给涉及的前端元素添加 `data-guide-id`：
+
+```tsx
+// 命名规则：{页面}.{区域}.{元素}
+<button data-guide-id="hub.trigger">Hub</button>
+<button data-guide-id="cats.add-member">添加成员</button>
+```
+
+**标签命名约定**：
+- 用点号分层，语义而非位置
+- 避免 CSS class 名、索引号
+- 标签一旦被 flow 引用即为契约，删改需走 CI 门禁
+
+**产出**：更新 `guides/tag-manifest.yaml`（CI 用于契约校验）：
+
+```yaml
+# guides/tag-manifest.yaml
+tags:
+  hub.trigger: { page: "/hub", component: "CatCafeHub.tsx" }
+  cats.add-member: { page: "/hub/cats", component: "HubCatsTab.tsx" }
+```
+
+### Step 4: 注册到 Guide Registry
+
+在 `guides/registry.yaml` 添加场景条目：
+
+```yaml
+- id: api-provider-setup
+  name: 配置 API Provider
+  keywords: [api, provider, 配置, llm, api-key, 模型]
+  entry_page: /hub/settings/providers
+  estimated_time: 3min
+  flow_file: guides/flows/api-provider-setup.yaml
+  priority: P1
+```
+
+**关键词设计原则**：
+- 覆盖中英文同义词
+- 包含用户可能的自然表达
+- 不要太泛（避免误匹配）
+
+### Step 5: CI 契约测试
+
+确保以下校验全部通过（对应 AC-S3）：
+- [ ] Flow schema 合法（step 字段 + advance 类型）
+- [ ] 所有 `target` 在 tag-manifest.yaml 中存在
+- [ ] 至少有退出路径（HUD 退出按钮 — 引擎内置，无需手动添加）
+
+### Step 6: 端到端验证
+
+1. 启动 dev 环境
+2. 在聊天中触发引导（说匹配关键词）
+3. 走完全流程：每步高亮正确 → 操作后自动推进 → 完成回调生效
+4. 测试异常路径：退出 → 刷新 → 目标元素不存在时的 locating 行为
+5. 确认完成后猫猫收到 completion 通知
+
+## Quick Reference
+
+| 要做什么 | 文件 | 说明 |
+|---------|------|------|
+| 写新引导流程 | `guides/flows/{id}.yaml` | 按 Step 2 模板 |
+| 加元素标签 | 前端组件 + `guides/tag-manifest.yaml` | 按 Step 3 命名约定 |
+| 注册发现 | `guides/registry.yaml` | 按 Step 4 |
+| 验证 | CI gate + 手动 E2E | 按 Step 5-6 |
+
+## Common Mistakes
+
+| 错误 | 后果 | 修复 |
+|------|------|------|
+| 标签用 CSS class 名 | UI 重构后引导失效 | 用语义命名 |
+| 忘记注册 registry | 猫猫查不到引导 | Step 4 不可跳过 |
+| 最后一步不用 confirm | 操作未成功就完成 | 涉及保存/提交的最后一步必须 confirm |
+| 关键词太泛 | 误匹配其他场景 | 用具体术语 |
+| 跳过 E2E 验证 | 线上引导卡死 | Step 6 是发布前必做 |
+
+## 和其他 Skill 的区别
+
+- `feat-lifecycle`：管理 Feature 生命周期 — guide-authoring 是写 **引导流程文档** 的 SOP
+- `tdd`：代码的测试驱动 — guide-authoring 是 **YAML 编排** 的质量纪律
+- `pencil-design`：出设计稿 — guide-authoring 定义引导 **逻辑和数据**，pencil 出 **视觉效果**
+
+## 下一步
+
+- 引导流程写完 → `tdd` 验证 YAML + 标签
+- 验证通过 → `quality-gate` → `request-review`

cat-cafe-skills/guide-interaction/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: guide-interaction
+description: >
+  场景引导交互模式：匹配到引导流程后，向用户提供交互式选择卡片，
+  处理用户选择（开始引导/步骤概览/跳过），启动前端引导 overlay。
+  Use when: 系统注入了 Guide Available（自动触发，不需要手动加载）。
+  Not for: 没有匹配到引导流程的普通对话。
+triggers:
+  - "引导流程"
+  - "guide"
+---
+
+# Guide Interaction — 场景引导交互模式
+
+## 你的角色
+
+你是场景引导助手。当系统检测到用户的问题匹配了一个已有的交互引导流程时，
+你负责用简短自然的方式告知用户，并提供交互选项让用户决定下一步。
+
+**核心原则**：
+- 不要直接给出长篇教程或步骤列表
+- 先提供选择，尊重用户意愿
+- 回复简短自然，像对话而非说明书
+
+## 系统注入格式
+
+当有匹配的引导流程时，系统会在你的 prompt 中注入：
+
+```
+🧭 Guide Available: thread={threadId} id={guideId} name={guideName} time={estimatedTime} status={status}
+→ Load guide-interaction skill and act per current status.
+```
+
+从这行读取 `guideId`、`guideName`、`estimatedTime`、`status`。
+
+## 工具速查
+
+| 动作 | MCP 工具 | 参数 |
+|------|----------|------|
+| 持久化引导状态 | `cat_cafe_update_guide_state` | `threadId`, `guideId`, `status`, `currentStep?` |
+| 发送交互选择卡片 | `cat_cafe_create_rich_block` | `block=<JSON string>` |
+| 启动前端引导 overlay | `cat_cafe_start_guide` | `guideId` |
+| 解析用户意图匹配 | `cat_cafe_guide_resolve` | `intent` |
+| 控制引导进度 | `cat_cafe_guide_control` | `action` (next/back/skip/exit) |
+
+**重要**：状态持久化是必须的，但进入 `active` 是例外。开始引导时必须调用 `cat_cafe_start_guide`，不要手动 `status='active'`，否则前端 overlay 不会收到完整 start side effects。
+
+## Status 驱动行为
+
+### status: offered
+
+首次向用户展示引导选项。
+
+1. 调用 `cat_cafe_update_guide_state(threadId, guideId, status='offered')` 持久化状态
+2. 写一句自然的话，告知用户你找到了匹配的引导流程
+   - 示例：「我找到了「{guideName}」的交互引导流程，大约需要 {estimatedTime}。」
+   - 可以根据对话上下文微调措辞，不必死板照搬
+3. 调用 `cat_cafe_create_rich_block`，`block` 参数传入以下 JSON 字符串：
+
+```json
+{
+  "id": "guide-offer-{guideId}-{取自系统注入的threadId的后8位}",
+  "kind": "interactive",
+  "v": 1,
+  "interactiveType": "select",
+  "title": "我找到了「{guideName}」引导流程（约 {estimatedTime}）。要现在开始吗？",
+  "options": [
+    { "id": "start", "label": "开始引导（推荐）", "emoji": "🚀" },
+    { "id": "preview", "label": "先看步骤概览", "emoji": "📋" },
+    { "id": "skip", "label": "暂不需要", "emoji": "⏭️" }
+  ],
+  "messageTemplate": "引导流程：{selection}"
+}
+```
+
+4. **禁止**在这个阶段直接给出步骤教程
+5. 等待用户在选项卡中做出选择
+
+### status: awaiting_choice
+
+用户已看到选项卡但尚未选择，或刷新了页面。
+- 不要重复发送选项卡
+- 用一句话提醒：「之前找到了「{guideName}」引导流程，你要开始吗？」
+
+### 用户选择后的处理
+
+用户点击选项后，系统会将选择作为消息发回（格式：`引导流程：{选项label}`）。
+根据选择内容执行：
+
+**用户选了「开始引导」**：
+1. 调用 `cat_cafe_start_guide(guideId)` 启动前端引导 overlay
+2. `cat_cafe_start_guide` 会同时完成 `offered/awaiting_choice → active` 的状态更新和 socket side effects
+3. 回复一句鼓励的话，如「引导已启动，跟着页面上的提示一步步来就好！遇到问题随时问我。」
+
+**用户选了「先看步骤概览」**：
+1. 调用 `cat_cafe_update_guide_state(threadId, guideId, status='awaiting_choice')` 标记已看到
+2. 调用 `cat_cafe_guide_resolve(intent={guideName})` 获取步骤信息
+3. 用 3-5 条简要列出主要步骤
+4. 在最后问用户是否要开始引导
+
+**用户选了「暂不需要」**：
+1. 调用 `cat_cafe_update_guide_state(threadId, guideId, status='cancelled')` 标记取消
+2. 简短回复：「好的，有需要随时说。」
+3. 如果用户原本有其他问题，继续回答那个问题
+
+### status: active
+
+引导正在进行中（前端 overlay 已启动）。
+- 监听用户反馈，感知用户遇到的困难
+- 如果用户问了和当前引导步骤相关的问题，结合引导上下文回答
+- 不要重复发送引导选项卡
+- 用户请求退出时：调用 `cat_cafe_guide_control(action='exit')`
+
+### status: completed
+
+引导已完成。
+- 不再触发引导相关行为
+- 正常对话模式
+
+### status: cancelled
+
+引导已取消。
+- 不再触发引导相关行为
+- 正常对话模式

cat-cafe-skills/manifest.yaml

@@ -38,6 +38,27 @@ skills:
     sop_step: null
     merged_from: ["feat-kickoff", "feat-discussion", "feat-completion"]
 
+  # ── 引导流程设计 ──
+  guide-authoring:
+    description: >
+      标准引导流程设计 SOP：场景识别 → YAML 编排 → 标签标注 → 注册发现 → 测试验证。
+      Use when: 新建引导流程、添加场景引导、维护 Guide Catalog、编写引导 YAML。
+      Not for: 使用引导（用户侧）、Guide Engine 代码实现（用 tdd）、视觉设计（用 pencil-design）。
+      Output: Flow YAML + tag-manifest 更新 + registry 注册 + CI 校验通过。
+    triggers:
+      - "新建引导"
+      - "添加场景引导"
+      - "写引导流程"
+      - "guide authoring"
+      - "引导 YAML"
+    not_for:
+      - "使用引导"
+      - "Guide Engine 实现"
+      - "出设计稿"
+    output: "Flow YAML / tag-manifest / registry entry / CI green"
+    next: ["pencil-design", "tdd"]
+    sop_step: null
+
   # ── 协作思考 ──
   collaborative-thinking:
     description: >

cat-cafe-skills/refs/shared-rules.md

@@ -313,14 +313,14 @@ Rebase 遇到冲突时，**必须看三个版本**（base / ours / theirs）再
 **前置条件**：`merge.conflictStyle=zdiff3`（`pnpm guards:install` 自动设置）。
 设置后冲突标记自动带 base 段：
 
-```
-<<<<<<< HEAD
+```text
+[conflict-start: HEAD]
 猫 A 的代码（ours）
-||||||| base
+[base]
 原始代码（改之前的样子）
-=======
+[separator]
 猫 B 的代码（theirs / main）
->>>>>>> main
+[conflict-end: main]
 ```
 
 **手动查看三屏**（当 zdiff3 标记不够用时）：