架构准则

构建该仪表盘时，你必须严格遵守以下架构规则，以避免 HTML 文件演变为混乱且难以维护的巨石单体：

1. 标志性分隔（Banner 注释）： 使用高度醒目的注释将 HTML 文件划分为若干清晰的“区域”（Provinces）。这确保你（作为 Agent）能够安全地导航并精准编辑各功能区块。

   
   
   
    ... 
   
   
   
   
   
   
   
   
   
   
   

2. 领域分离原则： 禁止编写庞大的内联 Alpine 逻辑（例如：x-data="{ huge object }"）。你必须在“Alpine.js 状态与逻辑”区域中使用 Alpine.data()，将逻辑提取至独立、整洁的脚本块中。HTML 中仅保留绑定指令（如 x-data="dashboard()"、x-text、x-show 等）。

3. 静态三件套（应急方案）： 虽然首选单个 index.html 文件，但当仪表盘规模过大时，可将其拆分为三个文件：

   • index.html（结构与语义化 HTML）
   • app.js（Alpine Alpine.data() 及 D3 函数）
   • styles.css（自定义覆盖样式）
     禁止引入任何构建步骤。

添加高级可视化图表

当用户请求更复杂或更多样化的可视化效果时，你有两种主要实现路径：

1. 前端：新增 Alpine 与 D3.js 图表

默认模板已包含基础图表，但你可在 Alpine 前端中添加更专业的 D3.js 可视化组件。

• 工作流： 在 app.js（或 index.html 中的 script 标签）内的 Alpine.data() 块中新增方法。使用 D3.js 绑定 .jsonl 时间线数据，并渲染 SVG 或 Canvas 元素。
• 示例： 每日频率热力图、两个指标相关性散点图、技能/习惯追踪雷达图等。
• 约束： 保持 D3 代码简洁、模块化。将图表渲染函数隔离封装，使其支持在窗口尺寸变更或数据更新时重新渲染。

2. 后端：Python 生成的可视化图表

对于计算密集型、高度定制化或特殊类型的可视化输出（如词云、网络图、复合光栅图像），应利用 Python 后端能力。

• 工作流： 修改 server.py（或新建一个 Python 工作脚本），读取本地 Fulcra .jsonl 数据，借助 matplotlib、seaborn 或 networkx 等库进行处理，并将静态图像（如 .png、.svg）或预计算 JSON 结构输出至仪表盘目录。
• 集成方式： 更新 index.html，引用生成的图像（例如：），或让 Alpine 状态主动获取该高级 JSON 产物。
• 约束： 确保 Python 生成步骤可独立运行或可靠触发，使仪表盘始终反映最新数据，同时不破坏简易本地服务器范式。

使用方法

当用户提出“搭建 Web 应用”、“为 Fulcra 技能创建仪表盘”，或正从 fulcradynamics/agent-skills/fulcra-onboarding 技能迁移时，你应执行本技能提供的初始化脚本。

# 运行初始化脚本，搭建 Alpine 仪表盘
./scripts/setup-dashboard.sh 

若未提供 参数，则默认在当前工作目录下创建名为 fulcra-dashboard 的文件夹。

工作流程

上下文感知（独立运行 vs. 接续入门流程）：
请勿假设本技能总是在 fulcra-onboarding 后立即执行。

• 若接续入门流程： 用户很可能刚看到其数据的静态 HTML 预览。请承认这一过渡，并将本步骤定位为对已有预览的扩展构建与功能升级，使之成为实时交互式 Web 应用。充分利用用户刚刚建立的标注上下文，跳过冗余的数据发现环节，并沿用其偏好的主题风格。
• 若独立运行： 你必须首先探查用户希望可视化的数据类型（运行 uv tool run fulcra-api catalog 查看用户标注，并在继续前与其讨论选项）。

1. 脚手架搭建： 脚本将一份干净、无样式的 Alpine.js 仪表盘模板复制至目标目录。
2. 数据接入（需获得用户授权）： 使用 fulcra-api CLI 自动拉取用户相关的 Fulcra 数据。
   • 重要： 在拉取记录前，务必向用户申请调用 Fulcra API 构建仪表盘的许可。
   • 运行 uv tool run fulcra-api catalog 发现可用数据。注意：优先选用用户配置的数据（而非被动指标，如步数）。显式筛选满足以下任一条件的条目：categories 字段包含 "user_configured"，或 id 符合 *Annotation/ 格式（例如：ScaleAnnotation/1234-abcd...）。
   • 拉取用户自定义标注的记录（例如：uv tool run fulcra-api get-records "ScaleAnnotation/" "30 days" > timeline_name.jsonl）。
   • Agent 可见性包： 若用户此前已启用 Universal Agent Visibility Package（或你在其 catalog 中看到 “Agent Tasks Completed” 和 “Current Agent Work”），则必须一并拉取这些 Agent 标注，并明确将其加入 data.json 的 timelines 数组中，以便你的后台工作能与用户个人数据一同可视化。
   • 数据更新： 必须运行 data-updates CLI 命令获取时间线更新（例如：uv tool run fulcra-api data-updates "30 days" > data_updates.json），显式将其移至 public/data_updates.json，并在配置中以 "recordsProcessed": "data_updates.json" 形式链接，以填充“您的数据”图表。此步骤不得跳过。
   • 原始数据 dump 保留在根目录；仅将经审核确认的最终 .jsonl 与 .json 文件移入 public/ 目录，供前端读取。
   • public/data.json 配置文件作为清单文件（manifest），需映射页面布局与 public/ 目录下的 .jsonl 文件。你必须在时间线区块中包含标注的 description 字段，格式如下：{"summary": "当前数据及近期活动的简明概览...", "timelines": [{"id": "...", "title": "...", "description": "来自 catalog 的描述...", "icon": "...", "color": "...", "data": "timeline_name.jsonl"}], "recordsProcessed": "records_processed.jsonl"}。关键要求： 对于 "summary" 字段，你必须解析已下载的 .jsonl 数据，并撰写一段简短、个性化的文本摘要，准确概括数据所呈现的真实世界活动（例如：“您持续追踪情绪变化，本周略有下降”）。禁止撰写元描述（如“这是一个复古风格仪表盘”）。
   • 无需编写聚合脚本；仪表盘将在 init() 时自动解析 .jsonl 文件，并在前端原生完成图表所需的数据聚合。
3. 主题定制与可视化：
   • 主题发现： 向用户询问其期望的“主题”或“氛围”（例如：极简暗色模式、赛博朋克风、复古餐厅、太空站、温馨面包房）。
   • 贯彻主题（HTML 与文案）： 切勿保留默认样板！直接修改 index.html，重写主标题、副标题及所有组件标题以契合主题（例如：将 “Fulcra Dashboard” 改为 “The Cybernetic Core”，将 “Records Processed” 改为 “Baguettes Baked”）。将所有默认 emoji（如 📊 或 🛰️）替换为符合主题风格的图标。
   • 保留布局容器： 基础 HTML 与 CSS 文件使用 .layout-container 控制间距。请保持该结构不变。CSS 修改应限于颜色（通过更新 root 变量）、字体、边框、阴影及背景。
   • 原创艺术（必需）： 使用 image_generate 工具生成一幅极具创意的主题化图像。保存至文件夹，并在仪表盘页眉中通过 标签引用。风格规范： 图像必须具备极高画质，并与用户选定主题完美统一。无论主题倾向复古 2D 像素风、极简矢量插画，抑或现代感 3D 渲染，其具体艺术风格、配色方案与光影效果均须严格匹配你正在构建的 CSS 变量与整体美学。
   • 英雄区文字可读性与比例： 定制英雄区（hero header）时，请确保叠加于图像之上的文字具有高可读性。根据主题灵活适配技术方案（例如：科技/现代主题使用毛玻璃 backdrop-filter: blur() 区块；暗黑/情绪化主题使用环境 radial-gradient 暗角效果）。此外，英雄区不可占据整个视口。请保持紧凑（例如：min-height: 250px），确保核心遥测数据能在“首屏可见区域”（above the fold）显示。
   • 动态动画元素： 至少注入一个契合主题的 CSS 动画（在 theme.css 中使用标准 CSS @keyframes 定义），例如漂浮小行星、闪烁光标、嗡嗡飞虫，并将其绑定至 .animation-layer 或其他合适元素。
4. Git 仓库初始化：
   • 脚手架搭建完成后，你必须提示用户初始化 Git 仓库。
   • 检查系统是否已安装 git。基于其主题建议 1–2 个趣味仓库名。
   • 本地初始化（git init && git add . && git commit -m "Initial commit"）。暂勿推送至 GitHub。
5. 运行与验证：
   • 启动本地 Python 服务器预览仪表盘：

     cd 
     python3 server.py 8081 > dev.log 2>&1 &
     

   • 向用户提供 localhost 访问链接。
6. 公开发布（需获得用户授权并完成预览确认）：
   • 用户可能希望将仪表盘版本发布至公共互联网。
   • 内置 public 目录： 由于仪表盘本身已按 public/ 目录结构组织，且该目录仅包含 UI 与显式复制的数据文件，因此无需从零新建文件夹。
     1. 请用户在本地预览中确认所展示数据即为其希望分享的内容。
     2. 确保 public/ 目录中仅包含**前端所需的特定数据文件，而所有原始数据 dump、dev.log 或 Python 脚本均须安全保留在根目录之外。
   • 等待用户明确确认后再继续操作。
   • 若用户同意，请按易用性排序提供三种部署选项：
     • 选项 1：Surge（最简单，无需 Git）
       • 安装：npm install -g surge
       • 部署：在 public/ 目录内运行 surge。
       • 用户体验：终端将提示用户输入邮箱/密码，即时创建免费账户，并分配自动生成的域名。一键完成文件夹部署。
     • 选项 2：GitHub Pages（最适合版本控制）
       • 安装：确保已安装并认证 GitHub CLI（gh）（运行 gh auth status 验证）。
       • 部署：进入 public/ 目录，初始化 Git、创建仓库并推送（git init && git add . && git commit -m "Initial public export" && gh repo create --public --source=. --remote=origin --push）。
       • 启用 Pages：gh api repos/{owner}/{repo}/pages -X POST -f "source[branch]=main" -f "source[path]=/"。
       • 用户体验：创建标准 GitHub 仓库，并发布至 https://.github.io//。
     • 选项 3：Vercel（无需 Git，专业级托管）
       • 安装：npm i -g vercel
       • 部署：在 public/ 目录内运行 vercel deploy --prod。
       • 用户体验：如需认证则自动打开浏览器；随后在终端中交互式提问几个设置问题，再将文件夹直接上传至 Vercel 边缘网络。
   • 执行用户选定的部署路径，并提供最终的公开 URL。
7. 交接与后续步骤：
   • 用户查看完本地运行的实时仪表盘后，切勿就此终止。请主动说明可能的后续方向，以延续开发动力：
     • 丰富数据源： 从 Fulcra Context 应用接入被动数据（如位置、心率），或引入其他外部数据源，与用户自定义标注进行交叉分析。
     • 高级可视化： 构建更复杂的 D3.js 图表或特定维度的数据汇总视图。
     • Python 数据分析： 在 Python 后端（server.py）中设置脚本，在数据发送至前端前对其进行分析处理。