From 1eb1792d029eb0d919be423c50acbf3e7c25eab6 Mon Sep 17 00:00:00 2001 From: "wang.yu" Date: Mon, 17 Aug 2026 22:08:32 +0800 Subject: [PATCH] =?utf8?q?docs:=20=E8=AE=BE=E8=AE=A1=E6=96=B9=E6=A1=88?= =?utf8?q?=E6=8F=8F=E8=BF=B0=E8=84=B1=E6=95=8F=EF=BC=8C=E7=A7=BB=E9=99=A4?= =?utf8?q?=E7=AB=99=E7=82=B9=E9=9A=90=E7=A7=81=E4=B8=8E=E5=85=B7=E4=BD=93?= =?utf8?q?=20AI=20=E6=9C=8D=E5=8A=A1=E4=BF=A1=E6=81=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit - 移除 IP/端口(:37823/:37822 等)、DNS、域名等站点隐私信息，改为组件名 - 将 codebuddy CLI / Wordbuddy Hy3 / dashboard-json-generator Skill 等具体 AI 服务描述 改写为中性的「AI 生成服务」「可视化生成 Skill」「后端固定配置模型」等表述 - 保留通用技术栈(Next.js/Vite/Cloudflare Worker)与接口路由，作为文档契约 --- public/design-doc.html | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/public/design-doc.html b/public/design-doc.html index 84717d3..bb897cd 100644 --- a/public/design-doc.html +++ b/public/design-doc.html @@ -86,18 +86,18 @@

2. 产品概述

-

StationBuilder 是面向 iStation 团队的内部工具，用于通过 AI（Wordbuddy Hy3）与 dashboard-json-generator Skill 快速生成站点的大屏看板（Cube 仪表盘 JSON）、资产配置、功能菜单与领域方案，并可预览、反馈微调与打包下载。核心用户路径为：站点列表 → 站点详情（基本属性 / 资产 / 功能与菜单 / 生成确认）→ 站点结果 / 页面预览。

+

StationBuilder 是面向 iStation 团队的内部工具，用于通过 AI 大模型与 可视化生成 Skill 快速生成站点的大屏看板（Cube 仪表盘 JSON）、资产配置、功能菜单与领域方案，并可预览、反馈微调与打包下载。核心用户路径为：站点列表 → 站点详情（基本属性 / 资产 / 功能与菜单 / 生成确认）→ 站点结果 / 页面预览。

3. 技术架构与运行环境

- - - + + +
层技术说明
前端Next.js 16 / React 19 / Vite 8 / Cloudflare Worker（Vinext）同源运行；Worker 路由代理 /api/db/* 与 /api/chat
数据SQLite + DB 旁路服务（db-sidecar，:37823）站点、Cube、资产、菜单、页面样式、文件等持久化
AIcodebuddy CLI（ai-sidecar :37822 代理 /api/chat；db-sidecar 直接调用）以 --output-format stream-json 调用，模型固定 Hy3
生成dashboard-json-generator Skill其 Cube 仪表盘结构规则注入到提示词中，由模型据此生成 JSON 提示词驱动
数据SQLite + DB 旁路服务（db-sidecar）站点、Cube、资产、菜单、页面样式、文件等持久化
AIAI 生成服务（ai-sidecar 代理 /api/chat；db-sidecar 直接调用）以流式 JSON 输出调用，模型由后端统一配置
生成可视化生成 Skill其 Cube 仪表盘结构规则注入到提示词中，由模型据此生成 JSON 提示词驱动
-

数据流：浏览器 → Worker(/api/db) → db-sidecar(SQLite) ；生成时 db-sidecar 直接 spawn codebuddy CLI → 模型+Skill → 解析 JSON 入库 → 以 NDJSON 流式回传进度/日志 → 前端「AI 生成工作流」终端实时显示。

+

数据流：浏览器 → Worker(/api/db) → db-sidecar(SQLite) ；生成时 db-sidecar 直接调用 AI 生成服务 → 模型+Skill → 解析 JSON 入库 → 以 NDJSON 流式回传进度/日志 → 前端「AI 生成工作流」终端实时显示。

4. 整体导航与菜单

@@ -108,7 +108,7 @@ 汉堡按钮 ☰布局占位（移动端菜单预留）—当前无行为 尚未实现 品牌区 iStation / iStation Team / StationBuilder⌄标识当前产品与模块静态纯展示 设计方案 链接打开本设计文档静态链接 /design-doc.html新标签页打开；位于登录者名称左侧 - 模型选择（Wordbuddy AI · 模型名⌄）切换 AI 问答模型前端 MODELS 常量点击弹出模型列表，仅「免费」模型可选（其余置灰）；仅影响 AI 问答，不影响生成（生成固定 Hy3） + 模型选择（AI 问答 · 模型名⌄）切换 AI 问答模型前端 MODELS 常量点击弹出模型列表，仅「免费」模型可选（其余置灰）；仅影响 AI 问答，不影响生成（生成使用后端固定配置模型） 登录者头像 W / 邮箱当前登录身份展示；返回登录页静态演示点击头像回到内部登录页 登录态尚未实现 @@ -239,7 +239,7 @@ 页面生成提示词（站点级 / 每页）生成前核对组合提示词前端本地拼装（与后端 buildCubePrompt 同源逻辑）「查看提示词」打开模态框，可复制 生成选项（复选）选择交付物范围静态勾选态；仅「生成 Asset Excel」置灰 Asset Excel 尚未实现，其余默认勾选 生成任务面板（进度条 / 任务列表）展示生成进度POST /api/db/sites/:id/generate-all 流式NDJSON 逐事件更新任务状态与百分比 - AI 生成工作流 终端只读实时展示 CLI/AI/Skill 过程同一流式响应中的 {log} 事件模型实时输出与 Skill 调用标记逐行滚动显示；点开始生成时清空 + AI 生成工作流 终端只读实时展示 AI/Skill 生成过程同一流式响应中的 {log} 事件模型实时输出与 Skill 调用标记逐行滚动显示；点开始生成时清空 「开始生成 / 重新生成」发起全站生成POST generate-all禁用直至完成；完成后出现「下载 ZIP」 「下载 ZIP」下载全部交付物GET /api/db/sites/:id/package新标签页下载 station-package.zip @@ -250,7 +250,7 @@ 结果头（状态 / 修改配置 / 下载全部 / 版本历史）概览与操作入口当前 site「修改配置」回 assets；「下载全部」取 package；「版本历史」开模态 KPI 条资产/MU/Cube/交付文件统计本地计算纯展示 页面结果卡片（缩略图 + 状态 + 预览/JSON/提示词/修改意见）逐页查看与操作GET /api/db/sites/:id/cubes/:cid/file缩略图由 dashboard-renderer 渲染生成 JSON；各按钮分别预览/下载/看提示词/提修改意见 - 「✎ 修改意见」对单页提反馈并重新生成POST /api/db/sites/:id/cubes/:cid/refine 流式只要该页已有生成文件（含「生成失败」但留有 JSON 的页面）即显示此按钮；打开反馈模态，提交后在当前页 JSON 基础上按意见重新生成；提交后模态内「修改意见」下方出现黑底白字的 AI 生成工作流 只读终端，实时滚动展示 CLI/AI/Skill 过程与进度，完成后自动刷新结果并关闭模态 + 「✎ 修改意见」对单页提反馈并重新生成POST /api/db/sites/:id/cubes/:cid/refine 流式只要该页已有生成文件（含「生成失败」但留有 JSON 的页面）即显示此按钮；打开反馈模态，提交后在当前页 JSON 基础上按意见重新生成；提交后模态内「修改意见」下方出现黑底白字的 AI 生成工作流 只读终端，实时滚动展示 AI/Skill 生成过程与进度，完成后自动刷新结果并关闭模态

页面结果卡片默认纵向单列排列（上下结构），每张卡片占满整行，便于在多个 Cube 页面间逐张查看与操作；每张卡片底部并排展示「预览 / JSON / 提示词 / 修改意见」四个按钮。

@@ -293,7 +293,7 @@
  1. 发起：在「生成确认」点「开始生成」→ 前端 POST /api/db/sites/:id/generate-all（携带各 Cube 的名称与内容）。
  2. 落库与准备：db-sidecar 先持久化前端传入的 Cube，再以 Promise.all 并行调用各 Cube 的生成（各页相互独立，互不阻塞）。
    3. -
  3. 调用模型：每页调用 runCodebuddy(prompt, sessionId) → spawn codebuddy CLI（--model hy3、--output-format stream-json、--tools ""）。提示词内含 dashboard-json-generator Skill 的 Cube 结构规则（DASHBOARD_SPEC）与站点/样式上下文；DASHBOARD_SPEC 已要求模拟数据精简（时序 ≤16 点、KPI/表格样例 ≤6 行）以缩短输出。
    4. +
  4. 调用模型：每页调用 AI 生成服务（后端 runCodebuddy 封装）→ 生成进程以流式 JSON 输出。提示词内含可视化生成 Skill 的 Cube 结构规则（DASHBOARD_SPEC）与站点/样式上下文；DASHBOARD_SPEC 已要求模拟数据精简（时序 ≤16 点、KPI/表格样例 ≤6 行）以缩短输出。
  5. 解析与校验（含代码级自动修复）：从流式输出抽取 JSON → fixDashboard 先做代码级自动修复（修复 x+w>24、面板重叠、首面板 Title 定位、KPI/Radar/Line 等 data 字段、缺失 id/gridPos 等）→ 再 validateDashboard 复校；仅当残留问题确无法自动修复时才再次调用模型（最多 2 次模型调用，原 3 次）。
  6. 写回：生成的 JSON 存入 gen_files 并关联 Cube，状态置为 generated，同时保存组合提示词。
  7. 打包：全部页面完成后打包为 station-package.zip。
    8. @@ -301,7 +301,7 @@
-

模型说明：生成固定使用 Hy3（后端硬编码），与顶栏「模型选择」无关——模型选择仅作用于右下角 AI 问答。每个 Cube 均新起一个 CLI 进程，存在进程冷启动耗时；实时日志可缓解等待时的“无反馈”感。

+

模型说明：生成使用后端固定配置模型（硬编码），与顶栏「模型选择」无关——模型选择仅作用于右下角 AI 问答。每个 Cube 均新起一个生成进程，存在进程冷启动耗时；实时日志可缓解等待时的“无反馈”感。

单页生成：在「功能与菜单」页对每个 Cube 点「生成」走非流式接口，不提供实时日志，仅结果刷新。

性能优化（本轮）：在不影响显示效果的前提下做了四项优化 —— ① 代码级自动修复：校验失败优先用 fixDashboard 程序化修正，避免为小问题重跑模型；② 精简模拟数据：提示词约束时序 ≤16 点、样例 ≤6 行，缩小输出 token；⑤ 重试降级：模型调用由最多 3 次降为最多 2 次（首次失败先走代码修复）；⑥ 并行生成：整站各 Cube 由顺序改为 Promise.all 并发。综合效果：整站生成约 4–9× 提速（75–90% 耗时下降），单次超时页（16 面板）约 60% 提速；已较快的单页提升约 30%。

@@ -310,14 +310,14 @@ - +
元素功能数据来源交互效果
右下角悬浮按钮（AI 图标）打开 / 收起 AI 助手—点击开对话框；可拖动改变位置，双击复位（光标为 pointer，拖动时 grabbing）
对话框（模型 · 消息流 / 输入框）站点相关问答POST /api/chat → ai-sidecar → codebuddy流式显示回答；上下文隔离、禁用工具与写操作（仅问答）
对话框（模型 · 消息流 / 输入框）站点相关问答POST /api/chat → ai-sidecar → AI 生成服务流式显示回答；上下文隔离、禁用工具与写操作（仅问答）
模型选择弹层切换问答模型前端 MODELS仅免费模型可选

8. 模态框（Modal）

- + @@ -341,7 +341,7 @@
  • 页面预览中「站点监控」真实数据接入（当前为静态演示） 尚未实现
  • 版本历史真实多版本管理（当前仅 V1 占位） 尚未实现
  • 列表搜索 / 筛选的服务端查询（当前为前端过滤） 尚未实现
    • -
  • 生成模型可切换（当前后端固定 Hy3） 尚未实现
    • +
  • 生成模型可切换（当前后端固定配置） 尚未实现
  • 单页生成（functions 页）的实时日志 尚未实现
  • 顶栏汉堡按钮的移动端菜单 尚未实现
    • -- 2.43.0
    类型功能交互效果
    提出修改意见（feedback）对单页提反馈并重新生成弹窗顶部即「修改意见」输入框（自动聚焦），下方展示影响范围（仅当前页 / 模拟数据 / 不受影响项）；提交后弹窗内出现黑底白字的 AI 生成工作流 终端，实时滚动 CLI/AI/Skill 进度，完成后自动刷新并关闭
    提出修改意见（feedback）对单页提反馈并重新生成弹窗顶部即「修改意见」输入框（自动聚焦），下方展示影响范围（仅当前页 / 模拟数据 / 不受影响项）；提交后弹窗内出现黑底白字的 AI 生成工作流 终端，实时滚动 AI/Skill 生成进度，完成后自动刷新并关闭
    下载站点交付物（download）选择下载项列表含 Cube JSON / 菜单配置 / 报告；Asset Excel 占位 尚未实现
    版本历史（history）查看版本仅展示 V1 当前版本 真实版本管理尚未实现
    生成提示词（prompt）查看/复制组合提示词展示发送给模型的完整提示词，可复制到剪贴板