# bv 技能：人工智能驱动的问题跟踪器分析 ## 概述 `bv` (beads_viewer) 是一个**高性能 Go TUI**，用于分析珠子问题跟踪器依赖关系图。这项技能使人工智能代理能够利用“bv”的**机器人协议**进行智能任务优先级排序、依赖性分析和架构健康监控。 **关键原则：** **切勿启动交互式 TUI**。始终使用“--robot-*”标志进行结构化 JSON 输出。 ** ** ## 何时使用此技能在以下情况下激活该技能： ### 任务优先级 *“接下来我应该做什么？” *“哪些问题阻碍了大部分工作？” *“影响最大的任务是什么？” * 冲刺计划和待办事项梳理 ### 依赖性分析 *“这个问题取决于什么？” *“此功能的依赖项是什么？” *“这会解锁什么？” * 了解顺序工作与并行工作 ### 项目健康监控 *“项目架构健康吗？” *“是否存在循环依赖？” *“代码库耦合度是否太高？” * 检测 CI/CD 中的架构漂移 ### 架构重构 *“瓶颈是什么？” * “我们应该首先重构哪些问题？” *“我们怎样才能减少耦合？” * 识别技术债务 ### 历史分析 *“自上次冲刺以来发生了什么变化？” *“项目的健康状况是改善还是恶化？” *“复杂性是如何演变的？” * 发布回顾 ** ** ## 核心能力 ### 1\.图表指标（9 个维度） `bv` 计算每个问题的综合指标：公制|意义|使用案例 ---|---|--- **页面排名** |阻挡力|基础依赖关系 **之间** |瓶颈状态|工作流之间的桥梁问题 **HITS（中心/权威机构）** |依赖性性质|整合与基础工作 **关键路径** |链条深度|顺序依赖长度 **特征向量** |网络影响力|相关问题的重要性 **学位** |连接数 |直接依赖 **密度** |耦合测量|整体图健康状况 **周期** |循环依赖|建筑问题 **拓扑排序** |有效执行顺序|工作可以排序吗？有关详细说明，请参阅 [principles/graph-metrics.md]()。 ** ** ### 2\.机器人协议命令所有命令都会返回**结构化 JSON** 以进行编程分析： #### 分析命令 # 综合指标 bv——机器人洞察 # 带有建议的执行计划 bv——机器人计划 # 优先级调整建议 bv --机器人优先级 # 可用的过滤配方 bv --机器人食谱 ####历史分析 # 与历史点比较 bv --diff-since HEAD~10 --robot-diff bv --diff-自 v1.0.0 --robot-diff bv --diff-自 2025-11-01 --robot-diff # 查看历史状态 bv --as-of v1.0.0 --robot-insights #### 漂移检测 # 保存基线以供将来比较 bv --save-baseline “2025 年第 4 季度基线 - 预重构” # 检查架构漂移 bv --检查漂移 --机器人漂移 # 查看基线元数据 bv --基线信息 #### 多存储库支持 # 聚合多个存储库 bv --workspace .bv/workspace.yaml --robot-insights # 按存储库过滤 bv --workspace.bv/workspace.yaml --repo api --robot-plan ** ** ## 决策框架 ### 优先级矩阵使用指标组合提出智能建议：场景 |指标|行动 ---|---|--- **关键瓶颈** |高PageRank+高介数+高关键路径| **最高优先级** \- 阻止一切 **基础工作** |高PageRank+高权威+低出度| **高优先级** \- 启用下游工作 **整合点** |高枢纽+高介数| **坐标** \- 需要许多输入 **快速获胜** |低度+无依赖性 | **可并行化** \- 适合副业 **建筑债务** |部分循环+高密度| **重构** \- 打破依赖关系 **独立功能** |低所有指标 + 程度 = 0 | **独立** \- 随时工作 ### 健康指标 **健康项目：** { 【密度】：0.2-0.4， “周期”：[]， “topologicalSortValid”：正确， "healthTrend": "稳定" } **警告标志：** { 【密度】：0.6-0.8， “周期”：[1-3]， "highBetweennessConcentration": ">5 个问题得分 >0.8" } **关键问题：** { “密度”：“0.8”， “周期”：“4+”， “topologicalSortValid”：假 } ** ** ## 常见工作流程 ### 1\.初步项目评估 # 获得全面的分析 bv --robot-insights > Insights.json # 生成执行计划 bv --robot-plan > plan.json # 检查优先级对齐 bv --robot-priority >priority.json # 导出人类可读的报告 bv --export-md health-report.md **决策逻辑：** const Insights = JSON.parse(fs.readFileSync('insights.json')); if (insights.cycles.length > 0) { return "CRITICAL: 在其他工作之前中断循环"; } 否则如果 (insights.graphStats.密度.密度 > 0.7) { return "警告：过度耦合 - 建议模块化"； } 否则{ return `健康：关注 ${plan.summary.recommendedNextIssue}`; } ** ** ### 2\.冲刺计划 # 过滤可操作的问题（无阻碍） bv --recipe actionable --robot-plan > sprint-plan.json # 获取高影响力的建议 bv --机器人洞察 | jq '.recommendations.highImpactIssues' # 验证优先级 bv --机器人优先级 | jq '.recommendations[] |选择（.置信度> 0.8）' **团队分配：** * **高级工程师：** 高影响力（impactScore > 0.7） * **中级工程师：** 解锁工作（unblocks.length > 0） * **初级工程师：** 快速获胜（无依赖性，影响低） ** ** ### 3\.架构重构 # 重构前保存基线 bv --save-baseline "预重构基线 - $(date +%Y-%m-%d)" # 确定重构目标 bv --robot-insights > current.json # 优先顺序： # 1. 中断周期（最高优先级） # 2.提取瓶颈（高介数） # 3.减少耦合（高密度） # 4. 稳定基础（高 PageRank） ** ** ### 4\. CI/CD健康监测 # .github/workflows/architecture-health.yml - 名称：检查漂移运行： bv --check-drift --robot-drift >drift-report.json - 名称：分析结果运行： | EXIT_CODE=$(jq -r '.exitCode' 漂移报告.json) 如果[“$EXIT_CODE”==“1”];然后 echo "::error::关键漂移 - 检测到新周期" 1号出口 elif [“$EXIT_CODE”==“2”];然后 echo "::警告::指标降级 - 建议审查" 菲 **退出代码：** * `0` = 健康（无漂移） * `1` = 严重（新周期） * `2` = 警告（密度增加，更多阻塞问题） ** ** ### 5\.历史分析 # 与上一个版本比较 bv --diff-since v1.0.0 --robot-diff >release-diff.json # 查看健康趋势 jq -r '.summary.healthTrend'release-diff.json # 输出：“改进”、“降级”或“稳定” # 查看已解决的循环 jq '.changes.resolvedCycles'release-diff.json ** ** ## TypeScript 集成导入{ 见解回应，计划响应，优先响应，差异响应，漂移响应来自 '../bv-codebase/types/core'; // 示例：检查项目健康状况异步函数 checkProjectHealth(): Promise { const { stdout } =等待 execAsync('bv --robot-insights'); const 见解：InsightsResponse = JSON.parse(stdout); const healthScore =calculateHealthScore(insights); 如果（健康分数 < 60）{ console.log('❌严重：需要立即采取行动'); console.log(`周期：${insights.cycles.length}`); console.log(`密度：${insights.graphStats.密度.interpretation}`); } else if (healthScore < 80) { console.log('⚠️警告：建议进行架构改进'); } 否则{ console.log('✅ 健康：项目状态良好'); } } 函数计算健康分数（见解：InsightsResponse）：数字{ 让分数= 100； // 减去循环数分数 -= Insights.cycles.length * 15; // 扣除高密度如果（insights.graphStats.密度.密度 > 0.7）得分 -= 20；否则如果（insights.graphStats.密度.密度> 0.5）分数-= 10； // 扣除瓶颈 constbottlenecks=insights.metrics. Betweenness.filter(m => m.score > 0.7); 分数 -=bottlenecks.length * 5; 返回 Math.max(0, 分数); } ** ** ## 多存储库支持 ### 工作区配置 # .bv/workspace.yaml 回购协议： - 名称：核心 API 路径：../core-api 前缀：api- - 名称：网络前端路径：../web-frontend 前缀：网络- - 名称：移动应用程序路径：../mobile-app 前缀：移动- ### 用法 # 一起查看所有仓库 bv --workspace .bv/workspace.yaml --robot-insights # 按存储库前缀过滤 bv --workspace.bv/workspace.yaml --repo api --robot-plan # 识别跨存储库依赖关系（高介数） bv --workspace .bv/workspace.yaml --robot-insights | bv --workspace .bv/workspace.yaml --robot-insights | \ jq '.metrics. Betweenness[] | jq '.metrics. Betweenness[] |选择(.score > 0.7)' **命名空间问题 ID：** `api-issue-001`、`web-issue-002`、`mobile-issue-003` ** ** ## 挂钩系统 ### 配置（`.bv/hooks.yaml`）预导出： - 名称：验证命令：./scripts/validate-before-export.sh 失败：错误导出后： - 名称：通知松弛命令：./scripts/send-slack-notification.sh 环境： SLACK_WEBHOOK：$SLACK_WEBHOOK_URL 失败：从不 - 名称：上传报告命令：./scripts/upload-to-s3.sh 失败：从不 ### 环境变量在钩子脚本中可用： * `BV_EXPORT_PATH` \- 输出文件路径 * `BV_EXPORT_FORMAT` \- `markdown` 或 `json` * `BV_ISSUE_COUNT` \- 问题总数 * `BV_TIMESTAMP` \- 导出时间戳 ### 跳过钩子 bv --export-md 报告.md --no-hooks ** ** ## 性能优化 ### 自动跳过度量 * **小图（< 100 个节点）：** 计算所有 9 个指标（~1 秒） * **中型图（100-1000 个节点）：** 除非需要，否则跳过介数（~2-5 秒） * **大型图表（> 1000 个节点）：** 仅基本指标（~5-10 秒） ### 强制全面分析 bv --force-full-analysis --robot-insights **使用时间：** 需要全面审核（对于大图可能需要 30 秒以上） ### 分析 # 人类可读 bv --配置文件启动 # 用于监控系统的 JSON bv --profile-startup --profile-json ** ** ## 错误处理即使出现错误，所有机器人命令也会返回有效的 JSON： { “错误”：正确， "message": "未找到基线。首先运行 --save-baseline。", “代码”：“NO_BASELINE”， "suggestion": "bv --save-baseline \"初始基线\"" } **始终安全地解析 JSON：** 尝试{ const 结果 = JSON.parse(stdout) as InsightsResponse; // 处理结果 } 捕获（错误）{ console.error('无法解析bv输出：', error); } ** ** ## 最佳实践 ### ✅ 做 1. **始终使用`--robot-*`标志** \- 从不启动 TUI 2. **解析 JSON 输出** \- 用于编程决策的结构化数据 3. **检查 CI 中的退出代码** \- `0` = 成功，`1` = 严重，`2` = 警告 4. **在重大更改之前保存基线** \- 启用漂移检测 5. **组合命令进行丰富的分析** \- 层层洞察以获得更好的决策 6. **使用配方进行过滤** \- `--recipe actionable` 进行冲刺计划 7. **随着时间的推移跟踪指标** \- 使用 `--diff-since` 来了解趋势 ### ❌不要 1. **永远不要在没有机器人标志的情况下运行`bv`** \- 将在 TUI 中无限期阻塞 2. **不要忽略循环** \- 必须解决循环依赖 3. **不要跳过 CI 中的漂移检查** \ - 防止架构退化 4. **不必要时不要强制进行全面分析** \- 对于大图来说速度很慢 5. **不要解析人类可读的输出** \- 始终使用机器人命令中的 JSON 6. **不要创建没有描述的基线** \- 上下文至关重要 ** ** ## 快速参考 ### 命令备忘单 # 分析 bv --robot-insights # 完整指标 bv --robot-plan # 执行计划 bv --robot-priority # 优先级建议 bv --robot-recipes # 可用的食谱 # 历史 bv --diff-since HEAD~10 --robot-diff # 与 10 次提交前比较 bv --diff-since v1.0.0 --robot-diff # 与发布标签比较 bv --diff-since 2025-11-01 --robot-diff # 与日期比较 bv --as-of v1.0.0 --robot-insights # 查看历史状态 # 漂移检测 bv --save-baseline "description" # 保存当前指标 bv --check-drift --robot-drift # 检查漂移 bv --baseline-info # 查看基线元数据 # 多仓库 bv --workspace .bv/workspace.yaml --robot-insights # 所有存储库 bv --workspace .bv/workspace.yaml --repo api --robot-plan # 按 repo 过滤 # 过滤 bv --recipe actionable --robot-plan # 无阻碍 bv --recipe high-impact --robot-insights # 高指标 bv --recipe Blocked --robot-insights # 拦截器的问题 # 导出 bv --export-md report.md # Markdown 报告 bv --export-md report.md --no-hooks # 跳过钩子 # 性能 bv --force-full-analysis --robot-insights # 计算所有指标 bv --profile-startup --profile-json # 性能分析 ### JQ 助手 # 提取具体数据 bv --机器人洞察 | jq '.recommendations.highImpactIssues' bv --机器人计划 | jq '.summary.recommendedNextIssue' bv --机器人优先级 | jq '.recommendations[] |选择（.置信度> 0.8）' # 按指标过滤 bv --机器人洞察 | jq '.metrics.pageRank[] | jq '.metrics.pageRank[] |选择(.score > 0.7)' bv --机器人洞察 | jq '.metrics. Betweenness[] | jq '.metrics. Betweenness[] |选择(.score > 0.8)' # 检查健康状况 bv --机器人洞察 | jq '.cycles |长度' bv --机器人洞察 | jq '.graphStats.密度.解释' bv --check-drift --robot-drift | bv --check-drift --robot-drift | jq '.exitCode' ** ** ## 文件和资源 ### 技能文件 * [SKILL.md]() \- 此文件 * [scripts/metrics-validator.sh]() \- 验证指标输出 * [references/robot-commands.md]() \- 完整命令参考 * [references/graph-analysis.md]() \- 指标解释指南 * [assets/cheatsheet.md]() \- 快速命令参考 ### 代码库文件 * [../bv-codebase/types/core.ts]() \- TypeScript 类型定义 * [../bv-codebase/principles/graph-metrics.md]() \- 深入了解指标 * [../bv-codebase/principles/robot-protocol.md]() \- 协议文档 * [../bv-codebase/templates/analysis-workflow.md]() \- 常见模式 * [../bv-codebase/README.md]() \- 代码库概述 ** ** ## 安装 # macOS（自制）酿造安装beadlabs/tap/bv # Linux 卷曲 -L https://github.com/beadslabs/bv/releases/latest/download/bv-linux-amd64 -o bv chmod +x bv sudo mv bv /usr/local/bin/ # 验证 bv——版本 ** ** ## 故障排除 **问题：** `bv` 永远挂起 * **原因：** TUI 在没有机器人标志的情况下启动 * **修复：** 始终使用 `--robot-*` 标志 **问题：** 空 JSON 响应 * **原因：** `.beads/` 目录中没有问题 * **修复：** 验证跟踪器是否存在 **问题：** 输出中缺少指标 * **原因：** 图较大，自动跳过 * **修复：** 使用 `--force-full-analysis` **问题：** 漂移检查始终返回 0 * **原因：** 未保存基线 * **修复：** 首先运行`bv --save-baseline“初始基线”` ** ** ## 示例 ### 示例 1：Sprint 计划 #!/bin/bash # 生成冲刺计划 # 1. 获取可操作的问题 bv --recipe actionable --robot-plan > sprint-plan.json # 2. 提取高影响力的作品 HIGH_IMPACT=$(jq -r '.tracks[].items[] | select(.impactScore > 0.7) | .issueId' sprint-plan.json) # 3. 快速获胜 QUICK_WINS=$(jq -r '.tracks[].items[] | select(.dependency | length == 0) | select(.unblocks | length == 0) | .issueId' sprint-plan.json) echo“高影响问题：” 回显“$HIGH_IMPACT” 回声“” echo“快速获胜：” 回显“$QUICK_WINS” ### 示例 2：CI 健康检查 #!/bin/bash # CI 管道漂移检查 bv --check-drift --robot-drift >drift-report.json 退出代码=$? 如果 [ $EXIT_CODE -eq 1 ];然后 echo“❌严重：检测到新周期” jq -r '.alerts[] | select(.level == "关键") | .message' 漂移报告.json 1号出口 elif [ $EXIT_CODE -eq 2 ];然后 echo“⚠️警告：指标降级” jq -r '.alerts[] | select(.level == "警告") | .message' 漂移报告.json 出口0 否则 echo“✅健康：未检测到漂移” 出口0 菲 ### 示例 3：优先级验证 #!/bin/bash # 检查优先级是否不一致 bv --robot-priority >priority-check.json HIGH_CONFIDENCE=$(jq '.recommendations[] | select(.confidence > 0.8)'priority-check.json) 如果[-n“$HIGH_CONFIDENCE”];然后 echo "⚠️高置信度优先级调整建议：" 回声“$HIGH_CONFIDENCE”| jq -r '"\(.issueId): P\(.currentPriority) → P\(.recommendedPriority) (\(.reasoning))"' 否则 echo“✅ 优先级与指标非常一致” 菲 ** ** ## 版本兼容性 * **bv:** v1.0.0+ * **机器人协议：** v1.x（semver-stable） * **此技能：** v1.0.0 ** ** ## 许可证该技能文档是为AI代理和开发人员提供的。 **bv** 由 Beads Labs 开发。请参阅了解工具许可。

乙肝病毒

包含技能