2026 · MAY · MONTHLY REPORT

brainwav 妙想客户端 · 5 月份汇报

从想法到原型：单机即开即用的 AI 头脑风暴 + Storybook 原型工具

项目brainwav-client v0.2.0 平台Windows 桌面（Electron） 报告周期2026-05-06 ~ 2026-06-05

1项目目标

在不引入云服务、不增加用户操作负担的前提下，把"产品经理脑中的想法"高效地变成"可点击的产品原型"。

产品定位

面向单台 Windows 电脑的个人使用者，双击即开、无需登录，所有数据落本地。

核心闭环

想法整理（PRD）→ 样子生成（Storybook 原型），两阶段都由本地大模型驱动。

差异化

本地工具而非 SaaS：API key、对话、PRD、原型工程都在用户目录，可控、可备份、可断网。

边界纪律

v1 只做想法 + 原型；不做账号、云同步、代码生成、模板库等越界需求。

2做法 / 工程方法

用清晰的进程与模块边界把"AI 易出错"的部分隔离，让智能体在受控范围内长期协作。

技术栈

Electron 33 + React 18 + Vite；Prisma + SQLite 落本地；Anthropic / OpenAI / DeepSeek / 自定义四类 Provider 在主进程统一抽象。

架构红线

渲染进程禁 import Node / Prisma / AI SDK；跨进程走类型化 IPC；模块边界由 dependency-cruiser 自动校验。

合并预览，而非自动写入

"整理需求"等关键写操作走 diff 预览 → 用户确认 → 落库，避免 AI 静默覆盖人工编辑。

会话恢复 + 3 次必停

每轮启动读 .omc/current-task.md，结束前更新；同一问题 3 次未解决转人工，不靠重试赌通过。

35 月进展

从骨架定稿到核心闭环跑通，本月把 v1 主链路真正"跑起来"。

62渲染层 .ts/.tsx
51主进程 .ts
6业务模块
4AI Provider 接入

3.1 关键里程碑

5 月 中旬
客户端骨架搭好
把规范、目录、进程边界都定下来，独立仓库就位，准备开干。
5 月 中旬
能建项目、能传素材
应用的新建、改名、删除全部跑通，文件和外链也能挂到项目下。
5 月 下旬
想用哪个大模型都行
设置页里填一下 key 就能用 Anthropic / OpenAI / DeepSeek，或者接私有模型，还能一键测连接。
5 月 下旬
能聊出 PRD，还能看到原型
对话边打字边出字，聊出来的内容自动归到 PRD 6 大分区；点一下就能在内置预览里看到生成的原型页面。
5 月 底
长程 PRD 总结：聊几十轮也不丢内容
以前聊到第 8 轮，第 3 轮说过的排序算法会被 AI 忘掉；现在把已有 PRD 当上下文回灌，几十轮后早期内容也能稳稳留住。
5 月 底
长程原型生成：项目之间不再串台
以前做完 A 项目再做 B，预览有时还停在 A 的页面；现在加了全局互斥 + 强制刷新，每个项目看到的都是自己的。

3.2 5 月技术攻坚

问题根因方案
多轮对话后早期 PRD 内容被覆盖丢失 提取器只看有限历史窗口 + 字段级覆盖 "现有 PRD"作为 system 上下文回灌，做增量合并
每次提取都返回"本轮未提取到新内容" 保留门槛过高 + existingPRD 位置误导 AI 重写规则、调位置、加日志暴露静默失败
项目 B 预览看到项目 A 的原型 缺全局互斥 + webview 跨项目缓存 主进程全局锁 + webview key + URL cache-bust

4价值

对用户、对协作、对组织三个维度都有积累。

对用户

双击图标 → 聊几轮 → 拿到结构化 PRD + 可交互原型。不登录、不联网存储，一台 Windows 就够。

对协作

三层边界 + 自动校验，AI 智能体在大体量代码里不串台，新人一天就能定位到正确文件。

对组织

CLAUDE.md 规范、会话恢复、合并预览、3 次必停，这套做法可平移到下一个 AI-辅助项目。

沉淀的智能体能力（Agents / Skills）

能力用途
Explore / Plan跨文件调研 + 改动前出方案，避免直接动手返工
code-review / simplify / verify自动审阅 diff、起 Electron 跑主路径，避免"只过 tsc 就报完成"
claude-apiAnthropic SDK 用法调优：prompt caching、流式响应、思考模式
auto memory跨会话记住技术栈决策、shell 陷阱、产品 pivot 等关键信息

工程中的长程控制（Agent Loop & Stateful Orchestration）

brainwav 工程内的两个核心智能体 —— PRD 提取器和Storybook 生成器 —— 各自实现了不同策略的长程控制，应对对话 20 轮、原型反复生成的复杂场景。

PRD 提取智能体 (prd-extractor.ts)

控制策略：无状态 structured output + 增量合并

  • 输入：最近 N 条对话（可配置 prdHistorySize，默认 20）+ 现有 PRD 全文作为上下文
  • Prompt：DEFAULT_PRD_EXTRACTOR_PROMPT 明确要求输出 JSON 数组 [{sectionKey, fields: {字段名: 值}}]
  • 输出验证：正则 + JSON.parse，过滤非法 sectionKey、校验 fieldLabel 在白名单内（FIELD_LABELS）
  • 合并：applyPRDUpdates 遍历提取结果，逐 section 增量 upsert 到 SQLite（Prisma ORM）
  • 为什么有效：PRD 是结构化文档，AI 擅长"从对话抽取结构化信息"。把决策权交给 AI（哪些字段该更新），把校验和存储权留给代码。

Storybook 生成智能体 (generator.ts + agent-loop.ts)

控制策略：Agentic tool-use loop + 全局互斥锁 + 服务器状态隔离

  • 全新生成模式（full）：
    1. 调用 AI 生成"生成计划"（markdown 段落，列出要生成的 stories）
    2. 解析计划 → 分批调用 AI，每批传入 PRD + 已生成文件列表，要求输出 <file path="...">...</file>
    3. 正则提取 XML 块 → 写入 .storybook/stories/
    4. 最后执行 pnpm install（如果是首次 scaffold）
  • 迭代生成模式（iterate）：
    1. 先读取现有 stories 文件清单 + 最近对话
    2. 调用 AI 生成"增量变更计划"（哪些页面要新增/修改/删除）
    3. 根据计划决定要重新生成的文件，走与 full 类似的 AI 调用 + 写文件流程
  • Agentic Loop（runAgentLoop）：
    • 支持 AI 调用 tool（如 read_file / list_existing_stories），返回 tool_result 后继续下一轮
    • 最大迭代次数 maxIterations 防止死循环；AbortSignal 支持用户中止
    • 每轮 onStep 回调推送进度到渲染层，显示"当前工具：xxx"
  • 全局互斥：activeGenerationAppId 保证同一时间只有一个项目在生成，避免并发写文件冲突
  • 服务器状态隔离：runner.setStatus() 加护栏，生成期间不会把 server 的 running 降级到 idle，保证预览不被错误关闭
  • 为什么有效：代码生成是多步骤、需要反馈的任务。AI 先规划（plan）再执行（generate），中间可以调 tool 查询上下文，符合"ReAct"模式。全局锁和状态隔离防止了竞态和 UI 错乱。
设计要点：
  • PRD 提取用"无状态调用 + 增量合并"，因为 PRD 结构稳定、变更局部，AI 每次只需看最近对话即可判断。
  • Storybook 生成用"有状态 agent loop + 全局锁"，因为代码生成需要多次调用、中间状态复杂、且不能并发冲突。
  • 两者共同点：都把"决策"交给 AI（哪些该改、怎么改），把"校验和执行"留给代码（schema 验证、文件写入、数据库事务），这是 AI 辅助工程的核心分工原则。

5下一阶段方向（6 月）

三件事：让产物更易看、让平台更广、让长程更稳。

① 更多可视化呈现方式

PRD 不只 Markdown 卡片 和 内容分区，引入流程图、结构图、关系图等多种视图；

② 多平台适配

从 Windows 单平台扩展到 macOS；窗口框架、字体、原生对话框等差异点统一抽象，跨平台 QA 流程跑通。

③ 长程稳定性提升

对话 50+ 轮、原型反复重生成的场景下，PRD 不丢内容、原型不串台、内存不泄漏；建立长程压测基线，回归不退化。

本月最重要一条经验：当 AI 行为出错时，不要靠"再试一次"绕过去。表象是"AI 没干对"，根因往往是上下文给得不对。把上下文修正确，AI 自然就对了。