Concept Demo Design — 让理念先被看见

概念 Demo 的工作，是把一句抽象主张变成观众能亲眼追踪的因果变化。页面、录屏和成片都是载体；成功判据是目标观众能复述核心变化，并知道自己为什么该相信或想要它。

先路由

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

1. 锁定唯一的观众变化

开工前写出两句话：

1. 观众看完能复述：“我看到 ______ 变成了 ______，因为 ______。”
2. 观众接下来愿意：尝试 / 投入 / 相信 / 继续了解哪一件事。

一支 Demo 只承载一个主变化。复杂理念可以有背景和护栏，不能让 Memory、Skill、Harness、Eval 同时争当主角。

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

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

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

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

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

Contract 必须记录：

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

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

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

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

4. 先画信号路径

用一行箭头写清：

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

逐箭头检查：

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

5. 声明诚实边界

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

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

6. 写 Demo Contract

复制 refs/demo-contract-template.md 填写。场景至少覆盖：

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

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

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

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

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

8. 按 claim 选验证机制

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

交付契约

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

Common Mistakes

Pressure Test

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

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

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

下一步

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