ddemo

name	ddemo
description	积木式能力验证方法论——判断「直接做 vs 先验证」、将不确定性分层隔离、沉淀可复用能力资产。触发场景：(1) 讨论技术可行性或方案选型，(2) 评估某个实现的不确定性，(3) 决定直接集成 vs 先做 Demo 验证，(4) 分析能力复用或知识沉淀策略，(5) 用户说"积木"、"Demo"、"能力验证"、"不确定性"
argument-hint	[Demo名称] [不确定性类型] [Layer1功能]
context	fork
agent	general-purpose
allowed-tools	["Read","Bash","Write","Edit","WebSearch","Grep","Glob"]

diwu-demo

积木式能力验证方法论：最小成本验证，最高效率复用。

---

产品分类：两种构建模式

所有产品开发可归为两类，构建策略截然不同：

类型	特征	核心工作	不确定性来源	示例
业务编排型	80% 是拼接已有能力	流程设计、数据建模、UI 组装	需求理解（做什么）	CRM、ERP、电商后台
能力构建型	核心能力需从零验证	能力验证、效果调优、边界探索	技术可行性（能不能做、效果稳不稳）	AI 产品、算法驱动产品

判断方法：项目中是否存在"做了才知道行不行"的部分？

• 全部可预期 → 业务编排型，直接进入设计和实现
• 存在不可预期部分 → 能力构建型，先隔离验证再集成

混合型产品（常见）：整体是业务编排，但某些模块属于能力构建。只对不可预期的部分做能力验证，其余直接实现。

比例参考：通常产品中不确定性工作占 20-40%（因产品而异）。Demo 覆盖的是产品中最关键、最有风险的少数部分，而非全部工作。

---

三层积木模型

将能力验证组织为三层递进结构，每层解决不同粒度的不确定性：

产品积木（完整功能模块）
  ├── 组合积木（多能力集成）
  │     ├── 原子积木 A（单一能力 Demo）
  │     └── 原子积木 B（单一能力 Demo）
  └── 组合积木（多能力集成）
        ├── 原子积木 C
        └── 原子积木 D

原子积木

最小粒度的能力验证单元。一个原子积木 = 一个隔离的 Demo，验证单一不确定性。

核心特征：一句话说清、换产品能用、独立可运行。

正例：prompt-citation-stability（Prompt 能否稳定输出引用标记格式） 反例：hera-meeting-citation（绑定了产品名，换项目不可用）

组合积木

多个原子积木的集成验证。解决"各自能跑但组合起来未测过"的集成风险。

触发条件：两个以上已验证通过的原子积木需要协同工作时。 验证重点：数据流衔接、接口适配、性能叠加效应。

产品积木

从能力到功能的最后一公里。将已验证的组合积木包装为用户可用的完整功能模块。

此时不确定性已消除，工作重心转向产品化：UI 设计、错误处理、配置管理。

---

不确定性四分类

识别不确定性的类型，决定验证策略：

类型	判断依据	验证重点	示例
能力缺口	团队从没做过这件事	能否跑通基本流程	第一次接入 TTS API
结果不可预期	做了但不知道效果如何	输出的稳定性和质量	Prompt 能否稳定输出指定格式
方法未验证	知道目标但路径不确定	方法是否可行且可重复	运营 SOP 能否跑通
集成风险	各自能跑但组合未测过	组合后的数据流和性能	三个模块集成后的端到端表现

应用方式：确定类型后，验证资产的设计才有方向——能力缺口需要最小可运行示例，结果不可预期需要多组测试 case，集成风险需要端到端数据流测试。

---

能力 vs 功能判断

在投入验证之前，先确认验证的是"能力"而非"功能"：

判断问题：换一个产品，这个验证还能用吗？

	能力（继续验证）	功能（重新定义）
定义	可跨产品复用的技术能力	绑定特定产品的业务逻辑
示例	SSE 流式推送、Prompt 稳定输出格式	Hera 的聊天页面、订单详情展示
价值	验证一次，多处复用	只在当前产品有意义

剥离方法：把产品特定部分去掉，找到底层能力。

• "Hera 会议引用功能" → "Prompt 能否稳定输出引用标记格式"
• "用户签到打卡" → "定时任务调度的可靠性"

---

资产形态四分类

能力验证的产出不只是代码。四类资产各有沉淀价值：

资产类型	内容	复用方式	示例
代码资产	可运行的代码片段、SDK 封装、工具函数	直接引用或 fork	SSE 客户端实现、音频格式转换函数
Prompt 资产	经过验证的 Prompt 模板及其测试 case	复制 + 微调	引用标记提取 Prompt v3（准确率 95%）
方案资产	技术选型结论、架构决策、对比分析	参考决策依据	"WebSocket vs SSE"对比及选型理由
方法论资产	可复用的工作方法、SOP、评估框架	套用到新场景	LLM 输出质量评估的 5 步流程

沉淀原则：每次验证结束后，至少产出一类资产。代码类验证产出代码 + 方案资产；Prompt 类验证产出 Prompt + 方法论资产。

Demo README 标准章节

每个 Demo 的 README.md 包含七个标准章节，确保知识完整沉淀：

#	章节	内容	何时填写
1	解决什么问题	从能力定义直接取	创建时
2	核心方案	最终采用的技术方案	验证后
3	验证结果	量化数据（对照通过标准）	验证后
4	已知限制	能力边界、未覆盖场景	验证后
5	集成注意事项	依赖版本、配置差异、接口适配	创建时（从规格文档复制）
6	怎么复用	复用路径、需要调整的部分	验证后
7	踩过的坑	踩坑记录、解决方法	验证后

---

知识容器

Demo 不仅验证自有想法，还是吸收外部知识的标准化入口。

外部知识来源

来源	吸收方式	产出
开源项目	提取核心能力，剥离项目特定部分，封装为原子积木	代码资产 + 方案资产
论文/技术博客	将理论方法转化为可执行的验证 case	方法论资产 + 代码资产
竞品分析	逆向推断能力实现路径，验证可复现性	方案资产
团队经验	将隐性知识显性化为可验证的标准	方法论资产

吸收三步法

1. 提取：从外部来源中识别"能力"而非"功能"（同上文判断方法）
2. 封装：将能力包装为一个原子积木，定义清晰的输入/输出和通过标准
3. 验证：在团队环境中跑通，确认可用性和边界

关键区分：吸收不是照搬。目标是将外部知识转化为团队标准化的、可复用的能力单元。

---

能力库积累飞轮

验证 → 沉淀 → 复用 → 加速
 ↑                      ↓
 └──────────────────────┘

飞轮四阶段

阶段	动作	产出
验证	隔离运行 Demo，验证不确定性	验证结论（通过/失败 + 量化数据）
沉淀	将验证过程和结论标准化为四类资产	可检索的能力库条目
复用	新项目/新功能遇到类似需求时，先查能力库	跳过验证直接集成，或基于已有 Demo 微调
加速	能力库越丰富 → 需要从零验证的越少 → 开发速度越快	团队能力的复利效应

版本积累维度

做得越多，积木越多，新版本越像「搭积木」而不是「造积木」：

版本	需要新 Demo	直接复用	说明
v1.0	~90%	~10%	从零开始，几乎每个能力都要验证
v1.5	~30%	~70%	能力库充足，大部分直接用
v2.0	~50%	~50%	架构升级，又有新的不确定性
v3.0	~20%	~80%	积累更厚，新版本大部分是组装

能力库检索优先级

遇到新的不确定性时，先查再做：

1. 已验证通过（passed） → 直接复用，不重新验证
2. 已验证但未通过（failed） → 读取失败原因，判断是否值得用新方法重试
3. 有相关但不完全匹配的 → 判断：复用并扩展 vs 新建
4. 无匹配 → 新建原子积木

---

「直接做 vs 先验证」决策框架

面对任何实现任务时的快速判断：

判断问题	可预期（直接做）	不可预期（先验证）
团队做过类似的事吗？	做过	没做过
结果有超过 90% 的把握吗？	有	没有
外部依赖（LLM、第三方 API）可控吗？	可控	不可控
多模块集成测试过吗？	测过	没测过

决策规则：

• 全部可预期 → 直接实现
• 任一不可预期 → 先隔离验证，再集成
• 验证已存在（能力库中有 passed 记录）→ 直接复用

---

五维约束设计

能力验证不只是"跑通代码"，还要编码约束——让违反约束的实现不可能被写出。基于产品特性，在设计阶段识别五个维度的约束：

维度	判断问题	例子
业务约束	100 年后还成立吗？	「原始录音不可变，摘要可重新生成」
时序约束	有没有执行路径可以绕过这个规则？	「停止录音后同一 session 不可恢复」
跨端约束	如果两个端定义不同，这是 bug 吗？	「CardType 在所有端完全一致」
并发约束	两个线程同时做这件事会出问题吗？	「状态机事件串行处理」
感知约束	超过这个阈值，用户会注意到吗？	「音频源切换 < 100ms」

使用方式

新增功能模块时，逐行过上表，把命中的约束写入 Demo 的 README 或设计文档。

约束编码示例：

1. 业务约束编码：「原始录音不可变，摘要可重新生成」

   • 编码方式：raw_transcripts 表无 updated_at 字段，cards 表的内容是投影
   • 验证方法：删除 cards 表数据，能从 raw_transcripts 重算

2. 时序约束编码：「停止录音后同一 session 不可恢复」

   • 编码方式：状态机转移表中 Stopped 状态无到 Recording 的转移
   • 验证方法：单元测试覆盖所有非法转移，确认返回错误或忽略

3. 并发约束编码：「状态机事件串行处理」

   • 编码方式：所有事件通过 Channel 串行化，transition 函数是纯函数
   • 验证方法：并发测试发送 100 个事件，状态转移顺序正确

何时使用

• 能力验证阶段：识别核心约束，在 Demo 中验证约束可编码
• 集成阶段：将约束从 Demo 迁移到产品代码，确保不被绕过
• Code Review：检查实现是否违反已声明的约束

---

反模式速查

反模式	症状	正确做法
功能伪装成能力	Demo 名含产品名，换项目不可用	剥离产品特定部分，找底层能力
跳过验证直接集成	"应该没问题"→ 集成后才发现不稳定	对不可预期部分先隔离验证
验证但不沉淀	做了 Demo 但只在聊天记录里	至少产出一类资产，写入能力库
过度验证	对标准 CRUD 也做 Demo	只对不可预期部分验证
原子太大	一个 Demo 验证三个不确定性	拆到一句话能说清
不查库就新建	团队已验证过类似能力但重新做	先查能力库，有则复用或扩展