{
"canonical_name": "campfirein/byterover-cli",
"compilation_id": "pack_be052020dc894de697a499f5ce7a6cf2",
"created_at": "2026-05-15T10:35:30.723149+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": "Browser Agents",
"label_zh": "浏览器 Agent",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-browser-agents",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Natural-language Web Actions",
"label_zh": "自然语言网页操作",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-natural-language-web-actions",
"type": "core_capability"
},
{
"label_en": "Multi-role Workflow",
"label_zh": "多角色协作流程",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-multi-role-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": [
"浏览器 Agent",
"网页任务自动化",
"自然语言网页操作",
"多角色协作流程",
"评测体系"
],
"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. introduction：Introduction to ByteRover CLI。围绕“Introduction to ByteRover CLI”模拟一次用户任务，不展示安装或运行结果。\n2. getting-started：Getting Started。围绕“Getting Started”模拟一次用户任务，不展示安装或运行结果。\n3. architecture-overview：System Architecture Overview。围绕“System Architecture Overview”模拟一次用户任务，不展示安装或运行结果。\n4. agent-system：Agent System。围绕“Agent System”模拟一次用户任务，不展示安装或运行结果。\n5. tool-system：Tool System。围绕“Tool System”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“Introduction to ByteRover CLI”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. getting-started\n输入：用户提供的“Getting Started”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. architecture-overview\n输入：用户提供的“System Architecture Overview”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. agent-system\n输入：用户提供的“Agent System”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. tool-system\n输入：用户提供的“Tool System”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“Introduction to ByteRover CLI”形成一个小中间产物，并等待用户确认。\n- Step 2 / getting-started：Step 2 必须围绕“Getting Started”形成一个小中间产物，并等待用户确认。\n- Step 3 / architecture-overview：Step 3 必须围绕“System Architecture Overview”形成一个小中间产物，并等待用户确认。\n- Step 4 / agent-system：Step 4 必须围绕“Agent System”形成一个小中间产物，并等待用户确认。\n- Step 5 / tool-system：Step 5 必须围绕“Tool System”形成一个小中间产物，并等待用户确认。\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- src/index.ts\n- package.json\n- scripts/install.sh\n- bin/run.js\n- src/oclif/commands/init.ts\n- src/server/infra/daemon/brv-server.ts\n- src/agent/infra/agent/base-agent.ts\n- src/server/infra/transport/socket-io-transport-server.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": [
"浏览器 Agent",
"网页任务自动化",
"自然语言网页操作",
"多角色协作流程",
"评测体系"
],
"thumb": "gray",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/campfirein/byterover-cli 项目说明书\n\n生成时间：2026-05-15 10:10:21 UTC\n\n## 目录\n\n- [Introduction to ByteRover CLI](#introduction)\n- [Getting Started](#getting-started)\n- [System Architecture Overview](#architecture-overview)\n- [Agent System](#agent-system)\n- [Tool System](#tool-system)\n- [LLM Providers](#llm-providers)\n- [Context Management](#context-management)\n- [Context Tree and Knowledge Storage](#context-tree)\n- [Version Control for Context](#version-control)\n- [WebUI Dashboard](#webui-dashboard)\n\n\n\n## Introduction to ByteRover CLI\n\n### 相关页面\n\n相关主题：[Getting Started](#getting-started), [System Architecture Overview](#architecture-overview)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/campfirein/byterover-cli/blob/main/README.md)\n- [src/server/templates/README.md](https://github.com/campfirein/byterover-cli/blob/main/src/server/templates/README.md)\n- [src/server/templates/skill/SKILL.md](https://github.com/campfirein/byterover-cli/blob/main/src/server/templates/skill/SKILL.md)\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- [src/agent/infra/process/command-validator.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/process/command-validator.ts)\n- [src/shared/transport/events/vc-events.ts](https://github.com/campfirein/byterover-cli/blob/main/src/shared/transport/events/vc-events.ts)\n\n\n# Introduction to ByteRover CLI\n\nByteRover CLI (`brv`) is an interactive REPL (Read-Eval-Print Loop) command-line tool that provides AI coding agents with persistent, structured memory capabilities. It enables developers to curate project knowledge into a context tree, synchronize it to the cloud, and share it across tools and teammates.\n\n资料来源：[README.md:1-10](https://github.com/campfirein/byterover-cli/blob/main/README.md)\n\n## Overview\n\nByteRover CLI serves as a bridge between human developers and AI coding assistants by maintaining a structured knowledge base of project patterns, decisions, and architectural rules. The CLI operates as an interactive REPL powered by a configurable LLM provider, allowing AI agents to understand codebases through an agentic map system.\n\n资料来源：[README.md:23-27](https://github.com/campfirein/byterover-cli/blob/main/README.md)\n\n### Key Capabilities\n\n| Capability | Description |\n|------------|-------------|\n| **Context Management** | Store and retrieve project patterns, decisions, and architectural rules |\n| **Knowledge Curation** | Add context to knowledge storage with `brv curate` |\n| **Query Engine** | Query context tree and knowledge using LLM synthesis |\n| **Version Control** | Local and cloud-based version control for context trees |\n| **HITL Review** | Human-in-the-loop review workflow for curated content |\n| **Template Generation** | Generate agent instruction rules via `brv gen-rules` |\n\n资料来源：[src/server/templates/skill/SKILL.md:1-25](https://github.com/campfirein/byterover-cli/blob/main/src/server/templates/skill/SKILL.md)\n\n## Architecture\n\nByteRover CLI follows a modular architecture with multiple integrated subsystems working together to provide knowledge management capabilities.\n\n```mermaid\ngraph TD\n subgraph \"Client Layer\"\n TUI[TUI Component]\n WEBUI[WebUI Component]\n CLI[CLI Commands]\n end\n \n subgraph \"Server Layer\"\n HTTP[HTTP Server]\n REVIEW_UI[Review UI]\n OAUTH[OAuth Callback]\n end\n \n subgraph \"Agent Layer\"\n ABSTRACT[Abstract Generator]\n FOLDER_PACK[Folder Pack Executor]\n CMD_VALIDATOR[Command Validator]\n end\n \n subgraph \"Transport Layer\"\n EVENTS[Transport Events]\n WS[WebSocket Transport]\n end\n \n CLI --> HTTP\n TUI --> HTTP\n WEBUI --> WS\n HTTP --> EVENTS\n AGENT --> FOLDER_PACK\n AGENT --> ABSTRACT\n EVENTS --> CMD_VALIDATOR\n```\n\n### Component Breakdown\n\n| Component | Location | Purpose |\n|-----------|----------|---------|\n| **TUI** | `src/tui/` | Terminal User Interface for interactive REPL |\n| **WebUI** | `src/webui/` | Browser-based dashboard (`brv webui`) |\n| **Agent** | `src/agent/` | AI agent infrastructure and LLM integration |\n| **Server** | `src/server/` | HTTP server, review UI, and OAuth handling |\n| **Shared** | `src/shared/` | Shared transport events and types |\n\n资料来源：[src/tui/components/execution/expanded-log-view.tsx:1-50](https://github.com/campfirein/byterover-cli/blob/main/src/tui/components/execution/expanded-log-view.tsx)\n\n## Core Workflow\n\nThe recommended workflow for using ByteRover CLI involves two main phases: querying existing knowledge before starting work, and curating new patterns after implementation.\n\n```mermaid\ngraph LR\n A[Start Task] --> B[brv query]\n A --> C[brv swarm query]\n B --> D{Knowledge Found?}\n C --> D\n D -->|Yes| E[Implement with Context]\n D -->|No| F[Search External Sources]\n E --> G[brv curate]\n F --> E\n G --> H[Review Pending]\n H --> I[brv review approve/reject]\n```\n\n### Knowledge Management Workflow\n\n1. **Before Thinking**: Run `brv query` and `brv swarm query` in parallel to understand existing patterns\n2. **After Implementing**: Run `brv curate` to save new patterns and decisions\n\n资料来源：[src/server/templates/skill/SKILL.md:30-45](https://github.com/campfirein/byterover-cli/blob/main/src/server/templates/skill/SKILL.md)\n\n## Command Reference\n\n### Core Commands\n\n| Command | Description |\n|---------|-------------|\n| `brv` | Start interactive REPL |\n| `brv webui` | Open ByteRover dashboard |\n| `brv status` | Show project and daemon status |\n| `brv login` | Authenticate with ByteRover cloud |\n| `brv init` | Initialize ByteRover in a project |\n\n### Context Management\n\n| Command | Description |\n|---------|-------------|\n| `brv curate` | Add context to knowledge storage |\n| `brv curate view` | View curate history |\n| `brv query` | Query context tree and knowledge |\n| `brv swarm query` | Multi-agent query across knowledge |\n\n### Review Workflow\n\n| Command | Description |\n|---------|-------------|\n| `brv review pending` | List pending review operations |\n| `brv review approve` | Approve curate operations |\n| `brv review reject` | Reject curate operations |\n\n资料来源：[README.md:35-50](https://github.com/campfirein/byterover-cli/blob/main/README.md)\n\n### Version Control Commands\n\n```bash\n# Initialize version control\nbrv vc init\n\n# Stage and commit\nbrv vc add \nbrv vc commit -m \"message\"\n\n# Branch management\nbrv vc branch # list branches\nbrv vc checkout # switch branch\nbrv vc merge # merge branches\n\n# Remote operations (requires authentication)\nbrv vc push # push to cloud\nbrv vc pull # pull from cloud\nbrv vc clone # clone a repository\n```\n\n资料来源：[src/server/templates/skill/SKILL.md:60-100](https://github.com/campfirein/byterover-cli/blob/main/src/server/templates/skill/SKILL.md)\n\n### Diff Modes\n\nThe version control system supports four diff modes mirroring Git's behavior:\n\n| Mode | Direction | Description |\n|------|-----------|-------------|\n| `unstaged` | STAGE → WORKDIR | Tracked files only (default `git diff`) |\n| `staged` | HEAD → STAGE | Matches `git diff --staged` |\n| `ref-vs-worktree` | `` → WORKDIR | Specific commit/branch vs working tree |\n| `range` | `` → `` | Two refs compared (e.g., `origin/main..HEAD`) |\n\n资料来源：[src/shared/transport/events/vc-events.ts:1-30](https://github.com/campfirein/byterover-cli/blob/main/src/shared/transport/events/vc-events.ts)\n\n## Knowledge Storage System\n\n### Directory Structure\n\nKnowledge is stored in `.brv/context-tree/` as human-readable Markdown files. The folder pack executor generates structured XML output for LLM consumption.\n\n资料来源：[src/server/templates/skill/SKILL.md:15-20](https://github.com/campfirein/byterover-cli/blob/main/src/server/templates/skill/SKILL.md)\n\n### Folder Pack Output Format\n\n```xml\n\n \n 1MB\n 500\n 3 patterns\n \n \n \n \n \n \n file content here\n \n \n \n Contains 25 files with 5000 total lines.\n \n\n```\n\n资料来源：[src/agent/infra/folder-pack/output-generator.ts:1-50](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/folder-pack/output-generator.ts)\n\n### Template System\n\nThe template system (`src/server/templates/`) generates agent instructions via the `brv gen-rules` command.\n\n```\nsrc/templates/\n├── base.md # Main template structure\n├── sections/\n│ ├── workflow.md # Workflow guide\n│ └── command-reference.md # BR CLI commands documentation\n└── README.md\n```\n\n| Variable | Description |\n|----------|-------------|\n| `{{agent_name}}` | Name of the agent (e.g., \"Claude Code\", \"Cursor\") |\n| `{{workflow}}` | Content from sections/workflow.md |\n| `{{command_reference}}` | Content from sections/command-reference.md |\n\n资料来源：[src/server/templates/README.md:1-40](https://github.com/campfirein/byterover-cli/blob/main/src/server/templates/README.md)\n\n## Security Features\n\n### Command Validation\n\nThe command validator (`command-validator.ts`) provides security checks for:\n\n- Dangerous pattern detection (e.g., recursive delete, network operations)\n- Injection attack prevention\n- Approval requirements based on security level\n- Blocked and allowed command lists\n\n资料来源：[src/agent/infra/process/command-validator.ts:1-60](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/process/command-validator.ts)\n\n### Read-Only Git Operations\n\nThe following Git operations are classified as safe read-only operations:\n\n| Command | Purpose |\n|---------|---------|\n| `git status` | Show working tree status |\n| `git log` | Show commit logs |\n| `git diff` | Show changes between commits |\n| `git show` | Show commit details |\n| `git branch` | List branches |\n| `git fetch` | Fetch remote refs |\n| `git pull` | Fetch and integrate remote changes |\n\n资料来源：[src/agent/infra/process/command-validator.ts:30-45](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/process/command-validator.ts)\n\n## Authentication\n\n### OAuth Flow\n\nByteRover CLI supports OAuth authentication for cloud sync operations. The callback server handles authorization at `/callback`:\n\n```typescript\n// Successful authorization returns this page\n\n\n\n ByteRover - Authorization Successful\n\n\n
Successful
\n
You can close this window and return to ByteRover.
\n \n\n\n```\n\n资料来源：[src/server/infra/provider-oauth/callback-server.ts:1-30](https://github.com/campfirein/byterover-cli/blob/main/src/server/infra/provider-oauth/callback-server.ts)\n\n### Authentication Requirements\n\n| Operation | Authentication Required |\n|-----------|------------------------|\n| `brv query` | No |\n| `brv swarm query` | No |\n| `brv curate` | No |\n| `brv vc` (local) | No |\n| `brv vc push` | Yes (login required) |\n| `brv vc pull` | Yes (login required) |\n\n资料来源：[src/server/templates/skill/SKILL.md:20-25](https://github.com/campfirein/byterover-cli/blob/main/src/server/templates/skill/SKILL.md)\n\n## Review UI\n\nThe HITL (Human-in-the-Loop) review UI provides a dark-themed interface for reviewing pending curate operations. It includes:\n\n- File cards showing operation types (add, update, delete)\n- Semantic summaries of previous/current versions\n- Approve and reject actions per file\n- Real-time reconnection handling for offline states\n\n```mermaid\ngraph TD\n A[Pending Operations] --> B[Render File Cards]\n B --> C[Show Semantic Summaries]\n C --> D{User Action}\n D -->|Approve| E[Apply Changes]\n D -->|Reject| F[Discard Changes]\n```\n\n资料来源：[src/server/infra/http/review-ui.ts:1-60](https://github.com/campfirein/byterover-cli/blob/main/src/server/infra/http/review-ui.ts)\n\n## Installation\n\nInstall ByteRover CLI globally via npm:\n\n```bash\nnpm install -g byterover-cli\n```\n\n资料来源：[src/server/templates/skill/SKILL.md:10-12](https://github.com/campfirein/byterover-cli/blob/main/src/server/templates/skill/SKILL.md)\n\n---\n\n\n\n## Getting Started\n\n### 相关页面\n\n相关主题：[Introduction to ByteRover CLI](#introduction), [WebUI Dashboard](#webui-dashboard)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [scripts/install.sh](https://github.com/campfirein/byterover-cli/blob/main/scripts/install.sh)\n- [bin/run.js](https://github.com/campfirein/byterover-cli/blob/main/bin/run.js)\n- [src/oclif/commands/init.ts](https://github.com/campfirein/byterover-cli/blob/main/src/oclif/commands/init.ts)\n- [README.md](https://github.com/campfirein/byterover-cli/blob/main/README.md)\n- [src/webui/index.html](https://github.com/campfirein/byterover-cli/blob/main/src/webui/index.html)\n\n\n# Getting Started\n\n## Overview\n\nThis page covers the initial setup and onboarding process for ByteRover CLI (`brv`), an interactive REPL CLI that provides AI-powered context memory for coding agents. The getting started workflow includes installation, authentication, and basic configuration to enable persistent, structured memory across development sessions.\n\nByteRover CLI supports multiple installation methods and auto-configures on first run, requiring no manual setup for most use cases. 资料来源：[README.md:1-50]()\n\n## System Requirements\n\n### Supported Platforms\n\n| Platform | Architecture | Installation Method |\n|----------|--------------|---------------------|\n| macOS | ARM64 (Apple Silicon) | Shell script, npm |\n| macOS | x64 (Intel) | Shell script, npm |\n| Linux | x64 | Shell script, npm |\n| Linux | ARM64 | Shell script, npm |\n\n### Prerequisites\n\n- **Node.js**: Version >= 20 required for npm-based installation\n- **curl**: Required for shell script installation\n- **Terminal access**: Required for REPL interaction\n\n资料来源：[README.md:60-80]()\n\n## Installation Methods\n\n### Shell Script Installation (Recommended)\n\nThe shell script installation requires no external dependencies and bundles everything needed for operation.\n\n```bash\ncurl -fsSL https://byterover.dev/install.sh | sh\n```\n\nThis script detects your platform and architecture automatically, downloading the appropriate binary and setting up the `brv` command globally. 资料来源：[scripts/install.sh:1-100]()\n\n#### Installation Script Architecture\n\n```mermaid\ngraph TD\n A[Start install.sh] --> B{Detect Platform}\n B -->|macOS| C{Detect Architecture}\n B -->|Linux| D{Detect Architecture}\n C -->|ARM64| E[Download macOS ARM64 binary]\n C -->|x64| F[Download macOS x64 binary]\n D -->|ARM64| G[Download Linux ARM64 binary]\n D -->|x64| H[Download Linux x64 binary]\n E --> I[Install to PATH]\n F --> I\n G --> I\n H --> I\n I --> J[Verify installation]\n```\n\n### npm Installation\n\nFor environments with Node.js already installed:\n\n```bash\nnpm install -g byterover-cli\n```\n\nThis method installs ByteRover CLI globally, making the `brv` command available system-wide. 资料来源：[README.md:70-75]()\n\n## Verification\n\nAfter installation, verify the setup:\n\n```bash\nbrv --version\n```\n\nA successful response displays the installed version number, confirming the CLI is accessible. 资料来源：[README.md:77-78]()\n\n## First Run and Initialization\n\n### Starting the REPL\n\nNavigate to your project directory and run:\n\n```bash\ncd your/project\nbrv\n```\n\nThe REPL auto-configures on first run without requiring any additional setup steps. 资料来源：[README.md:80-85]()\n\n### Initialization Command\n\nFor explicit initialization or reconfiguration:\n\n```bash\nbrv init\n```\n\nThe init command sets up the local workspace configuration and establishes the connection between your project and ByteRover's context management system. 资料来源：[src/oclif/commands/init.ts:1-100]()\n\n#### Initialization Flow\n\n```mermaid\ngraph LR\n A[brv init] --> B[Load Config]\n B --> C{Config Exists?}\n C -->|No| D[Create Default Config]\n C -->|Yes| E[Validate Config]\n D --> F[Setup Workspace]\n E --> G{Config Valid?}\n G -->|Yes| F\n G -->|No| H[Repair Config]\n H --> F\n F --> I[Initialize Complete]\n```\n\n### CLI Entry Point\n\nThe `bin/run.js` file serves as the entry point for the ByteRover CLI, handling command routing and initialization:\n\n```javascript\n// Simplified entry flow\nconst { run } = await import('./src/index.js')\nawait run(process.argv)\n```\n\nThis file establishes the command-line interface and delegates to the core application logic. 资料来源：[bin/run.js:1-30]()\n\n## Authentication\n\n### ByteRover Cloud Login\n\nTo access cloud sync and collaboration features:\n\n```bash\nbrv login\n```\n\nAuthentication is required for:\n- Syncing context trees to the cloud\n- Sharing knowledge across machines\n- Team collaboration features\n\nWithout authentication, all features work locally. Cloud features are optional enhancements. 资料来源：[README.md:90-100]()\n\n### Authentication Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI\n participant WebUI\n participant AuthServer\n \n User->>CLI: brv login\n CLI->>AuthServer: Initiate OAuth\n AuthServer->>WebUI: Display login page\n User->>WebUI: Enter credentials\n WebUI->>AuthServer: Submit credentials\n AuthServer->>CLI: Authorization token\n CLI->>CLI: Store token securely\n CLI->>User: Login successful\n```\n\n## Quick Start Workflow\n\n### Basic Commands\n\nOnce initialized, use the REPL with natural language or commands:\n\n```\n/curate \"Auth uses JWT with 24h expiry\" @src/middleware/auth.ts\n/query How is authentication implemented?\n```\n\nType `/` to discover all available commands. 资料来源：[README.md:85-88]()\n\n### Context Tree Workflow\n\n```mermaid\ngraph TD\n A[Create Context] --> B{Add Knowledge}\n B -->|File Reference| C[/curate @file]\n B -->|Natural Language| D[/curate \"description\"]\n C --> E[Store in Context Tree]\n D --> E\n E --> F[Generate Abstract]\n F --> G[Index for Search]\n G --> H[Ready for Query]\n \n H --> I{Need Information?}\n I -->|Yes| J[/query question]\n J --> K[Retrieve Relevant Context]\n K --> H\n I -->|No| L[Continue Development]\n L --> A\n```\n\n## Web UI Setup\n\nThe ByteRover Web UI provides a graphical interface for managing context and configurations. It runs locally and is accessible via a local server.\n\n### Web UI Configuration\n\nThe web interface is defined in `src/webui/index.html`:\n\n```html\n\n\n \n \n \n \n ByteRover - Local\n \n \n \n \n \n\n```\n\nThe UI initializes with dark mode enabled by default and serves as the local interface for ByteRover operations. 资料来源：[src/webui/index.html:1-15]()\n\n## Configuration\n\n### Default Configuration\n\nByteRover stores configuration in the local workspace:\n\n| Setting | Default | Description |\n|---------|---------|-------------|\n| Base Path | `.byterover/` | Local storage directory |\n| LLM Provider | Auto-detect | Default LLM for REPL |\n| Context Limit | 100 items | Max context entries |\n\n### Configuration Files\n\nThe initialization process creates:\n- `.byterover/config.json` - Main configuration\n- `.byterover/context/` - Context tree storage\n- `.byterover/logs/` - Operation logs\n\n## Troubleshooting\n\n### Installation Issues\n\n**Problem**: `brv: command not found` after installation\n\n**Solution**: Verify the installation directory is in your PATH. For shell script installation, restart your terminal session.\n\n### Authentication Issues\n\n**Problem**: Cloud features unavailable after login\n\n**Solution**: Check network connectivity and verify OAuth callback completes successfully. The callback server handles authentication at `localhost` with a standard HTTP response. 资料来源：[src/server/infra/http/callback-server.ts:1-50]()\n\n### Initialization Issues\n\n**Problem**: `brv init` fails or hangs\n\n**Solution**: Ensure write permissions in the project directory and no conflicting `.byterover/` directory exists from a previous installation.\n\n## Next Steps\n\nAfter successful installation and initialization:\n\n1. **Explore Commands**: Type `/` in the REPL to see all available commands\n2. **Add Knowledge**: Use `/curate` to add project context\n3. **Query Context**: Use `/query` to retrieve stored information\n4. **Sync to Cloud**: Run `/push` to sync context when authenticated\n\n资料来源：[README.md:80-95]()\n\n---\n\n\n\n## System Architecture Overview\n\n### 相关页面\n\n相关主题：[Agent System](#agent-system), [Context Tree and Knowledge Storage](#context-tree), [LLM Providers](#llm-providers)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/server/templates/README.md](https://github.com/campfirein/byterover-cli/blob/main/src/server/templates/README.md)\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/map/abstract-generator.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/map/abstract-generator.ts)\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/infra/http/review-ui.ts](https://github.com/campfirein/byterover-cli/blob/main/src/server/infra/http/review-ui.ts)\n- [README.md](https://github.com/campfirein/byterover-cli/blob/main/README.md)\n\n\n# System Architecture Overview\n\nByteRover CLI (`brv`) is an interactive REPL CLI that provides AI-powered context memory for coding agents. The system enables developers to curate project knowledge into a context tree, sync it to the cloud, and share it across tools and teammates.\n\n## Architecture Layers\n\nThe ByteRover CLI follows a multi-layered architecture with clear separation of concerns:\n\n| Layer | Description | Key Components |\n|-------|-------------|-----------------|\n| **CLI Layer** | User-facing command interface | `brv` commands, TUI components |\n| **Server Layer** | Background daemon and HTTP services | Daemon process, review UI, template system |\n| **Agent Layer** | AI agent infrastructure | Base agent, curate service, abstract generation |\n| **Transport Layer** | Real-time communication | Socket.IO transport, event system |\n| **Storage Layer** | Knowledge persistence | Context tree, version control |\n\n## Component Architecture\n\n### Server Infrastructure\n\nThe server layer runs as a background daemon process that manages all persistent operations:\n\n```mermaid\ngraph TD\n A[CLI Client] -->|Command| B[Daemon Process]\n B --> C[HTTP Server]\n B --> D[Template Service]\n B --> E[Review UI Generator]\n C --> F[WebUI]\n D --> G[brv gen-rules]\n E --> H[HTML Review Interface]\n```\n\n**Template System** (`src/server/templates/README.md`)\n\nThe template system generates agent instructions via the `brv gen-rules` command. It uses a modular template structure:\n\n```\nsrc/templates/\n├── base.md # Main template structure\n├── sections/ # Reusable content sections\n│ ├── workflow.md # Workflow guide\n│ └── command-reference.md # All BR CLI commands documentation\n└── README.md # This file\n```\n\nTemplate variables include:\n- `{{agent_name}}` - Name of the agent (e.g., \"Claude Code\", \"Cursor\")\n- `{{workflow}}` - Content from workflow.md\n- `{{command_reference}}` - Content from command-reference.md\n\n**Review UI Generator** (`src/server/infra/http/review-ui.ts`)\n\nReturns a self-contained HTML page for local HITL (Human-In-The-Loop) review. All CSS and JS are inline with no external dependencies:\n\n```typescript\nexport function getReviewPageHtml(): string {\n return `\n\n\n\n\n...\n```\n\nThe review UI displays semantic summaries of previous/current versions for each operation.\n\n### Agent Infrastructure\n\nThe agent layer provides AI agent capabilities with persistent memory:\n\n**Curate Service** (`src/agent/infra/sandbox/curate-service.ts`)\n\nThe curate service executes operations on knowledge topics:\n\n```typescript\nexport class CurateService implements ICurateService {\n private readonly workingDirectory: string\n\n async curate(operations: CurateOperation[], options?: CurateOptions): Promise {\n const rawBasePath = options?.basePath ?? DEFAULT_BASE_PATH\n // Resolve relative basePath against the working directory\n```\n\nCurate operations supported:\n| Operation | Requirements |\n|-----------|--------------|\n| `ADD` | title, content (rawConcept and/or narrative) |\n| `UPDATE` | title, content (rawConcept and/or narrative) |\n| `UPSERT` | title, content |\n| `DELETE` | path only |\n\nValidation failures include descriptive messages:\n- `${op.type} operation requires content with rawConcept and/or narrative.`\n- `${op.type} operation requires a title (becomes the .md filename).`\n\n**Abstract Generator** (`src/agent/infra/map/abstract-generator.ts`)\n\nGenerates structured XML overviews of knowledge documents for LLM consumption:\n\n```typescript\nfunction parseBatchedTags(response: string, innerTag: 'abstract' | 'overview'): Map {\n const result = new Map()\n const fileOp...\n```\n\nThe generator produces output format:\n```xml\n\">\n- bullet 1\n- bullet 2\n\n```\n\nOutput includes:\n- Key points (3-7 bullet points)\n- Structure/sections summary\n- Notable entities, patterns, or decisions\n\n### Transport and Event System\n\n**VC Events** (`src/shared/transport/events/vc-events.ts`)\n\nDefines version control event types and diff modes:\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\nDiff modes mirror `git diff`:\n| Mode | Meaning |\n|------|---------|\n| `unstaged` | STAGE → WORKDIR (tracked files only) |\n| `staged` | HEAD → STAGE |\n| `ref-vs-worktree` | `` → WORKDIR |\n| `range` | `` → `` |\n\n**File Status Types:**\n```typescript\nexport type VcDiffFileStatus = 'added' | 'deleted' | 'modified'\n```\n\n### Client Interfaces\n\n**WebUI** (`src/webui/index.html`)\n\nThe main WebUI entry point with dark mode support:\n```html\n\n\n \n \n ByteRover - Local\n \n \n \n \n \n\n```\n\n**Hub Panel** (`src/webui/features/hub/components/hub-panel.tsx`)\n\nDisplays registry entries with agent selection support:\n- Shows entry type, version, and registry\n- Agent target selection dropdown for agent-skill types\n- Install functionality with mutation state\n\n**Offline Screen** (`src/webui/features/transport/components/offline-screen.tsx`)\n\nHandles connection loss scenarios with:\n- Reconnection attempt counter\n- Config error detection\n- Copy-to-clipboard command display\n\n**Task Composer** (`src/webui/features/tasks/components/task-composer.tsx`)\n\nMain task composition interface with:\n- Type-specific input (curate, query, review)\n- Provider flow dialog\n- Keyboard shortcuts (Ctrl+Enter to submit, Tab for examples)\n- Character count display\n\n### Version Control Workflow\n\n```mermaid\ngraph LR\n A[brv vc init] --> B[Version Control Enabled]\n B --> C[brv vc add]\n C --> D[brv vc commit]\n D --> E[brv vc push/pull]\n E --> F[ByteRover Cloud]\n \n G[brv vc branch] --> H[Branch Management]\n H --> I[brv vc merge]\n I --> J[Conflict Resolution]\n J --> D\n```\n\n**VC Commands:**\n| Command | Description |\n|---------|-------------|\n| `brv vc init` | Initialize version control |\n| `brv vc status` | Show VCS status |\n| `brv vc add` | Stage files |\n| `brv vc commit` | Save staged changes |\n| `brv vc log` | Show commit history |\n| `brv vc branch` | List/create/delete branches |\n| `brv vc checkout` | Switch branches |\n| `brv vc merge` | Merge branches |\n| `brv vc push/pull` | Cloud sync operations |\n\n### TUI Components\n\n**Execution Log View** (`src/tui/components/execution/expanded-log-view.tsx`)\n\nDisplays execution output with:\n- Input display with file references (`@filename`)\n- Progress indicators for reasoning and tool calls\n- Streaming text content with cursor animation\n- Error state display\n- File changes summary (created/updated)\n\n**Execution Tool** (`src/tui/components/execution/execution-tool.tsx`)\n\nTool call visualization with status indicators:\n- ✓ for success\n- Blinking circle for running\n- ✗ for failed\n\n### Data Models\n\n**Context Tree Structure**\n\nThe system stores knowledge in a hierarchical context tree:\n\n```yaml\nknowledge/\n├── narrative/\n│ ├── rules.md\n│ ├── highlights.md\n│ ├── examples.md\n│ └── structure.md\n└── rawConcept/\n └── [topic-name]/\n └── [files].md\n```\n\n**Curate Operation Model**\n\n```typescript\ninterface CurateOperation {\n type: 'ADD' | 'UPDATE' | 'UPSERT' | 'DELETE'\n path: string\n title?: string\n content?: {\n rawConcept?: string\n narrative?: {\n rules?: string\n highlights?: string\n examples?: string\n dependencies?: string\n flow?: string\n structure?: string\n }\n }\n}\n```\n\n## Key Design Patterns\n\n1. **Self-Contained Components**: Review UI and templates are self-contained with inline styles and no external dependencies.\n\n2. **Event-Driven Transport**: VC operations use typed event system for real-time updates.\n\n3. **Validation Before Execution**: Curate operations validate requirements before applying changes.\n\n4. **Modular Templates**: Agent instructions generated from composable template sections.\n\n5. **Conflict Detection**: Diff system identifies binary files and text content differences.\n\n## Supported LLM Providers\n\nThe system supports 20+ LLM providers including:\n\n| Provider | Description |\n|----------|-------------|\n| Anthropic | Claude models |\n| OpenAI | GPT models |\n| Google | Gemini models |\n| Groq | Fast inference |\n| Mistral | Mistral models |\n| DeepSeek | DeepSeek V3 and R1 reasoning models |\n| OpenRouter | Multi-provider gateway |\n| Perplexity | Search-augmented models |\n\n资料来源：[README.md:1-100](https://github.com/campfirein/byterover-cli/blob/main/README.md)\n\n---\n\n\n\n## Agent System\n\n### 相关页面\n\n相关主题：[Tool System](#tool-system), [LLM Providers](#llm-providers), [Context Management](#context-management)\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/folder-pack/output-generator.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/folder-pack/output-generator.ts)\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/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/server/templates/skill/SKILL.md](https://github.com/campfirein/byterover-cli/blob/main/src/server/templates/skill/SKILL.md)\n\n\n# Agent System\n\n## Overview\n\nThe Agent System in ByteRover CLI is a modular infrastructure layer that enables AI agents to interact with knowledge bases, execute file operations, and communicate with external services. The system provides abstractions for abstract generation, sandbox curation, and output formatting that support the core agent workflow across both TUI and WebUI interfaces.\n\n## Architecture Overview\n\nThe agent infrastructure is organized into several key modules:\n\n```\nsrc/agent/\n├── infra/\n│ ├── map/ # Abstract generation for knowledge documents\n│ ├── sandbox/ # Curate service for knowledge topic operations\n│ ├── folder-pack/ # Output formatting and XML generation\n│ └── agent/ # Agent implementations\n└── core/\n └── interfaces/ # Core type definitions\n```\n\n## Core Components\n\n### Curate Service\n\nThe `CurateService` is the central orchestrator for knowledge topic operations within the sandbox environment. It implements the `ICurateService` interface and provides curate and domain detection operations.\n\n资料来源：[src/agent/infra/sandbox/curate-service.ts]()\n\n#### Supported Operations\n\nThe curate service supports the following operation types:\n\n| Operation | Description | Requirements |\n|-----------|-------------|--------------|\n| `ADD` | Create a new knowledge topic | `title` required, `rawConcept` and/or `narrative` content |\n| `UPDATE` | Modify existing topic | `title` required, `rawConcept` and/or `narrative` content |\n| `UPSERT` | Insert or update topic | `title` required, `rawConcept` and/or `narrative` content |\n| `DELETE` | Remove a topic | Only `path` required |\n| `MOVE` | Relocate a topic | Only `path` required |\n\n资料来源：[src/agent/infra/sandbox/curate-service.ts:1-50]()\n\n#### Validation Rules\n\nThe curate service enforces strict validation before executing operations:\n\n```typescript\n// ADD, UPDATE, and UPSERT require content with rawConcept and/or narrative\nif ((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, and UPSERT require title\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:1-50]()\n\n#### Constructor Configuration\n\n```typescript\nconstructor(\n workingDirectory?: string,\n private readonly abstractQueue?: AbstractGenerationQueue,\n private readonly runtimeSignalStore?: IRuntimeSignalStore,\n) {\n this.workingDirectory = workingDirectory ?? process.cwd()\n}\n```\n\nThe service resolves relative `basePath` against the working directory to ensure consistent file system operations.\n\n### Abstract Generation\n\nThe `AbstractGenerationQueue` and abstract generators produce structured overviews of knowledge documents for efficient LLM context consumption.\n\n资料来源：[src/agent/infra/map/abstract-generator.ts]()\n\n#### Generation Prompt Structure\n\nThe abstract generator creates XML-formatted prompts for LLM processing:\n\n```xml\n\">\n- bullet 1\n- bullet 2\n...\n\n```\n\nEach overview includes:\n- **Key points**: 3-7 bullet points\n- **Structure/sections summary**: Document organization\n- **Notable entities, patterns, or decisions**: Important technical details\n\n#### Parsing Strategy\n\nThe parser uses a tolerant approach for extracting `` and `` tags:\n\n```typescript\nfunction parseBatchedTags(response: string, innerTag: 'abstract' | 'overview'): Map\n```\n\nThe implementation is anchored on `` openers rather than closing tags, preventing issues when model output contains literal `` strings (common in documentation about XML, JSX, or build systems).\n\n资料来源：[src/agent/infra/map/abstract-generator.ts:40-70]()\n\n### Output Generator\n\nThe folder-pack output generator formats results as XML for system responses, supporting both configuration metadata and file content representation.\n\n资料来源：[src/agent/infra/folder-pack/output-generator.ts]()\n\n#### XML Output Structure\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#### File Type Statistics\n\nThe generator tracks file type distribution:\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## Agent-Skill Integration\n\nThe Agent System integrates with the Hub for agent-skill management. When installing an agent-skill, users can select the target agent.\n\n资料来源：[src/webui/features/hub/components/hub-panel.tsx:20-40]()\n\n### Agent Selection Component\n\n```tsx\n{entry.type === 'agent-skill' ? (\n
\n) : null}\n```\n\nThe default agent is \"Codex\", and available agents are defined in `AGENT_VALUES`.\n\n## Execution Monitoring\n\n### TUI Tool Display\n\nThe execution tool component provides real-time status visualization:\n\n```tsx\n{toolCall.status === 'completed' && ✓ }\n{toolCall.status === 'running' && }\n{toolCall.status === 'failed' && ✗ }\n```\n\n资料来源：[src/tui/components/execution/execution-tool.tsx:1-30]()\n\n### Log Streaming\n\nThe expanded log view handles multiple content types:\n\n| Content Type | Trigger Condition | Display |\n|--------------|-------------------|---------|\n| Streaming content | `status === 'running'` | Real-time streaming with cursor |\n| Error content | `status === 'failed'` | Error-styled output |\n| Completion content | `status === 'completed'` | Standard output display |\n| Changes | `status === 'completed'` | Created/updated file diffs |\n\n资料来源：[src/tui/components/execution/expanded-log-view.tsx:20-50]()\n\n### Change Tracking\n\nExecution results include detailed change tracking:\n\n```tsx\n\n```\n\n## Version Control Integration\n\nThe Agent System integrates with ByteRover's version control capabilities. Skills include comprehensive VC documentation covering:\n\n- **Staging**: `brv vc add .`, `brv vc add notes.md docs/`\n- **Committing**: `brv vc commit -m \"message\"`\n- **History**: `brv vc log`, `brv vc log --limit 20`, `brv vc log --all`\n- **Branching**: `brv vc branch`, `brv vc checkout`, `brv vc merge`\n- **Cloud sync**: Remote operations via `brv vc remote`\n\n资料来源：[src/server/templates/skill/SKILL.md:1-60]()\n\n## Data Flow\n\n```mermaid\ngraph TD\n A[User Request] --> B[CurateService]\n B --> C{Validate Operations}\n C -->|Valid| D[Execute Operations]\n C -->|Invalid| E[Return Failures]\n D --> F[AbstractGenerationQueue]\n F --> G[LLM Abstract Generation]\n G --> H[OutputGenerator]\n H --> I[XML Response]\n D --> J[File System Changes]\n J --> K[Log Streaming to TUI]\n K --> L[Execution Changes Display]\n```\n\n## Key Interfaces\n\n### CurateResult\n\n```typescript\ninterface CurateResult {\n operations: CurateOperation[]\n failures: CurateFailure[]\n basePath: string\n}\n```\n\n### CurateOperation\n\n```typescript\ninterface CurateOperation {\n type: 'ADD' | 'UPDATE' | 'UPSERT' | 'DELETE' | 'MOVE'\n path: string\n title?: string\n content?: {\n rawConcept?: string\n narrative?: string\n }\n}\n```\n\n## Summary\n\nThe ByteRover Agent System provides a comprehensive infrastructure for:\n\n1. **Knowledge curation**: Add, update, delete, and move knowledge topics with validation\n2. **Abstract generation**: Create LLM-friendly summaries of document collections\n3. **Output formatting**: XML-based structured output for system responses\n4. **Execution monitoring**: Real-time status, streaming logs, and change tracking\n5. **Agent-skill management**: Install and configure skills for different agents\n\nAll components are designed for integration across TUI and WebUI interfaces, providing consistent agent behavior regardless of the user interface preference.\n\n---\n\n\n\n## Tool System\n\n### 相关页面\n\n相关主题：[Agent System](#agent-system), [Context Tree and Knowledge Storage](#context-tree)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/agent/core/domain/tools/types.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/core/domain/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/search-knowledge-tool.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/implementations/search-knowledge-tool.ts)\n- [src/agent/resources/tools/bash_exec.txt](https://github.com/campfirein/byterover-cli/blob/main/src/agent/resources/tools/bash_exec.txt)\n\n\n# Tool System\n\n## Overview\n\nThe Tool System in ByteRover CLI provides a structured mechanism for AI agents to interact with the filesystem, execute commands, and manage project knowledge. It serves as the bridge between the AI agent's decision-making capabilities and concrete operations on the user's project.\n\nThe system follows a modular architecture with clear separation between tool definitions, registration, management, scheduling, and execution. This design enables extensibility, testability, and consistent behavior across different tool implementations.\n\n## Architecture\n\n```mermaid\ngraph TD\n A[Agent Request] --> B[Tool Manager]\n B --> C[Tool Registry]\n C --> D[Core Tool Scheduler]\n D --> E[Tool Implementations]\n \n E --> F[Read File Tool]\n E --> G[Write File Tool]\n E --> H[Search Knowledge Tool]\n E --> I[Bash Exec Tool]\n \n J[Resources] --> F\n J --> G\n J --> H\n J --> I\n```\n\n## Core Components\n\n### Tool Types\n\nThe foundation of the Tool System is defined in `types.ts`. Tools are typed according to their operational scope and execution requirements.\n\n| Type Category | Description |\n|--------------|-------------|\n| `filesystem` | File read, write, and manipulation operations |\n| `execution` | Command execution and process management |\n| `knowledge` | Context tree and knowledge management operations |\n| `search` | File searching and grep operations |\n\n### Tool Registry\n\nThe `ToolRegistry` maintains a centralized catalog of all available tools and their metadata.\n\n**Key Responsibilities:**\n\n- Register tool definitions with unique identifiers\n- Provide tool lookup by name\n- Validate tool availability\n- Track tool metadata (name, description, parameters)\n\n```typescript\n资料来源：[src/agent/infra/tools/tool-registry.ts]()\n```\n\n### Tool Manager\n\nThe `ToolManager` orchestrates tool operations and handles the lifecycle of tool invocations.\n\n**Key Responsibilities:**\n\n- Initialize and configure tools\n- Route tool requests to appropriate implementations\n- Handle tool input/output serialization\n- Manage tool state across execution cycles\n\n```typescript\n资料来源：[src/agent/infra/tools/tool-manager.ts]()\n```\n\n### Core Tool Scheduler\n\nThe `CoreToolScheduler` manages the scheduling and execution order of tool calls.\n\n**Key Responsibilities:**\n\n- Queue tool execution requests\n- Handle concurrent tool execution limits\n- Manage tool timeout and cancellation\n- Coordinate with sandbox execution environment\n\n```typescript\n资料来源：[src/agent/infra/tools/core-tool-scheduler.ts]()\n```\n\n## Tool Implementations\n\n### Read File Tool\n\nProvides filesystem read capabilities with support for:\n\n- Full file content retrieval\n- Line range specification\n- Encoding handling\n- Truncation for large files\n\n```typescript\n资料来源：[src/agent/infra/tools/implementations/read-file-tool.ts]()\n```\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `path` | string | Yes | Absolute or relative file path |\n| `startLine` | number | No | Starting line number (1-indexed) |\n| `endLine` | number | No | Ending line number |\n| `maxSize` | string | No | Maximum file size (e.g., \"100KB\") |\n\n### Write File Tool\n\nHandles file creation and modification operations.\n\n**Capabilities:**\n\n- Create new files with content\n- Overwrite existing files\n- Create parent directories as needed\n- Preserve or truncate existing content\n\n```typescript\n资料来源：[src/agent/infra/tools/implementations/write-file-tool.ts]()\n```\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `path` | string | Yes | Target file path |\n| `content` | string | Yes | File content to write |\n| `append` | boolean | No | Append mode (default: false) |\n\n### Search Knowledge Tool\n\nEnables querying the agent's knowledge base and context tree.\n\n**Features:**\n\n- Semantic search across curated knowledge\n- Domain and topic filtering\n- Relevance ranking\n- Context-aware results\n\n```typescript\n资料来源：[src/agent/infra/tools/implementations/search-knowledge-tool.ts]()\n```\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `query` | string | Yes | Search query string |\n| `domain` | string | No | Filter by knowledge domain |\n| `limit` | number | No | Maximum results (default: 10) |\n\n### Bash Exec Tool\n\nProvides shell command execution capabilities within the sandboxed environment.\n\n**Resources:**\n\n- Execution context configuration\n- Working directory management\n- Environment variable handling\n- Timeout and resource limits\n\n```typescript\n资料来源：[src/agent/resources/tools/bash_exec.txt]()\n```\n\n## Execution Flow\n\n```mermaid\nsequenceDiagram\n participant A as Agent\n participant M as Tool Manager\n participant R as Tool Registry\n participant S as Core Scheduler\n participant T as Tool Impl\n \n A->>M: Request tool call\n M->>R: Lookup tool definition\n R-->>M: Tool spec\n M->>S: Schedule execution\n S->>T: Execute with params\n T-->>S: Execution result\n S-->>M: Result with status\n M-->>A: Tool response\n```\n\n## Tool Call States\n\nDuring execution, tool calls progress through the following states:\n\n| Status | Description |\n|--------|-------------|\n| `pending` | Tool call queued, awaiting execution |\n| `running` | Tool currently executing |\n| `completed` | Tool finished successfully |\n| `failed` | Tool execution encountered an error |\n\n```typescript\n// Example tool call representation\n{\n id: \"tool_123\",\n name: \"readFile\",\n status: \"running\",\n arguments: { path: \"./src/index.ts\" },\n startTime: 1699900000000\n}\n```\n\n## Integration Points\n\n### Sandbox Integration\n\nTools execute within a sandboxed environment that provides:\n\n- Isolated filesystem access\n- Controlled command execution\n- Resource quota management\n- Audit logging\n\n### TUI Components\n\nThe execution UI displays tool calls with real-time status updates:\n\n```typescript\n资料来源：[src/tui/components/execution/execution-tool.tsx]()\n```\n\n**Display Elements:**\n\n- Status indicator (✓ running ✗)\n- Tool name\n- Tool arguments (when expanded)\n- Progress indicators\n\n### Curate Service Integration\n\nThe Tool System integrates with the Curate Service for knowledge operations:\n\n```typescript\n资料来源：[src/agent/infra/sandbox/curate-service.ts]()\n```\n\nSupported operations:\n\n| Operation | Description |\n|-----------|-------------|\n| `ADD` | Create new knowledge entry |\n| `UPDATE` | Modify existing entry |\n| `UPSERT` | Update or create entry |\n| `DELETE` | Remove knowledge entry |\n| `MOVE` | Relocate entry within tree |\n\n## Configuration\n\nTool behavior can be configured through the agent's runtime configuration:\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `maxFileSize` | Configured | Maximum file size for read operations |\n| `maxLinesPerFile` | Configured | Line limit for file reads |\n| `timeout` | Configured | Tool execution timeout |\n| `customIgnores` | [] | Patterns to exclude from operations |\n\n## Error Handling\n\nTool failures are categorized and reported:\n\n```typescript\ninterface ToolFailure {\n message: string;\n path?: string;\n status: 'failed';\n type: string;\n}\n```\n\nCommon failure scenarios:\n\n- **File not found**: Path does not exist or is inaccessible\n- **Permission denied**: Insufficient filesystem permissions\n- **Timeout**: Operation exceeded configured time limit\n- **Invalid parameters**: Tool arguments validation failed\n\n## Best Practices\n\n1. **Always validate paths** before passing to tools\n2. **Use line ranges** for large files to avoid memory issues\n3. **Check tool availability** before assuming capabilities\n4. **Handle failures gracefully** with appropriate user feedback\n5. **Log tool usage** for audit and debugging purposes\n\n---\n\n\n\n## LLM Providers\n\n### 相关页面\n\n相关主题：[Context Management](#context-management), [Agent System](#agent-system)\n\n\nRelated Source Files\n\nThe following source files were requested but were NOT included in the provided repository context:\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/model-capabilities.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/llm/model-capabilities.ts)\n- [src/agent/core/domain/llm/types.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/core/domain/llm/types.ts)\n\nThe following available context files provide supplementary information:\n\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- [src/server/templates/skill/SKILL.md](https://github.com/campfirein/byterover-cli/blob/main/src/server/templates/skill/SKILL.md)\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- [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\n\n\n# LLM Providers\n\n> **Note:** The specific LLM Provider implementation files were not included in the available repository context. This page provides an architectural overview based on patterns observable in the codebase and general ByteRover CLI architecture. For complete implementation details, refer to the actual source files listed above.\n\n## Overview\n\nThe LLM Providers system in ByteRover CLI provides an abstraction layer for interacting with various Large Language Model APIs. This design allows the CLI to support multiple LLM backends (Anthropic, OpenAI, Google) through a unified interface while enabling provider-specific configuration and capabilities.\n\nThe system is located under `src/agent/infra/llm/` and follows a modular architecture with separate provider implementations.\n\n## Architecture\n\n```mermaid\ngraph TD\n subgraph \"LLM Layer\"\n ALS[Agent LLM Service]\n MC[Model Capabilities]\n T[Types/Domain]\n end\n \n subgraph \"Providers\"\n P_INDEX[Provider Index]\n ANTH[Anthropic Provider]\n OAI[OpenAI Provider]\n GGLE[Google Provider]\n end\n \n ALS --> MC\n ALS --> T\n ALS --> P_INDEX\n P_INDEX --> ANTH\n P_INDEX --> OAI\n P_INDEX --> GGLE\n \n subgraph \"External APIs\"\n ANTH_API[Anthropic API]\n OAI_API[OpenAI API]\n GGLE_API[Google API]\n end\n \n ANTH --> ANTH_API\n OAI --> OAI_API\n GGLE --> GGLE_API\n```\n\n## Provider Types\n\nBased on the codebase structure, ByteRover CLI supports the following LLM providers:\n\n| Provider | File | Description |\n|----------|------|-------------|\n| Anthropic | `providers/anthropic.ts` | Claude models via Anthropic API |\n| OpenAI | `providers/openai.ts` | GPT models via OpenAI API |\n| Google | `providers/google.ts` | Gemini models via Google AI API |\n\n## Core Components\n\n### Provider Index (`providers/index.ts`)\n\nThe provider index exports a unified interface for all LLM providers. This module serves as the entry point for provider selection and instantiation.\n\n### Model Capabilities (`model-capabilities.ts`)\n\nDefines the capabilities and characteristics of supported models, including:\n\n- Context window size\n- Token limits\n- Supported features (streaming, function calling, vision)\n- Pricing tiers\n\n### Domain Types (`core/domain/llm/types.ts`)\n\nTypeScript type definitions for:\n\n- LLM request/response structures\n- Model configuration options\n- Provider-specific parameters\n- Streaming response types\n\n### Agent LLM Service (`agent-llm-service.ts`)\n\nThe main service that orchestrates LLM interactions:\n\n- Routes requests to appropriate providers\n- Handles authentication and API key management\n- Manages request/response streaming\n- Implements retry logic and error handling\n\n## Request Flow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant ALLS as Agent LLM Service\n participant PI as Provider Index\n participant Provider\n participant API as External API\n \n Client->>ALLS: LLM Request\n ALLS->>PI: Select Provider\n PI->>Provider: Instantiate Provider\n Provider->>API: API Request\n API-->>Provider: API Response\n Provider-->>PI: Normalized Response\n PI-->>ALLS: Standardized Response\n ALLS-->>Client: Result\n```\n\n## Configuration\n\nLLM providers are configured through environment variables and ByteRover configuration files:\n\n```bash\n# Provider API Keys\nANTHROPIC_API_KEY=sk-ant-...\nOPENAI_API_KEY=sk-...\nGOOGLE_API_KEY=...\n\n# Model Selection\nBYTEROVER_MODEL=claude-sonnet-4-20250514\n```\n\n## Integration with WebUI\n\nThe Hub panel component allows users to select target agents when working with agent-skills:\n\n```tsx\n\n setAgentSelections((current) => ({...current, [entry.id]: event.target.value}))\n }\n value={agentSelections[entry.id] ?? 'Codex'}\n>\n {AGENT_VALUES.map((agent) => (\n \n ))}\n\n```\n\n资料来源：[src/webui/features/hub/components/hub-panel.tsx:47-62]()\n\n## Usage Patterns\n\n### Context Tree Integration\n\nThe LLM providers are used extensively by the agent system for:\n\n- Abstract generation from documents\n- Context tree summarization\n- Knowledge curation and extraction\n- Agent instruction generation\n\n资料来源：[src/agent/infra/map/abstract-generator.ts]()\n资料来源：[src/agent/infra/folder-pack/output-generator.ts]()\n\n### Agent Skill Templates\n\nAgent skills can reference LLM provider configurations through templates:\n\n资料来源：[src/server/templates/skill/SKILL.md]()\n\n## Security Considerations\n\n- API keys are managed through secure credential storage\n- Provider authentication is handled by the Agent LLM Service\n- No raw API keys are exposed in logs or user-facing output\n\n## Extending Providers\n\nTo add a new LLM provider:\n\n1. Create a new provider file under `src/agent/infra/llm/providers/`\n2. Implement the provider interface with:\n - `chat()` method for non-streaming requests\n - `stream()` method for streaming responses\n - Authentication handling\n - Error mapping\n3. Export the provider from `providers/index.ts`\n4. Add model capability definitions in `model-capabilities.ts`\n5. Add type definitions in `core/domain/llm/types.ts`\n\n## Error Handling\n\nThe system handles provider-specific errors through:\n\n- Standardized error types in the domain layer\n- Provider-specific error mapping\n- Retry logic for transient failures\n- Graceful degradation when providers are unavailable\n\n## Related Documentation\n\n- [Agent System Overview](#)\n- [Context Tree Management](#)\n- [Hub and Skills Registry](#)\n- [WebUI Components](#)\n\n---\n\n\n\n## Context Management\n\n### 相关页面\n\n相关主题：[LLM Providers](#llm-providers), [Agent System](#agent-system)\n\n\nRelevant Source Files\n\nThe following source files were used to generate this documentation page:\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/folder-pack/output-generator.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/folder-pack/output-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/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/tui/components/execution/execution-tool.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/tui/components/execution/execution-tool.tsx)\n- [src/server/templates/skill/SKILL.md](https://github.com/campfirein/byterover-cli/blob/main/src/server/templates/skill/SKILL.md)\n\n\n# Context Management\n\n## Overview\n\nContext Management in ByteRover CLI encompasses the systems responsible for organizing, compressing, and managing information that flows between the AI agent and the file system. This system handles knowledge document processing, context tree packaging, and workspace-aware memory retrieval.\n\nThe ByteRover CLI uses a layered approach to context management:\n\n1. **Knowledge Document Processing** - Parsing and abstracting file contents for LLM consumption\n2. **Context Tree Packaging** - Converting project structures into compact, token-efficient representations\n3. **Workspace Memory** - Storing and retrieving contextual information about projects\n4. **Compression Strategies** - Reducing context size while preserving critical information\n\n---\n\n## Core Components\n\n### Abstract Generator\n\nThe abstract generator processes knowledge documents and produces structured markdown overviews for LLM context.\n\n**Location:** `src/agent/infra/map/abstract-generator.ts`\n\n**Key Responsibilities:**\n- Wrap file contents in CDATA sections for safe XML embedding\n- Generate structured overviews with key points, structure summaries, and notable entities\n- Parse batched tags from model responses using anchored regex matching\n\n**Prompt Generation Function:**\n```typescript\n// Generates a prompt instructing the LLM to produce structured overviews\n// Output format: ...\n```\n\n**XML Output Structure:**\n```xml\n\n \n \n - bullet 1\n - bullet 2\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\n### Folder Pack Output Generator\n\nHandles the XML serialization of packed folder structures for context embedding.\n\n**Location:** `src/agent/infra/folder-pack/output-generator.ts`\n\n**Output Structure:**\n\n| Section | Description |\n|---------|-------------|\n| `` | Contains max file size, max lines per file, and custom ignore patterns |\n| `` | CDATA-wrapped directory tree representation |\n| `` | Individual file entries with metadata |\n| `` | Files excluded due to size limits or ignore patterns |\n| `` | Aggregated statistics and descriptions |\n\n**Configuration Parameters:**\n\n| Parameter | Description |\n|-----------|-------------|\n| `maxFileSize` | Maximum file size in bytes |\n| `maxLinesPerFile` | Maximum lines per file |\n| `ignore` | Array of glob patterns to exclude |\n\n**File Entry Format:**\n```xml\n\n \n\n```\n\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\n## Context Tree Workflow\n\nThe context tree system provides a hierarchical approach to managing project context:\n\n```mermaid\ngraph TD\n A[User Command] --> B[Context Manager]\n B --> C[Knowledge Documents]\n B --> D[Folder Pack]\n C --> E[Abstract Generator]\n E --> F[Structured Overviews]\n D --> G[XML Output]\n F --> H[LLM Context]\n G --> H\n H --> I[Agent Response]\n \n J[Curate Operations] --> K[Curate Service]\n K --> L[Knowledge Topics]\n L --> M[Workspace Memory]\n```\n\n---\n\n## Curate Service\n\nThe curate service manages knowledge topics within the sandbox environment.\n\n**Location:** `src/agent/infra/sandbox/curate-service.ts`\n\n**Operation Types:**\n\n| Operation | Description | Required Fields |\n|-----------|-------------|-----------------|\n| `ADD` | Add new knowledge topic | `title`, `content.rawConcept` or `content.narrative` |\n| `UPDATE` | Modify existing topic | `path`, `title`, content fields |\n| `UPSERT` | Add or update topic | `path`, `title`, content fields |\n| `DELETE` | Remove topic | `path` |\n\n**Validation Rules:**\n- `ADD`, `UPDATE`, and `UPSERT` operations require both content (rawConcept and/or narrative) and title\n- Title becomes the `.md` filename for the knowledge document\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## Version Control Context Integration\n\nByteRover CLI integrates version control information into the context management system:\n\n**History Panel Component:** `src/webui/features/context/components/context-history-panel.tsx`\n\n**Commit Timeline Display:**\n- Shows current commit with active state indicator\n- Displays older commits in a scrollable timeline\n- Formats timestamps as `MMM d, HH:mm`\n\n```typescript\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](https://github.com/campfirein/byterover-cli/blob/main/src/webui/features/context/components/context-history-panel.tsx)\n\n---\n\n## Transport Layer Context\n\nThe transport layer manages real-time context synchronization between client and server:\n\n**Offline Screen Component:** `src/webui/features/transport/components/offline-screen.tsx`\n\n**States:**\n\n| State | Indicator | Action |\n|-------|-----------|--------|\n| Config Error | `Unreachable` pill (destructive) | Show refresh message |\n| Offline | `Offline` pill (warning) | Show reconnecting status with attempt counter |\n\n**Reconnection Display:**\n```\n●● Reconnecting · attempt 3\n```\n\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\n---\n\n## Command Reference\n\n### Version Control Commands\n\nFrom the SKILL template (`src/server/templates/skill/SKILL.md`):\n\n| Command | Description |\n|---------|-------------|\n| `brv vc add ` | Stage files for commit |\n| `brv vc commit -m ` | Commit staged changes |\n| `brv vc log` | View commit history |\n| `brv vc reset` | Unstage changes |\n| `brv vc branch` | List/create branches |\n| `brv vc checkout` | Switch branches |\n| `brv vc merge` | Merge branches |\n\n资料来源：[src/server/templates/skill/SKILL.md](https://github.com/campfirein/byterover-cli/blob/main/src/server/templates/skill/SKILL.md)\n\n---\n\n## Task Execution Context\n\nTool execution within the context tree:\n\n**Execution Tool Component:** `src/tui/components/execution/execution-tool.tsx`\n\n**Status Indicators:**\n\n| Status | Icon | Color |\n|--------|------|-------|\n| `completed` | ✓ | `colors.primary` |\n| `running` | ● (blinking) | `colors.dimText` |\n| `failed` | ✗ | `colors.errorText` |\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## Architecture Summary\n\n```mermaid\ngraph TD\n subgraph \"Client Layer\"\n TUI[TUI Components]\n WebUI[WebUI Components]\n end\n \n subgraph \"Agent Layer\"\n CM[Context Manager]\n AG[Abstract Generator]\n CS[Curate Service]\n end\n \n subgraph \"Compression Layer\"\n PRE[Pre-compaction Service]\n COMP[Compaction Service]\n end\n \n subgraph \"Output Layer\"\n FG[Folder Pack Generator]\n XML[XML Formatter]\n end\n \n TUI --> CM\n WebUI --> CM\n CM --> AG\n CM --> CS\n CM --> PRE\n PRE --> COMP\n AG --> FG\n CS --> FG\n COMP --> FG\n FG --> XML\n XML --> LLM[LLM Context]\n```\n\n---\n\n## Summary\n\nContext Management in ByteRover CLI provides a comprehensive system for:\n\n1. **Document Abstraction** - Converting files into LLM-digestible summaries\n2. **Structured Packaging** - Organizing project data into compact XML representations\n3. **Knowledge Curation** - Managing persistent workspace knowledge\n4. **Real-time Sync** - Maintaining context coherence across transport states\n5. **VC Integration** - Embedding version control history into the context\n\nThe system is designed to maximize useful context while respecting token limits, using validation-driven operations and XML-based serialization for reliable parsing.\n\n---\n\n\n\n## Context Tree and Knowledge Storage\n\n### 相关页面\n\n相关主题：[Version Control for Context](#version-control), [Tool System](#tool-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/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/infra/sandbox/curate-service.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/sandbox/curate-service.ts)\n- [src/agent/infra/map/abstract-queue.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/map/abstract-queue.ts)\n- [src/agent/infra/tools/implementations/expand-knowledge-tool.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/implementations/expand-knowledge-tool.ts)\n- [src/shared/transport/events/vc-events.ts](https://github.com/campfirein/byterover-cli/blob/main/src/shared/transport/events/vc-events.ts)\n\n\n# Context Tree and Knowledge Storage\n\nThe Context Tree is ByteRover's hierarchical knowledge management system that organizes curated information into a structured, searchable repository within each project. It serves as the long-term memory layer for the agent, enabling persistent storage and retrieval of domain-specific knowledge, architectural decisions, patterns, and operational insights.\n\n## Architecture Overview\n\nThe Context Tree operates as a file-based knowledge store where each piece of curated information is persisted as a Markdown document within the `.brv/context-tree/` directory structure. The system combines human-readable file storage with automated processing for summaries and overviews.\n\n```mermaid\ngraph TD\n A[User/Agent] -->|Curate Operations| B[CurateService]\n B --> C[File System: .brv/context-tree/]\n \n C --> D[Domains]\n D --> E[Topics]\n E --> F[context.md files]\n E --> G[Subfolders with context.md]\n \n H[AbstractGenerationQueue] -->|Background Processing| I[.abstract.md files]\n I --> J[_index.md auto-summaries]\n \n K[Search/Query] -->|Retrieve| L[expand-knowledge-tool]\n L --> F\n L --> J\n L -->|_archived| M[Archived Entries]\n```\n\n## Directory Structure\n\nThe Context Tree follows a predictable directory hierarchy that enables both human navigation and programmatic access.\n\n| Element | Type | Description |\n|---------|------|-------------|\n| `domains` | Directory | Top-level folders representing knowledge areas |\n| `context.md` | File | Primary knowledge content within topics |\n| `.overview.md` | File | L1 structured overview for quick retrieval |\n| `.abstract.md` | File | One-line summary of the content |\n| `_index.md` | File | Auto-generated directory summaries |\n| `_archived/` | Directory | Archived low-importance entries |\n\n资料来源：[context-tree-structure-contributor.ts:32-45]()\n\n### Domain Organization\n\nDomains are dynamically created based on the semantics of curated content. Domain names use `snake_case` naming convention (e.g., `architecture`, `market_trends`, `risk_analysis`). Before creating a new domain, the system checks whether existing domains could accommodate the new content to prevent fragmentation.\n\n## Curate Operations\n\nThe curation system supports a comprehensive set of operations for managing knowledge entries. These operations are validated and executed through `CurateService`.\n\n### Supported Operation Types\n\n| Operation | Description | Required Fields |\n|-----------|-------------|-----------------|\n| `ADD` | Create new knowledge entry | `title`, `content` (rawConcept and/or narrative) |\n| `UPDATE` | Modify existing entry | `path`, `title`, `content` |\n| `UPSERT` | Update or create entry | `path`, `title`, `content` |\n| `DELETE` | Remove knowledge entry | `path` |\n| `ARCHIVE` | Move to archived storage | `path` |\n| `RESTORE` | Recover from archive | `path` |\n\n资料来源：[curate-service.ts:35-55]()\n\n### Validation Rules\n\nThe curate service enforces strict validation before executing operations:\n\n1. **Content requirement**: `ADD`, `UPDATE`, and `UPSERT` operations must include content with either `rawConcept` and/or `narrative` fields\n2. **Title requirement**: These operations must also include a `title` field that becomes the `.md` filename\n3. **Path validation**: Paths outside the project root are rejected\n\n```mermaid\ngraph LR\n A[CurateOperation] --> B{Valid?}\n B -->|Missing Content| C[FAIL: operation requires content]\n B -->|Missing Title| D[FAIL: operation requires title]\n B -->|Valid| E[Execute Operation]\n E --> F[Write to .brv/context-tree/]\n F --> G[Trigger Abstract Generation Queue]\n```\n\n## Abstract Generation System\n\nThe abstract generation system provides automated summarization of curated knowledge entries. It operates asynchronously through a queue-based architecture.\n\n### Generation Types\n\n| Type | Purpose | Token Limit |\n|------|---------|-------------|\n| `abstract` | One-line summary | Max 80 tokens |\n| `overview` | Structured markdown | Under 1500 tokens |\n\nThe abstract captures the core topic and key insight in a single complete sentence, while the overview provides detailed structure including key points (3-7 bullets), section summaries, and notable entities or decisions.\n\n资料来源：[abstract-generator.ts:40-65]()\n\n### Batched Prompt Building\n\nThe system processes files in batches using XML-formatted prompts with CDATA wrapping to safely handle special characters:\n\n```xml\n\n\n\n```\n\nThe `wrapCdata` function uses a standard CDATA-in-CDATA escape technique:\n\n```typescript\nfunction wrapCdata(content: string): string {\n return `', ']]]]>')}]]>`\n}\n```\n\n资料来源：[abstract-generator.ts:30-35]()\n\n### Response Parsing\n\nThe parser extracts `` or `` tags from model responses using a robust regex approach anchored on `` openers rather than closing tags. This prevents premature termination when the content naturally contains `` sequences (common in documentation about XML, JSX, or build systems).\n\n```mermaid\ngraph TD\n A[Model Response] --> B{Scan for }\n B -->|Found| C[Extract slice to next opener]\n C --> D[Extract inner tag content]\n D --> E[Map path to content]\n B -->|Not found| F[End of parsing]\n```\n\n## Abstract Generation Queue\n\nThe `AbstractGenerationQueue` class manages background abstract generation with reliability features.\n\n### Queue Architecture\n\n| Feature | Description |\n|---------|-------------|\n| Batch processing | Processes files in configurable batch sizes |\n| Retry logic | Automatic retry with backoff for failed generations |\n| Status tracking | Real-time monitoring of pending, processing, and completed items |\n| Drain handling | Graceful shutdown with partial batch processing |\n\n### Queue Status\n\nThe queue exposes status through the `AbstractQueueStatus` interface:\n\n```typescript\ninterface AbstractQueueStatus {\n failed: number // Items that failed after all retries\n pending: number // Items waiting to be processed (including retry backoff)\n processed: number // Successfully processed items\n processing: number // Currently being processed\n}\n```\n\n### File Filtering\n\nThe queue automatically filters out certain file types to avoid generating redundant abstracts:\n\n- `context.md` files (hierarchy scaffolding)\n- `_index.md` files (auto-generated summaries)\n- `.abstract.md` files (output files themselves)\n- `.overview.md` files (output files themselves)\n\n资料来源：[abstract-queue.ts:25-35]()\n\n## Knowledge Retrieval\n\nByteRover provides multiple mechanisms for retrieving stored knowledge during agent operations.\n\n### Expand Knowledge Tool\n\nThe `expand-knowledge-tool` enables retrieval of content from the Context Tree through two primary modes:\n\n| Mode | Use Case | Behavior |\n|------|----------|----------|\n| `stubPath` | Archive drill-down | Retrieves full content from archived entries |\n| `overviewPath` | Quick overview | Retrieves L1 structured overview from `.overview.md` sibling files |\n\n```typescript\ninterface ExpandKnowledgeToolConfig {\n baseDirectory?: string // Custom base directory\n runtimeSignalStore?: IRuntimeSignalStore // Signal handling\n}\n```\n\nThe tool description clearly identifies its purpose:\n\n> \"Retrieve full content from archived knowledge entries or L1 overview files. Use stubPath when search results include an archive_stub that you need to drill into. Use overviewPath to retrieve the structured overview for a context entry.\"\n\n资料来源：[expand-knowledge-tool.ts:40-60]()\n\n### Query Commands\n\nQuery commands search **only within the Context Tree structure**, not the entire project. This ensures focused knowledge retrieval without noise from source code or unrelated files.\n\n### Knowledge Path Resolution\n\nThe system resolves knowledge paths relative to the project root (`.brv/context-tree/`), ensuring isolation from arbitrary file system access. Files outside this directory are not accessible through the knowledge system.\n\n## Storage Format\n\n### Knowledge File Structure\n\nIndividual knowledge entries are stored as Markdown files with structured frontmatter:\n\n```markdown\n# Title\n\n## Core Concept\n[rawConcept content]\n\n## Narrative\n[narrative content]\n\n## Metadata\n- Created: timestamp\n- Tags: [domain, topic]\n```\n\n### Archive Format\n\nArchived entries are stored in `_archived/` subdirectories, maintaining the same file structure but segregated for reduced visibility in default queries. The `expand_knowledge` command with `stubPath` is required to drill into archived content.\n\n## Integration Points\n\n### With Agent System\n\nThe Context Tree integrates with the agent's query and curate capabilities through the swarm coordinator, enabling:\n\n- Dynamic domain creation based on content semantics\n- Conflict detection between new and existing knowledge\n- Memory scoring for relevance-based retrieval\n\n### With Version Control\n\nThe `.brv/context-tree/` directory is designed for version control integration:\n\n- Files are human-readable Markdown\n- Standard git operations apply\n- Cloud sync via `brv vc push` and `brv vc pull` supports knowledge collaboration\n\n### With Sandbox Execution\n\nThe curate service runs within sandboxed environments, providing controlled access to the knowledge system. Operations are validated before execution, and results are tracked for audit purposes.\n\n## Configuration Options\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `basePath` | `.brv/context-tree/` | Root directory for knowledge storage |\n| `BATCH_SIZE_CAP` | Varies | Maximum items per abstract generation batch |\n| `max_file_size` | Configurable | Maximum file size for ingestion |\n| `max_lines_per_file` | Configurable | Maximum lines per file |\n\n## Best Practices\n\n1. **Domain organization**: Before creating new domains, verify existing domains cannot accommodate the content\n2. **Title conventions**: Use descriptive titles that serve as meaningful filenames\n3. **Content structure**: Include both `rawConcept` (concise summary) and `narrative` (detailed explanation) when possible\n4. **Archive management**: Use the archive feature for low-importance entries to keep active knowledge focused\n5. **Batch operations**: When curating multiple files, the queue's batching system optimizes LLM usage\n\n## Related Documentation\n\n- [SKILL.md](https://github.com/campfirein/byterover-cli/blob/main/src/server/templates/skill/SKILL.md) - CLI command reference for `brv curate` and `brv query`\n- [folder-pack-executor.ts](https://github.com/campfirein/byterover-cli/blob/main/src/server/infra/executor/folder-pack-executor.ts) - Folder packing for knowledge extraction\n\n---\n\n\n\n## Version Control for Context\n\n### 相关页面\n\n相关主题：[Context Tree and Knowledge Storage](#context-tree), [Agent System](#agent-system)\n\n\nRelevant Source Files\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/core/interfaces/services/i-git-service.ts](https://github.com/campfirein/byterover-cli/blob/main/src/server/core/interfaces/services/i-git-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/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/tui/features/vc/push/components/vc-push-flow.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/tui/features/vc/push/components/vc-push-flow.tsx)\n- [src/agent/resources/tools/bash_exec.txt](https://github.com/campfirein/byterover-cli/blob/main/src/agent/resources/tools/bash_exec.txt)\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\n\n# Version Control for Context\n\nVersion Control for Context (VC) provides git-based version control for ByteRover's knowledge base (context tree). It enables tracking, branching, committing, merging, and syncing curated knowledge using familiar git semantics, with all operations working locally without authentication. Remote sync with a team is optional.\n\n## Overview\n\nByteRover's Version Control system extends standard git functionality to manage the `.brv/context-tree/` directory where curated knowledge is stored. This system allows users to track changes to their knowledge base, create feature branches for experimental knowledge curation, collaborate with team members through remote sync, and maintain a complete history of knowledge evolution.\n\nThe VC system is built on top of an abstracted git service layer that provides cross-platform git operations, with additional intelligence for knowledge-specific use cases like tracking abstract generations and managing context tree structure. 资料来源：[src/shared/transport/events/vc-events.ts:1-50]()\n\n## Architecture\n\n```mermaid\ngraph TD\n subgraph \"User Interface Layer\"\n CLI[CLI - brv vc]\n WebUI[WebUI]\n TUI[TUI Components]\n end\n \n subgraph \"Command Layer\"\n VCCommands[VC Commands]\n BranchCmd[Branch Command]\n CommitCmd[Commit Command]\n MergeCmd[Merge Command]\n PushCmd[Push Command]\n end\n \n subgraph \"Service Layer\"\n GitService[Git Service Interface]\n CurateService[Curate Service]\n CommandValidator[Command Validator]\n end\n \n subgraph \"Infrastructure Layer\"\n GitImpl[Isomorphic Git]\n FileSystem[File System]\n Events[VC Events Transport]\n end\n \n subgraph \"Data Layer\"\n ContextTree[.brv/context-tree/]\n GitStorage[Git Repository]\n end\n \n CLI --> VCCommands\n WebUI --> VCCommands\n TUI --> VCCommands\n \n VCCommands --> GitService\n VCCommands --> CommitCmd\n VCCommands --> BranchCmd\n VCCommands --> MergeCmd\n \n GitService --> GitImpl\n GitService --> FileSystem\n GitService --> Events\n \n CommitCmd --> ContextTree\n CurateService --> ContextTree\n \n ContextTree --> GitStorage\n GitImpl --> GitStorage\n```\n\n## Diff Modes\n\nThe VC system supports four diff modes that mirror `git diff` semantics, allowing precise comparison of knowledge changes across different stages and references. 资料来源：[src/shared/transport/events/vc-events.ts:16-27]()\n\n| Mode | Git Equivalent | Comparison | Use Case |\n|------|---------------|------------|----------|\n| `unstaged` | `git diff` | Stage → Workdir | Tracked files with uncommitted changes |\n| `staged` | `git diff --staged` | HEAD → Stage | Committed changes ready to be finalized |\n| `ref-vs-worktree` | `git diff ` | Commit/Branch → Workdir | Compare any reference against working tree |\n| `range` | `git diff ..` | Ref1 → Ref2 | Compare two commits or branches |\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## Diff File Model\n\nEach file entry in a diff response includes comprehensive metadata about the change. 资料来源：[src/shared/transport/events/vc-events.ts:35-50]()\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `binary` | `boolean` | True when either side contains NUL byte; content fields are empty |\n| `newContent` | `string` | The new file content |\n| `oldContent` | `string` | The previous file content (empty for additions) |\n| `path` | `string` | Relative path to the file |\n| `newOid` | `string` | 7-character short OID (omitted for deletions) |\n| `oldOid` | `string` | Previous commit's OID |\n| `status` | `string` | Change type: `added`, `deleted`, `modified` |\n\nBinary files are filtered out of diff responses upstream, ensuring consumers only receive text content. Legacy WebUI consumers read `oldContent`, `newContent`, and `path` fields while ignoring additional fields for forward compatibility.\n\n## Git Service Interface\n\nThe `IGitService` interface defines the complete set of git operations available for version control. 资料来源：[src/server/core/interfaces/services/i-git-service.ts:1-100]()\n\n### Core Methods\n\n| Method | Returns | Description |\n|--------|---------|-------------|\n| `getTextBlob` | `Promise` | Retrieves blob content without double-read pattern |\n| `getTrackingBranch` | `Promise` | Returns upstream tracking branch config |\n| `hashBlob` | `Promise` | Computes 7-char short OID via `git hash-object` |\n| `init` | `Promise` | Initializes a new git repository |\n| `isAncestor` | `Promise` | Checks if ancestor commit is reachable from commit |\n| `isEmptyRepository` | `Promise` | Checks if repo has no commits, remotes, branches, tags, or untracked files |\n| `isInitialized` | `Promise` | Checks if `.git` directory exists |\n| `listBranches` | `Promise` | Lists local branches, optionally including remote-tracking |\n\n### Blob Operations\n\nThe `hashBlob` method computes the 7-character short OID that git would assign to content, using `git hash-object`. This is essential for rendering working-tree diff headers since the working tree has no stored OID. 资料来源：[src/server/core/interfaces/services/i-git-service.ts:20-27]()\n\n## Command Validation\n\nGit operations executed through the sandbox are validated for security and safety. The command validator enforces patterns that control which git operations are permitted. 资料来源：[src/agent/infra/process/command-validator.ts:1-50]()\n\n### Allowed Read-Only Operations\n\nThe following git operations are permitted in validated contexts:\n\n```typescript\n/git\\s+(status|log|diff|show|branch|tag|fetch|pull)(?!\\s+-)/i\n```\n\n### Recommended Git Workflow\n\nThe bash execution guidelines recommend this workflow for git operations: 资料来源：[src/agent/resources/tools/bash_exec.txt:1-30]()\n\n1. Run `git status` to see changes\n2. Run `git diff` to review changes\n3. Stage files with `git add`\n4. Commit with a meaningful message\n\nFor pull requests:\n1. Check branch status with `git status`\n2. Push to remote with `git push -u origin `\n3. Create PR using `gh pr create`\n\n## Commit History Display\n\nThe WebUI provides a commit history panel that displays the timeline of knowledge changes. 资料来源：[src/webui/features/context/components/context-history-panel.tsx:1-60]()\n\n```typescript\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\nThe history panel renders timeline items with:\n- Commit author name\n- Timestamp formatted as \"MMM d, HH:mm\"\n- Visual distinction between current commit (active) and older commits\n\n## Push Flow\n\nThe TUI push flow handles the process of pushing commits to remote repositories. It includes remote URL validation and status display during the push operation. 资料来源：[src/tui/features/vc/push/components/vc-push-flow.tsx:1-80]()\n\n```typescript\nreturn (\n \n {branch ? `Pushing to origin/${branch}...` : 'Pushing...'}\n \n)\n```\n\nThe push flow requires:\n- Remote URL configuration\n- Remote URL validation before submission\n- Branch name determination for the push target\n\n## Context Tree Structure\n\nThe context tree is organized in `.brv/context-tree/` and includes version control information in system prompts. 资料来源：[src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts:1-100]()\n\n### Structure Rules\n\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- `context.md` files contain the curated knowledge content\n- `_index.md` files are auto-generated summaries at each directory level\n- `_archived/` contains archived low-importance entries\n\n### Domain Management\n\nDomains are created dynamically based on the semantics of curated content. Domain names use snake_case (e.g., `architecture`, `market_trends`, `risk_analysis`). Before creating a new domain, the system checks if existing domains could accommodate the content.\n\n### VC Integration\n\nThe system prompt contributor includes version control information:\n- Query commands search only within the context tree structure\n- Curate commands check existing domains/topics before creating new ones\n- Archived entries can be accessed using `expand_knowledge` to drill into them\n\n## Workflow Diagram\n\n```mermaid\ngraph LR\n subgraph \"Local Operations\"\n A[Curate Knowledge] --> B[brv vc add]\n B --> C[brv vc commit]\n C --> D[brv vc status]\n D --> E{Changes?}\n E -->|Yes| F[Review Changes]\n E -->|No| G[Done]\n F --> H[brv vc log]\n end\n \n subgraph \"Branch Management\"\n I[brv vc branch feature/auth] --> J[brv vc checkout feature/auth]\n J --> K[Develop Knowledge]\n K --> L[brv vc merge]\n end\n \n subgraph \"Remote Sync\"\n M[brv vc push] --> N[brv vc pull]\n N --> O[brv vc fetch]\n end\n \n H --> I\n L --> M\n```\n\n## Key Features Summary\n\n| Feature | Description |\n|---------|-------------|\n| **Local-First** | All operations work locally without authentication |\n| **Git Semantics** | Familiar git commands and workflows |\n| **Branch Support** | Create, switch, merge, and delete branches |\n| **History Tracking** | Complete commit history with author and timestamp |\n| **Remote Sync** | Optional push/pull to team ByteRover spaces |\n| **Diff Modes** | Four modes matching git diff semantics |\n| **Binary Filtering** | Automatic filtering of binary files from diffs |\n| **Security Validation** | Command validation prevents dangerous operations |\n\n## Remote Operations\n\nRemote sync requires ByteRover authentication (`brv login`) and a configured remote. The following operations are supported:\n\n| Command | Description |\n|---------|-------------|\n| `brv vc remote` | Show current remote configuration |\n| `brv vc remote add origin ` | Add a new remote |\n| `brv vc remote set-url origin ` | Update remote URL |\n| `brv vc fetch` | Fetch remote refs |\n| `brv vc pull` | Fetch and merge remote commits |\n| `brv vc push` | Push commits to cloud |\n| `brv vc push -u origin main` | Push and set upstream tracking |\n| `brv vc clone` | Clone a team space repository |\n\n## Related Documentation\n\n- [ByteRover CLI Template System](src/server/templates/README.md) - Agent instruction generation\n- [Curate Service](src/agent/infra/sandbox/curate-service.ts) - Knowledge curation operations\n- [Context Tree Structure Contributor](src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts) - System prompt integration\n\n---\n\n\n\n## WebUI Dashboard\n\n### 相关页面\n\n相关主题：[System Architecture Overview](#architecture-overview)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/webui/router.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/webui/router.tsx)\n- [src/webui/pages/home-page.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/webui/pages/home-page.tsx)\n- [src/webui/features/context/components/context-layout.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/webui/features/context/components/context-layout.tsx)\n- [src/webui/features/tasks/components/task-list-view.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/webui/features/tasks/components/task-list-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/webui/lib/api-client.ts](https://github.com/campfirein/byterover-cli/blob/main/src/webui/lib/api-client.ts)\n- [src/server/infra/webui/webui-server.ts](https://github.com/campfirein/byterover-cli/blob/main/src/server/infra/webui/webui-server.ts)\n\n\n# WebUI Dashboard\n\nThe WebUI Dashboard is a React-based web interface served locally by the ByteRover daemon, providing developers with a graphical way to interact with the ByteRover CLI system. It serves as the primary user-facing component for managing AI coding agents, version control operations, context knowledge bases, task monitoring, and provider configurations through a modern, dark-themed interface.\n\n## Architecture Overview\n\nThe WebUI operates as a client-side React application that communicates with the server-side daemon via a WebSocket-based transport layer. The architecture follows a feature-based folder structure where related components, hooks, and utilities are co-located.\n\n```mermaid\ngraph TD\n Client[\"WebUI Client (React + Tailwind)\"]\n Server[\"WebUI Server (webui-server.ts)\"]\n API[\"API Client (api-client.ts)\"]\n Transport[\"WebSocket Transport\"]\n Daemon[\"ByteRover Daemon\"]\n Providers[\"LLM Providers\"]\n \n Client --> API\n API --> Transport\n Transport --> Server\n Server --> Daemon\n Server --> Providers\n \n subgraph WebUI_Features [\"WebUI Features\"]\n Context[\"Context/Knowledge Management\"]\n Tasks[\"Task Monitoring\"]\n VC[\"Version Control\"]\n Providers[\"Provider Configuration\"]\n Hub[\"Hub/Marketplace\"]\n Project[\"Project Management\"]\n end\n \n Client --> Context\n Client --> Tasks\n Client --> VC\n Client --> Providers\n Client --> Hub\n Client --> Project\n```\n\n## Core Components\n\n### Header Layout\n\nThe `header.tsx` file defines the main navigation header component that provides persistent access to key functionality across all pages.\n\n**Key Features:**\n\n| Element | Purpose |\n|---------|---------|\n| Provider Selector | Shows current LLM provider with connection status indicator |\n| Status Indicator | Visual dot showing active provider state (green/amber) |\n| Credit Pill | Displays remaining credits when using ByteRover billing |\n| Tooltip Triggers | Contextual help for user actions |\n\n资料来源：[src/webui/layouts/header.tsx:1-60]()\n\n```tsx\n setProviderDialogOpen(true)}\n size=\"sm\"\n variant=\"ghost\"\n />\n }\n>\n \n \n {activeProvider && (\n \n )}\n \n {providerLabel}\n\n```\n\n### Page Routing\n\nThe application uses file-based routing through `router.tsx`, mapping URL paths to React page components. The router serves as the central navigation hub, enabling deep linking and browser history integration.\n\n资料来源：[src/webui/router.tsx]()\n\n## Feature Panels\n\n### Context/Knowledge Management\n\nThe context panel provides an interface for managing the knowledge base used by AI agents. It displays the curated knowledge topics, allows navigation through the context tree structure, and shows search functionality.\n\n资料来源：[src/webui/features/context/components/context-layout.tsx]()\n\nKey operations supported:\n\n- View knowledge topics organized in a tree structure\n- Search and filter within the knowledge base\n- Expand/collapse topic hierarchies\n- Navigate to detailed topic views\n\n### Task Monitoring\n\nThe task list view component displays active, completed, and failed tasks from the agent execution history. It integrates with the task history system defined in the server domain layer.\n\n资料来源：[src/webui/features/tasks/components/task-list-view.tsx]()\n\nThe TUI's expanded log view provides a reference for expected task display behavior:\n\n```tsx\n{log.status === 'completed' && (\n \n \n \n)}\n```\n\n资料来源：[src/tui/components/execution/expanded-log-view.tsx:60-70]()\n\n### Version Control Panel\n\nThe VC components handle git-like operations including push and pull functionality. The UI provides visual feedback during sync operations and handles remote URL configuration.\n\n资料来源：[src/webui/features/vc/components/remotes-panel.tsx]()\n\n**Push Flow States:**\n\n| State | UI Display |\n|-------|------------|\n| No Remote | Prompts user to configure remote URL |\n| Pending | Shows spinner with branch name |\n| Success | Confirmation message |\n| Error | Error details with retry option |\n\n资料来源：[src/tui/features/vc/push/components/vc-push-flow.tsx:40-50]()\n\n### Provider Configuration\n\nThe providers panel enables users to configure LLM providers, set API keys, and manage OAuth authentication flows. It supports multiple authentication methods and provides validation before saving.\n\n资料来源：[src/webui/features/provider/components/providers-panel.tsx]()\n\n```tsx\n