concept-demo-design

name	concept-demo-design
tips_exempt	Existing concept-demo authoring workflow refinement; no new end-user Hub capability surface.
description	把抽象理念、家内 UI/UX 可点稿或端到端用户旅程变成可讲解、可验证的交互 Demo。Use: 做个 demo 让人 get 到、做 F284 式体验 Gate、验证完整用户旅程。Not: 已签字的正式产品前端、已有素材剪辑、PPT、纯视觉探索。Output: 双轴 Demo Contract（判题类型 × 交付车道）+ 确定性交互原型 + 验证记录。

Concept Demo Design — 让理念先被看见

Demo 的工作，是把尚未适合直接产品化的问题变成可以亲眼判断的证据。页面、录屏和成片都是载体；真正决定做法的是它要回答什么问题，以及证据交给谁。

先路由

当前任务	去向
理念还停在文字里，需要让人看见因果变化	本 skill，demo_kind=concept_story
正式实现前，需要在家里比较布局、交互、折叠与恢复行为	本 skill，demo_kind=product_experience_gate
需要验证用户能否从起点走到目标结果，包括跨面板交接与失败恢复	本 skill，demo_kind=journey_validation
Demo Contract 已定，需要实现交互前端	worktree + tdd，视觉核验用 browser-preview
已有录屏，需要配音、剪辑、导出	video-forge
需要台上讲述的 slide	ppt-forge
已经签字、准备进入正式产品 UI 与真实用户契约	console-dev

不要用正式产品工程代偿概念没想清。也不要拿一段剧本文字冒充可录屏的 Demo。

1. 先锁定唯一的判题

先选择 demo_kind，再写一句这个 Demo 必须回答的问题：

demo_kind	要回答的问题	成功证据
concept_story 概念叙事	这个抽象变化是什么，为什么值得相信或想要？	目标观众能复述因果变化
product_experience_gate 产品体验 Gate	哪个原生 UI / 交互方案应 keep、tune 或 sunset？	operator 能在真实产品语境中比较并签字
journey_validation 用户旅程验证	代表性用户能否从起始状态走到目标结果，并跨过交接、打断与恢复？	每一步有真实语义与可重放证据，终态可判定

三个类型不是页面风格。一个可点击页面可能是概念叙事，也可能是体验 Gate；一段录屏也可能是在验证用户旅程。按要回答的问题分类，不按媒介分类。

开工前补齐两句话：

1. 这个 Demo 要作出的判断：看完后，谁能决定 ______。
2. 最小可见证据：如果结论成立，画面上必须亲眼看到 ______。

concept_story 还要写观众复述句：“我看到 ______ 变成了 ______，因为 ______。”

一支 Demo 只承载一个主判断。复杂理念可以有背景和护栏，不能让多个 feature 或抽象同时争当主角。

再选一帧“灵魂画面”：没有旁白时，这一帧仍能表达主张。先定灵魂画面，再倒推前因和后果。

2. 再定交付车道：家内还是对外

“目标观众是谁”还不够。画页面前必须把 Demo 的交付车道冻结进 Contract：

交付车道	何时选	视觉真相源	可以舞台化什么	不能做什么
internal_product_gate 家内原生体验	给 operator / 家里体验，判断能力是否该进入正式产品；在 Hub / Browser Preview 中点击	当前 Clowder AI 页面、组件、token、布局和真实 worktree	独立的开发控制条、注释、场景跳转；应可隐藏	另造通用 SaaS 壳、落地页或“控制中心”代替产品界面
external_showcase 对外叙事展示	给没有家内先验的外部观众、发布会、招募或公开录屏	Clowder AI 品牌身份 + 被讲述能力的真实交互语法	简化产品 chrome、增加导览和叙事舞台	把展示壳冒充已经上线的产品 UI，或丢掉品牌身份做成模板站

默认规则：只要 Demo 要在家里被体验、比较或据此拍板，就走 internal_product_gate；只有明确存在外部分发对象或传播场景时才走 external_showcase。不能仅因“录屏”二字自动走对外车道。

demo_kind 与 delivery_lane 是两个正交维度：前者定义判题，后者定义交付对象与视觉真相。用户旅程不是第三条观众车道——它既可以先在家里验证，也可以在验证后改编成对外 showcase。禁止把 journey_validation 塞成第三个 delivery_lane。

F284 Workspace Shell 属于 product_experience_gate × internal_product_gate：它要在家里原生壳中判断 Workspace 结构，而不是向外宣传未来界面。

同一理念确实需要内外两用时，保留同一状态模型，做两个入口或两支短 Demo：产品交互留在原生壳里，外部叙事另加展示框。不要折中成一个半产品、半宣传的混合壳。

Contract 必须记录：

• demo_kind：只能是上述三个值之一；
• delivery_lane：只能是上述两个值之一；
• visual_source_of_truth：具体页面、组件、截图或 worktree，而不是“参考家里风格”；
• native_elements：哪些产品结构必须原样保留；
• stylized_elements：哪些仅为讲解服务，且如何与产品界面分层；
• truth_label：观众怎样区分概念编排、功能原型和真实产品。

动工前做首帧检查：隐藏标题里的 F 号与开发控制条后，家内 Demo 是否仍像 Clowder AI 的自然一部分；对外 Demo 是否既让陌生观众看懂，又不会被误认为生产截图。

3. 选视角，必要时拆成两支

视角	观众看见什么	回答的问题
工作台 / 用户视角	输入更少、修改更少、下一次直接更贴身	“我为什么想要它？”
控制室 / 维护者视角	系统发现、归因、干预、验证、拒绝假信号	“我凭什么信它不会瞎改？”

两个问题都重要时，做两支短 Demo。不要在同一画面里频繁切换受益者、操作者和裁判。

4. 先画信号路径

用一行箭头写清：

谁产生信号 → 系统在哪个界面/事件中看见 → 谁解释 → 谁决定是否采用 → 下一次哪里改变

逐箭头检查：

• 系统真的拿得到这份信号吗？拿不到的终稿、私下反馈和脑内偏好不能入戏。
• 中间人有没有独立判断价值？只负责转发的角色应被产品连接吃掉。
• 信号是测量，还是规约？读者能指出“没看懂”，作者仍拥有“想说什么”的主权。
• 冲突反馈如何拒绝、观察或降权？能拒绝诱人的假信号，是演示可信度的重要来源。

5. 声明诚实边界

按画面中的每个 claim 标一层：

层	可以展示什么	必须怎样标注
概念编排	预设剧情、模拟数据、定时状态变化	“概念演示 / 演示数据”
功能原型	真实可点击、可暂停、可切场景的前端行为	不暗示已接生产后端
真实证据	产品截图、日志、thread、PR、用户结果	保留来源、时间与适用边界

概念编排负责让人懂，真实证据负责让人信。两者可以前后相接，不能用“机制真实存在”掩盖尚未自动化的链路。

6. 写 Demo Contract

复制 refs/demo-contract-template.md 填写。先按 demo_kind 选择场景证据，不要把下列内容当成必须补齐的统一清单。

concept_story

1. 新手导览：每个面板、指标、日志分别回答什么问题。
2. 变化前：观众先看懂正常世界。
3. 信号出现：明确谁、何时、为何触发；切换客户/时间段时加分隔。
4. 系统变化：把归因、规则 diff、资产更新或路由变化画出来。
5. 新世界验证：改完后用新样本、同题对照、灰度或真实后续行为证明有效。
6. 拒绝时刻：适用于自适应系统；展示它怎样拒绝坏尺子、越界反馈或虚假提升。

product_experience_gate

1. 安静默认态：没有相关工作时，界面能多克制。
2. 主动作：用户在真实产品语境中完成最关键的任务。
3. 折叠与召回：内容如何让位、如何稳定找回，状态是否保留。
4. 等待、空态、错误与恢复：不能只演 happy path。
5. 方案比较：只改变待裁决变量，其他状态保持一致。
6. Must-Preserve 回归：原有能力、锁定态、响应式、会话生命周期和持久化语义不因新壳丢失。

journey_validation

1. 起始状态与目标结果：用户为何开始，何时算真正完成。
2. 触发与每个 canonical handoff：人、Agent、工具、面板之间如何交接，不能用导览跳过真实导航。
3. 中断与恢复：刷新、折叠、切换、失败或权限阻断后如何继续。
4. 一个诚实失败路径：展示不能完成时，系统怎样解释并保留上下文。
5. 可判定终态：结果、剩余动作与证据在哪；不能只用“完成了”卡片收尾。

用户旅程可以跨多个 surface，但每一步必须落到真实事件、状态或契约。模型总结可以辅助讲解，不能替代 canonical 内容，也不能凭空补一条现实中不存在的捷径。

每一幕只新增一个概念。保留人物、原话和具体动作；压低抽象门槛时，不要把叙事压成 SOP 摘要。

7. 用最低成本做出“真的画面”

默认选择确定性的纯前端交互。只有核心 claim 依赖真实后端行为时，才增加后端。

• 先把 visual_source_of_truth 中列出的页面逐一打开，记录要复用的组件、token、布局与交互；只写“像家里”不算盘点。
• product_experience_gate 从当前产品壳、组件、token 和目标 worktree 开始；演示控制放在可隐藏的开发层，不能反过来让控制面板成为主 UI。
• journey_validation 可以串起多个真实 surface；transition edge、状态 owner、失败与恢复必须沿用产品事件或明确契约，禁止搭一条绕开真实入口的“观光路线”。
• 对外车道从品牌身份和陌生观众导览开始；可以搭叙事舞台，但产品交互镜头仍沿用真实交互语法，并显式标注原型边界。
• 用 SVG 图标保持一致性；不要用 emoji 代替正式 UI 图标。
• 提供播放 / 暂停、上一幕 / 下一幕、左右键与空格键。讲者必须能控场。
• 时间轴、字幕、弹层共用同一暂停语义；暂停后不能继续偷偷变化。
• 节奏按“现场边讲边放”设计。默认宁可慢，试讲后再加速。
• 画面状态应可确定重放；录屏前不依赖随机 LLM 输出。

8. 按 claim 选验证机制

Claim	机制
demo_kind 是否选对，Demo 的证据能否回答所声明的判题	Contract 审计
场景顺序、控件、暂停、标签、角色连续性	自动化 test / guard
交付车道是否选对、视觉真相源是否真的被采用	Contract 审计 + 与所列产品页面逐幕对照
产品体验 Gate 的默认态、比较变量、折叠恢复与 Must-Preserve 是否成立	确定性 fixture + 浏览器逐态对照 + operator 签字
用户旅程的步骤、handoff、失败恢复与终态是否真实	Journey ledger + step / transition / recovery 断言
页面有没有溢出、视觉是否像产品、灵魂帧是否成立	浏览器逐幕检查 + 截图
讲者能否顺畅讲完	operator 试讲；卡壳处就是缺失锚点
目标观众有没有 get 到	让新观众复述第一节的句子
Demo 是否值得长期保留/调节/下线	有明确 consumer 和决策时再用 eval-design

自进化类 Demo 还要守住第五步：展示“改了”只证明发生了更新；外推成立后才有资格称为进化。

交付契约

• Demo Contract：判题类型、交付车道、观众、视觉真相源、视角、信号路径、灵魂帧、诚实边界、类型专属证据表。
• 可录屏交互前端：确定性播放、讲者控场、新手导览、原生视觉语言。
• 验证记录：自动检查、逐幕视觉检查、试讲或目标观众复述结果。
• 证据续接计划：Demo 后展示哪些真实截图、PR、轨迹或结果。

Common Mistakes

失败	根因	修正
把“用户旅程”做成第三条交付车道	混淆判题类型与观众 / 分发对象	用 demo_kind × delivery_lane 两轴表达
家内 UI 可点稿做成展示站	把产品体验判题误当概念宣传	选 product_experience_gate，从真实产品壳与待裁决变量开工
用户旅程只剩几张总结卡	用叙事压缩替代真实步骤与交接	建 Journey ledger，逐步钉 canonical event、状态与恢复证据
做成结论陈列页	没定义讲者与观众如何使用	先锁观众复述句与讲述节奏
只有四幕剧本，录不出东西	把叙事稿当 Demo	交付可运行画面与场景控制
花两天造真实引擎	把“真的 Demo”听成“真的后端”	先问 claim 是否需要后端；默认纯前端编排
Skill 写了“复用原生组件”，结果仍做成泛用 SaaS 壳	交付对象只写成“观众”，家内体验与外部传播没有 typed lane；弱提醒可被绕过	先冻结 delivery_lane 与具体视觉真相源；家内 Demo 必须从原生产品壳开工
为了内外两用，做成半产品半宣传的混合壳	把两个传播任务误当一张响应式页面	复用同一状态模型，分别做原生体验入口与对外叙事入口
一上来滚指标和日志	默认观众认识控制台	第一幕做面板与指标导览
自动播放太快	按观看速度设计，没按讲述速度设计	试讲定速 + 完整暂停语义
两个客户/时间段混在一起	场景连续性未写进 Contract	显式分隔、角色标签、状态前提
信号只能经人肉转发	没画 signal path	删除无价值 middle man，换可直达场景
收下所有反馈	把测量源当规约 owner	分拣表达问题与立场问题，保留人的晋升/拒绝权
改完即宣布成功	缺少新世界外推	同题对照、新用户、灰度或真实后续行为

Pressure Test

冻结 Contract 前逐题过一遍；只看关键词、不看实际交付对象就算失败：

请求	demo_kind	delivery_lane	必须出现的证据	失败信号
“做个让我在 Hub 里点点、决定 Workspace 怎么改的 Demo”	product_experience_gate	internal_product_gate	具体产品页面 / 组件 / worktree；比较态；可隐藏开发控制层	独立 SaaS 壳或宣传页成为主界面
“给不了解 Clowder AI 的外部伙伴录一支 60 秒理念 showcase”	concept_story	external_showcase	陌生观众导览、因果变化、品牌身份、原型诚实标注	堆家内缩写，或把叙事壳冒充生产 UI
“做个能录屏的 Demo 给我看看”	由判题决定，默认先问证据	internal_product_gate	家内体验入口；录屏只是载体	因“录屏”自动切去对外风格
“把从我提出需求、猫调用工具、结果回到 Workspace、失败后恢复这一整条演出来”	journey_validation	internal_product_gate	Journey ledger、真实 handoff、失败恢复、可判定终态	用几个总结卡跳过真实交接
“先给家里验证完整旅程，以后也想对外发”	journey_validation	先家内、后独立对外入口	同一旅程状态模型 + 两种入口与诚实边界	一个半产品、半宣传的混合壳

任一场景若无法从 Demo Contract 直接读出判题类型、交付车道、视觉真相源和诚实边界，不进入前端实现。

完整的两支 Demo 失败谱系与来源见 refs/lessons-from-two-demos.md。视觉 taste 还应读取 ../../docs/taste/vignettes/creative-craft-概念演示-mksdmh.md。

下一步

Contract 冻结后：交互实现走 worktree + tdd + browser-preview；需要正式成片时再交给 video-forge。