图谱视图

图谱视图（Graph View）以 Neo4j 风格的力导向图展示项目中任务、草稿、里程碑之间的依赖与归属关系，以及 Wiki、文档、决策构成的知识网络。它由内置的依赖图谱服务驱动：该服务扫描 backlog/ 下的 Markdown 文件构建图数据库，随文件变更自动增量更新，无需手工维护。

进入图谱页面

启动 Web 界面后，侧边栏「统计」下方提供两个图谱入口：

• 图谱（/graph）：任务依赖图谱，节点为任务、已完成任务、草稿与里程碑
• 知识图谱（/knowledge）：知识网络，节点为 Wiki 页面、文档、决策与标签（Tag）

直接访问 /graph 或 /knowledge 链接也能打开对应页面。

节点与边的视觉约定

• 节点形状与颜色：按类别区分（任务 / 已完成 / 草稿 / 里程碑 / Wiki / 文档 / 决策 / 标签），节点半径反映连接度（连接越多越大）；标题以字幕板形式随缩放层级逐步披露
• 主题感知描边：浅色主题下每种节点类型切换为同色相的深色边框、边颜色同步加深，避免浅底色上"边像空隙、节点像无轮廓圆点"的 wash-out 问题；深色主题配色保持不变
• 边的样式：
  • DependsOn（依赖）：实线
  • ParentOf（父子）：虚线，箭头指向父任务
  • BelongsToMilestone（归属里程碑）：点线
  • 知识图谱中另有 TaggedWith（标签）、SourcedFrom（来源）、LinksTo（wikilink 引用）边
• 图例：页面提供可点击的图例，点击某个节点类别可将其暂时隐藏（再次点击恢复），便于聚焦特定类型的节点；图例中的采样线使用与画布边相同的主题感知颜色，两者永不不一致

交互操作

页面右上角提供缩放控制组（放大、缩小、总览）。图谱通过 WebSocket 接收 graph-updated 广播，任何文件变更都会在原视口中原地刷新，不会打断当前浏览位置。

任务详情中的关系图

任务详情模态框的 Dependencies 区域标题右侧有一个关系图切换按钮，点击后将模态框正文切换为以当前任务为中心的关系子图：

• 子图沿依赖、父子、里程碑边双向展开（有深度与节点数上限），节点点击可继续钻取到邻居任务
• 每个任务的图视图状态（缩放位置、图例过滤）独立记忆，钻取后返回时原样恢复
• 再次点击标题栏的 ← 返回 箭头或按 Esc 退回任务详情正文

此外，模态框还会展示依赖闭包查询结果：「Waits for / Waited on by」（等待谁 / 被谁等待）按跳数分层列出，根阻塞任务高亮；无法解析或构成循环的引用也会如实标注。对依赖的内联编辑若被拒绝（例如会构成循环），界面会回滚修改并显示本地化原因。

高 DPI 渲染性能

在 Retina / 4K 等高像素密度屏幕上，图谱画布现在做了针对性优化，重绘开销显著下降：

• 视口裁剪：只绘制当前可见区域内的节点与边，视口外的图元直接跳过
• 批量绘制：边按 (dash, alpha)、节点按 (style, alpha) 分组，同组一次批绘，减少绘制调用
• DPR 上限：设备像素比（devicePixelRatio）封顶在 MAX_DPR=2，避免超高 DPI 屏无意义地渲染超出肉眼分辨能力的像素
• 文本 LOD：标签按缩放层级分三阶段（textStage）渐进显示，缩得越远越省略文字，最远时只画节点
• 手势快照：平移 / 缩放过程中复用上一帧快照，仅在新帧稳定后重绘，消除拖拽卡顿

以上优化均为纯渲染层，不改变图数据、布局或交互语义。

图谱服务与缓存

图谱服务随 Web 服务器自动启动，首次构建期间 /api/graph 返回 building 状态，完成后图谱页面自动可用：

• 扫描范围：仅 backlog/ 下的 tasks、drafts、milestones、completed（任务图谱）与 wiki、docs、decisions（知识图谱）；归档目录不进入图谱
• 冷启动加速：按文件指纹缓存校验，未变更的文件不重新解析；解析器或图结构版本升级会自动触发全量重建
• 热更新：CLI / TUI / Web / MCP 的任何写入都会通过钩子通知图谱服务做增量同步，另有目录监听与定期 reconciliation 兜底
• 缓存位置：图数据存放在操作系统缓存目录（而非项目树内），按项目路径哈希分槽存放，两个浏览器会话各自持有独立数据库互不争抢；可用环境变量 BACKLOG_GRAPH_CACHE_DIR 覆盖缓存目录。缓存目录里只有锁文件与指纹边车（*.kuzu.lock、*.kuzu.meta.json）落盘，数据库本体在 WASM 的内存文件系统里——这是设计而非残缺，图谱可由 Markdown 随时重建
• 后端：默认使用 RyuGraph WASM 后端（Kuzu 的 MIT fork 的 WebAssembly 构建，在 Bun 的 WebAssembly 运行时内执行，各平台开箱即用，无需环境变量）；原生 Kuzu 依赖已移除，BACKLOG_GRAPH_BACKEND=kuzu 不再是合法取值。BACKLOG_GRAPH_BACKEND=memory 可强制纯 JS 内存降级模式（不支持 Cypher 搜索）；ryu 初始化失败时也会自动回退到内存后端而不会崩溃。降级时终端打印一行英文告警（[graph] RyuGraph (WASM) backend init failed for <path> ...），Web 界面也原样显示服务端返回的英文错误信息
• 锁冲突：同一项目的图谱槽位同一时刻只允许一个进程持有；持有方进程已退出时自动回收锁，持有方仍存活时在交互终端中询问是否接管（卡 building 与接管的排查见故障排查）

图谱只做可视化与查询，从不回写 Markdown 文件——所有数据仍以 backlog/ 下的文件为唯一事实来源。