</ul>
<h2>2. 产品概述</h2>
- <p>StationBuilder 是面向 iStation 团队的内部工具，用于通过 AI（Wordbuddy Hy3）与 <b>dashboard-json-generator Skill</b> 快速生成站点的大屏看板（Cube 仪表盘 JSON）、资产配置、功能菜单与领域方案，并可预览、反馈微调与打包下载。核心用户路径为：<b>站点列表 → 站点详情（基本属性 / 资产 / 功能与菜单 / 生成确认）→ 站点结果 / 页面预览</b>。</p>
+ <p>StationBuilder 是面向 iStation 团队的内部工具，用于通过 AI 大模型与 <b>可视化生成 Skill</b> 快速生成站点的大屏看板（Cube 仪表盘 JSON）、资产配置、功能菜单与领域方案，并可预览、反馈微调与打包下载。核心用户路径为：<b>站点列表 → 站点详情（基本属性 / 资产 / 功能与菜单 / 生成确认）→ 站点结果 / 页面预览</b>。</p>
<h2>3. 技术架构与运行环境</h2>
<table>
<tr><th>层</th><th>技术</th><th>说明</th></tr>
<tr><td>前端</td><td>Next.js 16 / React 19 / Vite 8 / Cloudflare Worker（Vinext）</td><td>同源运行；Worker 路由代理 <code>/api/db/*</code> 与 <code>/api/chat</code></td></tr>
- <tr><td>æ\95°æ\8d®</td><td>SQLite + DB æ\97\81è·¯æ\9c\8då\8a¡ï¼\88db-sidecarï¼\8c:37823ï¼\89</td><td>ç«\99ç\82¹ã\80\81Cubeã\80\81èµ\84产ã\80\81è\8f\9cå\8d\95ã\80\81页é\9d¢æ ·å¼\8fã\80\81æ\96\87件ç\89æ\8c\81ä¹\85å\8c\96</td></tr>
- <tr><td>AI</td><td>codebuddy CLI（ai-sidecar :37822 代理 /api/chat；db-sidecar 直接调用）</td><td>以 <code>--output-format stream-json</code> 调用，模型固定 Hy3</td></tr>
- <tr><td>生成</td><td>dashboard-json-generator Skill</td><td>其 Cube 仪表盘结构规则注入到提示词中，由模型据此生成 JSON <span class="tag">提示词驱动</span></td></tr>
+ <tr><td>数据</td><td>SQLite + DB 旁路服务（db-sidecar）</td><td>站点、Cube、资产、菜单、页面样式、文件等持久化</td></tr>
+ <tr><td>AI</td><td>AI 生成服务（ai-sidecar 代理 /api/chat；db-sidecar 直接调用）</td><td>以流式 JSON 输出调用，模型由后端统一配置</td></tr>
+ <tr><td>生成</td><td>可视化生成 Skill</td><td>其 Cube 仪表盘结构规则注入到提示词中，由模型据此生成 JSON <span class="tag">提示词驱动</span></td></tr>
</table>
<div class="flow">
- <p><b>数据流</b>：浏览器 → Worker(<code>/api/db</code>) → db-sidecar(SQLite) ；生成时 db-sidecar 直接 <code>spawn</code> codebuddy CLI → 模型+Skill → 解析 JSON 入库 → 以 NDJSON 流式回传进度/日志 → 前端「AI 生成工作流」终端实时显示。</p>
+ <p><b>数据流</b>：浏览器 → Worker(<code>/api/db</code>) → db-sidecar(SQLite) ；生成时 db-sidecar 直接调用 AI 生成服务 → 模型+Skill → 解析 JSON 入库 → 以 NDJSON 流式回传进度/日志 → 前端「AI 生成工作流」终端实时显示。</p>
</div>
<h2>4. 整体导航与菜单</h2>
<tr><td>汉堡按钮 ☰</td><td>布局占位（移动端菜单预留）</td><td>—</td><td>当前无行为 <span class="todo">尚未实现</span></td></tr>
<tr><td>品牌区 iStation / iStation Team / StationBuilder⌄</td><td>标识当前产品与模块</td><td>静态</td><td>纯展示</td></tr>
<tr><td><b>设计方案</b> 链接</td><td>打开本设计文档</td><td>静态链接 <code>/design-doc.html</code></td><td>新标签页打开；位于登录者名称左侧</td></tr>
- <tr><td>模型选择（Wordbuddy AI · 模型名⌄）</td><td>切换 AI 问答模型</td><td>前端 <code>MODELS</code> 常量</td><td>点击弹出模型列表，仅「免费」模型可选（其余置灰）；<b>仅影响 AI 问答，不影响生成（生成固定 Hy3）</b></td></tr>
+ <tr><td>模型选择（AI 问答 · 模型名⌄）</td><td>切换 AI 问答模型</td><td>前端 <code>MODELS</code> 常量</td><td>点击弹出模型列表，仅「免费」模型可选（其余置灰）；<b>仅影响 AI 问答，不影响生成（生成使用后端固定配置模型）</b></td></tr>
<tr><td>登录者头像 W / 邮箱</td><td>当前登录身份展示；返回登录页</td><td>静态演示</td><td>点击头像回到内部登录页 <span class="todo">登录态尚未实现</span></td></tr>
</table>
<tr><td>页面生成提示词（站点级 / 每页）</td><td>生成前核对组合提示词</td><td>前端本地拼装（与后端 buildCubePrompt 同源逻辑）</td><td>「查看提示词」打开模态框，可复制</td></tr>
<tr><td>生成选项（复选）</td><td>选择交付物范围</td><td>静态</td><td>勾选态；仅「生成 Asset Excel」置灰 <span class="todo">Asset Excel 尚未实现</span>，其余默认勾选</td></tr>
<tr><td>生成任务面板（进度条 / 任务列表）</td><td>展示生成进度</td><td>POST /api/db/sites/:id/generate-all 流式</td><td>NDJSON 逐事件更新任务状态与百分比</td></tr>
- <tr><td><b>AI 生成工作流</b> 终端</td><td>只读实时展示 CLI/AI/Skill 过程</td><td>同一流式响应中的 <code>{log}</code> 事件</td><td>模型实时输出与 Skill 调用标记逐行滚动显示；点开始生成时清空</td></tr>
+ <tr><td><b>AI 生成工作流</b> 终端</td><td>只读实时展示 AI/Skill 生成过程</td><td>同一流式响应中的 <code>{log}</code> 事件</td><td>模型实时输出与 Skill 调用标记逐行滚动显示；点开始生成时清空</td></tr>
<tr><td>「开始生成 / 重新生成」</td><td>发起全站生成</td><td>POST generate-all</td><td>禁用直至完成；完成后出现「下载 ZIP」</td></tr>
<tr><td>「下载 ZIP」</td><td>下载全部交付物</td><td>GET /api/db/sites/:id/package</td><td>新标签页下载 station-package.zip</td></tr>
</table>
<tr><td>结果头（状态 / 修改配置 / 下载全部 / 版本历史）</td><td>概览与操作入口</td><td>当前 site</td><td>「修改配置」回 assets；「下载全部」取 package；「版本历史」开模态</td></tr>
<tr><td>KPI 条</td><td>资产/MU/Cube/交付文件统计</td><td>本地计算</td><td>纯展示</td></tr>
<tr><td>页面结果卡片（缩略图 + 状态 + 预览/JSON/提示词/修改意见）</td><td>逐页查看与操作</td><td>GET /api/db/sites/:id/cubes/:cid/file</td><td>缩略图由 dashboard-renderer 渲染生成 JSON；各按钮分别预览/下载/看提示词/提修改意见</td></tr>
- <tr><td>「✎ 修改意见」</td><td>对单页提反馈并重新生成</td><td>POST /api/db/sites/:id/cubes/:cid/refine 流式</td><td>只要该页<b>已有生成文件</b>（含「生成失败」但留有 JSON 的页面）即显示此按钮；打开反馈模态，提交后在当前页 JSON 基础上按意见重新生成；提交后模态内「修改意见」下方出现黑底白字的 <b>AI 生成工作流</b> 只读终端，实时滚动展示 CLI/AI/Skill 过程与进度，完成后自动刷新结果并关闭模态</td></tr>
+ <tr><td>「✎ 修改意见」</td><td>对单页提反馈并重新生成</td><td>POST /api/db/sites/:id/cubes/:cid/refine 流式</td><td>只要该页<b>已有生成文件</b>（含「生成失败」但留有 JSON 的页面）即显示此按钮；打开反馈模态，提交后在当前页 JSON 基础上按意见重新生成；提交后模态内「修改意见」下方出现黑底白字的 <b>AI 生成工作流</b> 只读终端，实时滚动展示 AI/Skill 生成过程与进度，完成后自动刷新结果并关闭模态</td></tr>
</table>
<p class="note">页面结果卡片默认<b>纵向单列</b>排列（上下结构），每张卡片占满整行，便于在多个 Cube 页面间逐张查看与操作；每张卡片底部并排展示「预览 / JSON / 提示词 / 修改意见」四个按钮。</p>
<ol>
<li><b>发起</b>：在「生成确认」点「开始生成」→ 前端 <code>POST /api/db/sites/:id/generate-all</code>（携带各 Cube 的名称与内容）。</li>
<li><b>落库与准备</b>：db-sidecar 先持久化前端传入的 Cube，再以 <code>Promise.all</code> 并行调用各 Cube 的生成（各页相互独立，互不阻塞）。</li>
- <li><b>调用模型</b>：每页调用 <code>runCodebuddy(prompt, sessionId)</code> → <code>spawn</code> codebuddy CLI（<code>--model hy3</code>、<code>--output-format stream-json</code>、<code>--tools ""</code>）。提示词内含 dashboard-json-generator Skill 的 Cube 结构规则（DASHBOARD_SPEC）与站点/样式上下文；DASHBOARD_SPEC 已要求模拟数据精简（时序 ≤16 点、KPI/表格样例 ≤6 行）以缩短输出。</li>
+ <li><b>调用模型</b>：每页调用 AI 生成服务（后端 <code>runCodebuddy</code> 封装）→ 生成进程以流式 JSON 输出。提示词内含可视化生成 Skill 的 Cube 结构规则（DASHBOARD_SPEC）与站点/样式上下文；DASHBOARD_SPEC 已要求模拟数据精简（时序 ≤16 点、KPI/表格样例 ≤6 行）以缩短输出。</li>
<li><b>解析与校验（含代码级自动修复）</b>：从流式输出抽取 JSON → <code>fixDashboard</code> 先做代码级自动修复（修复 <code>x+w>24</code>、面板重叠、首面板 Title 定位、KPI/Radar/Line 等 <code>data</code> 字段、缺失 <code>id/gridPos</code> 等）→ 再 <code>validateDashboard</code> 复校；仅当残留问题确无法自动修复时才再次调用模型（最多 2 次模型调用，原 3 次）。</li>
<li><b>写回</b>：生成的 JSON 存入 gen_files 并关联 Cube，状态置为 generated，同时保存组合提示词。</li>
<li><b>打包</b>：全部页面完成后打包为 station-package.zip。</li>
</ol>
</div>
<div class="note">
- <p><b>模型说明</b>：生成固定使用 Hy3（后端硬编码），与顶栏「模型选择」无关——模型选择仅作用于右下角 AI 问答。每个 Cube 均新起一个 CLI 进程，存在进程冷启动耗时；实时日志可缓解等待时的“无反馈”感。</p>
+ <p><b>模型说明</b>：生成使用后端固定配置模型（硬编码），与顶栏「模型选择」无关——模型选择仅作用于右下角 AI 问答。每个 Cube 均新起一个生成进程，存在进程冷启动耗时；实时日志可缓解等待时的“无反馈”感。</p>
<p><b>单页生成</b>：在「功能与菜单」页对每个 Cube 点「生成」走非流式接口，<b>不</b>提供实时日志，仅结果刷新。</p>
<p><b>性能优化（本轮）</b>：在不影响显示效果的前提下做了四项优化 —— ① <b>代码级自动修复</b>：校验失败优先用 <code>fixDashboard</code> 程序化修正，避免为小问题重跑模型；② <b>精简模拟数据</b>：提示词约束时序 ≤16 点、样例 ≤6 行，缩小输出 token；⑤ <b>重试降级</b>：模型调用由最多 3 次降为最多 2 次（首次失败先走代码修复）；⑥ <b>并行生成</b>：整站各 Cube 由顺序改为 <code>Promise.all</code> 并发。综合效果：整站生成约 4–9× 提速（75–90% 耗时下降），单次超时页（16 面板）约 60% 提速；已较快的单页提升约 30%。</p>
</div>
<table>
<tr><th>元素</th><th>功能</th><th>数据来源</th><th>交互效果</th></tr>
<tr><td>右下角悬浮按钮（AI 图标）</td><td>打开 / 收起 AI 助手</td><td>—</td><td>点击开对话框；<b>可拖动改变位置，双击复位</b>（光标为 pointer，拖动时 grabbing）</td></tr>
- <tr><td>对话框（模型 · 消息流 / 输入框）</td><td>站点相关问答</td><td>POST /api/chat → ai-sidecar → codebuddy</td><td>流式显示回答；上下文隔离、禁用工具与写操作（仅问答）</td></tr>
+ <tr><td>对话框（模型 · 消息流 / 输入框）</td><td>站点相关问答</td><td>POST /api/chat → ai-sidecar → AI 生成服务</td><td>流式显示回答；上下文隔离、禁用工具与写操作（仅问答）</td></tr>
<tr><td>模型选择弹层</td><td>切换问答模型</td><td>前端 MODELS</td><td>仅免费模型可选</td></tr>
</table>
<h2>8. 模态框（Modal）</h2>
<table>
<tr><th>类型</th><th>功能</th><th>交互效果</th></tr>
- <tr><td>提出修改意见（feedback）</td><td>对单页提反馈并重新生成</td><td>弹窗顶部即「修改意见」输入框（自动聚焦），下方展示影响范围（仅当前页 / 模拟数据 / 不受影响项）；提交后弹窗内出现黑底白字的 <b>AI 生成工作流</b> 终端，实时滚动 CLI/AI/Skill 进度，完成后自动刷新并关闭</td></tr>
+ <tr><td>提出修改意见（feedback）</td><td>对单页提反馈并重新生成</td><td>弹窗顶部即「修改意见」输入框（自动聚焦），下方展示影响范围（仅当前页 / 模拟数据 / 不受影响项）；提交后弹窗内出现黑底白字的 <b>AI 生成工作流</b> 终端，实时滚动 AI/Skill 生成进度，完成后自动刷新并关闭</td></tr>
<tr><td>下载站点交付物（download）</td><td>选择下载项</td><td>列表含 Cube JSON / 菜单配置 / 报告；Asset Excel 占位 <span class="todo">尚未实现</span></td></tr>
<tr><td>版本历史（history）</td><td>查看版本</td><td>仅展示 V1 当前版本 <span class="todo">真实版本管理尚未实现</span></td></tr>
<tr><td>生成提示词（prompt）</td><td>查看/复制组合提示词</td><td>展示发送给模型的完整提示词，可复制到剪贴板</td></tr>
<li>页面预览中「站点监控」真实数据接入（当前为静态演示） <span class="todo">尚未实现</span></li>
<li>版本历史真实多版本管理（当前仅 V1 占位） <span class="todo">尚未实现</span></li>
<li>列表搜索 / 筛选的服务端查询（当前为前端过滤） <span class="todo">尚未实现</span></li>
- <li>生成模型可切换（当前后端固定 Hy3） <span class="todo">尚未实现</span></li>
+ <li>生成模型可切换（当前后端固定配置） <span class="todo">尚未实现</span></li>
<li>单页生成（functions 页）的实时日志 <span class="todo">尚未实现</span></li>
<li>顶栏汉堡按钮的移动端菜单 <span class="todo">尚未实现</span></li>
</ul>
projects / StationBuilder.git / commitdiff