[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-Dicklesworthstone--beads_viewer":3,"tool-Dicklesworthstone--beads_viewer":64},[4,19,28,36,44,56],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":18},9989,"n8n","n8n-io\u002Fn8n","n8n 是一款面向技术团队的公平代码（fair-code）工作流自动化平台，旨在让用户在享受低代码快速构建便利的同时，保留编写自定义代码的灵活性。它主要解决了传统自动化工具要么过于封闭难以扩展、要么完全依赖手写代码效率低下的痛点，帮助用户轻松连接 400 多种应用与服务，实现复杂业务流程的自动化。\n\nn8n 特别适合开发者、工程师以及具备一定技术背景的业务人员使用。其核心亮点在于“按需编码”：既可以通过直观的可视化界面拖拽节点搭建流程，也能随时插入 JavaScript 或 Python 代码、调用 npm 包来处理复杂逻辑。此外，n8n 原生集成了基于 LangChain 的 AI 能力，支持用户利用自有数据和模型构建智能体工作流。在部署方面，n8n 提供极高的自由度，支持完全自托管以保障数据隐私和控制权，也提供云端服务选项。凭借活跃的社区生态和数百个现成模板，n8n 让构建强大且可控的自动化系统变得简单高效。",184740,2,"2026-04-19T23:22:26",[13,14,15,16,17],"数据工具","开发框架","Agent","图像","插件","ready",{"id":20,"name":21,"github_repo":22,"description_zh":23,"stars":24,"difficulty_score":25,"last_commit_at":26,"category_tags":27,"status":18},8272,"opencode","anomalyco\u002Fopencode","OpenCode 是一款开源的 AI 编程助手（Coding Agent），旨在像一位智能搭档一样融入您的开发流程。它不仅仅是一个代码补全插件，而是一个能够理解项目上下文、自主规划任务并执行复杂编码操作的智能体。无论是生成全新功能、重构现有代码，还是排查难以定位的 Bug，OpenCode 都能通过自然语言交互高效完成，显著减少开发者在重复性劳动和上下文切换上的时间消耗。\n\n这款工具专为软件开发者、工程师及技术研究人员设计，特别适合希望利用大模型能力来提升编码效率、加速原型开发或处理遗留代码维护的专业人群。其核心亮点在于完全开源的架构，这意味着用户可以审查代码逻辑、自定义行为策略，甚至私有化部署以保障数据安全，彻底打破了传统闭源 AI 助手的“黑盒”限制。\n\n在技术体验上，OpenCode 提供了灵活的终端界面（Terminal UI）和正在测试中的桌面应用程序，支持 macOS、Windows 及 Linux 全平台。它兼容多种包管理工具，安装便捷，并能无缝集成到现有的开发环境中。无论您是追求极致控制权的资深极客，还是渴望提升产出的独立开发者，OpenCode 都提供了一个透明、可信",144296,1,"2026-04-16T14:50:03",[15,17],{"id":29,"name":30,"github_repo":31,"description_zh":32,"stars":33,"difficulty_score":10,"last_commit_at":34,"category_tags":35,"status":18},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[17,15,16,14],{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":10,"last_commit_at":42,"category_tags":43,"status":18},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[17,14],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":10,"last_commit_at":50,"category_tags":51,"status":18},2268,"ML-For-Beginners","microsoft\u002FML-For-Beginners","ML-For-Beginners 是由微软推出的一套系统化机器学习入门课程，旨在帮助零基础用户轻松掌握经典机器学习知识。这套课程将学习路径规划为 12 周，包含 26 节精炼课程和 52 道配套测验，内容涵盖从基础概念到实际应用的完整流程，有效解决了初学者面对庞大知识体系时无从下手、缺乏结构化指导的痛点。\n\n无论是希望转型的开发者、需要补充算法背景的研究人员，还是对人工智能充满好奇的普通爱好者，都能从中受益。课程不仅提供了清晰的理论讲解，还强调动手实践，让用户在循序渐进中建立扎实的技能基础。其独特的亮点在于强大的多语言支持，通过自动化机制提供了包括简体中文在内的 50 多种语言版本，极大地降低了全球不同背景用户的学习门槛。此外，项目采用开源协作模式，社区活跃且内容持续更新，确保学习者能获取前沿且准确的技术资讯。如果你正寻找一条清晰、友好且专业的机器学习入门之路，ML-For-Beginners 将是理想的起点。",85267,"2026-04-18T11:00:28",[16,13,52,17,15,53,54,14,55],"视频","其他","语言模型","音频",{"id":57,"name":58,"github_repo":59,"description_zh":60,"stars":61,"difficulty_score":10,"last_commit_at":62,"category_tags":63,"status":18},51,"gstack","garrytan\u002Fgstack","gstack 是 Y Combinator CEO Garry Tan 亲自开源的一套 AI 工程化配置，旨在将 Claude Code 升级为你的虚拟工程团队。面对单人开发难以兼顾产品战略、架构设计、代码审查及质量测试的挑战，gstack 提供了一套标准化解决方案，帮助开发者实现堪比二十人团队的高效产出。\n\n这套配置特别适合希望提升交付效率的创始人、技术负责人，以及初次尝试 Claude Code 的开发者。gstack 的核心亮点在于内置了 15 个具有明确职责的 AI 角色工具，涵盖 CEO、设计师、工程经理、QA 等职能。用户只需通过简单的斜杠命令（如 `\u002Freview` 进行代码审查、`\u002Fqa` 执行测试、`\u002Fplan-ceo-review` 规划功能），即可自动化处理从需求分析到部署上线的全链路任务。\n\n所有操作基于 Markdown 和斜杠命令，无需复杂配置，完全免费且遵循 MIT 协议。gstack 不仅是一套工具集，更是一种现代化的软件工厂实践，让单人开发者也能拥有严谨的工程流程。",77468,"2026-04-19T23:09:22",[15,17],{"id":65,"github_repo":66,"name":67,"description_en":68,"description_zh":69,"ai_summary_zh":69,"readme_en":70,"readme_zh":71,"quickstart_zh":72,"use_case_zh":73,"hero_image_url":74,"owner_login":75,"owner_name":76,"owner_avatar_url":77,"owner_bio":78,"owner_company":79,"owner_location":79,"owner_email":79,"owner_twitter":80,"owner_website":81,"owner_url":82,"languages":83,"stars":122,"forks":123,"last_commit_at":124,"license":125,"difficulty_score":25,"env_os":126,"env_gpu":127,"env_ram":128,"env_deps":129,"category_tags":135,"github_topics":136,"view_count":10,"oss_zip_url":79,"oss_zip_packed_at":79,"status":18,"created_at":142,"updated_at":143,"faqs":144,"releases":174},9870,"Dicklesworthstone\u002Fbeads_viewer","beads_viewer","Graph-aware TUI for the Beads issue tracker: PageRank, critical path, kanban, dependency DAG visualization, and robot-mode JSON API","beads_viewer 是一款专为 Beads 问题追踪器打造的终端界面工具，它让开发者能在命令行中高效浏览和管理复杂的项目依赖关系。面对大型代码库中错综复杂的任务依赖网，传统列表视图往往难以直观呈现关键路径或潜在循环，而 beads_viewer 通过图形感知技术，将抽象数据转化为可视化的看板、依赖有向无环图（DAG）及 PageRank 影响力分析，帮助用户快速定位瓶颈与核心任务。\n\n这款工具特别适合习惯键盘操作的后端工程师、系统架构师及 DevOps 人员，尤其是那些需要在无图形界面服务器环境中工作，或追求极致操作效率的技术团队。其独特亮点在于“机器人模式”（Robot Mode），可通过 JSON API 直接与大模型代理集成，实现自动化任务分拣与分析；同时支持多种视图切换，如一键查看关键路径、检测依赖环路以及看板流视图。无论是日常任务梳理还是深度架构审查，beads_viewer 都能以轻量、快速且信息丰富的方式，提升问题追踪的清晰度与决策效率。","# Beads Viewer (bv)\n\n![Release](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002FDicklesworthstone\u002Fbeads_viewer?style=for-the-badge&color=bd93f9)\n![Go Version](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fgo-mod\u002Fgo-version\u002FDicklesworthstone\u002Fbeads_viewer?style=for-the-badge&color=6272a4)\n![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT%2BOpenAI%2FAnthropic%20Rider-blue-the-badge)\n[![Coverage](https:\u002F\u002Fcodecov.io\u002Fgh\u002FDicklesworthstone\u002Fbeads_viewer\u002Fbranch\u002Fmain\u002Fgraph\u002Fbadge.svg)](https:\u002F\u002Fcodecov.io\u002Fgh\u002FDicklesworthstone\u002Fbeads_viewer)\n\n> **The elegant, keyboard-driven terminal interface for the [Beads](https:\u002F\u002Fgithub.com\u002Fsteveyegge\u002Fbeads) issue tracker.**\n\n\u003Cdiv align=\"center\" style=\"margin: 1.2em 0;\">\n \u003Ctable>\n \u003Ctr>\n \u003Ctd align=\"center\" style=\"padding: 8px;\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FDicklesworthstone_beads_viewer_readme_9f0f894e0937.webp\" alt=\"Main split view\" width=\"420\" \u002F>\n \u003Cdiv>\u003Csub>Main split view: fast list + rich details\u003C\u002Fsub>\u003C\u002Fdiv>\n \u003C\u002Ftd>\n \u003Ctd align=\"center\" style=\"padding: 8px;\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FDicklesworthstone_beads_viewer_readme_efbff7a1d279.webp\" alt=\"Kanban board\" width=\"420\" \u002F>\n \u003Cdiv>\u003Csub>Kanban board (`b`) for flow at a glance\u003C\u002Fsub>\u003C\u002Fdiv>\n \u003C\u002Ftd>\n \u003C\u002Ftr>\n \u003Ctr>\n \u003Ctd align=\"center\" style=\"padding: 8px;\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FDicklesworthstone_beads_viewer_readme_4a96d537151b.webp\" alt=\"Insights view\" width=\"420\" \u002F>\n \u003Cdiv>\u003Csub>Insights panel: PageRank, critical path, cycles\u003C\u002Fsub>\u003C\u002Fdiv>\n \u003C\u002Ftd>\n \u003Ctd align=\"center\" style=\"padding: 8px;\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FDicklesworthstone_beads_viewer_readme_f5239545f0b9.webp\" alt=\"Graph view\" width=\"420\" \u002F>\n \u003Cdiv>\u003Csub>Graph view (`g`): navigate the dependency DAG\u003C\u002Fsub>\u003C\u002Fdiv>\n \u003C\u002Ftd>\n \u003C\u002Ftr>\n \u003C\u002Ftable>\n\u003C\u002Fdiv>\n\n## Installation\n\n### Recommended: Homebrew (macOS\u002FLinux)\n\n```bash\nbrew install dicklesworthstone\u002Ftap\u002Fbv\n```\n\nThis method provides:\n- Automatic updates via `brew upgrade`\n- Dependency management\n- Easy uninstall via `brew uninstall`\n\n### Windows: Scoop\n\n```powershell\nscoop bucket add dicklesworthstone https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fscoop-bucket\nscoop install dicklesworthstone\u002Fbv\n```\n\n### Alternative: Direct Download\n\nDownload the latest release for your platform (tar.gz assets):\n- [Linux x86_64](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Freleases\u002Flatest\u002Fdownload\u002Fbv_0.13.0_linux_amd64.tar.gz)\n- [Linux ARM64](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Freleases\u002Flatest\u002Fdownload\u002Fbv_0.13.0_linux_arm64.tar.gz)\n- [macOS Intel](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Freleases\u002Flatest\u002Fdownload\u002Fbv_0.13.0_darwin_amd64.tar.gz)\n- [macOS ARM](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Freleases\u002Flatest\u002Fdownload\u002Fbv_0.13.0_darwin_arm64.tar.gz)\n- [Windows](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Freleases\u002Flatest\u002Fdownload\u002Fbv_0.13.0_windows_amd64.tar.gz)\n\n> Note: Asset names include the release version. If a link 404s, open the latest release page and download the matching asset.\n\n### Alternative: Install Script\n\n**Linux\u002FmacOS:**\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash\n```\n\n**Windows (PowerShell):**\n```powershell\nirm \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Fmain\u002Finstall.ps1\" | iex\n```\n> **Note:** Windows requires Go 1.21+ ([download](https:\u002F\u002Fgo.dev\u002Fdl\u002F)). For best display, use Windows Terminal with a [Nerd Font](https:\u002F\u002Fwww.nerdfonts.com\u002F).\n\n---\n\n## Generating the JSONL File (`br` and `bd`)\n\n`bv` reads from `.beads\u002Fbeads.jsonl`. Both the Rust-based `br` and the original Go-based `bd` can generate this file.\n\n**Rust (`br`) users** — `br` writes `.beads\u002Fbeads.jsonl` by default; no extra steps needed.\n\n**Go (`bd`) users** — run:\n\n```bash\nbd export --no-memories -o .beads\u002Fbeads.jsonl\n```\n\nOnce the file exists, `bv` works identically regardless of which tool produced it.\n\n---\n\n## 🤖 Agent Quickstart (Robot Mode)\n\n⚠️ **Never run bare `bv` in an agent context** — it launches the interactive TUI. Always use `--robot-*`.\n\n```bash\n# 1) Start with triage (single-call mega-command)\nbv --robot-triage\n\n# 2) Minimal mode: just the top pick + claim command\nbv --robot-next\n\n# 3) Token-optimized output (TOON)\nbv --robot-triage --format toon\nexport BV_OUTPUT_FORMAT=toon\n\n# 4) Full robot help\nbv --robot-help\n```\n\n**Output conventions**\n- stdout = JSON\u002FTOON data only\n- stderr = diagnostics\n- exit 0 = success\n\n## 💡 TL;DR\n\n`bv` is a high-performance **Terminal User Interface (TUI)** for browsing and managing tasks in projects that use the **Beads** issue tracking system. \n\n**Why you'd care:**\n* **Speed:** Browse thousands of issues instantly with zero network latency.\n* **Focus:** Stay in your terminal and use Vim-style keys (`j`\u002F`k`) to navigate.\n* **Intelligence:** It visualizes your project as a **dependency graph**, automatically highlighting bottlenecks, cycles, and critical paths that traditional list-based trackers miss.\n* **AI-Ready:** It provides structured, pre-computed insights for AI coding agents, acting as a \"brain\" for your project's task management.\n\n---\n\n## 📖 The Core Experience\n\nAt its heart, `bv` is about **viewing your work nicely**.\n\n### ⚡ Fast, Fluid Browsing\nNo web page loads, no heavy clients. `bv` starts instantly and lets you fly through your issue backlog using standard Vim keys (`j`\u002F`k`).\n* **Split-View Dashboard:** On wider screens, see your list on the left and full details on the right.\n* **Markdown Rendering:** Issue descriptions, comments, and notes are beautifully rendered with syntax highlighting, headers, and lists.\n* **Instant Filtering:** Zero-latency filtering. Press `o` for Open, `c` for Closed, or `r` for Ready (unblocked) tasks.\n* **Live Reload:** Watches `.beads\u002Fbeads.jsonl` and refreshes lists, details, and insights automatically when the file changes—no restart needed.\n\n### 🔎 Rich Context\nDon't just read the title. `bv` gives you the full picture:\n* **Comments & History:** Scroll through the full conversation history of any task.\n* **Metadata:** Instantly see Assignees, Labels, Priority badges, and creation dates.\n* **Search:** Powerful fuzzy search (`\u002F`) finds issues by ID, title, or content instantly.\n\n### 🎯 Focused Workflows\n* **Kanban Board:** Press `b` to switch to a columnar view (Open, In Progress, Blocked, Closed) to visualize flow.\n* **Visual Graph:** Press `g` to explore the dependency tree visually.\n* **Insights:** Press `i` to see graph metrics and bottlenecks.\n* **History View:** Press `h` to see the timeline of changes, correlating git commits with bead modifications. On wider terminals, enjoy a responsive three-pane layout showing commits, affected beads, and details.\n* **Ultra-Wide Mode:** On large monitors, the list expands to show extra columns like sparklines and label tags.\n\n### 🛠️ Quick Actions\n* **Export:** Press `E` to export all issues to a timestamped Markdown file with Mermaid diagrams.\n* **Graph Export (CLI):** `bv --robot-graph` outputs the dependency graph as JSON, DOT (Graphviz), or Mermaid format. Use `--graph-format=dot` for rendering with Graphviz, or `--graph-root=ID --graph-depth=3` to extract focused subgraphs.\n* **Copy:** Press `C` to copy the selected issue as formatted Markdown to your clipboard.\n* **Edit:** Press `O` to open the `.beads\u002Fbeads.jsonl` file in your preferred GUI editor.\n* **Time-Travel:** Press `t` to compare against any git revision, or `T` for quick HEAD~5 comparison. Combined with History view (`h`), you can navigate to any commit and see exactly what changed.\n\n### 🔌 Automation Hooks\nConfigure pre- and post-export hooks in `.bv\u002Fhooks.yaml` to run validations, notifications, or uploads. Defaults: pre-export hooks fail fast on errors (`on_error: fail`), post-export hooks log and continue (`on_error: continue`). Empty commands are ignored with a warning for safety. Hook env includes `BV_EXPORT_PATH`, `BV_EXPORT_FORMAT`, `BV_ISSUE_COUNT`, `BV_TIMESTAMP`, plus any custom `env` entries.\n\n---\n\n## 🤖 Ready-made Blurb to Drop Into Your AGENTS.md or CLAUDE.md Files\n\n```\n### Using bv as an AI sidecar\n\nbv is a graph-aware triage engine for Beads projects (.beads\u002Fbeads.jsonl). Instead of parsing JSONL or hallucinating graph traversal, use robot flags for deterministic, dependency-aware outputs with precomputed metrics (PageRank, betweenness, critical path, cycles, HITS, eigenvector, k-core).\n\n**Scope boundary:** bv handles *what to work on* (triage, priority, planning). For agent-to-agent coordination (messaging, work claiming, file reservations), use [MCP Agent Mail](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fmcp_agent_mail).\n\n**⚠️ CRITICAL: Use ONLY `--robot-*` flags. Bare `bv` launches an interactive TUI that blocks your session.**\n\n#### The Workflow: Start With Triage\n\n**`bv --robot-triage` is your single entry point.** It returns everything you need in one call:\n- `quick_ref`: at-a-glance counts + top 3 picks\n- `recommendations`: ranked actionable items with scores, reasons, unblock info\n- `quick_wins`: low-effort high-impact items\n- `blockers_to_clear`: items that unblock the most downstream work\n- `project_health`: status\u002Ftype\u002Fpriority distributions, graph metrics\n- `commands`: copy-paste shell commands for next steps\n\nbv --robot-triage # THE MEGA-COMMAND: start here\nbv --robot-next # Minimal: just the single top pick + claim command\n\n# Token-optimized output (TOON) for lower LLM context usage:\nbv --robot-triage --format toon\nexport BV_OUTPUT_FORMAT=toon\nbv --robot-next\n\n#### Other Commands\n\n**Planning:**\n| Command | Returns |\n|---------|---------|\n| `--robot-plan` | Parallel execution tracks with `unblocks` lists |\n| `--robot-priority` | Priority misalignment detection with confidence |\n\n**Graph Analysis:**\n| Command | Returns |\n|---------|---------|\n| `--robot-insights` | Full metrics: PageRank, betweenness, HITS (hubs\u002Fauthorities), eigenvector, critical path, cycles, k-core, articulation points, slack |\n| `--robot-label-health` | Per-label health: `health_level` (healthy\\|warning\\|critical), `velocity_score`, `staleness`, `blocked_count` |\n| `--robot-label-flow` | Cross-label dependency: `flow_matrix`, `dependencies`, `bottleneck_labels` |\n| `--robot-label-attention [--attention-limit=N]` | Attention-ranked labels by: (pagerank × staleness × block_impact) \u002F velocity |\n\n**History & Change Tracking:**\n| Command | Returns |\n|---------|---------|\n| `--robot-history` | Bead-to-commit correlations: `stats`, `histories` (per-bead events\u002Fcommits\u002Fmilestones), `commit_index` |\n| `--robot-diff --diff-since \u003Cref>` | Changes since ref: new\u002Fclosed\u002Fmodified issues, cycles introduced\u002Fresolved |\n\n**Other Commands:**\n| Command | Returns |\n|---------|---------|\n| `--robot-burndown \u003Csprint>` | Sprint burndown, scope changes, at-risk items |\n| `--robot-forecast \u003Cid\\|all>` | ETA predictions with dependency-aware scheduling |\n| `--robot-alerts` | Stale issues, blocking cascades, priority mismatches |\n| `--robot-suggest` | Hygiene: duplicates, missing deps, label suggestions, cycle breaks |\n| `--robot-graph [--graph-format=json\\|dot\\|mermaid]` | Dependency graph export |\n| `--export-graph \u003Cfile.html>` | Self-contained interactive HTML visualization |\n\n#### Scoping & Filtering\n\nbv --robot-plan --label backend # Scope to label's subgraph\nbv --robot-insights --as-of HEAD~30 # Historical point-in-time\nbv --recipe actionable --robot-plan # Pre-filter: ready to work (no blockers)\nbv --recipe high-impact --robot-triage # Pre-filter: top PageRank scores\nbv --robot-triage --robot-triage-by-track # Group by parallel work streams\nbv --robot-triage --robot-triage-by-label # Group by domain\n\n#### Understanding Robot Output\n\n**All robot JSON includes:**\n- `data_hash` — Fingerprint of source beads.jsonl (verify consistency across calls)\n- `status` — Per-metric state: `computed|approx|timeout|skipped` + elapsed ms\n- `as_of` \u002F `as_of_commit` — Present when using `--as-of`; contains ref and resolved SHA\n\n**Two-phase analysis:**\n- **Phase 1 (instant):** degree, topo sort, density — always available immediately\n- **Phase 2 (async, 500ms timeout):** PageRank, betweenness, HITS, eigenvector, cycles — check `status` flags\n\n**For large graphs (>500 nodes):** Some metrics may be approximated or skipped. Always check `status`.\n\n#### jq Quick Reference\n\nbv --robot-triage | jq '.quick_ref' # At-a-glance summary\nbv --robot-triage | jq '.recommendations[0]' # Top recommendation\nbv --robot-plan | jq '.plan.summary.highest_impact' # Best unblock target\nbv --robot-insights | jq '.status' # Check metric readiness\nbv --robot-insights | jq '.Cycles' # Circular deps (must fix!)\nbv --robot-label-health | jq '.results.labels[] | select(.health_level == \"critical\")'\n\n**Performance:** Phase 1 instant, Phase 2 async (500ms timeout). Prefer `--robot-plan` over `--robot-insights` when speed matters. Results cached by data hash.\n\nUse bv instead of parsing beads.jsonl—it computes PageRank, critical paths, cycles, and parallel tracks deterministically.\n```\n\n### Automatic Integration\n\n`bv` can automatically add the above instructions to your project's agent file:\n\n- **On first run**, bv checks for AGENTS.md (or similar files) and offers to inject the blurb if not present\n- Choose **\"Yes\"** to add the instructions, **\"No\"** to skip, or **\"Don't ask again\"** to remember your preference\n- Preferences are stored per-project in `~\u002F.config\u002Fbv\u002Fagent-prompts\u002F`\n\n**Supported Files** (checked in order):\n1. `AGENTS.md` (preferred)\n2. `CLAUDE.md`\n3. `agents.md`\n4. `claude.md`\n\n**Manual Control:**\n\n```bash\nbv --agents-check # Check if blurb is present in agent file\nbv --agents-add # Add blurb to agent file (creates file if needed)\nbv --agents-remove # Remove blurb from agent file\nbv --agents-update # Update blurb to latest version\nbv --agents-dry-run # Show what would happen without executing\n```\n\n**Version Tracking:**\n\nThe blurb uses HTML comment markers for version tracking:\n```\n\u003C!-- bv-agent-instructions-v1 -->\n... content ...\n\u003C!-- end-bv-agent-instructions -->\n```\n\nWhen a new version of the blurb is released, `bv` can detect the outdated version and offer to update it.\n\n---\n\n## 📐 Architecture & Design\n\n`bv` treats your project as a **Directed Acyclic Graph (DAG)**, not just a list. This allows it to derive insights about what is *truly* important.\n\n```mermaid\ngraph TD\n %% Soft Pastel Theme — Refined\n classDef data fill:#e3f2fd,stroke:#90caf9,stroke-width:2px,color:#1565c0,rx:8\n classDef logic fill:#fff8e1,stroke:#ffcc80,stroke-width:2px,color:#e65100,rx:8\n classDef ui fill:#f3e5f5,stroke:#ce93d8,stroke-width:2px,color:#6a1b9a,rx:8\n classDef output fill:#e8f5e9,stroke:#a5d6a7,stroke-width:2px,color:#2e7d32,rx:8\n\n subgraph storage [\" 📂 Data Layer \"]\n A[\".beads\u002Fbeads.jsonl\u003Cbr\u002F>JSONL Issue Store\"]:::data\n end\n\n subgraph engine [\" ⚙️ Analysis Engine \"]\n B[\"Loader\"]:::logic\n C[\"Graph Builder\"]:::logic\n D[\"9 Metrics\u003Cbr\u002F>PageRank · Betweenness · HITS...\"]:::logic\n end\n\n subgraph interface [\" 🖥️ TUI Layer \"]\n E[\"Bubble Tea Model\"]:::ui\n F[\"List View\"]:::ui\n G[\"Graph View\"]:::ui\n G2[\"Tree View\"]:::ui\n H[\"Insights Dashboard\"]:::ui\n end\n\n subgraph outputs [\" 📤 Outputs \"]\n I[\"--robot-insights\u003Cbr\u002F>JSON for AI Agents\"]:::output\n J[\"--export-md\u003Cbr\u002F>Markdown Report\"]:::output\n end\n\n A --> B\n B --> C\n C --> D\n D --> E\n D --> I\n D --> J\n E --> F\n E --> G\n E --> G2\n E --> H\n\n linkStyle 0,1,2 stroke:#90caf9,stroke-width:2px\n linkStyle 3,4,5 stroke:#ffcc80,stroke-width:2px\n linkStyle 6,7,8,9 stroke:#ce93d8,stroke-width:2px\n```\n\n### Key Metrics & Algorithms\n`bv` computes **9 graph-theoretic metrics** to surface hidden project dynamics:\n\n| # | Metric | What It Measures | Key Insight |\n|---|--------|------------------|-------------|\n| 1 | **PageRank** | Recursive dependency importance | Foundational blockers |\n| 2 | **Betweenness** | Shortest-path traffic | Bottlenecks & bridges |\n| 3 | **HITS** | Hub\u002FAuthority duality | Epics vs. utilities |\n| 4 | **Critical Path** | Longest dependency chain | Keystones with zero slack |\n| 5 | **Eigenvector** | Influence via neighbors | Strategic dependencies |\n| 6 | **Degree** | Direct connection counts | Immediate blockers\u002Fblocked |\n| 7 | **Density** | Edge-to-node ratio | Project coupling health |\n| 8 | **Cycles** | Circular dependencies | Structural errors |\n| 9 | **Topo Sort** | Valid execution order | Work queue foundation |\n\n### 1. PageRank (Dependency Authority)\n**The Math:** Originally designed to rank web pages by \"importance\" based on incoming links, PageRank models a \"random surfer\" walking the graph. In our dependency graph (u → v implies u depends on v), we treat dependencies as \"votes\" of importance.\n$$\nPR(v) = \\frac{1-d}{N} + d \\sum_{u \\in M(v)} \\frac{PR(u)}{L(u)}\n$$\n\n**The Intuition:** If many tasks depend on Task A, or if a single very important Task B depends on Task A, then Task A implicitly becomes \"heavy.\" A random walker following dependency links will frequently get stuck at Task A.\n\n**Pragmatic Meaning:** **Foundational Blocks.** High PageRank tasks are the bedrock of your project. They are rarely \"features\" in the user-facing sense; they are often schemas, core libraries, or architectural decisions. Breaking them breaks the graph.\n\n### 2. Betweenness Centrality (Bottlenecks)\n**The Math:** Defined as the fraction of all shortest paths in the network that pass through a given node $v$.\n$$C_B(v) = \\sum_{s \\neq v \\neq t} \\frac{\\sigma_{st}(v)}{\\sigma_{st}}$$\n\n**The Intuition:** Imagine information (or progress) flowing from every task to every other task along the most efficient route. \"Bridge nodes\" that connect otherwise isolated clusters (e.g., the Frontend cluster and the Backend cluster) will see a massive amount of traffic.\n\n**Pragmatic Meaning:** **Gatekeepers & Bottlenecks.** A task with high Betweenness is a choke point. It might be an API contract that both the mobile app and the server team are waiting on. If this task is delayed, it doesn't just block one thread; it prevents entire sub-teams from synchronizing.\n\n### 3. HITS (Hubs & Authorities)\n**The Math:** An iterative algorithm that defines two scores for every node:\n* **Authority:** The sum of Hub scores of nodes pointing to it.\n* **Hub:** The sum of Authority scores of nodes it points to.\n\n**The Intuition:** This models a \"mutually reinforcing\" relationship. Good libraries (Authorities) are used by many applications. Good applications (Hubs) use many good libraries.\n\n**Pragmatic Meaning:** **Epics vs. Infrastructure.**\n* **High Hub Score:** These are your **Epics** or **Product Features**. They aggregate many dependencies to deliver value.\n* **High Authority Score:** These are your **Utilities**. They provide value to many consumers.\n\n### 4. Critical Path (Longest Path in DAG)\n**The Math:** In a DAG, the longest path represents the minimum time required to complete the project (assuming infinite parallelism). `bv` computes this recursively:\n$$Impact(u) = 1 + \\max(\\{Impact(v) \\mid u \\to v\\})$$\n\n**The Intuition:** If you hold the graph by its \"leaf\" nodes (tasks with no dependencies) and let it dangle, the tasks at the very top that support the longest chains are carrying the most weight.\n\n**Pragmatic Meaning:** **Keystones.** A Keystone task is one where *any* delay translates 1:1 into a delay for the final project delivery. These tasks have zero \"slack.\"\n\n### 5. Eigenvector Centrality (Influential Neighbors)\n**The Math:** Eigenvector centrality measures a node's influence by considering not just its connections, but the importance of those connections. A node with few but highly influential neighbors can score higher than a node with many unimportant neighbors.\n$$x_i = \\frac{1}{\\lambda} \\sum_{j \\in N(i)} x_j$$\n\nWhere $\\lambda$ is the largest eigenvalue of the adjacency matrix and $N(i)$ are neighbors of node $i$.\n\n**The Intuition:** It's not just *how many* connections you have, but *who* you're connected to. Being depended on by a critical task makes you more important than being depended on by many trivial tasks.\n\n**Pragmatic Meaning:** **Strategic Dependencies.** High Eigenvector tasks are connected to the \"power players\" in your graph. They may not have many direct dependents, but their dependents are themselves critical.\n\n### 6. Degree Centrality (Direct Connections)\n**The Math:** The simplest centrality measure—just count the edges.\n$$C_D^{in}(v) = |\\{u : u \\to v\\}|$$\n\n$$C_D^{out}(v) = |\\{u : v \\to u\\}|$$\n\n**The Intuition:**\n* **In-Degree:** How many tasks depend on me? (I am a blocker)\n* **Out-Degree:** How many tasks do I depend on? (I am blocked)\n\n**Pragmatic Meaning:** **Immediate Impact.**\n* **High In-Degree:** This task is a direct blocker for many others. Completing it immediately unblocks work.\n* **High Out-Degree:** This task has many prerequisites. It's likely to be blocked and should be scheduled later in the execution plan.\n\n### 7. Graph Density (Interconnectedness)\n**The Math:** Density measures how \"connected\" the graph is relative to its maximum possible connections.\n$$D = \\frac{|E|}{|V|(|V|-1)}$$\n\nWhere $|E|$ is the edge count and $|V|$ is the node count. For a directed graph, the maximum edges is $|V|(|V|-1)$.\n\n**The Intuition:** A density of 0.0 means no dependencies exist (isolated tasks). A density approaching 1.0 means everything depends on everything (pathological complexity).\n\n**Pragmatic Meaning:** **Project Health Indicator.**\n* **Low Density (\u003C 0.05):** Healthy. Tasks are relatively independent and can be parallelized.\n* **Medium Density (0.05 - 0.15):** Normal. Reasonable interconnection reflecting real-world dependencies.\n* **High Density (> 0.15):** Warning. Overly coupled project. Consider breaking into smaller modules.\n\n### 8. Cycle Detection (Circular Dependencies)\n**The Math:** A cycle in a directed graph is a path v₁ → v₂ → ⋯ → vₖ → v₁ where the start and end nodes are identical. `bv` uses Tarjan's algorithm variant via `topo.DirectedCyclesIn` to enumerate all elementary cycles.\n\n**The Intuition:** If A depends on B, and B depends on A, neither can ever be completed. This is a logical impossibility that must be resolved.\n\n**Pragmatic Meaning:** **Structural Errors.** Cycles are **bugs in your project plan**, not just warnings. They indicate:\n* Misclassified dependencies (A doesn't really block B, or vice versa)\n* Missing intermediate tasks (A and B both depend on an unstated C)\n* Scope confusion (A and B should be merged into a single task)\n\n### 9. Topological Sort (Execution Order)\n**The Math:** A topological ordering of a DAG is a linear sequence of all vertices such that for every edge u → v, vertex u appears before v in the sequence. Only acyclic graphs have valid topological orderings.\n\n**The Intuition:** If you must complete tasks in dependency order, topological sort gives you *a* valid order (there may be many).\n\n**Pragmatic Meaning:** **Work Queue.** The topological order is the foundation of `bv`'s execution planning. Combined with priority weights, it generates the \"what to work on next\" recommendations that power `--robot-plan`.\n\n---\n\n## 🤖 The Robot Protocol (AI Interface)\n\n`bv` bridges the gap between raw data and AI agents. Agents struggle with graph algorithms; `bv` solves this by acting as a deterministic \"sidecar\" that offloads the cognitive burden of graph traversal.\n\n```mermaid\nsequenceDiagram\n %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8f5e9', 'primaryTextColor': '#2e7d32', 'primaryBorderColor': '#81c784', 'lineColor': '#90a4ae', 'secondaryColor': '#fff8e1', 'tertiaryColor': '#fce4ec'}}}%%\n\n participant User\n participant Agent as 🤖 AI Agent\n participant BV as ⚡ bv\n participant File as 📄 beads.jsonl\n\n User->>Agent: \"Fix the next blocked task\"\n\n rect rgba(232, 245, 233, 0.4)\n Note over Agent, BV: Cognitive Offloading\n Agent->>BV: bv --robot-plan\n BV->>File: Read & Parse\n BV->>BV: PageRank + Topo Sort\n BV-->>Agent: { next: \"TASK-123\", unblocks: 5 }\n end\n\n rect rgba(255, 243, 224, 0.3)\n Note over Agent: Implementation Phase\n Agent->>Agent: Fix TASK-123\n Agent->>BV: bv --robot-insights\n BV-->>Agent: Updated graph metrics\n end\n```\n\n### The \"Cognitive Offloading\" Strategy\nThe primary design goal of the Robot Protocol is **Cognitive Offloading**.\nLarge Language Models (LLMs) are probabilistic engines; they are excellent at semantic reasoning (coding, writing) but notoriously unreliable at algorithmic graph traversal (finding cycles, computing shortest paths). The two-phase analyzer returns degree\u002Ftopo\u002Fdensity immediately and completes PageRank\u002FBetweenness\u002FHITS\u002FEigenvector\u002FCritical Path\u002FCycles asynchronously with size-aware timeouts and hashed caching, so repeat robot calls stay fast when the graph hasn’t changed.\n\nIf you feed an Agent raw `beads.jsonl` data, you are forcing the Agent to:\n1. Parse thousands of lines of JSON.\n2. Reconstruct the dependency graph in its context window.\n3. \"Hallucinate\" a path traversal or cycle check.\n\n`bv` solves this by providing a deterministic graph engine sidecar.\n\n### Why `bv` vs. Raw Beads?\nUsing `beads` directly gives an agent *data*. Using `bv --robot-insights` gives an agent *intelligence*.\n\n| Capability | Raw Beads (JSONL) | `bv` Robot Mode |\n| :--- | :--- | :--- |\n| **Query** | \"List all issues.\" | \"List the top 5 bottlenecks blocking the release.\" |\n| **Context Cost** | High (Linear with issue count). | Low (Fixed summary struct). |\n| **Graph Logic** | Agent must infer\u002Fcompute. | Pre-computed (PageRank\u002FBrandes). |\n| **Safety** | Agent might miss a cycle. | Cycles explicitly flagged. |\n\n### Agent Usage Patterns\nAgents typically use `bv` in three phases:\n\n1. **Triage & Orientation:**\n Before starting a session, the agent runs `bv --robot-insights`. It receives a lightweight JSON summary of the project's structural health. It immediately knows:\n * \"I should not work on Task C yet because it depends on Task B, which is a Bottleneck.\"\n * \"The graph has a cycle (A->B->A); I must fix this structural error before adding new features.\"\n\n2. **Impact Analysis:**\n When asked to \"refactor the login module,\" the agent checks the **PageRank** and **Impact Scores** of the relevant beads. If the scores are high, the agent knows this is a high-risk change with many downstream dependents, prompting it to run more comprehensive tests.\n\n3. **Execution Planning:**\n Instead of guessing the order of operations, the agent uses `bv`'s topological sort to generate a strictly linearized plan.\n\n**JSON Output Schema (`--robot-insights`):**\nThe output is designed to be strictly typed and easily parseable by tools like `jq` or standard JSON libraries.\n```json\n{\n \"bottlenecks\": [\n { \"id\": \"CORE-123\", \"value\": 0.45 }\n ],\n \"keystones\": [\n { \"id\": \"API-001\", \"value\": 12.0 }\n ],\n \"influencers\": [\n { \"id\": \"AUTH-007\", \"value\": 0.82 }\n ],\n \"hubs\": [\n { \"id\": \"EPIC-100\", \"value\": 0.67 }\n ],\n \"authorities\": [\n { \"id\": \"UTIL-050\", \"value\": 0.91 }\n ],\n \"cycles\": [\n [\"TASK-A\", \"TASK-B\", \"TASK-A\"]\n ],\n \"clusterDensity\": 0.045,\n \"stats\": {\n \"pageRank\": { \"CORE-123\": 0.15, \"...\": \"...\" },\n \"betweenness\": { \"CORE-123\": 0.45, \"...\": \"...\" },\n \"eigenvector\": { \"AUTH-007\": 0.82, \"...\": \"...\" },\n \"hubs\": { \"EPIC-100\": 0.67, \"...\": \"...\" },\n \"authorities\": { \"UTIL-050\": 0.91, \"...\": \"...\" },\n \"inDegree\": { \"CORE-123\": 5, \"...\": \"...\" },\n \"outDegree\": { \"CORE-123\": 2, \"...\": \"...\" },\n \"criticalPathScore\": { \"API-001\": 12.0, \"...\": \"...\" },\n \"density\": 0.045,\n \"topologicalOrder\": [\"CORE-123\", \"API-001\", \"...\"]\n }\n}\n```\n\n| Field | Metric | What It Contains |\n|-------|--------|------------------|\n| `bottlenecks` | Betweenness | Top nodes bridging graph clusters |\n| `keystones` | Critical Path | Top nodes on longest dependency chains |\n| `influencers` | Eigenvector | Top nodes connected to important neighbors |\n| `hubs` | HITS Hub | Top dependency aggregators (Epics) |\n| `authorities` | HITS Authority | Top prerequisite providers (Utilities) |\n| `cycles` | Cycle Detection | All circular dependency paths |\n| `clusterDensity` | Density | Overall graph interconnectedness |\n| `stats` | All Metrics | Full raw data for custom analysis |\n\n---\n\n## 🎨 TUI Engineering & Craftsmanship\n\n`bv` is built with the **Bubble Tea** framework, ensuring a glitch-free, 60fps experience. It features an adaptive layout engine that responds to terminal resize events and a custom ASCII\u002FUnicode graph renderer.\n\n```mermaid\nflowchart LR\n classDef core fill:#fef3e2,stroke:#f5d0a9,stroke-width:2px,color:#8b5a2b\n classDef engine fill:#f0e6f6,stroke:#d4b8e0,stroke-width:2px,color:#5d3a6b\n classDef ui fill:#e6f3e6,stroke:#b8d9b8,stroke-width:2px,color:#2d5a2d\n classDef output fill:#e8f4f8,stroke:#b8d4e3,stroke-width:2px,color:#2c5f7c\n\n INPUT[\"⌨️ Input\u003Cbr\u002F>Keys · Mouse · Resize\"]:::core\n MODEL[\"🫖 Model\u003Cbr\u002F>Issues · Stats · Focus\"]:::core\n GRAPH[\"🧮 Graph Engine\u003Cbr\u002F>PageRank · HITS · Cycles\"]:::engine\n VIEWS[\"🖼️ Views\u003Cbr\u002F>List · Board · Graph · Tree · Insights\"]:::ui\n LAYOUT[\"📐 Layout\u003Cbr\u002F>Mobile · Split · Wide\"]:::ui\n TERM[\"🖥️ Terminal\u003Cbr\u002F>60fps Output\"]:::output\n\n INPUT -->|tea.Msg| MODEL\n GRAPH -->|metrics| MODEL\n MODEL -->|state| VIEWS\n VIEWS --> LAYOUT\n LAYOUT --> TERM\n\n linkStyle 0 stroke:#f5d0a9,stroke-width:2px\n linkStyle 1 stroke:#d4b8e0,stroke-width:2px\n linkStyle 2 stroke:#b8d9b8,stroke-width:2px\n linkStyle 3,4 stroke:#b8d4e3,stroke-width:2px\n```\n\n### 1. Adaptive Layout Engine\n`bv` doesn't just dump text; it calculates geometry on every render cycle.\n* **Dynamic Resizing:** The `View()` function inspects the current terminal width (`msg.Width`) on every frame.\n* **Breakpoint Logic:**\n * `\u003C 100 cols`: **Mobile Mode**. List takes 100% width.\n * `> 100 cols`: **Split Mode**. List takes 40%, Details take 60%.\n * `> 140 cols`: **Ultra-Wide**. List injects extra columns (Sparklines, Labels) that are normally hidden.\n* **Padding Awareness:** The layout engine explicitly accounts for borders (2 chars) and padding (2 chars) to prevent \"off-by-one\" wrapping errors that plague many TUIs.\n\n### 2. Zero-Latency Virtualization\nRendering 10,000 issues would choke a naive terminal app. `bv` implements **Viewport Virtualization**:\n* **Windowing:** We only render the slice of rows currently visible in the terminal window.\n* **Pre-Computation:** Graph metrics (PageRank, etc.) are computed *once* at startup in a separate goroutine, not on every frame. The underlying graph uses a compact adjacency-list implementation that's 50-100× faster than naive map-backed approaches.\n* **Detail Caching:** The Markdown renderer is instantiated lazily and reused, avoiding expensive regex recompilation.\n\n### 3. Visual Graph Engine (`pkg\u002Fui\u002Fgraph.go`)\nWe built a custom 2D ASCII\u002FUnicode rendering engine from scratch to visualize the dependency graph.\n* **Canvas Abstraction:** A 2D grid of `rune` cells and `style` pointers allows us to draw \"pixels\" in the terminal.\n* **Manhattan Routing:** Edges are drawn using orthogonal lines with proper Unicode corner characters ( `╭`, `─`, `╮`, `│`, `╰`, `╯`) to minimize visual noise.\n* **Topological Layering:** Nodes are arranged in layers based on their \"Impact Depth,\" ensuring that dependencies always flow downwards.\n\n### 4. Thematic Consistency\nWe use **[Lipgloss](https:\u002F\u002Fgithub.com\u002Fcharmbracelet\u002Flipgloss)** to enforce a strict design system.\n* **Semantic Colors:** Colors are defined semantically (`Theme.Blocked`, `Theme.Open`) rather than hardcoded hex values. This allows `bv` to switch between \"Dracula\" (Dark) and \"Light\" modes seamlessly.\n* **Status Indicators:** We use Nerd Font glyphs (`🐛`, `✨`, `🔥`) paired with color coding to convey status instantly without reading text.\n\n---\n\n## 📈 Visual Data Encoding: Sparklines & Heatmaps\n\nIn dense information environments like the terminal, text is expensive. `bv` employs high-density data visualization techniques (`pkg\u002Fui\u002Fvisuals.go`) inspired by Edward Tufte to convey complex metrics in minimal space.\n\n### 1. Unicode Sparklines\nWhen viewing the list in Ultra-Wide mode, `bv` renders a \"Graph Score\" column using Unicode block characters (` `, `▂`, `▃`, `▄`, `▅`, `▆`, `▇`, `█`).\n* **The Math:** `RenderSparkline(val, width)` normalizes a float value (0.0 - 1.0) against the available character width. It calculates the precise block height for each character cell to create a continuous bar chart effect.\n* **The Utility:** This allows you to scan a list of 50 issues and instantly spot the \"spikes\" in complexity or centrality without reading a single number.\n\n### 2. Semantic Heatmaps\nWe don't just use random colors. `pkg\u002Fui\u002Fvisuals.go` implements a perceptually uniform color ramp (`GetHeatmapColor`) that maps metric intensity to a gradient:\n* `0.0 - 0.2`: **Low** (Gray\u002FDim)\n* `0.2 - 0.5`: **Mid** (Blue\u002FCool)\n* `0.5 - 0.8`: **High** (Purple\u002FWarm)\n* `0.8 - 1.0`: **Peak** (Pink\u002FHot)\nThis visual encoding is applied to badges in the Insights Dashboard, allowing you to differentiate between \"somewhat important\" and \"critically urgent\" tasks at a glance.\n\n---\n\n## 🔍 Search Architecture\n\nIn a project with thousands of issues, you cannot afford to wait for a backend query. `bv` implements a **composite, in-memory fuzzy search** that feels instantaneous.\n\n### The \"Flattened Vector\" Index\nInstead of searching fields individually (which requires complex UI controls), `bv` flattens every issue into a single searchable \"vector\" at load time.\nThe `FilterValue()` method constructs a composite string containing:\n* **Core Identity:** ID (`\"CORE-123\"`) and Title (`\"Fix login race condition\"`)\n* **Metadata:** Status (`\"open\"`), Type (`\"bug\"`), Priority\n* **Context:** Assignee (`\"@steve\"`) and Labels (`\"frontend, v1.0\"`)\n\n### Fuzzy Subsequence Matching\nWhen you press `\u002F`, the search engine performs a **fuzzy subsequence match** against this composite vector.\n* **Example:** Typing `\"log fix\"` successfully matches `\"Fix login race condition\"`.\n* **Example:** Typing `\"steve bug\"` finds bugs assigned to Steve.\n* **Example:** Typing `\"open v1.0\"` filters for open items in the v1.0 release.\n\n### Performance Characteristics\n* **Zero Allocation:** The search index is built once during the initial load (`loader.LoadIssues`).\n* **Client-Side Filtering:** Filtering happens entirely within the render loop. There is no database latency, no network round-trip, and no \"loading\" spinner.\n* **Stable Sort:** Search results maintain the topological and priority sorting of the main list, ensuring that even filtered views reflect the project's true priorities.\n\n---\n\n## 🧜 Mermaid Integration: Diagrams in the Terminal?\n\nA common question is: *\"How do you render complex diagrams in a text-only terminal?\"*\n\n`bv` approaches this problem in two ways:\n\n### 1. The Native Graph Visualizer (`g`)\nFor the interactive TUI, we built a specialized **ASCII\u002FUnicode Graph Engine** (`pkg\u002Fui\u002Fgraph.go`) that replicates the core value of a Mermaid flowchart without requiring graphical protocol support (like Sixel).\n* **Topological Layering:** Nodes are automatically sorted by their dependency depth.\n* **Orthogonal Routing:** Connections use box-drawing characters (`│`, `─`, `╭`, `╯`) to draw clean, right-angled paths that avoid crossing through node text.\n* **Adaptive Canvas:** The virtual canvas expands infinitely, but the viewport (`pkg\u002Fui\u002Fviewport.go`) clips rendering to exactly what fits on your screen, panning smoothly with `h`\u002F`j`\u002F`k`\u002F`l`.\n\n### 2. The Export Engine (`--export-md`)\nFor external reporting, `bv` includes a robust **Mermaid Generator** (`pkg\u002Fexport\u002Fmarkdown.go`).\n* **Sanitization:** It automatically escapes unsafe characters in issue titles to prevent syntax errors in the Mermaid parser.\n* **Collision-Proof IDs:** When sanitization would collide (e.g., symbol-only IDs), nodes get a stable hash suffix so edges never merge or disappear.\n* **Class-Based Styling:** Nodes are assigned CSS classes (`classDef open`, `classDef blocked`) based on their status, so the resulting diagram visually matches the TUI's color scheme when rendered on GitHub or GitLab.\n* **Semantic Edges:** Blockers are rendered with thick arrows (`==>`), while loose relations use dashed lines (`-.->`), encoding the *severity* of the link into the visual syntax.\n\n```mermaid\ngraph TD\n %% Generated by bv — Soft Pastel Theme\n classDef open fill:#c8e6c9,stroke:#81c784,stroke-width:2px,color:#2e7d32\n classDef blocked fill:#ffcdd2,stroke:#e57373,stroke-width:2px,color:#c62828\n classDef inProgress fill:#fff3e0,stroke:#ffb74d,stroke-width:2px,color:#ef6c00\n\n A[\"CORE-123\u003Cbr\u002F>Refactor Login\"]:::open\n B[\"UI-456\u003Cbr\u002F>Login Page\"]:::blocked\n C[\"API-789\u003Cbr\u002F>Auth Endpoint\"]:::inProgress\n\n A --> B\n A --> C\n C -.-> B\n\n linkStyle 0 stroke:#81c784,stroke-width:2px\n linkStyle 1 stroke:#81c784,stroke-width:2px\n linkStyle 2 stroke:#e57373,stroke-width:1px,stroke-dasharray:5\n```\n\n---\n\n## 📸 Graph Export (`--robot-graph`)\n\nExport the dependency graph in multiple formats for visualization, documentation, or integration with other tools:\n\n```bash\nbv --robot-graph # JSON (default)\nbv --robot-graph --graph-format=dot # Graphviz DOT\nbv --robot-graph --graph-format=mermaid # Mermaid diagram\n\n# Focused subgraph extraction\nbv --robot-graph --graph-root=bv-123 # Subgraph from specific root\nbv --robot-graph --graph-root=bv-123 --graph-depth=3 # Limited depth\n```\n\n### Output Formats\n\n| Format | Use Case | Rendering |\n|--------|----------|-----------|\n| `json` | Programmatic processing, custom visualization | Parse with jq or code |\n| `dot` | High-quality static images | `dot -Tpng file.dot -o graph.png` |\n| `mermaid` | Embed in Markdown, GitHub rendering | Paste into docs |\n\n### Subgraph Extraction\n\nFor large projects, extract focused views around specific issues:\n\n- **`--graph-root=ID`**: Start from a specific issue and include all its dependencies and dependents\n- **`--graph-depth=N`**: Limit traversal to N levels (0 = unlimited)\n\n### JSON Schema\n\n```json\n{\n \"nodes\": [\n { \"id\": \"bv-123\", \"title\": \"Fix auth\", \"status\": \"open\", \"priority\": 1 }\n ],\n \"edges\": [\n { \"from\": \"bv-124\", \"to\": \"bv-123\", \"type\": \"blocks\" }\n ],\n \"metadata\": {\n \"data_hash\": \"abc123\",\n \"node_count\": 45,\n \"edge_count\": 62\n }\n}\n```\n\n---\n\n## 🌌 Interactive Graph Visualization (`--export-graph`)\n\nFor deep exploration of complex dependency structures, `bv` generates **self-contained HTML visualizations** powered by a force-directed graph engine. Unlike static exports, these are fully interactive—pan, zoom, filter, and drill into individual beads without any server or dependencies.\n\n```bash\n# Generate interactive HTML graph\nbv --export-graph graph.html # Export to specific file\nbv --export-graph # Auto-generate timestamped filename\nbv --export-graph --graph-title \"Q4 Sprint\" # Custom title\nbv --export-graph --graph-include-closed # Include closed issues\n```\n\n### Why Interactive Graph Visualization?\n\nTraditional list-based views show tasks in isolation. The interactive graph reveals the **hidden structure** of your project:\n\n- **Dependency Chains**: See at a glance which tasks are blocking others, and trace critical paths through your backlog\n- **Bottleneck Detection**: Nodes sized by PageRank\u002Fbetweenness instantly reveal which items have outsized impact\n- **Cluster Discovery**: Force-directed layout naturally groups related work, exposing team boundaries or feature clusters\n- **Context Switching**: Hover over any node to see full details—description, design notes, acceptance criteria—without leaving the visualization\n\n### What's Included in the Export\n\nEach HTML file is **completely self-contained** (typically 400KB-1MB depending on project size):\n\n| Component | Description |\n|-----------|-------------|\n| **Full Bead Data** | Title, description, design, acceptance criteria, notes, labels, timestamps |\n| **Graph Metrics** | PageRank, betweenness, critical path score, slack, hub\u002Fauthority scores |\n| **Triage Analysis** | Complete triage recommendations with scores and reasons |\n| **Git Correlation** | Commit history linked to each bead (when available) |\n| **Dependency Map** | Full blocked-by\u002Fblocks relationships with visual edges |\n\n### Interface Overview\n\nThe visualization provides a rich, keyboard-driven interface:\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ 📊 Project Graph | [Search...] | Layout ▾ | Filters ▾ | 🔥 📋 ⭐ ☀️ ❓ │\n├──────────────────────┬──────────────────────────────────────────────────────┤\n│ │ │\n│ Bead Details │ Force-Directed Graph │\n│ ═══════════════ │ │\n│ ID: bv-xyz │ ●───────● │\n│ Title: Feature X │ \u002F│\\ │ │\n│ │ ● ● ● ●───● │\n│ Description: │ │ │ │\n│ [markdown...] │ ●───────────● │\n│ │ │\n│ Graph Metrics: │ ┌──────────────────┐ │\n│ PageRank: 2.34% │ │ Low ▰▰▰▰ High │ \u003C- Heatmap Legend │\n│ Betweenness: 0.12 │ └──────────────────┘ │\n│ Critical Path: 4.0 │ ┌─────────────┐ │\n│ │ │ Mini-map │ │\n│ Blocked By: [...] │ └─────────────┘ │\n│ Blocks: [...] │ │\n└──────────────────────┴──────────────────────────────────────────────────────┘\n```\n\n### Visual Encoding\n\nNodes encode multiple dimensions of information simultaneously:\n\n| Visual Property | Meaning |\n|-----------------|---------|\n| **Color** | Status: 🟢 Open, 🟠 In Progress, 🔴 Blocked, ⚫ Closed |\n| **Size** | Configurable metric (PageRank, betweenness, critical path, in-degree) |\n| **Shape** | Type: ● Feature, ▲ Bug, ■ Task, ◆ Epic |\n| **Glow** | Golden halo on hover shows connected subgraph (2-hop neighbors) |\n| **Edge Color** | Pink edges indicate critical path connections |\n\n### Keyboard Shortcuts\n\nThe visualization is fully keyboard-driven:\n\n| Key | Action | Key | Action |\n|-----|--------|-----|--------|\n| `?` | Help overlay | `D` | Dock\u002Fdetach detail panel |\n| `F` | Fit all in view | `L` | Toggle light\u002Fdark mode |\n| `R` | Reset to defaults | `H` | Toggle heatmap coloring |\n| `Space` | Fullscreen | `T` | Top nodes panel |\n| `Esc` | Clear\u002Fcancel | `G` | Triage panel |\n| `1-4` | Layout modes | `Y` | Recently viewed |\n| `P` | Path finder mode | | |\n\n### Features\n\n**Filtering & Search**\n- **Full-text search**: Find beads by ID, title, or content with live preview\n- **Status filter**: Open, In Progress, Blocked, Closed\n- **Type filter**: Feature, Bug, Task, Epic\n- **Priority filter**: P0 (Critical) through P4 (Backlog)\n- **Label filter**: Dynamically populated from your data\n\n**Navigation**\n- **Path Finder**: Press `P`, then click two nodes to find and highlight the shortest path between them\n- **Recently Viewed**: Press `Y` to see your navigation history and jump back to previous nodes\n- **Mini-map**: Overview in the corner shows your current viewport position\n\n**Panels**\n- **Docked Detail Panel**: Left sidebar shows full bead information on hover (default)\n- **Floating Mode**: Press `D` to detach the panel for floating tooltip-style display\n- **Triage Panel**: Shows top recommendations with scores and reasoning\n- **Top Nodes**: Lists highest PageRank nodes for quick navigation\n\n**Customization**\n- **Layout Modes**: Force-directed (default), DAG top-down, DAG left-right, Radial\n- **Size Metric**: Choose what determines node size (PageRank, betweenness, critical path, in-degree)\n- **Light\u002FDark Mode**: Full theme support with proper contrast\n- **Preferences Saved**: Theme and layout choices persist via localStorage\n\n### Use Cases\n\n| Scenario | How the Graph Helps |\n|----------|---------------------|\n| **Sprint Planning** | Identify which items unblock the most downstream work |\n| **Stakeholder Updates** | Share a single HTML file—no setup required to view |\n| **Architecture Review** | Spot unexpected dependencies between features |\n| **Onboarding** | New team members can explore the codebase's work structure |\n| **Retrospectives** | Visualize completed work and remaining blockers |\n\n### Example Workflow\n\n```bash\n# 1. Generate the visualization\nbv --export-graph sprint_review.html --graph-title \"Sprint 42 Review\"\n\n# 2. Open in browser\nopen sprint_review.html # macOS\nxdg-open sprint_review.html # Linux\nstart sprint_review.html # Windows\n\n# 3. Share with team\n# The HTML file is self-contained—just send it or host anywhere\n```\n\n### Technical Notes\n\n- **No Server Required**: Everything runs client-side in the browser\n- **Offline Capable**: Works completely offline once opened\n- **Modern Browsers**: Tested on Chrome, Firefox, Safari, Edge\n- **Performance**: Handles 500+ nodes smoothly with WebGL-accelerated rendering\n- **File Size**: Typically 400KB-1MB depending on project size and content\n\n---\n\n## 📄 The Status Report Engine\n\n`bv` isn't just for personal browsing; it's a communication tool. The `--export-md` flag generates a **Management-Ready Status Report** that converts your repo state into a polished document suitable for stakeholders.\n\n### 1. The \"Hybrid Document\" Architecture\nThe exporter (`pkg\u002Fexport\u002Fmarkdown.go`) constructs a document that bridges human readability and visual data:\n* **Summary at a Glance:** Top-level statistics (Total, Open, Blocked, Closed) give immediate health context.\n* **Embedded Graph:** It injects the full dependency graph as a Mermaid diagram *right into the document*. On platforms like GitHub or GitLab, this renders as an interactive chart.\n* **Anchor Navigation:** A generated Table of Contents uses URL-friendly slugs (`#core-123-refactor-login`) to link directly to specific issue details, allowing readers to jump between the high-level graph and low-level specs.\n\n### 2. Semantic Formatting\nWe don't just dump JSON values. The exporter applies specific formatting rules to ensure the report looks professional:\n* **Metadata Tables:** Key fields (Assignee, Priority, Status) are aligned in GFM (GitHub Flavored Markdown) tables with emoji indicators.\n* **Conversation threading:** Comments are rendered as blockquotes (`>`) with relative timestamps, preserving the flow of discussion distinct from the technical spec.\n* **Intelligent Sorting:** The report doesn't list issues ID-sequentially. It applies the same priority logic as the TUI: **Open Critical** issues appear first, ensuring the reader focuses on what matters now.\n\n---\n\n## ⏳ Time-Travel: Snapshot Diffing & Git History\n\nOne of `bv`'s most powerful capabilities is **Time-Travel**—the ability to compare your project's state across any two points in git history. This transforms `bv` from a \"viewer\" into a **progress tracking and regression detection system**.\n\n### The Snapshot Model\n`bv` captures the complete state of your project at any moment:\n\n```mermaid\ngraph LR\n %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8f5e9', 'primaryTextColor': '#2e7d32', 'primaryBorderColor': '#81c784', 'lineColor': '#90a4ae'}}}%%\n\n subgraph \"Git History\"\n A[\"HEAD~10\u003Cbr\u002F>\u003Csmall>10 commits ago\u003C\u002Fsmall>\"]\n B[\"HEAD~5\u003Cbr\u002F>\u003Csmall>5 commits ago\u003C\u002Fsmall>\"]\n C[\"HEAD\u003Cbr\u002F>\u003Csmall>Current\u003C\u002Fsmall>\"]\n end\n\n subgraph \"Snapshots\"\n D[\"Snapshot A\u003Cbr\u002F>\u003Csmall>45 issues, 3 cycles\u003C\u002Fsmall>\"]\n E[\"Snapshot B\u003Cbr\u002F>\u003Csmall>52 issues, 1 cycle\u003C\u002Fsmall>\"]\n F[\"Snapshot C\u003Cbr\u002F>\u003Csmall>58 issues, 0 cycles\u003C\u002Fsmall>\"]\n end\n\n A --> D\n B --> E\n C --> F\n D -.->|\"diff\"| E\n E -.->|\"diff\"| F\n\n style D fill:#ffcdd2,stroke:#e57373,stroke-width:2px\n style E fill:#fff3e0,stroke:#ffb74d,stroke-width:2px\n style F fill:#c8e6c9,stroke:#81c784,stroke-width:2px\n```\n\n### What Gets Tracked\nThe `SnapshotDiff` captures every meaningful change:\n\n| Category | Tracked Changes |\n|----------|-----------------|\n| **Issues** | New, Closed, Reopened, Removed, Modified |\n| **Fields** | Title, Status, Priority, Tags, Dependencies |\n| **Graph** | New Cycles, Resolved Cycles |\n| **Metrics** | Δ PageRank, Δ Betweenness, Δ Density |\n\n### Git History Integration (`pkg\u002Floader\u002Fgit.go`)\nThe `GitLoader` enables loading issues from **any git revision**:\n\n```go\nloader := NewGitLoader(\"\u002Fpath\u002Fto\u002Frepo\")\n\n\u002F\u002F Load from various references\ncurrent, _ := loader.LoadAt(\"HEAD\")\nlastWeek, _ := loader.LoadAt(\"HEAD~7\")\nrelease, _ := loader.LoadAt(\"v1.0.0\")\nbyDate, _ := loader.LoadAt(\"main@{2024-01-15}\")\n```\n\n**Cache Architecture:**\n- Revisions are resolved to commit SHAs for stable caching\n- Thread-safe `sync.RWMutex` protects concurrent access\n- 5-minute TTL prevents stale data while avoiding redundant git calls\n\n### Use Cases\n1. **Sprint Retrospectives:** \"How many issues did we close this sprint?\"\n2. **Regression Detection:** \"Did we accidentally reintroduce a dependency cycle?\"\n3. **Trend Analysis:** \"Is our graph density increasing? Are we creating too many dependencies?\"\n4. **Release Notes:** \"Generate a diff of all changes between v1.0 and v2.0\"\n\n---\n\n## 🍳 Recipe System: Declarative View Configuration\n\nInstead of memorizing CLI flags or repeatedly setting filters, `bv` supports **Recipes**—YAML-based view configurations that can be saved, shared, and version-controlled.\n\n### Recipe Structure\n```yaml\n# .beads\u002Frecipes\u002Fsprint-review.yaml\nname: sprint-review\ndescription: \"Issues touched in the current sprint\"\n\nfilters:\n status: [open, in_progress, closed]\n updated_after: \"14d\" # Relative time: 14 days ago\n exclude_tags: [backlog, icebox]\n\nsort:\n field: updated\n direction: desc\n secondary:\n field: priority\n direction: asc\n\nview:\n columns: [id, title, status, priority, updated]\n show_metrics: true\n max_items: 50\n\nexport:\n format: markdown\n include_graph: true\n```\n\n### Filter Capabilities\n\n| Filter | Type | Examples |\n|--------|------|----------|\n| `status` | Array | `[open, closed, blocked, in_progress]` |\n| `priority` | Array | `[0, 1]` (P0 and P1 only) |\n| `tags` | Array | `[frontend, urgent]` |\n| `exclude_tags` | Array | `[wontfix, duplicate]` |\n| `created_after` | Relative\u002FISO | `\"7d\"`, `\"2w\"`, `\"2024-01-01\"` |\n| `updated_before` | Relative\u002FISO | `\"30d\"`, `\"1m\"` |\n| `actionable` | Boolean | `true` = no open blockers |\n| `has_blockers` | Boolean | `true` = waiting on dependencies |\n| `id_prefix` | String | `\"bv-\"` for project filtering |\n| `title_contains` | String | Substring search |\n\n### Built-in Recipes\n`bv` ships with 11 pre-configured recipes:\n\n| Recipe | Purpose |\n|--------|---------|\n| `default` | All open issues sorted by priority |\n| `actionable` | Ready to work (no blockers) |\n| `recent` | Updated in last 7 days |\n| `blocked` | Waiting on dependencies |\n| `high-impact` | Top PageRank scores |\n| `stale` | Open but untouched for 30+ days |\n| `triage` | Sorted by computed triage score (impact + unblocking potential) |\n| `closed` | Recently closed issues |\n| `release-cut` | Closed in last 14 days (for changelog generation) |\n| `quick-wins` | Easy P2\u002FP3 items with no blockers |\n| `bottlenecks` | High betweenness nodes (project bottlenecks) |\n\n### Using Recipes\n```bash\n# Interactive picker (press 'R' in TUI)\nbv\n\n# Direct recipe invocation\nbv --recipe actionable\nbv --recipe high-impact\n\n# Custom recipe file\nbv --recipe .beads\u002Frecipes\u002Fsprint-review.yaml\n```\n\n---\n\n## 🎯 Composite Impact Scoring\n\nTraditional issue trackers sort by a single dimension—usually priority. `bv` computes a **multi-factor Impact Score** that blends graph-theoretic metrics with temporal and priority signals.\n\n### The Scoring Formula\n$$\n\\text{Impact} = 0.30 \\cdot \\text{PageRank} + 0.30 \\cdot \\text{Betweenness} + 0.20 \\cdot \\text{BlockerRatio} + 0.10 \\cdot \\text{Staleness} + 0.10 \\cdot \\text{PriorityBoost}\n$$\n\n### Component Breakdown\n\n| Component | Weight | What It Measures |\n|-----------|--------|------------------|\n| **PageRank** | 30% | Recursive dependency importance |\n| **Betweenness** | 30% | Bottleneck\u002Fbridge position |\n| **BlockerRatio** | 20% | Direct dependents (In-Degree) |\n| **Staleness** | 10% | Days since last update (aging) |\n| **PriorityBoost** | 10% | Human-assigned priority |\n\n### Why These Weights?\n- **60% Graph Metrics:** The structure of dependencies is the primary driver of true importance.\n- **20% Blocker Ratio:** Direct dependents matter for immediate unblocking.\n- **10% Staleness:** Old issues deserve attention; they may be forgotten blockers.\n- **10% Priority:** Human judgment is valuable but can be outdated or politically biased.\n\n### Score Output\n```json\n{\n \"issue_id\": \"CORE-123\",\n \"title\": \"Refactor auth module\",\n \"score\": 0.847,\n \"breakdown\": {\n \"pagerank\": 0.27,\n \"betweenness\": 0.25,\n \"blocker_ratio\": 0.18,\n \"staleness\": 0.07,\n \"priority_boost\": 0.08\n }\n}\n```\n\n### Priority Recommendations\n`bv` generates **actionable recommendations** when the computed impact score diverges significantly from the human-assigned priority:\n\n> ⚠️ **CORE-123** has Impact Score 0.85 but Priority P3.\n> *Reason: High PageRank (foundational dependency) + High Betweenness (bottleneck)*\n> **Recommendation:** Consider escalating to P1.\n\n### Priority Hints Overlay\n\nPress `p` in the list view to toggle **Priority Hints**—inline visual indicators showing which issues have misaligned priorities:\n\n```\n┌──────────────────────────────────────────────────────────────┐\n│ OPEN CORE-123 ⬆ Database schema migration P3 🟢 │\n│ OPEN UI-456 Login page styling P2 🟢 │\n│ BLOCKED API-789 ⬇ Legacy endpoint wrapper P1 🔴 │\n└──────────────────────────────────────────────────────────────┘\n ⬆ = Impact suggests higher priority (red arrow)\n ⬇ = Impact suggests lower priority (teal arrow)\n```\n\nThis provides at-a-glance feedback on whether your priority assignments match the computed graph importance.\n\n---\n\n## 🛤️ Parallel Execution Planning\n\nWhen you ask \"What should I work on next?\", `bv` doesn't just pick the highest-priority item. It generates a **complete execution plan** that respects dependencies and identifies opportunities for parallel work.\n\n### Track-Based Planning\nThe planner uses **Union-Find** to identify connected components in the dependency graph, grouping related issues into independent \"tracks\" that can be worked on concurrently.\n\n```mermaid\ngraph TD\n %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8f5e9', 'lineColor': '#90a4ae'}}}%%\n\n subgraph track_a [\"🅰️ Track A: Auth System\"]\n A1[\"AUTH-001\u003Cbr\u002F>P1 · Unblocks 3\"]:::actionable\n A2[\"AUTH-002\"]:::blocked\n A3[\"AUTH-003\"]:::blocked\n end\n\n subgraph track_b [\"🅱️ Track B: UI Polish\"]\n B1[\"UI-101\u003Cbr\u002F>P2 · Unblocks 1\"]:::actionable\n B2[\"UI-102\"]:::blocked\n end\n\n subgraph track_c [\"🅲 Track C: Independent\"]\n C1[\"DOCS-001\u003Cbr\u002F>P3 · Unblocks 0\"]:::actionable\n end\n\n A1 --> A2\n A2 --> A3\n B1 --> B2\n\n classDef actionable fill:#c8e6c9,stroke:#81c784,stroke-width:2px,color:#2e7d32\n classDef blocked fill:#ffcdd2,stroke:#e57373,stroke-width:2px,color:#c62828\n\n linkStyle 0,1,2 stroke:#81c784,stroke-width:2px\n```\n\n### Plan Output (`--robot-plan`)\n```json\n{\n \"tracks\": [\n {\n \"track_id\": \"track-A\",\n \"reason\": \"Independent work stream\",\n \"items\": [\n { \"id\": \"AUTH-001\", \"priority\": 1, \"unblocks\": [\"AUTH-002\", \"AUTH-003\", \"API-005\"] }\n ]\n },\n {\n \"track_id\": \"track-B\",\n \"reason\": \"Independent work stream\",\n \"items\": [\n { \"id\": \"UI-101\", \"priority\": 2, \"unblocks\": [\"UI-102\"] }\n ]\n }\n ],\n \"total_actionable\": 3,\n \"total_blocked\": 5,\n \"summary\": {\n \"highest_impact\": \"AUTH-001\",\n \"impact_reason\": \"Unblocks 3 tasks\",\n \"unblocks_count\": 3\n }\n}\n```\n\n### The Algorithm\n1. **Identify Actionable Issues:** Filter to non-closed issues with no open blockers.\n2. **Compute Unblocks:** For each actionable issue, calculate what becomes unblocked if it's completed.\n3. **Find Connected Components:** Use Union-Find to group issues by their dependency relationships.\n4. **Build Tracks:** Create parallel tracks from each component, sorted by priority within each track.\n5. **Compute Summary:** Identify the single highest-impact issue (most downstream unblocks).\n\n### Benefits for AI Agents\n- **Deterministic:** Same input always produces same plan (no LLM hallucination).\n- **Parallelism-Aware:** Multiple agents can grab different tracks without conflicts.\n- **Impact-Ranked:** The `highest_impact` field tells agents exactly where to start.\n\n---\n\n## 🔬 Insights Dashboard: Interactive Graph Analysis\n\nThe Insights Dashboard (`i`) transforms abstract graph metrics into an **interactive exploration interface**. Instead of just showing numbers, it lets you drill into *why* a bead scores high and *what* that means for your project.\n\n### The 6-Panel Layout\n\n```\n┌─────────────────────┬─────────────────────┬─────────────────────┐\n│ 🚧 Bottlenecks │ 🏛️ Keystones │ 🌐 Influencers │\n│ Betweenness │ Impact Depth │ Eigenvector │\n│ ───────────────── │ ───────────────── │ ───────────────── │\n│ ▸ 0.45 AUTH-001 │ 12.0 CORE-123 │ 0.82 API-007 │\n│ 0.38 API-005 │ 10.0 DB-001 │ 0.71 AUTH-001 │\n└─────────────────────┴─────────────────────┴─────────────────────┘\n┌─────────────────────┬─────────────────────┬─────────────────────┐\n│ 🛰️ Hubs │ 📚 Authorities │ 🔄 Cycles │\n│ HITS Hub Score │ HITS Auth Score │ Circular Deps │\n│ ───────────────── │ ───────────────── │ ───────────────── │\n│ 0.67 EPIC-100 │ 0.91 UTIL-050 │ ⚠ A → B → C → A │\n│ 0.54 FEAT-200 │ 0.78 LIB-010 │ ⚠ X → Y → X │\n└─────────────────────┴─────────────────────┴─────────────────────┘\n```\n\n### Panel Descriptions\n\n| Panel | Metric | What It Shows | Actionable Insight |\n|-------|--------|---------------|-------------------|\n| **🚧 Bottlenecks** | Betweenness | Beads on many shortest paths | Prioritize to unblock parallel work |\n| **🏛️ Keystones** | Impact Depth | Deep in dependency chains | Complete first—delays cascade |\n| **🌐 Influencers** | Eigenvector | Connected to important beads | Review carefully before changes |\n| **🛰️ Hubs** | HITS Hub | Aggregate many dependencies | Track for milestone completion |\n| **📚 Authorities** | HITS Authority | Depended on by many hubs | Stabilize early—breaking ripples |\n| **🔄 Cycles** | Tarjan SCC | Circular dependency loops | Must resolve—logical impossibility |\n\n### The Detail Panel: Calculation Proofs\n\nWhen you select a bead, the right-side **Detail Panel** shows not just the score, but the *proof*—the actual beads and values that contributed:\n\n```\n─── CALCULATION PROOF ───\nBW(v) = Σ (σst(v) \u002F σst) for all s≠v≠t\n\nBetweenness Score: 0.452\n\nBeads depending on this (5):\n ↓ UI-Login: Implement login form\n ↓ UI-Dashboard: User dashboard\n ↓ API-Auth: Authentication endpoint\n ... +2 more\n\nThis depends on (2):\n ↑ DB-Schema: User table migration\n ↑ CORE-Config: Environment setup\n\nThis bead lies on many shortest paths between\nother beads, making it a critical junction.\n```\n\n### Dashboard Navigation\n\n| Key | Action |\n|-----|--------|\n| `Tab` \u002F `Shift+Tab` | Move between panels |\n| `j` \u002F `k` | Navigate within panel |\n| `Enter` | Focus selected bead in main view |\n| `e` | Toggle explanations |\n| `i` | Exit dashboard |\n\n---\n\n## 📋 Kanban Board: Visual Workflow State\n\nThe Kanban Board (`b`) provides a **columnar workflow view** with intelligent swimlane grouping, visual dependency indicators, and rich card details. Empty columns automatically collapse to maximize screen real estate.\n\n### Swimlane Grouping Modes\n\nPress `s` to cycle through three grouping modes:\n\n| Mode | Columns | Use Case |\n|------|---------|----------|\n| **Status** (default) | Open \\| In Progress \\| Blocked \\| Closed | Workflow state tracking |\n| **Priority** | P0 Critical \\| P1 High \\| P2 Medium \\| P3+ Other | Urgency-based triage |\n| **Type** | Bug \\| Feature \\| Task \\| Epic | Work categorization |\n\nThe current mode is shown in the status bar. Each mode uses distinct column colors for quick visual identification.\n\n### Visual Dependency Indicators\n\nCard borders are **color-coded** to show dependency status at a glance:\n\n```\n┌─ 🔴 RED ──────────────────┐ ┌─ 🟡 YELLOW ─────────────────┐\n│ BLOCKED │ │ HIGH-IMPACT │\n│ This card has unresolved │ │ This card blocks others. │\n│ dependencies. Work on │ │ Completing it will unblock │\n│ blockers first. │ │ downstream work. │\n└────────────────────────────┘ └──────────────────────────────┘\n\n┌─ 🟢 GREEN ────────────────┐ ┌─ ⬜ DEFAULT ─────────────────┐\n│ READY TO WORK │ │ NORMAL │\n│ Open issue with no │ │ Standard priority, no │\n│ blockers. Pick this up! │ │ blocking relationships. │\n└────────────────────────────┘ └──────────────────────────────┘\n```\n\nSearch matches overlay with **purple** (current match) or **blue** (other matches) borders.\n\n### Rich 4-Line Card Format\n\nEach card displays comprehensive metadata in a compact format:\n\n```\n┌────────────────────────────────────┐\n│ 🐛 P1 BUG-1234 3d │ ← Line 1: Type, Priority, ID, Age\n│ Fix authentication timeout │ ← Line 2: Title (truncated)\n│ 👤alice ⛔3 →2 🏷️2 │ ← Line 3: Assignee, Blockers, Blocks, Labels\n│ auth, backend, critical │ ← Line 4: Label names\n└────────────────────────────────────┘\n```\n\n| Element | Meaning |\n|---------|---------|\n| **Type Icon** | 🐛 Bug, ✨ Feature, 📝 Task, 🎯 Epic, 🔧 Chore |\n| **Priority** | P0 (red), P1 (red), P2 (muted), P3+ (gray) |\n| **Age Color** | 🟢 \u003C7d (fresh), 🟡 7-30d (aging), 🔴 >30d (stale) |\n| **⛔N** | Blocked by N issues |\n| **→N** | Blocks N downstream issues |\n| **🏷️N** | Has N labels |\n\n### Column Statistics\n\nEach column header shows aggregate statistics:\n\n```\n┌─────────────────────────────────────┐\n│ IN PROGRESS (5) 🔥2 ⚠️1 │\n└─────────────────────────────────────┘\n │ │ │\n │ │ └── ⚠️ Blocked items in this column\n │ └────── 🔥 P0\u002FP1 critical items\n └───────────────── Total count\n```\n\n### Inline Card Expansion\n\nPress `d` to expand the selected card inline, showing:\n- Full issue description\n- All blocking dependencies (with titles)\n- All downstream dependents\n- Complete label list\n- Comments preview\n\nNavigation (`j`\u002F`k`) auto-collapses expanded cards for smooth browsing.\n\n### Detail Panel\n\nPress `Tab` to open a **side panel** with the full issue detail view (on wide terminals). Scroll with `Ctrl+J`\u002F`Ctrl+K`.\n\n### Board Navigation\n\n| Key | Action |\n|-----|--------|\n| **Movement** | |\n| `h` \u002F `l` | Move between columns |\n| `j` \u002F `k` | Move within column |\n| `gg` \u002F `G` | Jump to top\u002Fbottom of column |\n| `0` \u002F `$` | First\u002Flast item in column |\n| `H` \u002F `L` | Jump to first\u002Flast column |\n| `1-4` | Jump directly to column 1-4 |\n| `Ctrl+D` \u002F `Ctrl+U` | Page down\u002Fup |\n| **Grouping & Display** | |\n| `s` | Cycle swimlane mode (Status → Priority → Type) |\n| `e` | Toggle empty column visibility |\n| `d` | Expand\u002Fcollapse inline card detail |\n| `Tab` | Toggle side detail panel |\n| **Search** | |\n| `\u002F` | Start search |\n| `n` \u002F `N` | Next\u002Fprevious search match |\n| `Esc` | Cancel search |\n| **Filtering** | |\n| `o` | Filter: Open only |\n| `c` | Filter: Closed only |\n| `r` | Filter: Ready (no blockers) |\n| **Actions** | |\n| `y` | Copy issue ID to clipboard |\n| `V` | Preview related cass sessions (if cass installed) |\n| `Enter` | Focus selected bead in detail view |\n| `b` | Exit board view |\n\n---\n\n## 🔄 List Sorting: Multi-Dimensional Organization\n\nPress `s` to cycle through **five distinct sort modes**, giving you instant control over how issues are organized. The current sort mode is displayed in the status bar.\n\n### Sort Modes\n\n| Mode | Key Display | Ordering Logic | Use Case |\n|------|-------------|----------------|----------|\n| **Default** | `Default` | Priority (asc) → Created (desc) | Standard priority-driven workflow |\n| **Created ↑** | `Created ↑` | Creation date ascending (oldest first) | Audit: find long-standing issues |\n| **Created ↓** | `Created ↓` | Creation date descending (newest first) | Review: see recently created work |\n| **Priority** | `Priority` | Priority only (P0 → P4) | Pure priority triage |\n| **Updated** | `Updated` | Last update descending (newest first) | Activity tracking: see active issues |\n\n### Design Philosophy\n\nThe sort system uses a **stable secondary sort** to ensure deterministic ordering. When primary sort values are equal, issues fall back to ID ordering for consistency across sessions. This prevents the \"shuffling list\" problem where equal-priority items randomly reorder.\n\n### Status Bar Indicator\n\n```\n┌────────────────────────────────────────────────────────────┐\n│ 📋 ISSUES [Created ↓] │\n├────────────────────────────────────────────────────────────┤\n│ OPEN FEAT-789 Add dark mode toggle P2 🟢 │\n│ OPEN BUG-456 Fix login race condition P1 🟢 │\n│ OPEN TASK-123 Update documentation P3 🟢 │\n└────────────────────────────────────────────────────────────┘\n```\n\nThe `[Created ↓]` badge instantly communicates the active sort mode without requiring you to remember which mode you're in.\n\n---\n\n## 🌲 Hierarchical Tree View: Parent-Child Visualization\n\nPress `E` to open the **Hierarchical Tree View**—a collapsible tree that visualizes parent-child relationships between issues. Unlike the Graph View which shows all dependency types, the Tree View focuses exclusively on **structural hierarchy**: which issues are \"part of\" other issues.\n\n### Why Parent-Child Matters\n\nIn complex projects, issues often have two distinct relationship types:\n- **Blocking dependencies** (`blocks`\u002F`blocked_by`): Task B cannot start until Task A completes\n- **Parent-child relationships** (`parent`): Feature X contains Tasks A, B, and C as sub-work\n\nThe Tree View renders only parent-child relationships, creating a work breakdown structure (WBS) that answers questions like:\n- \"What sub-tasks make up this epic?\"\n- \"Which feature does this bug belong to?\"\n- \"How is work decomposed across the project?\"\n\n### Tree Layout\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ 🌲 TREE VIEW 3 roots · 12 nodes │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ ▾ 🎯 P1 EPIC-100 Auth System Overhaul ● open │\n│ │ ├─ ▸ ✨ P1 FEAT-101 Implement OAuth2 flow ● open │\n│ │ │ └─ • 📝 P2 TASK-102 Add token refresh logic ○ closed │\n│ │ └─ • 🐛 P0 BUG-103 Fix session timeout race ⚠ blocked │\n│ │ │\n│ ▾ 🎯 P2 EPIC-200 UI Polish Sprint ● open │\n│ │ ├─ • ✨ P2 FEAT-201 Dark mode support ● open │\n│ │ └─ • ✨ P3 FEAT-202 Responsive layout ● open │\n│ │ │\n│ • 📝 P3 TASK-300 Update documentation ● open │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n### Visual Encoding\n\n| Element | Meaning |\n|---------|---------|\n| **▾ \u002F ▸** | Expanded \u002F Collapsed (has children) |\n| **•** | Leaf node (no children) |\n| **├─ \u002F └─** | Tree branch connectors |\n| **Type Icon** | 🎯 Epic, ✨ Feature, 🐛 Bug, 📝 Task, 🔧 Chore |\n| **Priority** | P0 (critical red), P1 (high), P2 (medium gray), P3+ (muted) |\n| **Status Dot** | ● Open (green), ◐ In Progress (yellow), ⚠ Blocked (red), ○ Closed (gray) |\n\n### Tree Building Algorithm\n\nThe tree construction uses a **parent-child only** filter with intelligent root detection:\n\n1. **Filter Dependencies**: Only `DepParentChild` type dependencies are considered; blocking and related dependencies are ignored\n2. **Build Index**: Create a parent → children mapping for efficient traversal\n3. **Identify Roots**: Issues with no parent (or whose parent doesn't exist in the dataset) become root nodes\n4. **Recursive Build**: Depth-first traversal with cycle detection prevents infinite loops\n5. **Sort Children**: Within each parent, children are sorted by: Priority (ascending) → Type (epic > feature > bug > task) → Creation Date (newest first)\n\n**Handling Edge Cases:**\n- **Orphan References**: If an issue references a parent that doesn't exist, it becomes a root node (not silently dropped)\n- **Cycles**: Detected during traversal; cyclic nodes are rendered without recursing further\n- **Deep Hierarchies**: No depth limit—the tree faithfully represents arbitrarily nested structures\n\n### Tree Navigation\n\n| Key | Action |\n|-----|--------|\n| **Movement** | |\n| `j` \u002F `k` \u002F `↓` \u002F `↑` | Move cursor down \u002F up |\n| `g` \u002F `G` | Jump to first \u002F last node |\n| `Ctrl+D` \u002F `Ctrl+U` | Page down \u002F up (half viewport) |\n| **Expand\u002FCollapse** | |\n| `Enter` \u002F `Space` | Toggle expand\u002Fcollapse on current node |\n| `l` \u002F `→` | Expand node, or move to first child if already expanded |\n| `h` \u002F `←` | Collapse node, or jump to parent if already collapsed |\n| `o` | Expand all nodes in the tree |\n| `O` | Collapse all nodes in the tree |\n| **Integration** | |\n| `Tab` | Sync selection to detail panel (in split view) |\n| `E` \u002F `Esc` | Exit tree view, return to list |\n\n### Use Cases\n\n| Scenario | How Tree View Helps |\n|----------|---------------------|\n| **Sprint Planning** | Expand epics to see all sub-work and estimate scope |\n| **Progress Tracking** | Collapse completed branches, focus on open work |\n| **Onboarding** | New team members understand project structure at a glance |\n| **Refactoring** | See which tasks fall under a feature before restructuring |\n| **Status Meetings** | Walk through the hierarchy top-down for stakeholder updates |\n\n### Tree vs. Graph View\n\n| Aspect | Tree View (`E`) | Graph View (`g`) |\n|--------|-----------------|------------------|\n| **Relationships** | Parent-child only | All dependency types |\n| **Layout** | Indented hierarchy | Force-directed \u002F DAG |\n| **Focus** | Work breakdown structure | Dependency flow |\n| **Navigation** | Vim-style (j\u002Fk\u002Fh\u002Fl) | Viewport panning |\n| **Best For** | \"What's inside this epic?\" | \"What blocks this task?\" |\n\nBoth views complement each other: use Tree View to understand structure, Graph View to understand flow.\n\n---\n\n## 🎯 Actionable Plan View: Parallel Execution Tracks\n\nPress `a` to open the **Actionable Plan View**—a structured display of work items grouped into independent execution tracks. This view transforms abstract graph analysis into a concrete \"what to work on next\" interface.\n\n### Why Tracks Matter\n\nTraditional priority lists show tasks in a single ordered queue. But in complex dependency graphs, some work streams are completely independent—working on one doesn't affect another. The Actionable Plan View identifies these **parallel tracks** using Union-Find connected component analysis, letting multiple agents or team members work concurrently without stepping on each other.\n\n### Visual Layout\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ 🎯 ACTIONABLE PLAN 3 tracks · 8 items │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ ━━━ Track A: Auth System ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │\n│ │\n│ ▸ 🎯 P1 AUTH-001 Implement OAuth2 flow unblocks 3 │\n│ ✨ P2 AUTH-002 Add token refresh unblocks 1 │\n│ │\n│ ━━━ Track B: UI Polish ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │\n│ │\n│ 📝 P2 UI-101 Dark mode toggle unblocks 2 │\n│ 📝 P3 UI-102 Responsive layout unblocks 0 │\n│ │\n│ ━━━ Track C: Independent ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │\n│ │\n│ 📝 P3 DOCS-001 Update API documentation unblocks 0 │\n│ │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ Highest Impact: AUTH-001 (unblocks 3) │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n### What Makes an Item \"Actionable\"\n\nAn issue appears in the Actionable Plan when:\n1. **Status is open or in_progress** (not closed)\n2. **No open blockers** exist (all blocking dependencies are closed)\n\nThis ensures every item in the view can be started immediately without waiting on anything else.\n\n### Unblock Analysis\n\nEach item shows an **unblocks count**—the number of other issues that would become actionable if this item were completed. High unblock counts indicate **force multipliers**: completing them unlocks a cascade of downstream work.\n\nThe **Highest Impact** summary at the bottom identifies the single item that, when completed, unblocks the most additional work. This is your optimal \"next thing to pick up.\"\n\n### Navigation\n\n| Key | Action |\n|-----|--------|\n| `j` \u002F `k` | Move between items (across tracks) |\n| `Enter` | Focus selected item in detail view |\n| `a` \u002F `Esc` | Exit actionable view |\n\n### Use Cases\n\n| Scenario | How Actionable View Helps |\n|----------|---------------------------|\n| **Solo Development** | Always know the highest-impact next task |\n| **Team Standup** | Each person claims a different track |\n| **AI Agent Dispatch** | Agents grab `highest_impact` deterministically |\n| **Sprint Planning** | Estimate work by counting actionable items per track |\n\n---\n\n## 🔀 Flow Matrix View: Cross-Label Dependency Analysis\n\nPress `f` to open the **Flow Matrix View**—an interactive dashboard visualizing how labels (domains\u002Fteams) depend on each other. This reveals cross-team bottlenecks that aren't visible in single-issue views.\n\n### Why Cross-Label Flow Matters\n\nIn large projects, work is often organized by labels: `frontend`, `backend`, `api`, `auth`, `infra`. Dependencies between issues create implicit dependencies between *labels*. The Flow Matrix exposes these patterns:\n\n- **Which team is blocking others the most?**\n- **Which domain is waiting on the most external work?**\n- **Where are the cross-team coordination bottlenecks?**\n\n### Visual Layout\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ 🔀 FLOW MATRIX 5 labels · 23 deps │\n├───────────────────────────────────────────┬─────────────────────────────────┤\n│ LABELS │ DETAIL │\n│ ───────────────────────────────────── │ ───────────────────────────── │\n│ │ │\n│ ▸ 🔴 api ━━━━━━━━━━ 0.72 │ Label: api │\n│ outgoing: 8 → [auth, db, infra] │ ────────────────────── │\n│ incoming: 3 ← [frontend, mobile] │ │\n│ │ Bottleneck Score: 0.72 │\n│ 🟡 auth ━━━━━━━━ 0.58 │ (top 20% = critical) │\n│ outgoing: 4 → [db] │ │\n│ incoming: 5 ← [api, frontend] │ Outgoing Dependencies: │\n│ │ → auth (3 issues) │\n│ 🟢 frontend ━━━━━ 0.31 │ → db (4 issues) │\n│ outgoing: 2 → [api] │ → infra (1 issue) │\n│ incoming: 0 │ │\n│ │ Incoming Dependencies: │\n│ 🟢 db ━━━ 0.22 │ ← frontend (2 issues) │\n│ outgoing: 0 │ ← mobile (1 issue) │\n│ incoming: 7 ← [api, auth] │ │\n│ │ Critical Path: YES │\n└───────────────────────────────────────────┴─────────────────────────────────┘\n```\n\n### Bottleneck Score\n\nThe bottleneck score (0.0–1.0) measures how much a label blocks cross-domain work:\n\n$$\n\\text{Bottleneck} = \\frac{\\text{Outgoing Deps}}{\\text{Total Cross-Label Deps}} \\times \\text{Criticality Weight}\n$$\n\n| Score | Color | Meaning |\n|-------|-------|---------|\n| 0.7 – 1.0 | 🔴 Red | Critical bottleneck—prioritize unblocking |\n| 0.4 – 0.7 | 🟡 Yellow | Moderate blocking—monitor closely |\n| 0.0 – 0.4 | 🟢 Green | Healthy flow—no coordination issues |\n\n### Drilldown Mode\n\nPress `Enter` on a label to drill down into the specific issues creating cross-label dependencies:\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ 🔀 FLOW MATRIX > api → auth 3 issues │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ 🐛 P1 API-123 Auth endpoint returns 500 blocks AUTH-456 │\n│ ✨ P2 API-456 Add OAuth scope validation blocks AUTH-789 │\n│ 📝 P2 API-789 Token refresh rate limiting blocks AUTH-101 │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n### Navigation\n\n| Key | Action |\n|-----|--------|\n| `j` \u002F `k` | Move between labels |\n| `Tab` | Toggle focus between labels list and detail panel |\n| `Enter` | Drill down into cross-label issues |\n| `Esc` | Exit drilldown \u002F Exit view |\n| `f` \u002F `q` | Exit flow matrix view |\n\n### Robot Command\n\n```bash\nbv --robot-label-flow | jq '.flow.bottleneck_labels'\n```\n\n---\n\n## 🎪 Attention View: Label Priority Ranking\n\nPress `]` to open the **Attention View**—a ranked table of labels by attention score, helping you identify which project areas need focus.\n\n### Attention Score Formula\n\nThe attention score combines multiple signals to surface neglected or problematic areas:\n\n$$\n\\text{Attention} = \\frac{\\text{PageRank}_{\\text{avg}} \\times \\text{Staleness} \\times \\text{BlockImpact}}{\\text{Velocity} + \\epsilon}\n$$\n\n| Component | What It Measures |\n|-----------|------------------|\n| **PageRank (avg)** | Average importance of issues in this label |\n| **Staleness** | How long since issues were updated (higher = more stale) |\n| **Block Impact** | How many issues are blocked within this label |\n| **Velocity** | Completion rate (issues closed per week) |\n\nHigh attention scores indicate labels that are both important and neglected—they need intervention.\n\n### Visual Layout\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ 🎪 ATTENTION VIEW │\n├──────┬────────────┬───────────┬─────────────────────────────────────────────┤\n│ Rank │ Label │ Attention │ Reason │\n├──────┼────────────┼───────────┼─────────────────────────────────────────────┤\n│ 1 │ api │ 2.45 │ blocked=5 stale=3 vel=0.8 │\n│ 2 │ auth │ 1.89 │ blocked=2 stale=4 vel=1.2 │\n│ 3 │ infra │ 1.23 │ blocked=1 stale=6 vel=0.5 │\n│ 4 │ frontend │ 0.67 │ blocked=0 stale=1 vel=3.5 │\n│ 5 │ docs │ 0.34 │ blocked=0 stale=2 vel=2.1 │\n└──────┴────────────┴───────────┴─────────────────────────────────────────────┘\n```\n\n### Interpreting Results\n\n- **High Attention + Low Velocity**: Area is stuck—investigate blockers\n- **High Attention + High Stale**: Work forgotten—resurface and reprioritize\n- **Low Attention + High Velocity**: Healthy area—keep momentum\n- **High Blocked Count**: Dependencies creating bottleneck\n\n### Navigation\n\n| Key | Action |\n|-----|--------|\n| `j` \u002F `k` | Move between labels |\n| `]` \u002F `Esc` | Exit attention view |\n\n### Robot Command\n\n```bash\nbv --robot-label-attention --attention-limit=10\n```\n\n---\n\n## 📚 Shortcuts Sidebar: Persistent Keyboard Reference\n\nPress `;` (semicolon) or `F2` to toggle the **Shortcuts Sidebar**—a persistent panel showing context-aware keyboard shortcuts alongside your current view.\n\n### Why a Sidebar (Not Just Help)?\n\nThe `?` help overlay shows shortcuts but blocks your view. The shortcuts sidebar stays visible while you work, perfect for:\n- Learning keyboard shortcuts without interrupting your flow\n- Quick reference during complex navigation\n- Teaching new users while pair programming\n\n### Context Awareness\n\nThe sidebar automatically filters shortcuts to show only those relevant to your current view:\n\n| Context | Shown Sections |\n|---------|----------------|\n| List View | Navigation, Filters, Views, Actions |\n| Board View | Navigation, Board-specific, Swimlanes |\n| Graph View | Navigation, Panning, Zoom |\n| Insights | Navigation, Panels, Toggles |\n| History | Navigation, View Modes, Timeline |\n\n### Visual Layout\n\n```\n┌──────────────────────────────────────────────┬──────────────────────┐\n│ │ ⌨️ SHORTCUTS │\n│ │ ────────────────── │\n│ Main Content Area │ │\n│ │ Navigation │\n│ (List, Board, Graph, etc.) │ j\u002Fk Move ↓\u002F↑ │\n│ │ G\u002Fgg End\u002FStart │\n│ │ ^d\u002F^u Page ↓\u002F↑ │\n│ │ │\n│ │ Views │\n│ │ b Board │\n│ │ g Graph │\n│ │ i Insights │\n│ │ │\n│ │ ; to hide │\n└──────────────────────────────────────────────┴──────────────────────┘\n```\n\n### Sidebar Controls\n\n| Key | Action |\n|-----|--------|\n| `;` or `F2` | Toggle sidebar visibility |\n| `Ctrl+J` | Scroll sidebar down (when visible) |\n| `Ctrl+K` | Scroll sidebar up (when visible) |\n\nThe sidebar occupies a fixed 34-character width on the right edge of the terminal.\n\n---\n\n## 🎓 Interactive Tutorial System\n\nPress `` ` `` (backtick) to open the **Interactive Tutorial**—a comprehensive multi-page walkthrough that teaches all bv features through rich, styled content.\n\n### Tutorial Architecture\n\nThe tutorial uses a **component-based rendering system** that produces beautiful terminal output:\n\n| Component | Purpose | Example |\n|-----------|---------|---------|\n| **Section** | Styled headers with underlines | `## Navigation` |\n| **Paragraph** | Flowing text with proper wrapping | Explanation text |\n| **KeyTable** | Aligned key-description pairs | `j\u002Fk` → Move up\u002Fdown |\n| **Tip** | Highlighted advice boxes | 💡 TIP: Press g to jump... |\n| **Warning** | Alert boxes for important notes | ⚠️ WARN: This action... |\n| **Code** | Syntax-highlighted code blocks | `bv --robot-triage` |\n| **Bullet** | Styled bullet lists | • First item |\n| **Tree** | Hierarchical structure display | Directory trees |\n| **StatusFlow** | Visual workflow diagrams | Open → In Progress → Closed |\n| **InfoBox** | Bordered information panels | Feature highlights |\n\n### Tutorial Sections\n\nThe tutorial covers these topics in depth:\n\n1. **Introduction** — What bv is and why it exists\n2. **Core Concepts** — Beads, dependencies, labels, priorities\n3. **List View** — Navigation, filtering, sorting\n4. **Board View** — Kanban workflows, swimlanes\n5. **Graph View** — Dependency visualization\n6. **Tree View** — Parent-child hierarchies\n7. **Insights Dashboard** — Graph metrics deep dive\n8. **History View** — Git correlation\n9. **Robot Protocol** — AI agent integration\n10. **Workflows** — Triage, planning, sprint management\n\n### Progress Tracking\n\nThe tutorial automatically tracks which pages you've viewed:\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ 📖 TUTORIAL Page 3\u002F10 · 30% ████░░░░│\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ ## List View Navigation │\n│ ───────────────────────── │\n│ │\n│ The list view is your home base. Navigate with vim-style keys: │\n│ │\n│ j \u002F k Move down \u002F up │\n│ g \u002F G Jump to top \u002F bottom │\n│ Ctrl+D\u002FU Page down \u002F up │\n│ │\n│ ╭──────────────────────────────────────────────────────────────────────╮ │\n│ │ 💡 TIP Press `\u002F` to search, then type any part of an issue title │ │\n│ ╰──────────────────────────────────────────────────────────────────────╯ │\n│ │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ ← h previous │ l next → │ t TOC │ q close │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\nProgress persists across sessions, so you can close bv and resume where you left off.\n\n### Tutorial Navigation\n\n| Key | Action |\n|-----|--------|\n| `h` \u002F `l` or `←` \u002F `→` | Previous \u002F Next page |\n| `j` \u002F `k` | Scroll content up \u002F down |\n| `t` | Toggle Table of Contents |\n| `g` \u002F `G` | First \u002F Last page |\n| `q` \u002F `Esc` | Close tutorial |\n\n### Context-Sensitive Filtering\n\nWhen you open the tutorial from a specific view (e.g., press `` ` `` while in Board view), the tutorial can filter to show only pages relevant to that context. This provides focused learning without overwhelming new users.\n\n### Quick Reference vs. Full Tutorial\n\nbv provides two help levels:\n\n| Feature | Key | Purpose |\n|---------|-----|---------|\n| **Quick Reference** | `?` | Compact keyboard shortcuts for current view |\n| **Full Tutorial** | `` ` `` | Multi-page walkthrough with examples |\n| **Shortcuts Sidebar** | `;` | Persistent reference while working |\n\nFrom Quick Reference, press `Space` to jump directly into the full tutorial.\n\n---\n\n## 📜 History View: Bead-to-Commit Correlation\n\nPress `h` to open the **History View**—an interactive timeline that correlates beads with their related git commits. This bridges the gap between \"what work was planned\" and \"what code was actually written.\"\n\n### The Correlation Engine\n\nThe `pkg\u002Fcorrelation` package implements a **multi-strategy correlation system** that infers relationships between beads and commits using several techniques:\n\n```mermaid\ngraph TD\n %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8f5e9', 'lineColor': '#90a4ae'}}}%%\n\n subgraph strategies [\"🔍 Correlation Strategies\"]\n E[\"Explicit Mentions\u003Cbr\u002F>\u003Csmall>Commit contains bead ID\u003C\u002Fsmall>\"]\n T[\"Temporal Proximity\u003Cbr\u002F>\u003Csmall>Commit near bead events\u003C\u002Fsmall>\"]\n C[\"Co-Commit Analysis\u003Cbr\u002F>\u003Csmall>Files changed together\u003C\u002Fsmall>\"]\n P[\"Path Matching\u003Cbr\u002F>\u003Csmall>File paths match bead scope\u003C\u002Fsmall>\"]\n end\n\n subgraph scorer [\"📊 Confidence Scorer\"]\n S[\"Multi-Factor Scoring\u003Cbr\u002F>\u003Csmall>Weighted combination\u003C\u002Fsmall>\"]\n end\n\n subgraph output [\"📈 Output\"]\n H[\"BeadHistory\u003Cbr\u002F>\u003Csmall>Events + Commits + Milestones\u003C\u002Fsmall>\"]\n end\n\n E --> S\n T --> S\n C --> S\n P --> S\n S --> H\n\n classDef strategy fill:#e3f2fd,stroke:#90caf9,stroke-width:2px,color:#1565c0\n classDef score fill:#fff8e1,stroke:#ffcc80,stroke-width:2px,color:#e65100\n classDef out fill:#e8f5e9,stroke:#a5d6a7,stroke-width:2px,color:#2e7d32\n\n class E,T,C,P strategy\n class S score\n class H out\n```\n\n### Correlation Strategies\n\n| Strategy | Weight | How It Works |\n|----------|--------|--------------|\n| **Explicit Mentions** | High | Commit message contains bead ID (e.g., `fix(auth): resolve race condition [BV-123]`) |\n| **Temporal Proximity** | Medium | Commit timestamp falls within bead's active lifecycle window |\n| **Co-Commit Analysis** | Medium | Files frequently modified together suggest shared purpose |\n| **Path Matching** | Low | File paths match bead's label scope (e.g., `pkg\u002Fauth\u002F*` for `auth` label) |\n\n### Confidence Scoring\n\nEach correlation receives a **confidence score** (0.0–1.0) computed by:\n\n$$\n\\text{Confidence} = w_1 \\cdot \\text{Explicit} + w_2 \\cdot \\text{Temporal} + w_3 \\cdot \\text{CoCommit} + w_4 \\cdot \\text{Path}\n$$\n\nDefault weights: Explicit=0.5, Temporal=0.25, CoCommit=0.15, Path=0.10\n\n### History View Layout\n\nThe History View uses a **responsive three-pane layout** that adapts to terminal width:\n\n| Width | Layout |\n|-------|--------|\n| **\u003C 100** | Single pane: List with inline details |\n| **100-160** | Two panes: List + Detail |\n| **> 160** | Three panes: List + Timeline + Detail |\n\n**Wide Terminal (3-pane) Layout:**\n```\n┌─────────────────────────────────────────────────────────────────────────────────┐\n│ 📜 HISTORY VIEW [Bead Mode] [≥ 0.5] │\n├───────────────────────┬───────────────────┬─────────────────────────────────────┤\n│ BEADS │ TIMELINE │ COMMIT DETAIL │\n│ ───────────────── │ ───────────── │ ───────────────────────── │\n│ ▸ BV-123 (3 commits) │ ┃ │ abc1234 - Fix auth race │\n│ 🎯 BV-456 (1) │ ━╋━ Jan 15 │ Author: alice@example.com │\n│ 🔗 BV-789 (5) │ ┃ ▪▪▪ │ Date: 2025-01-15 14:32 │\n│ 📁 BV-100 (2) │ ━╋━ Jan 14 │ Confidence: 0.85 (explicit) │\n│ │ ┃ ▪ │ │\n│ │ ━╋━ Jan 13 │ Files changed: │\n│ │ ┃ ▪▪▪▪▪ │ M pkg\u002Fauth\u002Fsession.go │\n└───────────────────────┴───────────────────┴─────────────────────────────────────┘\n```\n\n### Timeline Panel (`t` Toggle)\n\nPress `t` to show\u002Fhide the **Timeline Panel**—a visual density chart of project activity:\n\n- **Vertical axis**: Time (newest at top)\n- **Horizontal bars**: Activity density (commits per day)\n- **Bar magnitude**: ▪ = 1-2, ▪▪ = 3-5, ▪▪▪ = 6-10, ▪▪▪▪ = 11+\n- **Highlights**: Selected bead's commits are marked with `━`\n\nClick or navigate to a date to filter the view to that time period.\n\n### Causality Markers\n\nEach bead-commit correlation shows its **detection method** as a visual marker:\n\n| Marker | Meaning | Confidence |\n|--------|---------|------------|\n| **🎯 Direct** | Commit message explicitly mentions bead ID | High (0.8-1.0) |\n| **🔗 Temporal** | Commit falls within bead's active lifecycle | Medium (0.4-0.7) |\n| **📁 File** | Commit touches files associated with bead | Low (0.2-0.5) |\n\n### View Modes\n\nPress `v` to toggle between two view modes:\n\n| Mode | Shows | Use Case |\n|------|-------|----------|\n| **Bead Mode** (default) | Beads grouped with their correlated commits | \"What commits relate to this task?\" |\n| **Git Mode** | Commits chronologically with correlated beads | \"What tasks did this commit touch?\" |\n\n### File-Centric Drill-Down (`f` Key)\n\nPress `f` to switch to **File Mode**—a tree view of changed files grouped by directory:\n\n```\n┌─────────────────────────────────────────────────────────────────────────┐\n│ 📁 FILE MODE [12 files] │\n├─────────────────────────────────────────────────────────────────────────┤\n│ ▼ pkg\u002Fauth\u002F │\n│ session.go 42 changes BV-123, BV-456 │\n│ token.go 18 changes BV-123 │\n│ middleware.go 8 changes BV-789 │\n│ ▼ pkg\u002Fapi\u002F │\n│ handler.go 25 changes BV-100 │\n│ routes.go 12 changes BV-100, BV-456 │\n└─────────────────────────────────────────────────────────────────────────┘\n```\n\nNavigate to a file and press `Enter` to see all beads and commits that touched it.\n\n### History Navigation\n\n| Key | Action |\n|-----|--------|\n| **Navigation** | |\n| `j` \u002F `k` | Move in primary pane (beads or commits) |\n| `J` \u002F `K` | Move in secondary pane (commits or detail) |\n| `Tab` | Cycle focus: List → Timeline → Detail |\n| `Enter` | Expand\u002Fcollapse or drill into selection |\n| **View Modes** | |\n| `v` | Toggle Bead Mode ↔ Git Mode |\n| `f` | Toggle File-centric drill-down |\n| `t` | Toggle Timeline panel visibility |\n| **Filtering** | |\n| `c` | Cycle confidence threshold (0.0 → 0.3 → 0.5 → 0.7) |\n| `\u002F` | Search commits or beads |\n| **Actions** | |\n| `y` | Copy selected commit SHA to clipboard |\n| `o` | Open commit in browser (GitHub\u002FGitLab) |\n| `V` | Preview cass sessions for selected bead |\n| `Esc` | Return to list view |\n\n### Robot Command: `--robot-history`\n\n```bash\nbv --robot-history # Full history report\nbv --robot-history --bead-history BV-123 # Single bead focus\nbv --robot-history --history-since '30 days ago'\nbv --robot-history --min-confidence 0.7 # High-confidence only\n```\n\n**Output Schema:**\n```json\n{\n \"stats\": {\n \"total_beads\": 58,\n \"beads_with_commits\": 42,\n \"total_commits\": 156,\n \"avg_cycle_time_hours\": 72.5,\n \"method_distribution\": {\n \"explicit\": 89,\n \"temporal\": 45,\n \"cocommit\": 22\n }\n },\n \"histories\": {\n \"BV-123\": {\n \"events\": [...],\n \"commits\": [...],\n \"milestones\": [...],\n \"cycle_time_hours\": 48.2\n }\n },\n \"commit_index\": {\n \"abc1234\": [\"BV-123\", \"BV-456\"]\n }\n}\n```\n\n---\n\n## 🔗 Correlation Analysis: Impact Network & Related Work\n\nBeyond simple bead-to-commit correlation, `bv` provides **deep analysis** of how beads relate to each other through shared code changes. This helps identify hidden dependencies, find related work, and understand the true impact of changes.\n\n### Impact Network Graph\n\nThe Impact Network visualizes **implicit relationships** between beads based on:\n\n```mermaid\ngraph LR\n %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e3f2fd', 'lineColor': '#90a4ae'}}}%%\n\n subgraph connections [\"🔗 Edge Types\"]\n SC[\"Shared Commit\u003Cbr\u002F>\u003Csmall>Same commit touches both beads\u003C\u002Fsmall>\"]\n SF[\"Shared File\u003Cbr\u002F>\u003Csmall>Both beads modify same files\u003C\u002Fsmall>\"]\n DEP[\"Dependency\u003Cbr\u002F>\u003Csmall>Explicit blocker relationship\u003C\u002Fsmall>\"]\n end\n\n classDef edge fill:#fff8e1,stroke:#ffcc80,stroke-width:2px\n class SC,SF,DEP edge\n```\n\n| Edge Type | Weight | Meaning |\n|-----------|--------|---------|\n| **Shared Commit** | High | A single commit references both beads (strong coupling) |\n| **Shared File** | Medium | Both beads touched the same source file |\n| **Dependency** | Explicit | Direct blocking relationship from issue tracker |\n\n### Network Clusters\n\n`bv` automatically detects **clusters** of tightly-connected beads using community detection:\n\n```\n┌─────────────────────────────────────────────────────────────────────────┐\n│ 🔗 IMPACT NETWORK [3 clusters] │\n├─────────────────────────────────────────────────────────────────────────┤\n│ │\n│ ┌─── Cluster 1: Auth Module ───┐ ┌─── Cluster 2: API Layer ───┐ │\n│ │ BV-123 ←──→ BV-456 │ │ BV-789 ←──→ BV-100 │ │\n│ │ ↕ ↕ │ │ ↕ │ │\n│ │ BV-321 ←──→ BV-654 │────→│ BV-111 │ │\n│ └──────────────────────────────┘ └─────────────────────────────┘ │\n│ │\n│ Central bead: BV-123 (highest degree) │\n│ Internal connectivity: 0.85 (tightly coupled) │\n│ External edges: 1 (to API layer cluster) │\n└─────────────────────────────────────────────────────────────────────────┘\n```\n\n### File-to-Bead Lookup\n\nFind all beads that have touched a specific file using `--robot-file-beads`:\n\n```bash\nbv --robot-file-beads pkg\u002Fui\u002Fboard.go\n```\n\nReturns beads sorted by recency with commit details:\n\n```json\n{\n \"file_path\": \"pkg\u002Fui\u002Fboard.go\",\n \"total_beads\": 21,\n \"open_beads\": [],\n \"closed_beads\": [\n {\n \"bead_id\": \"bv-v67w\",\n \"title\": \"Board: Integration & Polish\",\n \"status\": \"closed\",\n \"commit_shas\": [\"abc123\"],\n \"last_touch\": \"2025-12-18T00:19:21-05:00\",\n \"total_changes\": 17\n }\n ]\n}\n```\n\n**Use cases:**\n- **Code ownership**: \"Who has worked on this file recently?\"\n- **Impact analysis**: \"What work items are affected by this file?\"\n- **Bug investigation**: \"What changes might have introduced this regression?\"\n\n### Orphan Commit Detection\n\nFind commits that should be linked to beads but aren't using `--robot-orphans`:\n\n```bash\nbv --robot-orphans\n```\n\nReturns candidate commits with probable bead matches:\n\n```json\n{\n \"stats\": {\n \"total_commits\": 500,\n \"correlated_count\": 242,\n \"orphan_count\": 258,\n \"orphan_ratio\": 0.516\n },\n \"candidates\": [\n {\n \"sha\": \"abc1234\",\n \"message\": \"feat: add auth caching\",\n \"suspicion_score\": 100,\n \"probable_beads\": [\n {\n \"bead_id\": \"bv-xyz\",\n \"confidence\": 65,\n \"reasons\": [\"touches file pkg\u002Fauth\u002Fcache.go\", \"same author worked on bead nearby\"]\n }\n ]\n }\n ]\n}\n```\n\n**Use cases:**\n- **Hygiene**: Find commits that slipped through without proper linking\n- **Audit**: Ensure all code changes are tracked to work items\n- **Correlation improvement**: Train the system by confirming\u002Frejecting suggestions\n\n### Related Work Discovery\n\nFor any bead, `bv` can find **related work** across four dimensions:\n\n| Relation Type | How Detected | Example |\n|---------------|--------------|---------|\n| **File Overlap** | Both beads modify same source files | \"BV-123 and BV-456 both touch `session.go`\" |\n| **Commit Overlap** | Both beads referenced in same commit | \"BV-123 and BV-456 fixed in commit `abc123`\" |\n| **Dependency Cluster** | Both in same tightly-connected subgraph | \"BV-123 is in the Auth cluster with BV-456\" |\n| **Concurrent** | Active during the same time window | \"BV-123 and BV-456 both worked on last week\" |\n\nEach relation includes a **relevance score** (0-100) indicating strength.\n\n### Robot Commands\n\n```bash\n# Get the full impact network (use \"all\" for complete graph)\nbv --robot-impact-network all\n\n# Get subnetwork focused on specific bead (default depth=2, max=3)\nbv --robot-impact-network bv-123 --network-depth 2\n\n# Find related work for a bead\nbv --robot-related bv-123\n\n# Include closed beads in related work results\nbv --robot-related bv-123 --related-include-closed\n\n# Tune related work thresholds\nbv --robot-related bv-123 --related-min-relevance 30 --related-max-results 20\n\n# Analyze causal chain for a bead (timeline, blockers, insights)\nbv --robot-causality bv-123\n\n# Find beads that touched a file\nbv --robot-file-beads pkg\u002Fauth\u002Fsession.go\n\n# Find orphan commits (unlinked to beads)\nbv --robot-orphans\n```\n\n### Causal Chain Analysis\n\nThe `--robot-causality` command reveals **why a bead took as long as it did** by reconstructing its timeline of events:\n\n| Event Type | Description |\n|------------|-------------|\n| `created` | Bead was opened |\n| `claimed` | Work started (status → in_progress) |\n| `commit` | Code commit linked to bead |\n| `blocked` | Bead became blocked by another bead |\n| `unblocked` | Blocking dependency was resolved |\n| `closed` | Bead was completed |\n| `reopened` | Bead was reopened after closure |\n\n**Insights provided:**\n- **Blocked percentage**: How much time was spent waiting on dependencies\n- **Critical path**: The chain of events determining minimum completion time\n- **Longest gap**: Identifies stalled periods needing investigation\n- **Recommendations**: Actionable suggestions (e.g., \"Consider breaking into smaller beads\")\n\n**Causality Output Schema:**\n```json\n{\n \"generated_at\": \"2025-01-15T14:32:00Z\",\n \"data_hash\": \"abc123...\",\n \"chain\": {\n \"bead_id\": \"bv-123\",\n \"title\": \"Implement auth caching\",\n \"status\": \"closed\",\n \"events\": [\n {\"id\": 1, \"type\": \"created\", \"timestamp\": \"2025-01-10T10:00:00Z\"},\n {\"id\": 2, \"type\": \"claimed\", \"timestamp\": \"2025-01-10T11:00:00Z\", \"caused_by_id\": 1},\n {\"id\": 3, \"type\": \"blocked\", \"timestamp\": \"2025-01-11T09:00:00Z\", \"blocker_id\": \"bv-456\"},\n {\"id\": 4, \"type\": \"unblocked\", \"timestamp\": \"2025-01-12T16:00:00Z\"},\n {\"id\": 5, \"type\": \"commit\", \"timestamp\": \"2025-01-13T10:00:00Z\", \"commit_sha\": \"abc1234\"},\n {\"id\": 6, \"type\": \"closed\", \"timestamp\": \"2025-01-13T17:00:00Z\"}\n ],\n \"edge_count\": 5,\n \"total_time\": \"79h0m0s\",\n \"is_complete\": true\n },\n \"insights\": {\n \"total_duration\": \"79h0m0s\",\n \"blocked_duration\": \"31h0m0s\",\n \"active_duration\": \"48h0m0s\",\n \"blocked_percentage\": 39.2,\n \"blocked_periods\": [\n {\"start_time\": \"2025-01-11T09:00:00Z\", \"end_time\": \"2025-01-12T16:00:00Z\", \"blocker_id\": \"bv-456\"}\n ],\n \"commit_count\": 1,\n \"critical_path_desc\": \"created → claimed → blocked → unblocked → commit → closed\",\n \"summary\": \"Bead took 79h total; 39% blocked by bv-456\",\n \"recommendations\": [\"Consider unblocking bv-456 earlier to reduce wait time\"]\n }\n}\n```\n\n### Correlation Feedback System\n\nTrain the correlation engine by confirming or rejecting its suggestions:\n\n```bash\n# Explain why a correlation exists\nbv --robot-explain-correlation abc1234:bv-xyz\n\n# Confirm a correct correlation (boosts confidence)\nbv --robot-confirm-correlation abc1234:bv-xyz\n\n# Reject an incorrect correlation (removes it)\nbv --robot-reject-correlation abc1234:bv-xyz\n\n# View feedback statistics\nbv --robot-correlation-stats\n```\n\n**Feedback Stats Output:**\n```json\n{\n \"total_feedback\": 15,\n \"confirmed\": 12,\n \"rejected\": 3,\n \"accuracy_rate\": 0.80,\n \"avg_confirm_conf\": 0.85,\n \"avg_reject_conf\": 0.42\n}\n```\n\nThis feedback loop improves correlation accuracy over time—confirmed correlations strengthen pattern recognition, while rejections help eliminate false positives.\n\n**Impact Network Output Schema:**\n```json\n{\n \"generated_at\": \"2025-01-15T14:32:00Z\",\n \"data_hash\": \"abc123...\",\n \"stats\": {\n \"total_nodes\": 58,\n \"total_edges\": 142,\n \"cluster_count\": 5,\n \"avg_degree\": 4.9,\n \"density\": 0.086,\n \"isolated_nodes\": 3\n },\n \"clusters\": [\n {\n \"cluster_id\": 1,\n \"bead_ids\": [\"BV-123\", \"BV-456\", \"BV-321\"],\n \"label\": \"Auth Module\",\n \"internal_connectivity\": 0.85,\n \"central_bead\": \"BV-123\",\n \"shared_files\": [\"pkg\u002Fauth\u002Fsession.go\", \"pkg\u002Fauth\u002Ftoken.go\"]\n }\n ],\n \"edges\": [\n {\"from_bead\": \"BV-123\", \"to_bead\": \"BV-456\", \"edge_type\": \"shared_commit\", \"weight\": 5}\n ]\n}\n```\n\n---\n\n## 🤖 Cass Integration: AI Session Correlation (Optional)\n\n`bv` optionally integrates with [**cass**](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fcoding_agent_session_search) (Claude Agent Session Store)—a tool that captures and indexes coding sessions from AI assistants like Claude. When cass is installed, `bv` automatically enhances its correlation capabilities with session-based insights.\n\n### How It Works\n\n```mermaid\ngraph LR\n %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8f5e9', 'lineColor': '#90a4ae'}}}%%\n\n CASS[\"🤖 cass\u003Cbr\u002F>\u003Csmall>Session Store\u003C\u002Fsmall>\"]\n BV[\"⚡ bv\u003Cbr\u002F>\u003Csmall>Issue Viewer\u003C\u002Fsmall>\"]\n CORR[\"🔗 Enhanced\u003Cbr\u002F>Correlation\"]\n\n CASS --> BV\n BV --> CORR\n\n classDef tool fill:#e3f2fd,stroke:#90caf9,stroke-width:2px\n class CASS,BV,CORR tool\n```\n\n**Graceful Degradation:** If cass is not installed, `bv` works normally—no errors, broken UI, or loading states. Cass features simply become unavailable.\n\n### Detection & Status\n\n`bv` automatically detects cass on startup:\n\n| Status | Indicator | Meaning |\n|--------|-----------|---------|\n| **Healthy** | 🤖 in status bar | cass is installed, indexed, and ready |\n| **Needs Index** | ⚠️ in status bar | cass installed but needs `cass index` |\n| **Not Installed** | (none) | cass not in PATH—features hidden |\n\n### Session Preview Modal (`V` Key)\n\nPress `V` on any bead to open the **Session Preview Modal**—a view of AI coding sessions that may have contributed to that issue:\n\n```\n┌─────────────────────────────────────────────────────────────────────────┐\n│ 🤖 Related Coding Sessions for BV-123 │\n├─────────────────────────────────────────────────────────────────────────┤\n│ │\n│ ▸ Session 1 (claude-opus-4) Dec 15, 2:30 PM │\n│ \"Implementing session refresh timeout handling...\" │\n│ Confidence: 0.92 (explicit mention) │\n│ │\n│ Session 2 (claude-opus-4) Dec 14, 10:15 AM │\n│ \"Refactoring token validation middleware...\" │\n│ Confidence: 0.67 (file overlap) │\n│ │\n│ Session 3 (claude-opus-4) Dec 13, 4:45 PM │\n│ \"Adding retry logic to auth service...\" │\n│ Confidence: 0.45 (temporal) │\n│ │\n├─────────────────────────────────────────────────────────────────────────┤\n│ j\u002Fk: Navigate y: Copy search command Enter: View full session │\n└─────────────────────────────────────────────────────────────────────────┘\n```\n\n**Session Correlation Methods:**\n\n| Method | Weight | Meaning |\n|--------|--------|---------|\n| **Explicit** | 0.9-1.0 | Session mentions bead ID directly |\n| **File Overlap** | 0.5-0.8 | Session touched files associated with bead |\n| **Temporal** | 0.3-0.6 | Session occurred during bead's active lifecycle |\n| **Keyword** | 0.2-0.5 | Session contains keywords from bead title\u002Fdescription |\n\n### Status Bar Indicator\n\nWhen cass is healthy, the status bar shows agent activity:\n\n```\n┌────────────────────────────────────────────────────────────────────────┐\n│ 📋 437 issues • 🤖 claude-opus-4 (active) • Last: 5m ago │\n└────────────────────────────────────────────────────────────────────────┘\n```\n\n| State | Display | Meaning |\n|-------|---------|---------|\n| **Active** | 🤖 agent-name | Session in progress within last 15 minutes |\n| **Idle** | 💤 | No recent sessions |\n\n### Installing Cass\n\n```bash\n# Install cass (see https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fcoding_agent_session_search for full docs)\nbrew install dicklesworthstone\u002Ftap\u002Fcass # macOS\n# or\ncargo install cass # From source\n\n# Index your coding sessions\ncass index\n\n# Verify integration\nbv # Look for 🤖 in status bar\n```\n\n### Cass-Enhanced History View\n\nWhen cass is available, the History View gains additional capabilities:\n\n- **Session Timeline**: `V` key shows sessions alongside commits\n- **Agent Attribution**: See which AI assistant contributed to changes\n- **Enhanced Search**: Search across both commits and sessions\n\n---\n\n## 📅 Sprint Dashboard: Burndown & Progress Tracking\n\nPress `P` (uppercase) to open the **Sprint Dashboard**—a comprehensive view of sprint progress with burndown visualization, scope change tracking, and at-risk detection.\n\n### Dashboard Layout\n\n```\n┌─────────────────────────────────────────────────────────────────────────┐\n│ 📅 Sprint: January 2025 │\n│ ─────────────────────────────────────────────────────────────────── │\n│ Dates: Jan 6 → Jan 20 │\n│ Remaining: 5 days │\n│ │\n│ ══════════════════════════════════════════════════════════════════ │\n│ PROGRESS │\n│ ══════════════════════════════════════════════════════════════════ │\n│ │\n│ Total: 24 beads Closed: 18 (75%) Remaining: 6 │\n│ [████████████████████░░░░░░] 75% │\n│ │\n│ ══════════════════════════════════════════════════════════════════ │\n│ BURNDOWN │\n│ ══════════════════════════════════════════════════════════════════ │\n│ │\n│ 24 ┤ · │\n│ 20 ┤ ····· │\n│ 16 ┤ ····▸ │\n│ 12 ┤ ╲ (ideal) │\n│ 8 ┤ ╲ │\n│ 4 ┤ ╲ │\n│ 0 ┼────────────────────────────────────────────────────────────── │\n│ Jan 6 Jan 13 Jan 20 │\n│ │\n│ Legend: · = Actual ╲ = Ideal ▸ = Today │\n│ │\n│ ══════════════════════════════════════════════════════════════════ │\n│ SCOPE CHANGES │\n│ ══════════════════════════════════════════════════════════════════ │\n│ │\n│ Jan 8: +2 beads added (BV-456, BV-457) │\n│ Jan 10: -1 bead removed (BV-100 moved to backlog) │\n│ │\n│ ══════════════════════════════════════════════════════════════════ │\n│ AT-RISK ITEMS │\n│ ══════════════════════════════════════════════════════════════════ │\n│ │\n│ ⚠ BV-789 (P0 Critical) - Blocked for 3 days │\n│ ⚠ BV-234 (P1 High) - No activity for 5 days │\n└─────────────────────────────────────────────────────────────────────────┘\n```\n\n### Burndown Calculation\n\nThe burndown chart implements a **scope-aware algorithm** that tracks not just completion velocity but also scope changes:\n\n1. **Ideal Burn Rate:** `Total Beads \u002F Sprint Duration`\n2. **Actual Burn Rate:** `Closed Beads \u002F Days Elapsed`\n3. **Scope Events:** Added\u002Fremoved beads create discontinuities in the ideal line\n\nWhen beads are added mid-sprint, the burndown recalculates the ideal trajectory from that point forward, providing a realistic view of progress rather than a misleading \"behind schedule\" indicator.\n\n### At-Risk Detection\n\nItems are flagged as at-risk based on multiple heuristics:\n\n| Signal | Threshold | Reason |\n|--------|-----------|--------|\n| **Blocked Duration** | > 2 days | Dependency bottleneck |\n| **No Activity** | > 4 days | Potentially stuck or forgotten |\n| **High Priority Blocked** | P0\u002FP1 blocked | Critical path impediment |\n| **Dependencies Not Closing** | Blockers still open | Cascading delay risk |\n\n### Robot Commands\n\n```bash\nbv --robot-sprint-list # List all sprints\nbv --robot-sprint-show sprint-1 # Details for specific sprint\nbv --robot-burndown current # Burndown for active sprint\nbv --robot-burndown sprint-1 # Burndown for specific sprint\n```\n\n**Burndown Output:**\n```json\n{\n \"sprint_id\": \"sprint-1\",\n \"total_days\": 14,\n \"elapsed_days\": 9,\n \"remaining_days\": 5,\n \"total_issues\": 24,\n \"completed_issues\": 18,\n \"remaining_issues\": 6,\n \"ideal_burn_rate\": 1.71,\n \"actual_burn_rate\": 2.0,\n \"projected_complete\": \"2025-01-18\",\n \"on_track\": true,\n \"scope_changes\": [\n {\"date\": \"2025-01-08\", \"delta\": 2, \"reason\": \"Added BV-456, BV-457\"}\n ]\n}\n```\n\n---\n\n## 🏷️ Label Analytics: Domain-Centric Health Monitoring\n\nPress `L` (uppercase) to open the **Label Dashboard**—a table view showing health metrics for each label in your project. This enables **domain-driven prioritization** by surfacing which areas of your codebase need attention.\n\n### Label Dashboard Layout\n\n```\n┌─────────────────────────────────────────────────────────────────────────┐\n│ 🏷️ LABEL HEALTH │\n├──────────────┬────────┬────────┬────────┬────────┬────────┬────────────┤\n│ Label │ Health │ Status │ Open │ Blocked│ Stale │ Velocity │\n├──────────────┼────────┼────────┼────────┼────────┼────────┼────────────┤\n│ 🔴 api │ 0.32 │ CRIT │ 12 │ 5 │ 3 │ 0.8\u002Fwk │\n│ 🟡 auth │ 0.58 │ WARN │ 8 │ 2 │ 1 │ 2.1\u002Fwk │\n│ 🟢 ui │ 0.85 │ OK │ 4 │ 0 │ 0 │ 4.2\u002Fwk │\n│ 🟢 docs │ 0.92 │ OK │ 2 │ 0 │ 0 │ 1.5\u002Fwk │\n│ 🟡 infra │ 0.61 │ WARN │ 6 │ 1 │ 2 │ 1.2\u002Fwk │\n└──────────────┴────────┴────────┴────────┴────────┴────────┴────────────┘\n```\n\n### Health Score Calculation\n\nThe label health score combines multiple factors:\n\n$$\n\\text{Health} = 1 - \\left( w_1 \\cdot \\frac{\\text{Blocked}}{\\text{Open}} + w_2 \\cdot \\frac{\\text{Stale}}{\\text{Open}} + w_3 \\cdot (1 - \\text{VelocityScore}) \\right)\n$$\n\n| Component | Weight | Meaning |\n|-----------|--------|---------|\n| **Blocked Ratio** | 0.4 | High blocked count indicates bottlenecks |\n| **Stale Ratio** | 0.3 | Stale issues suggest neglect |\n| **Velocity Inverse** | 0.3 | Low throughput indicates capacity issues |\n\n### Health Levels\n\n| Level | Score Range | Indicator | Action |\n|-------|-------------|-----------|--------|\n| **Critical** | 0.0 – 0.4 | 🔴 | Immediate attention required |\n| **Warning** | 0.4 – 0.7 | 🟡 | Monitor closely |\n| **Healthy** | 0.7 – 1.0 | 🟢 | On track |\n\n### Robot Commands for Label Analysis\n\n**`--robot-label-health`**: Per-label health metrics\n```bash\nbv --robot-label-health\nbv --robot-label-health | jq '.results.labels[] | select(.health_level == \"critical\")'\n```\n\n**`--robot-label-flow`**: Cross-label dependency flow matrix\n```bash\nbv --robot-label-flow\nbv --robot-label-flow | jq '.flow.bottleneck_labels'\n```\n\n**`--robot-label-attention`**: Attention-ranked labels for prioritization\n```bash\nbv --robot-label-attention --attention-limit=5\n```\n\n### Label-Scoped Analysis\n\nUse `--label` to scope any robot command to a specific label's subgraph:\n\n```bash\nbv --robot-insights --label api # Graph metrics for api-labeled issues only\nbv --robot-plan --label backend # Execution plan for backend domain\nbv --robot-priority --label auth # Priority recommendations for auth work\n```\n\nThis enables **domain isolation**: analyze and plan within a bounded context rather than the entire project graph.\n\n### Flow Matrix: Cross-Label Dependencies\n\nThe flow matrix reveals how labels depend on each other:\n\n```\n → api → auth → ui → docs\napi - 3 2 0\nauth 1 - 0 1\nui 4 2 - 0\ndocs 0 0 0 -\n```\n\nRead as: \"api has 3 issues that depend on auth issues.\" High values indicate coupling between domains; the `bottleneck_labels` field highlights labels that block the most cross-domain work.\n\n---\n\n## 🌐 Static Site Export: Shareable Dashboards\n\n`bv` can generate **self-contained static websites** for sharing project status with stakeholders who don't have terminal access.\n\n### Interactive Wizard\n\n```bash\nbv --pages\n```\n\nLaunches an interactive wizard that guides you through:\n1. **Export**: Generate the static bundle\n2. **Preview**: Local server at `http:\u002F\u002Flocalhost:9000` (or next available port)\n3. **Deploy**: Push to GitHub Pages with automatic repository creation\n\n### Direct Export\n\n```bash\nbv --export-pages .\u002Fbv-pages # Export to directory\nbv --export-pages .\u002Fbv-pages --pages-title \"Sprint 42 Status\"\nbv --export-pages .\u002Fbv-pages --pages-exclude-closed # Omit closed issues\nbv --export-pages .\u002Fbv-pages --pages-exclude-history # Omit git history\n\n# Preview an existing bundle without regenerating\nbv --preview-pages .\u002Fbv-pages # Serve at localhost:9000 (or next available port)\n```\n\n### Optional: Hybrid Search WASM Scorer\n\nFor very large datasets, you can build an optional WASM scorer used by the static viewer.\n\n```bash\n# Build once (requires wasm-pack)\n.\u002Fscripts\u002Fbuild_hybrid_wasm.sh\n\n# Or build during export\nBV_BUILD_HYBRID_WASM=1 bv --export-pages .\u002Fbv-pages\n```\n\nIf the `wasm\u002F` assets are missing, the viewer automatically falls back to the JS scorer.\n\n### What Gets Generated\n\n```\n.\u002Fbv-pages\u002F\n├── index.html # Main dashboard with Alpine.js + Tailwind\n├── beads.sqlite3 # Full SQLite database (~2MB for 400+ issues)\n├── data\u002F\n│ ├── graph_layout.json # Pre-computed positions + metrics (~82KB)\n│ ├── meta.json # Export metadata\n│ ├── triage.json # Triage recommendations\n│ └── history.json # Bead-commit correlation data\n└── vendor\u002F\n ├── d3.v7.min.js # Visualization library\n ├── force-graph.min.js # Graph rendering\n └── bv_graph.js # WASM graph engine\n```\n\n### Graph Visualization: 16x Faster Render\n\nThe export uses a **hybrid architecture** for instant graph loading:\n\n| Component | Size | Purpose |\n|-----------|------|---------|\n| `graph_layout.json` | ~82KB | Pre-computed node positions + graph metrics |\n| `beads.sqlite3` | ~2MB | Full issue data for detail pane, search, tables |\n\n**How it works:**\n1. Browser loads tiny `graph_layout.json` first (~100ms over broadband)\n2. Graph renders instantly with pre-computed `fx`\u002F`fy` fixed positions\n3. SQLite loads in parallel for search and detail functionality\n4. Force simulation is completely bypassed—no jittering, no layout delay\n\n**Performance comparison:**\n\n| Metric | Without Pre-compute | With Pre-compute |\n|--------|---------------------|------------------|\n| Initial load | 4+ seconds | ~250ms |\n| Force simulation | 2+ seconds | 0ms (skipped) |\n| Graph data | 914KB (redundant) | 82KB (compact) |\n\n### Detail Pane\n\nClick any node to open a **400px sliding detail pane**:\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│ │ ╭─────────────────────────╮ │\n│ │ │ BV-123: Auth refactor │ │\n│ [Interactive Graph] │ │ ─────────────────────── │ │\n│ │ │ Priority: P1 (High) │ │\n│ ⬤ │ │ Type: Feature │ │\n│ \u002F│\\ │ │ Status: In Progress │ │\n│ \u002F │ \\ │ │ │ │\n│ ⬤ ⬤ ⬤ │ │ **Description** │ │\n│ │ │ Refactor auth module... │ │\n│ │ │ │ │\n│ │ │ ⛔ 3 blockers │ │\n│ │ │ 📤 blocks 5 issues │ │\n│ │ ╰─────────────────────────╯ │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n**Detail pane includes:**\n- Full issue title and description (markdown rendered)\n- Priority, type, status with visual indicators\n- **Blockers count** (\"⛔ 3 blockers\")—issues that must complete first\n- **Blocks count** (\"📤 blocks 5 issues\")—downstream work waiting on this\n- PageRank, betweenness metrics (from pre-computed data)\n\n### Features\n\n- **Full-Text Search**: SQLite FTS5 powers instant search across all issue titles and descriptions. Results appear as you type—no server required.\n- **Interactive Graph**: Visualize dependencies with D3.js force-graph, featuring zoom, pan, and node selection\n- **Detail Pane**: Click any node to see full issue details with dependency info\n- **Triage View**: Same recommendations as `--robot-triage`\n- **Offline Support**: Works without network after initial load\n- **Mobile Responsive**: Adapts to phone\u002Ftablet screens with touch-friendly interactions\n\n### Technical Notes\n\nThe static export uses a **hybrid architecture** combining:\n\n1. **Pure-Go SQLite** ([modernc.org\u002Fsqlite](https:\u002F\u002Fmodernc.org\u002Fsqlite)):\n - No C compiler required—works on any system without CGO\n - Cross-platform bundle generation\n - FTS5 full-text search built-in\n\n2. **Pre-computed Graph Layout**:\n - BFS hierarchical layout with depth-based X positioning\n - Node positions stored as `[x, y]` pairs\n - Metrics stored as compact 5-element arrays: `[pagerank, betweenness, inDegree, outDegree, inCycle]`\n - ~91% size reduction vs. full graph JSON\n\n3. **WASM Graph Engine** (`bv_graph.js`):\n - Client-side cycle detection\n - Efficient neighbor lookups\n - Path finding for blocker chains\n\n### Deployment Options\n\n| Platform | Command | Notes |\n|----------|---------|-------|\n| **GitHub Pages** | `bv --pages` (wizard) | Auto-creates `gh-pages` branch |\n| **Cloudflare Pages** | `bv --export-pages .\u002Fdist` + CF dashboard | Connect to git repo |\n| **Any Static Host** | `bv --export-pages .\u002Fdist` | Netlify, Vercel, S3, etc. |\n\n---\n\n## 🚨 Alerts System: Proactive Health Monitoring\n\nThe Alerts System surfaces potential problems before they become blockers. It combines **drift detection** (changes from baseline) with **proactive analysis** (pattern-based warnings).\n\n### Alert Types\n\n| Type | Trigger | Severity | Example |\n|------|---------|----------|---------|\n| `stale_issue` | No updates in 30+ days | Warning | \"BV-123 hasn't been touched since Oct 15\" |\n| `blocking_cascade` | Issue blocks 5+ others | Critical | \"AUTH-001 is blocking 8 downstream tasks\" |\n| `priority_mismatch` | Low priority but high PageRank | Warning | \"BV-456 has P3 but ranks #2 in PageRank\" |\n| `cycle_introduced` | New circular dependency | Critical | \"Cycle detected: A → B → C → A\" |\n| `scope_creep` | 20%+ increase in open issues | Info | \"Open issues grew from 45 to 58 this week\" |\n\n### TUI Integration\n\nPress `!` to open the **Alerts Panel**:\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ 🚨 ALERTS (3 active) [!] close │\n├─────────────────────────────────────────────────────────────┤\n│ ⚠️ WARNING: bv-123 stale for 45 days │\n│ 🔴 CRITICAL: bv-456 blocks 8 tasks (cascade risk) │\n│ ℹ️ INFO: Open issues increased 23% this sprint │\n├─────────────────────────────────────────────────────────────┤\n│ j\u002Fk navigate • Enter jump to issue • d dismiss • q close │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### Robot Integration\n\n```bash\n# Get all alerts as JSON\nbv --robot-alerts\n\n# Filter by severity (info, warning, critical)\nbv --robot-alerts --severity=critical\n\n# Filter by type\nbv --robot-alerts --alert-type=blocking_cascade\n\n# Filter by affected label\nbv --robot-alerts --alert-label=backend\n```\n\n### Output Schema\n\n```json\n{\n \"alerts\": [\n {\n \"type\": \"blocking_cascade\",\n \"severity\": \"critical\",\n \"issue_id\": \"bv-456\",\n \"message\": \"Blocks 8 downstream tasks\",\n \"blocked_ids\": [\"bv-101\", \"bv-102\", \"...\"],\n \"suggested_action\": \"Prioritize completion or break into smaller tasks\"\n }\n ],\n \"summary\": {\n \"total\": 3,\n \"critical\": 1,\n \"warning\": 1,\n \"info\": 1\n }\n}\n```\n\n---\n\n## 🤖 Complete CLI Reference\n\nBeyond the interactive TUI, `bv` provides a comprehensive **command-line interface** for scripting, automation, and AI agent integration.\n\n### Core Commands\n\n```bash\nbv # Launch interactive TUI\nbv --help # Show all options\nbv --version # Show version\n```\n\n### Robot Protocol Commands\n\nThese commands output **structured JSON** designed for programmatic consumption:\n\n| Command | Output | Use Case |\n|---------|--------|----------|\n| `--robot-triage` | **THE MEGA-COMMAND**: unified triage with all analysis | Single entry point for agents |\n| `--robot-next` | Single top recommendation + claim command | Quick \"what's next?\" answer |\n| `--robot-insights` | Graph metrics + top N lists | Project health assessment |\n| `--robot-plan` | Actionable tracks + dependencies | Work queue generation |\n| `--robot-priority` | Priority recommendations | Automated priority fixing |\n| `--robot-history` | Bead-to-commit correlations | Code change tracking |\n| `--robot-label-health` | Per-label health metrics | Domain health monitoring |\n| `--robot-label-flow` | Cross-label dependency matrix | Inter-domain analysis |\n| `--robot-label-attention` | Attention-ranked labels | Domain prioritization |\n| `--robot-sprint-list` | All sprints as JSON | Sprint planning |\n| `--robot-burndown` | Sprint burndown data | Progress tracking |\n| `--robot-suggest` | Hygiene suggestions (deps\u002Fdupes\u002Flabels\u002Fcycles) | Project cleanup automation |\n| `--robot-diff` | JSON diff (with `--diff-since`) | Change tracking |\n| `--robot-recipes` | Available recipe list | Recipe discovery |\n| `--robot-graph` | Dependency graph as JSON\u002FDOT\u002FMermaid | Graph visualization & export |\n| `--robot-forecast` | ETA predictions per issue | Completion timeline estimates |\n| `--robot-capacity` | Team capacity simulation | Resource planning |\n| `--robot-alerts` | Drift + proactive warnings | Health monitoring |\n| `--robot-help` | Detailed AI agent documentation | Agent onboarding |\n\nAll robot commands support `--as-of \u003Cref>` for historical analysis. Output includes `as_of` and `as_of_commit` metadata fields when specified.\n\n### Time-Travel Commands\n\nThe `--as-of` flag lets you view project state at any historical point without modifying your working tree. It works with both the interactive TUI and all robot commands.\n\n```bash\n# View historical state (TUI)\nbv --as-of HEAD~10 # 10 commits ago\nbv --as-of v1.0.0 # At release tag\nbv --as-of 2024-01-15 # At specific date\nbv --as-of main@{2024-01-15} # Branch at date\n\n# Historical analysis with robot commands\nbv --robot-insights --as-of HEAD~30 # Graph metrics from 30 commits ago\nbv --robot-plan --as-of v1.0.0 # Execution plan at release\nbv --robot-triage --as-of 2024-06-01 # Full triage from specific date\nbv --robot-priority --as-of HEAD~5 # Priority recs from 5 commits ago\n\n# Compare changes\nbv --diff-since HEAD~5 # Changes in last 5 commits\nbv --diff-since v1.0.0 # Changes since release\nbv --diff-since 2024-01-01 # Changes since date\n\n# JSON diff output (combines --as-of for \"to\" snapshot)\nbv --diff-since HEAD~10 --robot-diff # From HEAD~10 to current\nbv --diff-since HEAD~10 --as-of HEAD~5 --robot-diff # From HEAD~10 to HEAD~5\n```\n\nWhen using `--as-of` with robot commands, the JSON output includes additional metadata:\n- `as_of`: The ref you specified (e.g., \"HEAD~30\", \"v1.0.0\")\n- `as_of_commit`: The resolved commit SHA for reproducibility\n\n### Recipe Commands\n\n```bash\n# List available recipes\nbv --robot-recipes\n\n# Apply built-in recipes\nbv --recipe actionable # Ready to work\nbv --recipe high-impact # Top PageRank scores\nbv --recipe stale # Untouched 30+ days\nbv --recipe blocked # Waiting on dependencies\nbv -r recent # Short flag, updated in 7 days\n\n# Apply custom recipe\nbv --recipe .beads\u002Frecipes\u002Fsprint.yaml\n```\n\n### Export Commands\n\n```bash\n# Generate Markdown report with Mermaid diagrams\nbv --export-md report.md\n\n# Export priority brief (focused summary)\nbv --priority-brief brief.md\n\n# Export complete agent brief bundle\nbv --agent-brief .\u002Fagent-bundle\u002F\n# Creates: triage.json, insights.json, brief.md, helpers.md\n```\n\n### ETA Forecasting & Capacity Planning\n\n```bash\n# Forecast completion ETA for a specific issue\nbv --robot-forecast bv-123\n\n# Forecast all open issues with filtering\nbv --robot-forecast all --forecast-label=backend\nbv --robot-forecast all --forecast-sprint=sprint-1\nbv --robot-forecast all --forecast-agents=2 # Multi-agent parallelism\n\n# Capacity simulation: when will everything be done?\nbv --robot-capacity # Default: 1 agent\nbv --robot-capacity --agents=3 # 3 parallel agents\nbv --robot-capacity --capacity-label=frontend # Scoped to label\n```\n\n### Alerts & Health Monitoring\n\n```bash\n# Get all alerts (drift warnings + proactive health checks)\nbv --robot-alerts\n\n# Filter by severity\nbv --robot-alerts --severity=critical\nbv --robot-alerts --severity=warning\n\n# Filter by alert type\nbv --robot-alerts --alert-type=stale_issue\nbv --robot-alerts --alert-type=blocking_cascade\n\n# Filter by label scope\nbv --robot-alerts --alert-label=backend\n```\n\n### Triage Grouping (Multi-Agent Coordination)\n\n```bash\n# Group recommendations by execution track (parallel work streams)\nbv --robot-triage --robot-triage-by-track\n\n# Group recommendations by label (domain-focused agents)\nbv --robot-triage --robot-triage-by-label\n```\n\n### Shell Script Emission\n\nGenerate executable shell scripts from recommendations for automated workflows:\n\n```bash\n# Emit bash script for top 5 recommendations\nbv --robot-triage --emit-script --script-limit=5\n\n# Different shell formats\nbv --robot-triage --emit-script --script-format=fish\nbv --robot-triage --emit-script --script-format=zsh\n```\n\n### Feedback System (Adaptive Recommendations)\n\nThe feedback system learns from your accept\u002Fignore decisions to tune recommendation weights:\n\n```bash\n# Record positive feedback (you worked on this recommendation)\nbv --feedback-accept bv-123\n\n# Record negative feedback (you skipped this recommendation)\nbv --feedback-ignore bv-456\n\n# View current feedback state and weight adjustments\nbv --feedback-show\n\n# Reset feedback to defaults\nbv --feedback-reset\n```\n\n### Baseline & Drift Detection\n\n```bash\n# Save current state as baseline\nbv --save-baseline \"Pre-release v2.0\"\n\n# Show baseline information\nbv --baseline-info\n\n# Check for drift from baseline\nbv --check-drift # Exit codes: 0=OK, 1=critical, 2=warning\nbv --check-drift --robot-drift # JSON output\n```\n\n### Semantic Search\n\n```bash\n# Semantic vector search over titles\u002Fdescriptions\nbv --search \"login oauth\"\n\n# JSON output for automation\nbv --search \"login oauth\" --robot-search\n\n# Hybrid search (text + graph metrics)\nbv --search \"login oauth\" --search-mode hybrid --search-preset impact-first\n\n# Hybrid with custom weights\nbv --search \"login oauth\" --search-mode hybrid \\\n --search-weights '{\"text\":0.4,\"pagerank\":0.2,\"status\":0.15,\"impact\":0.1,\"priority\":0.1,\"recency\":0.05}'\n```\n\nSemantic search builds a lightweight vector index from a weighted issue document (ID and title repeated, labels and description included). This keeps lookup fast while still behaving like a human-readable search.\n\nHybrid mode is a two-stage pipeline: it first retrieves the top candidates by semantic similarity, then re-ranks those candidates using graph-aware signals (PageRank, status, impact, priority, recency). That keeps results anchored to your query while surfacing items that matter most in the dependency graph—a good fit for bv’s goal of making the “why this matters” visible.\n\nShort, intent-heavy queries (e.g., “benchmarks”, “oauth”) are treated differently on purpose. bv widens the candidate pool, boosts literal matches, and raises the text weight so quick lookups behave like a precise search. Longer, descriptive queries lean more on graph signals for smart tie‑breaking and prioritization.\n\nHybrid defaults can be set via:\n- `BV_SEARCH_MODE` (text|hybrid)\n- `BV_SEARCH_PRESET` (default|bug-hunting|sprint-planning|impact-first|text-only)\n- `BV_SEARCH_WEIGHTS` (JSON string, overrides preset)\n\nIn `--robot-search` JSON, hybrid results include `mode`, `preset`, `weights`, plus per-result `text_score` and `component_scores`.\n\n### Example: AI Agent Workflow\n\n```bash\n#!\u002Fbin\u002Fbash\n# agent-workflow.sh - Autonomous task selection\n\n# 1. Get the execution plan\nPLAN=$(bv --robot-plan)\n\n# 2. Extract highest-impact actionable task\nTASK=$(echo \"$PLAN\" | jq -r '.plan.summary.highest_impact')\n\n# 3. Get full insights for context\nINSIGHTS=$(bv --robot-insights)\n\n# 4. Check if completing this introduces regressions\nBASELINE=$(bv --diff-since HEAD~1 --robot-diff)\n\necho \"Working on: $TASK\"\necho \"Unblocks: $(echo \"$PLAN\" | jq '.plan.summary.unblocks_count') tasks\"\n```\n\n### Output Examples\n\n**`--robot-priority` Output:**\n```json\n{\n \"generated_at\": \"2025-01-15T10:30:00Z\",\n \"recommendations\": [\n {\n \"issue_id\": \"CORE-123\",\n \"current_priority\": 3,\n \"suggested_priority\": 1,\n \"confidence\": 0.87,\n \"direction\": \"increase\",\n \"reasoning\": \"High PageRank (0.15) + High Betweenness (0.45) indicates foundational blocker\"\n }\n ],\n \"summary\": {\n \"total_issues\": 58,\n \"recommendations\": 12,\n \"high_confidence\": 5\n }\n}\n```\n\n**`--robot-recipes` Output:**\n```json\n{\n \"recipes\": [\n { \"name\": \"actionable\", \"description\": \"Ready to work (no blockers)\", \"source\": \"builtin\" },\n { \"name\": \"high-impact\", \"description\": \"Top PageRank scores\", \"source\": \"builtin\" },\n { \"name\": \"sprint-review\", \"description\": \"Current sprint issues\", \"source\": \"project\" }\n ]\n}\n```\n\n---\n\n## 🏢 Multi-Repository Workspace Support\n\nFor monorepo and multi-package architectures, `bv` provides **workspace configuration** that unifies issues across multiple repositories into a single coherent view.\n\n### Workspace Configuration (`.bv\u002Fworkspace.yaml`)\n\n```yaml\n# .bv\u002Fworkspace.yaml - Multi-repo workspace definition\nname: my-workspace\n\nrepos:\n - name: api\n path: services\u002Fapi\n prefix: \"api-\" # Issues become api-AUTH-123\n beads_path: .beads # Optional per-repo override (defaults to .beads)\n\n - name: web\n path: apps\u002Fweb\n prefix: \"web-\" # Issues become web-UI-456\n\n - name: shared\n path: packages\u002Fshared\n prefix: \"lib-\" # Issues become lib-UTIL-789\n\ndiscovery:\n enabled: true\n patterns:\n - \"*\" # Direct children\n - \"packages\u002F*\" # npm\u002Fpnpm workspaces\n - \"apps\u002F*\" # Next.js\u002FTurborepo\n - \"services\u002F*\" # Microservices\n - \"libs\u002F*\" # Library packages\n exclude:\n - node_modules\n - vendor\n - .git\n max_depth: 2\n\ndefaults:\n beads_path: .beads # Where to find beads.jsonl in each repo\n```\n\n### ID Namespacing\n\nWhen working across repositories, issues are automatically namespaced:\n\n| Local ID | Repo Prefix | Namespaced ID |\n|----------|-------------|---------------|\n| `AUTH-123` | `api-` | `api-AUTH-123` |\n| `UI-456` | `web-` | `web-UI-456` |\n| `UTIL-789` | `lib-` | `lib-UTIL-789` |\n\n### Cross-Repository Dependencies\n\nThe workspace system enables **cross-repo blocking relationships**:\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ web-UI-456 (apps\u002Fweb) │\n│ \"Implement OAuth login page\" │\n│ │\n│ blocks: api-AUTH-123, lib-UTIL-789 │\n└─────────────────────────────────────────────────────────┘\n │ │\n ▼ ▼\n┌─────────────────┐ ┌─────────────────┐\n│ api-AUTH-123 │ │ lib-UTIL-789 │\n│ (services\u002Fapi) │ │ (packages\u002Flib) │\n│ \"Auth endpoint\" │ │ \"Token utils\" │\n└─────────────────┘ └─────────────────┘\n```\n\n### Filtering Within a Workspace\n\nUse `--repo` to scope the view (and robot outputs) to a specific repository prefix. Matching is case-insensitive and accepts common separators (`-`, `:`, `_`); it also honors the `source_repo` field when present.\n\n### Supported Monorepo Layouts\n\n| Layout | Pattern | Example Projects |\n|--------|---------|------------------|\n| **npm\u002Fpnpm workspaces** | `packages\u002F*` | Lerna, Turborepo |\n| **Next.js apps** | `apps\u002F*` | Vercel monorepos |\n| **Microservices** | `services\u002F*` | Backend platforms |\n| **Go modules** | `modules\u002F*` | Multi-module Go |\n| **Flat** | `*` | Simple monorepos |\n\n### ID Resolution\n\nThe `IDResolver` handles cross-repo references intelligently:\n\n```go\nresolver := NewIDResolver(config, \"api\")\n\n\u002F\u002F From api repo context:\nresolver.Resolve(\"AUTH-123\") \u002F\u002F → {Namespace: \"api-\", LocalID: \"AUTH-123\"}\nresolver.Resolve(\"web-UI-456\") \u002F\u002F → {Namespace: \"web-\", LocalID: \"UI-456\"}\nresolver.IsCrossRepo(\"web-UI-456\") \u002F\u002F → true\nresolver.DisplayID(\"api-AUTH-123\") \u002F\u002F → \"AUTH-123\" (local, strip prefix)\nresolver.DisplayID(\"web-UI-456\") \u002F\u002F → \"web-UI-456\" (cross-repo, keep prefix)\n```\n\n---\n\n## ⏰ Interactive Time-Travel Mode\n\nBeyond CLI diff commands, `bv` supports **interactive time-travel** within the TUI itself. This mode overlays diff badges on your issue list, letting you visually explore what changed.\n\n### Activating Time-Travel Mode\n\nPress `t` in the main list view to enter time-travel mode with a custom revision prompt:\n\n```\n┌──────────────────────────────────────────┐\n│ ⏱️ Time-Travel Mode │\n│ │\n│ Compare current state with a │\n│ historical revision │\n│ │\n│ ⏱️ Revision: HEAD~5█ │\n│ │\n│ Examples: HEAD~5, main, v1.0.0, │\n│ 2024-01-01, abc123 │\n│ │\n│ Press Enter to compare, Esc to cancel │\n└──────────────────────────────────────────┘\n```\n\nFor quick access, press `T` (uppercase) to instantly compare against `HEAD~5` without the prompt.\n\n### Diff Badges\n\nOnce activated, issues display visual badges indicating their diff status:\n\n| Badge | Meaning | Color |\n|-------|---------|-------|\n| `[NEW]` | Issue created since baseline | Green |\n| `[CLOSED]` | Issue closed since baseline | Gray |\n| `[MODIFIED]` | Issue fields changed | Yellow |\n| `[REOPENED]` | Issue reopened since baseline | Orange |\n\n### Visual Example\n\n```\n┌────────────────────────────────────────────────────────────┐\n│ 📋 ISSUES (since HEAD~5) 58 total │\n├────────────────────────────────────────────────────────────┤\n│ [NEW] ✨ FEAT-789 Add dark mode toggle P2 🟢 │\n│ [NEW] 🐛 BUG-456 Fix login race condition P1 🟢 │\n│ [MODIFIED] 📝 TASK-123 Update documentation P3 🟡 │\n│ ✨ FEAT-100 OAuth integration P1 🟢 │\n│ [CLOSED] 🐛 BUG-001 Memory leak in parser P0 ⚫ │\n└────────────────────────────────────────────────────────────┘\n```\n\n### Time-Travel Summary Panel\n\nThe footer shows aggregate statistics:\n\n```\n─────────────────────────────────────────────────────────────\n📊 Changes: +3 new ✓2 closed ~1 modified ↺0 reopened\nHealth: ↑ improving (density: -0.02, cycles: -1)\n─────────────────────────────────────────────────────────────\n```\n\n### Time-Travel Navigation\n\n| Key | Action |\n|-----|--------|\n| `t` | Enter time-travel (custom revision prompt) |\n| `T` | Quick time-travel (HEAD~5) |\n| `t` (while in time-travel) | Exit time-travel mode |\n| `n` | Jump to next changed issue |\n| `N` | Jump to previous changed issue |\n\n---\n\n## 🧪 Quality Assurance & Robustness\n\nTrust is earned. `bv` employs a rigorous testing strategy to ensure it can handle the messy reality of real-world repositories.\n\n### 1. Synthetic Data Fuzzing\nWe don't just test on \"happy path\" data. The test suite (`pkg\u002Floader\u002Fsynthetic_test.go`) generates **Synthetic Complex Graphs**—large JSONL files with thousands of nodes, intricate dependency cycles, and edge-case UTF-8 characters—to verify that the graph engine and rendering logic never panic under load.\n\n### 2. Robustness Against Corruption\nIn a git-based workflow, merge conflicts and partial writes happen. The `TestLoadIssuesRobustness` suite explicitly injects garbage lines and corrupted JSON into the data stream.\n* **Result:** `bv` detects corruption, logs a warning to `stderr`, and continues loading the valid data. It never crashes the user session due to a single bad line.\n\n### Contributing Tests\nFor contributors writing tests, see the comprehensive **[Testing Guide](docs\u002Ftesting.md)** which covers:\n- Test philosophy (no mocks, table-driven tests, golden files)\n- Using the `testutil` package for fixture generation\n- Running tests, coverage, and benchmarks\n- E2E test patterns and CI integration\n\n---\n\n## 🔄 The Zero-Friction Update Engine\n\n`bv` includes a proactive, non-intrusive update check to ensure you never miss a feature. We believe tools should maintain themselves without interrupting your flow.\n\n### Design & Implementation\nThe updater (`pkg\u002Fupdater\u002Fupdater.go`) is architected for silence and safety:\n1. **Non-Blocking Concurrency:** The check runs in a detached goroutine with a strict **2-second timeout**. It never delays your startup time or UI interactivity.\n2. **Semantic Versioning:** It doesn't just match strings. A custom SemVer comparator ensures you are only notified about strictly *newer* releases, handling complex edge cases like release candidates vs. stable builds.\n3. **Resilience:** It gracefully handles network partitions, GitHub API rate limits (403\u002F429), and timeouts by silently failing. You will never see a crash or error log due to an update check.\n4. **Unobtrusive Notification:** When an update is found, `bv` doesn't pop a modal. It simply renders a subtle **Update Available** indicator (`⭐`) in the footer, letting you choose when to upgrade.\n\n---\n\n## 🗂️ Data Loading & Self-Healing\n\nReliability is key. `bv` doesn't assume a perfect environment; it actively handles common file system inconsistencies.\n\n### 1. Intelligent Path Discovery\nThe loader (`pkg\u002Floader\u002Floader.go`) doesn't just blindly open `.beads\u002Fbeads.jsonl`. It employs a priority-based discovery algorithm:\n1. **Canonical:** Checks for `issues.jsonl` (preferred by beads upstream).\n2. **Legacy:** Fallback to `beads.jsonl` for backward compatibility.\n3. **Base:** Checks `beads.base.jsonl` (used by `br` in daemon mode).\n4. **Validation:** It skips temporary files like `*.backup` or `deletions.jsonl` to prevent displaying corrupted state.\n\n### 2. Robust Parsing\nThe JSONL parser is designed to be **Lossy-Tolerant**.\n* It uses a buffered scanner (`bufio.NewScanner`) with a generous 10MB line limit to handle massive description blobs.\n* Malformed lines (e.g., from a merge conflict) are skipped with a warning rather than crashing the application, ensuring you can still view the readable parts of your project even during a bad git merge.\n\n---\n\n## 🧩 Design Philosophy: Why Graphs?\n\nTraditional issue trackers (Jira, GitHub Issues, Trello) model work as **Buckets**: \"To Do\", \"In Progress\", \"Done\". This is fine for simple task lists, but it fails at scale because it ignores **Structure**.\n\nIn complex software projects, tasks are not isolated. They are deeply interconnected. A \"simple\" frontend task might depend on a backend endpoint, which depends on a schema change, which depends on a migration script.\n\n`bv` adopts a **Graph-First** philosophy:\n1. **Structure is Reality:** The dependency graph *is* the project. The list view is just a projection of that graph.\n2. **Explicit Blocking:** We don't just \"relate\" tasks; we define strict \"blocks\". If A blocks B, you literally cannot mark B as \"Ready\" in `bv` until A is Closed.\n3. **Local-First, Text-Based:** Your project data lives in your repo (`.beads\u002Fbeads.jsonl`), not on a remote server. It travels with your code, branches with your git, and merges with your PRs.\n\n---\n\n## ⚡ Performance Specs\n\n`bv` is engineered for speed. We believe that latency is the enemy of flow.\n\n* **Startup Time:** \u003C 50ms for typical repos (\u003C 1000 issues).\n* **Rendering:** 60 FPS UI updates using [Bubble Tea](https:\u002F\u002Fgithub.com\u002Fcharmbracelet\u002Fbubbletea).\n* **Virtualization:** List views and Markdown renderers are fully windowed. `bv` can handle repositories with **10,000+ issues** without UI lag, consuming minimal RAM.\n* **Graph Compute:** A two-phase analyzer computes topo\u002Fdegree\u002Fdensity instantly, then PageRank\u002FBetweenness\u002FHITS\u002FCritical Path\u002FCycles asynchronously with size-aware timeouts.\n* **Caching:** Repeated analyses reuse hashed results automatically, avoiding recomputation when the bead graph hasn’t changed.\n\n### Performance Benchmarking\n\n`bv` includes a comprehensive benchmark suite for performance validation:\n\n```bash\n# Run all benchmarks\n.\u002Fscripts\u002Fbenchmark.sh\n\n# Save current performance as baseline\n.\u002Fscripts\u002Fbenchmark.sh baseline\n\n# Compare against baseline (requires benchstat)\n.\u002Fscripts\u002Fbenchmark.sh compare\n\n# Quick benchmarks (CI mode)\n.\u002Fscripts\u002Fbenchmark.sh quick\n```\n\n**Benchmark Categories:**\n- **Full Analysis**: End-to-end `Analyze()` pipeline at various scales\n- **Individual Algorithms**: PageRank, Betweenness, HITS, TopoSort isolation\n- **Pathological Graphs**: Stress tests for timeout protection (many cycles, complete graphs)\n- **Timeout Verification**: Ensures large graphs don't hang\n\n**Timeout Protection:**\nAll expensive algorithms (Betweenness, PageRank, HITS, Cycle detection) have 500ms timeouts to prevent blocking on large or pathological graphs.\n\n**Detailed Tuning Guide:**\nFor comprehensive performance documentation including troubleshooting, size-based algorithm selection, and tuning options, see [docs\u002Fperformance.md](docs\u002Fperformance.md).\n\n### Graph Engine Optimization\n\nThe analysis engine uses a **compact adjacency-list graph** (`compactDirectedGraph`) instead of the standard Gonum map-backed implementation. This optimization delivers significant performance improvements:\n\n| Benchmark (696 issues) | Before | After | Improvement |\n|------------------------|--------|-------|-------------|\n| Full Triage | 67ms | 1.3ms | **52× faster** |\n| Full Analysis | 46ms | 477μs | **96× faster** |\n| Graph Build | 1.2ms | 323μs | **3.7× faster** |\n| Memory (Graph Build) | 735KB | 444KB | **40% less** |\n| Allocations | 4,647 | 2,512 | **46% fewer** |\n\n**Why it matters:** The default Gonum `DirectedGraph` uses map-backed edge sets, which cause heavy allocations during graph construction. Our compact implementation:\n- Pre-allocates node arrays at known size\n- Uses `[]int64` adjacency lists instead of `map[int64]set`\n- Eliminates map grow\u002Frehash overhead entirely\n\n**Real-data benchmarks:** Run `go test -bench=BenchmarkRealData .\u002Fpkg\u002Fanalysis\u002F...` to validate performance against your project's actual `.beads\u002Fissues.jsonl` data.\n\n---\n\n## ❓ Troubleshooting & FAQ\n\n**Q: My icons look weird \u002F text is misaligned.**\n* `bv` requires a terminal with **TrueColor** support and a **Nerd Font** installed.\n* *Recommended:* [Nerd Fonts](https:\u002F\u002Fwww.nerdfonts.com\u002F) (e.g., \"JetBrains Mono Nerd Font\" or \"Hack Nerd Font\").\n* *Terminals:* Windows Terminal, iTerm2, Alacritty, Kitty, WezTerm.\n\n**Q: Live reload isn’t updating (especially on NFS\u002FSMB\u002FSSHFS\u002FFUSE).**\n* Some filesystems don’t reliably deliver filesystem events. `bv` will try to auto-detect this and switch to polling.\n* If it still misbehaves, force polling:\n ```bash\n BV_FORCE_POLLING=1 bv\n # or\n BV_FORCE_POLL=1 bv\n ```\n\n**Q: I see `polling …` in the footer. Is that bad?**\nNo — it just means `bv` is using polling instead of filesystem events for live reload (common on remote filesystems). Polling can add a small delay before updates appear.\n\n**Q: I see `⚠ STALE` \u002F `✗ bg …` \u002F `⚠ worker unresponsive` \u002F `↻ recovered` in the footer.**\nThese indicators mean the background worker hasn’t produced a fresh snapshot recently (or needed to self-heal). Try `Ctrl+R`\u002F`F5`, check filesystem permissions\u002Fhealth, or temporarily disable background mode (`BV_BACKGROUND_MODE=0`) to fall back to synchronous reload.\n\n**Q: I see \"Cycles Detected\" in the dashboard. What now?**\nA: A cycle (e.g., A → B → A) means your project logic is broken; no task can be finished first. Use the Insights Dashboard (`i`) to find the specific cycle members, then use `br` to remove one of the dependency links (e.g., `br unblock A --from B`).\n\n**Q: Does this work with Jira\u002FGitHub?**\nA: `bv` is data-agnostic. The Beads data schema supports an `external_ref` field. If you populate your `.beads\u002Fbeads.jsonl` file with issues from external trackers (e.g., using a custom script or sync tool), `bv` will render them alongside your local tasks. Future versions of the `br` CLI may support native syncing, but `bv` is ready for that data today.\n\n**Q: What's the difference between \"bead\" and \"issue\"?**\nA: They're the same thing! In the Beads ecosystem, the unit of work is called a \"bead\" (hence the name). However, `bv` uses \"issue\" in many places since that's the more familiar term for most developers. The CLI flags use both interchangeably: `--robot-file-beads`, `--pages-include-closed` (issues), etc. Think of \"bead\" as the Beads-specific term and \"issue\" as the general concept.\n\n---\n\n## 📦 Installation\n\n### One-Line Install (Linux\u002FmacOS)\nThe fastest way to get started. Detects your OS and architecture automatically.\n\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash\n```\n\n### One-Line Install (Windows)\nFor Windows users using PowerShell:\n\n```powershell\nirm \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Fmain\u002Finstall.ps1\" | iex\n```\n\n**Requirements:**\n- Go 1.21+ installed and in your PATH ([download](https:\u002F\u002Fgo.dev\u002Fdl\u002F))\n- For best display, use [Windows Terminal](https:\u002F\u002Faka.ms\u002Fterminal) with a [Nerd Font](https:\u002F\u002Fwww.nerdfonts.com\u002F)\n\n### Build from Source\nRequires Go 1.21+.\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fbeads_viewer.git\ncd beads_viewer\ngo install .\u002Fcmd\u002Fbv\n```\n\n### Nix Flake\nFor Nix users, `bv` provides a flake for reproducible builds and development environments.\n\n```bash\n# Run directly\nnix run github:Dicklesworthstone\u002Fbeads_viewer\n\n# Install to profile\nnix profile install github:Dicklesworthstone\u002Fbeads_viewer\n\n# Development shell with Go toolchain\nnix develop github:Dicklesworthstone\u002Fbeads_viewer\n```\n\nOr add to your flake inputs:\n```nix\n{\n inputs.bv.url = \"github:Dicklesworthstone\u002Fbeads_viewer\";\n # Use: bv.packages.${system}.default\n}\n```\n\n---\n\n## 🚀 Usage Guide\n\nNavigate to any project initialized with `br init` and run:\n\n```bash\nbv\n```\n\n### 🎓 Getting Help\n\nbv has a comprehensive built-in help system:\n\n**Quick Reference** (`?`) - Press anywhere to see keyboard shortcuts for your current view. From here, press `Space` to jump directly to the full tutorial.\n\n**Interactive Tutorial** (`` ` `` backtick) - A multi-page walkthrough covering all features:\n- Concepts: beads, dependencies, labels, priorities\n- Views: list, board, graph, tree, insights, history\n- Workflows: AI agent integration, triage, planning\n- Progress is automatically saved—resume where you left off\n\n### Keyboard Control Map\n\n| Context | Key | Action |\n| :--- | :---: | :--- |\n| **Global Navigation** | `j` \u002F `k` | Next \u002F Previous Item |\n| | `g` \u002F `G` | Jump to Top \u002F Bottom |\n| | `Ctrl+D` \u002F `Ctrl+U` | Page Down \u002F Up |\n| | `Tab` | Switch Focus (List ↔ Details) |\n| | `Enter` | Open \u002F Focus Selection |\n| | `q` \u002F `Esc` | Quit \u002F Back |\n| **Filters** | `o` | Show **Open** Issues |\n| | `r` | Show **Ready** (Unblocked) |\n| | `c` | Show **Closed** Issues |\n| | `a` | Show **All** Issues |\n| | `\u002F` | **Search** (Fuzzy) |\n| | `Ctrl+S` | Toggle **Search Mode** (Semantic ↔ Fuzzy) |\n| | `l` | **Label Picker** (quick filter by label) |\n| **List Sorting** | `s` | Cycle Sort Mode (Default → Created ↑ → Created ↓ → Priority → Updated) |\n| **Views** | `b` | Toggle **Kanban Board** |\n| | `i` | Toggle **Insights Dashboard** |\n| | `g` | Toggle **Graph Visualizer** |\n| | `E` | Toggle **Tree View** (parent-child hierarchy) |\n| | `a` | Toggle **Actionable Plan** |\n| | `h` | Toggle **History View** (bead-to-commit correlation) |\n| | `f` | Toggle **Flow Matrix** (cross-label dependencies) |\n| | `[` | Toggle **Label Dashboard** (label health analytics) |\n| | `]` | Toggle **Attention View** (label attention scores) |\n| **Kanban Board** | `h` \u002F `l` | Move Between Columns |\n| | `j` \u002F `k` | Move Within Column |\n| **Insights Dashboard** | `Tab` | Next Panel |\n| | `Shift+Tab` | Previous Panel |\n| | `e` | Toggle Explanations |\n| | `x` | Toggle Calculation Proof |\n| | `m` | Toggle Heatmap Overlay |\n| **Graph View** | `H` \u002F `L` | Scroll Left \u002F Right |\n| | `Ctrl+D` \u002F `Ctrl+U` | Page Down \u002F Up |\n| **Tree View** | `j` \u002F `k` | Move cursor down \u002F up |\n| | `h` \u002F `l` | Collapse\u002Fparent or Expand\u002Fchild |\n| | `Enter` \u002F `Space` | Toggle expand\u002Fcollapse |\n| | `o` \u002F `O` | Expand all \u002F Collapse all |\n| | `g` \u002F `G` | Jump to top \u002F bottom |\n| **Time-Travel & Analysis** | `t` | Time-Travel Mode (custom revision) |\n| | `T` | Quick Time-Travel (HEAD~5) |\n| | `p` | Toggle Priority Hints Overlay |\n| **Actions** | `x` | Export to Markdown File |\n| | `C` | Copy Issue to Clipboard |\n| | `O` | Open in Editor |\n| **Help & Learning** | `?` | Toggle Help Overlay (keyboard shortcuts) |\n| | `` ` `` | Open Interactive Tutorial (progress saved) |\n| **Global** | `;` | Toggle Shortcuts Sidebar |\n| | `!` | Toggle **Alerts Panel** (proactive warnings) |\n| | `'` | Recipe Picker |\n| | `w` | Repo Picker (workspace mode) |\n\n---\n\n## 🛠️ Configuration\n\n`bv` automatically detects your terminal capabilities to render the best possible UI. It looks for `.beads\u002Fbeads.jsonl` in your current directory.\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `BEADS_DIR` | Custom beads directory path. When set, overrides the default `.beads` directory lookup. | `.beads` in cwd |\n| `BV_BACKGROUND_MODE` | Experimental: enable background snapshot loading for live reload in the TUI (`1`\u002F`0`). | (disabled) |\n| `BV_FORCE_POLLING` | Force polling-based live reload (useful on NFS\u002FSMB\u002FSSHFS\u002FFUSE or any setup where filesystem events are unreliable) (`1`\u002F`0`). | (auto) |\n| `BV_FORCE_POLL` | Alias for `BV_FORCE_POLLING`. | (auto) |\n| `BV_DEBOUNCE_MS` | Debounce window (milliseconds) for live reload events in background mode. | `200` |\n| `BV_CHANNEL_BUFFER` | Background worker message buffer size (worker → UI). | `8` |\n| `BV_HEARTBEAT_INTERVAL_S` | Background worker heartbeat interval (seconds). | `5` |\n| `BV_WATCHDOG_INTERVAL_S` | Background worker watchdog interval (seconds). | `10` |\n| `BV_FRESHNESS_WARN_S` | Snapshot staleness warning threshold (seconds). | `30` |\n| `BV_FRESHNESS_STALE_S` | Snapshot staleness critical threshold (seconds). | `120` |\n| `BV_MAX_LINE_SIZE_MB` | Max JSONL line size in MB (lines larger than this are skipped with a warning). | `10` |\n| `BV_SKIP_PHASE2` | Skip Phase 2 graph metrics (centrality, cycles, critical path) (`1`\u002F`0`). | (disabled) |\n| `BV_PHASE2_TIMEOUT_S` | Override per-metric Phase 2 timeouts (seconds). | (size-based) |\n| `BV_SEMANTIC_EMBEDDER` | Semantic embedding provider for `bv --search` and TUI semantic mode. | `hash` |\n| `BV_SEMANTIC_DIM` | Embedding dimension for semantic search index. | `384` |\n| `BV_SEMANTIC_MODEL` | Provider-specific model name for semantic search (optional). | (empty) |\n\n**Use cases for `BEADS_DIR`:**\n- **Monorepos**: Single beads directory shared across multiple packages\n- **Non-standard layouts**: Projects where `.beads` isn't in the working directory\n- **Testing**: Point to test fixtures without changing directory\n- **Cross-directory access**: View beads from anywhere on the filesystem\n\n```bash\n# Example: Point to a different beads directory\nBEADS_DIR=\u002Fpath\u002Fto\u002Fshared\u002Fbeads bv\n\n# Example: Use in monorepo\nexport BEADS_DIR=$(git rev-parse --show-toplevel)\u002F.beads\n```\n\n### Experimental: Background Mode (Live Reload)\n\nThe TUI can run live reload using an **experimental background snapshot worker** (moves file I\u002FO + analysis off the UI thread).\n\n**Enable (opt-in):**\n```bash\nBV_BACKGROUND_MODE=1 bv\nbv --background-mode\n```\n\n**Disable \u002F rollback:**\n```bash\nBV_BACKGROUND_MODE=0 bv\nbv --no-background-mode\n```\n\n**User config file (when neither CLI flags nor `BV_BACKGROUND_MODE` are set):**\n```yaml\n# ~\u002F.config\u002Fbv\u002Fconfig.yaml\nexperimental:\n background_mode: true\n```\n\n**Precedence:** CLI flags → `BV_BACKGROUND_MODE` → `~\u002F.config\u002Fbv\u002Fconfig.yaml`.\n\n**Migration plan (high level):**\n- Phase A (now): opt-in background mode, sync remains default.\n- Phase B: broaden rollout; keep explicit rollback (`--no-background-mode` \u002F `BV_BACKGROUND_MODE=0`).\n- Phase C: flip default when stable; keep sync as fallback for a period.\n- Phase D: remove legacy sync reload path after deprecation window.\n\n**Monitoring plan:** no automatic telemetry today; rely on CI + regression tests and user reports during Phase A\u002FB.\n\n### Status Indicators (Background Mode + Live Reload)\n\nWhen background mode or live reload is enabled, the footer may display these indicators:\n\n- `◌ metrics…` — Phase 2 metrics are still computing; the UI renders immediately with Phase 1 data.\n- `⚠ 45s ago` — snapshot age warning (data is getting stale).\n- `⚠ STALE: 3m ago` — snapshot is stale.\n- `✗ bg \u003Cphase> (3x)` — background worker hit repeated errors building snapshots (phase shown; retry count in parentheses).\n- `↻ recovered xN` — watchdog recovered the background worker N times (transient failures\u002Fself-healing).\n- `⚠ worker unresponsive` — watchdog detected the worker is stuck and is recovering.\n- `polling …` — live reload is using polling instead of filesystem events (common on remote filesystems); changes may appear with a small delay.\n\nTip: `Ctrl+R` (or `F5`) forces a refresh.\n\n### Visual Theme\nThe UI uses a visually distinct, high-contrast theme inspired by Dracula Principles to ensure readability.\n* **Primary:** `#BD93F9` (Purple)\n* **Status Open:** `#50FA7B` (Green)\n* **Status Blocked:** `#FF5555` (Red)\n\n---\n\n## 📄 License\n\nMIT License (with OpenAI\u002FAnthropic Rider). See [LICENSE](LICENSE).\n\nCopyright (c) 2025 Jeffrey Emanuel\n\n---\n\n## 🤖 Why Robots Love bv\n- Deterministic JSON contracts: robot commands emit stable field names, stable ordering (ties broken by ID), and include `data_hash`, `analysis_config`, and `computed_at` so multiple calls can be correlated safely.\n- Health flags: every expensive metric reports status (`computed`, `approx`, `timeout`, `skipped`) plus elapsed ms and (when sampled) the sample size used.\n- Consistent cache: robot subcommands share the same analyzer\u002Fcache keyed by the issue data hash, avoiding divergent outputs across `--robot-insights`, `--robot-plan`, and `--robot-priority`.\n- Instant + eventual completeness: Phase 1 metrics are available immediately; Phase 2 fills in and the status flags tell you when it is done or if it degraded.\n\n## 🧭 Data Flow at a Glance\n```\n.beads\u002Fbeads.jsonl\n ↓ tolerant loader (BOM strip, 10MB lines, skip malformed)\n ↓ graph builder (blocking deps only)\n ↓ analyzer (Phase 1 fast; Phase 2 centralities with timeouts)\n ↓ cache (hash-keyed)\n ↓ outputs: TUI | robot JSON | exports\u002Fhooks\n```\n- Hash and config travel with every robot payload so downstream consumers can verify consistency.\n\n## 📐 Graph Analysis Algorithms (plain English)\n- PageRank: “blocking authority” — foundational tasks with many (or important) dependents.\n- Betweenness: “bridges” — nodes on many shortest paths; bottlenecks between clusters.\n- HITS: hubs (aggregators) vs authorities (prerequisites).\n- Critical-path depth: longest downstream chain length; zero slack keystones.\n- Eigenvector: influence via influential neighbors.\n- Density, degree, topo sort: structural backbone.\n- Cycles: detected via Tarjan SCC + `DirectedCyclesIn`; capped with timeouts and stored count.\n- Each appears in robot insights with its status flag and, when ready, per-issue scores.\n\n## ⚡ Phase 1 vs Phase 2\n- **Phase 1 (instant):** degree, topo sort, density; always present.\n- **Phase 2 (async):** PageRank, Betweenness, HITS, Eigenvector, Critical Path, Cycles; 500ms defaults with size-based adjustments. Status flag reflects computed\u002Fapprox\u002Ftimeout\u002Fskipped.\n\n## ⏱️ Timeout & Approximation Semantics\n- Per-metric status: `computed` (full), `approx` (e.g., sampled betweenness), `timeout` (fallback), `skipped` (size\u002Fdensity guard).\n- Payload example:\n ```json\n {\n \"status\": {\n \"pagerank\": {\"state\":\"computed\",\"ms\":142},\n \"betweenness\": {\"state\":\"approx\",\"ms\":480,\"sample\":120},\n \"cycles\": {\"state\":\"timeout\",\"ms\":500,\"reason\":\"deadline\"}\n }\n }\n ```\n\n## 🧮 Execution Plan Logic\n- Actionable set: open\u002Fin-progress issues with no open blocking dependencies.\n- Unblocks: for each actionable, list of issues that would become actionable if it closed (no other open blockers).\n- Tracks: undirected connected components group actionable items into parallelizable streams.\n- Summary: highest-impact item = max unblocks, then priority, then ID for determinism.\n\n## 🎯 Priority Recommendation Model\n- Composite score weights: PageRank 30%, Betweenness 30%, blocker ratio 20%, staleness 10%, priority boost 10%.\n- Thresholds: high PR >0.30, high BW >0.50, staleness ~14 days, min confidence 0.30 by default.\n- Direction: “increase” or “decrease” priority derived from score vs current priority; confidence blends signal count, strength, and score delta.\n\n## 🔍 Diff & Time-Travel Safety Notes\n- When stdout is non-TTY or `BV_ROBOT=1`, `--diff-since` auto-emits JSON (or requires `--robot-diff` in strict setups); resolved revision is echoed in the payload.\n- TUI time-travel badges: `[NEW]`, `[CLOSED]`, `[MODIFIED]`, `[REOPENED]`, matching the robot diff summary.\n\n## 🛡️ Performance Guardrails\n- Two-phase analysis with size-aware configs (approx betweenness on large sparse graphs, cycle caps, HITS skipped on dense XL graphs).\n- 500ms default timeouts per expensive metric; results marked with status.\n- Cache TTL keeps repeated robot calls fast on unchanged data; hash mismatch triggers recompute.\n- Bench quick check: `.\u002Fscripts\u002Fbenchmark.sh quick` or diagnostics via `bv --profile-startup`.\n\n## 🧷 Robustness & Self-Healing\n- Loader skips malformed lines with warnings, strips UTF-8 BOM, tolerates large lines (10MB).\n- Beads file discovery order: issues.jsonl → beads.jsonl → beads.base.jsonl; skips backups\u002Fmerge artifacts\u002Fdeletions manifests.\n- Live reload is debounced; update check is non-blocking with graceful failure on network issues.\n\n## 🔗 Integrating with CI & Agents\n- Typical pipeline:\n ```bash\n bv --robot-insights > insights.json\n bv --robot-plan | jq '.plan.summary'\n bv --robot-priority | jq '.recommendations[0]'\n bv --check-drift --robot-drift --diff-since HEAD~5 > drift.json\n ```\n- Use `data_hash` to ensure all artifacts come from the same analysis run; fail CI if hashes diverge.\n- Exit codes: drift check (0 ok, 1 critical, 2 warning).\n\n## 🩺 Troubleshooting Matrix (robot mode)\n- Empty metric maps → Phase 2 still running or timed out; check status flags.\n- Large payloads → use jq to slice top items; re-run after filtering via recipes.\n- Missing cycles → likely skipped\u002Ftimeout; see `status.cycles`.\n- Inconsistent outputs between commands → compare `data_hash`; rerun if different.\n\n## 🔒 Security & Privacy Notes\n- Local-first: all analysis happens on your repo's JSONL; no network required for robots.\n- Hooks and exports are opt-in; update checks are silent and tolerate network failures without impacting startup.\n\n---\n\n## 🙏 Acknowledgments & Credits\n\n`bv` stands on the shoulders of giants. We're deeply grateful to the maintainers and contributors of these exceptional open source projects:\n\n### Foundation\n\n| Project | Author | Description |\n|---------|--------|-------------|\n| [**Beads**](https:\u002F\u002Fgithub.com\u002Fsteveyegge\u002Fbeads) | Steve Yegge | The elegant git-native issue tracking system that `bv` was built to complement |\n\n### Go Libraries (TUI & CLI)\n\n| Library | Author | What We Use It For |\n|---------|--------|-------------------|\n| [**Bubble Tea**](https:\u002F\u002Fgithub.com\u002Fcharmbracelet\u002Fbubbletea) | [Charm](https:\u002F\u002Fcharm.sh) | The Elm-inspired TUI framework powering all interactive views |\n| [**Lip Gloss**](https:\u002F\u002Fgithub.com\u002Fcharmbracelet\u002Flipgloss) | [Charm](https:\u002F\u002Fcharm.sh) | Beautiful terminal styling—colors, borders, layouts |\n| [**Bubbles**](https:\u002F\u002Fgithub.com\u002Fcharmbracelet\u002Fbubbles) | [Charm](https:\u002F\u002Fcharm.sh) | Ready-made components: lists, text inputs, spinners, viewports |\n| [**Huh**](https:\u002F\u002Fgithub.com\u002Fcharmbracelet\u002Fhuh) | [Charm](https:\u002F\u002Fcharm.sh) | Interactive forms and prompts for the deployment wizard |\n| [**Glamour**](https:\u002F\u002Fgithub.com\u002Fcharmbracelet\u002Fglamour) | [Charm](https:\u002F\u002Fcharm.sh) | Markdown rendering with syntax highlighting in terminal |\n| [**modernc.org\u002Fsqlite**](https:\u002F\u002Fmodernc.org\u002Fsqlite) | modernc.org | Pure-Go SQLite with FTS5 full-text search for static site export |\n| [**Gonum**](https:\u002F\u002Fgithub.com\u002Fgonum\u002Fgonum) | Gonum Authors | Graph algorithms: PageRank, betweenness centrality, SCC |\n| [**fsnotify**](https:\u002F\u002Fgithub.com\u002Ffsnotify\u002Ffsnotify) | fsnotify | File system watching for live reload |\n| [**clipboard**](https:\u002F\u002Fgithub.com\u002Fatotto\u002Fclipboard) | atotto | Cross-platform clipboard for copy-to-clipboard features |\n\n### JavaScript Libraries (Static Viewer)\n\n| Library | Author | What We Use It For |\n|---------|--------|-------------------|\n| [**force-graph**](https:\u002F\u002Fgithub.com\u002Fvasturiano\u002Fforce-graph) | [Vasco Asturiano](https:\u002F\u002Fgithub.com\u002Fvasturiano) | Beautiful interactive force-directed graph visualization |\n| [**D3.js**](https:\u002F\u002Fd3js.org\u002F) | Mike Bostock \u002F Observable | Data visualization foundation and graph physics |\n| [**Alpine.js**](https:\u002F\u002Falpinejs.dev\u002F) | Caleb Porzio | Lightweight reactive UI framework |\n| [**sql.js**](https:\u002F\u002Fgithub.com\u002Fsql-js\u002Fsql.js) | sql.js contributors | SQLite compiled to WebAssembly for client-side queries |\n| [**Chart.js**](https:\u002F\u002Fwww.chartjs.org\u002F) | Chart.js contributors | Interactive charts: burndown, priority distribution, heatmaps |\n| [**Mermaid**](https:\u002F\u002Fmermaid.js.org\u002F) | Knut Sveidqvist | Dependency graph diagrams in Markdown |\n| [**DOMPurify**](https:\u002F\u002Fgithub.com\u002Fcure53\u002FDOMPurify) | cure53 | XSS-safe HTML sanitization |\n| [**Marked**](https:\u002F\u002Fmarked.js.org\u002F) | marked contributors | Fast Markdown parsing |\n| [**Tailwind CSS**](https:\u002F\u002Ftailwindcss.com\u002F) | Tailwind Labs | Utility-first CSS framework |\n\n### Special Thanks\n\n- The entire **[Charm](https:\u002F\u002Fcharm.sh)** team for creating the most delightful terminal UI ecosystem in existence. Their libraries make building beautiful CLI tools a joy.\n- **[Vasco Asturiano](https:\u002F\u002Fgithub.com\u002Fvasturiano)** for the incredible `force-graph` library and the broader ecosystem of visualization tools.\n- **Steve Yegge** for the vision behind Beads—a refreshingly simple approach to issue tracking that respects developers' workflows.\n\n> *About Contributions:* Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other \"stakeholders,\" which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via `gh` and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.\n\n---\n\n## 📄 License\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and\u002For sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\n## 🤖 Robot JSON contract — quick cheat sheet\n\n**Shared across all robots**\n- `data_hash`: hash of the beads file driving the response (use to correlate multiple calls).\n- `analysis_config`: exact analysis settings (timeouts, modes, cycle caps) for reproducibility.\n- `status`: per-metric state `computed|approx|timeout|skipped` with elapsed ms\u002Freason; always check before trusting heavy metrics like PageRank\u002FBetweenness\u002FHITS.\n- `as_of` \u002F `as_of_commit`: present when using `--as-of`; contains the ref you specified and the resolved commit SHA for reproducibility.\n\n**Schemas in 5 seconds (jq-friendly)**\n- `bv --robot-insights` → `.status`, `.analysis_config`, metric maps (capped by `BV_INSIGHTS_MAP_LIMIT`), `Bottlenecks`, `CriticalPath`, `Cycles`, plus advanced signals: `Cores` (k-core), `Articulation` (cut vertices), `Slack` (longest-path slack).\n- `bv --robot-plan` → `.plan.tracks[].items[].{id,unblocks}` for downstream unlocks; `.plan.summary.highest_impact`.\n- `bv --robot-priority` → `.recommendations[].{id,current_priority,suggested_priority,confidence,reasoning}`.\n- `bv --robot-suggest` → `.suggestions.suggestions[]` (ranked suggestions) + `.suggestions.stats` (counts) + `.usage_hints`.\n- `bv --robot-diff --diff-since \u003Cref>` → `{from_data_hash,to_data_hash,diff.summary,diff.new_issues,diff.cycle_*}`.\n- `bv --robot-history` → `.histories[ID].events` + `.commit_index` for reverse lookup; `.stats.method_distribution` shows how correlations were inferred.\n\n**Copy\u002Fpaste guardrails**\n```bash\n# Ensure metrics are ready\nbv --robot-insights | jq '.status'\n\n# Top unblockers from plan\nbv --robot-plan | jq '.plan.tracks[].items[] | {id, unblocks}'\n\n# High-confidence priority fixes\nbv --robot-priority | jq '.recommendations[] | select(.confidence > 0.6)'\n\n# Structural strength and parallelism\nbv --robot-insights | jq '.full_stats.core_number | to_entries | sort_by(-.value)[:5]'\nbv --robot-insights | jq '.Articulation'\nbv --robot-insights | jq '.Slack[:5]'\n\n# Verify diff hashes match expectations\nbv --robot-diff --diff-since HEAD~1 | jq '{from: .from_data_hash, to: .to_data_hash}'\n\n# Historical analysis (verify as_of metadata)\nbv --robot-insights --as-of HEAD~30 | jq '{as_of, as_of_commit, data_hash}'\n```\n","# Beads 查看器 (bv)\n\n![发布](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002FDicklesworthstone\u002Fbeads_viewer?style=for-the-badge&color=bd93f9)\n![Go 版本](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fgo-mod\u002Fgo-version\u002FDicklesworthstone\u002Fbeads_viewer?style=for-the-badge&color=6272a4)\n![许可证](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT%2BOpenAI%2FAnthropic%20Rider-blue-the-badge)\n[![覆盖率](https:\u002F\u002Fcodecov.io\u002Fgh\u002FDicklesworthstone\u002Fbeads_viewer\u002Fbranch\u002Fmain\u002Fgraph\u002Fbadge.svg)](https:\u002F\u002Fcodecov.io\u002Fgh\u002FDicklesworthstone\u002Fbeads_viewer)\n\n> **优雅、键盘驱动的终端界面，专为 [Beads](https:\u002F\u002Fgithub.com\u002Fsteveyegge\u002Fbeads) 问题跟踪系统设计。**\n\n\u003Cdiv align=\"center\" style=\"margin: 1.2em 0;\">\n \u003Ctable>\n \u003Ctr>\n \u003Ctd align=\"center\" style=\"padding: 8px;\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FDicklesworthstone_beads_viewer_readme_9f0f894e0937.webp\" alt=\"主分屏视图\" width=\"420\" \u002F>\n \u003Cdiv>\u003Csub>主分屏视图：快速列表 + 丰富详情\u003C\u002Fsub>\u003C\u002Fdiv>\n \u003C\u002Ftd>\n \u003Ctd align=\"center\" style=\"padding: 8px;\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FDicklesworthstone_beads_viewer_readme_efbff7a1d279.webp\" alt=\"看板\" width=\"420\" \u002F>\n \u003Cdiv>\u003Csub>看板视图（`b`）：一目了然的工作流\u003C\u002Fsub>\u003C\u002Fdiv>\n \u003C\u002Ftd>\n \u003C\u002Ftr>\n \u003Ctr>\n \u003Ctd align=\"center\" style=\"padding: 8px;\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FDicklesworthstone_beads_viewer_readme_4a96d537151b.webp\" alt=\"洞察面板\" width=\"420\" \u002F>\n \u003Cdiv>\u003Csub>洞察面板：PageRank、关键路径、循环\u003C\u002Fsub>\u003C\u002Fdiv>\n \u003C\u002Ftd>\n \u003Ctd align=\"center\" style=\"padding: 8px;\">\n \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FDicklesworthstone_beads_viewer_readme_f5239545f0b9.webp\" alt=\"图视图\" width=\"420\" \u002F>\n \u003Cdiv>\u003Csub>图视图（`g`）：导航依赖 DAG\u003C\u002Fsub>\u003C\u002Fdiv>\n \u003C\u002Ftd>\n \u003C\u002Ftr>\n \u003C\u002Ftable>\n\u003C\u002Fdiv>\n\n## 安装\n\n### 推荐：Homebrew（macOS\u002FLinux）\n\n```bash\nbrew install dicklesworthstone\u002Ftap\u002Fbv\n```\n\n此方法提供：\n- 通过 `brew upgrade` 自动更新\n- 依赖管理\n- 通过 `brew uninstall` 轻松卸载\n\n### Windows：Scoop\n\n```powershell\nscoop bucket add dicklesworthstone https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fscoop-bucket\nscoop install dicklesworthstone\u002Fbv\n```\n\n### 其他：直接下载\n\n下载适用于您平台的最新版本（tar.gz 格式）：\n- [Linux x86_64](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Freleases\u002Flatest\u002Fdownload\u002Fbv_0.13.0_linux_amd64.tar.gz)\n- [Linux ARM64](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Freleases\u002Flatest\u002Fdownload\u002Fbv_0.13.0_linux_arm64.tar.gz)\n- [macOS Intel](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Freleases\u002Flatest\u002Fdownload\u002Fbv_0.13.0_darwin_amd64.tar.gz)\n- [macOS ARM](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Freleases\u002Flatest\u002Fdownload\u002Fbv_0.13.0_darwin_arm64.tar.gz)\n- [Windows](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Freleases\u002Flatest\u002Fdownload\u002Fbv_0.13.0_windows_amd64.tar.gz)\n\n> 注意：资产名称包含版本号。如果链接显示 404 错误，请打开最新发布页面并下载对应的文件。\n\n### 其他：安装脚本\n\n**Linux\u002FmacOS：**\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash\n```\n\n**Windows（PowerShell）：**\n```powershell\nirm \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Fmain\u002Finstall.ps1\" | iex\n```\n> **注意：** Windows 需要 Go 1.21 或更高版本（[下载](https:\u002F\u002Fgo.dev\u002Fdl\u002F)）。为了获得最佳显示效果，请使用带有 [Nerd Font](https:\u002F\u002Fwww.nerdfonts.com\u002F) 的 Windows Terminal。\n\n---\n\n## 生成 JSONL 文件 (`br` 和 `bd`)\n\n`bv` 从 `.beads\u002Fbeads.jsonl` 中读取数据。基于 Rust 的 `br` 和原始基于 Go 的 `bd` 都可以生成此文件。\n\n**Rust (`br`) 用户** — `br` 默认会写入 `.beads\u002Fbeads.jsonl`；无需额外步骤。\n\n**Go (`bd`) 用户** — 运行：\n\n```bash\nbd export --no-memories -o .beads\u002Fbeads.jsonl\n```\n\n一旦文件存在，无论由哪种工具生成，`bv` 的运行方式都相同。\n\n---\n\n## 🤖 代理快速入门（机器人模式）\n\n⚠️ **切勿在代理环境中直接运行 `bv`** — 它会启动交互式 TUI。请始终使用 `--robot-*` 参数。\n\n```bash\n# 1) 从分类开始（单次调用的超级命令）\nbv --robot-triage\n\n# 2) 最小化模式：仅选择最优先的任务并执行认领命令\nbv --robot-next\n\n# 3) 优化后的令牌输出（TOON）\nbv --robot-triage --format toon\nexport BV_OUTPUT_FORMAT=toon\n\n# 4) 完整的机器人帮助\nbv --robot-help\n```\n\n**输出规范**\n- stdout = 仅 JSON\u002FTOON 数据\n- stderr = 诊断信息\n- 退出码 0 = 成功\n\n## 💡 简而言之\n\n`bv` 是一款高性能的 **终端用户界面（TUI）**，用于浏览和管理使用 **Beads** 问题跟踪系统的项目中的任务。\n\n**为什么你会感兴趣：**\n* **速度：** 无需网络延迟，即可瞬间浏览数千个问题。\n* **专注：** 停留在终端中，使用 Vim 风格的按键（`j`\u002F`k`）进行导航。\n* **智能：** 它将你的项目可视化为 **依赖图**，自动突出显示传统基于列表的跟踪工具所忽略的瓶颈、循环和关键路径。\n* **AI 就绪：** 它提供结构化的预计算洞察，供 AI 编码代理使用，充当你项目任务管理的“大脑”。\n\n---\n\n## 📖 核心体验\n\n归根结底，`bv` 的核心在于 **美观地查看你的工作**。\n\n### ⚡ 快速流畅的浏览\n无需加载网页，也无需笨重的客户端。`bv` 可以立即启动，并允许你使用标准的 Vim 键盘（`j`\u002F`k`）快速浏览问题积压。\n* **分屏仪表盘：** 在较宽的屏幕上，左侧显示列表，右侧显示完整详情。\n* **Markdown 渲染：** 问题描述、评论和笔记都会以语法高亮、标题和列表的形式精美呈现。\n* **即时筛选：** 零延迟筛选。按 `o` 查看未处理的问题，按 `c` 查看已完成的问题，或按 `r` 查看已准备好（未被阻塞）的问题。\n* **实时重新加载：** 监听 `.beads\u002Fbeads.jsonl` 文件，当文件发生变化时，自动刷新列表、详情和洞察——无需重启。\n\n### 🔎 丰富的上下文\n不要只看标题。`bv` 会为你提供完整的画面：\n* **评论与历史记录：** 滚动查看任何任务的完整对话历史。\n* **元数据：** 立即查看分配人、标签、优先级徽章以及创建日期。\n* **搜索：** 强大的模糊搜索（`\u002F`）可立即根据 ID、标题或内容找到问题。\n\n### 🎯 专注的工作流程\n* **看板：** 按 `b` 切换到列式视图（未处理、进行中、被阻塞、已完成），以可视化工作流。\n* **可视化图：** 按 `g` 可以直观地探索依赖树。\n* **洞察：** 按 `i` 可以查看图谱指标和瓶颈。\n* **历史视图：** 按 `h` 可以查看变更时间线，将 git 提交与珠子修改关联起来。在较宽的终端上，享受响应式的三栏布局，显示提交、受影响的珠子和详细信息。\n* **超宽模式：** 在大屏幕上，列表会扩展以显示额外的列，例如火花线和标签。\n\n### 🛠️ 快捷操作\n* **导出:** 按下 `E` 可将所有问题导出为带时间戳的 Markdown 文件，并包含 Mermaid 图表。\n* **图导出（CLI）:** `bv --robot-graph` 会以 JSON、DOT（Graphviz）或 Mermaid 格式输出依赖关系图。使用 `--graph-format=dot` 可通过 Graphviz 渲染，或使用 `--graph-root=ID --graph-depth=3` 提取聚焦的子图。\n* **复制:** 按下 `C` 可将选中的问题以格式化的 Markdown 形式复制到剪贴板。\n* **编辑:** 按下 `O` 可在您首选的 GUI 编辑器中打开 `.beads\u002Fbeads.jsonl` 文件。\n* **时光回溯:** 按下 `t` 可与任意 Git 提交版本进行对比，或按下 `T` 进行快速的 HEAD~5 对比。结合历史视图（`h`），您可以导航到任意提交，并查看具体发生了哪些变化。\n\n### 🔌 自动化钩子\n在 `.bv\u002Fhooks.yaml` 中配置导出前后的钩子，以执行验证、通知或上传等操作。默认设置为：导出前钩子在出现错误时立即失败（`on_error: fail`），导出后钩子则记录日志并继续执行（`on_error: continue`）。为空的命令会被忽略，并发出警告以确保安全。钩子环境变量包括 `BV_EXPORT_PATH`、`BV_EXPORT_FORMAT`、`BV_ISSUE_COUNT`、`BV_TIMESTAMP`，以及任何自定义的 `env` 条目。\n\n---\n\n## 🤖 可直接插入 AGENTS.md 或 CLAUDE.md 文件的现成简介\n\n```\n### 使用 bv 作为 AI 辅助工具\n\nbv 是一个面向 Beads 项目（.beads\u002Fbeads.jsonl）的图感知分类引擎。它无需解析 JSONL 或凭空推测图遍历路径，而是通过机器人标志实现确定性、依赖感知的输出，并提供预计算的指标（PageRank、介数中心性、关键路径、环路、HITS、特征向量、k-核）。\n\n**作用范围边界:** bv 负责 *处理什么工作*（分类、优先级排序、规划）。对于代理间的协作（消息传递、任务认领、文件预留），请使用 [MCP Agent Mail](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fmcp_agent_mail)。\n\n**⚠️ 重要提示：仅使用 `--robot-*` 标志。直接运行 `bv` 会启动交互式 TUI，从而阻塞您的会话。**\n\n#### 工作流程：从分类开始\n\n**`bv --robot-triage` 是您的唯一入口。** 它一次调用即可返回您所需的一切：\n- `quick_ref`: 一目了然的统计信息 + 前三名建议\n- `recommendations`: 排序后的可执行事项，附带评分、理由及解除阻塞信息\n- `quick_wins`: 低投入高回报的任务\n- `blockers_to_clear`: 能够解锁最多下游工作的事项\n- `project_health`: 状态\u002F类型\u002F优先级分布、图谱指标\n- `commands`: 下一步操作的可复制粘贴 Shell 命令\n\nbv --robot-triage # 综合命令：从这里开始\nbv --robot-next # 极简版：仅显示排名第一的事项及认领命令\n\n# 面向低 LLM 上下文占用的优化输出（TOON）：\nbv --robot-triage --format toon\nexport BV_OUTPUT_FORMAT=toon\nbv --robot-next\n\n#### 其他命令\n\n**规划:**\n| 命令 | 返回内容 |\n|---------|---------|\n| `--robot-plan` | 并行执行轨迹及“解除阻塞”列表 |\n| `--robot-priority` | 优先级不匹配检测及置信度 |\n\n**图分析:**\n| 命令 | 返回内容 |\n|---------|---------|\n| `--robot-insights` | 完整指标：PageRank、介数中心性、HITS（枢纽\u002F权威）、特征向量、关键路径、环路、k-核、割点、松弛度 |\n| `--robot-label-health` | 按标签健康状况：`health_level`（健康\\|警告\\|严重）、`velocity_score`、`staleness`、`blocked_count` |\n| `--robot-label-flow` | 标签间依赖关系：`flow_matrix`、`dependencies`、`bottleneck_labels` |\n| `--robot-label-attention [--attention-limit=N]` | 按注意力排名的标签：(pagerank × staleness × block_impact) \u002F velocity |\n\n**历史与变更追踪:**\n| 命令 | 返回内容 |\n|---------|---------|\n| `--robot-history` | 珠子与提交的关联：`stats`、`histories`（每颗珠子的事件\u002F提交\u002F里程碑）、`commit_index` |\n| `--robot-diff --diff-since \u003Cref>` | 自指定参考以来的变更：新增\u002F关闭\u002F修改的问题、引入\u002F解决的环路 |\n\n**其他命令:**\n| 命令 | 返回内容 |\n|---------|---------|\n| `--robot-burndown \u003Csprint>` | Sprint 燃尽图、范围变化、风险事项 |\n| `--robot-forecast \u003Cid\\|all>` | 带依赖感知调度的 ETA 预测 |\n| `--robot-alerts` | 过期问题、阻塞级联、优先级不匹配 |\n| `--robot-suggest` | 卫生检查：重复项、缺失依赖、标签建议、环路修复 |\n| `--robot-graph [--graph-format=json\\|dot\\|mermaid]` | 导出依赖关系图 |\n| `--export-graph \u003Cfile.html>` | 自包含的交互式 HTML 可视化 |\n\n#### 范围限定与筛选\n\nbv --robot-plan --label backend # 限定到特定标签的子图\nbv --robot-insights --as-of HEAD~30 # 历史时间点\nbv --recipe actionable --robot-plan # 预过滤：已准备好工作的（无阻塞）\nbv --recipe high-impact --robot-triage # 预过滤：PageRank 分数最高的\nbv --robot-triage --robot-triage-by-track # 按并行工作流分组\nbv --robot-triage --robot-triage-by-label # 按领域分组\n\n#### 理解机器人输出\n\n**所有机器人 JSON 包含：**\n- `data_hash` — 源 beads.jsonl 的指纹（用于验证多次调用的一致性）\n- `status` — 各指标状态：`computed|approx|timeout|skipped` + 耗时 ms\n- `as_of` \u002F `as_of_commit` — 在使用 `--as-of` 时提供，包含引用和解析后的 SHA\n\n**两阶段分析：**\n- **第一阶段（即时）:** 度、拓扑排序、密度 — 总是立即可用\n- **第二阶段（异步，超时 500ms）:** PageRank、介数中心性、HITS、特征向量、环路 — 请检查 `status` 标志\n\n**对于大型图（>500 个节点）:** 部分指标可能会被近似或跳过。务必检查 `status`。\n\n#### jq 快速参考\n\nbv --robot-triage | jq '.quick_ref' # 一目了然的摘要\nbv --robot-triage | jq '.recommendations[0]' # 最优推荐\nbv --robot-plan | jq '.plan.summary.highest_impact' # 最佳解除阻塞目标\nbv --robot-insights | jq '.status' # 检查指标是否已就绪\nbv --robot-insights | jq '.Cycles' # 循环依赖（必须修复！）\nbv --robot-label-health | jq '.results.labels[] | select(.health_level == \"critical\")'\n\n**性能:** 第一阶段即时，第二阶段异步（超时 500ms）。当速度至关重要时，优先选择 `--robot-plan` 而不是 `--robot-insights`。结果按数据哈希缓存。\n使用 bv 替代直接解析 beads.jsonl——它能以确定性方式计算 PageRank、关键路径、环路和并行轨迹。\n```\n\n### 自动集成\n\n`bv` 可以自动将上述说明添加到你的项目代理文件中：\n\n- **首次运行时**，`bv` 会检查是否存在 `AGENTS.md`（或类似文件），如果不存在，则会提示是否注入简介。\n- 选择 **\"Yes\"** 添加说明，**\"No\"** 跳过，或 **\"Don't ask again\"** 记住你的选择。\n- 每个项目的偏好设置会存储在 `~\u002F.config\u002Fbv\u002Fagent-prompts\u002F` 目录下。\n\n**支持的文件**（按顺序检查）：\n1. `AGENTS.md`（优先）\n2. `CLAUDE.md`\n3. `agents.md`\n4. `claude.md`\n\n**手动控制：**\n\n```bash\nbv --agents-check # 检查代理文件中是否已存在简介\nbv --agents-add # 将简介添加到代理文件（如需要则创建文件）\nbv --agents-remove # 从代理文件中移除简介\nbv --agents-update # 将简介更新为最新版本\nbv --agents-dry-run # 显示不执行操作时会发生什么\n```\n\n**版本跟踪：**\n\n简介使用 HTML 注释标记进行版本跟踪：\n```\n\u003C!-- bv-agent-instructions-v1 -->\n... 内容 ...\n\u003C!-- end-bv-agent-instructions -->\n```\n\n当发布新版本的简介时，`bv` 可以检测到过时的版本并提示你更新。\n\n---\n\n## 📐 架构与设计\n\n`bv` 将你的项目视为一个**有向无环图（DAG）**，而不仅仅是一组列表。这使得它能够推导出哪些内容是*真正*重要的。\n\n```mermaid\ngraph TD\n %% Soft Pastel Theme — Refined\n classDef data fill:#e3f2fd,stroke:#90caf9,stroke-width:2px,color:#1565c0,rx:8\n classDef logic fill:#fff8e1,stroke:#ffcc80,stroke-width:2px,color:#e65100,rx:8\n classDef ui fill:#f3e5f5,stroke:#ce93d8,stroke-width:2px,color:#6a1b9a,rx:8\n classDef output fill:#e8f5e9,stroke:#a5d6a7,stroke-width:2px,color:#2e7d32,rx:8\n\n subgraph storage [\" 📂 数据层 \"]\n A[\".beads\u002Fbeads.jsonl\u003Cbr\u002F>JSONL 问题存储\"]:::data\n end\n\n subgraph engine [\" ⚙️ 分析引擎 \"]\n B[\"加载器\"]:::logic\n C[\"图构建器\"]:::logic\n D[\"9 个指标\u003Cbr\u002F>PageRank · Betweenness · HITS...\"]:::logic\n end\n\n subgraph interface [\" 🖥️ TUI 层 \"]\n E[\"Bubble Tea 模型\"]:::ui\n F[\"列表视图\"]:::ui\n G[\"图视图\"]:::ui\n G2[\"树形视图\"]:::ui\n H[\"洞察仪表盘\"]:::ui\n end\n\n subgraph outputs [\" 📤 输出 \"]\n I[\"--robot-insights\u003Cbr\u002F>用于 AI 代理的 JSON\"]:::output\n J[\"--export-md\u003Cbr\u002F>Markdown 报告\"]:::output\n end\n\n A --> B\n B --> C\n C --> D\n D --> E\n D --> I\n D --> J\n E --> F\n E --> G\n E --> G2\n E --> H\n\n linkStyle 0,1,2 stroke:#90caf9,stroke-width:2px\n linkStyle 3,4,5 stroke:#ffcc80,stroke-width:2px\n linkStyle 6,7,8,9 stroke:#ce93d8,stroke-width:2px\n```\n\n### 关键指标与算法\n`bv` 计算**9 个图论指标**，以揭示隐藏的项目动态：\n\n| 序号 | 指标 | 表示的内容 | 关键洞察 |\n|------|--------------|--------------------------------|--------------------------|\n| 1 | **PageRank** | 递归依赖的重要性 | 基础性阻塞因素 |\n| 2 | **Betweenness** | 最短路径上的流量 | 瓶颈与桥梁 |\n| 3 | **HITS** | Hub\u002FAuthority 对偶性 | 重大任务 vs. 工具性任务 |\n| 4 | **关键路径** | 最长依赖链 | 零松弛度的关键节点 |\n| 5 | **特征向量** | 通过邻居传递的影响 | 战略性依赖关系 |\n| 6 | **度数** | 直接连接的数量 | 即时阻塞者\u002F被阻塞者 |\n| 7 | **密度** | 边与节点的比例 | 项目耦合健康状况 |\n| 8 | **循环** | 循环依赖 | 结构性错误 |\n| 9 | **拓扑排序** | 合法的执行顺序 | 工作队列的基础 |\n\n### 1. PageRank（依赖权威）\n**数学公式：** 最初设计用于根据传入链接对网页的“重要性”进行排名，PageRank 模拟了一个“随机浏览者”在图上行走的过程。在我们的依赖图中（u → v 表示 u 依赖于 v），我们将依赖关系视为“投票”，用来衡量重要性。\n$$\nPR(v) = \\frac{1-d}{N} + d \\sum_{u \\in M(v)} \\frac{PR(u)}{L(u)}\n$$\n\n**直观理解：** 如果许多任务都依赖于任务 A，或者有一个非常重要的任务 B 依赖于任务 A，那么任务 A 就会变得“举足轻重”。一个随机游走者沿着依赖关系不断前进，往往会频繁地停留在任务 A 上。\n\n**实际意义：** **基础性阻塞因素。** PageRank 值高的任务是你项目的基石。它们很少是面向用户的“功能”，通常是架构、核心库或架构决策。一旦这些任务出现问题，整个依赖图就会崩溃。\n\n### 2. 介数中心性（瓶颈）\n**数学公式：** 定义为网络中所有最短路径中经过给定节点 $v$ 的比例。\n$$C_B(v) = \\sum_{s \\neq v \\neq t} \\frac{\\sigma_{st}(v)}{\\sigma_{st}}$$\n\n**直观理解：** 想象信息（或进度）从每个任务流向其他任务，沿着最高效的路径传输。“桥接节点”连接着原本孤立的集群（例如前端集群和后端集群），因此会承受巨大的流量。\n\n**实际意义：** **把关者与瓶颈。** 介数中心性高的任务是一个关键的卡点。它可能是一个移动应用和服务器团队都在等待的 API 接口。如果这个任务延迟了，不仅会阻塞一条线程，还会阻止整个子团队之间的同步。\n\n### 3. HITS（枢纽与权威）\n**数学公式：** 一种迭代算法，为每个节点定义两个分数：\n* **权威分：** 指向该节点的枢纽得分之和。\n* **枢纽分：** 该节点指向的权威得分之和。\n\n**直观理解：** 这种模型描述了一种“相互强化”的关系。优秀的库（权威）会被许多应用程序使用。而优秀的应用程序（枢纽）也会使用许多优秀的库。\n\n**实际意义：** **重大任务 vs. 基础设施。**\n* **高枢纽分：** 这些是你的**重大任务**或**产品特性**。它们汇集了许多依赖关系来交付价值。\n* **高权威分：** 这些是你的**工具性任务**。它们为许多消费者提供价值。\n\n### 4. 关键路径（DAG 中的最长路径）\n**数学公式：** 在 DAG 中，最长路径代表完成项目所需的最短时间（假设可以无限并行）。`bv` 会递归计算这一路径：\n$$Impact(u) = 1 + \\max(\\{Impact(v) \\mid u \\to v\\})$$\n\n**直观理解：** 如果你抓住图中的“叶子”节点（没有依赖的任务）让它悬空，那么位于最顶端、支撑着最长链条的任务就承担了最大的重量。\n\n**实际意义：** **关键节点。** 关键节点是指任何延迟都会直接导致整个项目交付延迟的任务。这些任务没有任何“松弛时间”。\n\n### 5. 特征向量中心性（影响力邻居）\n**数学公式：** 特征向量中心性不仅考虑节点的连接数量，还衡量这些连接的重要性。一个节点即使只有少数但非常重要的邻居，其得分也可能高于拥有大量不重要邻居的节点。\n$$x_i = \\frac{1}{\\lambda} \\sum_{j \\in N(i)} x_j$$\n\n其中，$\\lambda$ 是邻接矩阵的最大特征值，$N(i)$ 表示节点 $i$ 的邻居。\n\n**直观理解：** 影响力不仅仅取决于你有多少连接，更在于你与哪些人相连。如果一项关键任务依赖于你，那么你的作用就比许多琐碎任务依赖你更为重要。\n\n**实际意义：** **战略依赖关系。** 高特征向量中心性的任务通常与图中的“关键角色”相连。它们可能没有很多直接依赖的任务，但其依赖的任务本身却至关重要。\n\n### 6. 度中心性（直接连接）\n**数学公式：** 最简单的中心性度量——只需统计边的数量。\n$$C_D^{in}(v) = |\\{u : u \\to v\\}|$$\n\n$$C_D^{out}(v) = |\\{u : v \\to u\\}|$$\n\n**直观理解：**\n* **入度：** 有多少任务依赖于我？（我是阻塞者）\n* **出度：** 我依赖多少任务？（我被阻塞）\n\n**实际意义：** **直接影响。**\n* **高入度：** 该任务是许多其他任务的直接阻塞点。完成它会立即解除其他工作的阻塞。\n* **高出度：** 该任务有许多前置条件。它很可能处于被阻塞状态，应在执行计划中安排在较晚的时间。\n\n### 7. 图密度（互联程度）\n**数学公式：** 密度衡量图的实际连接情况与其最大可能连接数之间的比例。\n$$D = \\frac{|E|}{|V|(|V|-1)}$$\n\n其中，$|E|$ 是边的数量，$|V|$ 是节点的数量。对于有向图，最大边数为 $|V|(|V|-1)$。\n\n**直观理解：** 密度为 0.0 表示不存在依赖关系（孤立任务）。而密度接近 1.0 则意味着所有任务都相互依赖（病态复杂性）。\n\n**实际意义：** **项目健康指标。**\n* **低密度（\u003C 0.05）：** 健康。任务相对独立，可以并行化。\n* **中等密度（0.05 - 0.15）：** 正常。合理的互联反映了现实中的依赖关系。\n* **高密度（> 0.15）：** 警告。项目耦合过强。建议将其拆分为更小的模块。\n\n### 8. 环检测（循环依赖）\n**数学公式：** 有向图中的环是指从节点 $v_1$ 出发，经过一系列节点 $v_2, \\dots, v_k$ 后又回到 $v_1$ 的路径，即起点和终点相同。`bv` 使用 Tarjan 算法的变体，通过 `topo.DirectedCyclesIn` 来枚举所有基本环。\n\n**直观理解：** 如果 A 依赖 B，而 B 又依赖 A，那么两者都无法完成。这是一种逻辑上的不可能，必须予以解决。\n\n**实际意义：** **结构错误。** 环是项目计划中的“漏洞”，而不仅仅是警告。它们表明：\n* 依赖关系分类错误（A 并非真正阻塞 B，反之亦然）\n* 缺少中间任务（A 和 B 都依赖于未明确的 C）\n* 范围混淆（A 和 B 应合并为一个任务）\n\n### 9. 拓扑排序（执行顺序）\n**数学公式：** 有向无环图的拓扑排序是将所有顶点排列成一个线性序列，使得对于每一条边 $u \\to v$，顶点 $u$ 总是在 $v$ 之前出现。只有无环图才存在有效的拓扑排序。\n\n**直观理解：** 如果必须按照依赖关系完成任务，拓扑排序就能给出一种可行的顺序（可能存在多种）。\n\n**实际意义：** **工作队列。** 拓扑排序是 `bv` 执行计划的基础。结合优先级权重，它生成了“下一步要做什么”的建议，从而驱动 `--robot-plan` 功能。\n\n---\n\n## 🤖 机器人协议（AI 接口）\n\n`bv` 桥接了原始数据与 AI 代理之间的鸿沟。代理在处理图算法时往往表现不佳；而 `bv` 作为确定性的“辅助工具”，能够卸载图遍历的认知负担，从而解决这一问题。\n\n```mermaid\nsequenceDiagram\n %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8f5e9', 'primaryTextColor': '#2e7d32', 'primaryBorderColor': '#81c784', 'lineColor': '#90a4ae', 'secondaryColor': '#fff8e1', 'tertiaryColor': '#fce4ec'}}}%%\n\n participant 用户\n participant 代理 as 🤖 AI 代理\n participant BV as ⚡ bv\n participant 文件 as 📄 beads.jsonl\n\n 用户->代理: “修复下一个被阻塞的任务”\n\n rect rgba(232, 245, 233, 0.4)\n Note over 代理, BV: 认知卸载\n 代理->BV: bv --robot-plan\n BV->文件: 读取并解析\n BV->BV: PageRank + 拓扑排序\n BV-->>代理: { next: \"TASK-123\", unblocks: 5 }\n end\n\n rect rgba(255, 243, 224, 0.3)\n Note over 代理: 实施阶段\n 代理->代理: 修复 TASK-123\n 代理->BV: bv --robot-insights\n BV-->>代理: 更新后的图指标\n end\n```\n\n### “认知卸载”策略\n机器人协议的主要设计目标是 **认知卸载**。大型语言模型（LLM）本质上是概率引擎，它们擅长语义推理（如编码、写作），但在算法层面的图遍历（如寻找环、计算最短路径）方面却极不可靠。两阶段分析器会立即返回度、拓扑和密度等指标，并以大小感知的超时机制和哈希缓存异步完成 PageRank、介数中心性、HITS、特征向量中心性、关键路径以及环的检测，因此当图结构未发生变化时，重复调用机器人接口的速度依然很快。\n\n如果直接将原始的 `beads.jsonl` 数据输入到代理中，就会迫使代理：\n1. 解析数千行 JSON 数据。\n2. 在其上下文窗口中重建依赖关系图。\n3. “幻觉式”地尝试进行路径遍历或环检测。\n\n而 `bv` 提供了一个确定性的图引擎作为辅助工具，从而解决了这一问题。\n\n### 为什么选择 `bv` 而不是直接使用原始数据？\n直接使用 `beads` 数据只能为代理提供 *数据*；而使用 `bv --robot-insights` 则能为代理提供 *智能*。\n\n| 能力 | 原始 Beads (JSONL) | `bv` 机器人模式 |\n| :--- | :--- | :--- |\n| **查询** | “列出所有问题。” | “列出阻碍发布的前 5 个瓶颈。” |\n| **上下文开销** | 高（与问题数量成正比）。 | 低（固定摘要结构）。 |\n| **图逻辑** | 代理需自行推断\u002F计算。 | 已预先计算（PageRank\u002FBrandes）。 |\n| **安全性** | 代理可能会遗漏环。 | 环已被明确标记。 |\n\n### 代理使用模式\n代理通常在三个阶段使用 `bv`：\n\n1. **分类与定位：**\n 在开始会话之前，代理会运行 `bv --robot-insights`。它会收到一个轻量级的 JSON 摘要，描述项目的结构健康状况。代理会立即了解到：\n * “我目前不应该处理任务 C，因为它依赖于瓶颈任务 B。”\n * “图中存在环路（A->B->A）；在添加新功能之前，我必须修复这个结构性错误。”\n\n2. **影响分析：**\n 当被要求“重构登录模块”时，代理会检查相关节点的 **PageRank** 和 **影响得分**。如果这些得分较高，则代理知道这是一项高风险的变更，涉及大量下游依赖，因此需要运行更全面的测试。\n\n3. **执行计划制定：**\n 代理不会随意猜测操作顺序，而是使用 `bv` 的拓扑排序生成一个严格的线性化计划。\n\n**JSON 输出模式（`--robot-insights`）：**\n输出设计为严格类型化，便于工具如 `jq` 或标准 JSON 库解析。\n```json\n{\n \"bottlenecks\": [\n { \"id\": \"CORE-123\", \"value\": 0.45 }\n ],\n \"keystones\": [\n { \"id\": \"API-001\", \"value\": 12.0 }\n ],\n \"influencers\": [\n { \"id\": \"AUTH-007\", \"value\": 0.82 }\n ],\n \"hubs\": [\n { \"id\": \"EPIC-100\", \"value\": 0.67 }\n ],\n \"authorities\": [\n { \"id\": \"UTIL-050\", \"value\": 0.91 }\n ],\n \"cycles\": [\n [\"TASK-A\", \"TASK-B\", \"TASK-A\"]\n ],\n \"clusterDensity\": 0.045,\n \"stats\": {\n \"pageRank\": { \"CORE-123\": 0.15, \"...\": \"...\" },\n \"betweenness\": { \"CORE-123\": 0.45, \"...\": \"...\" },\n \"eigenvector\": { \"AUTH-007\": 0.82, \"...\": \"...\" },\n \"hubs\": { \"EPIC-100\": 0.67, \"...\": \"...\" },\n \"authorities\": { \"UTIL-050\": 0.91, \"...\": \"...\" },\n \"inDegree\": { \"CORE-123\": 5, \"...\": \"...\" },\n \"outDegree\": { \"CORE-123\": 2, \"...\": \"...\" },\n \"criticalPathScore\": { \"API-001\": 12.0, \"...\": \"...\" },\n \"density\": 0.045,\n \"topologicalOrder\": [\"CORE-123\", \"API-001\", \"...\"]\n }\n}\n```\n\n| 字段 | 指标 | 包含内容 |\n|-------|--------|------------------|\n| `bottlenecks` | Betweenness | 连接图中不同簇的顶级节点 |\n| `keystones` | Critical Path | 最长依赖链上的顶级节点 |\n| `influencers` | Eigenvector | 与重要邻居相连的顶级节点 |\n| `hubs` | HITS Hub | 顶级依赖聚合节点（Epic） |\n| `authorities` | HITS Authority | 顶级前置条件提供者（Utility） |\n| `cycles` | 环检测 | 所有循环依赖路径 |\n| `clusterDensity` | 密度 | 整体图的互联程度 |\n| `stats` | 所有指标 | 完整原始数据，用于自定义分析 |\n\n---\n\n## 🎨 TUI 工程与工艺\n\n`bv` 基于 **Bubble Tea** 框架构建，确保无卡顿、60fps 的流畅体验。它配备了一个自适应布局引擎，可响应终端大小调整事件，并内置了一个自定义的 ASCII\u002FUnicode 图形渲染器。\n\n```mermaid\nflowchart LR\n classDef core fill:#fef3e2,stroke:#f5d0a9,stroke-width:2px,color:#8b5a2b\n classDef engine fill:#f0e6f6,stroke:#d4b8e0,stroke-width:2px,color:#5d3a6b\n classDef ui fill:#e6f3e6,stroke:#b8d9b8,stroke-width:2px,color:#2d5a2d\n classDef output fill:#e8f4f8,stroke:#b8d4e3,stroke-width:2px,color:#2c5f7c\n\n INPUT[\"⌨️ 输入\u003Cbr\u002F>键 · 鼠标 · 调整大小\"]:::core\n MODEL[\"🫖 模型\u003Cbr\u002F>问题 · 统计 · 焦点\"]:::core\n GRAPH[\"🧮 图引擎\u003Cbr\u002F>PageRank · HITS · 循环\"]:::engine\n VIEWS[\"🖼️ 视图\u003Cbr\u002F>列表 · 板 · 图 · 树 · 智能洞察\"]:::ui\n LAYOUT[\"📐 布局\u003Cbr\u002F>移动 · 分割 · 宽屏\"]:::ui\n TERM[\"🖥️ 终端\u003Cbr\u002F>60fps 输出\"]:::output\n\n INPUT -->|tea.Msg| MODEL\n GRAPH -->|metrics| MODEL\n MODEL -->|state| VIEWS\n VIEWS --> LAYOUT\n LAYOUT --> TERM\n\n linkStyle 0 stroke:#f5d0a9,stroke-width:2px\n linkStyle 1 stroke:#d4b8e0,stroke-width:2px\n linkStyle 2 stroke:#b8d9b8,stroke-width:2px\n linkStyle 3,4 stroke:#b8d4e3,stroke-width:2px\n```\n\n### 1. 自适应布局引擎\n`bv` 并非简单地输出文本，而是在每个渲染周期计算几何布局。\n* **动态调整大小：** `View()` 函数会在每一帧检查当前终端宽度 (`msg.Width`)。\n* **断点逻辑：**\n * `\u003C 100 列`: **移动模式**。列表占据 100% 宽度。\n * `> 100 列`: **分割模式**。列表占 40%，详情占 60%。\n * `> 140 列`: **超宽模式**。列表会插入额外的列（Sparklines、标签），这些列通常会被隐藏。\n* **边距感知：** 布局引擎会明确考虑边框（2 个字符）和内边距（2 个字符），以防止许多 TUI 中常见的“差一”换行错误。\n\n### 2. 零延迟虚拟化\n渲染 10,000 个问题会让一个简单的终端应用崩溃。`bv` 实现了 **视口虚拟化**：\n* **窗口化：** 我们只渲染当前终端窗口中可见的行。\n* **预计算：** 图表指标（PageRank 等）在启动时由单独的 goroutine 计算一次，而不是每帧都计算。底层图采用紧凑的邻接表实现，比基于映射的传统方法快 50–100 倍。\n* **细节缓存：** Markdown 渲染器是惰性实例化的，并且重复使用，避免了昂贵的正则表达式重新编译。\n\n### 3. 可视化图引擎（`pkg\u002Fui\u002Fgraph.go`）\n我们从头开始构建了一个自定义的 2D ASCII\u002FUnicode 渲染引擎，用于可视化依赖关系图。\n* **画布抽象：** 使用 2D 格子的 `rune` 单元格和 `style` 指针，可以在终端中绘制“像素”。\n* **曼哈顿路由：** 边缘使用正交线绘制，并配合适当的 Unicode 角落字符（ `╭`, `─`, `╮`, `│`, `╰`, `╯`），以最大限度减少视觉干扰。\n* **拓扑分层：** 节点根据其“影响深度”分层排列，确保依赖关系始终向下流动。\n\n### 4. 主题一致性\n我们使用 **[Lipgloss](https:\u002F\u002Fgithub.com\u002Fcharmbracelet\u002Flipgloss)** 来强制执行严格的设计系统。\n* **语义化颜色：** 颜色是按语义定义的（`Theme.Blocked`, `Theme.Open`），而非硬编码的十六进制值。这使得 `bv` 能够在“吸血鬼”（暗色）和“亮色”模式之间无缝切换。\n* **状态指示器：** 我们使用 Nerd Font 字形（`🐛`, `✨`, `🔥`）搭配颜色编码，无需阅读文字即可快速传达状态。\n\n---\n\n## 📈 可视化数据编码：火花图与热力图\n\n在终端等信息密集的环境中，文本占用空间较大。`bv` 采用了受爱德华·塔夫特启发的高密度数据可视化技术（`pkg\u002Fui\u002Fvisuals.go`），以最小的空间传达复杂的指标。\n\n### 1. Unicode 简易图\n在超宽屏模式下查看列表时，`bv` 使用 Unicode 块字符（` `、`▂`、`▃`、`▄`、`▅`、`▆`、`▇`、`█`）渲染“图表分数”列。\n* **数学原理：** `RenderSparkline(val, width)` 将浮点数值（0.0 - 1.0）与可用的字符宽度进行归一化处理。它会计算每个字符单元格的精确高度，从而形成连续的柱状图效果。\n* **实用价值：** 这样你只需扫视包含 50 个问题的列表，就能立刻发现复杂度或中心性上的“高峰”，而无需逐个阅读数字。\n\n### 2. 语义热力图\n我们并不使用随机颜色。`pkg\u002Fui\u002Fvisuals.go` 实现了一种感知均匀的颜色渐变（`GetHeatmapColor`），可将指标强度映射到渐变色：\n* `0.0 - 0.2`：**低**（灰色\u002F暗淡）\n* `0.2 - 0.5`：**中**（蓝色\u002F冷色调）\n* `0.5 - 0.8`：**高**（紫色\u002F暖色调）\n* `0.8 - 1.0`：**峰值**（粉色\u002F炽热）\n\n这种视觉编码被应用于洞察仪表板中的徽章，使你能够一眼区分“稍重要”和“极度紧急”的任务。\n\n---\n\n## 🔍 搜索架构\n\n在一个拥有数千个问题的项目中，你无法承受等待后端查询的时间。`bv` 实现了一种**复合式、内存中的模糊搜索**，响应速度极快。\n\n### “扁平化向量”索引\n与其分别搜索各个字段（这需要复杂的 UI 控件），`bv` 在加载时会将每个问题合并为一个可搜索的“向量”。\n`FilterValue()` 方法会构建一个复合字符串，包含：\n* **核心标识：** ID（`\"CORE-123\"`）和标题（`\"修复登录竞态条件\"`）\n* **元数据：** 状态（`\"open\"`）、类型（`\"bug\"`）、优先级\n* **上下文：** 分配人（`\"@steve\"`）和标签（`\"frontend, v1.0\"`）\n\n### 模糊子序列匹配\n当你按下 `\u002F` 键时，搜索引擎会针对这个复合向量执行**模糊子序列匹配**。\n* **示例：** 输入 `\"log fix\"` 可成功匹配到 `\"Fix login race condition\"`。\n* **示例：** 输入 `\"steve bug\"` 可找到分配给 Steve 的 Bug。\n* **示例：** 输入 `\"open v1.0\"` 可筛选出 v1.0 版本中未关闭的问题。\n\n### 性能特点\n* **零分配：** 搜索索引仅在首次加载时构建一次（`loader.LoadIssues`）。\n* **客户端过滤：** 过滤完全在渲染循环中完成。不存在数据库延迟、网络往返，也没有“加载中”的提示。\n* **稳定排序：** 搜索结果会保持主列表的拓扑顺序和优先级排序，确保即使经过筛选后的视图也能反映项目的真正优先级。\n\n---\n\n## 🧜 Mermaid 集成：终端里的图表？\n\n常见问题之一是：“如何在纯文本终端中渲染复杂的图表？”\n\n`bv` 从两个方面解决了这个问题：\n\n### 1. 原生图形可视化器 (`g`)\n对于交互式 TUI，我们构建了一个专门的 **ASCII\u002FUnicode 图形引擎**（`pkg\u002Fui\u002Fgraph.go`），它能够在不依赖图形协议支持（如 Sixel）的情况下，复现 Mermaid 流程图的核心价值。\n* **拓扑分层：** 节点会根据其依赖深度自动排序。\n* **正交布线：** 连接线使用方框绘制字符（`│`、`─`、`╭`、`╯`），以绘制干净的直角路径，避免穿过节点文本。\n* **自适应画布：** 虚拟画布可以无限扩展，但视口（`pkg\u002Fui\u002Fviewport.go`）会裁剪渲染内容，只显示当前屏幕可见的部分，并通过 `h`\u002F`j`\u002F`k`\u002F`l` 键实现平滑滚动。\n\n### 2. 导出引擎 (`--export-md`)\n对于外部报告，`bv` 包含一个强大的 **Mermaid 生成器**（`pkg\u002Fexport\u002Fmarkdown.go`）。\n* **净化处理：** 它会自动转义问题标题中的不安全字符，以防止 Mermaid 解析器出现语法错误。\n* **防冲突 ID：** 当净化处理可能导致冲突时（例如仅由符号组成的 ID），节点会被赋予稳定的哈希后缀，从而确保边不会合并或消失。\n* **基于类别的样式：** 根据节点状态，为其分配 CSS 类（`classDef open`、`classDef blocked`等），这样在 GitHub 或 GitLab 上渲染时，生成的图表外观会与 TUI 的配色方案一致。\n* **语义边：** 阻碍关系用粗箭头表示（`==>`），而松散关系则用虚线表示（`-.->`），将链接的 *严重程度* 编码进视觉语法中。\n\n```mermaid\ngraph TD\n %% Generated by bv — Soft Pastel Theme\n classDef open fill:#c8e6c9,stroke:#81c784,stroke-width:2px,color:#2e7d32\n classDef blocked fill:#ffcdd2,stroke:#e57373,stroke-width:2px,color:#c62828\n classDef inProgress fill:#fff3e0,stroke:#ffb74d,stroke-width:2px,color:#ef6c00\n\n A[\"CORE-123\u003Cbr\u002F>重构登录\"]:::open\n B[\"UI-456\u003Cbr\u002F>登录页面\"]:::blocked\n C[\"API-789\u003Cbr\u002F>认证接口\"]:::inProgress\n\n A --> B\n A --> C\n C -.-> B\n\n linkStyle 0 stroke:#81c784,stroke-width:2px\n linkStyle 1 stroke:#81c784,stroke-width:2px\n linkStyle 2 stroke:#e57373,stroke-width:1px,stroke-dasharray:5\n```\n\n---\n\n## 📸 图表导出 (`--robot-graph`)\n\n将依赖关系图以多种格式导出，用于可视化、文档记录或与其他工具集成：\n\n```bash\nbv --robot-graph # JSON（默认）\nbv --robot-graph --graph-format=dot # Graphviz DOT\nbv --robot-graph --graph-format=mermaid # Mermaid 图\n\n# 提取聚焦子图\nbv --robot-graph --graph-root=bv-123 # 以特定根节点为中心的子图\nbv --robot-graph --graph-root=bv-123 --graph-depth=3 # 限制深度\n```\n\n### 输出格式\n\n| 格式 | 使用场景 | 渲染方式 |\n|--------|----------|-----------|\n| `json` | 程序化处理、自定义可视化 | 使用 jq 或代码解析 |\n| `dot` | 高质量静态图像 | `dot -Tpng file.dot -o graph.png` |\n| `mermaid` | 嵌入 Markdown、GitHub 渲染 | 直接粘贴到文档中 |\n\n### 子图提取\n\n对于大型项目，可以围绕特定问题提取聚焦视图：\n\n- **`--graph-root=ID`**：从某个问题出发，包含其所有依赖项和被依赖项\n- **`--graph-depth=N`**：限制遍历深度至 N 层（0 表示无限制）\n\n### JSON 模式\n\n```json\n{\n \"nodes\": [\n { \"id\": \"bv-123\", \"title\": \"修复认证\", \"status\": \"open\", \"priority\": 1 }\n ],\n \"edges\": [\n { \"from\": \"bv-124\", \"to\": \"bv-123\", \"type\": \"blocks\" }\n ],\n \"metadata\": {\n \"data_hash\": \"abc123\",\n \"node_count\": 45,\n \"edge_count\": 62\n }\n}\n```\n\n---\n\n## 🌌 交互式图形可视化 (`--export-graph`)\n\n为了深入探索复杂的依赖结构，`bv` 会生成由力导向图引擎驱动的**自包含 HTML 可视化文件**。与静态导出不同，这些文件完全可交互——你可以平移、缩放、过滤并深入查看单个节点，而无需任何服务器或额外依赖。\n\n```bash\n\n# 生成交互式 HTML 图表\nbv --export-graph graph.html # 导出到指定文件\nbv --export-graph # 自动生成带时间戳的文件名\nbv --export-graph --graph-title \"Q4 Sprint\" # 自定义标题\nbv --export-graph --graph-include-closed # 包含已关闭的问题\n```\n\n### 为什么选择交互式图可视化？\n\n传统的列表视图将任务孤立地展示出来。而交互式图则能揭示项目的**隐藏结构**：\n\n- **依赖链**：一眼看出哪些任务阻塞了其他任务，并追踪待办事项中的关键路径。\n- **瓶颈检测**：通过 PageRank 和介数中心性调整节点大小，可快速发现哪些事项对整体影响最大。\n- **聚类发现**：力导向布局会自然地将相关工作分组，从而揭示团队边界或功能集群。\n- **上下文切换**：只需悬停在任意节点上，即可查看完整详情——描述、设计说明、验收标准等，无需离开可视化界面。\n\n### 导出内容包含什么？\n\n每个 HTML 文件都是**完全自包含**的（通常大小为 400KB 至 1MB，具体取决于项目规模）：\n\n| 组件 | 描述 |\n|-----------|-------------|\n| **完整的珠子数据** | 标题、描述、设计、验收标准、备注、标签、时间戳 |\n| **图谱指标** | PageRank、介数中心性、关键路径得分、松弛值、枢纽\u002F权威得分 |\n| **分类分析** | 完整的分类建议，附带评分和理由 |\n| **Git 关联信息** | 每个珠子关联的提交历史（如有） |\n| **依赖关系图** | 完整的“被阻塞者”与“阻塞者”关系，以可视化边线表示 |\n\n### 界面概览\n\n该可视化提供了一个功能丰富的键盘驱动界面：\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ 📊 项目图 | [搜索...] | 布局 ▾ | 过滤器 ▾ | 🔥 📋 ⭐ ☀️ ❓ │\n├──────────────────────┬──────────────────────────────────────────────────────┤\n│ │ │\n│ 珠子详情 │ 力导向图 │\n│ ═══════════════ │ │\n│ ID: bv-xyz │ ●───────● │\n│ 标题: Feature X │ \u002F│\\ │ │\n│ │ ● ● ● ●───● │\n│ 描述: │ │ │ │\n│ [markdown...] │ ●───────────● │\n│ │ │\n│ 图谱指标: │ ┌──────────────────┐ │\n│ PageRank: 2.34% │ │ 低 ▰▰▰▰ 高 │ \u003C- 热图图例 │\n│ 介数: 0.12 │ └──────────────────┘ │\n│ 关键路径: 4.0 │ ┌─────────────┐ │\n│ │ │ 小地图 │ │\n│ 被阻塞者: [...] │ └─────────────┘ │\n│ 阻塞者: [...] │ │\n└──────────────────────┴──────────────────────────────────────────────────────┘\n```\n\n### 可视化编码\n\n节点同时编码了多维信息：\n\n| 视觉属性 | 含义 |\n|-----------------|---------|\n| **颜色** | 状态：🟢 开放、🟠 进行中、🔴 阻塞、⚫ 已关闭 |\n| **大小** | 可配置的度量标准（PageRank、介数中心性、关键路径、入度） |\n| **形状** | 类型：● 功能、▲ 缺陷、■ 任务、◆ 壮举 |\n| **光晕** | 悬停时出现金色光环，显示连接的子图（两跳邻居） |\n| **边的颜色** | 粉色边表示关键路径连接。\n\n### 键盘快捷键\n\n该可视化完全由键盘控制：\n\n| 键 | 动作 | 键 | 动作 |\n|-----|--------|-----|--------|\n| `?` | 帮助叠加层 | `D` | 固定\u002F分离详情面板 |\n| `F` | 适应所有内容 | `L` | 切换亮\u002F暗模式 |\n| `R` | 重置为默认 | `H` | 切换热图着色 |\n| `Space` | 全屏 | `T` | 顶部节点面板 |\n| `Esc` | 清除\u002F取消 | `G` | 分类面板 |\n| `1-4` | 布局模式 | `Y` | 最近查看 |\n| `P` | 路径查找模式 | | |\n\n### 功能\n\n**过滤与搜索**\n- **全文搜索**：按 ID、标题或内容实时预览查找珠子。\n- **状态筛选**：开放、进行中、阻塞、已关闭。\n- **类型筛选**：功能、缺陷、任务、壮举。\n- **优先级筛选**：从 P0（关键）到 P4（待办）。\n- **标签筛选**：根据您的数据动态填充。\n\n**导航**\n- **路径查找**：按下 `P`，然后点击两个节点，即可找到并高亮显示两者之间的最短路径。\n- **最近查看**：按下 `Y` 查看导航历史，并快速返回之前访问过的节点。\n- **小地图**：角落中的概览显示当前视口位置。\n\n**面板**\n- **固定详情面板**：左侧栏在悬停时显示完整的珠子信息（默认）。\n- **浮动模式**：按下 `D` 可将面板分离，以悬浮提示框形式显示。\n- **分类面板**：显示最高推荐项及其评分和理由。\n- **顶部节点**：列出 PageRank 最高的节点，方便快速导航。\n\n**定制化**\n- **布局模式**：力导向（默认）、DAG 自顶向下、DAG 自左向右、放射状。\n- **尺寸度量**：选择决定节点大小的指标（PageRank、介数中心性、关键路径、入度）。\n- **亮\u002F暗模式**：支持完整主题，确保适当的对比度。\n- **保存偏好设置**：主题和布局选择会通过 localStorage 持久化。\n\n### 使用场景\n\n| 场景 | 图表如何帮助 |\n|----------|---------------------|\n| **冲刺计划** | 识别哪些事项能够解锁最多的下游工作 |\n| **利益相关者更新** | 分享单个 HTML 文件——无需任何设置即可查看 |\n| **架构评审** | 发现功能之间意想不到的依赖关系 |\n| **新员工入职** | 新成员可以探索代码库的工作结构 |\n| **回顾会议** | 可视化已完成的工作及剩余的阻塞点 |\n\n### 示例流程\n\n```bash\n# 1. 生成可视化\nbv --export-graph sprint_review.html --graph-title \"Sprint 42 Review\"\n\n# 2. 在浏览器中打开\nopen sprint_review.html # macOS\nxdg-open sprint_review.html # Linux\nstart sprint_review.html # Windows\n\n# 3. 与团队分享\n# HTML 文件是自包含的——直接发送或托管到任何地方即可\n```\n\n### 技术说明\n\n- **无需服务器**：所有内容都在浏览器端运行。\n- **离线可用**：一旦打开即可完全离线使用。\n- **现代浏览器**：已在 Chrome、Firefox、Safari 和 Edge 上测试过。\n- **性能**：借助 WebGL 加速渲染，可流畅处理 500 多个节点。\n- **文件大小**：通常为 400KB 至 1MB，具体取决于项目规模和内容。\n\n---\n\n## 📄 状态报告引擎\n\n`bv` 不仅适用于个人浏览，它还是一种沟通工具。`--export-md` 标志会生成一份 **面向管理层的状态报告**，将你的代码库状态转换为一份适合利益相关者的精良文档。\n\n### 1. “混合文档”架构\n导出器（`pkg\u002Fexport\u002Fmarkdown.go`）构建的文档兼顾了人类可读性和可视化数据：\n* **一目了然的摘要：** 顶级统计信息（总数、未解决、阻塞中、已关闭）提供了即时的健康状况背景。\n* **嵌入式图表：** 它会将完整的依赖关系图以 Mermaid 图表的形式 *直接嵌入到文档中*。在 GitHub 或 GitLab 等平台上，这会渲染成一个交互式的图表。\n* **锚点导航：** 自动生成的目录使用 URL 友好的 slug（`#core-123-refactor-login`），可以直接链接到具体的 issue 详情，使读者能够在高层级的图表和底层规格之间自由跳转。\n\n### 2. 语义化格式\n我们并不只是简单地输出 JSON 值。导出器应用了特定的格式规则，以确保报告看起来专业：\n* **元数据表格：** 关键字段（分配人、优先级、状态）会在 GFM（GitHub 风格 Markdown）表格中对齐，并配有 emoji 指示符。\n* **对话线程化：** 评论会被渲染为块引用（`>`），并附带相对时间戳，从而保留讨论的流程，与技术规范区分开来。\n* **智能排序：** 报告并不会按 issue ID 顺序列出问题。它采用了与 TUI 相同的优先级逻辑：**未解决的高优先级问题**会首先出现，确保读者关注当前最重要的内容。\n\n---\n\n## ⏳ 时间旅行：快照对比与 Git 历史\n\n`bv` 最强大的功能之一就是 **时间旅行**——能够比较项目在 Git 历史中任意两个时间点的状态。这使得 `bv` 从一个“查看器”转变为一个 **进度跟踪和回归检测系统**。\n\n### 快照模型\n`bv` 可以在任何时刻捕获项目的完整状态：\n\n```mermaid\ngraph LR\n %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8f5e9', 'primaryTextColor': '#2e7d32', 'primaryBorderColor': '#81c784', 'lineColor': '#90a4ae'}}}%%\n\n subgraph \"Git 历史\"\n A[\"HEAD~10\u003Cbr\u002F>\u003Csmall>10 次提交前\u003C\u002Fsmall>\"]\n B[\"HEAD~5\u003Cbr\u002F>\u003Csmall>5 次提交前\u003C\u002Fsmall>\"]\n C[\"HEAD\u003Cbr\u002F>\u003Csmall>当前\u003C\u002Fsmall>\"]\n end\n\n subgraph \"快照\"\n D[\"快照 A\u003Cbr\u002F>\u003Csmall>45 个 issue，3 个循环\u003C\u002Fsmall>\"]\n E[\"快照 B\u003Cbr\u002F>\u003Csmall>52 个 issue，1 个循环\u003C\u002Fsmall>\"]\n F[\"快照 C\u003Cbr\u002F>\u003Csmall>58 个 issue，0 个循环\u003C\u002Fsmall>\"]\n end\n\n A --> D\n B --> E\n C --> F\n D -.->|\"diff\"| E\n E -.->|\"diff\"| F\n\n style D fill:#ffcdd2,stroke:#e57373,stroke-width:2px\n style E fill:#fff3e0,stroke:#ffb74d,stroke-width:2px\n style F fill:#c8e6c9,stroke:#81c784,stroke-width:2px\n```\n\n### 跟踪的内容\n`SnapshotDiff` 会捕获每一个有意义的变化：\n\n| 类别 | 跟踪的变化 |\n|----------|-----------------|\n| **Issues** | 新建、关闭、重新打开、移除、修改 |\n| **Fields** | 标题、状态、优先级、标签、依赖关系 |\n| **Graph** | 新增循环、已解决的循环 |\n| **Metrics** | PageRank 的变化、介数中心性的变化、密度的变化 |\n\n### Git 历史集成 (`pkg\u002Floader\u002Fgit.go`)\n`GitLoader` 能够从 **任意 Git 提交记录** 中加载 issue：\n\n```go\nloader := NewGitLoader(\"\u002Fpath\u002Fto\u002Frepo\")\n\n\u002F\u002F 从不同引用加载\ncurrent, _ := loader.LoadAt(\"HEAD\")\nlastWeek, _ := loader.LoadAt(\"HEAD~7\")\nrelease, _ := loader.LoadAt(\"v1.0.0\")\nbyDate, _ := loader.LoadAt(\"main@{2024-01-15}\")\n```\n\n**缓存架构：**\n- 提交记录会被解析为稳定的 commit SHA 值以便缓存\n- 线程安全的 `sync.RWMutex` 保护并发访问\n- 5 分钟的 TTL 避免数据过时，同时防止重复调用 Git\n\n### 使用场景\n1. **Sprint 回顾：** “这个 sprint 我们关闭了多少个 issue？”\n2. **回归检测：** “我们是否不小心重新引入了一个依赖循环？”\n3. **趋势分析：** “我们的图密度是否在增加？我们是否创建了过多的依赖关系？”\n4. **发布说明：** “生成 v1.0 和 v2.0 之间的所有变更差异。”\n\n---\n\n## 🍳 配方系统：声明式视图配置\n\n与其记住 CLI 标志或反复设置筛选条件，不如使用 `bv` 支持的 **配方**——基于 YAML 的视图配置，可以保存、共享并进行版本控制。\n\n### 配方结构\n```yaml\n# .beads\u002Frecipes\u002Fsprint-review.yaml\nname: sprint-review\ndescription: \"当前 sprint 中涉及的 issues\"\n\nfilters:\n status: [open, in_progress, closed]\n updated_after: \"14d\" # 相对时间：14 天前\n exclude_tags: [backlog, icebox]\n\nsort:\n field: updated\n direction: desc\n secondary:\n field: priority\n direction: asc\n\nview:\n columns: [id, title, status, priority, updated]\n show_metrics: true\n max_items: 50\n\nexport:\n format: markdown\n include_graph: true\n```\n\n### 过滤能力\n\n| 过滤器 | 类型 | 示例 |\n|--------|------|----------|\n| `status` | 数组 | `[open, closed, blocked, in_progress]` |\n| `priority` | 数组 | `[0, 1]`（仅 P0 和 P1） |\n| `tags` | 数组 | `[frontend, urgent]` |\n| `exclude_tags` | 数组 | `[wontfix, duplicate]` |\n| `created_after` | 相对\u002FISO | `\"7d\"`、`\"2w\"`、`\"2024-01-01\"` |\n| `updated_before` | 相对\u002FISO | `\"30d\"`、`\"1m\"` |\n| `actionable` | 布尔值 | `true` = 无未解决的阻塞问题 |\n| `has_blockers` | 布尔值 | `true` = 正等待依赖项 |\n| `id_prefix` | 字符串 | `\"bv-\"` 用于项目过滤 |\n| `title_contains` | 字符串 | 子字符串搜索 |\n\n### 内置配方\n`bv` 自带 11 种预配置配方：\n\n| 配方 | 用途 |\n|--------|---------|\n| `default` | 所有未解决的问题按优先级排序 |\n| `actionable` | 已准备好处理（无阻塞问题） |\n| `recent` | 近 7 天内更新过的 |\n| `blocked` | 正在等待依赖项 |\n| `high-impact` | PageRank 得分最高的 |\n| `stale` | 已经打开超过 30 天但未被触碰的 |\n| `triage` | 按计算出的分类评分排序（影响 + 解除阻塞潜力） |\n| `closed` | 最近关闭的 issues |\n| `release-cut` | 近 14 天内关闭的（用于生成变更日志） |\n| `quick-wins` | 容易处理的 P2\u002FP3 问题且无阻塞 |\n| `bottlenecks` | 介数中心性高的节点（项目瓶颈） |\n\n### 使用配方\n```bash\n# 交互式选择器（在 TUI 中按 R 键）\nbv\n\n# 直接调用配方\nbv --recipe actionable\nbv --recipe high-impact\n\n# 自定义配方文件\nbv --recipe .beads\u002Frecipes\u002Fsprint-review.yaml\n```\n\n---\n\n## 🎯 综合影响评分\n\n传统的 issue 跟踪工具通常只按单一维度排序——通常是优先级。而 `bv` 则会计算一个 **多因素影响评分**，将图论指标与时间因素及优先级信号相结合。\n\n### 评分公式\n$$\n\\text{Impact} = 0.30 \\cdot \\text{PageRank} + 0.30 \\cdot \\text{Betweenness} + 0.20 \\cdot \\text{BlockerRatio} + 0.10 \\cdot \\text{Staleness} + 0.10 \\cdot \\text{PriorityBoost}\n$$\n\n### 组件分解\n\n| 组件 | 权重 | 衡量内容 |\n|--------------|-------|------------------------------|\n| **PageRank** | 30% | 递归依赖的重要性 |\n| **Betweenness** | 30% | 瓶颈\u002F桥梁的位置 |\n| **BlockerRatio** | 20% | 直接依赖项（入度） |\n| **Staleness** | 10% | 自上次更新以来的天数（老化） |\n| **PriorityBoost** | 10% | 人工分配的优先级 |\n\n### 为什么选择这些权重？\n- **60% 图谱指标：** 依赖关系的结构是决定真正重要性的主要因素。\n- **20% 阻塞比：** 直接依赖项对立即解除阻塞至关重要。\n- **10% 老化程度：** 老问题值得关注，它们可能是被遗忘的阻塞点。\n- **10% 优先级：** 人工判断很有价值，但可能过时或带有政治偏见。\n\n### 分数输出\n```json\n{\n \"issue_id\": \"CORE-123\",\n \"title\": \"重构认证模块\",\n \"score\": 0.847,\n \"breakdown\": {\n \"pagerank\": 0.27,\n \"betweenness\": 0.25,\n \"blocker_ratio\": 0.18,\n \"staleness\": 0.07,\n \"priority_boost\": 0.08\n }\n}\n```\n\n### 优先级建议\n当计算出的影响分数与人工分配的优先级显著不同时，`bv` 会生成 **可操作的建议**：\n\n> ⚠️ **CORE-123** 的影响分数为 0.85，但优先级却是 P3。\n> *原因：高 PageRank（基础依赖）+ 高 Betweenness（瓶颈）*\n> **建议：** 考虑将其提升至 P1。\n\n### 优先级提示叠加\n\n在列表视图中按下 `p` 键即可切换 **优先级提示**——内联的视觉指示器，显示哪些问题的优先级与实际情况不符：\n\n```\n┌──────────────────────────────────────────────────────────────┐\n│ OPEN CORE-123 ⬆ 数据库模式迁移 P3 🟢 │\n│ OPEN UI-456 登录页面样式 P2 🟢 │\n│ BLOCKED API-789 ⬇ 旧版接口封装 P1 🔴 │\n└──────────────────────────────────────────────────────────────┘\n ⬆ = 影响分数表明应提高优先级（红色箭头）\n ⬇ = 影响分数表明应降低优先级（青色箭头）\n```\n\n这能让你一目了然地了解你的优先级分配是否与计算出的图谱重要性一致。\n\n---\n\n## 🛤️ 并行执行计划\n\n当你问“接下来该做什么？”时，`bv` 不只是挑选优先级最高的项目。它会生成一个 **完整的执行计划**，既尊重依赖关系，又识别可以并行处理的机会。\n\n### 按轨道规划\n规划器使用 **Union-Find** 算法来识别依赖关系图中的连通组件，将相关问题分组到独立的“轨道”中，以便同时进行处理。\n\n```mermaid\ngraph TD\n %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8f5e9', 'lineColor': '#90a4ae'}}}%%\n\n subgraph track_a [\"🅰️ 轨道 A：认证系统\"]\n A1[\"AUTH-001\u003Cbr\u002F>P1 · 解除 3 个阻塞\"]:::actionable\n A2[\"AUTH-002\"]:::blocked\n A3[\"AUTH-003\"]:::blocked\n end\n\n subgraph track_b [\"🅱️ 轨道 B：UI 优化\"]\n B1[\"UI-101\u003Cbr\u002F>P2 · 解除 1 个阻塞\"]:::actionable\n B2[\"UI-102\"]:::blocked\n end\n\n subgraph track_c [\"🅲 轨道 C：独立任务\"]\n C1[\"DOCS-001\u003Cbr\u002F>P3 · 无阻塞\"]:::actionable\n end\n\n A1 --> A2\n A2 --> A3\n B1 --> B2\n\n classDef actionable fill:#c8e6c9,stroke:#81c784,stroke-width:2px,color:#2e7d32\n classDef blocked fill:#ffcdd2,stroke:#e57373,stroke-width:2px,color:#c62828\n\n linkStyle 0,1,2 stroke:#81c784,stroke-width:2px\n```\n\n### 计划输出 (`--robot-plan`)\n```json\n{\n \"tracks\": [\n {\n \"track_id\": \"track-A\",\n \"reason\": \"独立工作流\",\n \"items\": [\n { \"id\": \"AUTH-001\", \"priority\": 1, \"unblocks\": [\"AUTH-002\", \"AUTH-003\", \"API-005\"] }\n ]\n },\n {\n \"track_id\": \"track-B\",\n \"reason\": \"独立工作流\",\n \"items\": [\n { \"id\": \"UI-101\", \"priority\": 2, \"unblocks\": [\"UI-102\"] }\n ]\n }\n ],\n \"total_actionable\": 3,\n \"total_blocked\": 5,\n \"summary\": {\n \"highest_impact\": \"AUTH-001\",\n \"impact_reason\": \"解除 3 个任务的阻塞\",\n \"unblocks_count\": 3\n }\n}\n```\n\n### 算法流程\n1. **识别可行动问题：** 过滤出未关闭且无未解决阻塞的问题。\n2. **计算解除阻塞情况：** 对每个可行动问题，计算完成它后会解除哪些阻塞。\n3. **寻找连通组件：** 使用 Union-Find 算法根据依赖关系将问题分组。\n4. **构建轨道：** 从每个组件中创建并行轨道，并按每个轨道内的优先级排序。\n5. **计算总结：** 识别出最具影响力的单一问题（解除下游阻塞最多）。\n\n### 对 AI 代理的好处\n- **确定性：** 相同输入始终产生相同计划（不会出现 LLM 幻觉）。\n- **并行感知：** 多个代理可以同时获取不同轨道而不会发生冲突。\n- **影响排序：** `highest_impact` 字段会明确告诉代理从哪里开始。\n\n---\n\n## 🔬 Insights 控制面板：交互式图分析\n\nInsights 控制面板（`i`）将抽象的图谱指标转化为 **交互式探索界面**。它不仅展示数字，还允许你深入探究某个节点为何得分较高，以及这对你的项目意味着什么。\n\n### 6 面板布局\n\n```\n┌─────────────────────┬─────────────────────┬─────────────────────┐\n│ 🚧 瓶颈 │ 🏛️ 关键节点 │ 🌐 影响者 │\n│ Betweenness │ Impact Depth │ Eigenvector │\n│ ───────────────── │ ───────────────── │ ───────────────── │\n│ ▸ 0.45 AUTH-001 │ 12.0 CORE-123 │ 0.82 API-007 │\n│ 0.38 API-005 │ 10.0 DB-001 │ 0.71 AUTH-001 │\n└─────────────────────┴─────────────────────┴─────────────────────┘\n┌─────────────────────┬─────────────────────┬─────────────────────┐\n│ 🛰️ 中心节点 │ 📚 权威节点 │ 🔄 循环依赖 │\n│ HITS Hub Score │ HITS Auth Score │ Circular Deps │\n│ ───────────────── │ ───────────────── │ ───────────────── │\n│ 0.67 EPIC-100 │ 0.91 UTIL-050 │ ⚠ A → B → C → A │\n│ 0.54 FEAT-200 │ 0.78 LIB-010 │ ⚠ X → Y → X │\n└─────────────────────┴─────────────────────┴─────────────────────┘\n```\n\n### 面板说明\n\n| 面板 | 指标 | 显示内容 | 可操作见解 |\n|--------------|-----------------|------------------------------|------------------------------|\n| **🚧 瓶颈** | Betweenness | 位于许多最短路径上的节点 | 优先处理以解除并行工作的阻塞 |\n| **🏛️ 关键节点** | Impact Depth | 深处依赖链中的节点 | 应首先完成——延迟会层层传导 |\n| **🌐 影响者** | Eigenvector | 与重要节点相连 | 在更改前仔细审查 |\n| **🛰️ 中心节点** | HITS Hub | 汇集大量依赖关系 | 作为里程碑跟踪完成进度 |\n| **📚 权威节点** | HITS Authority | 许多中心节点所依赖的对象 | 尽早稳定——否则会引发连锁反应 |\n| **🔄 循环依赖** | Tarjan SCC | 循环依赖环 | 必须解决——逻辑上不可能成立 |\n\n### 详情面板：计算证明\n\n当您选择一个节点时，右侧的**详情面板**不仅会显示得分，还会展示*证明*——即实际参与计算的节点及其对应的值：\n\n```\n─── 计算证明 ───\nBW(v) = Σ (σst(v) \u002F σst) 对所有 s≠v≠t\n\n介数中心性得分：0.452\n\n依赖于此节点的有（5个）：\n ↓ UI-Login：实现登录表单\n ↓ UI-Dashboard：用户仪表盘\n ↓ API-Auth：认证接口\n ... 还有2个\n\n此节点又依赖于（2个）：\n ↑ DB-Schema：用户表迁移\n ↑ CORE-Config：环境配置\n\n该节点位于许多其他节点之间的最短路径上，因此是关键的枢纽节点。\n```\n\n### 仪表板导航\n\n| 键 | 操作 |\n|-----|--------|\n| `Tab` \u002F `Shift+Tab` | 在不同面板之间切换 |\n| `j` \u002F `k` | 在当前面板内导航 |\n| `Enter` | 将选中的节点聚焦到主视图中 |\n| `e` | 切换说明 |\n| `i` | 退出仪表板 |\n\n---\n\n## 📋 看板：可视化工作流状态\n\n看板（`b`）提供一种**列式工作流视图**，具有智能泳道分组、可视化依赖关系指示器和丰富的卡片详情。空列会自动折叠，以最大化屏幕空间。\n\n### 泳道分组模式\n\n按下 `s` 键可在三种分组模式间循环切换：\n\n| 模式 | 列 | 使用场景 |\n|------|---------|----------|\n| **状态**（默认） | 待办 \\| 进行中 \\| 阻塞 \\| 已完成 | 跟踪工作流状态 |\n| **优先级** | P0 关键 \\| P1 高 \\| P2 中 \\| P3+ 其他 | 基于紧急程度的分类 |\n| **类型** | Bug \\| Feature \\| Task \\| Epic | 工作分类 |\n\n当前模式会显示在状态栏中。每种模式使用不同的列颜色，便于快速识别。\n\n### 可视化依赖关系指示器\n\n卡片边框采用**颜色编码**，以便一目了然地显示依赖状态：\n\n```\n┌─ 🔴 红色 ──────────────────┐ ┌─ 🟡 黄色 ─────────────────┐\n│ 阻塞中 │ │ 高影响 │\n│ 此卡片存在未解决的 │ │ 此卡片阻塞了其他任务。 │\n│ 依赖关系。请先处理 │ │ 完成它将解除下游任务的 │\n│ 阻碍因素。 │ │ 阻塞状态。 │\n└────────────────────────────┘ └──────────────────────────────┘\n\n┌─ 🟢 绿色 ────────────────┐ ┌─ ⬜ 默认 ─────────────────┐\n│ 可执行 │ │ 正常 │\n│ 无阻碍的待办事项。 │ │ 标准优先级，没有 │\n│ 请选择它！ │ │ 阻碍关系。 │\n└────────────────────────────┘ └──────────────────────────────┘\n```\n\n搜索匹配项会以**紫色**（当前匹配）或**蓝色**（其他匹配）边框叠加显示。\n\n### 丰富的四行卡片格式\n\n每张卡片以紧凑的格式展示全面的元数据：\n\n```\n┌────────────────────────────────────┐\n│ 🐛 P1 BUG-1234 3d │ ← 第一行：类型、优先级、编号、年龄\n│ 修复认证超时问题 │ ← 第二行：标题（已截断）\n│ 👤alice ⛔3 →2 🏷️2 │ ← 第三行：负责人、阻塞者、被阻塞者、标签\n│ auth, backend, critical │ ← 第四行：标签名称\n└────────────────────────────────────┘\n```\n\n| 元素 | 含义 |\n|---------|---------|\n| **类型图标** | 🐛 Bug，✨ Feature，📝 Task，🎯 Epic，🔧 Chore |\n| **优先级** | P0（红色）、P1（红色）、P2（暗色）、P3+（灰色） |\n| **年龄颜色** | 🟢 \u003C7天（新鲜），🟡 7-30天（老化），🔴 >30天（过期） |\n| **⛔N** | 被N个问题阻塞 |\n| **→N** | 阻塞N个下游问题 |\n| **🏷️N** | 拥有N个标签 |\n\n### 列统计信息\n\n每个列的标题都会显示汇总统计信息：\n\n```\n┌─────────────────────────────────────┐\n│ 进行中（5） 🔥2 ⚠️1 │\n└─────────────────────────────────────┘\n │ │ │\n │ │ └── ⚠️ 该列中的阻塞项\n │ └────── 🔥 P0\u002FP1 关键项\n └───────────────── 总数量\n```\n\n### 卡片内联展开\n\n按下 `d` 键可内联展开选中的卡片，显示：\n- 完整的问题描述\n- 所有阻塞依赖（附带标题）\n- 所有下游依赖\n- 完整的标签列表\n- 评论预览\n\n通过 `j`\u002F`k` 键进行导航时，展开的卡片会自动收起，以确保流畅浏览。\n\n### 详情面板\n\n按下 `Tab` 键可打开一个**侧边面板**，显示完整的问题详情视图（在宽屏终端上）。使用 `Ctrl+J`\u002F`Ctrl+K` 键进行滚动。\n\n### 看板导航\n\n| 键 | 操作 |\n|-----|--------|\n| **移动** | |\n| `h` \u002F `l` | 在列之间移动 |\n| `j` \u002F `k` | 在列内移动 |\n| `gg` \u002F `G` | 跳转到列的顶部\u002F底部 |\n| `0` \u002F `$` | 列中的第一个\u002F最后一个项目 |\n| `H` \u002F `L` | 跳转到第一\u002F最后一列 |\n| `1-4` | 直接跳转到第1-4列 |\n| `Ctrl+D` \u002F `Ctrl+U` | 向下\u002F向上翻页 |\n| **分组与显示** | |\n| `s` | 循环切换泳道模式（状态 → 优先级 → 类型） |\n| `e` | 切换空列可见性 |\n| `d` | 展开\u002F收起内联卡片详情 |\n| `Tab` | 切换侧边详情面板 |\n| **搜索** | |\n| `\u002F` | 开始搜索 |\n| `n` \u002F `N` | 下一个\u002F上一个搜索匹配 |\n| `Esc` | 取消搜索 |\n| **筛选** | |\n| `o` | 筛选：仅显示待办事项 |\n| `c` | 筛选：仅显示已完成事项 |\n| `r` | 筛选：可执行（无阻塞） |\n| **操作** | |\n| `y` | 复制问题编号到剪贴板 |\n| `V` | 预览相关CASS会话（如果已安装CASS） |\n| `Enter` | 将选中的节点聚焦到详情视图中 |\n| `b` | 退出看板视图 |\n\n---\n\n## 🔄 列表排序：多维度组织\n\n按下 `s` 键可在**五种不同的排序模式**之间循环切换，让您即时掌控问题的组织方式。当前排序模式会显示在状态栏中。\n\n### 排序模式\n\n| 模式 | 键显示 | 排序逻辑 | 使用场景 |\n|------|-------------|----------------|----------|\n| **默认** | `Default` | 优先级（升序）→ 创建时间（降序） | 标准的优先级驱动工作流 |\n| **创建时间↑** | `Created ↑` | 按创建日期升序排列（最早开始的排在前面） | 审计：查找长期未解决的问题 |\n| **创建时间↓** | `Created ↓` | 按创建日期降序排列（最新创建的排在前面） | 回顾：查看最近创建的工作 |\n| **优先级** | `Priority` | 仅按优先级排序（P0 → P4） | 纯粹的优先级分类 |\n| **更新时间** | `Updated` | 按最后更新时间降序排列（最新的排在前面） | 活动跟踪：查看活跃的问题 |\n\n### 设计理念\n\n排序系统采用**稳定的二级排序**，以确保确定性的排序结果。当主要排序值相同时，问题会回退到按ID排序，以保证跨会话的一致性。这可以防止“列表乱序”问题，即相同优先级的项目会随机重新排序。\n\n### 状态栏指示器\n\n```\n┌────────────────────────────────────────────────────────────┐\n│ 📋 问题 [创建时间↓] │\n├────────────────────────────────────────────────────────────┤\n│ 待办 FEAT-789 添加暗黑模式开关 P2 🟢 │\n│ 待办 BUG-456 修复登录竞态条件 P1 🟢 │\n│ 待办 TASK-123 更新文档 P3 🟢 │\n└────────────────────────────────────────────────────────────┘\n```\n\n`[创建时间↓]` 的标识牌会立即告知您当前的排序模式，而无需记住自己处于哪种模式。\n\n---\n\n## 🌲 层次树状视图：父子关系可视化\n\n按 `E` 键可打开**层次树状视图**——一个可折叠的树形结构，用于可视化问题之间的父子关系。与显示所有依赖类型的关系图视图不同，树状视图仅关注**结构化层级关系**：哪些问题是其他问题的“组成部分”。\n\n### 为什么父子关系很重要？\n\n在复杂项目中，问题通常有两种不同的关系类型：\n- **阻塞型依赖**（`blocks`\u002F`blocked_by`）：任务 B 必须等到任务 A 完成后才能开始。\n- **父子关系**（`parent`）：特性 X 包含任务 A、B 和 C 作为子工作。\n\n树状视图仅渲染父子关系，从而构建出一份工作分解结构（WBS），帮助回答以下问题：\n- “这个史诗级任务由哪些子任务组成？”\n- “这个缺陷属于哪个特性？”\n- “整个项目中的工作是如何分解的？”\n\n### 树状布局\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ 🌲 树状视图 3 个根节点 · 12 个节点 │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ ▾ 🎯 P1 EPIC-100 认证系统改造 ● 开启 │\n│ │ ├─ ▸ ✨ P1 FEAT-101 实现 OAuth2 流程 ● 开启 │\n│ │ │ └─ • 📝 P2 TASK-102 添加令牌刷新逻辑 ○ 已完成 │\n│ │ └─ • 🐛 P0 BUG-103 修复会话超时竞态问题 ⚠ 被阻塞 │\n│ │ │\n│ ▾ 🎯 P2 EPIC-200 UI 美化冲刺 ● 开启 │\n│ │ ├─ • ✨ P2 FEAT-201 支持深色模式 ● 开启 │\n│ │ └─ • ✨ P3 FEAT-202 响应式布局 ● 开启 │\n│ │ │\n│ • 📝 P3 TASK-300 更新文档 ● 开启 │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n### 可视化编码\n\n| 元素 | 含义 |\n|---------|---------|\n| **▾ \u002F ▸** | 展开 \u002F 折叠（有子节点） |\n| **•** | 叶子节点（无子节点） |\n| **├─ \u002F └─** | 树枝连接符 |\n| **类型图标** | 🎯 史诗级任务、✨ 特性、🐛 缺陷、📝 任务、🔧 杂项 |\n| **优先级** | P0（严重红色）、P1（高）、P2（中等灰色）、P3+（浅色） |\n| **状态点** | ● 开启（绿色）、◐ 进行中（黄色）、⚠ 被阻塞（红色）、○ 已完成（灰色） |\n\n### 树状视图构建算法\n\n树状视图的构建采用**仅父子关系**的过滤器，并结合智能根节点检测：\n\n1. **筛选依赖关系**：仅考虑 `DepParentChild` 类型的依赖关系；阻塞和相关依赖将被忽略。\n2. **构建索引**：创建父 → 子映射，以便高效遍历。\n3. **识别根节点**：没有父节点（或其父节点不在数据集中）的问题将成为根节点。\n4. **递归构建**：使用深度优先遍历并检测循环，防止无限循环。\n5. **排序子节点**：每个父节点下的子节点按以下顺序排序：优先级（升序）→ 类型（史诗级 > 特性 > 缺陷 > 任务）→ 创建日期（最新优先）。\n\n**边缘情况处理：**\n- **孤立引用**：如果某个问题引用了一个不存在的父节点，则该问题将成为根节点（不会被静默丢弃）。\n- **循环**：在遍历时检测到循环；循环节点将被渲染，但不再继续递归。\n- **深层层级**：无深度限制——树状视图能够忠实地表示任意嵌套的结构。\n\n### 树状视图导航\n\n| 键 | 操作 |\n|-----|--------|\n| **移动** | |\n| `j` \u002F `k` \u002F `↓` \u002F `↑` | 光标下移 \u002F 上移 |\n| `g` \u002F `G` | 跳转到第一个 \u002F 最后一个节点 |\n| `Ctrl+D` \u002F `Ctrl+U` | 向下 \u002F 向上翻页（半屏） |\n| **展开\u002F折叠** | |\n| `Enter` \u002F `Space` | 切换当前节点的展开\u002F折叠状态 |\n| `l` \u002F `→` | 展开节点，或在已展开状态下移动到第一个子节点 |\n| `h` \u002F `←` | 折叠节点，或在已折叠状态下跳转到父节点 |\n| `o` | 展开树中所有节点 |\n| `O` | 折叠树中所有节点 |\n| **集成** | |\n| `Tab` | 将选中内容同步到详情面板（分屏模式） |\n| `E` \u002F `Esc` | 退出树状视图，返回列表视图 |\n\n### 使用场景\n\n| 场景 | 树状视图如何帮助 |\n|----------|---------------------|\n| **冲刺计划** | 展开史诗级任务以查看所有子工作，并估算范围 |\n| **进度跟踪** | 折叠已完成的分支，专注于未完成的工作 |\n| **新人入职** | 新成员可以一目了然地了解项目结构 |\n| **重构** | 在重新组织之前，查看哪些任务属于某个特性 |\n| **状态会议** | 自上而下地梳理层级结构，向利益相关者汇报进展 |\n\n### 树状视图 vs. 关系图视图\n\n| 方面 | 树状视图 (`E`) | 关系图视图 (`g`) |\n|--------|-----------------|------------------|\n| **关系类型** | 仅父子关系 | 所有依赖类型 |\n| **布局** | 缩进式层级结构 | 力导向 \u002F DAG |\n| **关注点** | 工作分解结构 | 依赖流程 |\n| **导航方式** | Vim 风格（j\u002Fk\u002Fh\u002Fl） | 视口平移 |\n| **适用场景** | “这个史诗级任务里都有什么？” | “是什么阻塞了这个任务？” |\n\n两种视图相辅相成：使用树状视图理解结构，使用关系图视图理解流程。\n\n---\n\n## 🎯 可执行计划视图：并行执行轨道\n\n按 `a` 键可打开**可执行计划视图**——一种将工作项分组为独立执行轨道的结构化展示。该视图将抽象的关系图分析转化为具体的“接下来要做什么”的界面。\n\n### 为什么执行轨道很重要？\n\n传统的优先级列表会将任务按单一顺序排列。但在复杂的依赖关系图中，有些工作流是完全独立的——处理其中一个并不影响另一个。可执行计划视图利用并查集连通分量分析来识别这些**并行轨道**，允许多个团队成员或代理同时协作，而不会相互干扰。\n\n### 可视化布局\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ 🎯 可行动计划 3个轨道 · 8个项目 │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ ━━━ 轨道A：认证系统 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │\n│ │\n│ ▸ 🎯 P1 AUTH-001 实现OAuth2流程 解锁3项 │\n│ ✨ P2 AUTH-002 添加令牌刷新 解锁1项 │\n│ │\n│ ━━━ 轨道B：UI优化 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │\n│ │\n│ 📝 P2 UI-101 暗色模式切换 解锁2项 │\n│ 📝 P3 UI-102 响应式布局 解锁0项 │\n│ │\n│ ━━━ 轨道C：独立任务 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │\n│ │\n│ 📝 P3 DOCS-001 更新API文档 解锁0项 │\n│ │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ 最高影响力：AUTH-001（解锁3项） │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n### 什么使一个项目“可行动”\n\n当满足以下条件时，一个问题会出现在可行动计划中：\n1. **状态为未完成或进行中**（非已完成）\n2. **不存在未解决的阻塞问题**（所有依赖项均已解决）\n\n这确保了视图中的每个项目都可以立即开始，无需等待其他事项。\n\n### 解锁分析\n\n每个项目都会显示一个**解锁数量**——即如果该项目完成，将有多少其他问题变为可行动。较高的解锁数量表明其具有**放大效应**：完成这些项目将释放大量后续工作。\n\n底部的**最高影响力**摘要会标识出唯一一个项目，一旦完成，就能解锁最多的额外工作。这就是你接下来应该优先处理的最佳选择。\n\n### 导航\n\n| 快捷键 | 功能 |\n|-----|--------|\n| `j` \u002F `k` | 在不同项目间移动（跨轨道） |\n| `Enter` | 打开所选项目的详细视图 |\n| `a` \u002F `Esc` | 退出可行动视图 |\n\n### 使用场景\n\n| 场景 | 可行动视图如何帮助 |\n|----------|---------------------------|\n| **单人开发** | 始终清楚下一个最具影响力的任务 |\n| **团队站会** | 每个人认领不同的轨道 |\n| **AI代理调度** | 代理可以确定性地获取“highest_impact”项目 |\n| **冲刺规划** | 通过统计每个轨道上的可行动项目数量来估算工作量 |\n\n---\n\n## 🔀 流矩阵视图：跨标签依赖分析\n\n按下`f`键即可打开**流矩阵视图**——一个交互式仪表盘，用于可视化各标签（领域\u002F团队）之间的依赖关系。这能揭示在单个问题视图中无法看到的跨团队瓶颈。\n\n### 为什么跨标签流动很重要\n\n在大型项目中，工作通常按标签划分：`前端`、`后端`、`API`、`认证`、`基础设施`。问题之间的依赖关系会隐式地转化为*标签*之间的依赖。流矩阵能够揭示这些模式：\n\n- **哪个团队最常阻碍其他团队？**\n- **哪个领域正在等待最多的外部工作？**\n- **跨团队协作的瓶颈在哪里？**\n\n### 可视化布局\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ 🔀 流矩阵 5个标签 · 23项依赖 │\n├───────────────────────────────────────────┬─────────────────────────────────┤\n│ 标签 │ 详情 │\n│ ───────────────────────────────────── │ ───────────────────────────── │\n│ │ │\n│ ▸ 🔴 api ━━━━━━━━━━ 0.72 │ 标签：api │\n│ 外部依赖：8 → [auth, db, infra] │ ────────────────────── │\n│ 内部依赖：3 ← [frontend, mobile] │ │\n│ │ 瓶颈得分：0.72 │\n│ 🟡 auth ━━━━━━━━ 0.58 │ (前20% = 严重) │\n│ 外部依赖：4 → [db] │ │\n│ 内部依赖：5 ← [api, frontend] │ 外部依赖： │\n│ │ → auth（3个问题） │\n│ 🟢 frontend ━━━━━ 0.31 │ → db（4个问题） │\n│ 外部依赖：2 → [api] │ → infra（1个问题） │\n│ 内部依赖：0 │ │\n│ │ 内部依赖： │\n│ 🟢 db ━━━ 0.22 │ ← frontend（2个问题） │\n│ 外部依赖：0 │ ← mobile（1个问题） │\n│ 内部依赖：7 ← [api, auth] │ │\n│ │ 关键路径：是 │\n└───────────────────────────────────────────┴─────────────────────────────────┘\n```\n\n### 瓶颈得分\n\n瓶颈得分（0.0–1.0）衡量一个标签对跨领域工作的阻碍程度：\n\n$$\n\\text{瓶颈} = \\frac{\\text{外部依赖}}{\\text{总跨标签依赖}} \\times \\text{关键性权重}\n$$\n\n| 得分 | 颜色 | 含义 |\n|-------|-------|---------|\n| 0.7 – 1.0 | 🔴 红色 | 严重瓶颈——优先解除阻塞 |\n| 0.4 – 0.7 | 🟡 黄色 | 中度阻碍——需密切监控 |\n| 0.0 – 0.4 | 🟢 绿色 | 流畅——无协调问题 |\n\n### 下钻模式\n\n按下某个标签上的`Enter`键，即可深入查看造成跨标签依赖的具体问题：\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ 🔀 流矩阵 > api → auth 3个问题 │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ 🐛 P1 API-123 认证接口返回500错误 阻止AUTH-456 │\n│ ✨ P2 API-456 添加OAuth作用域验证 阻止AUTH-789 │\n│ 📝 P2 API-789 限制令牌刷新频率 阻止AUTH-101 │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n### 导航\n\n| 键 | 操作 |\n|-----|--------|\n| `j` \u002F `k` | 在标签之间移动 |\n| `Tab` | 在标签列表和详情面板之间切换焦点 |\n| `Enter` | 下钻到跨标签的问题 |\n| `Esc` | 退出下钻\u002F退出视图 |\n| `f` \u002F `q` | 退出流矩阵视图 |\n\n### 机器人命令\n\n```bash\nbv --robot-label-flow | jq '.flow.bottleneck_labels'\n```\n\n---\n\n## 🎪 注意力视图：标签优先级排序\n\n按下 `]` 打开 **注意力视图**——一个按注意力分数排序的标签表格，帮助您识别哪些项目领域需要重点关注。\n\n### 注意力分数公式\n\n注意力分数结合了多种信号，以突出被忽视或存在问题的区域：\n\n$$\n\\text{Attention} = \\frac{\\text{PageRank}_{\\text{avg}} \\times \\text{Staleness} \\times \\text{BlockImpact}}{\\text{Velocity} + \\epsilon}\n$$\n\n| 组件 | 表示的内容 |\n|-----------|------------------|\n| **PageRank（平均）** | 该标签中问题的平均重要性 |\n| **Staleness** | 问题自上次更新以来的时间长度（越高表示越陈旧） |\n| **Block Impact** | 该标签内被阻塞的问题数量 |\n| **Velocity** | 完成率（每周关闭的问题数） |\n\n高注意力分数表明该标签既重要又被忽视——需要采取干预措施。\n\n### 可视化布局\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ 🎪 ATTENTION VIEW │\n├──────┬────────────┬───────────┬─────────────────────────────────────────────┤\n│ Rank │ Label │ Attention │ Reason │\n├──────┼────────────┼───────────┼─────────────────────────────────────────────┤\n│ 1 │ api │ 2.45 │ blocked=5 stale=3 vel=0.8 │\n│ 2 │ auth │ 1.89 │ blocked=2 stale=4 vel=1.2 │\n│ 3 │ infra │ 1.23 │ blocked=1 stale=6 vel=0.5 │\n│ 4 │ frontend │ 0.67 │ blocked=0 stale=1 vel=3.5 │\n│ 5 │ docs │ 0.34 │ blocked=0 stale=2 vel=2.1 │\n└──────┴────────────┴───────────┴─────────────────────────────────────────────┘\n```\n\n### 结果解读\n\n- **高注意力 + 低速度**：该领域停滞不前——需调查阻塞因素。\n- **高注意力 + 高陈旧度**：工作被遗忘——重新浮现并重新优先级排序。\n- **低注意力 + 高速度**：健康领域——保持势头。\n- **高阻塞数量**：依赖关系造成瓶颈。\n\n### 导航\n\n| 键 | 操作 |\n|-----|--------|\n| `j` \u002F `k` | 在标签之间移动 |\n| `]` \u002F `Esc` | 退出注意力视图 |\n\n### 机器人命令\n\n```bash\nbv --robot-label-attention --attention-limit=10\n```\n\n---\n\n## 📚 快捷键侧边栏：持久化的键盘参考\n\n按下 `;`（分号）或 `F2` 切换 **快捷键侧边栏**——一个与当前视图上下文相关的持久化面板，显示键盘快捷键。\n\n### 为什么是侧边栏（而不是简单的帮助）？\n\n`?` 帮助覆盖层会显示快捷键，但会遮挡您的视图。而快捷键侧边栏在您工作时始终可见，非常适合：\n- 学习键盘快捷键而不打断工作流程\n- 在复杂导航时快速参考\n- 在结对编程时指导新用户\n\n### 上下文感知\n\n侧边栏会自动筛选快捷键，仅显示与当前视图相关的快捷键：\n\n| 上下文 | 显示的部分 |\n|---------|----------------|\n| 列表视图 | 导航、过滤器、视图、操作 |\n| 看板视图 | 导航、看板特定、泳道 |\n| 图形视图 | 导航、平移、缩放 |\n| 洞察视图 | 导航、面板、切换 |\n| 历史视图 | 导航、视图模式、时间线 |\n\n### 可视化布局\n\n```\n┌──────────────────────────────────────────────┬──────────────────────┐\n│ │ ⌨️ SHORTCUTS │\n│ │ ────────────────── │\n│ Main Content Area │ │\n│ │ Navigation │\n│ (List, Board, Graph, etc.) │ j\u002Fk Move ↓\u002F↑ │\n│ │ G\u002Fgg End\u002FStart │\n│ │ ^d\u002F^u Page ↓\u002F↑ │\n│ │ │\n│ │ Views │\n│ │ b Board │\n│ │ g Graph │\n│ │ i Insights │\n│ │ │\n│ │ ; to hide │\n└──────────────────────────────────────────────┴──────────────────────┘\n```\n\n### 侧边栏控制\n\n| 键 | 操作 |\n|-----|--------|\n| `;` 或 `F2` | 切换侧边栏的可见性 |\n| `Ctrl+J` | 向下滚动侧边栏（当可见时） |\n| `Ctrl+K` | 向上滚动侧边栏（当可见时） |\n\n侧边栏占据终端右侧固定宽度为34个字符。\n\n---\n\n## 🎓 交互式教程系统\n\n按下 `` ` ``（反引号）打开 **交互式教程**——一个全面的多页引导，通过丰富且样式化的内容教授所有 bv 功能。\n\n### 教程架构\n\n教程使用 **基于组件的渲染系统**，生成美观的终端输出：\n\n| 组件 | 目的 | 示例 |\n|-----------|---------|---------|\n| **Section** | 带下划线的样式标题 | `## 导航` |\n| **Paragraph** | 自动换行的流畅文本 | 解释性文字 |\n| **KeyTable** | 对齐的按键-描述对 | `j\u002Fk` → 上下移动 |\n| **Tip** | 高亮显示的提示框 | 💡 提示：按 g 跳转... |\n| **Warning** | 用于重要提示的警告框 | ⚠️ 警告：此操作... |\n| **Code** | 语法高亮的代码块 | `bv --robot-triage` |\n| **Bullet** | 样式化的项目符号列表 | • 第一项 |\n| **Tree** | 层次结构展示 | 目录树 |\n| **StatusFlow** | 可视化的流程图 | 开始 → 进行中 → 完成 |\n| **InfoBox** | 带边框的信息面板 | 功能亮点 |\n\n### 教程章节\n\n教程深入涵盖了以下主题：\n\n1. **简介** — bv 是什么以及存在的意义\n2. **核心概念** — 珠子、依赖关系、标签、优先级\n3. **列表视图** — 导航、过滤、排序\n4. **看板视图** — 看板工作流、泳道\n5. **图形视图** — 依赖关系可视化\n6. **树形视图** — 父子层级关系\n7. **洞察仪表盘** — 图形指标深度解析\n8. **历史视图** — 与 Git 的关联\n9. **机器人协议** — AI 代理集成\n10. **工作流程** — 分诊、计划、冲刺管理\n\n### 进度跟踪\n\n本教程会自动记录您已查看的页面：\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ 📖 教程 第3页\u002F共10页 · 30% ████░░░░│\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ ## 列表视图导航 │\n│ ───────────────────────── │\n│ │\n│ 列表视图是您的主界面。使用 Vim 风格的快捷键进行导航： │\n│ │\n│ j \u002F k 向下 \u002F 向上移动 │\n│ g \u002F G 跳转到顶部 \u002F 底部 │\n│ Ctrl+D\u002FU 向下 \u002F 向上翻页 │\n│ │\n│ ╭──────────────────────────────────────────────────────────────────────╮ │\n│ │ 💡 小贴士 按 `\u002F` 键搜索，然后输入问题标题中的任意部分 │ │\n│ ╰──────────────────────────────────────────────────────────────────────╯ │\n│ │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ ← h 上一页 │ l 下一页 → │ t 目录 │ q 关闭 │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n进度会在不同会话间保持，因此您可以关闭 bv 并从上次停止的地方继续。\n\n### 教程导航\n\n| 快捷键 | 功能 |\n|--------|------|\n| `h` \u002F `l` 或 `←` \u002F `→` | 上一页 \u002F 下一页 |\n| `j` \u002F `k` | 内容上下滚动 |\n| `t` | 切换目录 |\n| `g` \u002F `G` | 第一页 \u002F 最后一页 |\n| `q` \u002F `Esc` | 关闭教程 |\n\n### 上下文敏感过滤\n\n当您从特定视图打开教程时（例如，在看板视图中按下 `` ` ``），教程会自动筛选出与该上下文相关的页面。这样可以为新用户提供专注的学习体验，而不会让他们感到不知所措。\n\n### 快速参考与完整教程\n\nbv 提供两种帮助级别：\n\n| 功能 | 快捷键 | 用途 |\n|------|--------|------|\n| **快速参考** | `?` | 当前视图的简洁键盘快捷键 |\n| **完整教程** | `` ` `` | 包含示例的多页引导 |\n| **快捷键侧边栏** | `;` | 工作时持续显示的参考信息 |\n\n从快速参考界面，按 `Space` 键即可直接进入完整教程。\n\n---\n\n## 📜 历史视图：珠子与提交的关联\n\n按 `h` 键可打开 **历史视图**——一个交互式时间线，将珠子与其相关的 Git 提交关联起来。这有助于弥合“计划的工作”与“实际编写的代码”之间的差距。\n\n### 关联引擎\n\n`pkg\u002Fcorrelation` 包实现了一个 **多策略关联系统**，通过多种技术推断珠子和提交之间的关系：\n\n```mermaid\ngraph TD\n %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8f5e9', 'lineColor': '#90a4ae'}}}%%\n\n subgraph strategies [\"🔍 关联策略\"]\n E[\"显式提及\u003Cbr\u002F>\u003Csmall>提交包含珠子 ID\u003C\u002Fsmall>\"]\n T[\"时间邻近性\u003Cbr\u002F>\u003Csmall>提交靠近珠子事件\u003C\u002Fsmall>\"]\n C[\"共同提交分析\u003Cbr\u002F>\u003Csmall>文件一起被修改\u003C\u002Fsmall>\"]\n P[\"路径匹配\u003Cbr\u002F>\u003Csmall>文件路径与珠子范围一致\u003C\u002Fsmall>\"]\n end\n\n subgraph scorer [\"📊 置信度评分器\"]\n S[\"多因素评分\u003Cbr\u002F>\u003Csmall>加权组合\u003C\u002Fsmall>\"]\n end\n\n subgraph output [\"📈 输出\"]\n H[\"BeadHistory\u003Cbr\u002F>\u003Csmall>事件 + 提交 + 里程碑\u003C\u002Fsmall>\"]\n end\n\n E --> S\n T --> S\n C --> S\n P --> S\n S --> H\n\n classDef strategy fill:#e3f2fd,stroke:#90caf9,stroke-width:2px,color:#1565c0\n classDef score fill:#fff8e1,stroke:#ffcc80,stroke-width:2px,color:#e65100\n classDef out fill:#e8f5e9,stroke:#a5d6a7,stroke-width:2px,color:#2e7d32\n\n class E,T,C,P strategy\n class S score\n class H out\n```\n\n### 关联策略\n\n| 策略 | 权重 | 工作原理 |\n|----------|--------|--------------|\n| **显式提及** | 高 | 提交消息中包含珠子 ID（例如：`fix(auth): 解决竞态条件 [BV-123]`） |\n| **时间邻近性** | 中 | 提交时间戳落在珠子的有效生命周期窗口内 |\n| **共同提交分析** | 中 | 经常一起修改的文件表明具有共同目的 |\n| **路径匹配** | 低 | 文件路径与珠子的标签范围一致（例如：`pkg\u002Fauth\u002F*` 对应 `auth` 标签） |\n\n### 置信度评分\n\n每项关联都会获得一个 **置信度分数**（0.0–1.0），计算公式如下：\n\n$$\n\\text{置信度} = w_1 \\cdot \\text{显式} + w_2 \\cdot \\text{时间} + w_3 \\cdot \\text{共同提交} + w_4 \\cdot \\text{路径}\n$$\n\n默认权重：显式=0.5，时间=0.25，共同提交=0.15，路径=0.10\n\n### 历史视图布局\n\n历史视图采用 **响应式三栏布局**，可根据终端宽度自适应调整：\n\n| 宽度 | 布局 |\n|-------|--------|\n| **\u003C 100** | 单栏：带内嵌详情的列表 |\n| **100-160** | 双栏：列表 + 详情 |\n| **> 160** | 三栏：列表 + 时间线 + 详情 |\n\n**宽屏终端（三栏）布局：**\n```\n┌─────────────────────────────────────────────────────────────────────────────────┐\n│ 📜 历史视图 [珠子模式] [≥ 0.5] │\n├───────────────────────┬───────────────────┬─────────────────────────────────────┤\n│ 珠子 │ 时间线 │ 提交详情 │\n│ ───────────────── │ ───────────── │ ───────────────────────── │\n│ ▸ BV-123 (3次提交) │ ┃ │ abc1234 - 修复认证竞态 │\n│ 🎯 BV-456 (1次) │ ━╋━ 1月15日 │ 作者: alice@example.com │\n│ 🔗 BV-789 (5次) │ ┃ ▪▪▪ │ 日期: 2025-01-15 14:32 │\n│ 📁 BV-100 (2次) │ ━╋━ 1月14日 │ 置信度: 0.85（显式） │\n│ │ ┃ ▪ │ │\n│ │ ━╋━ 1月13日 │ 修改的文件: │\n│ │ ┃ ▪▪▪▪▪ │ M pkg\u002Fauth\u002Fsession.go │\n└───────────────────────┴───────────────────┴─────────────────────────────────────┘\n```\n\n### 时间线面板（`t` 切换）\n\n按 `t` 键可显示或隐藏 **时间线面板**——一张展示项目活动密度的可视化图表：\n\n- **纵轴**：时间（最新在顶部）\n- **横条**：活动密度（每日提交次数）\n- **条形大小**：▪ = 1-2 次，▪▪ = 3-5 次，▪▪▪ = 6-10 次，▪▪▪▪ = 11 次及以上\n- **亮点**：选定珠子的提交会用 `━` 标记\n\n点击或导航到某一天，即可将视图筛选到该时间段。\n\n### 因果标记\n\n每个珠子与提交的关联都会以可视化标记展示其**检测方法**：\n\n| 标记 | 含义 | 置信度 |\n|--------|---------|------------|\n| **🎯 直接** | 提交信息明确提及珠子 ID | 高（0.8-1.0） |\n| **🔗 时间** | 提交发生在珠子的有效生命周期内 | 中等（0.4-0.7） |\n| **📁 文件** | 提交触及与珠子相关的文件 | 低（0.2-0.5） |\n\n### 视图模式\n\n按 `v` 键可在两种视图模式之间切换：\n\n| 模式 | 显示内容 | 使用场景 |\n|------|-------|----------|\n| **珠子模式**（默认） | 将珠子与其相关联的提交分组 | “哪些提交与此任务相关？” |\n| **Git 模式** | 按时间顺序显示提交及其相关联的珠子 | “此提交涉及哪些任务？” |\n\n### 基于文件的下钻视图（`f` 键）\n\n按 `f` 键可切换到**文件模式**——一个按目录分组的更改文件树形视图：\n\n```\n┌─────────────────────────────────────────────────────────────────────────┐\n│ 📁 文件模式 [12个文件] │\n├─────────────────────────────────────────────────────────────────────────┤\n│ ▼ pkg\u002Fauth\u002F │\n│ session.go 42 处改动 BV-123, BV-456 │\n│ token.go 18 处改动 BV-123 │\n│ middleware.go 8 处改动 BV-789 │\n│ ▼ pkg\u002Fapi\u002F │\n│ handler.go 25 处改动 BV-100 │\n│ routes.go 12 处改动 BV-100, BV-456 │\n└─────────────────────────────────────────────────────────────────────────┘\n```\n\n导航至某个文件并按 `Enter` 键，即可查看所有触及该文件的珠子和提交。\n\n### 历史导航\n\n| 键 | 动作 |\n|-----|--------|\n| **导航** | |\n| `j` \u002F `k` | 在主面板（珠子或提交）中移动 |\n| `J` \u002F `K` | 在次级面板（提交或详情）中移动 |\n| `Tab` | 循环焦点：列表 → 时间线 → 详情 |\n| `Enter` | 展开\u002F折叠或深入选择项 |\n| **视图模式** | |\n| `v` | 切换珠子模式 ↔ Git 模式 |\n| `f` | 切换基于文件的下钻视图 |\n| `t` | 切换时间线面板的可见性 |\n| **筛选** | |\n| `c` | 循环置信度阈值（0.0 → 0.3 → 0.5 → 0.7） |\n| `\u002F` | 搜索提交或珠子 |\n| **操作** | |\n| `y` | 将选中的提交 SHA 复制到剪贴板 |\n| `o` | 在浏览器中打开提交（GitHub\u002FGitLab） |\n| `V` | 预览所选珠子的会话记录 |\n| `Esc` | 返回列表视图 |\n\n### 机器人命令：`--robot-history`\n\n```bash\nbv --robot-history # 完整历史报告\nbv --robot-history --bead-history BV-123 # 单个珠子聚焦\nbv --robot-history --history-since '30天前'\nbv --robot-history --min-confidence 0.7 # 仅高置信度\n```\n\n**输出格式：**\n```json\n{\n \"stats\": {\n \"total_beads\": 58,\n \"beads_with_commits\": 42,\n \"total_commits\": 156,\n \"avg_cycle_time_hours\": 72.5,\n \"method_distribution\": {\n \"explicit\": 89,\n \"temporal\": 45,\n \"cocommit\": 22\n }\n },\n \"histories\": {\n \"BV-123\": {\n \"events\": [...],\n \"commits\": [...],\n \"milestones\": [...],\n \"cycle_time_hours\": 48.2\n }\n },\n \"commit_index\": {\n \"abc1234\": [\"BV-123\", \"BV-456\"]\n }\n}\n```\n\n---\n\n## 🔗 关联分析：影响网络与相关工作\n\n除了简单的珠子与提交之间的关联外，`bv` 还提供了关于珠子如何通过共享代码变更相互关联的**深度分析**。这有助于识别隐藏的依赖关系、查找相关工作，并理解变更的真实影响。\n\n### 影响网络图\n\n影响网络基于以下内容可视化珠子之间的**隐式关系**：\n\n```mermaid\ngraph LR\n %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e3f2fd', 'lineColor': '#90a4ae'}}}%%\n\n subgraph connections [\"🔗 边类型\"]\n SC[\"共享提交\u003Cbr\u002F>\u003Csmall>同一份提交同时触及两个珠子\u003C\u002Fsmall>\"]\n SF[\"共享文件\u003Cbr\u002F>\u003Csmall>两个珠子修改了相同的文件\u003C\u002Fsmall>\"]\n DEP[\"依赖\u003Cbr\u002F>\u003Csmall>显式的阻塞关系\u003C\u002Fsmall>\"]\n end\n\n classDef edge fill:#fff8e1,stroke:#ffcc80,stroke-width:2px\n class SC,SF,DEP edge\n```\n\n| 边类型 | 权重 | 含义 |\n|-----------|--------|---------|\n| **共享提交** | 高 | 一份提交同时引用了两个珠子（强耦合） |\n| **共享文件** | 中等 | 两个珠子都触及了同一个源文件 |\n| **依赖** | 显式 | 来自问题跟踪系统的直接阻塞关系 |\n\n### 网络聚类\n\n`bv` 使用社区发现算法自动检测紧密连接的珠子**集群**：\n\n```\n┌─────────────────────────────────────────────────────────────────────────┐\n│ 🔗 影响网络 [3个集群] │\n├─────────────────────────────────────────────────────────────────────────┤\n│ │\n│ ┌─── 集群 1：认证模块 ───┐ ┌─── 集群 2：API 层 ───┐ │\n│ │ BV-123 ←──→ BV-456 │ │ BV-789 ←──→ BV-100 │ │\n│ │ ↕ ↕ │ │ ↕ │ │\n│ │ BV-321 ←──→ BV-654 │────→│ BV-111 │ │\n│ └──────────────────────────────┘ └─────────────────────────────┘ │\n│ │\n│ 中心珠子：BV-123（度数最高） │\n│ 内部连通性：0.85（紧密耦合） │\n│ 外部边：1（指向 API 层集群） │\n└─────────────────────────────────────────────────────────────────────────┘\n```\n\n### 文件到珠子的查找\n\n使用 `--robot-file-beads` 可以找到所有触及特定文件的珠子：\n\n```bash\nbv --robot-file-beads pkg\u002Fui\u002Fboard.go\n```\n\n返回按最近程度排序的珠子及提交详情：\n\n```json\n{\n \"file_path\": \"pkg\u002Fui\u002Fboard.go\",\n \"total_beads\": 21,\n \"open_beads\": [],\n \"closed_beads\": [\n {\n \"bead_id\": \"bv-v67w\",\n \"title\": \"Board: Integration & Polish\",\n \"status\": \"closed\",\n \"commit_shas\": [\"abc123\"],\n \"last_touch\": \"2025-12-18T00:19:21-05:00\",\n \"total_changes\": 17\n }\n ]\n}\n```\n\n**应用场景：**\n- **代码所有权**：“最近谁在维护这个文件？”\n- **影响分析**：“哪些工作项受到这个文件的影响？”\n- **Bug 调查**：“哪些变更可能导致了这次回归？”\n\n### 孤儿提交检测\n\n使用 `--robot-orphans` 查找本应与珠子关联但未关联的提交：\n\n```bash\nbv --robot-orphans\n```\n\n返回可能的珠子匹配候选提交：\n\n```json\n{\n \"stats\": {\n \"total_commits\": 500,\n \"correlated_count\": 242,\n \"orphan_count\": 258,\n \"orphan_ratio\": 0.516\n },\n \"candidates\": [\n {\n \"sha\": \"abc1234\",\n \"message\": \"feat: add auth caching\",\n \"suspicion_score\": 100,\n \"probable_beads\": [\n {\n \"bead_id\": \"bv-xyz\",\n \"confidence\": 65,\n \"reasons\": [\"touches file pkg\u002Fauth\u002Fcache.go\", \"same author worked on bead nearby\"]\n }\n ]\n }\n ]\n}\n```\n\n**用例：**\n- **卫生检查**：查找未正确关联的遗漏提交\n- **审计**：确保所有代码变更都追踪到工作项\n- **相关性改进**：通过确认或拒绝建议来训练系统\n\n### 相关工作发现\n\n对于任意珠子，`bv` 可以从四个维度找到其**相关工作**：\n\n| 关系类型 | 检测方式 | 示例 |\n|---------------|--------------|---------|\n| **文件重叠** | 两个珠子修改相同的源文件 | “BV-123 和 BV-456 都涉及 `session.go` 文件” |\n| **提交重叠** | 两个珠子在同一份提交中被引用 | “BV-123 和 BV-456 在提交 `abc123` 中被修复” |\n| **依赖簇** | 两者处于同一个紧密连接的子图中 | “BV-123 与 BV-456 同属认证模块” |\n| **同时进行** | 在同一时间段内活跃 | “BV-123 和 BV-456 上周都在开发中” |\n\n每种关系都包含一个**相关性评分**（0–100），表示其强度。\n\n### 机器人命令\n\n```bash\n# 获取完整的影响力网络（使用 \"all\" 获取完整图）\nbv --robot-impact-network all\n\n# 获取聚焦于特定珠子的子网络（默认深度为 2，最大 3）\nbv --robot-impact-network bv-123 --network-depth 2\n\n# 查找某珠子的相关工作\nbv --robot-related bv-123\n\n# 在相关工作结果中包含已关闭的珠子\nbv --robot-related bv-123 --related-include-closed\n\n# 调整相关工作的阈值\nbv --robot-related bv-123 --related-min-relevance 30 --related-max-results 20\n\n# 分析某珠子的因果链（时间线、阻塞点、洞察）\nbv --robot-causality bv-123\n\n# 查找接触过某个文件的珠子\nbv --robot-file-beads pkg\u002Fauth\u002Fsession.go\n\n# 查找孤儿提交（未关联珠子的提交）\nbv --robot-orphans\n```\n\n### 因果链分析\n\n`--robot-causality` 命令通过重建事件时间线，揭示**为何某珠子耗时如此之久**：\n\n| 事件类型 | 描述 |\n|------------|-------------|\n| `created` | 珠子被创建 |\n| `claimed` | 工作开始（状态变为 in_progress） |\n| `commit` | 与珠子关联的代码提交 |\n| `blocked` | 珠子因其他珠子而被阻塞 |\n| `unblocked` | 阻塞依赖被解决 |\n| `closed` | 珠子完成 |\n| `reopened` | 珠子在关闭后重新开启 |\n\n**提供的洞察：**\n- **阻塞比例**：等待依赖的时间占比\n- **关键路径**：决定最小完成时间的事件链\n- **最长停滞期**：识别需要调查的停滞阶段\n- **建议**：可操作的建议（例如：“考虑将任务拆分为更小的珠子”）\n\n**因果链输出模式：**\n```json\n{\n \"generated_at\": \"2025-01-15T14:32:00Z\",\n \"data_hash\": \"abc123...\",\n \"chain\": {\n \"bead_id\": \"bv-123\",\n \"title\": \"实现认证缓存\",\n \"status\": \"closed\",\n \"events\": [\n {\"id\": 1, \"type\": \"created\", \"timestamp\": \"2025-01-10T10:00:00Z\"},\n {\"id\": 2, \"type\": \"claimed\", \"timestamp\": \"2025-01-10T11:00:00Z\", \"caused_by_id\": 1},\n {\"id\": 3, \"type\": \"blocked\", \"timestamp\": \"2025-01-11T09:00:00Z\", \"blocker_id\": \"bv-456\"},\n {\"id\": 4, \"type\": \"unblocked\", \"timestamp\": \"2025-01-12T16:00:00Z\"},\n {\"id\": 5, \"type\": \"commit\", \"timestamp\": \"2025-01-13T10:00:00Z\", \"commit_sha\": \"abc1234\"},\n {\"id\": 6, \"type\": \"closed\", \"timestamp\": \"2025-01-13T17:00:00Z\"}\n ],\n \"edge_count\": 5,\n \"total_time\": \"79h0m0s\",\n \"is_complete\": true\n },\n \"insights\": {\n \"total_duration\": \"79h0m0s\",\n \"blocked_duration\": \"31h0m0s\",\n \"active_duration\": \"48h0m0s\",\n \"blocked_percentage\": 39.2,\n \"blocked_periods\": [\n {\"start_time\": \"2025-01-11T09:00:00Z\", \"end_time\": \"2025-01-12T16:00:00Z\", \"blocker_id\": \"bv-456\"}\n ],\n \"commit_count\": 1,\n \"critical_path_desc\": \"created → claimed → blocked → unblocked → commit → closed\",\n \"summary\": \"该珠子总共耗时 79 小时；其中 39% 时间被 bv-456 阻塞\",\n \"recommendations\": [\"建议提前解除 bv-456 的阻塞，以减少等待时间\"]\n }\n}\n```\n\n### 相关性反馈系统\n\n通过确认或拒绝相关性建议来训练相关性引擎：\n\n```bash\n# 解释某相关性的存在原因\nbv --robot-explain-correlation abc1234:bv-xyz\n\n# 确认正确的相关性（提升置信度）\nbv --robot-confirm-correlation abc1234:bv-xyz\n\n# 拒绝错误的相关性（移除该关联）\nbv --robot-reject-correlation abc1234:bv-xyz\n\n# 查看反馈统计信息\nbv --robot-correlation-stats\n```\n\n**反馈统计输出：**\n```json\n{\n \"total_feedback\": 15,\n \"confirmed\": 12,\n \"rejected\": 3,\n \"accuracy_rate\": 0.80,\n \"avg_confirm_conf\": 0.85,\n \"avg_reject_conf\": 0.42\n}\n```\n\n这一反馈循环会随着时间推移提高相关性的准确性——确认的相关性会强化模式识别能力，而拒绝则有助于消除误报。\n\n**影响力网络输出模式：**\n```json\n{\n \"generated_at\": \"2025-01-15T14:32:00Z\",\n \"data_hash\": \"abc123...\",\n \"stats\": {\n \"total_nodes\": 58,\n \"total_edges\": 142,\n \"cluster_count\": 5,\n \"avg_degree\": 4.9,\n \"density\": 0.086,\n \"isolated_nodes\": 3\n },\n \"clusters\": [\n {\n \"cluster_id\": 1,\n \"bead_ids\": [\"BV-123\", \"BV-456\", \"BV-321\"],\n \"label\": \"认证模块\",\n \"internal_connectivity\": 0.85,\n \"central_bead\": \"BV-123\",\n \"shared_files\": [\"pkg\u002Fauth\u002Fsession.go\", \"pkg\u002Fauth\u002Ftoken.go\"]\n }\n ],\n \"edges\": [\n {\"from_bead\": \"BV-123\", \"to_bead\": \"BV-456\", \"edge_type\": \"shared_commit\", \"weight\": 5}\n ]\n}\n```\n\n---\n\n## 🤖 Cass 集成：AI 会话关联（可选）\n\n`bv` 可选择集成 [**cass**](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fcoding_agent_session_search)（Claude 助手会话存储）——一款用于捕获和索引 Claude 等 AI 助手编码会话的工具。当安装 cass 后，`bv` 会自动利用会话级洞察增强其关联能力。\n\n### 工作原理\n\n```mermaid\ngraph LR\n %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e8f5e9', 'lineColor': '#90a4ae'}}}%%\n\n CASS[\"🤖 cass\u003Cbr\u002F>\u003Csmall>会话存储\u003C\u002Fsmall>\"]\n BV[\"⚡ bv\u003Cbr\u002F>\u003Csmall>问题查看器\u003C\u002Fsmall>\"]\n CORR[\"🔗 增强的\u003Cbr\u002F>关联功能\"]\n\n CASS --> BV\n BV --> CORR\n\n classDef tool fill:#e3f2fd,stroke:#90caf9,stroke-width:2px\n class CASS,BV,CORR tool\n```\n\n**优雅降级**：若未安装 cass，`bv` 仍可正常工作——不会出现错误、UI 破裂或加载状态。只是 cass 的功能不可用而已。\n\n### 检测与状态\n\n`bv` 在启动时会自动检测 cass 的状态：\n\n| 状态 | 标识 | 含义 |\n|------------|-------------|----------------------------------------|\n| **健康** | 状态栏中的 🤖 | cass 已安装、已索引并就绪 |\n| **需索引** | 状态栏中的 ⚠️ | cass 已安装，但需要运行 `cass index` |\n| **未安装** | （无） | cass 未在 PATH 中——功能被隐藏 |\n\n### 会话预览模态框（`V` 键）\n\n在任意 bead 上按下 `V` 键，即可打开 **会话预览模态框**，其中展示了可能对该问题有贡献的 AI 编码会话：\n\n```\n┌─────────────────────────────────────────────────────────────────────────┐\n│ 🤖 BV-123 的相关编码会话 │\n├─────────────────────────────────────────────────────────────────────────┤\n│ │\n│ ▸ 会话 1（claude-opus-4） 12月15日 下午2:30 │\n│ “实现会话刷新超时处理…” │\n│ 置信度：0.92（明确提及） │\n│ │\n│ 会话 2（claude-opus-4） 12月14日 上午10:15 │\n│ “重构令牌验证中间件…” │\n│ 置信度：0.67（文件重叠） │\n│ │\n│ 会话 3（claude-opus-4） 12月13日 下午4:45 │\n│ “为认证服务添加重试逻辑…” │\n│ 置信度：0.45（时间相关） │\n│ │\n├─────────────────────────────────────────────────────────────────────────┤\n│ j\u002Fk：导航 y：复制搜索命令 Enter：查看完整会话 │\n└─────────────────────────────────────────────────────────────────────────┘\n```\n\n**会话关联方法：**\n\n| 方法 | 权重 | 含义 |\n|----------------|------|----------------------------------------|\n| **明确提及** | 0.9–1.0 | 会话中直接提到 bead ID |\n| **文件重叠** | 0.5–0.8 | 会话涉及与该 bead 相关的文件 |\n| **时间相关** | 0.3–0.6 | 会话发生于 bead 的活跃生命周期内 |\n| **关键词匹配** | 0.2–0.5 | 会话包含来自 bead 标题或描述的关键词 |\n\n### 状态栏指示器\n\n当 cass 处于健康状态时，状态栏会显示代理活动：\n\n```\n┌────────────────────────────────────────────────────────────────────────┐\n│ 📋 437 个问题 • 🤖 claude-opus-4（活跃） • 最后：5 分钟前 │\n└────────────────────────────────────────────────────────────────────────┘\n```\n\n| 状态 | 显示 | 含义 |\n|----------|------------|----------------------------------------|\n| **活跃** | 🤖 代理名称 | 近 15 分钟内正在进行会话 |\n| **空闲** | 💤 | 无近期会话 |\n\n### 安装 Cass\n\n```bash\n# 安装 cass（完整文档请参见 https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fcoding_agent_session_search）\nbrew install dicklesworthstone\u002Ftap\u002Fcass # macOS\n# 或\ncargo install cass # 从源码安装\n\n# 索引你的编码会话\ncass index\n\n# 验证集成\nbv # 查看状态栏中是否有 🤖\n```\n\n### Cass 增强的历史视图\n\n当 cass 可用时，历史视图将具备以下额外功能：\n\n- **会话时间线**：按 `V` 键可同时查看会话和提交记录\n- **代理归属**：了解是哪位 AI 助手对代码变更做出了贡献\n- **增强搜索**：可在提交记录和会话中进行联合搜索\n\n---\n\n## 📅 Sprint 仪表板：燃尽图与进度跟踪\n\n按下 `P` 键（大写）即可打开 **Sprint 仪表板**，这是一个全面展示 sprint 进度的视图，包含燃尽图可视化、范围变更跟踪以及风险项检测。\n\n### 仪表板布局\n\n```\n┌─────────────────────────────────────────────────────────────────────────┐\n│ 📅 Sprint：2025年1月 │\n│ ─────────────────────────────────────────────────────────────────── │\n│ 日期：1月6日 → 1月20日 │\n│ 剩余：5天 │\n│ │\n│ ══════════════════════════════════════════════════════════════════ │\n│ 进度 │\n│ ══════════════════════════════════════════════════════════════════ │\n│ │\n│ 总数：24 个 bead 已关闭：18个（75%） 剩余：6个 │\n│ [████████████████████░░░░░░] 75% │\n│ │\n│ ══════════════════════════════════════════════════════════════════ │\n│ 燃尽图 │\n│ ══════════════════════════════════════════════════════════════════ │\n│ │\n│ 24 ┤ · │\n│ 20 ┤ ····· │\n│ 16 ┤ ····▸ │\n│ 12 ┤ ╲ （理想） │\n│ 8 ┤ ╲ │\n│ 4 ┤ ╲ │\n│ 0 ┼────────────────────────────────────────────────────────────── │\n│ 1月6日 1月13日 1月20日 │\n│ │\n│ 图例：· = 实际 ╲ = 理想 ▸ = 今日 │\n│ │\n│ ══════════════════════════════════════════════════════════════════ │\n│ 范围变更 │\n│ ══════════════════════════════════════════════════════════════════ │\n│ │\n│ 1月8日：新增 2 个 bead（BV-456、BV-457） │\n│ 1月10日：移除 1 个 bead（BV-100 被移至待办列表） │\n│ │\n│ ══════════════════════════════════════════════════════════════════ │\n│ 风险项 │\n│ ══════════════════════════════════════════════════════════════════ │\n│ │\n│ ⚠ BV-789（P0 严重） - 已阻塞 3 天 │\n│ ⚠ BV-234（P1 高） - 已 5 天未有进展 │\n└─────────────────────────────────────────────────────────────────────────┘\n```\n\n### 燃尽图计算\n\n燃尽图采用一种**范围感知算法**，不仅跟踪完成速度，还跟踪范围的变化：\n\n1. **理想燃尽速率**：`总任务数 \u002F Sprint 时长`\n2. **实际燃尽速率**：`已完成任务数 \u002F 已经过的天数`\n3. **范围事件**：新增或移除的任务会在理想线上产生断点。\n\n当在 Sprint 中间添加任务时，燃尽图会从该点重新计算理想轨迹，从而提供一个更真实的进度视图，而不是误导性的“落后于计划”指示。\n\n### 风险检测\n\n根据多种启发式规则，项目会被标记为有风险：\n\n| 信号 | 阈值 | 原因 |\n|--------|-----------|--------|\n| **阻塞时长** | > 2 天 | 依赖瓶颈 |\n| **无活动** | > 4 天 | 可能卡住或被遗忘 |\n| **高优先级阻塞** | P0\u002FP1 阻塞 | 关键路径障碍 |\n| **依赖未解决** | 阻塞项仍未关闭 | 连锁延迟风险 |\n\n### 机器人命令\n\n```bash\nbv --robot-sprint-list # 列出所有 Sprint\nbv --robot-sprint-show sprint-1 # 查看特定 Sprint 的详细信息\nbv --robot-burndown current # 当前活跃 Sprint 的燃尽图\nbv --robot-burndown sprint-1 # 特定 Sprint 的燃尽图\n```\n\n**燃尽图输出：**\n```json\n{\n \"sprint_id\": \"sprint-1\",\n \"total_days\": 14,\n \"elapsed_days\": 9,\n \"remaining_days\": 5,\n \"total_issues\": 24,\n \"completed_issues\": 18,\n \"remaining_issues\": 6,\n \"ideal_burn_rate\": 1.71,\n \"actual_burn_rate\": 2.0,\n \"projected_complete\": \"2025-01-18\",\n \"on_track\": true,\n \"scope_changes\": [\n {\"date\": \"2025-01-08\", \"delta\": 2, \"reason\": \"新增 BV-456、BV-457\"}\n ]\n}\n```\n\n---\n\n## 🏷️ 标签分析：领域中心的健康监控\n\n按下 `L`（大写）可打开**标签仪表板**——一个表格视图，显示项目中每个标签的健康指标。这有助于通过揭示代码库中哪些区域需要关注来实现**领域驱动的优先级排序**。\n\n### 标签仪表板布局\n\n```\n┌─────────────────────────────────────────────────────────────────────────┐\n│ 🏷️ 标签健康 │\n├──────────────┬────────┬────────┬────────┬────────┬────────┬────────────┤\n│ 标签 │ 健康度 │ 状态 │ 开放 │ 阻塞│ 老化 │ 流量 │\n├──────────────┼────────┼────────┼────────┼────────┼────────┼────────────┤\n│ 🔴 api │ 0.32 │ CRIT │ 12 │ 5 │ 3 │ 0.8\u002F周 │\n│ 🟡 auth │ 0.58 │ WARN │ 8 │ 2 │ 1 │ 2.1\u002F周 │\n│ 🟢 ui │ 0.85 │ OK │ 4 │ 0 │ 0 │ 4.2\u002F周 │\n│ 🟢 docs │ 0.92 │ OK │ 2 │ 0 │ 0 │ 1.5\u002F周 │\n│ 🟡 infra │ 0.61 │ WARN │ 6 │ 1 │ 2 │ 1.2\u002F周 │\n└──────────────┴────────┴────────┴────────┴────────┴────────┴────────────┘\n```\n\n### 健康度计算\n\n标签健康度综合了多个因素：\n\n$$\n\\text{健康} = 1 - \\left( w_1 \\cdot \\frac{\\text{阻塞数}}{\\text{开放数}} + w_2 \\cdot \\frac{\\text{老化数}}{\\text{开放数}} + w_3 \\cdot (1 - \\text{流量评分}) \\right)\n$$\n\n| 组件 | 权重 | 含义 |\n|-----------|--------|---------|\n| **阻塞比例** | 0.4 | 高阻塞数量表明存在瓶颈 |\n| **老化比例** | 0.3 | 老化问题暗示疏忽 |\n| **流量倒数** | 0.3 | 低吞吐量表明容量问题 |\n\n### 健康等级\n\n| 等级 | 分数范围 | 指示 | 行动 |\n|-------|-------------|-----------|--------|\n| **严重** | 0.0 – 0.4 | 🔴 | 需立即处理 |\n| **警告** | 0.4 – 0.7 | 🟡 | 密切监控 |\n| **健康** | 0.7 – 1.0 | 🟢 | 进展正常 |\n\n### 用于标签分析的机器人命令\n\n**`--robot-label-health`**：按标签显示健康指标 \n```bash\nbv --robot-label-health\nbv --robot-label-health | jq '.results.labels[] | select(.health_level == \"critical\")'\n```\n\n**`--robot-label-flow`**：跨标签依赖关系矩阵 \n```bash\nbv --robot-label-flow\nbv --robot-label-flow | jq '.flow.bottleneck_labels'\n```\n\n**`--robot-label-attention`**：按关注度排序的标签，用于优先级排序 \n```bash\nbv --robot-label-attention --attention-limit=5\n```\n\n### 标签范围内的分析\n\n使用 `--label` 参数可以将任何机器人命令限定在特定标签的子图范围内：\n\n```bash\nbv --robot-insights --label api # 仅针对 api 标签的问题生成图表指标\nbv --robot-plan --label backend # 针对 backend 领域的执行计划\nbv --robot-priority --label auth # 针对 auth 工作的优先级建议\n```\n\n这实现了**领域隔离**：可以在一个限定的上下文中进行分析和规划，而不是在整个项目图上操作。\n\n### 流量矩阵：跨标签依赖关系\n\n流量矩阵展示了标签之间的依赖关系：\n\n```\n → api → auth → ui → docs\napi - 3 2 0\nauth 1 - 0 1\nui 4 2 - 0\ndocs 0 0 0 -\n```\n\n解读为：“api 有 3 个问题依赖于 auth 的问题。” 高数值表示领域之间的耦合；`bottleneck_labels` 字段则突出显示阻碍最多跨领域工作的标签。\n\n---\n\n## 🌐 静态站点导出：可共享的仪表板\n\n`bv` 可以生成**自包含的静态网站**，方便与没有终端访问权限的利益相关者分享项目状态。\n\n### 交互式向导\n\n```bash\nbv --pages\n```\n\n启动一个交互式向导，引导您完成以下步骤：\n1. **导出**：生成静态资源包\n2. **预览**：本地服务器地址为 `http:\u002F\u002Flocalhost:9000`（或下一个可用端口）\n3. **部署**：推送到 GitHub Pages，并自动创建仓库\n\n### 直接导出\n\n```bash\nbv --export-pages .\u002Fbv-pages # 导出到指定目录\nbv --export-pages .\u002Fbv-pages --pages-title \"Sprint 42 Status\"\nbv --export-pages .\u002Fbv-pages --pages-exclude-closed # 排除已完成的问题\nbv --export-pages .\u002Fbv-pages --pages-exclude-history # 排除 Git 历史记录\n\n# 预览现有资源包，无需重新生成\nbv --preview-pages .\u002Fbv-pages # 在 localhost:9000（或下一个可用端口）提供服务\n```\n\n### 可选：混合搜索 WASM 计分器\n\n对于非常大的数据集，您可以构建一个可选的 WASM 计分器，供静态查看器使用。\n\n```bash\n# 一次性构建（需要 wasm-pack）\n.\u002Fscripts\u002Fbuild_hybrid_wasm.sh\n\n# 或在导出时构建\nBV_BUILD_HYBRID_WASM=1 bv --export-pages .\u002Fbv-pages\n```\n\n如果缺少 `wasm\u002F` 资源，查看器会自动回退到 JS 计分器。\n\n### 生成的内容\n\n```\n.\u002Fbv-pages\u002F\n├── index.html # 主仪表板，使用 Alpine.js + Tailwind\n├── beads.sqlite3 # 完整的 SQLite 数据库（约 2MB，包含 400 多个问题）\n├── data\u002F\n│ ├── graph_layout.json # 预先计算的位置和指标（约 82KB）\n│ ├── meta.json # 导出元数据\n│ ├── triage.json # 分类建议\n│ └── history.json # 问题与提交的关联数据\n└── vendor\u002F\n ├── d3.v7.min.js # 可视化库\n ├── force-graph.min.js # 图形渲染\n └── bv_graph.js # WASM 图形引擎\n```\n\n### 图形可视化：渲染速度提升16倍\n\n导出采用**混合架构**，实现图形的即时加载：\n\n| 组件 | 大小 | 用途 |\n|-----------|------|---------|\n| `graph_layout.json` | ~82KB | 预计算的节点位置 + 图谱指标 |\n| `beads.sqlite3` | ~2MB | 完整的问题数据，用于详情面板、搜索和表格 |\n\n**工作原理：**\n1. 浏览器首先加载极小的 `graph_layout.json`（宽带下约100毫秒）。\n2. 使用预计算的 `fx`\u002F`fy` 固定位置，图形立即渲染。\n3. SQLite 并行加载，以支持搜索和详情功能。\n4. 完全跳过力导向模拟——无抖动，无布局延迟。\n\n**性能对比：**\n\n| 指标 | 未预计算 | 已预计算 |\n|--------|---------------------|------------------|\n| 初始加载 | 4+秒 | ~250毫秒 |\n| 力导向模拟 | 2+秒 | 0毫秒（已跳过） |\n| 图形数据 | 914KB（冗余） | 82KB（精简） |\n\n### 详情面板\n\n点击任意节点即可打开一个**400px宽的滑动详情面板**：\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│ │ ╭─────────────────────────╮ │\n│ │ │ BV-123: 认证重构 │ │\n│ [交互式图] │ │ ─────────────────────── │ │\n│ │ │ 优先级：P1（高） │ │\n│ ⬤ │ │ 类型：功能 │ │\n│ \u002F│\\ │ │ 状态：进行中 │ │\n│ \u002F │ \\ │ │ │ │\n│ ⬤ ⬤ ⬤ │ │ **描述** │ │\n│ │ │ 重构认证模块... │ │\n│ │ │ │ │\n│ │ │ ⛔ 3个阻塞项 │ │\n│ │ │ 📤 阻塞了5个问题 │ │\n│ │ ╰─────────────────────────╯ │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n**详情面板包含：**\n- 完整的问题标题和描述（Markdown渲染）\n- 优先级、类型、状态及可视化标识\n- **阻塞项数量**（“⛔ 3个阻塞项”）——必须先完成的问题\n- **被阻塞问题数量**（“📤 阻塞了5个问题”）——等待此问题解决的下游工作\n- PageRank、介数中心性等指标（来自预计算数据）\n\n### 功能特性\n\n- **全文搜索**：SQLite FTS5 提供跨所有问题标题和描述的即时搜索。结果随键入显示，无需服务器。\n- **交互式图**：使用 D3.js 力导向图可视化依赖关系，支持缩放、平移和节点选择。\n- **详情面板**：点击任意节点可查看完整问题详情及依赖信息。\n- **分类视图**：与 `--robot-triage` 提供的建议相同。\n- **离线支持**：首次加载后无需网络即可使用。\n- **移动端响应式**：适配手机\u002F平板屏幕，提供触控友好的交互体验。\n\n### 技术说明\n\n静态导出采用**混合架构**，结合以下组件：\n\n1. **纯Go SQLite**（[modernc.org\u002Fsqlite](https:\u002F\u002Fmodernc.org\u002Fsqlite)）：\n - 无需C编译器——可在任何系统上运行，无需CGO。\n - 跨平台打包生成。\n - 内置FTS5全文搜索。\n\n2. **预计算图布局**：\n - BFS层次布局，按深度分配X坐标。\n - 节点位置存储为 `[x, y]` 对。\n - 指标存储为紧凑的5元素数组：`[pagerank, betweenness, inDegree, outDegree, inCycle]`。\n - 相比完整图JSON，文件大小缩减约91%。\n\n3. **WASM图引擎**（`bv_graph.js`）：\n - 客户端侧环检测。\n - 高效的邻居查找。\n - 用于阻塞链的路径查找。\n\n### 部署选项\n\n| 平台 | 命令 | 备注 |\n|----------|---------|-------|\n| **GitHub Pages** | `bv --pages`（向导） | 自动创建 `gh-pages` 分支 |\n| **Cloudflare Pages** | `bv --export-pages .\u002Fdist` + CF控制台 | 连接至Git仓库 |\n| **任何静态托管服务** | `bv --export-pages .\u002Fdist` | Netlify、Vercel、S3等 |\n\n---\n\n## 🚨 警报系统：主动健康监测\n\n警报系统能够在问题演变为阻塞之前，提前发现潜在风险。它结合了**漂移检测**（与基线的偏差）和**主动分析**（基于模式的警告）。\n\n### 警报类型\n\n| 类型 | 触发条件 | 严重程度 | 示例 |\n|------|---------|----------|---------|\n| `stale_issue` | 30天以上无更新 | 警告 | “BV-123自10月15日以来未被处理” |\n| `blocking_cascade` | 一个问题阻塞5个及以上问题 | 严重 | “AUTH-001正在阻塞8个下游任务” |\n| `priority_mismatch` | 优先级低但PageRank高 | 警告 | “BV-456优先级为P3，但PageRank排名第二” |\n| `cycle_introduced` | 新出现循环依赖 | 严重 | “检测到循环：A → B → C → A” |\n| `scope_creep` | 开放问题数量增加20%以上 | 信息 | “本周开放问题从45个增至58个” |\n\n### TUI集成\n\n按下 `!` 键即可打开**警报面板**：\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ 🚨 警报（3条活跃） [!] 关闭 │\n├─────────────────────────────────────────────────────────────┤\n│ ⚠️ 警告：bv-123已闲置45天 │\n│ 🔴 严重：bv-456阻塞8个任务（级联风险） │\n│ ℹ️ 信息：本冲刺周期开放问题增加了23% │\n├─────────────────────────────────────────────────────────────┤\n│ j\u002Fk 导航 • Enter 跳转至问题 • d 屏蔽 • q 关闭 │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### 机器人集成\n\n```bash\n# 获取所有警报的JSON格式\nbv --robot-alerts\n\n# 按严重程度筛选（信息、警告、严重）\nbv --robot-alerts --severity=critical\n\n# 按类型筛选\nbv --robot-alerts --alert-type=blocking_cascade\n\n# 按受影响标签筛选\nbv --robot-alerts --alert-label=backend\n```\n\n### 输出格式\n\n```json\n{\n \"alerts\": [\n {\n \"type\": \"blocking_cascade\",\n \"severity\": \"critical\",\n \"issue_id\": \"bv-456\",\n \"message\": \"阻塞8个下游任务\",\n \"blocked_ids\": [\"bv-101\", \"bv-102\", \"...\"],\n \"suggested_action\": \"优先完成或拆分为更小的任务\"\n }\n ],\n \"summary\": {\n \"total\": 3,\n \"critical\": 1,\n \"warning\": 1,\n \"info\": 1\n }\n}\n```\n\n---\n\n## 🤖 完整CLI参考\n\n除了交互式TUI外，`bv`还提供全面的**命令行接口**，适用于脚本编写、自动化以及AI代理集成。\n\n### 核心命令\n\n```bash\nbv # 启动交互式TUI\nbv --help # 显示所有选项\nbv --version # 显示版本号\n```\n\n### 机器人协议命令\n\n这些命令会输出专为程序化消费设计的**结构化 JSON**：\n\n| 命令 | 输出 | 使用场景 |\n|---------|--------|----------|\n| `--robot-triage` | **超级命令**：包含所有分析的统一分类 | 代理的单一入口点 |\n| `--robot-next` | 单个最高推荐项 + 执行命令 | 快速回答“下一步是什么？” |\n| `--robot-insights` | 图形指标 + 前N名列表 | 项目健康评估 |\n| `--robot-plan` | 可执行的任务轨道 + 依赖关系 | 工作队列生成 |\n| `--robot-priority` | 优先级建议 | 自动化优先级修复 |\n| `--robot-history` | 提交与问题的关联 | 代码变更追踪 |\n| `--robot-label-health` | 按标签的健康指标 | 领域健康监控 |\n| `--robot-label-flow` | 标签间依赖矩阵 | 跨领域分析 |\n| `--robot-label-attention` | 按关注度排序的标签 | 领域优先级排序 |\n| `--robot-sprint-list` | 所有冲刺以 JSON 格式 | 冲刺计划 |\n| `--robot-burndown` | 冲刺燃尽数据 | 进度跟踪 |\n| `--robot-suggest` | 卫生建议（依赖、重复、标签、循环） | 项目清理自动化 |\n| `--robot-diff` | JSON 差异（配合 `--diff-since`） | 变更追踪 |\n| `--robot-recipes` | 可用配方列表 | 配方发现 |\n| `--robot-graph` | 依赖关系图以 JSON\u002FDOT\u002FMermaid 格式 | 图表可视化与导出 |\n| `--robot-forecast` | 按问题预测的 ETA | 完成时间预估 |\n| `--robot-capacity` | 团队容量模拟 | 资源规划 |\n| `--robot-alerts` | 偏离预警 + 主动警告 | 健康监控 |\n| `--robot-help` | 详细 AI 代理文档 | 代理入职 |\n\n所有机器人命令都支持 `--as-of \u003Cref>` 用于历史分析。指定后，输出将包含 `as_of` 和 `as_of_commit` 元数据字段。\n\n### 时间旅行命令\n\n`--as-of` 标志允许您在不修改工作树的情况下查看项目的任意历史状态。它既适用于交互式 TUI，也适用于所有机器人命令。\n\n```bash\n# 查看历史状态（TUI）\nbv --as-of HEAD~10 # 10 次提交之前\nbv --as-of v1.0.0 # 在发布标签处\nbv --as-of 2024-01-15 # 在特定日期\nbv --as-of main@{2024-01-15} # 分支在该日期的状态\n\n# 使用机器人命令进行历史分析\nbv --robot-insights --as-of HEAD~30 # 30 次提交前的图形指标\nbv --robot-plan --as-of v1.0.0 # 发布时的执行计划\nbv --robot-triage --as-of 2024-06-01 # 特定日期的全面分类\nbv --robot-priority --as-of HEAD~5 # 5 次提交前的优先级建议\n\n# 比较变更\nbv --diff-since HEAD~5 # 最近 5 次提交的变更\nbv --diff-since v1.0.0 # 自发布以来的变更\nbv --diff-since 2024-01-01 # 自该日期以来的变更\n\n# JSON 差异输出（结合 `--as-of` 获取“到”快照）\nbv --diff-since HEAD~10 --robot-diff # 从 HEAD~10 到当前\nbv --diff-since HEAD~10 --as-of HEAD~5 --robot-diff # 从 HEAD~10 到 HEAD~5\n```\n\n当使用 `--as-of` 与机器人命令结合时，JSON 输出会包含额外的元数据：\n- `as_of`: 您指定的引用（例如，“HEAD~30”、“v1.0.0”）\n- `as_of_commit`: 解析后的提交 SHA，以确保可重复性\n\n### 配方命令\n\n```bash\n# 列出可用配方\nbv --robot-recipes\n\n# 应用内置配方\nbv --recipe actionable # 立即可执行\nbv --recipe high-impact # PageRank 得分最高的\nbv --recipe stale # 30 天以上未触碰\nbv --recipe blocked # 等待依赖解决\nbv -r recent # 短标志，7 天内更新\n\n# 应用自定义配方\nbv --recipe .beads\u002Frecipes\u002Fsprint.yaml\n```\n\n### 导出命令\n\n```bash\n# 生成带有 Mermaid 图的 Markdown 报告\nbv --export-md report.md\n\n# 导出优先级简报（重点摘要）\nbv --priority-brief brief.md\n\n# 导出完整的代理简报包\nbv --agent-brief .\u002Fagent-bundle\u002F\n# 生成：triaje.json、insights.json、brief.md、helpers.md\n```\n\n### ETA 预测与容量规划\n\n```bash\n# 预测特定问题的完成 ETA\nbv --robot-forecast bv-123\n\n# 对所有开放问题进行预测并筛选\nbv --robot-forecast all --forecast-label=backend\nbv --robot-forecast all --forecast-sprint=sprint-1\nbv --robot-forecast all --forecast-agents=2 # 多代理并行处理\n\n# 容量模拟：什么时候所有任务都能完成？\nbv --robot-capacity # 默认：1 个代理\nbv --robot-capacity --agents=3 # 3 个并行代理\nbv --robot-capacity --capacity-label=frontend # 限定于特定标签\n```\n\n### 警报与健康监控\n\n```bash\n# 获取所有警报（偏离预警 + 主动健康检查）\nbv --robot-alerts\n\n# 按严重程度筛选\nbv --robot-alerts --severity=critical\nbv --robot-alerts --severity=warning\n\n# 按警报类型筛选\nbv --robot-alerts --alert-type=stale_issue\nbv --robot-alerts --alert-type=blocking_cascade\n\n# 按标签范围筛选\nbv --robot-alerts --alert-label=backend\n```\n\n### 分类分组（多代理协调）\n\n```bash\n# 按执行轨道对建议进行分组（并行工作流）\nbv --robot-triage --robot-triage-by-track\n\n# 按标签对建议进行分组（领域专注代理）\nbv --robot-triage --robot-triage-by-label\n```\n\n### Shell 脚本生成\n\n从建议中生成可执行的 Shell 脚本，用于自动化工作流：\n\n```bash\n# 为前 5 条建议生成 Bash 脚本\nbv --robot-triage --emit-script --script-limit=5\n\n# 不同的 Shell 格式\nbv --robot-triage --emit-script --script-format=fish\nbv --robot-triage --emit-script --script-format=zsh\n```\n\n### 反馈系统（自适应建议）\n\n反馈系统会根据您的接受或忽略决定来调整建议权重：\n\n```bash\n# 记录正面反馈（您已执行此建议）\nbv --feedback-accept bv-123\n\n# 记录负面反馈（您跳过了此建议）\nbv --feedback-ignore bv-456\n\n# 查看当前反馈状态及权重调整\nbv --feedback-show\n\n# 将反馈重置为默认值\nbv --feedback-reset\n```\n\n### 基线与漂移检测\n\n```bash\n# 将当前状态保存为基线\nbv --save-baseline \"Pre-release v2.0\"\n\n# 显示基线信息\nbv --baseline-info\n\n# 检查是否偏离基线\nbv --check-drift # 退出码：0=正常，1=严重，2=警告\nbv --check-drift --robot-drift # JSON 输出\n```\n\n### 语义搜索\n\n```bash\n# 对标题\u002F描述进行语义向量搜索\nbv --search \"login oauth\"\n\n# 用于自动化的 JSON 输出\nbv --search \"login oauth\" --robot-search\n\n# 混合搜索（文本 + 图形指标）\nbv --search \"login oauth\" --search-mode hybrid --search-preset impact-first\n\n# 混合模式，自定义权重\nbv --search \"login oauth\" --search-mode hybrid \\\n --search-weights '{\"text\":0.4,\"pagerank\":0.2,\"status\":0.15,\"impact\":0.1,\"priority\":0.1,\"recency\":0.05}'\n```\n\n语义搜索会基于加权的问题文档（ID 和标题重复，包含标签和描述）构建一个轻量级向量索引。这样既能保持快速查找，又能像人类可读的搜索一样工作。\n\n混合模式是一个两阶段的流程：首先根据语义相似度检索出最相关的候选问题，然后使用图感知信号（PageRank、状态、影响、优先级、最近性）对这些候选问题进行重新排序。这使得结果既紧扣查询内容，又能突出依赖关系图中最重要的项目——非常符合 bv 的目标，即让“为什么这件事重要”一目了然。\n\n对于简短且意图明确的查询（例如“benchmarks”、“oauth”），bv 会特意采取不同的处理方式。它会扩大候选池，提升精确匹配的权重，并提高文本相关性的权重，从而使快速查找表现得更像一次精准搜索。而对于较长、描述性更强的查询，则更多地依赖图信号来进行智能的并列解决和优先级排序。\n\n混合模式的默认设置可以通过以下方式配置：\n- `BV_SEARCH_MODE`（text|hybrid）\n- `BV_SEARCH_PRESET`（default|bug-hunting|sprint-planning|impact-first|text-only）\n- `BV_SEARCH_WEIGHTS`（JSON 字符串，会覆盖预设值）\n\n在 `--robot-search` 的 JSON 输出中，混合模式的结果会包含 `mode`、`preset`、`weights`，以及每个结果的 `text_score` 和 `component_scores`。\n\n### 示例：AI 代理工作流\n\n```bash\n#!\u002Fbin\u002Fbash\n# agent-workflow.sh - 自动化任务选择\n\n# 1. 获取执行计划\nPLAN=$(bv --robot-plan)\n\n# 2. 提取最具影响力的可执行任务\nTASK=$(echo \"$PLAN\" | jq -r '.plan.summary.highest_impact')\n\n# 3. 获取完整洞察以提供上下文\nINSIGHTS=$(bv --robot-insights)\n\n# 4. 检查完成此任务是否会引入回归\nBASELINE=$(bv --diff-since HEAD~1 --robot-diff)\n\necho \"正在处理：$TASK\"\necho \"将解除阻塞：$(echo \"$PLAN\" | jq '.plan.summary.unblocks_count') 个任务\"\n```\n\n### 输出示例\n\n**`--robot-priority` 输出：**\n```json\n{\n \"generated_at\": \"2025-01-15T10:30:00Z\",\n \"recommendations\": [\n {\n \"issue_id\": \"CORE-123\",\n \"current_priority\": 3,\n \"suggested_priority\": 1,\n \"confidence\": 0.87,\n \"direction\": \"increase\",\n \"reasoning\": \"高 PageRank（0.15）+ 高介数中心性（0.45）表明这是一个基础性阻塞问题\"\n }\n ],\n \"summary\": {\n \"total_issues\": 58,\n \"recommendations\": 12,\n \"high_confidence\": 5\n }\n}\n```\n\n**`--robot-recipes` 输出：**\n```json\n{\n \"recipes\": [\n { \"name\": \"actionable\", \"description\": \"可立即处理（无阻塞）\", \"source\": \"builtin\" },\n { \"name\": \"high-impact\", \"description\": \"PageRank 得分最高\", \"source\": \"builtin\" },\n { \"name\": \"sprint-review\", \"description\": \"当前冲刺中的问题\", \"source\": \"project\" }\n ]\n}\n```\n\n---\n\n## 🏢 多仓库工作区支持\n\n对于单体仓库和多包架构，`bv` 提供了 **工作区配置**，可以将多个仓库中的问题统一到一个连贯的视图中。\n\n### 工作区配置文件（`.bv\u002Fworkspace.yaml`）\n\n```yaml\n# .bv\u002Fworkspace.yaml - 多仓库工作区定义\nname: my-workspace\n\nrepos:\n - name: api\n path: services\u002Fapi\n prefix: \"api-\" # 问题会变成 api-AUTH-123\n beads_path: .beads # 可选的仓库级覆盖（默认为 .beads）\n\n - name: web\n path: apps\u002Fweb\n prefix: \"web-\" # 问题会变成 web-UI-456\n\n - name: shared\n path: packages\u002Fshared\n prefix: \"lib-\" # 问题会变成 lib-UTIL-789\n\ndiscovery:\n enabled: true\n patterns:\n - \"*\" # 直接子目录\n - \"packages\u002F*\" # npm\u002Fpnpm 工作空间\n - \"apps\u002F*\" # Next.js\u002FTurborepo\n - \"services\u002F*\" # 微服务\n - \"libs\u002F*\" # 库包\n exclude:\n - node_modules\n - vendor\n - .git\n max_depth: 2\n\ndefaults:\n beads_path: .beads # 在每个仓库中查找 beads.jsonl 的位置\n```\n\n### ID 命名空间\n\n当跨多个仓库工作时，问题会自动进行命名空间划分：\n\n| 本地 ID | 仓库前缀 | 命名空间 ID |\n|----------|-------------|---------------|\n| `AUTH-123` | `api-` | `api-AUTH-123` |\n| `UI-456` | `web-` | `web-UI-456` |\n| `UTIL-789` | `lib-` | `lib-UTIL-789` |\n\n### 跨仓库依赖关系\n\n工作区系统支持 **跨仓库的阻塞关系**：\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ web-UI-456 (apps\u002Fweb) │\n│ “实现 OAuth 登录页面” │\n│ │\n│ 阻塞：api-AUTH-123、lib-UTIL-789 │\n└─────────────────────────────────────────────────────────┘\n │ │\n ▼ ▼\n┌─────────────────┐ ┌─────────────────┐\n│ api-AUTH-123 │ │ lib-UTIL-789 │\n│ (services\u002Fapi) │ │ (packages\u002Flib) │\n│ “认证端点” │ │ “令牌工具” │\n└─────────────────┘ └─────────────────┘\n```\n\n### 工作区内筛选\n\n使用 `--repo` 参数可以将视图（以及机器人输出）限定到特定的仓库前缀。匹配不区分大小写，并接受常见的分隔符（`-`、`:`、`_`）；如果存在 `source_repo` 字段，则会优先考虑该字段。\n\n### 支持的单体仓库布局\n\n| 布局 | 模式 | 示例项目 |\n|--------|---------|------------------|\n| **npm\u002Fpnpm 工作空间** | `packages\u002F*` | Lerna、Turborepo |\n| **Next.js 应用** | `apps\u002F*` | Vercel 单体仓库 |\n| **微服务** | `services\u002F*` | 后端平台 |\n| **Go 模块** | `modules\u002F*` | 多模块 Go 项目 |\n| **扁平结构** | `*` | 简单的单体仓库 |\n\n### ID 解析\n\n`IDResolver` 会智能地处理跨仓库引用：\n\n```go\nresolver := NewIDResolver(config, \"api\")\n\n\u002F\u002F 从 api 仓库上下文中：\nresolver.Resolve(\"AUTH-123\") \u002F\u002F → {Namespace: \"api-\", LocalID: \"AUTH-123\"}\nresolver.Resolve(\"web-UI-456\") \u002F\u002F → {Namespace: \"web-\", LocalID: \"UI-456\"}\nresolver.IsCrossRepo(\"web-UI-456\") \u002F\u002F → true\nresolver.DisplayID(\"api-AUTH-123\") \u002F\u002F → \"AUTH-123\"（本地，去掉前缀）\nresolver.DisplayID(\"web-UI-456\") \u002F\u002F → \"web-UI-456\"（跨仓库，保留前缀）\n```\n\n---\n\n## ⏰ 交互式时间旅行模式\n\n除了 CLI 中的 diff 命令之外，`bv` 还支持在 TUI 内部进行 **交互式时间旅行**。该模式会在问题列表上叠加差异标记，让你直观地探索哪些内容发生了变化。\n\n### 激活时光旅行模式\n\n在主列表视图中按下 `t` 键，即可进入带有自定义修订版本提示的时光旅行模式：\n\n```\n┌──────────────────────────────────────────┐\n│ ⏱️ 时间旅行模式 │\n│ │\n│ 将当前状态与历史修订版本进行比较 │\n│ │\n│ ⏱️ 修订版本: HEAD~5█ │\n│ │\n│ 示例：HEAD~5、main、v1.0.0、 │\n│ 2024-01-01、abc123 │\n│ │\n│ 按 Enter 键比较，按 Esc 键取消 │\n└──────────────────────────────────────────┘\n```\n\n若需快速访问，可按下 `T` 键（大写），直接与 `HEAD~5` 进行比较，无需提示。\n\n### 差异徽章\n\n激活后，问题会显示视觉徽章，指示其差异状态：\n\n| 徽章 | 含义 | 颜色 |\n|-------|---------|-------|\n| `[NEW]` | 自基线以来创建的问题 | 绿色 |\n| `[CLOSED]` | 自基线以来关闭的问题 | 灰色 |\n| `[MODIFIED]` | 问题字段已更改 | 黄色 |\n| `[REOPENED]` | 自基线以来重新打开的问题 | 橙色 |\n\n### 可视化示例\n\n```\n┌────────────────────────────────────────────────────────────┐\n│ 📋 问题（自 HEAD~5 起） 总计 58 个 │\n├────────────────────────────────────────────────────────────┤\n│ [NEW] ✨ FEAT-789 添加暗色模式切换 P2 🟢 │\n│ [NEW] 🐛 BUG-456 修复登录竞争条件 P1 🟢 │\n│ [MODIFIED] 📝 TASK-123 更新文档 P3 🟡 │\n│ ✨ FEAT-100 OAuth 集成 P1 🟢 │\n│ [CLOSED] 🐛 BUG-001 解析器中的内存泄漏 P0 ⚫ │\n└────────────────────────────────────────────────────────────┘\n```\n\n### 时光旅行摘要面板\n\n页脚显示汇总统计信息：\n\n```\n─────────────────────────────────────────────────────────────\n📊 变更：+3 新建 ✓2 关闭 ~1 修改 ↺0 重新打开\n健康状况：↑ 改善中（密度：-0.02，周期：-1）\n─────────────────────────────────────────────────────────────\n```\n\n### 时光旅行导航\n\n| 键 | 操作 |\n|-----|--------|\n| `t` | 进入时光旅行（自定义修订版本提示） |\n| `T` | 快速时光旅行（HEAD~5） |\n| `t`（在时光旅行模式中） | 退出时光旅行模式 |\n| `n` | 跳转到下一个变更问题 |\n| `N` | 跳转到上一个变更问题 |\n\n---\n\n## 🧪 质量保证与鲁棒性\n\n信任是通过努力赢得的。`bv` 采用严格的测试策略，以确保它能够应对真实世界代码库中可能出现的各种复杂情况。\n\n### 1. 合成数据模糊测试\n我们不仅针对“正常路径”数据进行测试。测试套件（`pkg\u002Floader\u002Fsynthetic_test.go`）会生成**合成复杂图**——包含数千个节点、错综复杂的依赖循环以及边缘 UTF-8 字符的大规模 JSONL 文件——以验证图引擎和渲染逻辑在高负载下绝不会崩溃。\n\n### 2. 对损坏数据的鲁棒性\n在基于 Git 的工作流中，合并冲突和部分写入时有发生。`TestLoadIssuesRobustness` 测试套件会明确地向数据流中注入垃圾行和损坏的 JSON。\n* **结果：** `bv` 能够检测到损坏数据，将警告记录到 `stderr`，并继续加载有效数据。它绝不会因为一行错误数据而导致用户会话崩溃。\n\n### 贡献测试\n对于编写测试的贡献者，请参阅全面的**[测试指南](docs\u002Ftesting.md)**，其中涵盖了：\n- 测试理念（不使用模拟、表格驱动测试、黄金文件）\n- 使用 `testutil` 包生成测试用例\n- 运行测试、覆盖率和基准测试\n- E2E 测试模式及 CI 集成\n\n---\n\n## 🔄 无摩擦更新引擎\n\n`bv` 内置了一个主动且非侵入式的更新检查功能，以确保您不会错过任何新功能。我们认为工具应该能够自我维护，而不应打断您的工作流程。\n\n### 设计与实现\n更新程序（`pkg\u002Fupdater\u002Fupdater.go`）的设计宗旨是安静与安全：\n1. **非阻塞并发：** 检查会在一个独立的 goroutine 中运行，且有严格的**2 秒超时限制**。它绝不会延迟您的启动时间或影响 UI 的交互性。\n2. **语义版本控制：** 它不仅仅是简单地匹配字符串。自定义的 SemVer 比较器确保您只会收到关于严格意义上的*新版本*的通知，从而处理诸如发布候选版与稳定版等复杂边缘情况。\n3. **容错性：** 它能够优雅地处理网络分区、GitHub API 速率限制（403\u002F429）以及超时等情况，静默失败。您永远不会因为更新检查而看到崩溃或错误日志。\n4. **不显眼的通知：** 当发现更新时，`bv` 不会弹出模态窗口。它只是在页脚处显示一个低调的**有更新可用**指示符（`⭐`），让您自行决定何时升级。\n\n---\n\n## 🗂️ 数据加载与自我修复\n\n可靠性至关重要。`bv` 并不假设环境完美；它会主动处理常见的文件系统不一致性。\n\n### 1. 智能路径发现\n加载器（`pkg\u002Floader\u002Floader.go`）并不会盲目地打开 `.beads\u002Fbeads.jsonl`。它采用基于优先级的发现算法：\n1. **标准路径：** 检查 `issues.jsonl`（beads 上游推荐的格式）。\n2. **旧版路径：** 回退到 `beads.jsonl` 以保持向后兼容性。\n3. **基础路径：** 检查 `beads.base.jsonl`（由 `br` 在守护进程模式下使用）。\n4. **验证：** 它会跳过临时文件，如 `*.backup` 或 `deletions.jsonl`，以防止显示损坏的状态。\n\n### 2. 强大的解析能力\nJSONL 解析器被设计为**容错型**。\n* 它使用缓冲扫描器（`bufio.NewScanner`）配合 10MB 的宽松行长度限制，以处理巨大的描述文本块。\n* 格式错误的行（例如来自合并冲突的行）会被跳过，并发出警告，而不是导致应用程序崩溃。这样即使在糟糕的 Git 合并过程中，您仍然可以查看项目中未损坏的部分。\n\n---\n\n## 🧩 设计哲学：为何选择图？\n\n传统的任务跟踪工具（Jira、GitHub Issues、Trello）将工作视为“容器”：“待办”、“进行中”、“已完成”。这对于简单的任务列表来说尚可，但在大规模场景下却显得力不从心，因为它忽略了**结构**。\n\n在复杂的软件项目中，任务并非孤立存在，而是相互紧密关联。一个“简单”的前端任务可能依赖于后端接口，而后端接口又依赖于架构变更，而架构变更则需要迁移脚本的支持。\n\n`bv` 采用了**图优先**的理念：\n1. **结构即现实：** 依赖关系图就是整个项目本身。列表视图只是该图的一个投影而已。\n2. **明确的阻塞关系：** 我们不只是简单地“关联”任务，还会定义严格的“阻塞”关系。如果 A 阻塞 B，那么在 A 关闭之前，您根本无法在 `bv` 中将 B 标记为“就绪”。\n3. **本地优先、文本为基础：** 您的项目数据存储在您的仓库中（`.beads\u002Fbeads.jsonl`），而不是远程服务器上。它随您的代码一起移动，随着您的分支一起分叉，并随着您的 PR 一起合并。\n\n---\n\n## ⚡ 性能规格\n\n`bv` 专为速度而设计。我们相信，延迟是流畅体验的敌人。\n\n* **启动时间:** 对于典型仓库（少于 1000 个问题），启动时间小于 50 毫秒。\n* **渲染:** 使用 [Bubble Tea](https:\u002F\u002Fgithub.com\u002Fcharmbracelet\u002Fbubbletea) 实现 60 FPS 的 UI 更新。\n* **虚拟化:** 列表视图和 Markdown 渲染器完全采用窗口化技术。`bv` 能够处理包含 **10,000+ 个问题** 的仓库，而不会出现 UI 卡顿，同时占用极少的内存。\n* **图计算:** 两阶段分析器会立即计算拓扑结构、度数和密度，随后异步计算 PageRank、介数中心性、HITS、关键路径和环路，并设置与规模相关的超时机制。\n* **缓存:** 重复的分析会自动重用哈希结果，避免在珠状图未发生变化时进行重复计算。\n\n### 性能基准测试\n\n`bv` 包含一套全面的基准测试套件，用于验证性能：\n\n```bash\n# 运行所有基准测试\n.\u002Fscripts\u002Fbenchmark.sh\n\n# 将当前性能保存为基准\n.\u002Fscripts\u002Fbenchmark.sh baseline\n\n# 与基准对比（需要 benchstat）\n.\u002Fscripts\u002Fbenchmark.sh compare\n\n# 快速基准测试（CI 模式）\n.\u002Fscripts\u002Fbenchmark.sh quick\n```\n\n**基准测试类别:**\n- **完整分析:** 各种规模下的端到端 `Analyze()` 流程\n- **单个算法:** PageRank、介数中心性、HITS、拓扑排序的独立测试\n- **病态图:** 用于保护超时机制的压力测试（大量环路、完全图）\n- **超时验证:** 确保大型图不会卡死\n\n**超时保护:**\n所有耗时较长的算法（介数中心性、PageRank、HITS、环路检测）都设置了 500 毫秒的超时，以防止在大型或病态图上阻塞。\n\n**详细调优指南:**\n有关性能的全面文档，包括故障排除、基于规模的算法选择以及调优选项，请参阅 [docs\u002Fperformance.md](docs\u002Fperformance.md)。\n\n### 图引擎优化\n\n分析引擎使用一种 **紧凑的邻接表图** (`compactDirectedGraph`)，而非标准的 Gonum 基于 map 的实现。这一优化带来了显著的性能提升：\n\n| 基准测试（696 个问题） | 优化前 | 优化后 | 提升 |\n|------------------------|--------|-------|-------------|\n| 完整分类 | 67ms | 1.3ms | **快 52 倍** |\n| 完整分析 | 46ms | 477μs | **快 96 倍** |\n| 图构建 | 1.2ms | 323μs | **快 3.7 倍** |\n| 内存（图构建） | 735KB | 444KB | **减少 40%** |\n| 分配次数 | 4,647 | 2,512 | **减少 46%** |\n\n**为什么重要:** 默认的 Gonum `DirectedGraph` 使用基于 map 的边集，在图构建过程中会产生大量的内存分配。而我们的紧凑实现：\n- 在已知大小下预先分配节点数组\n- 使用 `[]int64` 邻接列表代替 `map[int64]set`\n- 完全消除了 map 扩容和重新哈希的开销\n\n**真实数据基准测试:** 运行 `go test -bench=BenchmarkRealData .\u002Fpkg\u002Fanalysis\u002F...`，以根据您项目的实际 `.beads\u002Fissues.jsonl` 数据验证性能。\n\n---\n\n## ❓ 故障排除与常见问题\n\n**Q: 我的图标显示异常 \u002F 文本对齐错位。**\n* `bv` 需要支持 **TrueColor** 的终端，并安装 **Nerd Font**。\n* *推荐:* [Nerd Fonts](https:\u002F\u002Fwww.nerdfonts.com\u002F)（例如，“JetBrains Mono Nerd Font”或“Hack Nerd Font”）。\n* *终端:* Windows Terminal、iTerm2、Alacritty、Kitty、WezTerm。\n\n**Q: 实时刷新没有更新（尤其是在 NFS\u002FSMB\u002FSSHFS\u002FFUSE 上）。**\n* 某些文件系统无法可靠地传递文件系统事件。`bv` 会尝试自动检测并切换到轮询模式。\n* 如果仍然有问题，请强制启用轮询：\n ```bash\n BV_FORCE_POLLING=1 bv\n # 或者\n BV_FORCE_POLL=1 bv\n ```\n\n**Q: 我在页脚看到 `polling …`。这有问题吗？**\n没关系——这只是表示 `bv` 正在使用轮询而不是文件系统事件来进行实时刷新（这在远程文件系统中很常见）。轮询可能会导致更新出现时稍有延迟。\n\n**Q: 我在页脚看到 `⚠ STALE` \u002F `✗ bg …` \u002F `⚠ worker unresponsive` \u002F `↻ recovered`。**\n这些提示意味着后台工作进程最近没有生成新的快照（或者需要自我修复）。请尝试按 `Ctrl+R`\u002F`F5`，检查文件系统权限和健康状况，或者暂时禁用后台模式 (`BV_BACKGROUND_MODE=0`) 来回退到同步刷新。\n\n**Q: 我在仪表盘上看到“检测到环路”。接下来该怎么办？**\n答：环路（例如 A → B → A）意味着您的项目逻辑存在缺陷，没有任何任务可以优先完成。请使用洞察仪表盘 (`i`) 查找具体的环路成员，然后使用 `br` 删除其中一条依赖关系（例如 `br unblock A --from B`）。\n\n**Q: 这个工具适用于 Jira\u002FGitHub 吗？**\n答：`bv` 是数据无关的。Beads 数据模式支持 `external_ref` 字段。如果您使用自定义脚本或同步工具将外部跟踪器中的问题填充到您的 `.beads\u002Fbeads.jsonl` 文件中，`bv` 会将其与本地任务一起渲染。未来版本的 `br` CLI 可能会支持原生同步功能，但 `bv` 目前已经可以处理这类数据了。\n\n**Q: “bead” 和 “issue” 有什么区别？**\n答：它们是一回事！在 Beads 生态系统中，工作单元被称为“bead”（这也是名称的由来）。然而，`bv` 在许多地方使用“issue”，因为这对大多数开发者来说更为熟悉。CLI 标志也交替使用这两个术语：`--robot-file-beads`、`--pages-include-closed`（issues）等。您可以将“bead”视为 Beads 特有的术语，而“issue”则是更通用的概念。\n\n---\n\n## 📦 安装\n\n### 一行安装（Linux\u002FmacOS）\n最快开始的方式。会自动检测您的操作系统和架构。\n\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash\n```\n\n### 一行安装（Windows）\n对于使用 PowerShell 的 Windows 用户：\n\n```powershell\nirm \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Fmain\u002Finstall.ps1\" | iex\n```\n\n**要求:**\n- 已安装 Go 1.21+ 并添加到 PATH 中（[下载](https:\u002F\u002Fgo.dev\u002Fdl\u002F)）\n- 为了获得最佳显示效果，请使用带有 [Nerd Font](https:\u002F\u002Fwww.nerdfonts.com\u002F) 的 [Windows Terminal](https:\u002F\u002Faka.ms\u002Fterminal)\n\n### 从源码构建\n需要 Go 1.21+。\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fbeads_viewer.git\ncd beads_viewer\ngo install .\u002Fcmd\u002Fbv\n```\n\n### Nix Flake\n对于 Nix 用户，`bv` 提供了一个 flake，用于可重复的构建和开发环境。\n\n```bash\n# 直接运行\nnix run github:Dicklesworthstone\u002Fbeads_viewer\n\n# 安装到用户配置文件\nnix profile install github:Dicklesworthstone\u002Fbeads_viewer\n\n# 开发环境，包含 Go 工具链\nnix develop github:Dicklesworthstone\u002Fbeads_viewer\n```\n\n或者将以下内容添加到您的 flake 输入中：\n```nix\n{\n inputs.bv.url = \"github:Dicklesworthstone\u002Fbeads_viewer\";\n # 使用：bv.packages.${system}.default\n}\n```\n\n---\n\n## 🚀 使用指南\n\n导航到任何使用 `br init` 初始化的项目，然后运行：\n\n```bash\nbv\n```\n\n### 🎓 获取帮助\n\nbv 内置了全面的帮助系统：\n\n**快速参考** (`?`) - 在任意位置按下即可查看当前视图的快捷键。从这里按 `Space` 键可直接跳转到完整教程。\n\n**交互式教程** (`` ` `` 反引号) - 多页指南，涵盖所有功能：\n- 概念：珠子、依赖关系、标签、优先级\n- 视图：列表、看板、图谱、树状图、洞察、历史\n- 工作流：AI 代理集成、分类处理、计划制定\n- 进度会自动保存——您可以从中断处继续。\n\n### 键盘控制表\n\n| 上下文 | 键 | 动作 |\n| :--- | :---: | :--- |\n| **全局导航** | `j` \u002F `k` | 下一个\u002F上一个项目 |\n| | `g` \u002F `G` | 跳至顶部\u002F底部 |\n| | `Ctrl+D` \u002F `Ctrl+U` | 向下\u002F向上翻页 |\n| | `Tab` | 切换焦点（列表 ↔ 详情） |\n| | `Enter` | 打开\u002F聚焦选中项 |\n| | `q` \u002F `Esc` | 退出\u002F返回 |\n| **筛选器** | `o` | 显示 **未完成** 问题 |\n| | `r` | 显示 **已就绪**（未阻塞） |\n| | `c` | 显示 **已完成** 问题 |\n| | `a` | 显示 **全部** 问题 |\n| | `\u002F` | **搜索**（模糊匹配） |\n| | `Ctrl+S` | 切换 **搜索模式**（语义 ↔ 模糊） |\n| | `l` | **标签选择器**（按标签快速筛选） |\n| **列表排序** | `s` | 循环切换排序模式（默认 → 创建时间升序 → 创建时间降序 → 优先级 → 更新时间） |\n| **视图切换** | `b` | 切换 **看板** |\n| | `i` | 切换 **洞察仪表板** |\n| | `g` | 切换 **图谱可视化工具** |\n| | `E` | 切换 **树状视图**（父子层级） |\n| | `a` | 切换 **可执行计划** |\n| | `h` | 切换 **历史视图**（珠子与提交的关联） |\n| | `f` | 切换 **流程矩阵**（跨标签依赖关系） |\n| | `[` | 切换 **标签仪表板**（标签健康分析） |\n| | `]` | 切换 **关注视图**（标签关注度评分） |\n| **看板** | `h` \u002F `l` | 在列之间移动 |\n| | `j` \u002F `k` | 在列内移动 |\n| **洞察仪表板** | `Tab` | 切换到下一个面板 |\n| | `Shift+Tab` | 切换到上一个面板 |\n| | `e` | 切换解释说明 |\n| | `x` | 切换计算证明 |\n| | `m` | 切换热力图叠加 |\n| **图谱视图** | `H` \u002F `L` | 向左\u002F向右滚动 |\n| | `Ctrl+D` \u002F `Ctrl+U` | 向下\u002F向上翻页 |\n| **树状视图** | `j` \u002F `k` | 光标上下移动 |\n| | `h` \u002F `l` | 折叠父节点或展开子节点 |\n| | `Enter` \u002F `Space` | 切换展开\u002F折叠 |\n| | `o` \u002F `O` | 展开全部\u002F折叠全部 |\n| | `g` \u002F `G` | 跳至顶部\u002F底部 |\n| **时间旅行与分析** | `t` | 时间旅行模式（自定义版本） |\n| | `T` | 快速时间旅行（HEAD~5） |\n| | `p` | 切换优先级提示叠加 |\n| **操作** | `x` | 导出为 Markdown 文件 |\n| | `C` | 将问题复制到剪贴板 |\n| | `O` | 在编辑器中打开 |\n| **帮助与学习** | `?` | 切换帮助覆盖层（快捷键） |\n| | `` ` `` | 打开交互式教程（进度已保存） |\n| **全局** | `;` | 切换快捷键侧边栏 |\n| | `!` | 切换 **警报面板**（主动预警） |\n| | `'` | 食谱选择器 |\n| | `w` | 仓库选择器（工作区模式） |\n\n---\n\n## 🛠️ 配置\n\n`bv` 会自动检测终端能力，以呈现最佳 UI。它会在当前目录中查找 `.beads\u002Fbeads.jsonl` 文件。\n\n### 环境变量\n\n| 变量 | 描述 | 默认值 |\n|----------|-------------|---------|\n| `BEADS_DIR` | 自定义珠子目录路径。设置后将覆盖默认的 `.beads` 目录查找。 | 当前工作目录下的 `.beads` |\n| `BV_BACKGROUND_MODE` | 实验性功能：启用后台快照加载，实现 TUI 的实时重载（`1`\u002F`0`）。 | （禁用） |\n| `BV_FORCE_POLLING` | 强制使用轮询方式的实时重载（适用于 NFS\u002FSMB\u002FSSHFS\u002FFUSE 或任何文件系统事件不可靠的环境）（`1`\u002F`0`）。 | （自动） |\n| `BV_FORCE_POLL` | `BV_FORCE_POLLING` 的别名。 | （自动） |\n| `BV_DEBOUNCE_MS` | 后台模式下实时重载事件的防抖窗口（毫秒）。 | `200` |\n| `BV_CHANNEL_BUFFER` | 后台工作线程与 UI 之间的消息缓冲区大小。 | `8` |\n| `BV_HEARTBEAT_INTERVAL_S` | 后台工作线程的心跳间隔（秒）。 | `5` |\n| `BV_WATCHDOG_INTERVAL_S` | 后台工作线程的看门狗间隔（秒）。 | `10` |\n| `BV_FRESHNESS_WARN_S` | 快照过时警告阈值（秒）。 | `30` |\n| `BV_FRESHNESS_STALE_S` | 快照过时严重阈值（秒）。 | `120` |\n| `BV_MAX_LINE_SIZE_MB` | JSONL 文件每行的最大大小（MB）。超过此大小的行将被跳过并发出警告。 | `10` |\n| `BV_SKIP_PHASE2` | 跳过第二阶段的图谱指标计算（中心性、环路、关键路径）（`1`\u002F`0`）。 | （禁用） |\n| `BV_PHASE2_TIMEOUT_S` | 重写第二阶段各指标的超时时间（秒）。 | （基于文件大小） |\n| `BV_SEMANTIC_EMBEDDER` | 用于 `bv --search` 和 TUI 语义模式的语义嵌入提供商。 | `hash` |\n| `BV_SEMANTIC_DIM` | 语义搜索索引的嵌入维度。 | `384` |\n| `BV_SEMANTIC_MODEL` | 语义搜索特定提供商的模型名称（可选）。 | （空） |\n\n**`BEADS_DIR` 的使用场景：**\n- **单体仓库**：多个包共享同一个珠子目录\n- **非标准布局**：`.beads` 不在工作目录中的项目\n- **测试**：指向测试用例而不改变目录\n- **跨目录访问**：从文件系统的任意位置查看珠子\n\n```bash\n# 示例：指向不同的珠子目录\nBEADS_DIR=\u002Fpath\u002Fto\u002Fshared\u002Fbeads bv\n\n# 示例：在单体仓库中使用\nexport BEADS_DIR=$(git rev-parse --show-toplevel)\u002F.beads\n```\n\n### 实验性功能：后台模式（实时重载）\n\nTUI 可以通过 **实验性后台快照工作线程** 实现实时重载（将文件 I\u002FO 和分析从 UI 线程中移出）。\n\n**启用（需手动开启）：**\n```bash\nBV_BACKGROUND_MODE=1 bv\nbv --background-mode\n```\n\n**禁用\u002F回滚：**\n```bash\nBV_BACKGROUND_MODE=0 bv\nbv --no-background-mode\n```\n\n**用户配置文件（当 CLI 标志和 `BV_BACKGROUND_MODE` 均未设置时）：**\n```yaml\n# ~\u002F.config\u002Fbv\u002Fconfig.yaml\nexperimental:\n background_mode: true\n```\n\n**优先级顺序：** CLI 标志 → `BV_BACKGROUND_MODE` → `~\u002F.config\u002Fbv\u002Fconfig.yaml`。\n\n**迁移计划（高层次）：**\n- A 阶段（目前）：启用后台模式，同步模式仍为默认。\n- B 阶段：扩大推广范围；保留显式回滚选项（`--no-background-mode` \u002F `BV_BACKGROUND_MODE=0`）。\n- C 阶段：稳定后将默认模式切换为后台模式；在过渡期内仍保留同步模式作为备用。\n- D 阶段：经过弃用期后，移除旧版同步重载路径。\n\n**监控计划：** 目前暂无自动遥测；A\u002FB 阶段将依靠 CI + 回归测试以及用户反馈。\n\n### 状态指示器（后台模式 + 实时重载）\n\n当启用后台模式或实时重载时，页脚可能会显示以下指示器：\n\n- `◌ metrics…` — 第二阶段指标仍在计算中；UI 会立即使用第一阶段的数据进行渲染。\n- `⚠ 45s ago` — 快照过期警告（数据正在变得陈旧）。\n- `⚠ STALE: 3m ago` — 快照已过期。\n- `✗ bg \u003Cphase> (3x)` — 后台工作进程在构建快照时多次遇到错误（显示阶段；括号内为重试次数）。\n- `↻ recovered xN` — 监控程序已恢复后台工作进程 N 次（瞬态故障\u002F自我修复）。\n- `⚠ worker unresponsive` — 监控程序检测到工作进程卡死并正在进行恢复。\n- `polling …` — 实时重载正在使用轮询而非文件系统事件（常见于远程文件系统）；更改可能会有轻微延迟。\n\n提示：按 `Ctrl+R`（或 `F5`）可强制刷新。\n\n### 视觉主题\nUI 使用受 Dracula 原则启发的高对比度、视觉上鲜明的主题，以确保易读性。\n* **主色:** `#BD93F9`（紫色）\n* **状态：开放**:`#50FA7B`（绿色）\n* **状态：阻塞**:`#FF5555`（红色）\n\n---\n\n## 📄 许可证\n\nMIT 许可证（附带 OpenAI\u002FAnthropic 的附加条款）。详情请参阅 [LICENSE](LICENSE)。\n\n版权所有 © 2025 杰弗里·伊曼纽尔\n\n---\n\n## 🤖 为什么机器人喜欢 bv\n\n- 确定性的 JSON 协议：机器人命令会发出稳定的字段名和顺序（相同 ID 的任务按 ID 排序），并包含 `data_hash`、`analysis_config` 和 `computed_at`，以便安全地关联多次调用。\n- 健康标志：每个耗时指标都会报告其状态（`computed`、`approx`、`timeout`、`skipped`），以及所花费的毫秒数，并在采样时注明使用的样本量。\n- 一致的缓存：机器人子命令共享同一个基于问题数据哈希的分析器\u002F缓存，从而避免在 `--robot-insights`、`--robot-plan` 和 `--robot-priority` 之间出现输出不一致的情况。\n- 即时与最终完整性：第一阶段指标会立即可用；第二阶段会补充完整，而状态标志会告知您何时完成或是否降级。\n\n## 🧭 数据流概览\n\n```\n.beads\u002Fbeads.jsonl\n ↓ 容错加载器（去除 BOM、10MB 行、跳过格式错误）\n ↓ 图构建器（仅处理阻塞性依赖关系）\n ↓ 分析器（第一阶段快速；第二阶段中心性指标带有超时限制）\n ↓ 缓存（按哈希键存储）\n ↓ 输出：TUI | 机器人 JSON | 导出\u002F钩子\n```\n- 每个机器人负载中都会携带哈希值和配置信息，以便下游消费者验证一致性。\n\n## 📐 图分析算法（通俗解释）\n\n- PageRank：“阻塞权威”——拥有大量（或重要）依赖的任务。\n- Betweenness：“桥梁”——位于许多最短路径上的节点；是不同集群之间的瓶颈。\n- HITS：枢纽节点（聚合者）与权威节点（前置条件）。\n- 关键路径深度：最长的下游链长度；零松弛的关键节点。\n- 特征向量：通过有影响力的邻居传播影响力。\n- 密度、度数、拓扑排序：结构骨干。\n- 循环：通过 Tarjan SCC 和 `DirectedCyclesIn` 检测；设置超时限制并记录循环数量。\n- 每项指标都会出现在机器人洞察中，并附带状态标志，待准备就绪后会显示每项问题的得分。\n\n## ⚡ 第一阶段 vs 第二阶段\n\n- **第一阶段（即时）：** 度数、拓扑排序、密度；始终存在。\n- **第二阶段（异步）：** PageRank、Betweenness、HITS、特征向量、关键路径、循环；默认超时时间为 500 毫秒，并根据规模进行调整。状态标志会反映计算完成、近似结果、超时或跳过等情况。\n\n## ⏱️ 超时与近似语义\n\n- 每项指标的状态：`computed`（完整）、`approx`（例如，采样的 betweenness）、`timeout`（回退）、`skipped`（基于大小\u002F密度的保护机制）。\n- 负载示例：\n ```json\n {\n \"status\": {\n \"pagerank\": {\"state\":\"computed\",\"ms\":142},\n \"betweenness\": {\"state\":\"approx\",\"ms\":480,\"sample\":120},\n \"cycles\": {\"state\":\"timeout\",\"ms\":500,\"reason\":\"deadline\"}\n }\n }\n ```\n\n## 🧮 执行计划逻辑\n\n- 可执行集合：无未解决阻塞性依赖的开放\u002F进行中问题。\n- 解除阻塞：对于每个可执行问题，列出如果该问题关闭后将变为可执行的问题列表（且没有其他未解决的阻塞）。\n- 路径：无向连通分量将可执行事项分组为可并行处理的流。\n- 总结：最具影响力的项目 = 最多解除阻塞的问题，其次是优先级，最后是 ID 以保证确定性。\n\n## 🎯 优先级推荐模型\n\n- 复合评分权重：PageRank 30%，Betweenness 30%，阻塞比例 20%，陈旧程度 10%，优先级提升 10%。\n- 阈值：高 PR >0.30，高 BW >0.50，陈旧程度约 14 天，最低置信度默认为 0.30。\n- 方向：根据评分与当前优先级的比较得出“提高”或“降低”优先级的结论；置信度结合信号数量、强度和评分差来综合判断。\n\n## 🔍 差异与时间旅行安全注意事项\n\n- 当标准输出不是 TTY 或 `BV_ROBOT=1` 时，`--diff-since` 会自动输出 JSON（或在严格设置下需要使用 `--robot-diff`）；解析后的修订版本会回显在负载中。\n- TUI 时间旅行标记：`[NEW]`、`[CLOSED]`、`[MODIFIED]`、`[REOPENED]`，与机器人差异摘要相匹配。\n\n## 🛡️ 性能保障措施\n\n- 两阶段分析，配备基于规模的配置（对大型稀疏图采用近似的 betweenness，对循环设置上限，在密集的 XL 图上跳过 HITS）。\n- 每个耗时指标的默认超时时间为 500 毫秒；结果会标注状态。\n- 缓存 TTL 使重复的机器人调用在数据未变化时保持快速；若哈希不匹配，则会触发重新计算。\n- 快速基准测试：`.\u002Fscripts\u002Fbenchmark.sh quick`，或通过 `bv --profile-startup` 进行诊断。\n\n## 🧷 稳健性与自我修复\n\n- 加载器会跳过格式错误的行并发出警告，去除 UTF-8 BOM，容忍大行（10MB）。\n- Beads 文件发现顺序：issues.jsonl → beads.jsonl → beads.base.jsonl；会跳过备份、合并产物和删除清单。\n- 实时重载经过防抖处理；更新检查是非阻塞的，在网络出现问题时也能优雅失败。\n\n## 🔗 与 CI 和代理集成\n\n- 典型流水线：\n ```bash\n bv --robot-insights > insights.json\n bv --robot-plan | jq '.plan.summary'\n bv --robot-priority | jq '.recommendations[0]'\n bv --check-drift --robot-drift --diff-since HEAD~5 > drift.json\n ```\n- 使用 `data_hash` 确保所有工件来自同一次分析运行；若哈希值不一致，则 CI 测试失败。\n- 退出码：漂移检查（0 正常，1 严重，2 警告）。\n\n## 🩺 故障排除矩阵（机器人模式）\n\n- 空的指标映射 → 第二阶段仍在运行或已超时；请检查状态标志。\n- 大型负载 → 使用 jq 截取前几项；按照配方过滤后再重新运行。\n- 缺少循环 → 很可能被跳过或超时；请查看 `status.cycles`。\n- 不同命令之间的输出不一致 → 比较 `data_hash`；若不同则重新运行。\n\n## 🔒 安全与隐私注意事项\n\n- 本地优先：所有分析都在您的仓库的 JSONL 文件上进行；机器人无需联网。\n- 钩子和导出功能为可选；更新检查静默进行，即使网络出现故障也不会影响启动。\n\n---\n\n## 🙏 致谢与鸣谢\n\n`bv` 站在巨人的肩膀上。我们衷心感谢这些卓越开源项目的维护者和贡献者：\n\n### 基础\n\n| 项目 | 作者 | 描述 |\n|---------|--------|-------------|\n| [**Beads**](https:\u002F\u002Fgithub.com\u002Fsteveyegge\u002Fbeads) | Steve Yegge | 这是一个优雅的原生 Git 风格的问题跟踪系统，`bv` 就是为了配合它而构建的 |\n\n### Go 库（TUI 和 CLI）\n\n| 库 | 作者 | 我们如何使用 |\n|---------|--------|-------------------|\n| [**Bubble Tea**](https:\u002F\u002Fgithub.com\u002Fcharmbracelet\u002Fbubbletea) | [Charm](https:\u002F\u002Fcharm.sh) | 受 Elm 启发的 TUI 框架，为所有交互式界面提供支持 |\n| [**Lip Gloss**](https:\u002F\u002Fgithub.com\u002Fcharmbracelet\u002Flipgloss) | [Charm](https:\u002F\u002Fcharm.sh) | 美观的终端样式——颜色、边框、布局 |\n| [**Bubbles**](https:\u002F\u002Fgithub.com\u002Fcharmbracelet\u002Fbubbles) | [Charm](https:\u002F\u002Fcharm.sh) | 现成组件：列表、文本输入、加载指示器、视口 |\n| [**Huh**](https:\u002F\u002Fgithub.com\u002Fcharmbracelet\u002Fhuh) | [Charm](https:\u002F\u002Fcharm.sh) | 用于部署向导的交互式表单和提示 |\n| [**Glamour**](https:\u002F\u002Fgithub.com\u002Fcharmbracelet\u002Fglamour) | [Charm](https:\u002F\u002Fcharm.sh) | 在终端中带有语法高亮的 Markdown 渲染 |\n| [**modernc.org\u002Fsqlite**](https:\u002F\u002Fmodernc.org\u002Fsqlite) | modernc.org | 纯 Go 实现的 SQLite，带 FTS5 全文检索功能，用于静态站点导出 |\n| [**Gonum**](https:\u002F\u002Fgithub.com\u002Fgonum\u002Fgonum) | Gonum 作者 | 图算法：PageRank、介数中心性、强连通分量 |\n| [**fsnotify**](https:\u002F\u002Fgithub.com\u002Ffsnotify\u002Ffsnotify) | fsnotify | 文件系统监听，用于实时重载 |\n| [**clipboard**](https:\u002F\u002Fgithub.com\u002Fatotto\u002Fclipboard) | atotto | 跨平台剪贴板，用于复制到剪贴板功能 |\n\n### JavaScript 库（静态查看器）\n\n| 库 | 作者 | 我们如何使用 |\n|---------|--------|-------------------|\n| [**force-graph**](https:\u002F\u002Fgithub.com\u002Fvasturiano\u002Fforce-graph) | [Vasco Asturiano](https:\u002F\u002Fgithub.com\u002Fvasturiano) | 美丽的交互式力导向图可视化 |\n| [**D3.js**](https:\u002F\u002Fd3js.org\u002F) | Mike Bostock \u002F Observable | 数据可视化基础及图物理学 |\n| [**Alpine.js**](https:\u002F\u002Falpinejs.dev\u002F) | Caleb Porzio | 轻量级响应式 UI 框架 |\n| [**sql.js**](https:\u002F\u002Fgithub.com\u002Fsql-js\u002Fsql.js) | sql.js 贡献者 | SQLite 编译为 WebAssembly，用于客户端查询 |\n| [**Chart.js**](https:\u002F\u002Fwww.chartjs.org\u002F) | Chart.js 贡献者 | 交互式图表：燃尽图、优先级分布、热力图 |\n| [**Mermaid**](https:\u002F\u002Fmermaid.js.org\u002F) | Knut Sveidqvist | 在 Markdown 中绘制依赖关系图 |\n| [**DOMPurify**](https:\u002F\u002Fgithub.com\u002Fcure53\u002FDOMPurify) | cure53 | 安全的 XSS 防护 HTML 净化 |\n| [**Marked**](https:\u002F\u002Fmarked.js.org\u002F) | marked 贡献者 | 高速 Markdown 解析 |\n| [**Tailwind CSS**](https:\u002F\u002Ftailwindcss.com\u002F) | Tailwind Labs | 实用程序优先的 CSS 框架 |\n\n### 特别致谢\n\n- 整个 **[Charm](https:\u002F\u002Fcharm.sh)** 团队，感谢他们打造了目前最令人愉悦的终端 UI 生态系统。他们的库让构建美观的 CLI 工具变得无比轻松。\n- **[Vasco Asturiano](https:\u002F\u002Fgithub.com\u002Fvasturiano)**，感谢他出色的 `force-graph` 库以及更广泛的可视化工具生态。\n- **Steve Yegge**，感谢他提出的 Beads 理念——一种清新简洁的问题跟踪方式，充分尊重开发者的日常工作流程。\n\n> *关于贡献:* 请不要误会，我并不接受任何外部对我的项目的贡献。我真的没有精力去评审这些内容，而且这个项目是我个人的名字在负责，所以如果出现问题，我需要承担全部责任；从我的角度来看，这种风险与回报极不对称。此外，我还得担心其他“利益相关者”，这对我来说并不明智，毕竟这些工具大多是我在业余时间免费制作的。当然，你仍然可以提交问题，甚至 PR 来展示你的修复方案，但我不会直接合并它们。相反，我会让 Claude 或 Codex 通过 `gh` 工具来审查这些提交，并独立决定是否以及如何处理它们。尤其是 bug 报告，我们非常欢迎。抱歉如果这让你感到不快，但我不想浪费大家的时间，也不想伤害任何人的情感。我明白这与当前倡导社区贡献的开源精神不太一致，但这却是我能以现有速度推进工作并保持理智的唯一方式。\n\n---\n\n## 📄 许可证\n\n特此授予任何人免费获取本软件及其相关文档文件（以下简称“软件”）副本的权利，允许其不受限制地处理该软件，包括但不限于以下权利：使用、复制、修改、合并、发布、分发、再许可和\u002F或销售该软件的副本，并允许向任何获得该软件的人提供服务，但须遵守以下条件：\n\n上述版权声明和本许可声明应包含在该软件的所有副本或实质性部分中。\n\n本软件按“原样”提供，不提供任何形式的明示或暗示担保，包括但不限于适销性、特定用途适用性和非侵权性。在任何情况下，作者或版权所有者均不对因本软件或其使用或其他交易而产生的任何索赔、损害赔偿或其他责任负责，无论该责任是基于合同、侵权行为或其他原因。\n\n## 🤖 机器人 JSON 协议——快速参考表\n\n**所有机器人共享**\n- `data_hash`: 驱动响应的 beads 文件的哈希值（用于关联多次调用）。\n- `analysis_config`: 精确的分析设置（超时、模式、循环上限），以确保可重复性。\n- `status`: 每项指标的状态 `computed|approx|timeout|skipped`，附带耗时\u002F原因；在信任 PageRank\u002F介数\u002FHITS 等复杂指标之前，请务必检查。\n- `as_of` \u002F `as_of_commit`: 使用 `--as-of` 时显示；包含您指定的引用以及解析后的提交 SHA，以确保可重复性。\n\n**5 秒内了解 Schema（jq 友好）**\n- `bv --robot-insights` → `.status`, `.analysis_config`, 指标映射（受 `BV_INSIGHTS_MAP_LIMIT` 限制）、`Bottlenecks`, `CriticalPath`, `Cycles`，以及高级信号：`Cores`（k-core）、`Articulation`（割点）、`Slack`（最长路径松弛）。\n- `bv --robot-plan` → `.plan.tracks[].items[].{id,unblocks}`，用于下游解锁；`.plan.summary.highest_impact`。\n- `bv --robot-priority` → `.recommendations[].{id,current_priority,suggested_priority,confidence,reasoning}`。\n- `bv --robot-suggest` → `.suggestions.suggestions[]`（排名靠前的建议）+ `.suggestions.stats`（数量统计）+ `.usage_hints`。\n- `bv --robot-diff --diff-since \u003Cref>` → `{from_data_hash,to_data_hash,diff.summary,diff.new_issues,diff.cycle_*}`。\n- `bv --robot-history` → `.histories[ID].events` + `.commit_index`，用于反向查找；`.stats.method_distribution` 显示相关性是如何推断的。\n\n**复制粘贴注意事项**\n```bash\n# 确保指标已准备好\nbv --robot-insights | jq '.status'\n\n# 计划中的顶级解锁项\nbv --robot-plan | jq '.plan.tracks[].items[] | {id, unblocks}'\n\n# 高置信度的优先级修复建议\nbv --robot-priority | jq '.recommendations[] | select(.confidence > 0.6)'\n\n# 结构强度与并行性\nbv --robot-insights | jq '.full_stats.core_number | to_entries | sort_by(-.value)[:5]'\nbv --robot-insights | jq '.Articulation'\nbv --robot-insights | jq '.Slack[:5]'\n\n# 验证差异哈希是否符合预期\nbv --robot-diff --diff-since HEAD~1 | jq '{from: .from_data_hash, to: .to_data_hash}'\n\n# 历史分析（验证 as_of 元数据）\nbv --robot-insights --as-of HEAD~30 | jq '{as_of, as_of_commit, data_hash}'\n```","# Beads Viewer (bv) 快速上手指南\n\nBeads Viewer (`bv`) 是一个基于终端的高性能界面（TUI），专为 [Beads](https:\u002F\u002Fgithub.com\u002Fsteveyegge\u002Fbeads) 问题追踪系统设计。它支持键盘驱动操作，能够以极快的速度浏览任务、可视化依赖关系图，并为 AI 代理提供结构化的项目洞察。\n\n## 1. 环境准备\n\n在开始之前，请确保满足以下系统要求：\n\n* **操作系统**：macOS, Linux, 或 Windows。\n* **前置依赖**：\n * **数据源**：项目中必须存在 `.beads\u002Fbeads.jsonl` 文件。\n * 若使用 Rust 版 `br`：默认自动生成，无需额外操作。\n * 若使用 Go 版 `bd`：需运行 `bd export --no-memories -o .beads\u002Fbeads.jsonl` 生成。\n * **Windows 用户特别提示**：\n * 需要安装 **Go 1.21+** ([下载地址](https:\u002F\u002Fgo.dev\u002Fdl\u002F))。\n * 推荐安装 **Windows Terminal** 并配置 [Nerd Font](https:\u002F\u002Fwww.nerdfonts.com\u002F) 以获得最佳显示效果。\n\n## 2. 安装步骤\n\n根据你的操作系统选择最合适的安装方式：\n\n### macOS \u002F Linux (推荐：Homebrew)\n自动处理依赖更新，卸载方便。\n```bash\nbrew install dicklesworthstone\u002Ftap\u002Fbv\n```\n\n### Windows (推荐：Scoop)\n```powershell\nscoop bucket add dicklesworthstone https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fscoop-bucket\nscoop install dicklesworthstone\u002Fbv\n```\n\n### 通用安装脚本 (Linux\u002FmacOS\u002FWindows)\n一键下载并安装最新版本。\n\n**Linux\u002FmacOS:**\n```bash\ncurl -fsSL \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Fmain\u002Finstall.sh?$(date +%s)\" | bash\n```\n\n**Windows (PowerShell):**\n```powershell\nirm \"https:\u002F\u002Fraw.githubusercontent.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Fmain\u002Finstall.ps1\" | iex\n```\n\n> **注意**：如果上述链接失效，可前往 [GitHub Releases](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Freleases\u002Flatest) 手动下载对应平台的 `.tar.gz` 压缩包并解压。\n\n## 3. 基本使用\n\n### 🖥️ 交互式终端界面 (人工操作)\n\n确保当前目录下存在 `.beads\u002Fbeads.jsonl` 文件，直接运行：\n\n```bash\nbv\n```\n\n**核心快捷键：**\n* `j` \u002F `k`：上下移动选择任务。\n* `b`：切换至 **看板视图** (Kanban)。\n* `g`：切换至 **依赖关系图视图** (Graph)。\n* `i`：查看 **项目洞察** (PageRank、关键路径、循环依赖等)。\n* `\u002F`：模糊搜索任务。\n* `o` \u002F `c` \u002F `r`：快速筛选 (打开\u002F关闭\u002F就绪) 的任务。\n* `E`：导出为 Markdown。\n* `q`：退出。\n\n### 🤖 AI 代理模式 (Robot Mode)\n\n⚠️ **重要提示**：在 AI Agent 或自动化脚本中调用时，**严禁**直接运行 `bv`（会启动交互界面导致阻塞）。必须使用 `--robot-*` 标志以获取结构化数据输出。\n\n**常用命令示例：**\n\n1. **智能分拣 (推荐入口)**：获取优先级排序、建议操作及项目健康度概览。\n ```bash\n bv --robot-triage\n ```\n\n2. **极简模式**：仅返回下一个最佳任务及认领命令。\n ```bash\n bv --robot-next\n ```\n\n3. **Token 优化输出**：减少 LLM 上下文消耗。\n ```bash\n bv --robot-triage --format toon\n ```\n\n4. **导出依赖图**：生成 JSON\u002FDOT\u002FMermaid 格式供进一步分析。\n ```bash\n bv --robot-graph --graph-format=mermaid\n ```\n\n**输出规范：**\n* `stdout`：仅包含 JSON 或 TOON 格式的数据。\n* `stderr`：包含诊断信息。\n* `exit 0`：表示执行成功。","某大型开源项目的技术负责人正在梳理积压的数百个功能请求与缺陷报告，试图制定下周的冲刺计划并识别阻碍发布的关键瓶颈。\n\n### 没有 beads_viewer 时\n- **依赖关系一团乱麻**：面对复杂的任务依赖网，只能靠肉眼在电子表格中追踪，极易遗漏关键的阻塞项，导致开发中途卡壳。\n- **优先级判断凭感觉**：缺乏量化依据，难以区分哪些是真正影响全局的核心任务，往往陷入“谁声音大先做谁”的被动局面。\n- **状态同步效率低下**：需要频繁切换网页看板、代码库和文档来确认进度，无法在一个界面内获得项目全貌，上下文切换成本极高。\n- **关键路径不清晰**：无法直观看到从当前状态到最终发布的最长依赖链，导致资源分配分散，无法集中火力攻克阻碍发布的“拦路虎”。\n\n### 使用 beads_viewer 后\n- **依赖图谱一目了然**：通过 `g` 键 instantly 调出依赖 DAG 可视化视图，清晰展示任务间的上下游关系，瞬间定位所有潜在的循环依赖和断点。\n- **科学决策优先级**：利用内置的 PageRank 算法自动计算任务权重，精准识别出那些被最多其他任务依赖的“枢纽型”问题，确保优先解决高价值痛点。\n- **终端内全景掌控**：在分屏视图中同时查看任务列表、详细元数据和 Kanban 看板，无需离开终端即可完成从分析到规划的全流程，心流不被打断。\n- **关键路径自动高亮**：一键显示项目的关键路径（Critical Path），让团队明确知道哪些任务的延误会直接推迟整个版本发布，从而针对性地投入资源。\n\nbeads_viewer 将混乱的任务依赖转化为可视化的智能洞察，帮助团队从“盲目救火”转向“精准攻坚”，显著提升研发交付效率。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002FDicklesworthstone_beads_viewer_9f0f894e.webp","Dicklesworthstone","Jeff Emanuel","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002FDicklesworthstone_c96b6d22.jpg","Building in NY",null,"doodlestein","https:\u002F\u002Fwww.jeffreyemanuel.com\u002F","https:\u002F\u002Fgithub.com\u002FDicklesworthstone",[84,88,92,96,100,104,108,112,116,119],{"name":85,"color":86,"percentage":87},"Go","#00ADD8",85.2,{"name":89,"color":90,"percentage":91},"HTML","#e34c26",4.9,{"name":93,"color":94,"percentage":95},"JavaScript","#f1e05a",4,{"name":97,"color":98,"percentage":99},"Rust","#dea584",3.6,{"name":101,"color":102,"percentage":103},"Shell","#89e051",1.3,{"name":105,"color":106,"percentage":107},"CSS","#663399",0.8,{"name":109,"color":110,"percentage":111},"PowerShell","#012456",0.1,{"name":113,"color":114,"percentage":115},"Nix","#7e7eff",0,{"name":117,"color":118,"percentage":115},"Python","#3572A5",{"name":120,"color":121,"percentage":115},"Makefile","#427819",1468,119,"2026-04-19T15:52:46","NOASSERTION","Linux, macOS, Windows","无 GPU 需求","未说明",{"notes":130,"python":131,"dependencies":132},"该工具是基于 Go 语言开发的终端用户界面 (TUI)，无需 Python 环境。Windows 用户若使用安装脚本需预先安装 Go 1.21+，其他平台可直接下载二进制文件或使用包管理器 (Homebrew\u002FScoop)。为获得最佳显示效果，建议使用支持 Nerd Fonts 的终端（如 Windows Terminal）。工具依赖本地 .beads\u002Fbeads.jsonl 文件运行，可由 Rust (br) 或 Go (bd) 工具生成。","不需要 Python (基于 Go 语言)",[133,134],"Go 1.21+ (仅 Windows 安装脚本需要)","Nerd Fonts (推荐用于最佳显示效果)",[17],[137,138,139,140,141],"developer-tools","go","graph-analysis","issue-tracker","tui","2026-03-27T02:49:30.150509","2026-04-20T10:35:03.853007",[145,150,155,160,165,170],{"id":146,"question_zh":147,"answer_zh":148,"source_url":149},44327,"为什么运行 `bv list` 显示找不到任何 Issue，但 `bd list` 和 `br list` 却能正常工作？","这是因为新版本的 Beads 已迁移到使用 Dolt 数据库，而当前的 `beads_viewer` (bv) 尚不支持直接读取 Dolt 格式。解决方案有两个：1. 安装并使用 Rust 版本实现（beads_rust）；2. 或者使用迁移到 Dolt 之前的旧版 Beads（基于 SQLite），大多数用户目前仍配合 `br` 命令使用。","https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Fissues\u002F94",{"id":151,"question_zh":152,"answer_zh":153,"source_url":154},44328,"`beads_viewer` 是否支持最新版的基于 Dolt 的 Beads (v0.50+)？","目前原生不支持。`bv` 是通过读取文件\u002F数据库（如 `beads.db` SQLite 或 JSONL 文件）集成的，无法直接访问 Dolt 数据库。兼容方案是：使用 `bd export -o issues.jsonl` 导出数据快照，然后让 `bv` 读取该 JSONL 文件。这属于离线\u002F快照兼容，而非实时的 Dolt 原生集成。","https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Fissues\u002F121",{"id":156,"question_zh":157,"answer_zh":158,"source_url":159},44329,"如何在 Git Worktree 中使用 `bv`？为什么在 worktree 中运行提示 \"No issues found\"？","该问题已在 commit `6414b4b` 中修复。更新后的 `GetBeadsDir` 函数现在能够检测 Git worktrees，并自动去主仓库根目录查找 `.beads` 文件夹。请确保您的 `beads_viewer` 已更新到包含此修复的版本。","https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Fissues\u002F66",{"id":161,"question_zh":162,"answer_zh":163,"source_url":164},44330,"是否有层级视图（如 Epic\u002FTask\u002FSubtask 树状结构）来展示 beads？","主仓库目前未内置此功能，但社区提供了替代方案：1. 可以使用名为 `beadwork` 的 fork 版本，它包含完整的树状视图功能 (https:\u002F\u002Fgithub.com\u002Fvanderheijden86\u002Fbeadwork)；2. 或者通过 PR #58 实现的按 ID 排序标签视图作为变通方案；3. 也有用户开发了自定义应用 `bsv` 来满足特定需求。","https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Fissues\u002F43",{"id":166,"question_zh":167,"answer_zh":168,"source_url":169},44331,"能否在界面中查看已关闭 beads 的解决原因（Close Reason）或结果摘要？","截至当前版本，`bv` 的数据模型中尚未包含 `close_reason` 字段，TUI 界面也未渲染“解决方案\u002F结果”部分。虽然 Beads 数据中存在这些信息（通过 `bd close --reason` 写入），但 `beads_viewer` 暂未将其作为首要分类信号进行展示或推理。该功能目前不在开发计划中，除非有明确的优先级调整。","https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Fissues\u002F46",{"id":171,"question_zh":172,"answer_zh":173,"source_url":149},44332,"如果不想切换到 Rust 实现，还能继续使用 `bv` 吗？","可以，但必须回退到使用 SQLite 作为后端的旧版 Beads（即在迁移到 Dolt 之前的版本）。新版 Beads 默认使用 Dolt，而 `bv` 暂时无法直接读取 Dolt 数据。如果您希望继续使用现有的 `bv` 而不改变后端，请确保您的 Beads 版本是基于 SQLite 的（例如 v0.49.6 或更早）。",[175,180,185,190,195,200,205,210,215,220,225,230,235,240,245,250,255,260,265,270],{"id":176,"version":177,"summary_zh":178,"released_at":179},351874,"v0.15.2","## 更改记录\n* 05981db chore: 将回退版本升级至 v0.15.2\n* cf001ba fix(pages): 检查所有 Wrangler 配置路径，并处理刷新令牌\n\n","2026-03-09T01:35:34",{"id":181,"version":182,"summary_zh":183,"released_at":184},351875,"v0.15.1","## 更改日志\n* c9b6459 杂项：将回退版本升级至 v0.15.1\n* 4cc8635 修复（页面）：Wrangler 身份验证检查在无头服务器上会挂起\n\n","2026-03-09T00:28:39",{"id":186,"version":187,"summary_zh":188,"released_at":189},351876,"v0.15.0","## 更改日志\n* e0a1bd8 杂项(beads): 添加 bd→br 迁移和发布说明回退的 beads\n* d314f99 杂项(beads): 用实施计划增强 bead 描述\n* b50820a 杂项(beads): 使用完整规范细化 bd→br 迁移和发布说明的 beads\n* f46c76d 杂项(beads): 同步问题跟踪器\n* 3ece5bc 杂项(beads): 同步问题跟踪器\n* afc589d 杂项(beads): 同步问题跟踪器状态\n* 98ded85 杂项(beads): 同步问题跟踪器状态\n* 7ce4706 杂项(beads): 跟踪 Solarized 颜色兼容性修复和发布说明回退工作流\n* a7322e3 杂项: 将 .crush\u002F 添加到 .gitignore\n* 64ec7d6 杂项: 添加 GitHub 社交预览图片 (1280x640)\n* 7fea9cc 杂项: 将回退版本提升至 v0.15.0 以供发布\n* df805e2 杂项: 关闭 bd-1m4u (刷新优化已在 70ms 下验证)\n* 571d86e 杂项: 关闭 bd-3v9s (bd→br 迁移已完成)\n* e02f279 杂项: 关闭 bd-sfad (发布说明工作流已测试)\n* 719ca79 杂项: 更新 Nix flake 配置\n* 81c2b94 杂项: 将许可证更新为 MIT，并加入 OpenAI\u002FAnthropic 附则\n* ffce7cc ci: 增强发布说明回退工作流 (bd-t8dx, GH #99)\n* e60384b 功能(导出): 添加 GitHub Pages 和 Cloudflare 部署支持\n* ede65f2 功能(版本): 添加多源版本检测及优雅回退机制\n* 8e9c656 功能: 添加 --agents-* CLI 标志，用于管理 AGENTS.md 简介 (bv-105)\n* b56ddae 功能: 添加 --db 标志和 BEADS_DB 环境变量，用于配置数据库路径 (#125)\n* ce542b3 功能: 添加草稿\u002F评审状态，并将 agent 简介升级至 v2\n* 42d69f7 功能: 添加延迟、草稿、置顶、挂起、评审和墓碑状态的颜色映射\n* d1e8233 修复(缓存): 使用 WalkDir 进行深度 mtime 扫描，并简化 BEADS_DB 检查\n* dc6bfab 修复(cli): 在机器人模式之前应用配方过滤 (bv-93)\n* cf26e8f 修复(文档): 将 README 中过时的 bd 引用替换为 br\u002Fbv\n* 5285cba 修复(文档): 将 cass 的 GitHub URL 更新为 coding_agent_session_search\n* 87f36d7 修复(加载器): 为兼容 bd，优先使用 beads.jsonl 而不是 issues.jsonl\n* d49b071 修复(发布): 在 goreleaser ldflags 中为版本添加 v 前缀\n* 19437c4 修复(sqlite): 从单独的 labels 表中读取标签，以实现 br\u002Fbeads-rs 兼容\n* 271cb10 修复(ui): 改善页脚文本在不同终端主题下的对比度 (#128)\n* 2fef54f 修复(版本): 将硬编码版本与 git 标签 v0.14.4 同步\n* 087af33 修复(版本): 验证 ldflags 注入，以防止版本输出为空 (#126)\n* b14e9c4 修复: 为 GetActionableIssues 添加传递性父级阻塞检查 (bv-108)\n* e50be8a 修复: 允许看板列在非常窄的终端上缩小到 12 个字符以下\n* cbbcb1f 修复: 针对 Solarized\u002F16 色终端进行色彩配置感知的样式调整 (bd-23lq)\n* 6bce598 修复: 完成剩余源代码和测试中 bd-to-br 命令的迁移\n* 2ff6cab 修复: 纠正看板详情面板的方框绘制，并添加 GITHUB_TOKEN 支持以实现自更新 (#116, #117)\n* 08eb523 修复: 纠正看板视图列宽计算，以防止线条渲染异常 (#114)\n* 1bb3c27 修复: 从版本检测中过滤掉伪版本和脏构建\n* 9464db4 修复: 使…失效","2026-03-08T23:48:29",{"id":191,"version":192,"summary_zh":193,"released_at":194},351877,"v0.14.4","发布 v0.14.4","2026-02-03T17:09:01",{"id":196,"version":197,"summary_zh":198,"released_at":199},351878,"v0.14.3","## 更改日志\n* d263a78 修复（导出）：确保始终计算 SHA-256 哈希值，以用于 OPFS 缓存失效\n* 005a220 修复：对标题进行 XSS 转义、包裹错误信息、改进 OPFS 缓存清理\n\n","2026-02-03T03:11:55",{"id":201,"version":202,"summary_zh":203,"released_at":204},351879,"v0.14.2","发布 v0.14.2","2026-02-03T00:59:50",{"id":206,"version":207,"summary_zh":208,"released_at":209},351880,"v0.14.1","发布 v0.14.1","2026-02-03T00:40:39",{"id":211,"version":212,"summary_zh":213,"released_at":214},351881,"v0.14.0","**完整更新日志**: https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Fcompare\u002Fv0.13.0...v0.14.0","2026-02-02T01:13:33",{"id":216,"version":217,"summary_zh":218,"released_at":219},351882,"v0.13.0","## 更改日志\n* d8ca243 添加依赖边并守护工作线程生命周期\n* 0785a43 合并远程跟踪分支 'origin\u002Fmain'\n* daba452 beads：同步任务跟踪数据\n* 34c3c3a 杂项：捕获优化前的基准测试数据\n* b3175ee 杂项：更新基准测试基线\n* eda6972 杂项：更新 .gitignore\u002Fubsignore 文件，以忽略临时文件\n* c7e2cfe 功能（agents）：添加 TTY 防护，防止在机器人模式下控制序列泄漏\n* cba2f3f 功能（analysis）：添加孤儿节点检测、O(1) 时间复杂度的环路查找以及不区分大小写的标签\n* ea25629 功能（analysis）：增强数据哈希计算，实现确定性的缓存失效\n* fbeb585 功能（bv-4jfr）：为 GraphStats 添加单值访问器模式\n* 8ec02df 功能（bv-fwjm）：将 topk 包集成到向量搜索中\n* c0e3582 功能（loader）：添加 IssueFilter 回调函数和状态归一化处理\n* 1cbdb9c 功能：添加 topk 工具和 TriageContext，用于性能优化\n* 127176b 功能：通过 TriageContext 对 GetActionableIssues 进行记忆化处理（bv-oko3）\n* 3d393e0 功能：添加 Claude Code SKILL.md，用于自动发现能力\n* f696e3d 功能：添加带有详细日志记录的端到端测试套件（bv-dikp）\n* 2324e61 功能：为 SQLite 导出功能添加注释（#52），并为导出功能添加监听模式（#55）\n* 164f2d7 功能：添加同构验证测试基础设施（bv-3wni）\n* af868af 功能：添加性能指标包和 --robot-metrics 命令（bv-84tp）\n* f25a827 功能：更新基准测试并改进 README 文档\n* 09db3df 功能：启用 GoReleaser 自动发布到 Homebrew 和 Scoop\n* a80a75c 功能：统一代码库中墓碑状态和已关闭状态的处理逻辑\n* a122cff 修复（e2e）：添加内存字节数提取的验证\n* a1e4ca3 修复（export）：防止 XSS 攻击、进行 JSON 编码，并增加预览验证\n* da2be05 修复（export）：处理向导中的空标准输入管道，防止无限挂起\n* 2bedf41 修复（export）：移除死代码，并修复向导标准输入处理中的 goroutine 泄漏问题\n* fe79efa 修复（platform）：为原子文件操作添加 Windows 兼容性\n* fe8f062 修复（search）：添加默认优先级，并提升指标缓存的一致性\n* 2922790 修复（ui）：修正注意力表格宽度计算，并增加测试覆盖率\n* c1c5c40 修复：支持所有 8 种 beads 状态类型，并从 robot-next 中过滤掉被屏蔽的项目\n* 309506c 修复：解决缓冲池相关代码审查中的问题\n* 2a4304d 修复：防止因无效 sampleSize 导致的除零错误和 panic\n* eac6338 性能（analysis）：优化分诊评分，并制定优化方案\n* 47adaeb 性能：针对 robot-triage 延迟进行全面的第二轮优化\n* 44c10c2 性能：为 Brandes 算法实现缓冲池技术\n* 9c560be 测试（e2e）：提升 E2E 测试覆盖率和确定性\n\n","2026-01-14T04:33:01",{"id":221,"version":222,"summary_zh":223,"released_at":224},351883,"v0.12.1","## 更改日志\n* 3d5bd2d bd 同步：2026-01-06 13:44:55\n* c0b1871 bd 同步：2026-01-06 13:50:51\n* fe9f22e 杂项：将版本号提升至 v0.12.1\n* 8bf8118 功能（实例）：添加多实例感知与协调功能（bv-vrvn）\n* 3b0ed00 功能（加载器）：为 JSONL 解析器添加全面的模糊测试\n* cd31623 功能（UI）：添加 Phase 1 后台工作线程基础设施（bv-dskh）\n* 5ff1d90 功能（UI）：在 BackgroundWorker 中添加错误处理和 panic 恢复功能（bv-u9gz）\n* bb5c4bc 功能（UI）：实现异步的 Phase 2 分析通知功能（bv-e3ub）\n* 0b67acd 功能（UI）：实现带有去重和错误处理的 buildSnapshot() 方法（bv-y0da）\n* 74e4081 功能（UI）：将 Model 与后台工作线程快照对接（bv-m7v8）\n* 3d48d7a 功能：通过 PowerShell 脚本添加 Windows 安装支持\n* 8c9d759 修复（分析）：在 InDegreeRank\u002FOutDegreeRank 中添加缺失的互斥锁\n* 6040b5d 修复（install.ps1）：改进 GOBIN 处理及 PATH 匹配\n* b544a31 修复（实例）：修复 stale lock 接管中的 TOCTOU 竞争条件\n* f3cba6e 修复（模型）：为兼容 Gastown，接受任何非空 IssueType\n* 761f4fb 修复（UI）：将静态颜色转换为 AdaptiveColor，以支持浅色模式\n* e5cf5f7 修复（UI）：防止在 Stop() 之后 Start() 显示为成功\n* ca5004b 修复（UI）：防止在并发 TriggerRefresh 调用时重复处理\n* 160ff93 修复（UI）：防止 BackgroundWorker 生命周期中出现 panic 和超时\n* a029cb4 修复（UI）：防止在 buildSnapshot 日志记录中因短哈希字符串而引发 panic\n* 2e47a0a 修复（UI）：防止 BackgroundWorker.process() 中出现竞争条件\n* 9cd383b 修复（UI）：防止编辑器文件路径中的 shell 注入\n* f028fbe 修复（UI）：如果 BackgroundWorker 中的 watcher.Start() 失败，重置 started 标志\n* 0d94180 修复（UI）：为保持一致性，在 Phase2ReadyMsg 处理程序中设置 Phase2Ready\n* 4718386 修复（向导）：修正管道输入流为空的检测逻辑","2026-01-07T08:01:17",{"id":226,"version":227,"summary_zh":228,"released_at":229},351884,"v0.12.0","## Changelog\n* 7c9603c chore(coverage): complete test coverage audit for pkg\u002Fui (bv-wdfg)\n* e123866 chore: sync beads JSONL with database state\n* 8de39e6 chore: sync beads after closing bv-e0oi and bv-gllx\n* 77b8bda chore: sync beads after closing bv-i0ei\n* 7431790 chore: sync beads state\n* d5147f4 chore: sync beads state\n* 6e4ebf3 chore: sync beads state\n* 50e5c2d ci: adjust coverage thresholds to realistic values\n* eea913b ci: lower export package threshold to 69%\n* 48652d0 ci: lower overall coverage threshold to 71%\n* dbfe967 feat(tree): add TreeState persistence types (bv-zv7p)\n* 18901e3 feat(ui): add model.go test coverage for state machine (bv-5e5q)\n* 7cae563 feat(ui): add tree view skeleton (bv-i0ei)\n* 33a8618 feat(ui): integrate TreeModel with main app (bv-gllx\u002Fbv-0n0v)\n* 673806a feat(ui\u002Ftest): add view transition integration tests (bv-i3ls)\n* a1b5e7c feat(ui\u002Ftree): add scroll position indicator (bv-2nax)\n* f514f95 feat(ui\u002Ftree): implement cursor-follows-viewport scrolling (bv-lnc4)\n* 8355e48 feat(ui\u002Ftree): implement tree state loading on build (bv-afcm)\n* f54da8b feat(ui\u002Ftree): implement tree state persistence on expand\u002Fcollapse (bv-19vz)\n* e3ad293 feat(ui\u002Ftree): implement windowed viewport rendering (bv-db02)\n* f995bac fix(test): correct test name generation in integration_test.go\n* 76e6f12 fix(tree): handle negative viewportOffset in visibleRange\n* b4745b0 fix(ui): correct misleading comment in handleTreeKeys\n* 786cbc3 fix(ui): use visual width in padRight for proper emoji\u002FCJK alignment\n* a2ccf82 fix(ui\u002Ftree): add defensive checks for division by zero in benchmarks\n* fe23943 fix(ui\u002Ftree): add defensive nil checks\n* 26f2365 fix(ui\u002Ftree): correct display width calculation and comment\n* 0a9aa23 fix(wizard): prevent hang on empty stdin while preserving banner\n* bdae62a fix: handle EDITOR with arguments (e.g., \"cursor -w\")\n* 86306db fix: recompute editorBase after auto-detection fallback\n* d9b6756 test(graph): add SelectByID and diamond pattern tests (bv-8a4r)\n* 3bf7fbd test(ui): add FlowMatrixModel test coverage (bv-w4l0)\n* 5144f69 test(ui\u002Ftree): add comprehensive benchmark suite (bv-e0oi)\n\n","2026-01-06T03:28:29",{"id":231,"version":232,"summary_zh":233,"released_at":234},351885,"v0.11.3","## What's New in v0.11.3\n\n### ✨ Features\n\n- **Nix Flake Support**: Added Nix flake for reproducible builds and development environment. Install with `nix profile install github:Dicklesworthstone\u002Fbeads_viewer` or build locally with `nix build`.\n\n### 🐛 Bug Fixes\n\n- **TUI Improvements**:\n - Fixed multiple focus issues in detail view and design field display\n - Restored proper focus to label picker and time travel input after closing help\n - Fixed false positive update notifications for dev builds\n - Added TUI update modal for in-app updates\n - Fixed bugs in update modal and version comparison logic\n - Handle restore-from-backup error gracefully in update flow\n\n- **Build System**:\n - Changed Version from `const` to `var` to support ldflags injection at build time\n - Updated Nix flake to use nixpkgs-unstable for Go 1.25 support\n\n- **Documentation**:\n - Corrected Board view context help (L jumps to last column, not label picker)\n\n### 📚 Documentation\n\n- Fixed documentation inconsistencies that could confuse new users:\n - Corrected project structure docs (uses `pkg\u002F` not `internal\u002F`)\n - Fixed file discovery order documentation\n - Added comment explaining empty dependency type behavior\n- Updated built-in recipes list (now correctly shows 11, not 6)\n- Added FAQ about \"bead\" vs \"issue\" terminology\n- Fixed keyboard shortcut inconsistencies across help, tutorial, and sidebar\n\n### 🧪 Tests\n\n- Added comprehensive tests for update modal and update flow\n- Fixed test flag names in e2e update tests\n- Corrected malformed URL and misleading comment in tests\n\n---\n\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Fcompare\u002Fv0.11.2...v0.11.3","2026-01-03T19:11:14",{"id":236,"version":237,"summary_zh":238,"released_at":239},351886,"v0.11.2","## Changelog\n* 1c4c0fb fix(correlation): use normalizedFiles length in ImpactAnalysis\n* d537ba5 fix: embed viewer assets in binary for --pages export\n\n","2025-12-21T19:19:44",{"id":241,"version":242,"summary_zh":243,"released_at":244},351887,"v0.11.1","## Changelog\n* 7eb65f1 chore(version): bump to v0.11.1\n* 5a8c94c feat(viewer): add arrow key navigation, enhanced heatmap, and mobile help modal\n\n","2025-12-19T04:28:25",{"id":246,"version":247,"summary_zh":248,"released_at":249},351888,"v0.11.0","## Changelog\n* 6573fb9 chore(version): bump to v0.11.0\n* bd30f67 chore: update analysis, correlation modules and misc improvements\n* 5497d8e docs(search): document hybrid search in README, AGENTS.md, and help system\n* 61a93f7 feat(export): add graph metrics to SQLite schema and optional WASM scorer\n* 7956d47 feat(search): add hybrid search core types with weighted scoring model\n* 4cbd453 feat(search): add metrics cache and query-adaptive weight adjustment\n* 87981a0 feat(search): add search configuration and CLI hybrid search integration\n* 8ba75d8 feat(viewer): add hybrid search with graph-aware ranking in static export\n* 04299d6 fix(ui): clear isHistoryView when switching to other views\n* a3ff088 fix(ui,test): escape key closes label dashboard + drift test build fix\n* 4fd7410 refactor(ui): minor code cleanups in view toggle handlers\n* 9e29b42 test(search): add comprehensive hybrid search test suite and benchmarks\n\n","2025-12-19T02:39:10",{"id":251,"version":252,"summary_zh":253,"released_at":254},351889,"v0.10.6","## Changelog\n* aedc2c1 chore(version): bump to v0.10.6\n* ebfdcf0 fix(e2e): support Linux script command syntax for TUI tests\n\n","2025-12-18T16:49:12",{"id":256,"version":257,"summary_zh":258,"released_at":259},351890,"v0.10.5","## Bug Fixes\n\n### 🐛 Escape Key Now Properly Closes Label Picker ([bff5876](https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Fcommit\u002Fbff5876))\n\n**Problem:** When pressing Escape with the label picker open (triggered by `l` key), the first press triggered the quit confirmation dialog instead of closing the label picker. A second press would exit the program entirely, trapping users in the label picker modal.\n\n**Root Cause:** The escape key handler in the main `Update()` switch statement checked various views (details, insights, graph, board, actionable, history) but did not check for `showLabelPicker` before falling through to the quit confirmation logic.\n\n**Fix:** Added a check for `m.showLabelPicker` in the escape key handler that closes the label picker and returns to the list view before any quit confirmation logic runs.\n\n**Expected behavior restored:**\n- First ESC: Close label picker (return to list view) \n- Second ESC: Clear filters (if any active)\n- Third ESC: Show quit confirmation dialog\n\n---\n\n## Installation\n\n### Homebrew (macOS\u002FLinux)\n```bash\nbrew tap dicklesworthstone\u002Fbeads_viewer\nbrew install bv\n```\n\n### Go Install\n```bash\ngo install github.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Fcmd\u002Fbv@v0.10.5\n```\n\n### Download Binary\nDownload the appropriate binary for your platform from the assets below.\n\n---\n\n**Full Changelog:** https:\u002F\u002Fgithub.com\u002FDicklesworthstone\u002Fbeads_viewer\u002Fcompare\u002Fv0.10.4...v0.10.5","2025-12-18T16:00:17",{"id":261,"version":262,"summary_zh":263,"released_at":264},351891,"v0.10.4","## Changelog\n* 5c8ef87 chore(beads): sync issues.jsonl with hybrid search epic tasks\n* 8589a49 chore(beads): sync issues.jsonl with new hybrid search epic\n* 5a558a6 chore(beads): update hybrid search tasks and close implementation notes\n* dd55c0f chore(version): bump to v0.10.4\n* 53da0ca feat(export): add mobile-responsive UI and advanced graph metrics\n* 6fe88ed feat(tutorial): replace ASCII art with native lipgloss component system\n\n","2025-12-18T15:46:40",{"id":266,"version":267,"summary_zh":268,"released_at":269},351892,"v0.10.3","## Changelog\n* 9755748 Fix install command URL\n* 90d8432 Remove deprecated beads.jsonl, keep issues.jsonl\n* 5075f17 Update beads to v0.30.0: fix config, add sync-branch\n* a2b352c build: add Makefile with FTS5 support enabled\n* 3691052 chore(beads): close SUB-EPIC bv-ul1l - all pkg\u002Fui unit tests complete\n* 015785f chore(beads): close all remaining issues - project 100% complete!\n* fc720e6 chore(beads): close bv-0trk\n* 357dbb6 chore(beads): close bv-100, bv-101 - label health types and extraction\n* 7f40034 chore(beads): close bv-10g (deployment wizard)\n* 4fd1e7d chore(beads): close bv-121 (robot-label-attention command)\n* 21560d0 chore(beads): close bv-127 (comprehensive label analysis tests)\n* 9da5cf7 chore(beads): close bv-134 (Sprint & Forecast System epic complete)\n* cd2765e chore(beads): close bv-138 agent swarm types\n* 6b49be6 chore(beads): close bv-139 agent registry CLI\n* b9eb429 chore(beads): close bv-146 - triage V2 types complete\n* 8c561a8 chore(beads): close bv-147 unified scoring algorithm\n* b6f3970 chore(beads): close bv-148 reason generation\n* f8b11e1 chore(beads): close bv-149, bv-150 - robot-triage implemented\n* ce4b49d chore(beads): close bv-157 (ETA estimation algorithm)\n* f7840d7 chore(beads): close bv-159\n* c15786f chore(beads): close bv-160 (capacity simulation)\n* 304c7b1 chore(beads): close bv-181 - canonical advanced_insights schema\n* eef2415 chore(beads): close bv-50r (preview server)\n* 3dda116 chore(beads): close bv-6xa1\n* a3d17fa chore(beads): close bv-75 incremental history updates\n* c77c7c1 chore(beads): close bv-76 large repo optimization\n* d9600ba chore(beads): close bv-7pu (documentation)\n* 9d97bbb chore(beads): close bv-82 risk and volatility signals\n* 1648037 chore(beads): close bv-82 risk signals implementation\n* eab28f3 chore(beads): close bv-84 - ergonomic robot output filters\n* d30a06c chore(beads): close bv-85 - advanced graph signals\n* 0e24d4c chore(beads): close bv-86 - cycle break in advanced_insights\n* 232f729 chore(beads): close bv-88, bv-130 - safety filters and cycle breaks complete\n* 31b560f chore(beads): close bv-93 (priority radar)\n* 2b3f6a9 chore(beads): close bv-c5lp after glamour integration\n* 55e94d4 chore(beads): close bv-ct7m after adding E2E tests\n* 76049e9 chore(beads): close bv-dgyb (WASM optimization)\n* b672996 chore(beads): close bv-dyg (issue detail view)\n* b5faa5a chore(beads): close bv-focq after wizard E2E tests\n* f4b4e93 chore(beads): close bv-gdlt (error handling)\n* 3ef2a3a chore(beads): close bv-kdn (gh CLI integration)\n* 80bf5d3 chore(beads): close bv-mvvu (P0 data integrity fix)\n* 380f416 chore(beads): close bv-ocw0\n* f5c3df9 chore(beads): close bv-p32k (WASM fallback)\n* d0b1477 chore(beads): close bv-qjc.2 (hook configuration system)\n* 3a1673b chore(beads): close bv-qjc.3 (hooks integration)\n* 272aa85 chore(beads): close bv-sd8b\n* 3eb0f6f chore(beads): close bv-ta9l (ETA unit tests)\n* 7b138fe chore(beads): close bv-w97 (SQLite export pipeline)\n* 263e220 chore(beads): close bv-y5i epic (Static Site Export complete)\n* e79700a chore(beads): close suggestion epic (bv-137, bv-176, bv-178, bv-179, bv-180)\n* f7a43dc chore(beads): fix sync state and update gitignore\n* 1124dd8 chore(beads): sync after closing bv-122 (label subgraph scoping)\n* f387809 chore(beads): sync after closing bv-125\n* 487b576 chore(beads): sync after closing bv-155 and bv-156 (sprint types and viewing)\n* 14704a8 chore(beads): sync after closing bv-161 (sprint view)\n* 86a8240 chore(beads): sync after closing bv-167 (alert configuration)\n* 841a8a5 chore(beads): sync after closing bv-168 (alerts panel)\n* 73274af chore(beads): sync after closing bv-1opc (vim keyboard navigation)\n* b615e3b chore(beads): sync after closing bv-3qi5 and bv-uqoh (GitHub triage epic)\n* 3d0875f chore(beads): sync after closing bv-5dl (Cloudflare Pages)\n* 4b19d76 chore(beads): sync after closing bv-5yb (issues list filters)\n* c572689 chore(beads): sync after closing bv-73f (export-pages CLI)\n* 398dc77 chore(beads): sync after closing bv-81ew (k-core decomposition)\n* 449355d chore(beads): sync after closing bv-87 (track\u002Flabel grouping)\n* 5f4560c chore(beads): sync after closing bv-89\n* ce2f944 chore(beads): sync after closing bv-90\n* a123756 chore(beads): sync after closing bv-91\n* dcf5c15 chore(beads): sync after closing bv-91 (priority insights panel)\n* 8e407b9 chore(beads): sync after closing bv-96 (priority brief)\n* d06deae chore(beads): sync after closing bv-a276 (eigenvector centrality)\n* 1242d9c chore(beads): sync after closing bv-ake (integration tests)\n* e4d4d17 chore(beads): sync after closing bv-awl (dark mode)\n* 15bf4c2 chore(beads): sync after closing bv-d4w7, bv-bxoe, bv-yi6k\n* fbc7e5b chore(beads): sync after closing bv-gij1 (critical path animation)\n* b30337a chore(beads): sync after closing bv-gv7 (mobile responsive)\n* be8cc0f chore(beads): sync after closing bv-k79d (WASM memory management)\n* 8710f61 chore(beads): sync after closing bv-kdug (reachability)\n* a80e9b0 chore(beads): sync aft","2025-12-18T08:10:49",{"id":271,"version":272,"summary_zh":273,"released_at":274},351893,"v0.10.2","Highlights\\n- Hooks: executor hardened (command-not-found, permission denied, timeout, large stderr truncation) with new edge-case tests.\\n- RunHooks: integration coverage for missing configs, fail\u002Fcontinue semantics, and nil\u002Fno-hooks paths.\\n- UI: broader Update() coverage (list\u002Fboard\u002Fgraph\u002Factionable toggles, recipe picker, time-travel prompts, footer\u002Fstatus badges, help\u002Fquit flows).\\n- Analysis: profile stats getters and phase-2 readiness\u002Fcaching paths covered.\\n- Beads: normalized IDs to beads_viewer-* and closed hooks bead; version bumped to v0.10.2.\\n\\nArtifacts\\n- Multi-OS\u002Farch tarballs (linux\u002Fdarwin\u002Fwindows; amd64\u002Farm64)\\n- checksums.txt (SHA256 for all assets)\\n\\nUpgrade\\n- Download the tarball for your OS\u002Farch from this release or use install.sh with tag v0.10.2.\\n- Replace existing bv binary and run `bv --version` to verify v0.10.2.","2025-11-30T20:44:38"]