{
"canonical_name": "campfirein/byterover-cli",
"compilation_id": "pack_84331f02827141e28385d44fa86b0aac",
"created_at": "2026-05-14T13:18:50.554370+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `npm install -g byterover-cli` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "npm install -g byterover-cli",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_059144ba93b649d8bd4e26e3991aa488"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_8cb9b39f538cb72bcba649f53ee5c3c4",
"canonical_name": "campfirein/byterover-cli",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/campfirein/byterover-cli",
"slug": "byterover-cli",
"source_packet_id": "phit_16a5fb9b77ea409b948119ad9c8c7af7",
"source_validation_id": "dval_91ddd0b1491442239f32e69c7d30787b"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
"github_forks": 450,
"github_stars": 4742,
"one_liner_en": "ByteRover CLI (brv) - The portable memory layer for autonomous coding agents (formerly Cipher)",
"one_liner_zh": "ByteRover CLI (brv) - The portable memory layer for autonomous coding agents (formerly Cipher)",
"primary_category": {
"category_id": "software-development",
"confidence": "high",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:coding, git, ci"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "byterover-cli",
"title_zh": "byterover-cli 能力包",
"visible_tags": [
{
"label_en": "MCP Tools",
"label_zh": "MCP 工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-mcp-tools",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Workflow Automation",
"label_zh": "流程自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-workflow-automation",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_16a5fb9b77ea409b948119ad9c8c7af7",
"page_model": {
"artifacts": {
"artifact_slug": "byterover-cli",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "npm install -g byterover-cli",
"label": "Node.js / npm · 官方安装入口",
"source": "https://github.com/campfirein/byterover-cli#readme",
"verified": true
}
],
"display_tags": [
"MCP 工具",
"知识库问答",
"流程自动化",
"节点式流程编排",
"评测体系"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "ByteRover CLI (brv) - The portable memory layer for autonomous coding agents (formerly Cipher)"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Curator can copy prompt example facts into the context tree when using Gemini Flash-Lite",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_f0927b3fa77c4e7ab29ba04f3c4b7ed7 | https://github.com/campfirein/byterover-cli/issues/647 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Curator can copy prompt example facts into the context tree when using Gemini Flash-Lite",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Visual corruption while browsing a long model list",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_3112b1ba6fc54e0a8d973b277ab8d106 | https://github.com/campfirein/byterover-cli/issues/620 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Visual corruption while browsing a long model list",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.10.1",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_c21085e93cad46a5b79d8ff2353f156c | https://github.com/campfirein/byterover-cli/releases/tag/v3.10.1 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：ByteRover CLI 3.10.1",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.10.3",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_5ada5377aa504edeac454b6a66310a47 | https://github.com/campfirein/byterover-cli/releases/tag/v3.10.3 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：ByteRover CLI 3.10.3",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.8.1",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_370b6c20f13544c28427013da0519f1f | https://github.com/campfirein/byterover-cli/releases/tag/v3.8.1 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：ByteRover CLI 3.8.1",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.8.2",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_48b470d455aa406480648e100bc08c94 | https://github.com/campfirein/byterover-cli/releases/tag/v3.8.2 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：ByteRover CLI 3.8.2",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.8.3",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_70d8761f65864cf2897a70138eabb5b7 | https://github.com/campfirein/byterover-cli/releases/tag/v3.8.3 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：ByteRover CLI 3.8.3",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.9.0",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_955f12701a864106895fc95c8ef7fd05 | https://github.com/campfirein/byterover-cli/releases/tag/v3.9.0 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：ByteRover CLI 3.9.0",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：`brv mcp` client stuck in infinite exception loop consuming 75–90% CPU for hours",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_50500a3417394344864f50cf765157ea | https://github.com/campfirein/byterover-cli/issues/660 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：`brv mcp` client stuck in infinite exception loop consuming 75–90% CPU for hours",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ByteRover CLI 3.10.0",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_78241481b8c647e4a05827b06eafdc99 | https://github.com/campfirein/byterover-cli/releases/tag/v3.10.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：ByteRover CLI 3.10.0",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ByteRover CLI 3.10.2",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_2af62a087710490b8250f23ac6258644 | https://github.com/campfirein/byterover-cli/releases/tag/v3.10.2 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：ByteRover CLI 3.10.2",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ByteRover CLI 3.11.0",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_ea3c8b32846b4edfaef28f8aa1cca40f | https://github.com/campfirein/byterover-cli/releases/tag/v3.11.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：ByteRover CLI 3.11.0",
"user_impact": "可能影响升级、迁移或版本选择。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 19 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Curator can copy prompt example facts into the context tree when using Gemini Flash-Lite。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 27,
"forks": 450,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 4742
},
"source_url": "https://github.com/campfirein/byterover-cli",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "ByteRover CLI (brv) - The portable memory layer for autonomous coding agents (formerly Cipher)",
"title": "byterover-cli 能力包",
"trial_prompt": "# byterover-cli - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 byterover-cli 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. project-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. system-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. agent-system：Agent核心系统。围绕“Agent核心系统”模拟一次用户任务，不展示安装或运行结果。\n4. llm-providers：LLM提供商集成。围绕“LLM提供商集成”模拟一次用户任务，不展示安装或运行结果。\n5. tools-system：工具系统。围绕“工具系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. project-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. system-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. agent-system\n输入：用户提供的“Agent核心系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. llm-providers\n输入：用户提供的“LLM提供商集成”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. tools-system\n输入：用户提供的“工具系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / project-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / system-architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / agent-system：Step 3 必须围绕“Agent核心系统”形成一个小中间产物，并等待用户确认。\n- Step 4 / llm-providers：Step 4 必须围绕“LLM提供商集成”形成一个小中间产物，并等待用户确认。\n- Step 5 / tools-system：Step 5 必须围绕“工具系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/campfirein/byterover-cli\n- https://github.com/campfirein/byterover-cli#readme\n- src/server/templates/skill/SKILL.md\n- README.md\n- package.json\n- CLAUDE.md\n- src/agent/core/interfaces/index.ts\n- src/index.ts\n- src/server/infra/transport/socket-io-transport-server.ts\n- src/oclif/commands/main.ts\n- src/agent/core/domain/agent/agent-state-machine.ts\n- src/agent/core/domain/agent/agent-registry.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 byterover-cli 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: `brv mcp` client stuck in infinite exception loop consuming 75–90% CPU f（https://github.com/campfirein/byterover-cli/issues/660）；github/github_issue: Visual corruption while browsing a long model list（https://github.com/campfirein/byterover-cli/issues/620）；github/github_issue: Curator can copy prompt example facts into the context tree when using G（https://github.com/campfirein/byterover-cli/issues/647）；github/github_release: ByteRover CLI 3.12.0（https://github.com/campfirein/byterover-cli/releases/tag/v3.12.0）；github/github_release: ByteRover CLI 3.11.0（https://github.com/campfirein/byterover-cli/releases/tag/v3.11.0）；github/github_release: ByteRover CLI 3.10.3（https://github.com/campfirein/byterover-cli/releases/tag/v3.10.3）；github/github_release: ByteRover CLI 3.10.2（https://github.com/campfirein/byterover-cli/releases/tag/v3.10.2）；github/github_release: ByteRover CLI 3.10.1（https://github.com/campfirein/byterover-cli/releases/tag/v3.10.1）；github/github_release: ByteRover CLI 3.10.0（https://github.com/campfirein/byterover-cli/releases/tag/v3.10.0）；github/github_release: ByteRover CLI 3.9.0（https://github.com/campfirein/byterover-cli/releases/tag/v3.9.0）；github/github_release: ByteRover CLI 3.8.3（https://github.com/campfirein/byterover-cli/releases/tag/v3.8.3）；github/github_release: ByteRover CLI 3.8.2（https://github.com/campfirein/byterover-cli/releases/tag/v3.8.2）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "`brv mcp` client stuck in infinite exception loop consuming 75–90% CPU f",
"url": "https://github.com/campfirein/byterover-cli/issues/660"
},
{
"kind": "github_issue",
"source": "github",
"title": "Visual corruption while browsing a long model list",
"url": "https://github.com/campfirein/byterover-cli/issues/620"
},
{
"kind": "github_issue",
"source": "github",
"title": "Curator can copy prompt example facts into the context tree when using G",
"url": "https://github.com/campfirein/byterover-cli/issues/647"
},
{
"kind": "github_release",
"source": "github",
"title": "ByteRover CLI 3.12.0",
"url": "https://github.com/campfirein/byterover-cli/releases/tag/v3.12.0"
},
{
"kind": "github_release",
"source": "github",
"title": "ByteRover CLI 3.11.0",
"url": "https://github.com/campfirein/byterover-cli/releases/tag/v3.11.0"
},
{
"kind": "github_release",
"source": "github",
"title": "ByteRover CLI 3.10.3",
"url": "https://github.com/campfirein/byterover-cli/releases/tag/v3.10.3"
},
{
"kind": "github_release",
"source": "github",
"title": "ByteRover CLI 3.10.2",
"url": "https://github.com/campfirein/byterover-cli/releases/tag/v3.10.2"
},
{
"kind": "github_release",
"source": "github",
"title": "ByteRover CLI 3.10.1",
"url": "https://github.com/campfirein/byterover-cli/releases/tag/v3.10.1"
},
{
"kind": "github_release",
"source": "github",
"title": "ByteRover CLI 3.10.0",
"url": "https://github.com/campfirein/byterover-cli/releases/tag/v3.10.0"
},
{
"kind": "github_release",
"source": "github",
"title": "ByteRover CLI 3.9.0",
"url": "https://github.com/campfirein/byterover-cli/releases/tag/v3.9.0"
},
{
"kind": "github_release",
"source": "github",
"title": "ByteRover CLI 3.8.3",
"url": "https://github.com/campfirein/byterover-cli/releases/tag/v3.8.3"
},
{
"kind": "github_release",
"source": "github",
"title": "ByteRover CLI 3.8.2",
"url": "https://github.com/campfirein/byterover-cli/releases/tag/v3.8.2"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "ByteRover CLI (brv) - The portable memory layer for autonomous coding agents (formerly Cipher)",
"effort": "安装已验证",
"forks": 450,
"icon": "code",
"name": "byterover-cli 能力包",
"risk": "可发布",
"slug": "byterover-cli",
"stars": 4742,
"tags": [
"MCP 工具",
"知识库问答",
"流程自动化",
"节点式流程编排",
"评测体系"
],
"thumb": "gray",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/campfirein/byterover-cli 项目说明书\n\n生成时间：2026-05-14 13:16:52 UTC\n\n## 目录\n\n- [项目概述](#project-overview)\n- [系统架构](#system-architecture)\n- [Agent核心系统](#agent-system)\n- [LLM提供商集成](#llm-providers)\n- [工具系统](#tools-system)\n- [上下文树与知识管理](#context-tree)\n- [版本控制系统](#version-control)\n- [Swarm多代理协调](#swarm-coordination)\n- [TUI交互界面](#tui-interface)\n- [WebUI管理面板](#webui-dashboard)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [Agent核心系统](#agent-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/campfirein/byterover-cli/blob/main/README.md)\n- [src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts)\n- [src/server/templates/README.md](https://github.com/campfirein/byterover-cli/blob/main/src/server/templates/README.md)\n- [src/shared/transport/events/vc-events.ts](https://github.com/campfirein/byterover-cli/blob/main/src/shared/transport/events/vc-events.ts)\n- [src/tui/components/onboarding/welcome-box.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/tui/components/onboarding/welcome-box.tsx)\n- [src/agent/infra/sandbox/curate-service.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/sandbox/curate-service.ts)\n \n\n# 项目概述\n\n## 项目简介\n\nByteRover CLI（命令行工具）是一个交互式 REPL（Read-Eval-Print Loop）命令行工具，专为 AI 编程代理提供持久化、结构化的记忆能力。它使开发者能够将项目知识组织成上下文树（Context Tree），同步到云端，并在不同工具和团队成员之间共享。\n\n资料来源：[README.md:1-15]()\n\n该工具通过命令行界面 `brv` 运行，开发者可以在任何项目目录中启动，享受 AI 代理带来的智能编程体验。ByteRover 的核心设计理念是：**让 AI 代理能够理解和记忆项目上下文，从而提供更精准的代码生成和问题诊断**。\n\n## 核心架构\n\n### 系统组件概览\n\nByteRover CLI 采用模块化架构，主要包含以下核心组件：\n\n| 组件名称 | 功能描述 | 源码位置 |\n|---------|---------|---------|\n| **Agent 核心** | AI 代理执行引擎，处理工具调用和推理 | `src/agent/` |\n| **Sandbox 服务** | 知识策展操作的执行环境 | `src/agent/infra/sandbox/` |\n| **TUI 组件** | 终端用户界面渲染 | `src/tui/` |\n| **WebUI 组件** | 浏览器图形界面 | `src/webui/` |\n| **传输层** | 前后端通信和事件系统 | `src/shared/transport/` |\n| **模板系统** | 动态生成代理指令 | `src/server/templates/` |\n\n### 架构流程图\n\n```mermaid\ngraph TD\n A[用户终端] -->|brv 命令| B[CLI 入口]\n B --> C{交互模式}\n C -->|TUI| D[终端用户界面]\n C -->|WebUI| E[Web 浏览器界面]\n \n D --> F[Agent 执行引擎]\n E --> F\n \n F --> G[上下文树管理]\n F --> H[Sandbox 服务]\n F --> I[版本控制集成]\n \n G --> J[知识策展服务]\n H --> J\n I --> J\n \n J --> K[云端同步]\n K --> L[远程存储]\n \n F --> M[系统提示构建]\n M --> N[上下文树结构贡献者]\n N --> O[Context Tree 结构]\n```\n\n## 核心功能模块\n\n### 1. 上下文树（Context Tree）\n\n上下文树是 ByteRover 的核心知识组织结构，采用层次化文件管理方式存储项目知识。\n\n资料来源：[src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts:1-60]()\n\n#### 目录结构规范\n\n```\n.brv/context-tree/\n├── [domain]/ # 顶级域名（动态创建）\n│ ├── [topic].md # 主题文件\n│ └── [subtopic]/\n│ └── context.md # 子主题内容\n├── _index.md # 自动生成的目录摘要\n└── _archived/ # 归档的低优先级条目\n```\n\n#### 动态域名系统\n\n- **域名创建**：根据策展内容的语义动态创建\n- **命名规范**：使用 snake_case 格式（如 `architecture`、`market_trends`）\n- **组织原则**：在创建新域名之前，应检查现有域名是否可容纳内容\n\n### 2. 知识策展服务（Curate Service）\n\n知识策展服务负责对上下文树中的知识主题进行增删改查操作。\n\n资料来源：[src/agent/infra/sandbox/curate-service.ts:1-80]()\n\n#### 策展操作类型\n\n| 操作类型 | 说明 | 内容要求 |\n|---------|------|---------|\n| `ADD` | 添加新主题 | 需要 title 和 content |\n| `UPDATE` | 更新现有主题 | 需要 title 和/或 content |\n| `UPSERT` | 存在则更新，不存在则创建 | 需要 title 和 content |\n| `DELETE` | 删除主题 | 只需要 path |\n\n#### 内容存储格式\n\n策展内容支持多种数据类型的存储：\n\n- **事实（Factual）**：个人、项目配置、团队约定等\n- **图表（Diagrams）**：Mermaid、PlantUML、ASCII 图表\n- **决策（Decisions）**：包含完整理由的决策文本\n- **流程（Flow）**：工作流步骤和条件\n\n### 3. 版本控制集成（VC Events）\n\nByteRover 内置了类似 Git 的版本控制功能，支持分布式团队协作。\n\n资料来源：[src/shared/transport/events/vc-events.ts:1-50]()\n\n#### 差异比较模式\n\n| 模式 | 说明 | Git 对应 |\n|-----|------|---------|\n| `unstaged` | 工作目录 vs 暂存区 | `git diff` |\n| `staged` | 暂存区 vs HEAD | `git diff --staged` |\n| `ref-vs-worktree` | 指定引用 vs 工作目录 | `git diff [` |\n| `range` | 两个引用之间 | `git diff ..` |\n\n#### 版本控制命令\n\n```bash\nbrv vc add . # 暂存所有文件\nbrv vc add notes.md docs/ # 暂存指定文件\nbrv vc commit -m \"add patterns\" # 提交更改\nbrv vc log # 查看历史\nbrv vc branch feature/auth # 创建分支\nbrv vc merge feature/auth # 合并分支\n```\n\n### 4. 模板系统（Template System）\n\n模板系统用于根据用户选择的 AI 代理动态生成指令规则。\n\n资料来源：[src/server/templates/README.md:1-40]()\n\n#### 模板目录结构\n\n```\nsrc/templates/\n├── base.md # 主模板结构\n├── sections/ # 可复用内容区块\n│ ├── workflow.md # 工作流指南\n│ └── command-reference.md # 命令参考文档\n└── README.md # 本说明文件\n```\n\n#### 模板变量\n\n| 变量名 | 说明 | 示例 |\n|-------|------|------|\n| `{{agent_name}}` | 代理名称 | \"Claude Code\", \"Cursor\" |\n| `{{workflow}}` | 工作流内容 | sections/workflow.md |\n| `{{command_reference}}` | 命令参考 | sections/command-reference.md |\n\n### 5. 用户界面\n\nByteRover 提供两种用户界面选项：\n\n#### 终端用户界面（TUI）\n\n基于终端的交互式界面，支持以下功能：\n\n- 实时执行日志展示\n- 文件变更追踪\n- 推理内容显示\n- 欢迎引导界面\n\n资料来源：[src/tui/components/onboarding/welcome-box.tsx:1-50]()\n\n#### Web 用户界面（WebUI）\n\n浏览器图形界面，提供：\n\n- 上下文历史面板\n- Hub 组件展示\n- 离线状态处理\n- 传输层事件处理\n\n## 数据流与状态管理\n\n### 代理执行流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant TUI as TUI 界面\n participant Agent as Agent 引擎\n participant Sandbox as Sandbox 服务\n participant Tree as 上下文树\n participant Cloud as 云端\n\n User->>TUI: 输入命令\n TUI->>Agent: 转发请求\n Agent->>Agent: 执行推理\n Agent->>Sandbox: 调用工具\n Sandbox->>Tree: 读写知识\n Tree-->>Sandbox: 返回数据\n Sandbox-->>Agent: 执行结果\n Agent->>Cloud: 同步变更\n Cloud-->>Agent: 确认\n Agent-->>TUI: 返回响应\n TUI-->>User: 展示结果\n```\n\n### 知识策展操作流\n\n```mermaid\ngraph TD\n A[发起策展操作] --> B{操作类型验证}\n B -->|有效| C[验证必需字段]\n B -->|无效| D[返回失败]\n C -->|完整| E[执行文件操作]\n C -->|不完整| F[返回失败]\n E --> G[更新上下文树]\n G --> H[生成摘要]\n H --> I[同步云端]\n```\n\n## 命令行接口\n\n### 核心命令\n\n| 命令 | 功能 | 示例 |\n|-----|------|------|\n| `brv login` | 用户认证 | `brv login` |\n| `brv init` | 初始化项目 | `brv init` |\n| `brv status` | 查看状态 | `brv status` |\n| `brv add` | 添加上下文 | `brv add ./docs` |\n| `brv gen-rules` | 生成代理规则 | `brv gen-rules` |\n| `brv push` | 推送到云端 | `brv push` |\n| `brv watch` | 监听文件变更 | `brv watch` |\n| `brv cipher-agent` | 代理加密 | `brv cipher-agent` |\n\n### Space 命令\n\n| 命令 | 功能 |\n|-----|------|\n| `brv space list` | 列出所有空间 |\n| `brv space switch` | 切换当前空间 |\n\n## 技术特点\n\n### 设计原则\n\n1. **持久化记忆**：为 AI 代理提供跨会话的项目上下文记忆\n2. **结构化组织**：使用树形结构管理知识，便于检索\n3. **云端同步**：支持团队协作和跨设备同步\n4. **多代理支持**：兼容多种 AI 编码代理（Claude Code、Cursor 等）\n5. **自包含**：WebUI 采用全内联 CSS/JS，无外部依赖\n\n### 安全性\n\n- 支持代理加密功能（`cipher-agent`）\n- 版本控制支持分支管理和合并冲突解决\n- 敏感操作需要用户确认（如 Approve/Reject）\n\n## 快速入门\n\n```bash\n# 安装 CLI\nnpm install -g byterover-cli\n\n# 登录认证\nbrv login\n\n# 初始化项目\nbrv init\n\n# 启动交互式 REPL\nbrv\n\n# 在 REPL 中策展知识\n/curate\n\n# 查询相关记忆\n/query <关键词>\n\n# 同步到云端\nbrv push\n```\n\n## 相关文档\n\n- [工作流指南](./workflow.md)\n- [命令参考](./command-reference.md)\n- [技能模板](./skill/SKILL.md)\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目概述](#project-overview), [Agent核心系统](#agent-system)\n\n]\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agent/infra/map/abstract-generator.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/map/abstract-generator.ts)\n- [src/agent/infra/sandbox/curate-service.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/sandbox/curate-service.ts)\n- [src/server/infra/http/review-ui.ts](https://github.com/campfirein/byterover-cli/blob/main/src/server/infra/http/review-ui.ts)\n- [src/server/infra/provider-oauth/callback-server.ts](https://github.com/campfirein/byterover-cli/blob/main/src/server/infra/provider-oauth/callback-server.ts)\n- [src/server/templates/README.md](https://github.com/campfirein/byterover-cli/blob/main/src/server/templates/README.md)\n- [src/shared/transport/events/vc-events.ts](https://github.com/campfirein/byterover-cli/blob/main/src/shared/transport/events/vc-events.ts)\n- [src/tui/features/vc/pull/components/vc-pull-flow.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/tui/features/vc/pull/components/vc-pull-flow.tsx)\n- [README.md](https://github.com/campfirein/byterover-cli/blob/main/README.md)\n \n\n# 系统架构\n\n## 概述\n\nByteRover CLI（命令行工具 `brv`）是一个为 AI 编程代理提供持久化、结构化记忆的交互式 REPL 工具。它允许开发者在上下文树中管理项目知识，与云端同步，并跨工具和团队共享。 资料来源：[README.md]()\n\n该系统采用分层架构设计，核心层负责 AI 代理的上下文管理与操作，传输层处理客户端与服务器之间的实时通信，呈现层同时支持终端界面（TUI）和网页界面（WebUI）两种交互模式。\n\n## 整体架构\n\n```mermaid\ngraph TD\n subgraph 客户端层\n TUI[TUI 终端界面]\n WebUI[WebUI 网页界面]\n end\n \n subgraph 传输层\n SocketIO[Socket.IO 传输服务器]\n HTTP[HTTP 服务器]\n end\n \n subgraph 核心层\n Agent[Agent 核心]\n Sandbox[沙箱环境]\n CurateService[Curate 服务]\n end\n \n subgraph 基础设施层\n VcEvents[VC 事件系统]\n AbstractGen[抽象生成器]\n OutputGen[输出生成器]\n ReviewUI[审查 UI]\n end\n \n TUI <--> SocketIO\n WebUI <--> HTTP\n SocketIO <--> Agent\n HTTP <--> Agent\n Agent <--> Sandbox\n Sandbox <--> CurateService\n Agent <--> VcEvents\n Agent <--> AbstractGen\n Agent <--> OutputGen\n```\n\n## 分层架构详解\n\n### 1. 客户端层\n\nByteRover CLI 提供两种用户界面，以满足不同使用场景的需求：\n\n| 界面类型 | 技术栈 | 适用场景 |\n|---------|--------|----------|\n| TUI | React + Ink | 终端重度用户，习惯命令行操作 |\n| WebUI | React + TailwindCSS | 偏好图形界面，需要可视化操作 |\n\n#### TUI 组件结构\n\nTUI（终端用户界面）采用组件化设计，主要组件位于 `src/tui/` 目录：\n\n- **执行组件**：`ExecutionProgress`、`ExecutionContent`、`ExecutionChanges` 用于展示代理执行过程\n- **VC 组件**：`VcPullFlow` 处理版本控制拉取流程\n- **Hub 组件**：`HubDetailStep` 展示技能详情\n\n```tsx\n// 执行日志视图 - 展示流式内容\n{log.streamingContent && log.status === 'running' && (\n \n)}\n```\n\n资料来源：[src/tui/components/execution/expanded-log-view.tsx:36-42]()\n\n### 2. 传输层\n\n传输层负责客户端与服务器之间的通信，采用双协议支持：\n\n#### Socket.IO 传输服务器\n\n基于 Socket.IO 实现实时双向通信，适用于需要即时反馈的场景：\n\n```typescript\n// 核心传输服务器职责：\n// - 管理客户端连接生命周期\n// - 处理实时事件分发\n// - 维护连接状态\n```\n\n#### HTTP 服务器\n\nHTTP 服务器处理同步请求和回调流程，主要用途包括：\n\n- OAuth 认证回调处理\n- 静态资源服务\n- HITL（人机回环）审查 UI 服务\n\n```typescript\nfunction errorHtml(message: string): string {\n return `\n\n\n ByteRover - Authorization Failed\n ...\n\n`\n}\n```\n\n资料来源：[src/server/infra/provider-oauth/callback-server.ts:42-59]()\n\n### 3. 核心层\n\n核心层是系统的中枢，包含 AI 代理的主要逻辑：\n\n#### Agent 核心模块\n\n代理核心负责：\n- 理解代码库结构和语义\n- 读取和写入文件\n- 管理上下文树状态\n- 与 LLM 交互生成响应\n\n#### Curate 服务\n\n`CurateService` 是核心层的重要组成部分，提供知识主题的组织和领域检测功能：\n\n```typescript\nexport class CurateService implements ICurateService {\n private readonly workingDirectory: string\n\n constructor(\n workingDirectory?: string,\n private readonly abstractQueue?: AbstractGenerationQueue,\n private readonly runtimeSignalStore?: IRuntimeSignalStore,\n ) {\n this.workingDirectory = workingDirectory ?? process.cwd()\n }\n}\n```\n\n资料来源：[src/agent/infra/sandbox/curate-service.ts:66-76]()\n\n#### Curate 操作验证\n\n系统对 Curate 操作有严格的验证规则：\n\n| 操作类型 | 必需字段 | 说明 |\n|---------|---------|------|\n| ADD | title, content | 添加新知识条目 |\n| UPDATE | title, content | 更新现有条目 |\n| UPSERT | title, content | 存在则更新，不存在则创建 |\n| DELETE | path | 删除指定路径的条目 |\n\n```typescript\n// 操作验证逻辑\nif ((op.type === 'ADD' || op.type === 'UPDATE' || op.type === 'UPSERT') && !op.title) {\n failures.push({\n message: `${op.type} operation requires a title (becomes the .md filename).`,\n path: op.path,\n status: 'failed',\n type: op.type,\n })\n}\n```\n\n资料来源：[src/agent/infra/sandbox/curate-service.ts:41-49]()\n\n### 4. 基础设施层\n\n基础设施层为上层提供通用能力支持：\n\n#### VC 事件系统\n\n版本控制事件系统定义完整的 Diff 模式和数据模型：\n\n```typescript\nexport type VcDiffMode =\n | {from: string; kind: 'range'; to: string}\n | {kind: 'ref-vs-worktree'; ref: string}\n | {kind: 'staged'}\n | {kind: 'unstaged'}\n```\n\n资料来源：[src/shared/transport/events/vc-events.ts:14-21]()\n\n支持的 Diff 模式：\n\n| 模式 | 说明 | 对应 Git 命令 |\n|------|------|---------------|\n| unstaged | 工作目录 vs 暂存区 | `git diff` |\n| staged | HEAD vs 暂存区 | `git diff --staged` |\n| ref-vs-worktree | 指定提交 vs 工作目录 | `git diff [` |\n| range | 提交范围对比 | `git diff ..` |\n\n#### 抽象生成器\n\n`AbstractGenerator` 负责从知识文档生成结构化摘要：\n\n```typescript\nfunction parseBatchedTags(response: string, innerTag: 'abstract' | 'overview'): Map\n```\n\n输出格式采用 XML 结构：\n```xml\n\">\n- bullet 1\n- bullet 2\n\n```\n\n资料来源：[src/agent/infra/map/abstract-generator.ts:47-67]()\n\n#### 输出生成器\n\n`OutputGenerator` 负责将文件夹打包结果转换为 XML 格式输出：\n\n```typescript\n// 生成文件类型分布统计\nconst typeBreakdown = new Map()\nfor (const file of result.files) {\n const fileType = file.fileType ?? 'unknown'\n typeBreakdown.set(fileType, (typeBreakdown.get(fileType) ?? 0) + 1)\n}\n```\n\n资料来源：[src/agent/infra/folder-pack/output-generator.ts:37-41]()\n\n#### 审查 UI 生成\n\nHITL 审查 UI 是自包含的 HTML 页面，内嵌所有 CSS 和 JavaScript：\n\n```typescript\nexport function getReviewPageHtml(): string {\n return `\n\n\n\n\nByteRover Review\n\n\n...`\n}\n```\n\n资料来源：[src/server/infra/http/review-ui.ts:7-28]()\n\n## 命令行入口\n\n系统通过 `oclif` 框架实现命令行入口，主要命令位于 `src/oclif/commands/`：\n\n```bash\nbrv login # 用户认证\nbrv init # 初始化项目\nbrv status # 查看状态\nbrv add # 添加文件到上下文\nbrv gen-rules # 生成代理规则\nbrv push # 推送到云端\nbrv watch # 监听文件变化\nbrv vc # 版本控制命令\n```\n\n资料来源：[src/server/templates/skill/SKILL.md:1-20]()\n\n## 云端同步架构\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端 (brv)\n participant Server as ByteRover Cloud\n participant Space as Space 工作区\n \n Client->>Server: brv login\n Server-->>Client: 认证成功\n Client->>Space: brv vc push/pull\n Space-->>Client: 同步完成\n```\n\n云端同步功能要求：\n- 完成 ByteRover 认证（`brv login`）\n- 配置远程仓库地址\n- 可通过 Web 应用创建或打开 Space\n\n资料来源：[src/tui/features/vc/pull/components/vc-pull-flow.tsx:1-15]()\n\n## 模板系统\n\nByteRover 使用模板系统生成代理指令，通过 `brv gen-rules` 命令触发：\n\n```\nsrc/templates/\n├── base.md # 主模板结构\n├── sections/ # 可复用内容区段\n│ ├── workflow.md # 工作流指南\n│ └── command-reference.md # 命令参考文档\n└── README.md\n```\n\n模板变量替换：\n- `{{agent_name}}` - 代理名称\n- `{{workflow}}` - 工作流内容\n- `{{command_reference}}` - 命令参考内容\n\n资料来源：[src/server/templates/README.md:1-30]()\n\n## 技术栈总结\n\n| 层级 | 主要技术 | 文件位置 |\n|------|---------|----------|\n| 客户端 | React, Ink, TailwindCSS | `src/tui/`, `src/webui/` |\n| 传输 | Socket.IO, Node.js HTTP | `src/server/infra/transport/` |\n| 核心 | TypeScript | `src/agent/core/`, `src/agent/infra/` |\n| 基础设施 | XML 生成, 事件系统 | `src/shared/`, `src/agent/infra/` |\n| CLI | oclif | `src/oclif/` |\n\n---\n\n\n\n## Agent核心系统\n\n### 相关页面\n\n相关主题：[LLM提供商集成](#llm-providers), [工具系统](#tools-system), [上下文树与知识管理](#context-tree)\n\n]\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agent/infra/map/abstract-generator.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/map/abstract-generator.ts)\n- [src/agent/infra/sandbox/curate-service.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/sandbox/curate-service.ts)\n- [src/agent/infra/process/command-validator.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/process/command-validator.ts)\n- [src/agent/infra/folder-pack/output-generator.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/folder-pack/output-generator.ts)\n \n\n# Agent核心系统\n\n## 概述\n\nByteRover CLI 的 Agent 核心系统是一个模块化的基础设施架构，负责为 AI Agent 提供运行时环境、命令安全验证、知识管理和输出生成能力。该系统采用分层设计，核心基础设施包括：\n\n- **抽象生成器**（Abstract Generator）：处理知识文档的结构化概览生成\n- **策展服务**（Curate Service）：管理知识主题的增删改查操作\n- **命令验证器**（Command Validator）：提供命令安全性和权限校验\n- **输出生成器**（Output Generator）：生成结构化的文件夹打包输出\n\n## 系统架构\n\n```mermaid\ngraph TB\n subgraph \"Agent 核心基础设施\"\n AG[Agent Core]\n end\n \n subgraph \"Infra Layer\"\n MAP[Map/Abstract Generator
src/agent/infra/map/]\n SBX[Sandbox/Curate Service
src/agent/infra/sandbox/]\n PROC[Process/Command Validator
src/agent/infra/process/]\n OUT[Folder Pack/Output Generator
src/agent/infra/folder-pack/]\n end\n \n AG --> MAP\n AG --> SBX\n AG --> PROC\n AG --> OUT\n```\n\n## 抽象生成器（Abstract Generator）\n\n### 功能定位\n\n`abstract-generator.ts` 负责从知识文档集合中生成结构化的概览信息，支持 XML 格式的批量处理和解析。\n\n### 核心能力\n\n| 能力 | 描述 |\n|------|------|\n| 文档包装 | 将文件路径和内容封装为 XML 格式 |\n| 概览生成 | 提示 LLM 生成 markdown 格式的结构化摘要 |\n| 批量解析 | 从模型输出中提取 `` 和 `/` 标签 |\n\n### XML 格式规范\n\n系统使用 CDATA 块保护内容，避免 XML 转义问题：\n\n```xml\n\n \n\n```\n\n### 解析策略\n\n`parseBatchedTags` 函数采用锚定策略进行容错解析：\n\n- 以 `` 开启标签为锚点\n- 每个开启标签own对应到下一个开启标签前的响应切片\n- 内部正则提取该切片中的 payload\n- 此设计避免模型输出中包含 `` 字面量时导致的错误匹配\n\n资料来源：[src/agent/infra/map/abstract-generator.ts:28-35]()\n\n## 策展服务（Curate Service）\n\n### 功能定位\n\n`curate-service.ts` 实现知识主题的策展操作，支持 ADD、UPDATE、UPSERT、DELETE 等原子操作。\n\n### 操作验证规则\n\n| 操作类型 | 必需字段 | 验证条件 |\n|----------|----------|----------|\n| ADD | title, content | title 为文件名，content 包含 rawConcept 和/或 narrative |\n| UPDATE | title, content | 同 ADD |\n| UPSERT | title, content | 同 ADD |\n| DELETE | path | 仅需 path |\n\n### CurateResult 结构\n\n策展操作返回结果包含：\n\n- `appliedOperations`：已应用的原子操作列表\n- `summary`：操作摘要\n- `failures`：验证失败的操作详情\n\n```typescript\ninterface CurateResult {\n appliedOperations: CurateOperation[]\n summary: string\n failures: Array<{\n message: string\n path: string\n status: 'failed'\n type: OperationType\n }>\n}\n```\n\n资料来源：[src/agent/infra/sandbox/curate-service.ts:1-40]()\n\n## 命令验证器（Command Validator）\n\n### 安全架构\n\n命令验证器是 Agent 系统的安全防线，基于可配置的安全级别和黑白名单机制。\n\n```mermaid\ngraph LR\n CMD[Command Input] --> VAL{CommandValidator}\n VAL -->|Allowed| EXEC[Execute]\n VAL -->|Blocked| REJECT[Reject + Log]\n VAL -->|Requires Approval| WAIT[Wait for Approval]\n \n style EXEC fill:#90EE90\n style REJECT fill:#FFB6C1\n style WAIT fill:#FFE4B5\n```\n\n### 内置只读命令模式\n\n系统预定义了安全的只读命令正则：\n\n```typescript\nconst READ_ONLY_PATTERNS = [\n /cat\\s+.*>/, // 读取文件内容\n /find\\s+.*>/, // 查找文件\n /git\\s+(status|log|diff|show|branch|tag|fetch|pull)(?!\\s+-)/i, // Git 只读操作\n]\n```\n\n### 验证流程\n\n1. **危险模式检测**：检查是否匹配已知危险命令模式\n2. **黑名单检查**：验证命令是否在 blockedCommands 列表中\n3. **白名单放行**：若命中 allowedCommands，直接通过\n4. **安全级别评估**：根据 securityLevel 判断是否需要审批\n\n### 路径参数提取\n\n`extractPathArguments` 方法专门处理命令中的文件路径参数：\n\n- 过滤掉以 `-` 开头的 flags\n- 排除 chmod 等特殊参数模式\n- 规范化跨平台路径格式\n\n资料来源：[src/agent/infra/process/command-validator.ts:1-60]()\n\n## 输出生成器（Output Generator）\n\n### 功能定位\n\n`output-generator.ts` 负责将文件夹打包结果转换为 XML 格式的结构化输出，便于 LLM 理解和处理。\n\n### 输出结构\n\n```xml\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```typescript\nconst typeBreakdown = new Map()\nfor (const file of result.files) {\n const fileType = file.fileType ?? 'unknown'\n typeBreakdown.set(fileType, (typeBreakdown.get(fileType) ?? 0) + 1)\n}\n```\n\n### 配置项\n\n| 配置项 | 用途 | 默认行为 |\n|--------|------|----------|\n| maxFileSize | 单文件大小限制 | 格式化显示 |\n| maxLinesPerFile | 单文件行数限制 | 格式化显示 |\n| ignore | 忽略模式列表 | 显示模式数量 |\n\n资料来源：[src/agent/infra/folder-pack/output-generator.ts:1-50]()\n\n## 工作流程集成\n\n### Agent 执行上下文\n\n```mermaid\nsequenceDiagram\n participant Agent as Agent Core\n participant Validator as Command Validator\n participant Curate as Curate Service\n participant Output as Output Generator\n \n Agent->>Validator: Validate Command\n Validator-->>Agent: Allow/Block/Approval Required\n \n alt Command Allowed\n Agent->>Curate: Curate Operations\n Curate-->>Agent: CurateResult\n Agent->>Output: Generate XML Output\n Output-->>Agent: Structured Response\n end\n```\n\n### 知识文档处理流程\n\n1. **输入**：知识文档集合（路径 + 内容）\n2. **包装**：转换为 XML 格式，使用 CDATA 保护内容\n3. **生成**：提示 LLM 生成结构化概览\n4. **解析**：从模型响应中提取 `` 和 `` 标签对\n5. **输出**：返回 Map 结构\n\n## 配置与扩展\n\n### 安全级别配置\n\n`ProcessConfig` 支持的安全配置项：\n\n```typescript\ninterface ProcessConfig {\n allowedCommands?: string[] // 白名单命令\n blockedCommands?: string[] // 黑名单命令\n securityLevel?: 'low' | 'medium' | 'high'\n}\n```\n\n### 扩展点\n\n| 扩展点 | 文件位置 | 扩展方式 |\n|--------|----------|----------|\n| 命令验证 | command-validator.ts | 添加新的验证正则或规则 |\n| 抽象生成 | abstract-generator.ts | 自定义解析策略或输出格式 |\n| 策展操作 | curate-service.ts | 添加新的操作类型 |\n| 输出格式 | output-generator.ts | 扩展 XML 结构 |\n\n## 总结\n\nByteRover CLI 的 Agent 核心系统通过模块化的基础设施设计，实现了：\n\n- **安全性**：命令验证器提供多层安全防护\n- **可观测性**：结构化输出便于调试和追踪\n- **扩展性**：清晰的接口和配置机制支持定制\n- **容错性**：解析器采用锚定策略避免边界情况\n\n这些基础设施组件协同工作，为 AI Agent 提供安全、可靠、可控的运行时环境。\n\n---\n\n\n\n## LLM提供商集成\n\n### 相关页面\n\n相关主题：[Agent核心系统](#agent-system), [工具系统](#tools-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agent/infra/llm/providers/index.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/llm/providers/index.ts)\n- [src/agent/infra/llm/providers/anthropic.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/llm/providers/anthropic.ts)\n- [src/agent/infra/llm/providers/openai.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/llm/providers/openai.ts)\n- [src/agent/infra/llm/providers/google.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/llm/providers/google.ts)\n- [src/agent/infra/llm/agent-llm-service.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/llm/agent-llm-service.ts)\n- [src/agent/infra/llm/retry/retry-with-backoff.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/llm/retry/retry-with-backoff.ts)\n- [src/agent/infra/llm/context/context-manager.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/llm/context/context-manager.ts)\n \n\n# LLM提供商集成\n\n## 概述\n\nByteRover CLI 的 LLM（大型语言模型）提供商集成模块位于 `src/agent/infra/llm/` 目录下，负责管理与各种 AI 模型提供商的通信。该模块采用工厂模式和适配器模式，支持多种 LLM 提供商（Anthropic、OpenAI、Google）的无缝切换，使系统能够在不同 AI 服务之间灵活选择和配置。\n\nLLM 提供商集成的核心职责包括：\n\n- **统一抽象接口**：为不同提供商提供一致的调用方式\n- **认证管理**：处理各提供商的 API 密钥和环境变量配置\n- **请求重试机制**：通过指数退避策略处理临时性网络故障和限流\n- **上下文管理**：优化 token 使用，控制对话历史长度\n\n资料来源：[src/agent/infra/llm/providers/index.ts]()\n\n## 架构设计\n\n### 模块结构\n\n```\nsrc/agent/infra/llm/\n├── providers/ # 提供商适配器\n│ ├── index.ts # 提供商工厂与注册\n│ ├── anthropic.ts # Anthropic (Claude) 适配器\n│ ├── openai.ts # OpenAI (GPT) 适配器\n│ └── google.ts # Google (Gemini) 适配器\n├── agent-llm-service.ts # Agent LLM 服务主类\n├── retry/\n│ └── retry-with-backoff.ts # 重试机制实现\n└── context/\n └── context-manager.ts # 上下文管理\n```\n\n### 核心类关系\n\n```mermaid\ngraph TD\n A[Agent LLM Service] --> B[Provider Factory]\n B --> C[Anthropic Provider]\n B --> D[OpenAI Provider]\n B --> E[Google Provider]\n A --> F[Context Manager]\n A --> G[Retry with Backoff]\n \n H[LLM Request] --> A\n A --> I[Provider Response]\n \n C --> C1[Anthropic API]\n D --> D1[OpenAI API]\n E --> E1[Google AI API]\n```\n\n## 提供商适配器\n\n### 提供商注册与工厂模式\n\n`providers/index.ts` 实现了一个工厂模式，所有提供商在此注册。系统通过配置选择使用哪个提供商，无需修改调用代码即可切换 AI 模型。\n\n资料来源：[src/agent/infra/llm/providers/index.ts]()\n\n### Anthropic 提供商\n\nAnthropic 提供商适配器负责与 Claude 系列模型的通信。该适配器处理：\n\n- Anthropic 特有的请求格式（messages API）\n- `anthropic-version` 头部设置\n- `max_tokens` 和 `thinking` 块配置\n- 流式响应的解析\n\n资料来源：[src/agent/infra/llm/providers/anthropic.ts]()\n\n### OpenAI 提供商\n\nOpenAI 提供商适配器支持 GPT-4、GPT-4o 等模型系列。特性包括：\n\n- 兼容 OpenAI Chat Completions API 格式\n- 支持 `temperature`、`top_p` 等采样参数\n- 函数调用（Function Calling）支持\n- 多模态输入处理\n\n资料来源：[src/agent/infra/llm/providers/openai.ts]()\n\n### Google 提供商\n\nGoogle 提供商适配器集成 Gemini 模型：\n\n- Gemini API 格式适配\n- 安全过滤配置\n- 生成配置（temperature、topP、topK）\n- 系统指令处理\n\n资料来源：[src/agent/infra/llm/providers/google.ts]()\n\n## Agent LLM 服务\n\n`agent-llm-service.ts` 是 LLM 集成的核心服务类，封装了所有与 AI 模型交互的逻辑。\n\n### 主要职责\n\n| 职责 | 描述 |\n|------|------|\n| 提供商初始化 | 根据配置创建相应的提供商实例 |\n| 请求发送 | 构建请求并调用提供商 |\n| 响应处理 | 解析 AI 响应并转换为统一格式 |\n| 错误处理 | 统一管理各类异常情况 |\n\n资料来源：[src/agent/infra/llm/agent-llm-service.ts]()\n\n### 工作流程\n\n```mermaid\nsequenceDiagram\n participant Agent as Agent/Worker\n participant LLMService as Agent LLM Service\n participant Provider as Selected Provider\n participant API as External LLM API\n\n Agent->>LLMService: 发送请求\n LLMService->>LLMService: 应用上下文管理\n LLMService->>Provider: 调用提供商接口\n Provider->>API: 发送 API 请求\n API-->>Provider: 返回响应\n Provider-->>LLMService: 返回标准格式响应\n LLMService-->>Agent: 返回处理结果\n```\n\n## 重试机制\n\n### 指数退避策略\n\n`retry-with-backoff.ts` 实现了智能重试机制，用于处理网络临时故障和 API 限流情况。\n\n资料来源：[src/agent/infra/llm/retry/retry-with-backoff.ts]()\n\n### 重试配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| maxRetries | number | 3 | 最大重试次数 |\n| initialDelay | number | 1000 | 初始延迟（毫秒） |\n| maxDelay | number | 30000 | 最大延迟上限 |\n| backoffMultiplier | number | 2 | 退避系数 |\n\n### 重试条件\n\n系统仅对以下情况触发重试：\n\n- **网络错误**：连接超时、DNS 解析失败\n- **5xx 服务器错误**：上游服务暂时不可用\n- **429 限流错误**：API 调用频率超限\n\n以下情况不进行重试：\n\n- 认证失败（401、403）\n- 客户端请求错误（400）\n- 内容安全过滤（根据提供商配置）\n\n## 上下文管理\n\n### Context Manager\n\n`context-manager.ts` 负责管理和优化对话上下文，确保在 token 限制内提供最佳上下文。\n\n资料来源：[src/agent/infra/llm/context/context-manager.ts]()\n\n### 上下文窗口管理\n\n```mermaid\ngraph LR\n A[用户消息] --> B[Context Manager]\n B --> C{Token 计数}\n C -->|超限| D[压缩历史]\n C -->|正常| E[直接添加]\n D --> F[摘要生成]\n E --> G[上下文列表]\n F --> G\n G --> H[LLM 请求]\n```\n\n### 上下文优化策略\n\n| 策略 | 触发条件 | 处理方式 |\n|------|----------|----------|\n| 滑动窗口 | 对话历史过长 | 保留最近 N 条消息 |\n| 摘要压缩 | 单条消息过长 | 生成摘要替代原文 |\n| 关键信息保留 | 任何压缩场景 | 保留系统指令和关键配置 |\n\n## 配置与认证\n\n### 环境变量配置\n\n| 变量名 | 提供商 | 说明 |\n|--------|--------|------|\n| `ANTHROPIC_API_KEY` | Anthropic | Claude API 密钥 |\n| `OPENAI_API_KEY` | OpenAI | GPT API 密钥 |\n| `GOOGLE_API_KEY` | Google | Gemini API 密钥 |\n\n### 提供商选择\n\n通过配置文件或启动参数指定使用的 LLM 提供商：\n\n```yaml\nllm:\n provider: \"anthropic\" # anthropic | openai | google\n model: \"claude-sonnet-4-20250514\"\n maxTokens: 8192\n```\n\n## 错误处理\n\n### 错误类型分类\n\n| 错误类型 | HTTP 状态码 | 处理方式 |\n|----------|-------------|----------|\n| 认证错误 | 401, 403 | 直接抛出，不重试 |\n| 限流错误 | 429 | 指数退避重试 |\n| 服务器错误 | 500, 502, 503 | 指数退避重试 |\n| 网络错误 | - | 指数退避重试 |\n| 超时错误 | - | 指数退避重试 |\n\n### 错误响应格式\n\n```typescript\ninterface LLMError {\n provider: string; // 提供商名称\n code: string; // 错误代码\n message: string; // 错误描述\n retryable: boolean; // 是否可重试\n originalError?: Error; // 原始错误对象\n}\n```\n\n## 扩展新的提供商\n\n如需添加新的 LLM 提供商，需完成以下步骤：\n\n1. **创建提供商文件**：在 `providers/` 下创建 `newprovider.ts`\n2. **实现 Provider 接口**：实现统一的调用方法\n3. **注册到工厂**：在 `index.ts` 中添加新提供商\n4. **添加配置支持**：更新配置解析逻辑\n5. **编写测试用例**：确保错误处理和响应解析正确\n\n```typescript\n// 实现示例\nexport class NewProvider implements LLMProvider {\n constructor(config: ProviderConfig) { /* ... */ }\n async complete(request: LLMRequest): Promise { /* ... */ }\n async stream(request: LLMRequest): AsyncIterable { /* ... */ }\n}\n```\n\n## 最佳实践\n\n### 生产环境建议\n\n- **使用环境变量**：不要在代码中硬编码 API 密钥\n- **配置重试策略**：根据提供商限流调整重试参数\n- **监控 token 使用**：避免意外超支\n- **设置超时限制**：防止长时间阻塞\n\n### 开发调试建议\n\n- **使用本地模拟**：开发时可用 mock 提供商\n- **启用详细日志**：便于追踪请求/响应\n- **测试边界情况**：验证 token 限制和错误处理\n\n---\n\n\n\n## 工具系统\n\n### 相关页面\n\n相关主题：[Agent核心系统](#agent-system), [LLM提供商集成](#llm-providers), [版本控制系统](#version-control)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agent/infra/tools/types.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/types.ts)\n- [src/agent/infra/tools/tool-registry.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/tool-registry.ts)\n- [src/agent/infra/tools/tool-manager.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/tool-manager.ts)\n- [src/agent/infra/tools/core-tool-scheduler.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/core-tool-scheduler.ts)\n- [src/agent/infra/tools/implementations/read-file-tool.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/implementations/read-file-tool.ts)\n- [src/agent/infra/tools/implementations/write-file-tool.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/implementations/write-file-tool.ts)\n- [src/agent/infra/tools/implementations/code-exec-tool.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/implementations/code-exec-tool.ts)\n- [src/agent/resources/tools](https://github.com/campfirein/byterover-cli/blob/main/src/agent/resources/tools)\n \n\n# 工具系统\n\n## 概述\n\nByteRover CLI 的工具系统是 AI 代理与代码库交互的核心桥梁。该系统提供了一套标准化的工具接口，使 AI 代理能够执行文件操作、代码执行、知识管理等多种任务。通过统一的工具注册、调度和执行机制，实现了工具的模块化管理和安全验证。资料来源：[src/agent/infra/tools/tool-registry.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/tool-registry.ts)\n\n## 核心架构\n\n工具系统采用分层架构设计，包含以下核心组件：\n\n### 组件层级\n\n```mermaid\ngraph TD\n A[AI 代理层] --> B[工具管理器 ToolManager]\n B --> C[工具注册表 ToolRegistry]\n C --> D[核心工具调度器 CoreToolScheduler]\n D --> E[具体工具实现]\n \n E --> E1[ReadFileTool]\n E --> E2[WriteFileTool]\n E --> E3[CodeExecTool]\n E --> E4[CurateTool]\n \n F[命令验证器 CommandValidator] --> B\n G[沙箱服务 CurateService] --> E4\n```\n\n### 核心组件表\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| ToolRegistry | `src/agent/infra/tools/tool-registry.ts` | 工具注册、查找、生命周期管理 |\n| ToolManager | `src/agent/infra/tools/tool-manager.ts` | 工具调度、参数验证、执行协调 |\n| CoreToolScheduler | `src/agent/infra/tools/core-tool-scheduler.ts` | 异步任务队列、并发控制 |\n| CommandValidator | `src/agent/infra/process/command-validator.ts` | 命令安全验证、危险模式检测 |\n\n资料来源：[src/agent/infra/tools/tool-manager.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/tool-manager.ts)\n\n## 工具类型体系\n\n### 类型定义\n\n工具系统定义了丰富的类型体系来规范工具的结构和行为。工具必须实现标准接口，包含名称、描述、参数模式和执行逻辑。资料来源：[src/agent/infra/tools/types.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/types.ts)\n\n### 核心工具实现\n\n#### ReadFileTool（读取文件工具）\n\n提供文件系统读取能力，支持以下功能：\n\n- 单文件读取，返回文件内容和元数据\n- 支持行数限制和截断检测\n- 文件路径验证和访问控制\n\n```typescript\n// 读取文件工具的典型调用模式\nawait tools.readFile('path/to/file.txt')\n// 返回: { content: string, lines: number, truncated: boolean }\n```\n\n资料来源：[src/agent/infra/tools/implementations/read-file-tool.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/implementations/read-file-tool.ts)\n\n#### WriteFileTool（写入文件工具）\n\n提供文件系统写入能力，支持：\n\n- 新建文件内容\n- 更新现有文件\n- 批量文件操作\n\n#### CodeExecTool（代码执行工具）\n\n在沙箱环境中执行代码，具备以下特性：\n\n- 支持多种编程语言的代码执行\n- 内置文件系统操作工具（readFile、grep）\n- 与 curate 服务集成进行知识管理\n- 批处理模式（每次处理 5-10 个文件）\n\n```typescript\n// 代码执行工具中的工具调用\nconst fileContent = await tools.readFile('path/to/file')\nconst matches = await tools.grep(']*path=\".*README.*\">', { path: tmpFilePath })\nawait tools.curate([{ type: 'ADD', path: 'overview', data: { concept: '...' } }])\n```\n\n资料来源：[src/agent/infra/tools/implementations/code-exec-tool.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/implementations/code-exec-tool.ts)\n\n## 工具执行流程\n\n### 执行状态机\n\n工具执行过程中会经历多种状态，TUI 组件通过状态渲染不同的视觉效果：\n\n```mermaid\nstateDiagram-v2\n [*] --> pending: 任务创建\n pending --> running: 开始执行\n running --> completed: 执行成功\n running --> failed: 执行失败\n completed --> [*]\n failed --> [*]\n```\n\n### TUI 状态显示\n\n在执行视图中，不同状态对应不同的显示效果：\n\n| 状态 | 显示样式 | 符号 |\n|------|----------|------|\n| pending | 默认灰色 | `○` |\n| running | 闪烁动画 | `◐` |\n| completed | 绿色高亮 | `✓` |\n| failed | 红色高亮 | `✗` |\n\n资料来源：[src/tui/components/execution/execution-tool.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/tui/components/execution/execution-tool.tsx)\n\n### 执行日志视图\n\n执行日志组件（ExpandedLogView）负责渲染工具调用结果：\n\n```mermaid\ngraph LR\n A[日志数据] --> B{running?}\n B -->|是| C[显示流式内容]\n B -->|否| D{completed?}\n D -->|是| E[显示更改]\n D -->|否| F[显示错误]\n```\n\n组件支持以下渲染内容：\n\n- 工具调用参数和名称\n- 流式文本内容（带光标动画）\n- 完整执行结果\n- 文件变更摘要（创建/更新）\n\n资料来源：[src/tui/components/execution/expanded-log-view.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/tui/components/execution/expanded-log-view.tsx)\n\n## 命令验证与安全\n\n### 安全验证机制\n\nCommandValidator 组件负责验证命令的安全性，支持多层级的安全控制：\n\n```typescript\n// 只读命令白名单\nconst readOnlyCommands = [\n /git\\s+(status|log|diff|show|branch|tag|fetch|pull)(?!\\s+-)/i,\n /cat\\s+.*>/,\n /find\\s+.*>/,\n]\n```\n\n### 验证规则\n\n| 验证类型 | 说明 | 配置来源 |\n|----------|------|----------|\n| 危险模式检测 | 检测 rm -rf 等危险命令 | blockedCommands |\n| 白名单验证 | 允许的命令列表 | allowedCommands |\n| 安全级别 | 控制验证严格程度 | securityLevel |\n| 路径提取 | 验证文件路径安全性 | extractPathArguments |\n\n资料来源：[src/agent/infra/process/command-validator.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/process/command-validator.ts)\n\n## 工具资源定义\n\n### 工具描述格式\n\n工具通过 Markdown 格式定义，存储在 `src/agent/resources/tools` 目录。标准格式包含：\n\n- 工具名称和描述\n- 参数说明（名称、类型、必填、默认值）\n- 使用示例\n- 返回值格式\n\n### 工具模板结构\n\n```markdown\n## 工具名称\n\n描述工具用途和功能\n\n### 参数\n| 参数名 | 类型 | 必填 | 默认值 | 说明 |\n\n### 示例\n```bash\n工具调用示例\n```\n\n### 返回值\n返回数据格式说明\n```\n\n资料来源：[src/agent/resources/tools](https://github.com/campfirein/byterover-cli/blob/main/src/agent/resources/tools)\n\n## 异步调度机制\n\n### 核心调度器\n\nCoreToolScheduler 负责管理工具执行的异步队列：\n\n- 并发任务数量控制\n- 任务优先级管理\n- 执行结果回调\n- 错误处理和重试机制\n\n### 调度配置\n\n| 配置项 | 说明 | 默认值 |\n|--------|------|--------|\n| maxConcurrency | 最大并发数 | 3 |\n| timeout | 单任务超时 | 30000ms |\n| retryCount | 失败重试次数 | 2 |\n\n资料来源：[src/agent/infra/tools/core-tool-scheduler.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/core-tool-scheduler.ts)\n\n## 工具管理服务\n\n### CurateService 集成\n\nCurateService 为代码执行工具提供知识管理能力：\n\n- 添加、更新、删除知识条目\n- 批量操作支持（最多 5 个文件）\n- 域检测和自动分类\n- 标题和内容验证\n\n```typescript\n// curate 操作类型\ntype CurateOperation = {\n type: 'ADD' | 'UPDATE' | 'DELETE' | 'UPSERT'\n path: string\n title?: string\n content?: {\n rawConcept?: string\n narrative?: string\n }\n}\n```\n\n资料来源：[src/agent/infra/sandbox/curate-service.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/sandbox/curate-service.ts)\n\n## 最佳实践\n\n### 工具使用建议\n\n1. **批量处理**：使用 code-exec-tool 时，每次处理 5-10 个文件以控制输出大小\n2. **路径验证**：所有文件操作前验证路径在项目目录内\n3. **错误处理**：检查 truncated 标志以处理大文件截断\n4. **安全优先**：使用命令验证器过滤危险操作\n\n### 性能优化\n\n| 场景 | 优化策略 |\n|------|----------|\n| 大文件读取 | 使用行数限制和截断检测 |\n| 批量搜索 | 使用 grep 替代多次 readFile |\n| 并发控制 | 调整 CoreToolScheduler 的 maxConcurrency |\n\n### 调试技巧\n\n- 使用 TUI 的 expanded-log-view 查看详细执行日志\n- 检查 toolCalls 数组追踪工具调用链\n- 监控 streamingContent 观察实时输出\n\n---\n\n\n\n## 上下文树与知识管理\n\n### 相关页面\n\n相关主题：[Agent核心系统](#agent-system), [版本控制系统](#version-control), [Swarm多代理协调](#swarm-coordination)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agent/infra/map/abstract-generator.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/map/abstract-generator.ts)\n- [src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts)\n- [src/agent/resources/prompts/curate-detail-preservation.yml](https://github.com/campfirein/byterover-cli/blob/main/src/agent/resources/prompts/curate-detail-preservation.yml)\n- [src/agent/infra/sandbox/curate-service.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/sandbox/curate-service.ts)\n- [src/server/templates/README.md](https://github.com/campfirein/byterover-cli/blob/main/src/server/templates/README.md)\n \n\n# 上下文树与知识管理\n\n## 概述\n\n上下文树（Context Tree）是 ByteRover CLI 中的核心知识管理基础设施，用于组织和持久化 AI Agent 在项目开发过程中积累的结构化知识。通过上下文树，系统能够将分散的代码模式、设计决策、项目约定等内容转化为可查询、可复用的知识资产。\n\n上下文树位于项目根目录的 `.brv/context-tree/` 路径下，采用分层目录结构组织知识内容，支持动态域名创建和自动摘要生成。\n\n## 架构设计\n\n### 核心组件\n\n| 组件 | 职责 | 文件位置 |\n|------|------|----------|\n| ContextTreeStore | 上下文树数据存储与检索 | `src/agent/infra/map/context-tree-store.ts` |\n| AbstractGenerator | 知识摘要生成服务 | `src/agent/infra/map/abstract-generator.ts` |\n| CurateService | 知识整理操作执行器 | `src/agent/infra/sandbox/curate-service.ts` |\n| ContextTreeContributor | 系统提示词上下文注入 | `src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts` |\n\n### 数据流架构\n\n```mermaid\ngraph TD\n A[AI Agent 执行任务] --> B[Curate 操作请求]\n B --> C[CurateService 验证]\n C --> D{验证结果}\n D -->|失败| E[返回失败详情]\n D -->|成功| F[写入 ContextTreeStore]\n F --> G[生成摘要 AbstractGenerator]\n G --> H[更新系统提示词]\n H --> I[ContextTreeContributor 注入结构]\n I --> J[Agent 下次交互使用知识]\n```\n\n## 目录结构规范\n\n上下文树采用固定的目录层次结构组织知识内容：\n\n```\n.brv/context-tree/\n├── _index.md # 根级自动生成摘要\n├── architecture/ # 动态域名：架构相关知识\n│ ├── _index.md # 目录摘要\n│ ├── system_design.md\n│ └── api_patterns.md\n├── patterns/ # 代码模式与最佳实践\n│ ├── _index.md\n│ └── authentication.md\n├── conventions/ # 团队约定与规范\n│ ├── _index.md\n│ └── git_workflow.md\n└── _archived/ # 归档的低优先级知识\n └── old_notes.md\n```\n\n### 结构规范说明\n\n| 结构元素 | 说明 | 创建规则 |\n|----------|------|----------|\n| 顶级文件夹 | 代表知识领域（Domain） | 根据内容语义动态创建 |\n| `.md` 文件 | 单个知识主题（Topic） | 包含具体知识内容 |\n| `context.md` | 目录级知识入口 | 子文件夹可包含此文件定义目录级上下文 |\n| `_index.md` | 自动生成的目录摘要 | 系统自动维护 |\n| `_archived/` | 归档存储 | 存放低重要性条目 |\n\n资料来源：[src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts:27-35]()\n\n## Curate 操作类型\n\nCurateService 实现了四种核心知识操作类型，用于管理系统中的知识条目：\n\n| 操作类型 | 说明 | 必需字段 |\n|----------|------|----------|\n| ADD | 添加新的知识条目 | title, content |\n| UPDATE | 更新现有条目内容 | title, content |\n| UPSERT | 存在则更新，不存在则添加 | title, content |\n| DELETE | 删除指定条目 | path |\n| MOVE | 移动条目到新位置 | from, to |\n\n### 操作验证规则\n\n```typescript\n// ADD、UPDATE、UPSERT 必须包含 content\nif ((op.type === 'ADD' || op.type === 'UPDATE' || op.type === 'UPSERT') && !op.content) {\n failures.push({\n message: `${op.type} operation requires content with rawConcept and/or narrative.`,\n path: op.path,\n status: 'failed',\n type: op.type,\n })\n}\n\n// ADD、UPDATE、UPSERT 必须包含 title（作为 .md 文件名）\nif ((op.type === 'ADD' || op.type === 'UPDATE' || op.type === 'UPSERT') && !op.title) {\n failures.push({\n message: `${op.type} operation requires a title (becomes the .md filename).`,\n path: op.path,\n status: 'failed',\n type: op.type,\n })\n}\n```\n\n资料来源：[src/agent/infra/sandbox/curate-service.ts:14-35]()\n\n## 知识内容结构\n\n### 知识条目数据模型\n\n每个知识条目（Topic）包含以下结构化字段：\n\n```typescript\ninterface KnowledgeEntry {\n path: string; // 条目路径\n title: string; // 标题（决定文件名）\n content: {\n rawConcept: string; // 原始概念定义\n facts: Fact[]; // 提取的事实清单\n };\n narrative: {\n rules?: string[]; // 规则与约束\n highlights?: string[]; // 重点与亮点\n structure?: string; // 结构说明\n examples?: string[]; // 示例列表\n flow?: string; // 工作流程\n diagrams?: Diagram[]; // 图表引用\n dependencies?: string[]; // 依赖关系\n };\n metadata: {\n tags: string[];\n category: string;\n createdAt: string;\n updatedAt: string;\n };\n}\n```\n\n### 图表类型支持\n\n```typescript\ninterface Diagram {\n type: 'mermaid' | 'plantuml' | 'ascii' | 'other';\n title?: string;\n content: string;\n}\n```\n\n资料来源：[src/agent/resources/prompts/curate-detail-preservation.yml:1-40]()\n\n## 摘要生成系统\n\n### AbstractGenerator 工作流程\n\nAbstractGenerator 负责从批量知识文件中生成结构化摘要，使用 XML 格式输出：\n\n```mermaid\ngraph LR\n A[输入文件列表] --> B[生成 XML 格式]\n B --> C[构建 LLM Prompt]\n C --> D[模型生成概述]\n D --> E[解析 XML 响应]\n E --> F[提取 或 ]\n F --> G[返回 Map]\n```\n\n### 输出格式规范\n\n```xml\n\n\n- bullet 1\n- bullet 2\n...\n\n\n```\n\n### 解析实现要点\n\n解析器采用锚定于 `` 开启标签的策略，避免内容中包含 `` 时导致匹配错误：\n\n```typescript\nfunction parseBatchedTags(response: string, innerTag: 'abstract' | 'overview'): Map {\n // 每个 opener 拥有到下一个 opener（或字符串结尾）的响应片段\n // 内部正则表达式从该片段中提取有效载荷\n}\n```\n\n资料来源：[src/agent/infra/map/abstract-generator.ts:20-60]()\n\n## 知识保存与提取\n\n### 事实提取规范\n\n知识内容中的事实必须按类别精确提取：\n\n| 类别 | 说明 | 示例 |\n|------|------|------|\n| personal | 用户个人信息 | \"我的名字是 Andy\" |\n| project | 项目配置值 | 端口号、URL、版本号 |\n| convention | 团队约定与流程 | Git 工作流规范 |\n\n### 非代码内容保存\n\n| 内容类型 | 保存位置 | 说明 |\n|----------|----------|------|\n| 会议决策与理由 | `narrative.rules` / `narrative.highlights` | 必须保留完整决策过程 |\n| 操作项与截止日期 | `narrative.examples` | 包含负责人和期限 |\n| 投票结果与优先级 | `narrative.highlights` | 保留精确数值 |\n| 状态更新与阻塞项 | `narrative.dependencies` | 记录当前障碍 |\n| 工作流步骤 | `rawConcept.flow` | 包含所有条件判断 |\n| 指标与 KPI | `narrative.highlights` | 保留精确值 |\n\n资料来源：[src/agent/resources/prompts/curate-detail-preservation.yml:40-80]()\n\n## 系统提示词集成\n\nContextTreeContributor 负责将上下文树结构注入到 Agent 的系统提示词中：\n\n```mermaid\ngraph TD\n A[加载 ContextTreeStore] --> B[获取目录结构]\n B --> C{条目数量}\n C -->|< 阈值| D[显示完整结构]\n C -->|>= 阈值| E[截断并显示计数]\n D --> F[构建结构说明]\n E --> F\n F --> G[注入系统提示词]\n```\n\n### 动态域名说明\n\n```typescript\n// 构建结构指南\n'## Structure Guide',\n'- Each top-level folder is a **domain** (dynamically created based on content)',\n'- Inside domains are **topics** as `.md` files or subfolders with `context.md`',\n\n// 动态域名规则\n'## Dynamic Domains',\n'- Domains are created dynamically based on the semantics of curated content',\n'- Domain names should be descriptive, use snake_case',\n'- Before creating a new domain, check if existing domains could accommodate the content'\n```\n\n### 截断机制\n\n当条目数量超过显示阈值时，系统会截断输出并显示剩余数量：\n\n```\n.brv/context-tree/\n architecture/\n patterns/\n conventions/\n [5 additional entries not shown]\n```\n\n资料来源：[src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts:1-80]()\n\n## 知识查询与使用\n\n### 查询命令\n\nAgent 通过上下文树结构查询相关知识：\n\n| 命令类型 | 说明 | 查询范围 |\n|----------|------|----------|\n| Query | 检索相关知识条目 | 仅在上下文树结构内搜索 |\n| Expand | 展开归档知识 | 可深入 `_archived/` 目录 |\n\n### 使用建议\n\n1. **创建新条目前**：先检查现有域名是否可容纳新内容\n2. **域名命名**：使用 snake_case 格式，描述性强（如 `architecture`、`market_trends`）\n3. **知识归档**：低优先级条目可移至 `_archived/`，使用 `expand_knowledge` 命令可展开查看\n\n## 最佳实践\n\n### 知识组织原则\n\n1. **单一职责**：每个主题文件专注于一个知识领域\n2. **语义化分类**：根据内容语义选择合适的域名，而非机械分类\n3. **摘要更新**：修改知识后及时更新相关 `_index.md` 摘要\n4. **事实优先**：关键数值、配置、约定应提取为 facts 便于快速引用\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| `src/agent/infra/map/context-tree-store.ts` | 上下文树数据存储实现 |\n| `src/agent/infra/map/abstract-generator.ts` | 知识摘要生成器 |\n| `src/agent/infra/sandbox/curate-service.ts` | Curate 操作服务 |\n| `src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts` | 系统提示词注入 |\n| `src/agent/resources/prompts/curate-detail-preservation.yml` | 内容保存规范 |\n\n---\n\n\n\n## 版本控制系统\n\n### 相关页面\n\n相关主题：[上下文树与知识管理](#context-tree)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/shared/transport/events/vc-events.ts](https://github.com/campfirein/byterover-cli/blob/main/src/shared/transport/events/vc-events.ts)\n- [src/server/templates/skill/SKILL.md](https://github.com/campfirein/byterover-cli/blob/main/src/server/templates/skill/SKILL.md)\n- [src/server/infra/http/review-ui.ts](https://github.com/campfirein/byterover-cli/blob/main/src/server/infra/http/review-ui.ts)\n- [src/agent/infra/map/abstract-generator.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/map/abstract-generator.ts)\n- [src/agent/infra/sandbox/curate-service.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/sandbox/curate-service.ts)\n- [src/tui/features/hub/components/hub-detail-step.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/tui/features/hub/components/hub-detail-step.tsx)\n \n\n# 版本控制系统\n\n## 概述\n\nByteRover CLI 的版本控制系统（Version Control System，简称 VC）是该项目提供的核心功能之一。该系统通过 `brv vc` 命令族为 AI 编码代理提供持久化的上下文记忆能力，支持本地文件变更追踪、云端同步以及团队协作。\n\n版本控制系统的设计目标是让 AI 代理能够在项目目录中追踪和管理文件变更，同时与 ByteRover 云服务协同工作，实现知识的持久化和跨工具共享。\n\n## 核心架构\n\n### 类型定义体系\n\n版本控制系统的类型定义集中于 `src/shared/transport/events/vc-events.ts` 文件中，定义了完整的 diff 操作类型体系：\n\n```typescript\n// 资料来源：src/shared/transport/events/vc-events.ts\nexport type VcDiffMode =\n | {from: string; kind: 'range'; to: string}\n | {kind: 'ref-vs-worktree'; ref: string}\n | {kind: 'staged'}\n | {kind: 'unstaged'}\n\nexport type VcDiffFileStatus = 'added' | 'deleted' | 'modified'\n\nexport interface IVcDiffFile {\n binary?: boolean\n newContent: string\n newOid: string\n oldContent: string\n oldOid: string\n path: string\n status: VcDiffFileStatus\n}\n```\n\n### Diff 模式分类\n\n系统支持四种差异模式，与 Git 原生命令保持一致：\n\n| 模式名称 | 描述 | 对应 Git 命令 |\n|---------|------|--------------|\n| `unstaged` | 工作目录与暂存区对比（仅追踪文件） | `git diff` |\n| `staged` | 暂存区与 HEAD 对比 | `git diff --staged` |\n| `ref-vs-worktree` | 指定提交/分支与工作目录对比 | `git diff [` |\n| `range` | 两个引用之间的差异 | `git diff ..` |\n\n```mermaid\ngraph TD\n A[版本控制系统] --> B[Diff 操作]\n B --> C{模式选择}\n C -->|unstaged| D[WORKDIR → STAGE]\n C -->|staged| E[HEAD → STAGE]\n C -->|ref-vs-worktree| F[ref → WORKDIR]\n C -->|range| G[ref1 → ref2]\n \n H[IVcDiffFile] --> I[status: added/deleted/modified]\n H --> J[newOid/oldOid]\n H --> K[newContent/oldContent]\n H --> L[binary flag]\n```\n\n## 命令体系\n\n### 命令分类总览\n\n`brv vc` 命令提供完整的版本控制操作能力，文档位于 `src/server/templates/skill/SKILL.md`：\n\n| 命令 | 功能描述 |\n|------|---------|\n| `brv vc add` | 暂存文件变更 |\n| `brv vc commit` | 提交暂存区变更 |\n| `brv vc log` | 查看提交历史 |\n| `brv vc reset` | 取消暂存或撤销提交 |\n| `brv vc branch` | 分支管理 |\n| `brv vc checkout` | 切换分支 |\n| `brv vc merge` | 合并分支 |\n| `brv vc remote` | 远程仓库操作 |\n\n### 文件操作命令\n\n#### 暂存文件 (`brv vc add`)\n\n```bash\nbrv vc add . # 暂存所有文件\nbrv vc add notes.md docs/ # 暂存指定文件\n```\n\n暂存操作会将工作目录中的变更移动到暂存区，为提交做准备。\n\n#### 查看历史 (`brv vc log`)\n\n```bash\nbrv vc log # 查看最近提交\nbrv vc log --limit 20 # 限制显示数量\nbrv vc log --all # 查看所有分支历史\n```\n\n#### 重置操作 (`brv vc reset`)\n\n| 命令 | 行为 |\n|------|------|\n| `brv vc reset` | 取消所有文件暂存 |\n| `brv vc reset ` | 取消指定文件暂存 |\n| `brv vc reset --soft HEAD~1` | 撤销上次提交，保留变更在暂存区 |\n| `brv vc reset --hard HEAD~1` | 撤销上次提交并丢弃所有变更 |\n\n### 分支管理\n\n#### 分支操作\n\n```bash\nbrv vc branch # 列出本地分支\nbrv vc branch feature/auth # 创建新分支\nbrv vc branch -a # 列出所有分支（含远程追踪分支）\nbrv vc branch -d feature/auth # 删除分支\n```\n\n#### 切换分支\n\n```bash\nbrv vc checkout feature/auth # 切换到现有分支\nbrv vc checkout -b feature/new # 创建并切换到新分支\n```\n\n#### 合并操作\n\n```bash\nbrv vc merge feature/auth # 将目标分支合并到当前分支\nbrv vc merge --continue # 解决冲突后继续合并\nbrv vc merge --abort # 中止合并操作\n```\n\n#### 设置上游追踪\n\n```bash\nbrv vc branch --set-upstream-to origin/main\n```\n\n```mermaid\ngraph LR\n A[brv vc branch] --> B[create]\n A --> C[list]\n A --> D[delete]\n A --> E[set-upstream]\n \n F[brv vc checkout] --> G[switch]\n F --> H[create-and-switch]\n \n I[brv vc merge] --> J[normal]\n I --> K[continue]\n I --> L[abort]\n```\n\n### 云端同步\n\n版本控制系统支持与 ByteRover 云服务同步，需要先完成身份认证和远程仓库配置：\n\n```bash\nbrv login # ByteRover 身份认证\nbrv vc remote # 查看当前远程仓库\nbrv vc remote add origin # 添加远程仓库\n```\n\n云同步功能允许用户将本地版本控制状态与云端保持一致，实现跨设备和团队协作。\n\n## 评审界面集成\n\nByteRover 提供本地 HITL（Human-in-the-Loop）评审界面，集成于 `src/server/infra/http/review-ui.ts`：\n\n### 评审页面架构\n\n评审界面使用自包含的 HTML/CSS/JS 实现，支持变更的语义化摘要展示：\n\n```typescript\n// 资料来源：src/server/infra/http/review-ui.ts\nexport function getReviewPageHtml(): string {\n return `\n\n\n\n\nByteRover Review\n\n\n\n \n\n`\n}\n```\n\n### 文件卡片渲染\n\n评审界面为每个变更文件生成卡片，包含操作类型徽章和操作按钮：\n\n```typescript\n// 资料来源：src/server/infra/http/review-ui.ts\nfunction renderFileCard(file, index) {\n const opBadges = file.operations.map(op =>\n '' + op.type + ''\n ).join('');\n \n return ']'\n + ''\n + '
';\n}\n```\n\n### 评审操作按钮\n\n| 按钮 | 功能 |\n|------|------|\n| Approve | 批准变更 |\n| Reject | 拒绝变更 |\n\n## 抽象生成与摘要\n\n版本控制系统与知识管理模块集成，通过抽象生成队列处理文档摘要：\n\n```typescript\n// 资料来源：src/agent/infra/sandbox/curate-service.ts\nexport class CurateService implements ICurateService {\n async curate(operations: CurateOperation[], options?: CurateOptions): Promise {\n const rawBasePath = options?.basePath ?? DEFAULT_BASE_PATH\n // 处理整理操作...\n }\n}\n```\n\n### 摘要生成提示词\n\n系统使用专门的提示词模板生成文件摘要，支持单行摘要和结构化概览两种模式：\n\n```typescript\n// 资料来源：src/agent/infra/map/abstract-generator.ts\nfunction buildBatchedAbstractPrompt(items) {\n return `For each of the following knowledge documents, produce a ONE-LINE summary (max 80 tokens)\nOutput format — emit exactly one element per input file:\n\">One-line summary.`\n}\n\nfunction buildBatchedOverviewPrompt(items) {\n return `For each of the following knowledge documents, produce a structured overview (markdown, under 1500 tokens) that includes:\n- Key points (3-7 bullet points)\n- Structure / sections summary\n- Any notable entities, patterns, or decisions mentioned`\n}\n```\n\n### CDATA 封装\n\n为防止 XML 解析冲突，文档内容使用 CDATA 段封装：\n\n```typescript\n// 资料来源：src/agent/infra/map/abstract-generator.ts\nfunction wrapCdata(content: string): string {\n return `', ']]]]>')}]]>`\n}\n```\n\n## 数据结构\n\n### 版本控制 Diff 文件结构\n\n```typescript\ninterface IVcDiffFile {\n /** 二进制文件标志（任一端包含 NUL 字节时为 true） */\n binary?: boolean\n /** 新版本内容 */\n newContent: string\n /** 7 位短 OID，新增文件时省略 */\n newOid: string\n /** 旧版本内容 */\n oldContent: string\n /** 删除文件时省略 */\n oldOid: string\n /** 文件路径 */\n path: string\n /** 变更类型 */\n status: VcDiffFileStatus\n}\n```\n\n### Diff 端定义\n\n```typescript\n// 资料来源：src/shared/transport/events/vc-events.ts\ninterface VcDiffSide {\n oid: string\n content: string\n}\n```\n\n## 总结\n\nByteRover CLI 的版本控制系统是一个完整的功能模块，它：\n\n1. **提供命令行接口**：通过 `brv vc` 命令族提供 Git 风格的操作体验\n2. **支持多种 Diff 模式**：兼容 unstaged、staged、ref-vs-worktree、range 四种模式\n3. **集成评审流程**：提供内置的 HITL 评审界面\n4. **支持云端同步**：与 ByteRover 云服务集成实现协作\n5. **与知识管理协同**：与上下文树和知识整理系统深度集成\n\n该系统专为 AI 编码代理设计，使其能够像人类开发者一样有效地管理和追踪项目变更。\n\n---\n\n\n\n## Swarm多代理协调\n\n### 相关页面\n\n相关主题：[上下文树与知识管理](#context-tree), [Agent核心系统](#agent-system)\n\n# Swarm多代理协调\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agent/core/domain/swarm/types.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/core/domain/swarm/types.ts)\n- [src/agent/infra/swarm/swarm-coordinator.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/swarm/swarm-coordinator.ts)\n- [src/agent/infra/swarm/swarm-router.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/swarm/swarm-router.ts)\n- [src/agent/infra/swarm/adapters/byterover-adapter.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/swarm/adapters/byterover-adapter.ts)\n- [src/agent/infra/swarm/wizard/swarm-wizard.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/swarm/wizard/swarm-wizard.ts)\n- [src/oclif/commands/swarm/query.ts](https://github.com/campfirein/byterover-cli/blob/main/src/oclif/commands/swarm/query.ts)\n \n\n## 概述\n\nSwarm（多代理协调系统）是ByteRover CLI中的一个核心模块，旨在实现跨多个记忆提供商的智能协调与信息检索。该系统通过统一的查询和整理接口，将ByteRover上下文树、Obsidian保险库、GBrain、本地Markdown文件夹以及Memory Wiki等多个记忆源进行整合，为用户提供无缝的知识访问体验。\n\nSwarm的核心设计理念是**多提供者并行查询**与**智能结果融合**。当用户配置了多个记忆提供者时，Swarm能够同时向所有可用提供者发起查询请求，并通过RRF（Reciprocal Rank Fusion，倒数排名融合）算法对结果进行排序和去重，最终返回最优的检索结果。资料来源：[src/server/templates/skill/SKILL.md]()\n\n## 核心架构\n\n### 系统组件\n\nSwarm多代理协调系统由以下几个核心组件构成：\n\n| 组件 | 职责 | 文件位置 |\n|------|------|----------|\n| SwarmCoordinator | 协调多个提供者的查询与整理操作 | `src/agent/infra/swarm/swarm-coordinator.ts` |\n| SwarmRouter | 根据内容类型和配置路由请求到合适的提供者 | `src/agent/infra/swarm/swarm-router.ts` |\n| ByteoverAdapter | ByteRover上下文树适配器 | `src/agent/infra/swarm/adapters/byterover-adapter.ts` |\n| SwarmWizard | 引导用户配置Swarm设置 | `src/agent/infra/swarm/wizard/swarm-wizard.ts` |\n| SwarmConfigLoader | 加载和验证Swarm配置文件 | `src/agent/infra/swarm/config/swarm-config-loader.ts` |\n\n### 数据流架构\n\n```mermaid\ngraph TD\n User[用户请求] --> CLI[brv swarm query/curate]\n CLI --> Coordinator[SwarmCoordinator]\n Coordinator --> Router[SwarmRouter]\n Router --> Providers[多个记忆提供者]\n \n Providers --> ByteRover[ByteRover上下文树]\n Providers --> Obsidian[Obsidian保险库]\n Providers --> GBrain[GBrain实体库]\n Providers --> LocalMD[本地Markdown]\n Providers --> MemWiki[Memory Wiki]\n \n Providers --> RRF[RRF结果融合]\n RRF --> Filter[精确度过滤]\n Filter --> Result[最终结果]\n \n subgraph 配置层\n Config[.brv/swarm/config.yaml]\n ConfigLoader[SwarmConfigLoader]\n end\n \n ConfigLoader --> Config\n Coordinator -.依赖.-> ConfigLoader\n```\n\n## 记忆提供者\n\nSwarm支持五种类型的记忆提供者，每种提供者都有其特定的用途和配置方式。\n\n### 提供者类型\n\n| 提供者 | 类型标识 | 用途 | 可写 |\n|--------|----------|------|------|\n| ByteRover | `byterover` | 上下文树主存储 | 是 |\n| Obsidian | `obsidian` | Markdown笔记Vault | 可配置 |\n| GBrain | `gbrain` | 实体概念存储 | 可配置 |\n| Local Markdown | `local-markdown` | 本地文件夹笔记 | 可配置 |\n| Memory Wiki | `memory-wiki` | Wiki格式知识库 | 可配置 |\n\n### 提供者配置\n\n每个提供者在Swarm配置中都有以下可配置属性：\n\n```yaml\nproviders:\n byterover:\n enabled: true\n type: memory-tree\n obsidian:\n enabled: true\n path: /Users/you/Documents/MyObsidian\n type: vault\n gbrain:\n enabled: true\n path: /Users/you/workspaces/gbrain\n type: entity-store\n memory-wiki:\n enabled: true\n path: /Users/you/.openclaw/wiki/main\n type: wiki\n```\n\n资料来源：[src/server/templates/skill/SKILL.md]()\n\n## Swarm配置系统\n\n### 配置文件加载\n\nSwarm配置存储在项目根目录的`.brv/swarm/config.yaml`文件中。配置加载器负责读取、解析和验证配置。\n\n配置加载流程：\n\n1. 读取`.brv/swarm/config.yaml`文件\n2. 解析YAML内容\n3. 解析环境变量引用（`${VAR}`格式）\n4. 通过Zod Schema进行验证\n5. 返回类型安全的SwarmConfig对象\n\n```typescript\nexport async function loadSwarmConfig(\n projectRoot: string,\n env?: Record\n): Promise\n```\n\n如果配置文件不存在，抛出错误提示用户运行`brv swarm onboard`命令创建配置。资料来源：[src/agent/infra/swarm/config/swarm-config-loader.ts]()\n\n### 配置验证\n\n配置验证确保Swarm设置的完整性和正确性。验证内容包括：\n\n- 提供者路径有效性\n- 提供者类型识别\n- 环境变量引用解析\n- Schema类型检查\n\n## 查询操作\n\n### 查询流程\n\nSwarm查询操作通过以下步骤执行：\n\n```mermaid\ngraph LR\n A[查询请求] --> B[分类查询类型]\n B --> C[选择提供者]\n C --> D[并行查询所有提供者]\n D --> E[收集结果]\n E --> F[RRF融合排序]\n F --> G[精确度过滤]\n G --> H[返回结果]\n```\n\n### 查询分类\n\nSwarm能够自动分类查询类型，以优化提供者选择：\n\n| 查询类型 | 特征 | 适用场景 |\n|----------|------|----------|\n| `factual` | 事实性问题 | 具体信息检索 |\n| `semantic` | 语义理解 | 概念和模式识别 |\n| `contextual` | 上下文相关 | 依赖上下文的查询 |\n\n### 查询命令\n\n```bash\n# 基本查询\nbrv swarm query \"authentication patterns\"\n\n# 显示详细信息\nbrv swarm query \"authentication patterns\" --explain\n\n# JSON格式输出\nbrv swarm query \"rate limiting\" --format json\n\n# 限制结果数量\nbrv swarm query \"testing strategy\" -n 5\n```\n\n### 查询输出示例\n\n使用`--explain`标志时，输出包含详细的分类和提供者信息：\n\n```\nClassification: factual\nProvider selection: 4 of 4 available\n ✓ byterover (healthy, selected, 0 results, 14ms)\n ✓ obsidian (healthy, selected, 5 results, 91ms)\n ✓ memory-wiki (healthy, selected, 2 results, 15ms)\n ✓ gbrain (healthy, selected, 1 results, 260ms)\nEnrichment:\n byterover → obsidian\n byterover → memory-wiki\nResults: 8 raw → 7 after RRF fusion + precision filtering\n```\n\n资料来源：[src/server/templates/skill/SKILL.md]()\n\n### JSON输出格式\n\n```json\n{\n \"meta\": {\n \"queryType\": \"factual\",\n \"totalLatencyMs\": 340,\n \"providers\": {\n \"byterover\": { \"selected\": true, \"resultCount\": 0 },\n \"obsidian\": { \"selected\": true, \"resultCount\": 5 },\n \"gbrain\": { \"selected\": true, \"resultCount\": 1 },\n \"memory-wiki\": { \"selected\": true, \"resultCount\": 1 }\n }\n },\n \"results\": [\n { \"provider\": \"memory-wiki\", \"providerType\": \"memory-wiki\", \"score\": 0.015, \"content\": \"# Rate Limiting ...\" }\n ]\n}\n```\n\n## 整理操作\n\n### 整理流程\n\nSwarm整理（Curate）操作用于将知识存储到最合适的外部记忆提供者中。系统自动分类内容类型并路由到对应的提供者。\n\n```mermaid\ngraph TD\n A[整理请求] --> B[分析内容类型]\n B --> C{内容分类}\n \n C -->|实体/人物| D[GBrain]\n C -->|笔记/TODO| E[本地Markdown]\n C -->|通用内容| F[第一个可写提供者]\n C -->|无可用外部| G[ByteRover上下文树]\n \n D --> H[存储完成]\n E --> H\n F --> H\n G --> H\n```\n\n### 路由规则\n\n| 内容类型 | 目标提供者 | 存储格式 |\n|----------|------------|----------|\n| 人物/组织实体 | GBrain | concept/xxx |\n| 会议笔记/TODO | 本地Markdown | note-xxx.md |\n| 通用内容 | 第一个可写提供者 | 提供者特定格式 |\n| 无外部提供者 | ByteRover | context.md |\n\n### 整理命令\n\n```bash\n# 基本整理\nbrv swarm curate \"Jane Smith is the CTO of TechCorp\"\n\n# 指定提供者\nbrv swarm curate \"meeting notes: decided on JWT\" --provider local-markdown:notes\n\n# 存储到GBrain\nbrv swarm curate \"Architecture uses event sourcing\" --provider gbrain\n\n# JSON输出\nbrv swarm curate \"Test content\" --format json\n```\n\n### 整理输出\n\n```\nStored to gbrain as concept/jane-smith-cto\n```\n\n## Swarm状态检查\n\n### 健康检查\n\n在执行查询或整理操作前，建议先检查Swarm状态以验证提供者的可用性。\n\n```bash\nbrv swarm status\n```\n\n### 状态输出示例\n\n```\nMemory Swarm Health Check\n════════════════════════════════════════\n ✓ ByteRover context-tree (always on)\n ✓ Obsidian /Users/you/Documents/MyObsidian\n ✓ Local .md 1 folder(s)\n ✓ GBrain /Users/you/workspaces/gbrain\n ✓ Memory Wiki /Users/you/.openclaw/wiki/main\n\nWrite Targets:\n gbrain (entity, general)\n local-markdown:project-docs (note, general)\n\nSwarm is operational (5/5 providers configured).\n```\n\n资料来源：[src/server/templates/skill/SKILL.md]()\n\n## 命令行接口\n\n### 可用命令\n\n| 命令 | 功能 | 必需参数 |\n|------|------|----------|\n| `brv swarm query` | 跨提供者搜索 | 查询字符串 |\n| `brv swarm curate` | 存储知识到提供者 | 内容字符串 |\n| `brv swarm status` | 检查提供者健康状态 | 无 |\n| `brv swarm onboard` | 初始化Swarm配置 | 无 |\n\n### 全局参数\n\n| 参数 | 描述 | 默认值 |\n|------|------|--------|\n| `--explain` | 显示详细路由信息 | false |\n| `--format json` | JSON格式输出 | false |\n| `-n <数量>` | 限制结果数量 | 全部 |\n| `--provider ` | 指定目标提供者 | 自动选择 |\n\n## 高级配置\n\n### 提供者选择策略\n\nSwarm支持细粒度的提供者选择控制：\n\n```yaml\nswarm:\n query:\n # 查询时使用的提供者\n providers:\n - byterover\n - obsidian\n - gbrain\n - memory-wiki\n # RRF融合参数\n fusion:\n k: 60 # RRF常数，通常为60\n curate:\n # 整理时的默认提供者优先级\n priority:\n - gbrain\n - local-markdown:project-docs\n - memory-wiki\n```\n\n### 环境变量引用\n\n配置文件支持使用`${VAR}`语法引用环境变量：\n\n```yaml\nproviders:\n obsidian:\n path: ${OBSIDIAN_VAULT_PATH}\n gbrain:\n path: ${GBRAIN_WORKSPACE}\n```\n\n资料来源：[src/agent/infra/swarm/config/swarm-config-loader.ts]()\n\n## 最佳实践\n\n### 查询优化\n\n1. **结合使用**：运行`brv swarm query`的同时运行`brv query`，可以扩大召回范围\n2. **使用explain模式**：调试时使用`--explain`了解提供者选择和融合过程\n3. **限制结果数量**：大数据集时使用`-n`参数控制输出\n\n### 整理策略\n\n1. **检查现有结构**：整理前先检查现有域和主题，避免重复创建\n2. **使用精确提供者**：当需要存储到特定提供者时使用`--provider`参数\n3. **利用自动分类**：信任系统的自动路由逻辑，除非有特殊需求\n\n### 配置建议\n\n1. **定期检查状态**：运行`brv swarm status`确保所有提供者健康\n2. **使用onboard初始化**：首次配置使用`brv swarm onboard`引导完成\n3. **验证配置文件**：确保`.brv/swarm/config.yaml`格式正确\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 原因 | 解决方案 |\n|------|------|----------|\n| 查询无结果 | 提供者路径无效 | 检查配置文件，更新路径 |\n| 整理失败 | 提供者不可写 | 检查提供者写权限 |\n| 配置加载错误 | YAML格式错误 | 验证YAML语法 |\n| 提供者不健康 | 路径不存在 | 确认目录存在 |\n\n### 诊断步骤\n\n1. 运行`brv swarm status`检查所有提供者状态\n2. 验证`.brv/swarm/config.yaml`配置正确\n3. 确认各提供者的存储路径存在且可访问\n4. 检查环境变量是否正确设置\n\n## 相关文档\n\n- [上下文树结构说明](./context-tree-structure.md)\n- [Curate服务文档](./curate-service.md)\n- [命令行参考手册](./command-reference.md)\n\n---\n\n\n\n## TUI交互界面\n\n### 相关页面\n\n相关主题：[WebUI管理面板](#webui-dashboard), [Agent核心系统](#agent-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tui/components/execution/execution-tool.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/tui/components/execution/execution-tool.tsx)\n- [src/tui/components/execution/expanded-log-view.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/tui/components/execution/expanded-log-view.tsx)\n- [src/tui/features/hub/components/hub-detail-step.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/tui/features/hub/components/hub-detail-step.tsx)\n \n\n# TUI交互界面\n\n## 概述\n\nByteRover CLI 的 TUI（终端用户界面）模块是一个基于文本的交互界面，使用 React 组件和渲染库构建，为开发者在终端环境中提供可视化的工作流程体验。TUI 模块位于 `src/tui/` 目录下，采用组件化架构设计，支持命令行操作、日志展示、技能市场浏览等功能。\n\nTUI 界面通过自包含的渲染管线将复杂的 Agent 工作流状态实时呈现给用户，包括工具调用执行、进度追踪、文件变更展示等核心功能。界面采用深色主题设计，符合现代开发者工具的视觉风格。\n\n## 架构设计\n\n### 组件层级结构\n\nTUI 模块遵循 React 组件树结构，主要分为以下几大功能区域：\n\n```mermaid\ngraph TD\n A[TUI Root] --> B[布局组件]\n A --> C[命令输入组件]\n A --> D[执行展示组件]\n A --> E[功能面板]\n \n B --> B1[主布局]\n B --> B2[侧边栏]\n \n C --> C1[命令输入框]\n C --> C2[斜杠命令处理器]\n \n D --> D1[工具执行展示]\n D --> D2[日志视图]\n D --> D3[流式内容]\n D --> D4[变更追踪]\n \n E --> E1[Hub 市场]\n E --> E2[上下文历史]\n E --> E3[任务管理]\n```\n\n### 执行流程状态机\n\nAgent 执行过程中的状态转换通过 TUI 组件实时反映：\n\n```mermaid\nstateDiagram-v2\n [*] --> Running : 开始执行\n Running --> Completed : 成功完成\n Running --> Failed : 执行失败\n Completed --> [*] : 用户确认\n Failed --> [*] : 用户查看后关闭\n \n Running --> Streaming : 流式输出\n Streaming --> Running : 数据更新\n```\n\n## 核心组件\n\n### 执行展示组件\n\n#### 工具调用展示 (`execution-tool.tsx`)\n\n该组件负责在执行过程中显示单个工具调用的状态信息。根据工具调用的状态，组件渲染不同的视觉标识：\n\n| 状态值 | 视觉表现 | 颜色配置 |\n|--------|----------|----------|\n| `success` | ✓ 前缀绿色对勾 | `colors.primary` |\n| `running` | 闪烁圆圈动画 | `colors.dimText` |\n| `failed` | ✗ 前缀红色叉号 | `colors.errorText` |\n\n组件接收以下属性：\n\n```typescript\ninterface ExecutionToolProps {\n toolCall: ToolCall; // 工具调用数据\n toolName?: string; // 工具显示名称\n toolArguments?: string; // 工具参数字符串\n}\n```\n\n当工具处于 `running` 状态时，组件渲染 `` 动画元素，提示用户当前正在处理中。\n\n#### 展开日志视图 (`expanded-log-view.tsx`)\n\n该组件是执行日志的核心展示容器，集成了多种内容类型的渲染能力：\n\n| 内容区域 | 触发条件 | 组件 |\n|----------|----------|------|\n| 输入信息 | 始终显示 | `` |\n| 进度追踪 | `toolCalls` 或 `reasoningContents` 存在 | `` |\n| 流式内容 | `status === 'running'` 且有 `streamingContent` | `` |\n| 执行结果 | `status === 'failed'` 或 `status === 'completed'` | `` |\n| 变更列表 | `status === 'completed'` | `` |\n\n组件的数据结构定义：\n\n```typescript\ninterface ExpandedLog {\n input: string;\n files?: string[];\n toolCalls?: ToolCall[];\n reasoningContents?: ReasoningContent[];\n streamingContent?: string;\n isStreaming?: boolean;\n status: 'running' | 'completed' | 'failed';\n content?: string;\n changes: {\n created: string[];\n updated: string[];\n };\n}\n```\n\n流式文本内容通过 `StreamingText` 组件渲染，支持实时光标显示和动态内容更新。当 `isStreaming` 为 true 时，光标会持续闪烁，提示用户数据仍在传输中。\n\n#### 变更追踪展示\n\n执行完成后的变更内容通过 `ExecutionChanges` 组件展示，该组件接受以下参数：\n\n```typescript\ninterface ExecutionChangesProps {\n created: string[]; // 创建的文件路径列表\n updated: string[]; // 更新的文件路径列表\n isExpanded: boolean; // 是否展开显示\n maxChanges: {\n created: number; // 创建文件的最大显示数量\n updated: number; // 更新文件的最大显示数量\n };\n}\n```\n\n文件路径以 `@` 前缀形式展示，如 `@src/main.ts`，便于用户识别文件位置。\n\n### Hub 功能面板\n\n#### 详情展示 (`hub-detail-step.tsx`)\n\nHub 面板提供技能和 Agent 的详细信息浏览功能。组件展示的数据字段包括：\n\n| 字段 | 显示标签 | 样式说明 |\n|------|----------|----------|\n| `version` | 版本号 | 卡片式布局 |\n| `registry` | 仓库名 | 卡片式布局，默认值 'default' |\n| `tags` | 标签列表 | 以 `#` 前缀显示 |\n| `dependencies` | 依赖项 | 警告色显示 |\n| `category` | 分类 | 标准文本 |\n| `author.name` | 作者 | 左对齐标签配右对齐值 |\n| `license` | 许可证 | 左对齐标签配右对齐值 |\n| `file_tree` | 文件列表 | 缩进显示 |\n\n当条目类型为 `agent-skill` 时，组件额外渲染目标 Agent 选择器：\n\n```typescript\n// Agent 选择器配置\nconst AGENT_VALUES = ['Codex', /* other agents */];\n\n setAgentSelections({...current, [entry.id]: event.target.value})}\n>\n {AGENT_VALUES.map((agent) => (\n \n ))}\n\n```\n\n#### 快捷键绑定\n\nHub 详情面板支持以下键盘交互：\n\n| 按键 | 功能 |\n|------|------|\n| `Enter` | 安装选中的技能/Agent |\n| `o` | 在浏览器中打开详情 |\n| `Esc` | 返回上一级 |\n\n## 状态管理\n\n### 执行状态流转\n\nTUI 界面的执行状态管理遵循以下流程：\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant CLI as 命令行\n participant Agent as Agent服务\n participant TUI as TUI组件\n \n User->>CLI: 输入命令\n CLI->>Agent: 发起执行请求\n Agent-->>TUI: 流式返回状态\n TUI->>TUI: 更新running状态\n TUI->>TUI: 渲染流式内容\n \n Agent-->>CLI: 执行完成\n CLI-->>TUI: 发送completed/failed\n TUI->>TUI: 更新最终状态\n TUI->>TUI: 展示变更列表\n```\n\n### Hub 选择状态\n\nAgent 选择状态通过 `useState` 管理：\n\n```typescript\nconst [agentSelections, setAgentSelections] = useState>({});\n\n// 更新单个选择\nsetAgentSelections((current) => ({\n ...current,\n [entry.id]: event.target.value\n}));\n```\n\n## 视觉设计\n\n### 配色系统\n\nTUI 组件采用终端友好的配色方案：\n\n| 用途 | 颜色变量 | 说明 |\n|------|----------|------|\n| 主色调 | `colors.primary` | 成功状态、强调元素 |\n| 文字色 | `colors.text` | 主要文本内容 |\n| 暗淡文字 | `colors.dimText` | 次要信息、标签 |\n| 错误色 | `colors.errorText` | 失败状态、警告 |\n| 警告色 | `colors.warning` | 依赖项展示 |\n\n### 布局模式\n\n组件采用灵活的布局系统，主要使用以下布局属性：\n\n- `flexDirection: 'row' | 'column'` - 主轴方向\n- `gap: number` - 子元素间距\n- `marginBottom: number` - 底部外边距\n- `paddingX: number` - 水平内边距\n\n## 技术实现要点\n\n### 渲染管线\n\nTUI 采用声明式渲染模式，组件根据状态变化自动重新渲染。关键优化点包括：\n\n1. **条件渲染**：仅在数据存在时渲染对应内容区域\n2. **状态隔离**：每个日志条目维护独立的状态副本\n3. **流式处理**：支持 `isStreaming` 标志控制实时内容更新\n\n### 组件复用策略\n\n通过抽象公共接口实现组件复用：\n\n- `ExecutionTool` 和 `ExecutionContent` 共享错误状态处理逻辑\n- `StreamingText` 组件同时服务于执行日志和普通流式输出\n- Hub 面板的布局模式可扩展至其他详情展示场景\n\n## 相关命令\n\nTUI 界面支持通过 `brv` 命令行工具触发：\n\n```bash\nbrv webui # 启动 WebUI 界面\nbrv login # 用户认证\nbrv init # 初始化项目\nbrv status # 查看连接状态\n```\n\n## 源码引用\n\n| 组件 | 文件路径 | 功能描述 |\n|------|----------|----------|\n| 工具执行展示 | `src/tui/components/execution/execution-tool.tsx:1-24` | 渲染工具调用状态 |\n| 展开日志视图 | `src/tui/components/execution/expanded-log-view.tsx:1-50` | 聚合展示执行详情 |\n| Hub详情面板 | `src/tui/features/hub/components/hub-detail-step.tsx:1-80` | 技能市场详情浏览 |\n\n## 扩展说明\n\n### 流式内容处理\n\n`expanded-log-view.tsx` 中的流式内容展示采用以下策略：\n\n1. 监测 `streamingContent` 和 `isStreaming` 属性\n2. 处于 `running` 状态时持续渲染 ``\n3. `showCursor` 属性在 `isStreaming` 为 true 时激活闪烁光标\n4. `maxLines={0}` 配置允许内容无限延展\n\n### 错误处理可视化\n\n执行失败时的错误信息通过以下流程呈现：\n\n1. 检测 `status === 'failed'`\n2. 使用 `isError` 属性高亮错误文本\n3. 错误内容从 `content` 字段提取\n4. 配合 `colors.errorText` 配色方案突出显示\n\n---\n\n\n\n## WebUI管理面板\n\n### 相关页面\n\n相关主题：[TUI交互界面](#tui-interface)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/webui/index.html](https://github.com/campfirein/byterover-cli/blob/main/src/webui/index.html)\n- [src/webui/features/hub/components/hub-panel.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/webui/features/hub/components/hub-panel.tsx)\n- [src/webui/features/hub/components/hub-detail-step.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/webui/features/hub/components/hub-detail-step.tsx)\n- [src/webui/features/transport/components/offline-screen.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/webui/features/transport/components/offline-screen.tsx)\n- [src/webui/features/project/components/project-dropdown.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/webui/features/project/components/project-dropdown.tsx)\n- [src/webui/features/context/components/context-history-panel.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/webui/features/context/components/context-history-panel.tsx)\n- [src/webui/features/tasks/components/task-composer.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/webui/features/tasks/components/task-composer.tsx)\n- [src/webui/features/tasks/components/task-detail-view.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/webui/features/tasks/components/task-detail-view.tsx)\n- [src/webui/features/vc/components/diff-view.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/webui/features/vc/components/diff-view.tsx)\n- [src/server/infra/http/review-ui.ts](https://github.com/campfirein/byterover-cli/blob/main/src/server/infra/http/review-ui.ts)\n- [src/server/infra/http/callback-server.ts](https://github.com/campfirein/byterover-cli/blob/main/src/server/infra/http/callback-server.ts)\n- [src/server/infra/provider-oauth/callback-server.ts](https://github.com/campfirein/byterover-cli/blob/main/src/server/infra/provider-oauth/callback-server.ts)\n \n\n# WebUI管理面板\n\n## 概述\n\nWebUI管理面板是ByteRover CLI的图形化Web界面模块，提供项目上下文管理、技能市场、任务编辑、版本控制等核心功能的可视化操作界面。该模块基于React构建，采用TypeScript开发，通过WebSocket与本地后端服务通信，实现对AI编程助手的持久化记忆管理。\n\nWebUI的核心价值在于将CLI的命令行操作转换为直观的图形界面，使开发者能够更便捷地管理项目知识库、查看上下文历史、浏览技能市场、以及进行版本控制操作。资料来源：[src/webui/index.html:1-13]()\n\n## 系统架构\n\n### 整体架构\n\nWebUI采用前后端分离的架构设计，前端为单页应用(SPA)，后端为Express服务。系统通过WebSocket保持实时通信，同时提供HTTP API用于认证回调和数据同步。\n\n```mermaid\ngraph TD\n A[用户浏览器] <--> B[WebUI前端
React SPA]\n B <--> C[本地Server
Express + WebSocket]\n C --> D[项目文件系统]\n C --> E[ByteRover Cloud
远程同步]\n C --> F[AI Provider
OAuth认证]\n \n G[CLI终端] <--> C\n```\n\n### 目录结构\n\nWebUI模块位于`src/webui/`目录下，采用特性模块组织代码结构：\n\n```\nsrc/webui/\n├── index.html # HTML入口文件\n├── index.tsx # React根组件入口\n├── App.tsx # 主应用组件\n├── router.tsx # 路由配置\n├── layouts/\n│ └── main-layout.tsx # 主布局组件\n├── providers/\n│ └── app-providers.tsx # 全局状态提供者\n├── features/ # 功能模块\n│ ├── hub/ # 技能中心\n│ ├── tasks/ # 任务编辑\n│ ├── context/ # 上下文管理\n│ ├── project/ # 项目选择\n│ ├── transport/ # 连接状态\n│ └── vc/ # 版本控制\n└── components/ # 通用组件\n```\n\n资料来源：[src/webui/index.html:1-13]()\n\n## 核心功能模块\n\n### Hub技能中心\n\nHub模块是WebUI的核心功能区域，提供技能和代理的管理界面。用户可以浏览、安装和管理来自不同注册表的AI技能。\n\n#### Hub面板组件\n\n`hub-panel.tsx`负责渲染技能列表和安装界面，支持以下功能：\n\n| 功能 | 描述 | 源码位置 |\n|------|------|----------|\n| 技能列表 | 显示所有可用的技能和代理类型 | hub-panel.tsx |\n| 安装按钮 | 触发技能安装流程 | hub-panel.tsx |\n| 代理选择 | 为技能选择目标AI代理 | hub-panel.tsx |\n| 版本显示 | 展示技能当前版本号 | hub-panel.tsx |\n| 注册表信息 | 显示技能来源的注册表 | hub-panel.tsx |\n\n组件支持`agent-skill`类型条目的代理选择功能，用户可以通过下拉菜单选择目标代理（如Codex等）。资料来源：[src/webui/features/hub/components/hub-panel.tsx:1-50]()\n\n#### Hub详情步骤组件\n\n`hub-detail-step.tsx`提供技能的详细元数据展示界面，包括：\n\n| 元数据字段 | 说明 |\n|-----------|------|\n| Tags | 技能标签，用于分类检索 |\n| Requires | 技能依赖项 |\n| Category | 技能分类 |\n| Registry | 技能来源注册表 |\n| Author | 作者信息 |\n| Version | 版本号 |\n\n资料来源：[src/webui/features/hub/components/hub-detail-step.tsx:1-60]()\n\n### 项目管理\n\n项目下拉组件`project-dropdown.tsx`实现项目选择和管理功能。\n\n```mermaid\ngraph LR\n A[点击下拉触发] --> B{是否有打开的项目}\n B -->|是| C[显示打开项目列表]\n B -->|否| D[显示最近项目列表]\n C --> E[选择项目]\n D --> E\n E --> F[加载项目上下文]\n```\n\n项目选择支持三种来源：\n\n1. **当前打开的项目** - 已激活的项目列表\n2. **最近项目** - 历史访问过的项目，最多显示`RECENT_LIMIT`个\n3. **所有项目** - 点击\"See all\"展开完整列表\n\n新项目需要通过CLI命令`brv webui`在项目目录下注册后才能在界面中显示。资料来源：[src/webui/features/project/components/project-dropdown.tsx:1-80]()\n\n### 任务编辑\n\n任务编辑器`task-composer.tsx`是WebUI的核心输入组件，支持多种任务类型的创建和编辑。\n\n#### 支持的任务类型\n\n| 类型 | 描述 | 特殊处理 |\n|------|------|----------|\n| curate | 知识整理任务 | 显示CurateAttachmentHint提示 |\n| default | 默认任务类型 | 标准编辑器 |\n| 其他 | 自定义任务类型 | 根据HelpRow配置显示帮助信息 |\n\n#### 编辑器界面元素\n\n- **快捷键提示**：显示键盘快捷键（如`Ctrl+Enter`提交、`Tab`使用示例）\n- **字符计数**：实时显示输入内容长度\n- **HelpRow帮助**：根据任务类型显示对应的帮助信息\n- **ComposerFooter**：底部工具栏，包含提交、取消、详情展开等操作\n\n```tsx\n// 提交验证\nconst canSubmit = content.length > 0 && hasActiveProvider\n```\n\n资料来源：[src/webui/features/tasks/components/task-composer.tsx:1-100]()\n\n#### 任务详情视图\n\n`task-detail-view.tsx`提供任务的详细查看界面，用于展示已完成任务的完整信息、变更内容和执行结果。\n\n### 上下文历史\n\n`context-history-panel.tsx`组件负责展示项目的上下文提交历史记录。\n\n| 功能 | 说明 |\n|------|------|\n| 当前提交 | 高亮显示当前活跃的上下文版本 |\n| 历史记录 | 按时间倒序展示旧的提交记录 |\n| 时间格式化 | 将时间戳转换为可读格式（如\"Jan 15, 14:30\"） |\n\n```tsx\nfunction formatCommitDate(timestamp: string): string {\n try {\n return `Updated at ${format(new Date(timestamp), 'MMM d, HH:mm')}`\n } catch {\n return 'Updated'\n }\n}\n```\n\n资料来源：[src/webui/features/context/components/context-history-panel.tsx:1-80]()\n\n### 版本控制差异视图\n\n`diff-view.tsx`组件提供文件变更的可视化对比功能，支持：\n\n- 创建文件高亮（绿色背景）\n- 更新文件差异展示\n- 删除文件标记（红色）\n\n### 连接状态管理\n\n`offline-screen.tsx`组件处理网络连接状态的UI展示。\n\n| 状态 | 显示内容 | 指示器颜色 |\n|------|----------|-----------|\n| 正常连接 | 无特殊显示 | 绿色 |\n| 离线 | \"Offline\"徽章 | 黄色警告 |\n| 配置错误 | \"Unreachable\"徽章 | 红色错误 |\n| 重连中 | 重连尝试次数显示 | 脉冲动画 |\n\n```tsx\n// 重连状态显示\n{isConfigError ? (\n Refresh once the host is back.\n) : (\n <>\n Reconnecting\n attempt {reconnectCount}\n \n)}\n```\n\n资料来源：[src/webui/features/transport/components/offline-screen.tsx:1-80]()\n\n## 认证与回调系统\n\n### OAuth回调处理\n\nByteRover支持多种AI Provider的OAuth认证，后端服务提供专用的回调处理。\n\n#### HTTP回调服务器\n\n`src/server/infra/http/callback-server.ts`提供认证回调的HTML响应：\n\n| 函数 | 功能 |\n|------|------|\n| successHtml | 渲染认证成功页面，2秒后自动关闭 |\n| errorHtml | 渲染认证失败页面，显示错误详情 |\n\n成功页面包含：\n- 品牌Logo展示\n- \"Authentication Successful\"标题\n- 自动关闭提示\n\n错误页面包含：\n- 错误图标\n- 错误描述文本\n- 可选的详细错误信息（使用`escapeHtml`转义）\n\n#### Provider OAuth回调\n\n`src/server/infra/provider-oauth/callback-server.ts`提供Provider特定的OAuth回调页面，包含：\n- 品牌Logo和标题\n- 成功/失败状态展示\n- CSS内联样式确保无依赖运行\n\n资料来源：[src/server/infra/http/callback-server.ts:1-100]()\n资料来源：[src/server/infra/provider-oauth/callback-server.ts:1-80]()\n\n## 审查UI模块\n\n`review-ui.ts`提供本地HITL（Human-in-the-Loop）审查界面的HTML生成功能。\n\n### 特性\n\n- **自包含设计**：所有CSS和JavaScript内联，无外部依赖\n- **语义化展示**：显示操作的前置版本和当前版本摘要\n- **深色主题**：采用GitHub风格的深色配色方案\n\n### 样式变量\n\n```css\n:root {\n --bg: #0d1117;\n --bg-secondary: #161b22;\n --bg-tertiary: #21262d;\n --border: #30363d;\n --text: #e6edf3;\n --text-muted: #8b949e;\n --green: #238636;\n --red: #da3633;\n --blue: #58a6ff;\n --yellow: #d29922;\n}\n```\n\n资料来源：[src/server/infra/http/review-ui.ts:1-50]()\n\n## 执行日志展示\n\nWebUI的执行日志组件负责展示AI代理的执行过程，包括：\n\n| 组件 | 功能 |\n|------|------|\n| expanded-log-view.tsx | 展开的日志视图，显示输入、工具调用、流式内容、变更 |\n| execution-tool.tsx | 单个工具调用展示，包含状态图标和参数 |\n| ExecutionProgress | 推理内容和工具调用进度条 |\n| ExecutionContent | 任务完成后的输出内容展示 |\n| ExecutionChanges | 创建和更新的文件列表展示 |\n\n### 日志状态\n\n| 状态 | 样式 | 显示内容 |\n|------|------|----------|\n| running | 流式文本+进度条 | 实时输出 |\n| completed | 绿色勾选+变更列表 | 最终结果 |\n| failed | 红色叉号+错误信息 | 错误详情 |\n\n资料来源：[src/tui/components/execution/expanded-log-view.tsx:1-80]()\n资料来源：[src/tui/components/execution/execution-tool.tsx:1-50]()\n\n## 数据流架构\n\n```mermaid\ngraph TD\n subgraph 前端层\n A[React Components] --> B[Context Providers]\n B --> C[Feature Modules]\n end\n \n subgraph 通信层\n C --> D[WebSocket
实时事件]\n C --> E[HTTP API
REST请求]\n end\n \n subgraph 后端层\n D --> F[Express Server]\n E --> F\n F --> G[项目文件系统]\n F --> H[Cloud Sync]\n F --> I[AI Provider]\n end\n \n subgraph 存储层\n G --> J[本地知识库]\n H --> K[云端上下文]\n end\n```\n\n## 状态管理\n\nWebUI使用React Context进行全局状态管理，主要Provider包括：\n\n| Provider | 职责 |\n|----------|------|\n| AppProviders | 根级别提供者，聚合所有子Provider |\n| 任务状态 | 管理当前编辑的任务内容 |\n| 项目状态 | 管理选中和最近的项目列表 |\n| 连接状态 | 管理WebSocket连接状态和重连逻辑 |\n| Hub状态 | 管理技能列表和安装状态 |\n\n## 总结\n\nWebUI管理面板是ByteRover CLI的图形化操作界面，通过模块化的React组件架构提供了完整的项目上下文管理功能。主要模块包括：\n\n- **Hub技能中心**：浏览和安装AI技能\n- **项目管理**：项目选择和切换\n- **任务编辑**：创建和编辑各类任务\n- **上下文历史**：查看和管理知识版本\n- **版本控制**：文件变更对比\n- **连接状态**：网络状态监控\n\n整个系统采用TypeScript开发，确保类型安全；通过WebSocket实现实时通信；后端Express服务提供API和OAuth认证支持。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：campfirein/byterover-cli\n\n摘要：发现 19 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Curator can copy prompt example facts into the context tree when using Gemini Flash-Lite。\n\n## 1. 安装坑 · 来源证据：Curator can copy prompt example facts into the context tree when using Gemini Flash-Lite\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Curator can copy prompt example facts into the context tree when using Gemini Flash-Lite\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f0927b3fa77c4e7ab29ba04f3c4b7ed7 | https://github.com/campfirein/byterover-cli/issues/647 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Visual corruption while browsing a long model list\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Visual corruption while browsing a long model list\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3112b1ba6fc54e0a8d973b277ab8d106 | https://github.com/campfirein/byterover-cli/issues/620 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：ByteRover CLI 3.10.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.10.1\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c21085e93cad46a5b79d8ff2353f156c | https://github.com/campfirein/byterover-cli/releases/tag/v3.10.1 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：ByteRover CLI 3.10.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.10.3\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5ada5377aa504edeac454b6a66310a47 | https://github.com/campfirein/byterover-cli/releases/tag/v3.10.3 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：ByteRover CLI 3.8.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.8.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_370b6c20f13544c28427013da0519f1f | https://github.com/campfirein/byterover-cli/releases/tag/v3.8.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：ByteRover CLI 3.8.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.8.2\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_48b470d455aa406480648e100bc08c94 | https://github.com/campfirein/byterover-cli/releases/tag/v3.8.2 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：ByteRover CLI 3.8.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.8.3\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_70d8761f65864cf2897a70138eabb5b7 | https://github.com/campfirein/byterover-cli/releases/tag/v3.8.3 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 安装坑 · 来源证据：ByteRover CLI 3.9.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.9.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_955f12701a864106895fc95c8ef7fd05 | https://github.com/campfirein/byterover-cli/releases/tag/v3.9.0 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：`brv mcp` client stuck in infinite exception loop consuming 75–90% CPU for hours\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：`brv mcp` client stuck in infinite exception loop consuming 75–90% CPU for hours\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_50500a3417394344864f50cf765157ea | https://github.com/campfirein/byterover-cli/issues/660 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 10. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | README/documentation is current enough for a first validation pass.\n\n## 11. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | last_activity_observed missing\n\n## 12. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 来源证据：ByteRover CLI 3.10.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ByteRover CLI 3.10.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_78241481b8c647e4a05827b06eafdc99 | https://github.com/campfirein/byterover-cli/releases/tag/v3.10.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：ByteRover CLI 3.10.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ByteRover CLI 3.10.2\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2af62a087710490b8250f23ac6258644 | https://github.com/campfirein/byterover-cli/releases/tag/v3.10.2 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：ByteRover CLI 3.11.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ByteRover CLI 3.11.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ea3c8b32846b4edfaef28f8aa1cca40f | https://github.com/campfirein/byterover-cli/releases/tag/v3.11.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：ByteRover CLI 3.12.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ByteRover CLI 3.12.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_917109bf273c4c09a26a50f00fd1b6e4 | https://github.com/campfirein/byterover-cli/releases/tag/v3.12.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 18. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | issue_or_pr_quality=unknown\n\n## 19. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | release_recency=unknown\n\n\n",
"markdown_key": "byterover-cli",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1005233473",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/campfirein/byterover-cli"
},
{
"evidence_id": "art_e485eef68b8049eda3f9dde4f7877bb1",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/campfirein/byterover-cli#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "byterover-cli 说明书",
"toc": [
"https://github.com/campfirein/byterover-cli 项目说明书",
"目录",
"项目概述",
"项目简介",
"核心架构",
"核心功能模块",
"数据流与状态管理",
"命令行接口",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "f87a0ded1f693ad6d09f794ac2dcc93a6eaa6706",
"repo_inspection_error": null,
"repo_inspection_files": [
"package.json",
"README.md",
"src/index.ts",
"src/webui/vite-env.d.ts",
"src/webui/vite.config.ts",
"src/webui/tsconfig.json",
"src/server/constants.ts",
"src/oclif/constants.ts",
"src/webui/stores/transport-store.ts",
"src/webui/utils/initials.ts",
"src/webui/lib/error-messages.ts",
"src/webui/lib/transport.ts",
"src/webui/lib/syntax-highlighter.ts",
"src/webui/lib/react-query.ts",
"src/webui/lib/noop.ts",
"src/webui/lib/api-client.ts",
"src/webui/lib/toast-vc-error.ts",
"src/webui/lib/transport-error.ts",
"src/webui/features/context/types.ts",
"src/webui/features/vc/types.ts",
"src/webui/features/session/api/create-session.ts",
"src/webui/features/context/api/get-context-history.ts",
"src/webui/features/context/api/get-context-file-metadata.ts",
"src/webui/features/context/api/get-context-nodes.ts",
"src/webui/features/context/api/update-context-file.ts",
"src/webui/features/context/api/get-context-file.ts",
"src/webui/features/context/hooks/use-context-layout.ts",
"src/webui/features/context/utils/tree-utils.ts",
"src/webui/features/provider/api/list-billing-usage.ts",
"src/webui/features/provider/api/await-oauth-callback.ts",
"src/webui/features/provider/api/get-free-user-limit.ts",
"src/webui/features/provider/api/set-pinned-team.ts",
"src/webui/features/provider/api/set-active-provider.ts",
"src/webui/features/provider/api/start-oauth.ts",
"src/webui/features/provider/api/submit-oauth-code.ts",
"src/webui/features/provider/api/disconnect-provider.ts",
"src/webui/features/provider/api/get-providers.ts",
"src/webui/features/provider/api/get-pinned-team.ts",
"src/webui/features/provider/api/connect-provider.ts",
"src/webui/features/provider/api/get-active-provider-config.ts"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# byterover-cli - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 byterover-cli 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **AI 研究者或研究型 Agent 构建者**：README 明确围绕研究、实验或论文工作流展开。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`src/server/templates/skill/SKILL.md` Claim：`clm_0005` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`src/server/templates/skill/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`AGENTS.md`, `README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `curl -fsSL https://byterover.dev/install.sh | sh` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `npm install -g byterover-cli` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `npx mocha --forbid-only \"test/path/to/file.test.ts\" # Single test` 证据：`AGENTS.md` Claim：`clm_0008` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：AI 研究者或研究型 Agent 构建者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`src/server/templates/skill/SKILL.md` Claim：`clm_0005` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`src/server/templates/skill/SKILL.md` Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`AGENTS.md`, `README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0006` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`AGENTS.md`, `CLAUDE.md`, `src/server/templates/skill/SKILL.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`AGENTS.md`, `README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`AGENTS.md`, `CLAUDE.md`, `src/server/templates/skill/SKILL.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`AGENTS.md`, `README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0009` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`AGENTS.md`, `README.md` Claim：`clm_0010` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`src/server/templates/skill/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`AGENTS.md`, `README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：1880\n- 重要文件覆盖：40/1880\n- 证据索引条目：48\n- 角色 / Skill 条目：1\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 byterover-cli 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 byterover-cli 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 byterover-cli 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 1 个角色 / Skill / 项目文档条目。\n\n- **byterover**（skill）：You MUST use this for gathering contexts before any work. This is a Knowledge management for AI agents. Use brv to store and retrieve project patterns, decisions, and architectural rules in .brv/context-tree. Uses a configured LLM provider default: ByteRover, no API key needed for query and curate operations. 激活提示：当用户任务与“byterover”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`src/server/templates/skill/SKILL.md`\n\n## 证据索引\n\n- 共索引 48 条证据。\n\n- **Repository Guidelines**（documentation）：ByteRover CLI brv - Interactive REPL with React/Ink TUI 证据：`AGENTS.md`\n- **CLAUDE.md**（documentation）：ByteRover CLI brv - Interactive REPL with React/Ink TUI 证据：`CLAUDE.md`\n- **ByteRover CLI**（documentation）：Interactive REPL CLI for AI-powered context memory 证据：`README.md`\n- **ByteRover: Agent-Native Memory Through LLM-Curated Hierarchical Context**（documentation）：ByteRover: Agent-Native Memory Through LLM-Curated Hierarchical Context 证据：`paper/README.md`\n- **ByteRover CLI Template System**（documentation）：This directory contains template files used to generate agent instructions via the brv gen-rules command. 证据：`src/server/templates/README.md`\n- **Package**（package_manifest）：{ \"name\": \"byterover-cli\", \"description\": \"ByteRover's CLI\", \"keywords\": \"cli\", \"ai\", \"llm\", \"mcp\", \"developer-tools\", \"context-memory\", \"autonomous-agents\", \"coding-assistant\", \"knowledge-management\" , \"version\": \"3.12.0\", \"author\": \"ByteRover\", \"bin\": { \"brv\": \"./bin/run.js\" }, \"bugs\": \"https://github.com/campfirein/byterover-cli/issues\", \"dependencies\": { \"@ai-sdk/anthropic\": \"^2.0.60\", \"@ai-sdk/cerebras\": \"^1.0.11\", \"@ai-sdk/cohere\": \"^2.0.0\", \"@ai-sdk/deepinfra\": \"^1.0.35\", \"@ai-sdk/google\": \"^2.0.52\", \"@ai-sdk/groq\": \"^2.0.34\", \"@ai-sdk/mistral\": \"^2.0.27\", \"@ai-sdk/openai\": \"^2.0.89\", \"@ai-sdk/openai-compatible\": \"^1.0.32\", \"@ai-sdk/perplexity\": \"^2.0.0\", \"@ai-sdk/togetherai\": \"^1.0.… 证据：`package.json`\n- **Contributing to ByteRover CLI**（documentation）：Thank you for your interest in contributing to ByteRover CLI! Whether you're fixing a bug, adding a feature, improving documentation, or reporting an issue — every contribution is valued. 证据：`CONTRIBUTING.md`\n- **ByteRover Knowledge Management**（skill_instruction）：Use the brv CLI to manage your project's long-term memory. Install: npm install -g byterover-cli Knowledge is stored in .brv/context-tree/ as human-readable Markdown files. 证据：`src/server/templates/skill/SKILL.md`\n- **License**（source_file）：Acceptance By using the software, you agree to all of the terms and conditions below. 证据：`LICENSE`\n- **Summary**（documentation）：- Problem: - Why it matters: - What changed: - What did NOT change scope boundary : 证据：`.github/PULL_REQUEST_TEMPLATE.md`\n- **CLAUDE.md**（documentation）：ByteRover CLI brv - Interactive REPL with React/Ink TUI 证据：`.github/copilot-instructions.md`\n- **Changelog**（documentation）：All notable user-facing changes to ByteRover CLI will be documented in this file. 证据：`CHANGELOG.md`\n- **Base**（documentation）：{{workflow}} --- {{command reference}} 证据：`src/server/templates/base.md`\n- **Mcp Base**（documentation）：{{mcp workflow}} 证据：`src/server/templates/mcp-base.md`\n- **ByteRover Memory System - MANDATORY**（documentation）：⚠️ STOP: Before responding, check if this is a code task. Code task? → brv query FIRST. Wrote code? → brv curate BEFORE done. 证据：`src/server/templates/sections/brv-instructions.md`\n- **ByteRover CLI Command Reference**（documentation）：- brv curate - Curate context to the context tree. Blocking default — wait for it to finish before continuing returns logId on completion . - brv curate --detach - Queue curate and return logId immediately. Use ONLY when BOTH a no remaining step in this turn reads this data or builds on it, AND b user explicitly said not to wait \"don't wait\", \"fire and forget\" . See Workflow. - brv curate view - List curate history last 10 entries by default - brv curate view - Full detail for a specific entry: all files and operations performed logId returned by brv curate - brv curate view --detail - List entries with their file operations visible no logId needed - brv query - Query and retrieve informati… 证据：`src/server/templates/sections/command-reference.md`\n- **Workflow Instruction**（documentation）：You are a coding agent integrated with ByteRover via MCP Model Context Protocol . 证据：`src/server/templates/sections/mcp-workflow.md`\n- **Workflow Instruction**（documentation）：You are a coding agent focused on one codebase. Use the brv CLI to manage working context. 证据：`src/server/templates/sections/workflow.md`\n- **Settings**（structured_config）：{ \"permissions\": { \"allow\": \"WebSearch\", \"Bash find: \", \"Bash npm run test: \", \"Bash grep: \", \"Bash npm run build: \", \"Bash npx mocha: \", \"Bash git log: \", \"Bash git show: \", \"mcp linear list issues\", \"mcp linear get issue\", \"mcp linear list issue labels\", \"mcp linear list issue statuses\", \"mcp linear list projects\", \"mcp linear get project\", \"mcp linear list comments\", \"mcp linear list milestones\", \"mcp linear save issue\", \"mcp linear get milestone\", \"mcp linear get document\", \"mcp linear save project\", \"mcp linear save milestone\", \"mcp linear update document\", \"mcp linear save comment\", \"mcp linear list teams\", \"Bash gh api: \" } } 证据：`.claude/settings.json`\n- **.Mocharc**（structured_config）：{ \"require\": \"ts-node/register\" , \"watch-extensions\": \"ts\" , \"recursive\": true, \"reporter\": \"spec\", \"timeout\": 60000, \"exit\": true, \"node-option\": \"loader=ts-node/esm\", \"experimental-specifier-resolution=node\" } 证据：`.mocharc.json`\n- **.Prettierrc**（structured_config）：\"@oclif/prettier-config\" 证据：`.prettierrc.json`\n- **Tsconfig**（structured_config）：{ \"extends\": \"../tsconfig\", \"compilerOptions\": { \"noEmit\": true, }, \"references\": {\"path\": \"..\"} } 证据：`test/tsconfig.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"declaration\": true, \"module\": \"Node16\", \"outDir\": \"dist\", \"rootDir\": \"src\", \"strict\": true, \"target\": \"es2022\", \"moduleResolution\": \"node16\", \"skipLibCheck\": true, \"jsx\": \"react-jsx\", }, \"include\": \"./src/ / \" , \"exclude\": \"./src/webui/ / \" , \"ts-node\": { \"esm\": true, \"compilerOptions\": { \"module\": \"ESNext\", \"moduleResolution\": \"bundler\" } } } 证据：`tsconfig.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"es2022\", \"module\": \"ESNext\", \"moduleResolution\": \"bundler\", \"jsx\": \"react-jsx\", \"baseUrl\": \".\", \"paths\": { \"@campfirein/byterover-packages/ \": \"../../packages/byterover-packages/ui/src/ \", \"../../node modules/@campfirein/byterover-packages/ui/src/ \" , \"@workspace/ui/ \": \"../../packages/byterover-packages/ui/src/ \", \"../../node modules/@campfirein/byterover-packages/ui/src/ \" }, \"strict\": true, \"skipLibCheck\": true, \"noEmit\": true, \"lib\": \"DOM\", \"DOM.Iterable\", \"ES2022\" }, \"include\": \"./ / \" } 证据：`src/webui/tsconfig.json`\n- **ByteRover CLI - Environment Configuration**（source_file）：ByteRover CLI - Environment Configuration Copy this file to .env.development for dev or .env.production for production and fill in the values for your environment. 证据：`.env.example`\n- **Default: all changes require review**（source_file）：Default: all changes require review @leehpham @bao-byterover 证据：`.github/CODEOWNERS`\n- **ByteRover workspace local development only**（source_file）：-debug.log -error.log /.DS Store /.idea /dist /tmp /node modules oclif.manifest.json 证据：`.gitignore`\n- **.gitmodules**（source_file）：submodule \"packages/byterover-packages\" path = packages/byterover-packages url = git@github.com:campfirein/byterover-packages.git branch = main 证据：`.gitmodules`\n- **Pre Commit**（source_file）：npx lint-staged 证据：`.husky/pre-commit`\n- **Pre Push**（source_file）：npm run typecheck 证据：`.husky/pre-push`\n- **Dev**（source_file）：set BRV ENV=development node --loader ts-node/esm --no-warnings=ExperimentalWarning \"%~dp0\\dev\" % 证据：`bin/dev.cmd`\n- **!/usr/bin/env -S node --import tsx --no-warnings**（source_file）：!/usr/bin/env -S node --import tsx --no-warnings 证据：`bin/dev.js`\n- **!/usr/bin/env node**（source_file）：/ Gracefully stops the running brv daemon. Uses the daemon.json PID tracking from brv-transport-client instead of brute-force pkill. Sends SIGTERM first, then falls back to SIGKILL after the stop budget 3s . Usage: node bin/kill-daemon.js graceful stop npm run dev:kill via npm script npm run dev kill + build + run full cycle / 证据：`bin/kill-daemon.js`\n- **Run**（source_file）：set BRV ENV=production node \"%~dp0\\run\" % 证据：`bin/run.cmd`\n- **!/usr/bin/env node**（source_file）：import {execute} from '@oclif/core' import {config as loadEnv} from 'dotenv' import {resolve} from 'node:path' 证据：`bin/run.js`\n- **Eslint.Config**（source_file）：import {includeIgnoreFile} from '@eslint/compat' import oclif from 'eslint-config-oclif' import prettier from 'eslint-config-prettier' import path from 'node:path' import {fileURLToPath} from 'node:url' 证据：`eslint.config.mjs`\n- **paper/.gitignore**（source_file）：.pdf .aux .bbl .blg .log .out .toc .lof .lot .fls .fdb latexmk .synctex.gz 证据：`paper/.gitignore`\n- **ByteRover Paper Build**（source_file）：ByteRover Paper Build Usage: make build PDF make clean remove build artifacts make watch rebuild on changes — requires fswatch 证据：`paper/Makefile`\n- **!/bin/bash**（source_file）：!/bin/bash export PATH=\"/Library/TeX/texbin:/usr/bin:$PATH\" cd \"$ dirname \"$0\" \" 证据：`paper/build.sh`\n- **Relations**（source_file）：% ============================================================ % ByteRover: Agent-Native Memory Through LLM-Curated % Hierarchical Context % ============================================================ \\documentclass 11pt {article} 证据：`paper/main.tex`\n- **References**（source_file）：% ============================================================ % ByteRover Paper — Bibliography % ============================================================ 证据：`paper/references.bib`\n- **!/bin/sh**（source_file）：!/bin/sh byterover-legacy-plugin.sh — Legacy ByteRover Context Plugin Installer DEPRECATED: This script installs the old local-file-based ByteRover context plugin. For new installations, use the official plugin CLI instead: openclaw plugins install @byterover/byterover This script is provided for users who need the previous manual plugin installation e.g. air-gapped environments, custom plugin modifications, or rollback scenarios . Usage: sh scripts/byterover-legacy-plugin.sh --uninstall 证据：`scripts/byterover-legacy-plugin.sh`\n- **!/bin/sh**（source_file）：!/bin/sh install.sh — ByteRover CLI installer Usage: curl -fsSL https://storage.googleapis.com/brv-releases/install.sh sh Environment variables: BRV INSTALL DIR Override install location default: ~/.brv-cli 证据：`scripts/install.sh`\n- **!/usr/bin/env npx ts-node --esm**（source_file）：!/usr/bin/env npx ts-node --esm / One-shot migration: ensure every context-tree markdown file has all seven required semantic frontmatter fields. Usage: npx ts-node --esm scripts/migrate-frontmatter-complete.ts npx ts-node --esm scripts/migrate-frontmatter-complete.ts --dry-run / 证据：`scripts/migrate-frontmatter-complete.ts`\n- **!/bin/sh**（source_file）：!/bin/sh openclaw-setup.sh — ByteRover Integration Installer for OpenClaw Usage: curl -fsSL https://storage.googleapis.com/brv-releases/openclaw-setup.sh sh Configures ByteRover as long-term memory for OpenClaw agents: - Automatic Memory Flush context compaction - ByteRover Context Plugin hook-based injection - Workspace protocol updates AGENTS.md, TOOLS.md 证据：`scripts/openclaw-setup.sh`\n- **Prepare Ui Submodule Links**（source_file）：import {constants} from 'node:fs' import {access, lstat, mkdir, rm, symlink} from 'node:fs/promises' import {dirname, resolve} from 'node:path' import {fileURLToPath} from 'node:url' 证据：`scripts/prepare-ui-submodule-links.mjs`\n- **!/bin/sh**（source_file）：!/bin/sh uninstall.sh — ByteRover CLI uninstaller Usage: curl -fsSL https://storage.googleapis.com/brv-releases/uninstall.sh sh Flags: --yes, -y Skip confirmation prompt --help, -h Show usage information Environment variables: BRV INSTALL DIR Override install location default: ~/.brv-cli BRV DATA DIR Override data directory 证据：`scripts/uninstall.sh`\n- **Index**（source_file）：export {run} from '@oclif/core' 证据：`src/index.ts`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`AGENTS.md`, `CLAUDE.md`, `README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`AGENTS.md`, `CLAUDE.md`, `README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概述**：importance `high`\n - source_paths: README.md, package.json, CLAUDE.md\n- **系统架构**：importance `high`\n - source_paths: src/agent/core/interfaces/index.ts, src/index.ts, src/server/infra/transport/socket-io-transport-server.ts, src/oclif/commands/main.ts\n- **Agent核心系统**：importance `high`\n - source_paths: src/agent/core/domain/agent/agent-state-machine.ts, src/agent/core/domain/agent/agent-registry.ts, src/agent/infra/agent/base-agent.ts, src/agent/infra/agent/agent-state-manager.ts, src/agent/infra/memory/memory-manager.ts\n- **LLM提供商集成**：importance `high`\n - source_paths: src/agent/infra/llm/providers/index.ts, src/agent/infra/llm/providers/anthropic.ts, src/agent/infra/llm/providers/openai.ts, src/agent/infra/llm/providers/google.ts, src/agent/infra/llm/agent-llm-service.ts\n- **工具系统**：importance `high`\n - source_paths: src/agent/core/domain/tools/types.ts, src/agent/infra/tools/tool-registry.ts, src/agent/infra/tools/tool-manager.ts, src/agent/infra/tools/core-tool-scheduler.ts, src/agent/infra/tools/implementations/read-file-tool.ts\n- **上下文树与知识管理**：importance `high`\n - source_paths: src/agent/infra/map/agentic-map-service.ts, src/agent/infra/map/context-tree-store.ts, src/server/infra/context-tree/file-context-tree-service.ts, src/server/infra/context-tree/file-context-tree-summary-service.ts, src/agent/core/domain/knowledge/conflict-detector.ts\n- **版本控制系统**：importance `medium`\n - source_paths: src/oclif/commands/vc/index.ts, src/oclif/commands/vc/branch.ts, src/oclif/commands/vc/commit.ts, src/oclif/commands/vc/merge.ts, src/server/infra/git/isomorphic-git-service.ts\n- **Swarm多代理协调**：importance `medium`\n - source_paths: src/agent/core/domain/swarm/types.ts, src/agent/infra/swarm/swarm-coordinator.ts, src/agent/infra/swarm/swarm-router.ts, src/agent/infra/swarm/adapters/byterover-adapter.ts, src/agent/infra/swarm/wizard/swarm-wizard.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `f87a0ded1f693ad6d09f794ac2dcc93a6eaa6706`\n- inspected_files: `package.json`, `README.md`, `src/index.ts`, `src/webui/vite-env.d.ts`, `src/webui/vite.config.ts`, `src/webui/tsconfig.json`, `src/server/constants.ts`, `src/oclif/constants.ts`, `src/webui/stores/transport-store.ts`, `src/webui/utils/initials.ts`, `src/webui/lib/error-messages.ts`, `src/webui/lib/transport.ts`, `src/webui/lib/syntax-highlighter.ts`, `src/webui/lib/react-query.ts`, `src/webui/lib/noop.ts`, `src/webui/lib/api-client.ts`, `src/webui/lib/toast-vc-error.ts`, `src/webui/lib/transport-error.ts`, `src/webui/features/context/types.ts`, `src/webui/features/vc/types.ts`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：Curator can copy prompt example facts into the context tree when using Gemini Flash-Lite\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Curator can copy prompt example facts into the context tree when using Gemini Flash-Lite\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_f0927b3fa77c4e7ab29ba04f3c4b7ed7 | https://github.com/campfirein/byterover-cli/issues/647 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：Visual corruption while browsing a long model list\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Visual corruption while browsing a long model list\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_3112b1ba6fc54e0a8d973b277ab8d106 | https://github.com/campfirein/byterover-cli/issues/620 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：ByteRover CLI 3.10.1\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.10.1\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_c21085e93cad46a5b79d8ff2353f156c | https://github.com/campfirein/byterover-cli/releases/tag/v3.10.1 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：ByteRover CLI 3.10.3\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.10.3\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_5ada5377aa504edeac454b6a66310a47 | https://github.com/campfirein/byterover-cli/releases/tag/v3.10.3 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：ByteRover CLI 3.8.1\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.8.1\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_370b6c20f13544c28427013da0519f1f | https://github.com/campfirein/byterover-cli/releases/tag/v3.8.1 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：ByteRover CLI 3.8.2\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.8.2\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_48b470d455aa406480648e100bc08c94 | https://github.com/campfirein/byterover-cli/releases/tag/v3.8.2 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：ByteRover CLI 3.8.3\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.8.3\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_70d8761f65864cf2897a70138eabb5b7 | https://github.com/campfirein/byterover-cli/releases/tag/v3.8.3 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：ByteRover CLI 3.9.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.9.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_955f12701a864106895fc95c8ef7fd05 | https://github.com/campfirein/byterover-cli/releases/tag/v3.9.0 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：`brv mcp` client stuck in infinite exception loop consuming 75–90% CPU for hours\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：`brv mcp` client stuck in infinite exception loop consuming 75–90% CPU for hours\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_50500a3417394344864f50cf765157ea | https://github.com/campfirein/byterover-cli/issues/660 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：campfirein/byterover-cli\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：Curator can copy prompt example facts into the context tree when using Gemini Flash-Lite（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Visual corruption while browsing a long model list（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：ByteRover CLI 3.10.1（medium）：可能影响升级、迁移或版本选择。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：ByteRover CLI 3.10.3（medium）：可能影响升级、迁移或版本选择。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：ByteRover CLI 3.8.1（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/campfirein/byterover-cli 项目说明书\n\n生成时间：2026-05-14 13:16:52 UTC\n\n## 目录\n\n- [项目概述](#project-overview)\n- [系统架构](#system-architecture)\n- [Agent核心系统](#agent-system)\n- [LLM提供商集成](#llm-providers)\n- [工具系统](#tools-system)\n- [上下文树与知识管理](#context-tree)\n- [版本控制系统](#version-control)\n- [Swarm多代理协调](#swarm-coordination)\n- [TUI交互界面](#tui-interface)\n- [WebUI管理面板](#webui-dashboard)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [Agent核心系统](#agent-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/campfirein/byterover-cli/blob/main/README.md)\n- [src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts)\n- [src/server/templates/README.md](https://github.com/campfirein/byterover-cli/blob/main/src/server/templates/README.md)\n- [src/shared/transport/events/vc-events.ts](https://github.com/campfirein/byterover-cli/blob/main/src/shared/transport/events/vc-events.ts)\n- [src/tui/components/onboarding/welcome-box.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/tui/components/onboarding/welcome-box.tsx)\n- [src/agent/infra/sandbox/curate-service.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/sandbox/curate-service.ts)\n \n\n# 项目概述\n\n## 项目简介\n\nByteRover CLI（命令行工具）是一个交互式 REPL（Read-Eval-Print Loop）命令行工具，专为 AI 编程代理提供持久化、结构化的记忆能力。它使开发者能够将项目知识组织成上下文树（Context Tree），同步到云端，并在不同工具和团队成员之间共享。\n\n资料来源：[README.md:1-15]()\n\n该工具通过命令行界面 `brv` 运行，开发者可以在任何项目目录中启动，享受 AI 代理带来的智能编程体验。ByteRover 的核心设计理念是：**让 AI 代理能够理解和记忆项目上下文，从而提供更精准的代码生成和问题诊断**。\n\n## 核心架构\n\n### 系统组件概览\n\nByteRover CLI 采用模块化架构，主要包含以下核心组件：\n\n| 组件名称 | 功能描述 | 源码位置 |\n|---------|---------|---------|\n| **Agent 核心** | AI 代理执行引擎，处理工具调用和推理 | `src/agent/` |\n| **Sandbox 服务** | 知识策展操作的执行环境 | `src/agent/infra/sandbox/` |\n| **TUI 组件** | 终端用户界面渲染 | `src/tui/` |\n| **WebUI 组件** | 浏览器图形界面 | `src/webui/` |\n| **传输层** | 前后端通信和事件系统 | `src/shared/transport/` |\n| **模板系统** | 动态生成代理指令 | `src/server/templates/` |\n\n### 架构流程图\n\n```mermaid\ngraph TD\n A[用户终端] -->|brv 命令| B[CLI 入口]\n B --> C{交互模式}\n C -->|TUI| D[终端用户界面]\n C -->|WebUI| E[Web 浏览器界面]\n \n D --> F[Agent 执行引擎]\n E --> F\n \n F --> G[上下文树管理]\n F --> H[Sandbox 服务]\n F --> I[版本控制集成]\n \n G --> J[知识策展服务]\n H --> J\n I --> J\n \n J --> K[云端同步]\n K --> L[远程存储]\n \n F --> M[系统提示构建]\n M --> N[上下文树结构贡献者]\n N --> O[Context Tree 结构]\n```\n\n## 核心功能模块\n\n### 1. 上下文树（Context Tree）\n\n上下文树是 ByteRover 的核心知识组织结构，采用层次化文件管理方式存储项目知识。\n\n资料来源：[src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts:1-60]()\n\n#### 目录结构规范\n\n```\n.brv/context-tree/\n├── [domain]/ # 顶级域名（动态创建）\n│ ├── [topic].md # 主题文件\n│ └── [subtopic]/\n│ └── context.md # 子主题内容\n├── _index.md # 自动生成的目录摘要\n└── _archived/ # 归档的低优先级条目\n```\n\n#### 动态域名系统\n\n- **域名创建**：根据策展内容的语义动态创建\n- **命名规范**：使用 snake_case 格式（如 `architecture`、`market_trends`）\n- **组织原则**：在创建新域名之前，应检查现有域名是否可容纳内容\n\n### 2. 知识策展服务（Curate Service）\n\n知识策展服务负责对上下文树中的知识主题进行增删改查操作。\n\n资料来源：[src/agent/infra/sandbox/curate-service.ts:1-80]()\n\n#### 策展操作类型\n\n| 操作类型 | 说明 | 内容要求 |\n|---------|------|---------|\n| `ADD` | 添加新主题 | 需要 title 和 content |\n| `UPDATE` | 更新现有主题 | 需要 title 和/或 content |\n| `UPSERT` | 存在则更新，不存在则创建 | 需要 title 和 content |\n| `DELETE` | 删除主题 | 只需要 path |\n\n#### 内容存储格式\n\n策展内容支持多种数据类型的存储：\n\n- **事实（Factual）**：个人、项目配置、团队约定等\n- **图表（Diagrams）**：Mermaid、PlantUML、ASCII 图表\n- **决策（Decisions）**：包含完整理由的决策文本\n- **流程（Flow）**：工作流步骤和条件\n\n### 3. 版本控制集成（VC Events）\n\nByteRover 内置了类似 Git 的版本控制功能，支持分布式团队协作。\n\n资料来源：[src/shared/transport/events/vc-events.ts:1-50]()\n\n#### 差异比较模式\n\n| 模式 | 说明 | Git 对应 |\n|-----|------|---------|\n| `unstaged` | 工作目录 vs 暂存区 | `git diff` |\n| `staged` | 暂存区 vs HEAD | `git diff --staged` |\n| `ref-vs-worktree` | 指定引用 vs 工作目录 | `git diff [` |\n| `range` | 两个引用之间 | `git diff ..` |\n\n#### 版本控制命令\n\n```bash\nbrv vc add . # 暂存所有文件\nbrv vc add notes.md docs/ # 暂存指定文件\nbrv vc commit -m \"add patterns\" # 提交更改\nbrv vc log # 查看历史\nbrv vc branch feature/auth # 创建分支\nbrv vc merge feature/auth # 合并分支\n```\n\n### 4. 模板系统（Template System）\n\n模板系统用于根据用户选择的 AI 代理动态生成指令规则。\n\n资料来源：[src/server/templates/README.md:1-40]()\n\n#### 模板目录结构\n\n```\nsrc/templates/\n├── base.md # 主模板结构\n├── sections/ # 可复用内容区块\n│ ├── workflow.md # 工作流指南\n│ └── command-reference.md # 命令参考文档\n└── README.md # 本说明文件\n```\n\n#### 模板变量\n\n| 变量名 | 说明 | 示例 |\n|-------|------|------|\n| `{{agent_name}}` | 代理名称 | \"Claude Code\", \"Cursor\" |\n| `{{workflow}}` | 工作流内容 | sections/workflow.md |\n| `{{command_reference}}` | 命令参考 | sections/command-reference.md |\n\n### 5. 用户界面\n\nByteRover 提供两种用户界面选项：\n\n#### 终端用户界面（TUI）\n\n基于终端的交互式界面，支持以下功能：\n\n- 实时执行日志展示\n- 文件变更追踪\n- 推理内容显示\n- 欢迎引导界面\n\n资料来源：[src/tui/components/onboarding/welcome-box.tsx:1-50]()\n\n#### Web 用户界面（WebUI）\n\n浏览器图形界面，提供：\n\n- 上下文历史面板\n- Hub 组件展示\n- 离线状态处理\n- 传输层事件处理\n\n## 数据流与状态管理\n\n### 代理执行流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant TUI as TUI 界面\n participant Agent as Agent 引擎\n participant Sandbox as Sandbox 服务\n participant Tree as 上下文树\n participant Cloud as 云端\n\n User->>TUI: 输入命令\n TUI->>Agent: 转发请求\n Agent->>Agent: 执行推理\n Agent->>Sandbox: 调用工具\n Sandbox->>Tree: 读写知识\n Tree-->>Sandbox: 返回数据\n Sandbox-->>Agent: 执行结果\n Agent->>Cloud: 同步变更\n Cloud-->>Agent: 确认\n Agent-->>TUI: 返回响应\n TUI-->>User: 展示结果\n```\n\n### 知识策展操作流\n\n```mermaid\ngraph TD\n A[发起策展操作] --> B{操作类型验证}\n B -->|有效| C[验证必需字段]\n B -->|无效| D[返回失败]\n C -->|完整| E[执行文件操作]\n C -->|不完整| F[返回失败]\n E --> G[更新上下文树]\n G --> H[生成摘要]\n H --> I[同步云端]\n```\n\n## 命令行接口\n\n### 核心命令\n\n| 命令 | 功能 | 示例 |\n|-----|------|------|\n| `brv login` | 用户认证 | `brv login` |\n| `brv init` | 初始化项目 | `brv init` |\n| `brv status` | 查看状态 | `brv status` |\n| `brv add` | 添加上下文 | `brv add ./docs` |\n| `brv gen-rules` | 生成代理规则 | `brv gen-rules` |\n| `brv push` | 推送到云端 | `brv push` |\n| `brv watch` | 监听文件变更 | `brv watch` |\n| `brv cipher-agent` | 代理加密 | `brv cipher-agent` |\n\n### Space 命令\n\n| 命令 | 功能 |\n|-----|------|\n| `brv space list` | 列出所有空间 |\n| `brv space switch` | 切换当前空间 |\n\n## 技术特点\n\n### 设计原则\n\n1. **持久化记忆**：为 AI 代理提供跨会话的项目上下文记忆\n2. **结构化组织**：使用树形结构管理知识，便于检索\n3. **云端同步**：支持团队协作和跨设备同步\n4. **多代理支持**：兼容多种 AI 编码代理（Claude Code、Cursor 等）\n5. **自包含**：WebUI 采用全内联 CSS/JS，无外部依赖\n\n### 安全性\n\n- 支持代理加密功能（`cipher-agent`）\n- 版本控制支持分支管理和合并冲突解决\n- 敏感操作需要用户确认（如 Approve/Reject）\n\n## 快速入门\n\n```bash\n# 安装 CLI\nnpm install -g byterover-cli\n\n# 登录认证\nbrv login\n\n# 初始化项目\nbrv init\n\n# 启动交互式 REPL\nbrv\n\n# 在 REPL 中策展知识\n/curate\n\n# 查询相关记忆\n/query <关键词>\n\n# 同步到云端\nbrv push\n```\n\n## 相关文档\n\n- [工作流指南](./workflow.md)\n- [命令参考](./command-reference.md)\n- [技能模板](./skill/SKILL.md)\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目概述](#project-overview), [Agent核心系统](#agent-system)\n\n]\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agent/infra/map/abstract-generator.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/map/abstract-generator.ts)\n- [src/agent/infra/sandbox/curate-service.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/sandbox/curate-service.ts)\n- [src/server/infra/http/review-ui.ts](https://github.com/campfirein/byterover-cli/blob/main/src/server/infra/http/review-ui.ts)\n- [src/server/infra/provider-oauth/callback-server.ts](https://github.com/campfirein/byterover-cli/blob/main/src/server/infra/provider-oauth/callback-server.ts)\n- [src/server/templates/README.md](https://github.com/campfirein/byterover-cli/blob/main/src/server/templates/README.md)\n- [src/shared/transport/events/vc-events.ts](https://github.com/campfirein/byterover-cli/blob/main/src/shared/transport/events/vc-events.ts)\n- [src/tui/features/vc/pull/components/vc-pull-flow.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/tui/features/vc/pull/components/vc-pull-flow.tsx)\n- [README.md](https://github.com/campfirein/byterover-cli/blob/main/README.md)\n \n\n# 系统架构\n\n## 概述\n\nByteRover CLI（命令行工具 `brv`）是一个为 AI 编程代理提供持久化、结构化记忆的交互式 REPL 工具。它允许开发者在上下文树中管理项目知识，与云端同步，并跨工具和团队共享。 资料来源：[README.md]()\n\n该系统采用分层架构设计，核心层负责 AI 代理的上下文管理与操作，传输层处理客户端与服务器之间的实时通信，呈现层同时支持终端界面（TUI）和网页界面（WebUI）两种交互模式。\n\n## 整体架构\n\n```mermaid\ngraph TD\n subgraph 客户端层\n TUI[TUI 终端界面]\n WebUI[WebUI 网页界面]\n end\n \n subgraph 传输层\n SocketIO[Socket.IO 传输服务器]\n HTTP[HTTP 服务器]\n end\n \n subgraph 核心层\n Agent[Agent 核心]\n Sandbox[沙箱环境]\n CurateService[Curate 服务]\n end\n \n subgraph 基础设施层\n VcEvents[VC 事件系统]\n AbstractGen[抽象生成器]\n OutputGen[输出生成器]\n ReviewUI[审查 UI]\n end\n \n TUI <--> SocketIO\n WebUI <--> HTTP\n SocketIO <--> Agent\n HTTP <--> Agent\n Agent <--> Sandbox\n Sandbox <--> CurateService\n Agent <--> VcEvents\n Agent <--> AbstractGen\n Agent <--> OutputGen\n```\n\n## 分层架构详解\n\n### 1. 客户端层\n\nByteRover CLI 提供两种用户界面，以满足不同使用场景的需求：\n\n| 界面类型 | 技术栈 | 适用场景 |\n|---------|--------|----------|\n| TUI | React + Ink | 终端重度用户，习惯命令行操作 |\n| WebUI | React + TailwindCSS | 偏好图形界面，需要可视化操作 |\n\n#### TUI 组件结构\n\nTUI（终端用户界面）采用组件化设计，主要组件位于 `src/tui/` 目录：\n\n- **执行组件**：`ExecutionProgress`、`ExecutionContent`、`ExecutionChanges` 用于展示代理执行过程\n- **VC 组件**：`VcPullFlow` 处理版本控制拉取流程\n- **Hub 组件**：`HubDetailStep` 展示技能详情\n\n```tsx\n// 执行日志视图 - 展示流式内容\n{log.streamingContent && log.status === 'running' && (\n \n)}\n```\n\n资料来源：[src/tui/components/execution/expanded-log-view.tsx:36-42]()\n\n### 2. 传输层\n\n传输层负责客户端与服务器之间的通信，采用双协议支持：\n\n#### Socket.IO 传输服务器\n\n基于 Socket.IO 实现实时双向通信，适用于需要即时反馈的场景：\n\n```typescript\n// 核心传输服务器职责：\n// - 管理客户端连接生命周期\n// - 处理实时事件分发\n// - 维护连接状态\n```\n\n#### HTTP 服务器\n\nHTTP 服务器处理同步请求和回调流程，主要用途包括：\n\n- OAuth 认证回调处理\n- 静态资源服务\n- HITL（人机回环）审查 UI 服务\n\n```typescript\nfunction errorHtml(message: string): string {\n return `\n\n\n ByteRover - Authorization Failed\n ...\n\n`\n}\n```\n\n资料来源：[src/server/infra/provider-oauth/callback-server.ts:42-59]()\n\n### 3. 核心层\n\n核心层是系统的中枢，包含 AI 代理的主要逻辑：\n\n#### Agent 核心模块\n\n代理核心负责：\n- 理解代码库结构和语义\n- 读取和写入文件\n- 管理上下文树状态\n- 与 LLM 交互生成响应\n\n#### Curate 服务\n\n`CurateService` 是核心层的重要组成部分，提供知识主题的组织和领域检测功能：\n\n```typescript\nexport class CurateService implements ICurateService {\n private readonly workingDirectory: string\n\n constructor(\n workingDirectory?: string,\n private readonly abstractQueue?: AbstractGenerationQueue,\n private readonly runtimeSignalStore?: IRuntimeSignalStore,\n ) {\n this.workingDirectory = workingDirectory ?? process.cwd()\n }\n}\n```\n\n资料来源：[src/agent/infra/sandbox/curate-service.ts:66-76]()\n\n#### Curate 操作验证\n\n系统对 Curate 操作有严格的验证规则：\n\n| 操作类型 | 必需字段 | 说明 |\n|---------|---------|------|\n| ADD | title, content | 添加新知识条目 |\n| UPDATE | title, content | 更新现有条目 |\n| UPSERT | title, content | 存在则更新，不存在则创建 |\n| DELETE | path | 删除指定路径的条目 |\n\n```typescript\n// 操作验证逻辑\nif ((op.type === 'ADD' || op.type === 'UPDATE' || op.type === 'UPSERT') && !op.title) {\n failures.push({\n message: `${op.type} operation requires a title (becomes the .md filename).`,\n path: op.path,\n status: 'failed',\n type: op.type,\n })\n}\n```\n\n资料来源：[src/agent/infra/sandbox/curate-service.ts:41-49]()\n\n### 4. 基础设施层\n\n基础设施层为上层提供通用能力支持：\n\n#### VC 事件系统\n\n版本控制事件系统定义完整的 Diff 模式和数据模型：\n\n```typescript\nexport type VcDiffMode =\n | {from: string; kind: 'range'; to: string}\n | {kind: 'ref-vs-worktree'; ref: string}\n | {kind: 'staged'}\n | {kind: 'unstaged'}\n```\n\n资料来源：[src/shared/transport/events/vc-events.ts:14-21]()\n\n支持的 Diff 模式：\n\n| 模式 | 说明 | 对应 Git 命令 |\n|------|------|---------------|\n| unstaged | 工作目录 vs 暂存区 | `git diff` |\n| staged | HEAD vs 暂存区 | `git diff --staged` |\n| ref-vs-worktree | 指定提交 vs 工作目录 | `git diff [` |\n| range | 提交范围对比 | `git diff ..` |\n\n#### 抽象生成器\n\n`AbstractGenerator` 负责从知识文档生成结构化摘要：\n\n```typescript\nfunction parseBatchedTags(response: string, innerTag: 'abstract' | 'overview'): Map\n```\n\n输出格式采用 XML 结构：\n```xml\n\">\n- bullet 1\n- bullet 2\n\n```\n\n资料来源：[src/agent/infra/map/abstract-generator.ts:47-67]()\n\n#### 输出生成器\n\n`OutputGenerator` 负责将文件夹打包结果转换为 XML 格式输出：\n\n```typescript\n// 生成文件类型分布统计\nconst typeBreakdown = new Map()\nfor (const file of result.files) {\n const fileType = file.fileType ?? 'unknown'\n typeBreakdown.set(fileType, (typeBreakdown.get(fileType) ?? 0) + 1)\n}\n```\n\n资料来源：[src/agent/infra/folder-pack/output-generator.ts:37-41]()\n\n#### 审查 UI 生成\n\nHITL 审查 UI 是自包含的 HTML 页面，内嵌所有 CSS 和 JavaScript：\n\n```typescript\nexport function getReviewPageHtml(): string {\n return `\n\n\n\n\nByteRover Review\n\n\n...`\n}\n```\n\n资料来源：[src/server/infra/http/review-ui.ts:7-28]()\n\n## 命令行入口\n\n系统通过 `oclif` 框架实现命令行入口，主要命令位于 `src/oclif/commands/`：\n\n```bash\nbrv login # 用户认证\nbrv init # 初始化项目\nbrv status # 查看状态\nbrv add # 添加文件到上下文\nbrv gen-rules # 生成代理规则\nbrv push # 推送到云端\nbrv watch # 监听文件变化\nbrv vc # 版本控制命令\n```\n\n资料来源：[src/server/templates/skill/SKILL.md:1-20]()\n\n## 云端同步架构\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端 (brv)\n participant Server as ByteRover Cloud\n participant Space as Space 工作区\n \n Client->>Server: brv login\n Server-->>Client: 认证成功\n Client->>Space: brv vc push/pull\n Space-->>Client: 同步完成\n```\n\n云端同步功能要求：\n- 完成 ByteRover 认证（`brv login`）\n- 配置远程仓库地址\n- 可通过 Web 应用创建或打开 Space\n\n资料来源：[src/tui/features/vc/pull/components/vc-pull-flow.tsx:1-15]()\n\n## 模板系统\n\nByteRover 使用模板系统生成代理指令，通过 `brv gen-rules` 命令触发：\n\n```\nsrc/templates/\n├── base.md # 主模板结构\n├── sections/ # 可复用内容区段\n│ ├── workflow.md # 工作流指南\n│ └── command-reference.md # 命令参考文档\n└── README.md\n```\n\n模板变量替换：\n- `{{agent_name}}` - 代理名称\n- `{{workflow}}` - 工作流内容\n- `{{command_reference}}` - 命令参考内容\n\n资料来源：[src/server/templates/README.md:1-30]()\n\n## 技术栈总结\n\n| 层级 | 主要技术 | 文件位置 |\n|------|---------|----------|\n| 客户端 | React, Ink, TailwindCSS | `src/tui/`, `src/webui/` |\n| 传输 | Socket.IO, Node.js HTTP | `src/server/infra/transport/` |\n| 核心 | TypeScript | `src/agent/core/`, `src/agent/infra/` |\n| 基础设施 | XML 生成, 事件系统 | `src/shared/`, `src/agent/infra/` |\n| CLI | oclif | `src/oclif/` |\n\n---\n\n\n\n## Agent核心系统\n\n### 相关页面\n\n相关主题：[LLM提供商集成](#llm-providers), [工具系统](#tools-system), [上下文树与知识管理](#context-tree)\n\n]\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agent/infra/map/abstract-generator.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/map/abstract-generator.ts)\n- [src/agent/infra/sandbox/curate-service.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/sandbox/curate-service.ts)\n- [src/agent/infra/process/command-validator.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/process/command-validator.ts)\n- [src/agent/infra/folder-pack/output-generator.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/folder-pack/output-generator.ts)\n \n\n# Agent核心系统\n\n## 概述\n\nByteRover CLI 的 Agent 核心系统是一个模块化的基础设施架构，负责为 AI Agent 提供运行时环境、命令安全验证、知识管理和输出生成能力。该系统采用分层设计，核心基础设施包括：\n\n- **抽象生成器**（Abstract Generator）：处理知识文档的结构化概览生成\n- **策展服务**（Curate Service）：管理知识主题的增删改查操作\n- **命令验证器**（Command Validator）：提供命令安全性和权限校验\n- **输出生成器**（Output Generator）：生成结构化的文件夹打包输出\n\n## 系统架构\n\n```mermaid\ngraph TB\n subgraph \"Agent 核心基础设施\"\n AG[Agent Core]\n end\n \n subgraph \"Infra Layer\"\n MAP[Map/Abstract Generator
src/agent/infra/map/]\n SBX[Sandbox/Curate Service
src/agent/infra/sandbox/]\n PROC[Process/Command Validator
src/agent/infra/process/]\n OUT[Folder Pack/Output Generator
src/agent/infra/folder-pack/]\n end\n \n AG --> MAP\n AG --> SBX\n AG --> PROC\n AG --> OUT\n```\n\n## 抽象生成器（Abstract Generator）\n\n### 功能定位\n\n`abstract-generator.ts` 负责从知识文档集合中生成结构化的概览信息，支持 XML 格式的批量处理和解析。\n\n### 核心能力\n\n| 能力 | 描述 |\n|------|------|\n| 文档包装 | 将文件路径和内容封装为 XML 格式 |\n| 概览生成 | 提示 LLM 生成 markdown 格式的结构化摘要 |\n| 批量解析 | 从模型输出中提取 `` 和 `/` 标签 |\n\n### XML 格式规范\n\n系统使用 CDATA 块保护内容，避免 XML 转义问题：\n\n```xml\n\n \n\n```\n\n### 解析策略\n\n`parseBatchedTags` 函数采用锚定策略进行容错解析：\n\n- 以 `` 开启标签为锚点\n- 每个开启标签own对应到下一个开启标签前的响应切片\n- 内部正则提取该切片中的 payload\n- 此设计避免模型输出中包含 `` 字面量时导致的错误匹配\n\n资料来源：[src/agent/infra/map/abstract-generator.ts:28-35]()\n\n## 策展服务（Curate Service）\n\n### 功能定位\n\n`curate-service.ts` 实现知识主题的策展操作，支持 ADD、UPDATE、UPSERT、DELETE 等原子操作。\n\n### 操作验证规则\n\n| 操作类型 | 必需字段 | 验证条件 |\n|----------|----------|----------|\n| ADD | title, content | title 为文件名，content 包含 rawConcept 和/或 narrative |\n| UPDATE | title, content | 同 ADD |\n| UPSERT | title, content | 同 ADD |\n| DELETE | path | 仅需 path |\n\n### CurateResult 结构\n\n策展操作返回结果包含：\n\n- `appliedOperations`：已应用的原子操作列表\n- `summary`：操作摘要\n- `failures`：验证失败的操作详情\n\n```typescript\ninterface CurateResult {\n appliedOperations: CurateOperation[]\n summary: string\n failures: Array<{\n message: string\n path: string\n status: 'failed'\n type: OperationType\n }>\n}\n```\n\n资料来源：[src/agent/infra/sandbox/curate-service.ts:1-40]()\n\n## 命令验证器（Command Validator）\n\n### 安全架构\n\n命令验证器是 Agent 系统的安全防线，基于可配置的安全级别和黑白名单机制。\n\n```mermaid\ngraph LR\n CMD[Command Input] --> VAL{CommandValidator}\n VAL -->|Allowed| EXEC[Execute]\n VAL -->|Blocked| REJECT[Reject + Log]\n VAL -->|Requires Approval| WAIT[Wait for Approval]\n \n style EXEC fill:#90EE90\n style REJECT fill:#FFB6C1\n style WAIT fill:#FFE4B5\n```\n\n### 内置只读命令模式\n\n系统预定义了安全的只读命令正则：\n\n```typescript\nconst READ_ONLY_PATTERNS = [\n /cat\\s+.*>/, // 读取文件内容\n /find\\s+.*>/, // 查找文件\n /git\\s+(status|log|diff|show|branch|tag|fetch|pull)(?!\\s+-)/i, // Git 只读操作\n]\n```\n\n### 验证流程\n\n1. **危险模式检测**：检查是否匹配已知危险命令模式\n2. **黑名单检查**：验证命令是否在 blockedCommands 列表中\n3. **白名单放行**：若命中 allowedCommands，直接通过\n4. **安全级别评估**：根据 securityLevel 判断是否需要审批\n\n### 路径参数提取\n\n`extractPathArguments` 方法专门处理命令中的文件路径参数：\n\n- 过滤掉以 `-` 开头的 flags\n- 排除 chmod 等特殊参数模式\n- 规范化跨平台路径格式\n\n资料来源：[src/agent/infra/process/command-validator.ts:1-60]()\n\n## 输出生成器（Output Generator）\n\n### 功能定位\n\n`output-generator.ts` 负责将文件夹打包结果转换为 XML 格式的结构化输出，便于 LLM 理解和处理。\n\n### 输出结构\n\n```xml\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```typescript\nconst typeBreakdown = new Map()\nfor (const file of result.files) {\n const fileType = file.fileType ?? 'unknown'\n typeBreakdown.set(fileType, (typeBreakdown.get(fileType) ?? 0) + 1)\n}\n```\n\n### 配置项\n\n| 配置项 | 用途 | 默认行为 |\n|--------|------|----------|\n| maxFileSize | 单文件大小限制 | 格式化显示 |\n| maxLinesPerFile | 单文件行数限制 | 格式化显示 |\n| ignore | 忽略模式列表 | 显示模式数量 |\n\n资料来源：[src/agent/infra/folder-pack/output-generator.ts:1-50]()\n\n## 工作流程集成\n\n### Agent 执行上下文\n\n```mermaid\nsequenceDiagram\n participant Agent as Agent Core\n participant Validator as Command Validator\n participant Curate as Curate Service\n participant Output as Output Generator\n \n Agent->>Validator: Validate Command\n Validator-->>Agent: Allow/Block/Approval Required\n \n alt Command Allowed\n Agent->>Curate: Curate Operations\n Curate-->>Agent: CurateResult\n Agent->>Output: Generate XML Output\n Output-->>Agent: Structured Response\n end\n```\n\n### 知识文档处理流程\n\n1. **输入**：知识文档集合（路径 + 内容）\n2. **包装**：转换为 XML 格式，使用 CDATA 保护内容\n3. **生成**：提示 LLM 生成结构化概览\n4. **解析**：从模型响应中提取 `` 和 `` 标签对\n5. **输出**：返回 Map 结构\n\n## 配置与扩展\n\n### 安全级别配置\n\n`ProcessConfig` 支持的安全配置项：\n\n```typescript\ninterface ProcessConfig {\n allowedCommands?: string[] // 白名单命令\n blockedCommands?: string[] // 黑名单命令\n securityLevel?: 'low' | 'medium' | 'high'\n}\n```\n\n### 扩展点\n\n| 扩展点 | 文件位置 | 扩展方式 |\n|--------|----------|----------|\n| 命令验证 | command-validator.ts | 添加新的验证正则或规则 |\n| 抽象生成 | abstract-generator.ts | 自定义解析策略或输出格式 |\n| 策展操作 | curate-service.ts | 添加新的操作类型 |\n| 输出格式 | output-generator.ts | 扩展 XML 结构 |\n\n## 总结\n\nByteRover CLI 的 Agent 核心系统通过模块化的基础设施设计，实现了：\n\n- **安全性**：命令验证器提供多层安全防护\n- **可观测性**：结构化输出便于调试和追踪\n- **扩展性**：清晰的接口和配置机制支持定制\n- **容错性**：解析器采用锚定策略避免边界情况\n\n这些基础设施组件协同工作，为 AI Agent 提供安全、可靠、可控的运行时环境。\n\n---\n\n\n\n## LLM提供商集成\n\n### 相关页面\n\n相关主题：[Agent核心系统](#agent-system), [工具系统](#tools-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agent/infra/llm/providers/index.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/llm/providers/index.ts)\n- [src/agent/infra/llm/providers/anthropic.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/llm/providers/anthropic.ts)\n- [src/agent/infra/llm/providers/openai.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/llm/providers/openai.ts)\n- [src/agent/infra/llm/providers/google.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/llm/providers/google.ts)\n- [src/agent/infra/llm/agent-llm-service.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/llm/agent-llm-service.ts)\n- [src/agent/infra/llm/retry/retry-with-backoff.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/llm/retry/retry-with-backoff.ts)\n- [src/agent/infra/llm/context/context-manager.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/llm/context/context-manager.ts)\n \n\n# LLM提供商集成\n\n## 概述\n\nByteRover CLI 的 LLM（大型语言模型）提供商集成模块位于 `src/agent/infra/llm/` 目录下，负责管理与各种 AI 模型提供商的通信。该模块采用工厂模式和适配器模式，支持多种 LLM 提供商（Anthropic、OpenAI、Google）的无缝切换，使系统能够在不同 AI 服务之间灵活选择和配置。\n\nLLM 提供商集成的核心职责包括：\n\n- **统一抽象接口**：为不同提供商提供一致的调用方式\n- **认证管理**：处理各提供商的 API 密钥和环境变量配置\n- **请求重试机制**：通过指数退避策略处理临时性网络故障和限流\n- **上下文管理**：优化 token 使用，控制对话历史长度\n\n资料来源：[src/agent/infra/llm/providers/index.ts]()\n\n## 架构设计\n\n### 模块结构\n\n```\nsrc/agent/infra/llm/\n├── providers/ # 提供商适配器\n│ ├── index.ts # 提供商工厂与注册\n│ ├── anthropic.ts # Anthropic (Claude) 适配器\n│ ├── openai.ts # OpenAI (GPT) 适配器\n│ └── google.ts # Google (Gemini) 适配器\n├── agent-llm-service.ts # Agent LLM 服务主类\n├── retry/\n│ └── retry-with-backoff.ts # 重试机制实现\n└── context/\n └── context-manager.ts # 上下文管理\n```\n\n### 核心类关系\n\n```mermaid\ngraph TD\n A[Agent LLM Service] --> B[Provider Factory]\n B --> C[Anthropic Provider]\n B --> D[OpenAI Provider]\n B --> E[Google Provider]\n A --> F[Context Manager]\n A --> G[Retry with Backoff]\n \n H[LLM Request] --> A\n A --> I[Provider Response]\n \n C --> C1[Anthropic API]\n D --> D1[OpenAI API]\n E --> E1[Google AI API]\n```\n\n## 提供商适配器\n\n### 提供商注册与工厂模式\n\n`providers/index.ts` 实现了一个工厂模式，所有提供商在此注册。系统通过配置选择使用哪个提供商，无需修改调用代码即可切换 AI 模型。\n\n资料来源：[src/agent/infra/llm/providers/index.ts]()\n\n### Anthropic 提供商\n\nAnthropic 提供商适配器负责与 Claude 系列模型的通信。该适配器处理：\n\n- Anthropic 特有的请求格式（messages API）\n- `anthropic-version` 头部设置\n- `max_tokens` 和 `thinking` 块配置\n- 流式响应的解析\n\n资料来源：[src/agent/infra/llm/providers/anthropic.ts]()\n\n### OpenAI 提供商\n\nOpenAI 提供商适配器支持 GPT-4、GPT-4o 等模型系列。特性包括：\n\n- 兼容 OpenAI Chat Completions API 格式\n- 支持 `temperature`、`top_p` 等采样参数\n- 函数调用（Function Calling）支持\n- 多模态输入处理\n\n资料来源：[src/agent/infra/llm/providers/openai.ts]()\n\n### Google 提供商\n\nGoogle 提供商适配器集成 Gemini 模型：\n\n- Gemini API 格式适配\n- 安全过滤配置\n- 生成配置（temperature、topP、topK）\n- 系统指令处理\n\n资料来源：[src/agent/infra/llm/providers/google.ts]()\n\n## Agent LLM 服务\n\n`agent-llm-service.ts` 是 LLM 集成的核心服务类，封装了所有与 AI 模型交互的逻辑。\n\n### 主要职责\n\n| 职责 | 描述 |\n|------|------|\n| 提供商初始化 | 根据配置创建相应的提供商实例 |\n| 请求发送 | 构建请求并调用提供商 |\n| 响应处理 | 解析 AI 响应并转换为统一格式 |\n| 错误处理 | 统一管理各类异常情况 |\n\n资料来源：[src/agent/infra/llm/agent-llm-service.ts]()\n\n### 工作流程\n\n```mermaid\nsequenceDiagram\n participant Agent as Agent/Worker\n participant LLMService as Agent LLM Service\n participant Provider as Selected Provider\n participant API as External LLM API\n\n Agent->>LLMService: 发送请求\n LLMService->>LLMService: 应用上下文管理\n LLMService->>Provider: 调用提供商接口\n Provider->>API: 发送 API 请求\n API-->>Provider: 返回响应\n Provider-->>LLMService: 返回标准格式响应\n LLMService-->>Agent: 返回处理结果\n```\n\n## 重试机制\n\n### 指数退避策略\n\n`retry-with-backoff.ts` 实现了智能重试机制，用于处理网络临时故障和 API 限流情况。\n\n资料来源：[src/agent/infra/llm/retry/retry-with-backoff.ts]()\n\n### 重试配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| maxRetries | number | 3 | 最大重试次数 |\n| initialDelay | number | 1000 | 初始延迟（毫秒） |\n| maxDelay | number | 30000 | 最大延迟上限 |\n| backoffMultiplier | number | 2 | 退避系数 |\n\n### 重试条件\n\n系统仅对以下情况触发重试：\n\n- **网络错误**：连接超时、DNS 解析失败\n- **5xx 服务器错误**：上游服务暂时不可用\n- **429 限流错误**：API 调用频率超限\n\n以下情况不进行重试：\n\n- 认证失败（401、403）\n- 客户端请求错误（400）\n- 内容安全过滤（根据提供商配置）\n\n## 上下文管理\n\n### Context Manager\n\n`context-manager.ts` 负责管理和优化对话上下文，确保在 token 限制内提供最佳上下文。\n\n资料来源：[src/agent/infra/llm/context/context-manager.ts]()\n\n### 上下文窗口管理\n\n```mermaid\ngraph LR\n A[用户消息] --> B[Context Manager]\n B --> C{Token 计数}\n C -->|超限| D[压缩历史]\n C -->|正常| E[直接添加]\n D --> F[摘要生成]\n E --> G[上下文列表]\n F --> G\n G --> H[LLM 请求]\n```\n\n### 上下文优化策略\n\n| 策略 | 触发条件 | 处理方式 |\n|------|----------|----------|\n| 滑动窗口 | 对话历史过长 | 保留最近 N 条消息 |\n| 摘要压缩 | 单条消息过长 | 生成摘要替代原文 |\n| 关键信息保留 | 任何压缩场景 | 保留系统指令和关键配置 |\n\n## 配置与认证\n\n### 环境变量配置\n\n| 变量名 | 提供商 | 说明 |\n|--------|--------|------|\n| `ANTHROPIC_API_KEY` | Anthropic | Claude API 密钥 |\n| `OPENAI_API_KEY` | OpenAI | GPT API 密钥 |\n| `GOOGLE_API_KEY` | Google | Gemini API 密钥 |\n\n### 提供商选择\n\n通过配置文件或启动参数指定使用的 LLM 提供商：\n\n```yaml\nllm:\n provider: \"anthropic\" # anthropic | openai | google\n model: \"claude-sonnet-4-20250514\"\n maxTokens: 8192\n```\n\n## 错误处理\n\n### 错误类型分类\n\n| 错误类型 | HTTP 状态码 | 处理方式 |\n|----------|-------------|----------|\n| 认证错误 | 401, 403 | 直接抛出，不重试 |\n| 限流错误 | 429 | 指数退避重试 |\n| 服务器错误 | 500, 502, 503 | 指数退避重试 |\n| 网络错误 | - | 指数退避重试 |\n| 超时错误 | - | 指数退避重试 |\n\n### 错误响应格式\n\n```typescript\ninterface LLMError {\n provider: string; // 提供商名称\n code: string; // 错误代码\n message: string; // 错误描述\n retryable: boolean; // 是否可重试\n originalError?: Error; // 原始错误对象\n}\n```\n\n## 扩展新的提供商\n\n如需添加新的 LLM 提供商，需完成以下步骤：\n\n1. **创建提供商文件**：在 `providers/` 下创建 `newprovider.ts`\n2. **实现 Provider 接口**：实现统一的调用方法\n3. **注册到工厂**：在 `index.ts` 中添加新提供商\n4. **添加配置支持**：更新配置解析逻辑\n5. **编写测试用例**：确保错误处理和响应解析正确\n\n```typescript\n// 实现示例\nexport class NewProvider implements LLMProvider {\n constructor(config: ProviderConfig) { /* ... */ }\n async complete(request: LLMRequest): Promise { /* ... */ }\n async stream(request: LLMRequest): AsyncIterable { /* ... */ }\n}\n```\n\n## 最佳实践\n\n### 生产环境建议\n\n- **使用环境变量**：不要在代码中硬编码 API 密钥\n- **配置重试策略**：根据提供商限流调整重试参数\n- **监控 token 使用**：避免意外超支\n- **设置超时限制**：防止长时间阻塞\n\n### 开发调试建议\n\n- **使用本地模拟**：开发时可用 mock 提供商\n- **启用详细日志**：便于追踪请求/响应\n- **测试边界情况**：验证 token 限制和错误处理\n\n---\n\n\n\n## 工具系统\n\n### 相关页面\n\n相关主题：[Agent核心系统](#agent-system), [LLM提供商集成](#llm-providers), [版本控制系统](#version-control)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agent/infra/tools/types.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/types.ts)\n- [src/agent/infra/tools/tool-registry.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/tool-registry.ts)\n- [src/agent/infra/tools/tool-manager.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/tool-manager.ts)\n- [src/agent/infra/tools/core-tool-scheduler.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/core-tool-scheduler.ts)\n- [src/agent/infra/tools/implementations/read-file-tool.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/implementations/read-file-tool.ts)\n- [src/agent/infra/tools/implementations/write-file-tool.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/implementations/write-file-tool.ts)\n- [src/agent/infra/tools/implementations/code-exec-tool.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/implementations/code-exec-tool.ts)\n- [src/agent/resources/tools](https://github.com/campfirein/byterover-cli/blob/main/src/agent/resources/tools)\n \n\n# 工具系统\n\n## 概述\n\nByteRover CLI 的工具系统是 AI 代理与代码库交互的核心桥梁。该系统提供了一套标准化的工具接口，使 AI 代理能够执行文件操作、代码执行、知识管理等多种任务。通过统一的工具注册、调度和执行机制，实现了工具的模块化管理和安全验证。资料来源：[src/agent/infra/tools/tool-registry.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/tool-registry.ts)\n\n## 核心架构\n\n工具系统采用分层架构设计，包含以下核心组件：\n\n### 组件层级\n\n```mermaid\ngraph TD\n A[AI 代理层] --> B[工具管理器 ToolManager]\n B --> C[工具注册表 ToolRegistry]\n C --> D[核心工具调度器 CoreToolScheduler]\n D --> E[具体工具实现]\n \n E --> E1[ReadFileTool]\n E --> E2[WriteFileTool]\n E --> E3[CodeExecTool]\n E --> E4[CurateTool]\n \n F[命令验证器 CommandValidator] --> B\n G[沙箱服务 CurateService] --> E4\n```\n\n### 核心组件表\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| ToolRegistry | `src/agent/infra/tools/tool-registry.ts` | 工具注册、查找、生命周期管理 |\n| ToolManager | `src/agent/infra/tools/tool-manager.ts` | 工具调度、参数验证、执行协调 |\n| CoreToolScheduler | `src/agent/infra/tools/core-tool-scheduler.ts` | 异步任务队列、并发控制 |\n| CommandValidator | `src/agent/infra/process/command-validator.ts` | 命令安全验证、危险模式检测 |\n\n资料来源：[src/agent/infra/tools/tool-manager.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/tool-manager.ts)\n\n## 工具类型体系\n\n### 类型定义\n\n工具系统定义了丰富的类型体系来规范工具的结构和行为。工具必须实现标准接口，包含名称、描述、参数模式和执行逻辑。资料来源：[src/agent/infra/tools/types.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/types.ts)\n\n### 核心工具实现\n\n#### ReadFileTool（读取文件工具）\n\n提供文件系统读取能力，支持以下功能：\n\n- 单文件读取，返回文件内容和元数据\n- 支持行数限制和截断检测\n- 文件路径验证和访问控制\n\n```typescript\n// 读取文件工具的典型调用模式\nawait tools.readFile('path/to/file.txt')\n// 返回: { content: string, lines: number, truncated: boolean }\n```\n\n资料来源：[src/agent/infra/tools/implementations/read-file-tool.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/implementations/read-file-tool.ts)\n\n#### WriteFileTool（写入文件工具）\n\n提供文件系统写入能力，支持：\n\n- 新建文件内容\n- 更新现有文件\n- 批量文件操作\n\n#### CodeExecTool（代码执行工具）\n\n在沙箱环境中执行代码，具备以下特性：\n\n- 支持多种编程语言的代码执行\n- 内置文件系统操作工具（readFile、grep）\n- 与 curate 服务集成进行知识管理\n- 批处理模式（每次处理 5-10 个文件）\n\n```typescript\n// 代码执行工具中的工具调用\nconst fileContent = await tools.readFile('path/to/file')\nconst matches = await tools.grep(']*path=\".*README.*\">', { path: tmpFilePath })\nawait tools.curate([{ type: 'ADD', path: 'overview', data: { concept: '...' } }])\n```\n\n资料来源：[src/agent/infra/tools/implementations/code-exec-tool.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/implementations/code-exec-tool.ts)\n\n## 工具执行流程\n\n### 执行状态机\n\n工具执行过程中会经历多种状态，TUI 组件通过状态渲染不同的视觉效果：\n\n```mermaid\nstateDiagram-v2\n [*] --> pending: 任务创建\n pending --> running: 开始执行\n running --> completed: 执行成功\n running --> failed: 执行失败\n completed --> [*]\n failed --> [*]\n```\n\n### TUI 状态显示\n\n在执行视图中，不同状态对应不同的显示效果：\n\n| 状态 | 显示样式 | 符号 |\n|------|----------|------|\n| pending | 默认灰色 | `○` |\n| running | 闪烁动画 | `◐` |\n| completed | 绿色高亮 | `✓` |\n| failed | 红色高亮 | `✗` |\n\n资料来源：[src/tui/components/execution/execution-tool.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/tui/components/execution/execution-tool.tsx)\n\n### 执行日志视图\n\n执行日志组件（ExpandedLogView）负责渲染工具调用结果：\n\n```mermaid\ngraph LR\n A[日志数据] --> B{running?}\n B -->|是| C[显示流式内容]\n B -->|否| D{completed?}\n D -->|是| E[显示更改]\n D -->|否| F[显示错误]\n```\n\n组件支持以下渲染内容：\n\n- 工具调用参数和名称\n- 流式文本内容（带光标动画）\n- 完整执行结果\n- 文件变更摘要（创建/更新）\n\n资料来源：[src/tui/components/execution/expanded-log-view.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/tui/components/execution/expanded-log-view.tsx)\n\n## 命令验证与安全\n\n### 安全验证机制\n\nCommandValidator 组件负责验证命令的安全性，支持多层级的安全控制：\n\n```typescript\n// 只读命令白名单\nconst readOnlyCommands = [\n /git\\s+(status|log|diff|show|branch|tag|fetch|pull)(?!\\s+-)/i,\n /cat\\s+.*>/,\n /find\\s+.*>/,\n]\n```\n\n### 验证规则\n\n| 验证类型 | 说明 | 配置来源 |\n|----------|------|----------|\n| 危险模式检测 | 检测 rm -rf 等危险命令 | blockedCommands |\n| 白名单验证 | 允许的命令列表 | allowedCommands |\n| 安全级别 | 控制验证严格程度 | securityLevel |\n| 路径提取 | 验证文件路径安全性 | extractPathArguments |\n\n资料来源：[src/agent/infra/process/command-validator.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/process/command-validator.ts)\n\n## 工具资源定义\n\n### 工具描述格式\n\n工具通过 Markdown 格式定义，存储在 `src/agent/resources/tools` 目录。标准格式包含：\n\n- 工具名称和描述\n- 参数说明（名称、类型、必填、默认值）\n- 使用示例\n- 返回值格式\n\n### 工具模板结构\n\n```markdown\n## 工具名称\n\n描述工具用途和功能\n\n### 参数\n| 参数名 | 类型 | 必填 | 默认值 | 说明 |\n\n### 示例\n```bash\n工具调用示例\n```\n\n### 返回值\n返回数据格式说明\n```\n\n资料来源：[src/agent/resources/tools](https://github.com/campfirein/byterover-cli/blob/main/src/agent/resources/tools)\n\n## 异步调度机制\n\n### 核心调度器\n\nCoreToolScheduler 负责管理工具执行的异步队列：\n\n- 并发任务数量控制\n- 任务优先级管理\n- 执行结果回调\n- 错误处理和重试机制\n\n### 调度配置\n\n| 配置项 | 说明 | 默认值 |\n|--------|------|--------|\n| maxConcurrency | 最大并发数 | 3 |\n| timeout | 单任务超时 | 30000ms |\n| retryCount | 失败重试次数 | 2 |\n\n资料来源：[src/agent/infra/tools/core-tool-scheduler.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/core-tool-scheduler.ts)\n\n## 工具管理服务\n\n### CurateService 集成\n\nCurateService 为代码执行工具提供知识管理能力：\n\n- 添加、更新、删除知识条目\n- 批量操作支持（最多 5 个文件）\n- 域检测和自动分类\n- 标题和内容验证\n\n```typescript\n// curate 操作类型\ntype CurateOperation = {\n type: 'ADD' | 'UPDATE' | 'DELETE' | 'UPSERT'\n path: string\n title?: string\n content?: {\n rawConcept?: string\n narrative?: string\n }\n}\n```\n\n资料来源：[src/agent/infra/sandbox/curate-service.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/sandbox/curate-service.ts)\n\n## 最佳实践\n\n### 工具使用建议\n\n1. **批量处理**：使用 code-exec-tool 时，每次处理 5-10 个文件以控制输出大小\n2. **路径验证**：所有文件操作前验证路径在项目目录内\n3. **错误处理**：检查 truncated 标志以处理大文件截断\n4. **安全优先**：使用命令验证器过滤危险操作\n\n### 性能优化\n\n| 场景 | 优化策略 |\n|------|----------|\n| 大文件读取 | 使用行数限制和截断检测 |\n| 批量搜索 | 使用 grep 替代多次 readFile |\n| 并发控制 | 调整 CoreToolScheduler 的 maxConcurrency |\n\n### 调试技巧\n\n- 使用 TUI 的 expanded-log-view 查看详细执行日志\n- 检查 toolCalls 数组追踪工具调用链\n- 监控 streamingContent 观察实时输出\n\n---\n\n\n\n## 上下文树与知识管理\n\n### 相关页面\n\n相关主题：[Agent核心系统](#agent-system), [版本控制系统](#version-control), [Swarm多代理协调](#swarm-coordination)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agent/infra/map/abstract-generator.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/map/abstract-generator.ts)\n- [src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts)\n- [src/agent/resources/prompts/curate-detail-preservation.yml](https://github.com/campfirein/byterover-cli/blob/main/src/agent/resources/prompts/curate-detail-preservation.yml)\n- [src/agent/infra/sandbox/curate-service.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/sandbox/curate-service.ts)\n- [src/server/templates/README.md](https://github.com/campfirein/byterover-cli/blob/main/src/server/templates/README.md)\n \n\n# 上下文树与知识管理\n\n## 概述\n\n上下文树（Context Tree）是 ByteRover CLI 中的核心知识管理基础设施，用于组织和持久化 AI Agent 在项目开发过程中积累的结构化知识。通过上下文树，系统能够将分散的代码模式、设计决策、项目约定等内容转化为可查询、可复用的知识资产。\n\n上下文树位于项目根目录的 `.brv/context-tree/` 路径下，采用分层目录结构组织知识内容，支持动态域名创建和自动摘要生成。\n\n## 架构设计\n\n### 核心组件\n\n| 组件 | 职责 | 文件位置 |\n|------|------|----------|\n| ContextTreeStore | 上下文树数据存储与检索 | `src/agent/infra/map/context-tree-store.ts` |\n| AbstractGenerator | 知识摘要生成服务 | `src/agent/infra/map/abstract-generator.ts` |\n| CurateService | 知识整理操作执行器 | `src/agent/infra/sandbox/curate-service.ts` |\n| ContextTreeContributor | 系统提示词上下文注入 | `src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts` |\n\n### 数据流架构\n\n```mermaid\ngraph TD\n A[AI Agent 执行任务] --> B[Curate 操作请求]\n B --> C[CurateService 验证]\n C --> D{验证结果}\n D -->|失败| E[返回失败详情]\n D -->|成功| F[写入 ContextTreeStore]\n F --> G[生成摘要 AbstractGenerator]\n G --> H[更新系统提示词]\n H --> I[ContextTreeContributor 注入结构]\n I --> J[Agent 下次交互使用知识]\n```\n\n## 目录结构规范\n\n上下文树采用固定的目录层次结构组织知识内容：\n\n```\n.brv/context-tree/\n├── _index.md # 根级自动生成摘要\n├── architecture/ # 动态域名：架构相关知识\n│ ├── _index.md # 目录摘要\n│ ├── system_design.md\n│ └── api_patterns.md\n├── patterns/ # 代码模式与最佳实践\n│ ├── _index.md\n│ └── authentication.md\n├── conventions/ # 团队约定与规范\n│ ├── _index.md\n│ └── git_workflow.md\n└── _archived/ # 归档的低优先级知识\n └── old_notes.md\n```\n\n### 结构规范说明\n\n| 结构元素 | 说明 | 创建规则 |\n|----------|------|----------|\n| 顶级文件夹 | 代表知识领域（Domain） | 根据内容语义动态创建 |\n| `.md` 文件 | 单个知识主题（Topic） | 包含具体知识内容 |\n| `context.md` | 目录级知识入口 | 子文件夹可包含此文件定义目录级上下文 |\n| `_index.md` | 自动生成的目录摘要 | 系统自动维护 |\n| `_archived/` | 归档存储 | 存放低重要性条目 |\n\n资料来源：[src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts:27-35]()\n\n## Curate 操作类型\n\nCurateService 实现了四种核心知识操作类型，用于管理系统中的知识条目：\n\n| 操作类型 | 说明 | 必需字段 |\n|----------|------|----------|\n| ADD | 添加新的知识条目 | title, content |\n| UPDATE | 更新现有条目内容 | title, content |\n| UPSERT | 存在则更新，不存在则添加 | title, content |\n| DELETE | 删除指定条目 | path |\n| MOVE | 移动条目到新位置 | from, to |\n\n### 操作验证规则\n\n```typescript\n// ADD、UPDATE、UPSERT 必须包含 content\nif ((op.type === 'ADD' || op.type === 'UPDATE' || op.type === 'UPSERT') && !op.content) {\n failures.push({\n message: `${op.type} operation requires content with rawConcept and/or narrative.`,\n path: op.path,\n status: 'failed',\n type: op.type,\n })\n}\n\n// ADD、UPDATE、UPSERT 必须包含 title（作为 .md 文件名）\nif ((op.type === 'ADD' || op.type === 'UPDATE' || op.type === 'UPSERT') && !op.title) {\n failures.push({\n message: `${op.type} operation requires a title (becomes the .md filename).`,\n path: op.path,\n status: 'failed',\n type: op.type,\n })\n}\n```\n\n资料来源：[src/agent/infra/sandbox/curate-service.ts:14-35]()\n\n## 知识内容结构\n\n### 知识条目数据模型\n\n每个知识条目（Topic）包含以下结构化字段：\n\n```typescript\ninterface KnowledgeEntry {\n path: string; // 条目路径\n title: string; // 标题（决定文件名）\n content: {\n rawConcept: string; // 原始概念定义\n facts: Fact[]; // 提取的事实清单\n };\n narrative: {\n rules?: string[]; // 规则与约束\n highlights?: string[]; // 重点与亮点\n structure?: string; // 结构说明\n examples?: string[]; // 示例列表\n flow?: string; // 工作流程\n diagrams?: Diagram[]; // 图表引用\n dependencies?: string[]; // 依赖关系\n };\n metadata: {\n tags: string[];\n category: string;\n createdAt: string;\n updatedAt: string;\n };\n}\n```\n\n### 图表类型支持\n\n```typescript\ninterface Diagram {\n type: 'mermaid' | 'plantuml' | 'ascii' | 'other';\n title?: string;\n content: string;\n}\n```\n\n资料来源：[src/agent/resources/prompts/curate-detail-preservation.yml:1-40]()\n\n## 摘要生成系统\n\n### AbstractGenerator 工作流程\n\nAbstractGenerator 负责从批量知识文件中生成结构化摘要，使用 XML 格式输出：\n\n```mermaid\ngraph LR\n A[输入文件列表] --> B[生成 XML 格式]\n B --> C[构建 LLM Prompt]\n C --> D[模型生成概述]\n D --> E[解析 XML 响应]\n E --> F[提取 或 ]\n F --> G[返回 Map]\n```\n\n### 输出格式规范\n\n```xml\n\n\n- bullet 1\n- bullet 2\n...\n\n\n```\n\n### 解析实现要点\n\n解析器采用锚定于 `` 开启标签的策略，避免内容中包含 `` 时导致匹配错误：\n\n```typescript\nfunction parseBatchedTags(response: string, innerTag: 'abstract' | 'overview'): Map {\n // 每个 opener 拥有到下一个 opener（或字符串结尾）的响应片段\n // 内部正则表达式从该片段中提取有效载荷\n}\n```\n\n资料来源：[src/agent/infra/map/abstract-generator.ts:20-60]()\n\n## 知识保存与提取\n\n### 事实提取规范\n\n知识内容中的事实必须按类别精确提取：\n\n| 类别 | 说明 | 示例 |\n|------|------|------|\n| personal | 用户个人信息 | \"我的名字是 Andy\" |\n| project | 项目配置值 | 端口号、URL、版本号 |\n| convention | 团队约定与流程 | Git 工作流规范 |\n\n### 非代码内容保存\n\n| 内容类型 | 保存位置 | 说明 |\n|----------|----------|------|\n| 会议决策与理由 | `narrative.rules` / `narrative.highlights` | 必须保留完整决策过程 |\n| 操作项与截止日期 | `narrative.examples` | 包含负责人和期限 |\n| 投票结果与优先级 | `narrative.highlights` | 保留精确数值 |\n| 状态更新与阻塞项 | `narrative.dependencies` | 记录当前障碍 |\n| 工作流步骤 | `rawConcept.flow` | 包含所有条件判断 |\n| 指标与 KPI | `narrative.highlights` | 保留精确值 |\n\n资料来源：[src/agent/resources/prompts/curate-detail-preservation.yml:40-80]()\n\n## 系统提示词集成\n\nContextTreeContributor 负责将上下文树结构注入到 Agent 的系统提示词中：\n\n```mermaid\ngraph TD\n A[加载 ContextTreeStore] --> B[获取目录结构]\n B --> C{条目数量}\n C -->|< 阈值| D[显示完整结构]\n C -->|>= 阈值| E[截断并显示计数]\n D --> F[构建结构说明]\n E --> F\n F --> G[注入系统提示词]\n```\n\n### 动态域名说明\n\n```typescript\n// 构建结构指南\n'## Structure Guide',\n'- Each top-level folder is a **domain** (dynamically created based on content)',\n'- Inside domains are **topics** as `.md` files or subfolders with `context.md`',\n\n// 动态域名规则\n'## Dynamic Domains',\n'- Domains are created dynamically based on the semantics of curated content',\n'- Domain names should be descriptive, use snake_case',\n'- Before creating a new domain, check if existing domains could accommodate the content'\n```\n\n### 截断机制\n\n当条目数量超过显示阈值时，系统会截断输出并显示剩余数量：\n\n```\n.brv/context-tree/\n architecture/\n patterns/\n conventions/\n [5 additional entries not shown]\n```\n\n资料来源：[src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts:1-80]()\n\n## 知识查询与使用\n\n### 查询命令\n\nAgent 通过上下文树结构查询相关知识：\n\n| 命令类型 | 说明 | 查询范围 |\n|----------|------|----------|\n| Query | 检索相关知识条目 | 仅在上下文树结构内搜索 |\n| Expand | 展开归档知识 | 可深入 `_archived/` 目录 |\n\n### 使用建议\n\n1. **创建新条目前**：先检查现有域名是否可容纳新内容\n2. **域名命名**：使用 snake_case 格式，描述性强（如 `architecture`、`market_trends`）\n3. **知识归档**：低优先级条目可移至 `_archived/`，使用 `expand_knowledge` 命令可展开查看\n\n## 最佳实践\n\n### 知识组织原则\n\n1. **单一职责**：每个主题文件专注于一个知识领域\n2. **语义化分类**：根据内容语义选择合适的域名，而非机械分类\n3. **摘要更新**：修改知识后及时更新相关 `_index.md` 摘要\n4. **事实优先**：关键数值、配置、约定应提取为 facts 便于快速引用\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| `src/agent/infra/map/context-tree-store.ts` | 上下文树数据存储实现 |\n| `src/agent/infra/map/abstract-generator.ts` | 知识摘要生成器 |\n| `src/agent/infra/sandbox/curate-service.ts` | Curate 操作服务 |\n| `src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts` | 系统提示词注入 |\n| `src/agent/resources/prompts/curate-detail-preservation.yml` | 内容保存规范 |\n\n---\n\n\n\n## 版本控制系统\n\n### 相关页面\n\n相关主题：[上下文树与知识管理](#context-tree)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/shared/transport/events/vc-events.ts](https://github.com/campfirein/byterover-cli/blob/main/src/shared/transport/events/vc-events.ts)\n- [src/server/templates/skill/SKILL.md](https://github.com/campfirein/byterover-cli/blob/main/src/server/templates/skill/SKILL.md)\n- [src/server/infra/http/review-ui.ts](https://github.com/campfirein/byterover-cli/blob/main/src/server/infra/http/review-ui.ts)\n- [src/agent/infra/map/abstract-generator.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/map/abstract-generator.ts)\n- [src/agent/infra/sandbox/curate-service.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/sandbox/curate-service.ts)\n- [src/tui/features/hub/components/hub-detail-step.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/tui/features/hub/components/hub-detail-step.tsx)\n \n\n# 版本控制系统\n\n## 概述\n\nByteRover CLI 的版本控制系统（Version Control System，简称 VC）是该项目提供的核心功能之一。该系统通过 `brv vc` 命令族为 AI 编码代理提供持久化的上下文记忆能力，支持本地文件变更追踪、云端同步以及团队协作。\n\n版本控制系统的设计目标是让 AI 代理能够在项目目录中追踪和管理文件变更，同时与 ByteRover 云服务协同工作，实现知识的持久化和跨工具共享。\n\n## 核心架构\n\n### 类型定义体系\n\n版本控制系统的类型定义集中于 `src/shared/transport/events/vc-events.ts` 文件中，定义了完整的 diff 操作类型体系：\n\n```typescript\n// 资料来源：src/shared/transport/events/vc-events.ts\nexport type VcDiffMode =\n | {from: string; kind: 'range'; to: string}\n | {kind: 'ref-vs-worktree'; ref: string}\n | {kind: 'staged'}\n | {kind: 'unstaged'}\n\nexport type VcDiffFileStatus = 'added' | 'deleted' | 'modified'\n\nexport interface IVcDiffFile {\n binary?: boolean\n newContent: string\n newOid: string\n oldContent: string\n oldOid: string\n path: string\n status: VcDiffFileStatus\n}\n```\n\n### Diff 模式分类\n\n系统支持四种差异模式，与 Git 原生命令保持一致：\n\n| 模式名称 | 描述 | 对应 Git 命令 |\n|---------|------|--------------|\n| `unstaged` | 工作目录与暂存区对比（仅追踪文件） | `git diff` |\n| `staged` | 暂存区与 HEAD 对比 | `git diff --staged` |\n| `ref-vs-worktree` | 指定提交/分支与工作目录对比 | `git diff [` |\n| `range` | 两个引用之间的差异 | `git diff ..` |\n\n```mermaid\ngraph TD\n A[版本控制系统] --> B[Diff 操作]\n B --> C{模式选择}\n C -->|unstaged| D[WORKDIR → STAGE]\n C -->|staged| E[HEAD → STAGE]\n C -->|ref-vs-worktree| F[ref → WORKDIR]\n C -->|range| G[ref1 → ref2]\n \n H[IVcDiffFile] --> I[status: added/deleted/modified]\n H --> J[newOid/oldOid]\n H --> K[newContent/oldContent]\n H --> L[binary flag]\n```\n\n## 命令体系\n\n### 命令分类总览\n\n`brv vc` 命令提供完整的版本控制操作能力，文档位于 `src/server/templates/skill/SKILL.md`：\n\n| 命令 | 功能描述 |\n|------|---------|\n| `brv vc add` | 暂存文件变更 |\n| `brv vc commit` | 提交暂存区变更 |\n| `brv vc log` | 查看提交历史 |\n| `brv vc reset` | 取消暂存或撤销提交 |\n| `brv vc branch` | 分支管理 |\n| `brv vc checkout` | 切换分支 |\n| `brv vc merge` | 合并分支 |\n| `brv vc remote` | 远程仓库操作 |\n\n### 文件操作命令\n\n#### 暂存文件 (`brv vc add`)\n\n```bash\nbrv vc add . # 暂存所有文件\nbrv vc add notes.md docs/ # 暂存指定文件\n```\n\n暂存操作会将工作目录中的变更移动到暂存区，为提交做准备。\n\n#### 查看历史 (`brv vc log`)\n\n```bash\nbrv vc log # 查看最近提交\nbrv vc log --limit 20 # 限制显示数量\nbrv vc log --all # 查看所有分支历史\n```\n\n#### 重置操作 (`brv vc reset`)\n\n| 命令 | 行为 |\n|------|------|\n| `brv vc reset` | 取消所有文件暂存 |\n| `brv vc reset ` | 取消指定文件暂存 |\n| `brv vc reset --soft HEAD~1` | 撤销上次提交，保留变更在暂存区 |\n| `brv vc reset --hard HEAD~1` | 撤销上次提交并丢弃所有变更 |\n\n### 分支管理\n\n#### 分支操作\n\n```bash\nbrv vc branch # 列出本地分支\nbrv vc branch feature/auth # 创建新分支\nbrv vc branch -a # 列出所有分支（含远程追踪分支）\nbrv vc branch -d feature/auth # 删除分支\n```\n\n#### 切换分支\n\n```bash\nbrv vc checkout feature/auth # 切换到现有分支\nbrv vc checkout -b feature/new # 创建并切换到新分支\n```\n\n#### 合并操作\n\n```bash\nbrv vc merge feature/auth # 将目标分支合并到当前分支\nbrv vc merge --continue # 解决冲突后继续合并\nbrv vc merge --abort # 中止合并操作\n```\n\n#### 设置上游追踪\n\n```bash\nbrv vc branch --set-upstream-to origin/main\n```\n\n```mermaid\ngraph LR\n A[brv vc branch] --> B[create]\n A --> C[list]\n A --> D[delete]\n A --> E[set-upstream]\n \n F[brv vc checkout] --> G[switch]\n F --> H[create-and-switch]\n \n I[brv vc merge] --> J[normal]\n I --> K[continue]\n I --> L[abort]\n```\n\n### 云端同步\n\n版本控制系统支持与 ByteRover 云服务同步，需要先完成身份认证和远程仓库配置：\n\n```bash\nbrv login # ByteRover 身份认证\nbrv vc remote # 查看当前远程仓库\nbrv vc remote add origin # 添加远程仓库\n```\n\n云同步功能允许用户将本地版本控制状态与云端保持一致，实现跨设备和团队协作。\n\n## 评审界面集成\n\nByteRover 提供本地 HITL（Human-in-the-Loop）评审界面，集成于 `src/server/infra/http/review-ui.ts`：\n\n### 评审页面架构\n\n评审界面使用自包含的 HTML/CSS/JS 实现，支持变更的语义化摘要展示：\n\n```typescript\n// 资料来源：src/server/infra/http/review-ui.ts\nexport function getReviewPageHtml(): string {\n return `\n\n\n\n\nByteRover Review\n\n\n\n \n\n`\n}\n```\n\n### 文件卡片渲染\n\n评审界面为每个变更文件生成卡片，包含操作类型徽章和操作按钮：\n\n```typescript\n// 资料来源：src/server/infra/http/review-ui.ts\nfunction renderFileCard(file, index) {\n const opBadges = file.operations.map(op =>\n '' + op.type + ''\n ).join('');\n \n return ']'\n + ''\n + '
';\n}\n```\n\n### 评审操作按钮\n\n| 按钮 | 功能 |\n|------|------|\n| Approve | 批准变更 |\n| Reject | 拒绝变更 |\n\n## 抽象生成与摘要\n\n版本控制系统与知识管理模块集成，通过抽象生成队列处理文档摘要：\n\n```typescript\n// 资料来源：src/agent/infra/sandbox/curate-service.ts\nexport class CurateService implements ICurateService {\n async curate(operations: CurateOperation[], options?: CurateOptions): Promise {\n const rawBasePath = options?.basePath ?? DEFAULT_BASE_PATH\n // 处理整理操作...\n }\n}\n```\n\n### 摘要生成提示词\n\n系统使用专门的提示词模板生成文件摘要，支持单行摘要和结构化概览两种模式：\n\n```typescript\n// 资料来源：src/agent/infra/map/abstract-generator.ts\nfunction buildBatchedAbstractPrompt(items) {\n return `For each of the following knowledge documents, produce a ONE-LINE summary (max 80 tokens)\nOutput format — emit exactly one element per input file:\n\">One-line summary.`\n}\n\nfunction buildBatchedOverviewPrompt(items) {\n return `For each of the following knowledge documents, produce a structured overview (markdown, under 1500 tokens) that includes:\n- Key points (3-7 bullet points)\n- Structure / sections summary\n- Any notable entities, patterns, or decisions mentioned`\n}\n```\n\n### CDATA 封装\n\n为防止 XML 解析冲突，文档内容使用 CDATA 段封装：\n\n```typescript\n// 资料来源：src/agent/infra/map/abstract-generator.ts\nfunction wrapCdata(content: string): string {\n return `', ']]]]>')}]]>`\n}\n```\n\n## 数据结构\n\n### 版本控制 Diff 文件结构\n\n```typescript\ninterface IVcDiffFile {\n /** 二进制文件标志（任一端包含 NUL 字节时为 true） */\n binary?: boolean\n /** 新版本内容 */\n newContent: string\n /** 7 位短 OID，新增文件时省略 */\n newOid: string\n /** 旧版本内容 */\n oldContent: string\n /** 删除文件时省略 */\n oldOid: string\n /** 文件路径 */\n path: string\n /** 变更类型 */\n status: VcDiffFileStatus\n}\n```\n\n### Diff 端定义\n\n```typescript\n// 资料来源：src/shared/transport/events/vc-events.ts\ninterface VcDiffSide {\n oid: string\n content: string\n}\n```\n\n## 总结\n\nByteRover CLI 的版本控制系统是一个完整的功能模块，它：\n\n1. **提供命令行接口**：通过 `brv vc` 命令族提供 Git 风格的操作体验\n2. **支持多种 Diff 模式**：兼容 unstaged、staged、ref-vs-worktree、range 四种模式\n3. **集成评审流程**：提供内置的 HITL 评审界面\n4. **支持云端同步**：与 ByteRover 云服务集成实现协作\n5. **与知识管理协同**：与上下文树和知识整理系统深度集成\n\n该系统专为 AI 编码代理设计，使其能够像人类开发者一样有效地管理和追踪项目变更。\n\n---\n\n\n\n## Swarm多代理协调\n\n### 相关页面\n\n相关主题：[上下文树与知识管理](#context-tree), [Agent核心系统](#agent-system)\n\n# Swarm多代理协调\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/agent/core/domain/swarm/types.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/core/domain/swarm/types.ts)\n- [src/agent/infra/swarm/swarm-coordinator.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/swarm/swarm-coordinator.ts)\n- [src/agent/infra/swarm/swarm-router.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/swarm/swarm-router.ts)\n- [src/agent/infra/swarm/adapters/byterover-adapter.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/swarm/adapters/byterover-adapter.ts)\n- [src/agent/infra/swarm/wizard/swarm-wizard.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/swarm/wizard/swarm-wizard.ts)\n- [src/oclif/commands/swarm/query.ts](https://github.com/campfirein/byterover-cli/blob/main/src/oclif/commands/swarm/query.ts)\n \n\n## 概述\n\nSwarm（多代理协调系统）是ByteRover CLI中的一个核心模块，旨在实现跨多个记忆提供商的智能协调与信息检索。该系统通过统一的查询和整理接口，将ByteRover上下文树、Obsidian保险库、GBrain、本地Markdown文件夹以及Memory Wiki等多个记忆源进行整合，为用户提供无缝的知识访问体验。\n\nSwarm的核心设计理念是**多提供者并行查询**与**智能结果融合**。当用户配置了多个记忆提供者时，Swarm能够同时向所有可用提供者发起查询请求，并通过RRF（Reciprocal Rank Fusion，倒数排名融合）算法对结果进行排序和去重，最终返回最优的检索结果。资料来源：[src/server/templates/skill/SKILL.md]()\n\n## 核心架构\n\n### 系统组件\n\nSwarm多代理协调系统由以下几个核心组件构成：\n\n| 组件 | 职责 | 文件位置 |\n|------|------|----------|\n| SwarmCoordinator | 协调多个提供者的查询与整理操作 | `src/agent/infra/swarm/swarm-coordinator.ts` |\n| SwarmRouter | 根据内容类型和配置路由请求到合适的提供者 | `src/agent/infra/swarm/swarm-router.ts` |\n| ByteoverAdapter | ByteRover上下文树适配器 | `src/agent/infra/swarm/adapters/byterover-adapter.ts` |\n| SwarmWizard | 引导用户配置Swarm设置 | `src/agent/infra/swarm/wizard/swarm-wizard.ts` |\n| SwarmConfigLoader | 加载和验证Swarm配置文件 | `src/agent/infra/swarm/config/swarm-config-loader.ts` |\n\n### 数据流架构\n\n```mermaid\ngraph TD\n User[用户请求] --> CLI[brv swarm query/curate]\n CLI --> Coordinator[SwarmCoordinator]\n Coordinator --> Router[SwarmRouter]\n Router --> Providers[多个记忆提供者]\n \n Providers --> ByteRover[ByteRover上下文树]\n Providers --> Obsidian[Obsidian保险库]\n Providers --> GBrain[GBrain实体库]\n Providers --> LocalMD[本地Markdown]\n Providers --> MemWiki[Memory Wiki]\n \n Providers --> RRF[RRF结果融合]\n RRF --> Filter[精确度过滤]\n Filter --> Result[最终结果]\n \n subgraph 配置层\n Config[.brv/swarm/config.yaml]\n ConfigLoader[SwarmConfigLoader]\n end\n \n ConfigLoader --> Config\n Coordinator -.依赖.-> ConfigLoader\n```\n\n## 记忆提供者\n\nSwarm支持五种类型的记忆提供者，每种提供者都有其特定的用途和配置方式。\n\n### 提供者类型\n\n| 提供者 | 类型标识 | 用途 | 可写 |\n|--------|----------|------|------|\n| ByteRover | `byterover` | 上下文树主存储 | 是 |\n| Obsidian | `obsidian` | Markdown笔记Vault | 可配置 |\n| GBrain | `gbrain` | 实体概念存储 | 可配置 |\n| Local Markdown | `local-markdown` | 本地文件夹笔记 | 可配置 |\n| Memory Wiki | `memory-wiki` | Wiki格式知识库 | 可配置 |\n\n### 提供者配置\n\n每个提供者在Swarm配置中都有以下可配置属性：\n\n```yaml\nproviders:\n byterover:\n enabled: true\n type: memory-tree\n obsidian:\n enabled: true\n path: /Users/you/Documents/MyObsidian\n type: vault\n gbrain:\n enabled: true\n path: /Users/you/workspaces/gbrain\n type: entity-store\n memory-wiki:\n enabled: true\n path: /Users/you/.openclaw/wiki/main\n type: wiki\n```\n\n资料来源：[src/server/templates/skill/SKILL.md]()\n\n## Swarm配置系统\n\n### 配置文件加载\n\nSwarm配置存储在项目根目录的`.brv/swarm/config.yaml`文件中。配置加载器负责读取、解析和验证配置。\n\n配置加载流程：\n\n1. 读取`.brv/swarm/config.yaml`文件\n2. 解析YAML内容\n3. 解析环境变量引用（`${VAR}`格式）\n4. 通过Zod Schema进行验证\n5. 返回类型安全的SwarmConfig对象\n\n```typescript\nexport async function loadSwarmConfig(\n projectRoot: string,\n env?: Record\n): Promise\n```\n\n如果配置文件不存在，抛出错误提示用户运行`brv swarm onboard`命令创建配置。资料来源：[src/agent/infra/swarm/config/swarm-config-loader.ts]()\n\n### 配置验证\n\n配置验证确保Swarm设置的完整性和正确性。验证内容包括：\n\n- 提供者路径有效性\n- 提供者类型识别\n- 环境变量引用解析\n- Schema类型检查\n\n## 查询操作\n\n### 查询流程\n\nSwarm查询操作通过以下步骤执行：\n\n```mermaid\ngraph LR\n A[查询请求] --> B[分类查询类型]\n B --> C[选择提供者]\n C --> D[并行查询所有提供者]\n D --> E[收集结果]\n E --> F[RRF融合排序]\n F --> G[精确度过滤]\n G --> H[返回结果]\n```\n\n### 查询分类\n\nSwarm能够自动分类查询类型，以优化提供者选择：\n\n| 查询类型 | 特征 | 适用场景 |\n|----------|------|----------|\n| `factual` | 事实性问题 | 具体信息检索 |\n| `semantic` | 语义理解 | 概念和模式识别 |\n| `contextual` | 上下文相关 | 依赖上下文的查询 |\n\n### 查询命令\n\n```bash\n# 基本查询\nbrv swarm query \"authentication patterns\"\n\n# 显示详细信息\nbrv swarm query \"authentication patterns\" --explain\n\n# JSON格式输出\nbrv swarm query \"rate limiting\" --format json\n\n# 限制结果数量\nbrv swarm query \"testing strategy\" -n 5\n```\n\n### 查询输出示例\n\n使用`--explain`标志时，输出包含详细的分类和提供者信息：\n\n```\nClassification: factual\nProvider selection: 4 of 4 available\n ✓ byterover (healthy, selected, 0 results, 14ms)\n ✓ obsidian (healthy, selected, 5 results, 91ms)\n ✓ memory-wiki (healthy, selected, 2 results, 15ms)\n ✓ gbrain (healthy, selected, 1 results, 260ms)\nEnrichment:\n byterover → obsidian\n byterover → memory-wiki\nResults: 8 raw → 7 after RRF fusion + precision filtering\n```\n\n资料来源：[src/server/templates/skill/SKILL.md]()\n\n### JSON输出格式\n\n```json\n{\n \"meta\": {\n \"queryType\": \"factual\",\n \"totalLatencyMs\": 340,\n \"providers\": {\n \"byterover\": { \"selected\": true, \"resultCount\": 0 },\n \"obsidian\": { \"selected\": true, \"resultCount\": 5 },\n \"gbrain\": { \"selected\": true, \"resultCount\": 1 },\n \"memory-wiki\": { \"selected\": true, \"resultCount\": 1 }\n }\n },\n \"results\": [\n { \"provider\": \"memory-wiki\", \"providerType\": \"memory-wiki\", \"score\": 0.015, \"content\": \"# Rate Limiting ...\" }\n ]\n}\n```\n\n## 整理操作\n\n### 整理流程\n\nSwarm整理（Curate）操作用于将知识存储到最合适的外部记忆提供者中。系统自动分类内容类型并路由到对应的提供者。\n\n```mermaid\ngraph TD\n A[整理请求] --> B[分析内容类型]\n B --> C{内容分类}\n \n C -->|实体/人物| D[GBrain]\n C -->|笔记/TODO| E[本地Markdown]\n C -->|通用内容| F[第一个可写提供者]\n C -->|无可用外部| G[ByteRover上下文树]\n \n D --> H[存储完成]\n E --> H\n F --> H\n G --> H\n```\n\n### 路由规则\n\n| 内容类型 | 目标提供者 | 存储格式 |\n|----------|------------|----------|\n| 人物/组织实体 | GBrain | concept/xxx |\n| 会议笔记/TODO | 本地Markdown | note-xxx.md |\n| 通用内容 | 第一个可写提供者 | 提供者特定格式 |\n| 无外部提供者 | ByteRover | context.md |\n\n### 整理命令\n\n```bash\n# 基本整理\nbrv swarm curate \"Jane Smith is the CTO of TechCorp\"\n\n# 指定提供者\nbrv swarm curate \"meeting notes: decided on JWT\" --provider local-markdown:notes\n\n# 存储到GBrain\nbrv swarm curate \"Architecture uses event sourcing\" --provider gbrain\n\n# JSON输出\nbrv swarm curate \"Test content\" --format json\n```\n\n### 整理输出\n\n```\nStored to gbrain as concept/jane-smith-cto\n```\n\n## Swarm状态检查\n\n### 健康检查\n\n在执行查询或整理操作前，建议先检查Swarm状态以验证提供者的可用性。\n\n```bash\nbrv swarm status\n```\n\n### 状态输出示例\n\n```\nMemory Swarm Health Check\n════════════════════════════════════════\n ✓ ByteRover context-tree (always on)\n ✓ Obsidian /Users/you/Documents/MyObsidian\n ✓ Local .md 1 folder(s)\n ✓ GBrain /Users/you/workspaces/gbrain\n ✓ Memory Wiki /Users/you/.openclaw/wiki/main\n\nWrite Targets:\n gbrain (entity, general)\n local-markdown:project-docs (note, general)\n\nSwarm is operational (5/5 providers configured).\n```\n\n资料来源：[src/server/templates/skill/SKILL.md]()\n\n## 命令行接口\n\n### 可用命令\n\n| 命令 | 功能 | 必需参数 |\n|------|------|----------|\n| `brv swarm query` | 跨提供者搜索 | 查询字符串 |\n| `brv swarm curate` | 存储知识到提供者 | 内容字符串 |\n| `brv swarm status` | 检查提供者健康状态 | 无 |\n| `brv swarm onboard` | 初始化Swarm配置 | 无 |\n\n### 全局参数\n\n| 参数 | 描述 | 默认值 |\n|------|------|--------|\n| `--explain` | 显示详细路由信息 | false |\n| `--format json` | JSON格式输出 | false |\n| `-n <数量>` | 限制结果数量 | 全部 |\n| `--provider ` | 指定目标提供者 | 自动选择 |\n\n## 高级配置\n\n### 提供者选择策略\n\nSwarm支持细粒度的提供者选择控制：\n\n```yaml\nswarm:\n query:\n # 查询时使用的提供者\n providers:\n - byterover\n - obsidian\n - gbrain\n - memory-wiki\n # RRF融合参数\n fusion:\n k: 60 # RRF常数，通常为60\n curate:\n # 整理时的默认提供者优先级\n priority:\n - gbrain\n - local-markdown:project-docs\n - memory-wiki\n```\n\n### 环境变量引用\n\n配置文件支持使用`${VAR}`语法引用环境变量：\n\n```yaml\nproviders:\n obsidian:\n path: ${OBSIDIAN_VAULT_PATH}\n gbrain:\n path: ${GBRAIN_WORKSPACE}\n```\n\n资料来源：[src/agent/infra/swarm/config/swarm-config-loader.ts]()\n\n## 最佳实践\n\n### 查询优化\n\n1. **结合使用**：运行`brv swarm query`的同时运行`brv query`，可以扩大召回范围\n2. **使用explain模式**：调试时使用`--explain`了解提供者选择和融合过程\n3. **限制结果数量**：大数据集时使用`-n`参数控制输出\n\n### 整理策略\n\n1. **检查现有结构**：整理前先检查现有域和主题，避免重复创建\n2. **使用精确提供者**：当需要存储到特定提供者时使用`--provider`参数\n3. **利用自动分类**：信任系统的自动路由逻辑，除非有特殊需求\n\n### 配置建议\n\n1. **定期检查状态**：运行`brv swarm status`确保所有提供者健康\n2. **使用onboard初始化**：首次配置使用`brv swarm onboard`引导完成\n3. **验证配置文件**：确保`.brv/swarm/config.yaml`格式正确\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 原因 | 解决方案 |\n|------|------|----------|\n| 查询无结果 | 提供者路径无效 | 检查配置文件，更新路径 |\n| 整理失败 | 提供者不可写 | 检查提供者写权限 |\n| 配置加载错误 | YAML格式错误 | 验证YAML语法 |\n| 提供者不健康 | 路径不存在 | 确认目录存在 |\n\n### 诊断步骤\n\n1. 运行`brv swarm status`检查所有提供者状态\n2. 验证`.brv/swarm/config.yaml`配置正确\n3. 确认各提供者的存储路径存在且可访问\n4. 检查环境变量是否正确设置\n\n## 相关文档\n\n- [上下文树结构说明](./context-tree-structure.md)\n- [Curate服务文档](./curate-service.md)\n- [命令行参考手册](./command-reference.md)\n\n---\n\n\n\n## TUI交互界面\n\n### 相关页面\n\n相关主题：[WebUI管理面板](#webui-dashboard), [Agent核心系统](#agent-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tui/components/execution/execution-tool.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/tui/components/execution/execution-tool.tsx)\n- [src/tui/components/execution/expanded-log-view.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/tui/components/execution/expanded-log-view.tsx)\n- [src/tui/features/hub/components/hub-detail-step.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/tui/features/hub/components/hub-detail-step.tsx)\n \n\n# TUI交互界面\n\n## 概述\n\nByteRover CLI 的 TUI（终端用户界面）模块是一个基于文本的交互界面，使用 React 组件和渲染库构建，为开发者在终端环境中提供可视化的工作流程体验。TUI 模块位于 `src/tui/` 目录下，采用组件化架构设计，支持命令行操作、日志展示、技能市场浏览等功能。\n\nTUI 界面通过自包含的渲染管线将复杂的 Agent 工作流状态实时呈现给用户，包括工具调用执行、进度追踪、文件变更展示等核心功能。界面采用深色主题设计，符合现代开发者工具的视觉风格。\n\n## 架构设计\n\n### 组件层级结构\n\nTUI 模块遵循 React 组件树结构，主要分为以下几大功能区域：\n\n```mermaid\ngraph TD\n A[TUI Root] --> B[布局组件]\n A --> C[命令输入组件]\n A --> D[执行展示组件]\n A --> E[功能面板]\n \n B --> B1[主布局]\n B --> B2[侧边栏]\n \n C --> C1[命令输入框]\n C --> C2[斜杠命令处理器]\n \n D --> D1[工具执行展示]\n D --> D2[日志视图]\n D --> D3[流式内容]\n D --> D4[变更追踪]\n \n E --> E1[Hub 市场]\n E --> E2[上下文历史]\n E --> E3[任务管理]\n```\n\n### 执行流程状态机\n\nAgent 执行过程中的状态转换通过 TUI 组件实时反映：\n\n```mermaid\nstateDiagram-v2\n [*] --> Running : 开始执行\n Running --> Completed : 成功完成\n Running --> Failed : 执行失败\n Completed --> [*] : 用户确认\n Failed --> [*] : 用户查看后关闭\n \n Running --> Streaming : 流式输出\n Streaming --> Running : 数据更新\n```\n\n## 核心组件\n\n### 执行展示组件\n\n#### 工具调用展示 (`execution-tool.tsx`)\n\n该组件负责在执行过程中显示单个工具调用的状态信息。根据工具调用的状态，组件渲染不同的视觉标识：\n\n| 状态值 | 视觉表现 | 颜色配置 |\n|--------|----------|----------|\n| `success` | ✓ 前缀绿色对勾 | `colors.primary` |\n| `running` | 闪烁圆圈动画 | `colors.dimText` |\n| `failed` | ✗ 前缀红色叉号 | `colors.errorText` |\n\n组件接收以下属性：\n\n```typescript\ninterface ExecutionToolProps {\n toolCall: ToolCall; // 工具调用数据\n toolName?: string; // 工具显示名称\n toolArguments?: string; // 工具参数字符串\n}\n```\n\n当工具处于 `running` 状态时，组件渲染 `` 动画元素，提示用户当前正在处理中。\n\n#### 展开日志视图 (`expanded-log-view.tsx`)\n\n该组件是执行日志的核心展示容器，集成了多种内容类型的渲染能力：\n\n| 内容区域 | 触发条件 | 组件 |\n|----------|----------|------|\n| 输入信息 | 始终显示 | `` |\n| 进度追踪 | `toolCalls` 或 `reasoningContents` 存在 | `` |\n| 流式内容 | `status === 'running'` 且有 `streamingContent` | `` |\n| 执行结果 | `status === 'failed'` 或 `status === 'completed'` | `` |\n| 变更列表 | `status === 'completed'` | `` |\n\n组件的数据结构定义：\n\n```typescript\ninterface ExpandedLog {\n input: string;\n files?: string[];\n toolCalls?: ToolCall[];\n reasoningContents?: ReasoningContent[];\n streamingContent?: string;\n isStreaming?: boolean;\n status: 'running' | 'completed' | 'failed';\n content?: string;\n changes: {\n created: string[];\n updated: string[];\n };\n}\n```\n\n流式文本内容通过 `StreamingText` 组件渲染，支持实时光标显示和动态内容更新。当 `isStreaming` 为 true 时，光标会持续闪烁，提示用户数据仍在传输中。\n\n#### 变更追踪展示\n\n执行完成后的变更内容通过 `ExecutionChanges` 组件展示，该组件接受以下参数：\n\n```typescript\ninterface ExecutionChangesProps {\n created: string[]; // 创建的文件路径列表\n updated: string[]; // 更新的文件路径列表\n isExpanded: boolean; // 是否展开显示\n maxChanges: {\n created: number; // 创建文件的最大显示数量\n updated: number; // 更新文件的最大显示数量\n };\n}\n```\n\n文件路径以 `@` 前缀形式展示，如 `@src/main.ts`，便于用户识别文件位置。\n\n### Hub 功能面板\n\n#### 详情展示 (`hub-detail-step.tsx`)\n\nHub 面板提供技能和 Agent 的详细信息浏览功能。组件展示的数据字段包括：\n\n| 字段 | 显示标签 | 样式说明 |\n|------|----------|----------|\n| `version` | 版本号 | 卡片式布局 |\n| `registry` | 仓库名 | 卡片式布局，默认值 'default' |\n| `tags` | 标签列表 | 以 `#` 前缀显示 |\n| `dependencies` | 依赖项 | 警告色显示 |\n| `category` | 分类 | 标准文本 |\n| `author.name` | 作者 | 左对齐标签配右对齐值 |\n| `license` | 许可证 | 左对齐标签配右对齐值 |\n| `file_tree` | 文件列表 | 缩进显示 |\n\n当条目类型为 `agent-skill` 时，组件额外渲染目标 Agent 选择器：\n\n```typescript\n// Agent 选择器配置\nconst AGENT_VALUES = ['Codex', /* other agents */];\n\n setAgentSelections({...current, [entry.id]: event.target.value})}\n>\n {AGENT_VALUES.map((agent) => (\n \n ))}\n\n```\n\n#### 快捷键绑定\n\nHub 详情面板支持以下键盘交互：\n\n| 按键 | 功能 |\n|------|------|\n| `Enter` | 安装选中的技能/Agent |\n| `o` | 在浏览器中打开详情 |\n| `Esc` | 返回上一级 |\n\n## 状态管理\n\n### 执行状态流转\n\nTUI 界面的执行状态管理遵循以下流程：\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant CLI as 命令行\n participant Agent as Agent服务\n participant TUI as TUI组件\n \n User->>CLI: 输入命令\n CLI->>Agent: 发起执行请求\n Agent-->>TUI: 流式返回状态\n TUI->>TUI: 更新running状态\n TUI->>TUI: 渲染流式内容\n \n Agent-->>CLI: 执行完成\n CLI-->>TUI: 发送completed/failed\n TUI->>TUI: 更新最终状态\n TUI->>TUI: 展示变更列表\n```\n\n### Hub 选择状态\n\nAgent 选择状态通过 `useState` 管理：\n\n```typescript\nconst [agentSelections, setAgentSelections] = useState>({});\n\n// 更新单个选择\nsetAgentSelections((current) => ({\n ...current,\n [entry.id]: event.target.value\n}));\n```\n\n## 视觉设计\n\n### 配色系统\n\nTUI 组件采用终端友好的配色方案：\n\n| 用途 | 颜色变量 | 说明 |\n|------|----------|------|\n| 主色调 | `colors.primary` | 成功状态、强调元素 |\n| 文字色 | `colors.text` | 主要文本内容 |\n| 暗淡文字 | `colors.dimText` | 次要信息、标签 |\n| 错误色 | `colors.errorText` | 失败状态、警告 |\n| 警告色 | `colors.warning` | 依赖项展示 |\n\n### 布局模式\n\n组件采用灵活的布局系统，主要使用以下布局属性：\n\n- `flexDirection: 'row' | 'column'` - 主轴方向\n- `gap: number` - 子元素间距\n- `marginBottom: number` - 底部外边距\n- `paddingX: number` - 水平内边距\n\n## 技术实现要点\n\n### 渲染管线\n\nTUI 采用声明式渲染模式，组件根据状态变化自动重新渲染。关键优化点包括：\n\n1. **条件渲染**：仅在数据存在时渲染对应内容区域\n2. **状态隔离**：每个日志条目维护独立的状态副本\n3. **流式处理**：支持 `isStreaming` 标志控制实时内容更新\n\n### 组件复用策略\n\n通过抽象公共接口实现组件复用：\n\n- `ExecutionTool` 和 `ExecutionContent` 共享错误状态处理逻辑\n- `StreamingText` 组件同时服务于执行日志和普通流式输出\n- Hub 面板的布局模式可扩展至其他详情展示场景\n\n## 相关命令\n\nTUI 界面支持通过 `brv` 命令行工具触发：\n\n```bash\nbrv webui # 启动 WebUI 界面\nbrv login # 用户认证\nbrv init # 初始化项目\nbrv status # 查看连接状态\n```\n\n## 源码引用\n\n| 组件 | 文件路径 | 功能描述 |\n|------|----------|----------|\n| 工具执行展示 | `src/tui/components/execution/execution-tool.tsx:1-24` | 渲染工具调用状态 |\n| 展开日志视图 | `src/tui/components/execution/expanded-log-view.tsx:1-50` | 聚合展示执行详情 |\n| Hub详情面板 | `src/tui/features/hub/components/hub-detail-step.tsx:1-80` | 技能市场详情浏览 |\n\n## 扩展说明\n\n### 流式内容处理\n\n`expanded-log-view.tsx` 中的流式内容展示采用以下策略：\n\n1. 监测 `streamingContent` 和 `isStreaming` 属性\n2. 处于 `running` 状态时持续渲染 ``\n3. `showCursor` 属性在 `isStreaming` 为 true 时激活闪烁光标\n4. `maxLines={0}` 配置允许内容无限延展\n\n### 错误处理可视化\n\n执行失败时的错误信息通过以下流程呈现：\n\n1. 检测 `status === 'failed'`\n2. 使用 `isError` 属性高亮错误文本\n3. 错误内容从 `content` 字段提取\n4. 配合 `colors.errorText` 配色方案突出显示\n\n---\n\n\n\n## WebUI管理面板\n\n### 相关页面\n\n相关主题：[TUI交互界面](#tui-interface)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/webui/index.html](https://github.com/campfirein/byterover-cli/blob/main/src/webui/index.html)\n- [src/webui/features/hub/components/hub-panel.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/webui/features/hub/components/hub-panel.tsx)\n- [src/webui/features/hub/components/hub-detail-step.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/webui/features/hub/components/hub-detail-step.tsx)\n- [src/webui/features/transport/components/offline-screen.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/webui/features/transport/components/offline-screen.tsx)\n- [src/webui/features/project/components/project-dropdown.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/webui/features/project/components/project-dropdown.tsx)\n- [src/webui/features/context/components/context-history-panel.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/webui/features/context/components/context-history-panel.tsx)\n- [src/webui/features/tasks/components/task-composer.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/webui/features/tasks/components/task-composer.tsx)\n- [src/webui/features/tasks/components/task-detail-view.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/webui/features/tasks/components/task-detail-view.tsx)\n- [src/webui/features/vc/components/diff-view.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/webui/features/vc/components/diff-view.tsx)\n- [src/server/infra/http/review-ui.ts](https://github.com/campfirein/byterover-cli/blob/main/src/server/infra/http/review-ui.ts)\n- [src/server/infra/http/callback-server.ts](https://github.com/campfirein/byterover-cli/blob/main/src/server/infra/http/callback-server.ts)\n- [src/server/infra/provider-oauth/callback-server.ts](https://github.com/campfirein/byterover-cli/blob/main/src/server/infra/provider-oauth/callback-server.ts)\n \n\n# WebUI管理面板\n\n## 概述\n\nWebUI管理面板是ByteRover CLI的图形化Web界面模块，提供项目上下文管理、技能市场、任务编辑、版本控制等核心功能的可视化操作界面。该模块基于React构建，采用TypeScript开发，通过WebSocket与本地后端服务通信，实现对AI编程助手的持久化记忆管理。\n\nWebUI的核心价值在于将CLI的命令行操作转换为直观的图形界面，使开发者能够更便捷地管理项目知识库、查看上下文历史、浏览技能市场、以及进行版本控制操作。资料来源：[src/webui/index.html:1-13]()\n\n## 系统架构\n\n### 整体架构\n\nWebUI采用前后端分离的架构设计，前端为单页应用(SPA)，后端为Express服务。系统通过WebSocket保持实时通信，同时提供HTTP API用于认证回调和数据同步。\n\n```mermaid\ngraph TD\n A[用户浏览器] <--> B[WebUI前端
React SPA]\n B <--> C[本地Server
Express + WebSocket]\n C --> D[项目文件系统]\n C --> E[ByteRover Cloud
远程同步]\n C --> F[AI Provider
OAuth认证]\n \n G[CLI终端] <--> C\n```\n\n### 目录结构\n\nWebUI模块位于`src/webui/`目录下，采用特性模块组织代码结构：\n\n```\nsrc/webui/\n├── index.html # HTML入口文件\n├── index.tsx # React根组件入口\n├── App.tsx # 主应用组件\n├── router.tsx # 路由配置\n├── layouts/\n│ └── main-layout.tsx # 主布局组件\n├── providers/\n│ └── app-providers.tsx # 全局状态提供者\n├── features/ # 功能模块\n│ ├── hub/ # 技能中心\n│ ├── tasks/ # 任务编辑\n│ ├── context/ # 上下文管理\n│ ├── project/ # 项目选择\n│ ├── transport/ # 连接状态\n│ └── vc/ # 版本控制\n└── components/ # 通用组件\n```\n\n资料来源：[src/webui/index.html:1-13]()\n\n## 核心功能模块\n\n### Hub技能中心\n\nHub模块是WebUI的核心功能区域，提供技能和代理的管理界面。用户可以浏览、安装和管理来自不同注册表的AI技能。\n\n#### Hub面板组件\n\n`hub-panel.tsx`负责渲染技能列表和安装界面，支持以下功能：\n\n| 功能 | 描述 | 源码位置 |\n|------|------|----------|\n| 技能列表 | 显示所有可用的技能和代理类型 | hub-panel.tsx |\n| 安装按钮 | 触发技能安装流程 | hub-panel.tsx |\n| 代理选择 | 为技能选择目标AI代理 | hub-panel.tsx |\n| 版本显示 | 展示技能当前版本号 | hub-panel.tsx |\n| 注册表信息 | 显示技能来源的注册表 | hub-panel.tsx |\n\n组件支持`agent-skill`类型条目的代理选择功能，用户可以通过下拉菜单选择目标代理（如Codex等）。资料来源：[src/webui/features/hub/components/hub-panel.tsx:1-50]()\n\n#### Hub详情步骤组件\n\n`hub-detail-step.tsx`提供技能的详细元数据展示界面，包括：\n\n| 元数据字段 | 说明 |\n|-----------|------|\n| Tags | 技能标签，用于分类检索 |\n| Requires | 技能依赖项 |\n| Category | 技能分类 |\n| Registry | 技能来源注册表 |\n| Author | 作者信息 |\n| Version | 版本号 |\n\n资料来源：[src/webui/features/hub/components/hub-detail-step.tsx:1-60]()\n\n### 项目管理\n\n项目下拉组件`project-dropdown.tsx`实现项目选择和管理功能。\n\n```mermaid\ngraph LR\n A[点击下拉触发] --> B{是否有打开的项目}\n B -->|是| C[显示打开项目列表]\n B -->|否| D[显示最近项目列表]\n C --> E[选择项目]\n D --> E\n E --> F[加载项目上下文]\n```\n\n项目选择支持三种来源：\n\n1. **当前打开的项目** - 已激活的项目列表\n2. **最近项目** - 历史访问过的项目，最多显示`RECENT_LIMIT`个\n3. **所有项目** - 点击\"See all\"展开完整列表\n\n新项目需要通过CLI命令`brv webui`在项目目录下注册后才能在界面中显示。资料来源：[src/webui/features/project/components/project-dropdown.tsx:1-80]()\n\n### 任务编辑\n\n任务编辑器`task-composer.tsx`是WebUI的核心输入组件，支持多种任务类型的创建和编辑。\n\n#### 支持的任务类型\n\n| 类型 | 描述 | 特殊处理 |\n|------|------|----------|\n| curate | 知识整理任务 | 显示CurateAttachmentHint提示 |\n| default | 默认任务类型 | 标准编辑器 |\n| 其他 | 自定义任务类型 | 根据HelpRow配置显示帮助信息 |\n\n#### 编辑器界面元素\n\n- **快捷键提示**：显示键盘快捷键（如`Ctrl+Enter`提交、`Tab`使用示例）\n- **字符计数**：实时显示输入内容长度\n- **HelpRow帮助**：根据任务类型显示对应的帮助信息\n- **ComposerFooter**：底部工具栏，包含提交、取消、详情展开等操作\n\n```tsx\n// 提交验证\nconst canSubmit = content.length > 0 && hasActiveProvider\n```\n\n资料来源：[src/webui/features/tasks/components/task-composer.tsx:1-100]()\n\n#### 任务详情视图\n\n`task-detail-view.tsx`提供任务的详细查看界面，用于展示已完成任务的完整信息、变更内容和执行结果。\n\n### 上下文历史\n\n`context-history-panel.tsx`组件负责展示项目的上下文提交历史记录。\n\n| 功能 | 说明 |\n|------|------|\n| 当前提交 | 高亮显示当前活跃的上下文版本 |\n| 历史记录 | 按时间倒序展示旧的提交记录 |\n| 时间格式化 | 将时间戳转换为可读格式（如\"Jan 15, 14:30\"） |\n\n```tsx\nfunction formatCommitDate(timestamp: string): string {\n try {\n return `Updated at ${format(new Date(timestamp), 'MMM d, HH:mm')}`\n } catch {\n return 'Updated'\n }\n}\n```\n\n资料来源：[src/webui/features/context/components/context-history-panel.tsx:1-80]()\n\n### 版本控制差异视图\n\n`diff-view.tsx`组件提供文件变更的可视化对比功能，支持：\n\n- 创建文件高亮（绿色背景）\n- 更新文件差异展示\n- 删除文件标记（红色）\n\n### 连接状态管理\n\n`offline-screen.tsx`组件处理网络连接状态的UI展示。\n\n| 状态 | 显示内容 | 指示器颜色 |\n|------|----------|-----------|\n| 正常连接 | 无特殊显示 | 绿色 |\n| 离线 | \"Offline\"徽章 | 黄色警告 |\n| 配置错误 | \"Unreachable\"徽章 | 红色错误 |\n| 重连中 | 重连尝试次数显示 | 脉冲动画 |\n\n```tsx\n// 重连状态显示\n{isConfigError ? (\n Refresh once the host is back.\n) : (\n <>\n Reconnecting\n attempt {reconnectCount}\n \n)}\n```\n\n资料来源：[src/webui/features/transport/components/offline-screen.tsx:1-80]()\n\n## 认证与回调系统\n\n### OAuth回调处理\n\nByteRover支持多种AI Provider的OAuth认证，后端服务提供专用的回调处理。\n\n#### HTTP回调服务器\n\n`src/server/infra/http/callback-server.ts`提供认证回调的HTML响应：\n\n| 函数 | 功能 |\n|------|------|\n| successHtml | 渲染认证成功页面，2秒后自动关闭 |\n| errorHtml | 渲染认证失败页面，显示错误详情 |\n\n成功页面包含：\n- 品牌Logo展示\n- \"Authentication Successful\"标题\n- 自动关闭提示\n\n错误页面包含：\n- 错误图标\n- 错误描述文本\n- 可选的详细错误信息（使用`escapeHtml`转义）\n\n#### Provider OAuth回调\n\n`src/server/infra/provider-oauth/callback-server.ts`提供Provider特定的OAuth回调页面，包含：\n- 品牌Logo和标题\n- 成功/失败状态展示\n- CSS内联样式确保无依赖运行\n\n资料来源：[src/server/infra/http/callback-server.ts:1-100]()\n资料来源：[src/server/infra/provider-oauth/callback-server.ts:1-80]()\n\n## 审查UI模块\n\n`review-ui.ts`提供本地HITL（Human-in-the-Loop）审查界面的HTML生成功能。\n\n### 特性\n\n- **自包含设计**：所有CSS和JavaScript内联，无外部依赖\n- **语义化展示**：显示操作的前置版本和当前版本摘要\n- **深色主题**：采用GitHub风格的深色配色方案\n\n### 样式变量\n\n```css\n:root {\n --bg: #0d1117;\n --bg-secondary: #161b22;\n --bg-tertiary: #21262d;\n --border: #30363d;\n --text: #e6edf3;\n --text-muted: #8b949e;\n --green: #238636;\n --red: #da3633;\n --blue: #58a6ff;\n --yellow: #d29922;\n}\n```\n\n资料来源：[src/server/infra/http/review-ui.ts:1-50]()\n\n## 执行日志展示\n\nWebUI的执行日志组件负责展示AI代理的执行过程，包括：\n\n| 组件 | 功能 |\n|------|------|\n| expanded-log-view.tsx | 展开的日志视图，显示输入、工具调用、流式内容、变更 |\n| execution-tool.tsx | 单个工具调用展示，包含状态图标和参数 |\n| ExecutionProgress | 推理内容和工具调用进度条 |\n| ExecutionContent | 任务完成后的输出内容展示 |\n| ExecutionChanges | 创建和更新的文件列表展示 |\n\n### 日志状态\n\n| 状态 | 样式 | 显示内容 |\n|------|------|----------|\n| running | 流式文本+进度条 | 实时输出 |\n| completed | 绿色勾选+变更列表 | 最终结果 |\n| failed | 红色叉号+错误信息 | 错误详情 |\n\n资料来源：[src/tui/components/execution/expanded-log-view.tsx:1-80]()\n资料来源：[src/tui/components/execution/execution-tool.tsx:1-50]()\n\n## 数据流架构\n\n```mermaid\ngraph TD\n subgraph 前端层\n A[React Components] --> B[Context Providers]\n B --> C[Feature Modules]\n end\n \n subgraph 通信层\n C --> D[WebSocket
实时事件]\n C --> E[HTTP API
REST请求]\n end\n \n subgraph 后端层\n D --> F[Express Server]\n E --> F\n F --> G[项目文件系统]\n F --> H[Cloud Sync]\n F --> I[AI Provider]\n end\n \n subgraph 存储层\n G --> J[本地知识库]\n H --> K[云端上下文]\n end\n```\n\n## 状态管理\n\nWebUI使用React Context进行全局状态管理，主要Provider包括：\n\n| Provider | 职责 |\n|----------|------|\n| AppProviders | 根级别提供者，聚合所有子Provider |\n| 任务状态 | 管理当前编辑的任务内容 |\n| 项目状态 | 管理选中和最近的项目列表 |\n| 连接状态 | 管理WebSocket连接状态和重连逻辑 |\n| Hub状态 | 管理技能列表和安装状态 |\n\n## 总结\n\nWebUI管理面板是ByteRover CLI的图形化操作界面，通过模块化的React组件架构提供了完整的项目上下文管理功能。主要模块包括：\n\n- **Hub技能中心**：浏览和安装AI技能\n- **项目管理**：项目选择和切换\n- **任务编辑**：创建和编辑各类任务\n- **上下文历史**：查看和管理知识版本\n- **版本控制**：文件变更对比\n- **连接状态**：网络状态监控\n\n整个系统采用TypeScript开发，确保类型安全；通过WebSocket实现实时通信；后端Express服务提供API和OAuth认证支持。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：campfirein/byterover-cli\n\n摘要：发现 19 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Curator can copy prompt example facts into the context tree when using Gemini Flash-Lite。\n\n## 1. 安装坑 · 来源证据：Curator can copy prompt example facts into the context tree when using Gemini Flash-Lite\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Curator can copy prompt example facts into the context tree when using Gemini Flash-Lite\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f0927b3fa77c4e7ab29ba04f3c4b7ed7 | https://github.com/campfirein/byterover-cli/issues/647 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Visual corruption while browsing a long model list\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Visual corruption while browsing a long model list\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3112b1ba6fc54e0a8d973b277ab8d106 | https://github.com/campfirein/byterover-cli/issues/620 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：ByteRover CLI 3.10.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.10.1\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c21085e93cad46a5b79d8ff2353f156c | https://github.com/campfirein/byterover-cli/releases/tag/v3.10.1 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：ByteRover CLI 3.10.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.10.3\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5ada5377aa504edeac454b6a66310a47 | https://github.com/campfirein/byterover-cli/releases/tag/v3.10.3 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：ByteRover CLI 3.8.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.8.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_370b6c20f13544c28427013da0519f1f | https://github.com/campfirein/byterover-cli/releases/tag/v3.8.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：ByteRover CLI 3.8.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.8.2\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_48b470d455aa406480648e100bc08c94 | https://github.com/campfirein/byterover-cli/releases/tag/v3.8.2 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：ByteRover CLI 3.8.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.8.3\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_70d8761f65864cf2897a70138eabb5b7 | https://github.com/campfirein/byterover-cli/releases/tag/v3.8.3 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 安装坑 · 来源证据：ByteRover CLI 3.9.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.9.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_955f12701a864106895fc95c8ef7fd05 | https://github.com/campfirein/byterover-cli/releases/tag/v3.9.0 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：`brv mcp` client stuck in infinite exception loop consuming 75–90% CPU for hours\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：`brv mcp` client stuck in infinite exception loop consuming 75–90% CPU for hours\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_50500a3417394344864f50cf765157ea | https://github.com/campfirein/byterover-cli/issues/660 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 10. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | README/documentation is current enough for a first validation pass.\n\n## 11. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | last_activity_observed missing\n\n## 12. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 来源证据：ByteRover CLI 3.10.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ByteRover CLI 3.10.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_78241481b8c647e4a05827b06eafdc99 | https://github.com/campfirein/byterover-cli/releases/tag/v3.10.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：ByteRover CLI 3.10.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ByteRover CLI 3.10.2\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2af62a087710490b8250f23ac6258644 | https://github.com/campfirein/byterover-cli/releases/tag/v3.10.2 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：ByteRover CLI 3.11.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ByteRover CLI 3.11.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ea3c8b32846b4edfaef28f8aa1cca40f | https://github.com/campfirein/byterover-cli/releases/tag/v3.11.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：ByteRover CLI 3.12.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ByteRover CLI 3.12.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_917109bf273c4c09a26a50f00fd1b6e4 | https://github.com/campfirein/byterover-cli/releases/tag/v3.12.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 18. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | issue_or_pr_quality=unknown\n\n## 19. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：campfirein/byterover-cli\n\n摘要：发现 19 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Curator can copy prompt example facts into the context tree when using Gemini Flash-Lite。\n\n## 1. 安装坑 · 来源证据：Curator can copy prompt example facts into the context tree when using Gemini Flash-Lite\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Curator can copy prompt example facts into the context tree when using Gemini Flash-Lite\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f0927b3fa77c4e7ab29ba04f3c4b7ed7 | https://github.com/campfirein/byterover-cli/issues/647 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Visual corruption while browsing a long model list\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Visual corruption while browsing a long model list\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3112b1ba6fc54e0a8d973b277ab8d106 | https://github.com/campfirein/byterover-cli/issues/620 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：ByteRover CLI 3.10.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.10.1\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c21085e93cad46a5b79d8ff2353f156c | https://github.com/campfirein/byterover-cli/releases/tag/v3.10.1 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：ByteRover CLI 3.10.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.10.3\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5ada5377aa504edeac454b6a66310a47 | https://github.com/campfirein/byterover-cli/releases/tag/v3.10.3 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：ByteRover CLI 3.8.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.8.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_370b6c20f13544c28427013da0519f1f | https://github.com/campfirein/byterover-cli/releases/tag/v3.8.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：ByteRover CLI 3.8.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.8.2\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_48b470d455aa406480648e100bc08c94 | https://github.com/campfirein/byterover-cli/releases/tag/v3.8.2 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：ByteRover CLI 3.8.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.8.3\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_70d8761f65864cf2897a70138eabb5b7 | https://github.com/campfirein/byterover-cli/releases/tag/v3.8.3 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 安装坑 · 来源证据：ByteRover CLI 3.9.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.9.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_955f12701a864106895fc95c8ef7fd05 | https://github.com/campfirein/byterover-cli/releases/tag/v3.9.0 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：`brv mcp` client stuck in infinite exception loop consuming 75–90% CPU for hours\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：`brv mcp` client stuck in infinite exception loop consuming 75–90% CPU for hours\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_50500a3417394344864f50cf765157ea | https://github.com/campfirein/byterover-cli/issues/660 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 10. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | README/documentation is current enough for a first validation pass.\n\n## 11. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | last_activity_observed missing\n\n## 12. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 来源证据：ByteRover CLI 3.10.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ByteRover CLI 3.10.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_78241481b8c647e4a05827b06eafdc99 | https://github.com/campfirein/byterover-cli/releases/tag/v3.10.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：ByteRover CLI 3.10.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ByteRover CLI 3.10.2\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2af62a087710490b8250f23ac6258644 | https://github.com/campfirein/byterover-cli/releases/tag/v3.10.2 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：ByteRover CLI 3.11.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ByteRover CLI 3.11.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ea3c8b32846b4edfaef28f8aa1cca40f | https://github.com/campfirein/byterover-cli/releases/tag/v3.11.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：ByteRover CLI 3.12.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ByteRover CLI 3.12.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_917109bf273c4c09a26a50f00fd1b6e4 | https://github.com/campfirein/byterover-cli/releases/tag/v3.12.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 18. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | issue_or_pr_quality=unknown\n\n## 19. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# byterover-cli - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 byterover-cli 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. project-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. system-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. agent-system：Agent核心系统。围绕“Agent核心系统”模拟一次用户任务，不展示安装或运行结果。\n4. llm-providers：LLM提供商集成。围绕“LLM提供商集成”模拟一次用户任务，不展示安装或运行结果。\n5. tools-system：工具系统。围绕“工具系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. project-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. system-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. agent-system\n输入：用户提供的“Agent核心系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. llm-providers\n输入：用户提供的“LLM提供商集成”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. tools-system\n输入：用户提供的“工具系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / project-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / system-architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / agent-system：Step 3 必须围绕“Agent核心系统”形成一个小中间产物，并等待用户确认。\n- Step 4 / llm-providers：Step 4 必须围绕“LLM提供商集成”形成一个小中间产物，并等待用户确认。\n- Step 5 / tools-system：Step 5 必须围绕“工具系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/campfirein/byterover-cli\n- https://github.com/campfirein/byterover-cli#readme\n- src/server/templates/skill/SKILL.md\n- README.md\n- package.json\n- CLAUDE.md\n- src/agent/core/interfaces/index.ts\n- src/index.ts\n- src/server/infra/transport/socket-io-transport-server.ts\n- src/oclif/commands/main.ts\n- src/agent/core/domain/agent/agent-state-machine.ts\n- src/agent/core/domain/agent/agent-registry.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 byterover-cli 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：campfirein/byterover-cli\n\n## 官方安装入口\n\n### Node.js / npm · 官方安装入口\n\n```bash\nnpm install -g byterover-cli\n```\n\n来源：https://github.com/campfirein/byterover-cli#readme\n\n## 来源\n\n- repo: https://github.com/campfirein/byterover-cli\n- docs: https://github.com/campfirein/byterover-cli#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_91ddd0b1491442239f32e69c7d30787b"
}