{
"canonical_name": "google-gemini/gemini-cli",
"compilation_id": "pack_dbd8689430eb4d748ee68479b46c8475",
"created_at": "2026-05-13T10:00:27.388202+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, 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 `npx @google/gemini-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": "npx @google/gemini-cli",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_a662361d9da14f2ead3ffdf9c647cb9f"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_a739e6bf97552f632a54be02f6ae89b8",
"canonical_name": "google-gemini/gemini-cli",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/google-gemini/gemini-cli",
"slug": "gemini-cli",
"source_packet_id": "phit_a150ede1ae46455ca64abcc0faeb4815",
"source_validation_id": "dval_db8319d8d7e54841875a82b94e0be05e"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 mcp_host的用户",
"github_forks": 13621,
"github_stars": 103838,
"one_liner_en": "An open-source AI agent that brings the power of Gemini directly into your terminal.",
"one_liner_zh": "An open-source AI agent that brings the power of Gemini directly into your terminal.",
"primary_category": {
"category_id": "software-development",
"confidence": "medium",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:git, cli"
},
"target_user": "使用 mcp_host 等宿主 AI 的用户",
"title_en": "gemini-cli",
"title_zh": "gemini-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": "Browser Automation",
"label_zh": "浏览器自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-browser-automation",
"type": "core_capability"
},
{
"label_en": "Page Observation and Action Planning",
"label_zh": "页面观察与动作规划",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-page-observation-and-action-planning",
"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_a150ede1ae46455ca64abcc0faeb4815",
"page_model": {
"artifacts": {
"artifact_slug": "gemini-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": "npx @google/gemini-cli",
"label": "Gemini CLI · 官方安装入口",
"source": "https://github.com/google-gemini/gemini-cli#readme",
"verified": true
}
],
"display_tags": [
"浏览器 Agent",
"网页任务自动化",
"浏览器自动化",
"页面观察与动作规划",
"评测体系"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "An open-source AI agent that brings the power of Gemini directly into your terminal."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Surface or quarantine invalid Auto Memory inbox patches",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_58be51e305414f12a3dd5f6c39b5e777 | https://github.com/google-gemini/gemini-cli/issues/26523 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Surface or quarantine invalid Auto Memory inbox patches",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Memory system bugs and quality improvements",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_956d952c67c7469189ec67aef86139d4 | https://github.com/google-gemini/gemini-cli/issues/26516 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Memory system bugs and quality improvements",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Change the steering eval test to always pass",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_e480448796b34a7da894c9769d69b46c | https://github.com/google-gemini/gemini-cli/issues/23313 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Change the steering eval test to always pass",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Model frequently creates tmp scripts in random spots",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_abead6f384f94be497a8893d52d0ca2b | https://github.com/google-gemini/gemini-cli/issues/23571 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Model frequently creates tmp scripts in random spots",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Gemini CLI encounters 400 error with > 128 tools",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_1e04a5efd78143d79b2ef38a564c428f | https://github.com/google-gemini/gemini-cli/issues/24246 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Gemini CLI encounters 400 error with > 128 tools",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add deterministic redaction and reduce Auto Memory logging",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_33c66a37dc674c5084470c52157d3f4b | https://github.com/google-gemini/gemini-cli/issues/26525 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Add deterministic redaction and reduce Auto Memory logging",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：All model quotas not resetting, even after days",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_1ed06494b0e8487e9f5b9b5faa68374c | https://github.com/google-gemini/gemini-cli/issues/26967 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：All model quotas not resetting, even after days",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Gemini CLI 0.42.0-preview.1: [API Error: ..... v1internal:generateContent failed, reason: ] Request contains an invalid argument at process.processTicksAndReje…",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_9f0cc269f15147bf94171001a3d0a145 | https://github.com/google-gemini/gemini-cli/issues/26572 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Gemini CLI 0.42.0-preview.1: [API Error: ..... v1internal:generateContent failed, reason: ] Request contains an invalid…",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Gemini failed to open in a temporary path A:\\",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_b7b6d80c305d48d2a7548e12a6621b72 | https://github.com/google-gemini/gemini-cli/issues/25216 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Gemini failed to open in a temporary path A:\\",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Robust component level evalutions",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_0b7e5ce9e4de49d1aae81349f2856cd7 | https://github.com/google-gemini/gemini-cli/issues/24353 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Robust component level evalutions",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Shell command execution gets stuck with \"Waiting input\" after command completes",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_73f28f340a29499e9a1718d38d5500ad | https://github.com/google-gemini/gemini-cli/issues/25166 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Shell command execution gets stuck with \"Waiting input\" after command completes",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Stop Auto Memory from retrying low-signal sessions indefinitely",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_fb1dec66ee3c4a9f9faf5cb91b286667 | https://github.com/google-gemini/gemini-cli/issues/26522 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Stop Auto Memory from retrying low-signal sessions indefinitely",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Tool \"save_memory\" not found.",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_7b0f9e9404664597ab5f60b481da55fe | https://github.com/google-gemini/gemini-cli/issues/26563 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Tool \"save_memory\" not found.",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Your idiotic AI disobeyed me completely lied and has now cost me 300 dollars worth of work that went into my obsidian - 10000s of files and work deleted not re…",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_4bdaf010293245ac9e6f4ceece341d76 | https://github.com/google-gemini/gemini-cli/issues/26856 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Your idiotic AI disobeyed me completely lied and has now cost me 300 dollars worth of work that went into my obsidian -…",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat(cli): expose model thinking events in --output-format stream-json",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_5c2ad6806ee6413dbf441b91f6862364 | https://github.com/google-gemini/gemini-cli/issues/22083 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：feat(cli): expose model thinking events in --output-format stream-json",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:968197216 | https://github.com/google-gemini/gemini-cli | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 23 个潜在踩坑项，其中 14 个为 high/blocking；最高优先级：安装坑 - 来源证据：Surface or quarantine invalid Auto Memory inbox patches。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 666,
"forks": 13621,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 103838
},
"source_url": "https://github.com/google-gemini/gemini-cli",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "An open-source AI agent that brings the power of Gemini directly into your terminal.",
"title": "gemini-cli 能力包",
"trial_prompt": "# gemini-cli - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 gemini-cli 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：MCP Client\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. page-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装与配置。围绕“安装与配置”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-tools：核心工具集。围绕“核心工具集”模拟一次用户任务，不展示安装或运行结果。\n5. page-agent-system：代理系统与子代理。围绕“代理系统与子代理”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装与配置”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-tools\n输入：用户提供的“核心工具集”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-agent-system\n输入：用户提供的“代理系统与子代理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装与配置”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-tools：Step 4 必须围绕“核心工具集”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-agent-system：Step 5 必须围绕“代理系统与子代理”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/google-gemini/gemini-cli\n- https://github.com/google-gemini/gemini-cli#readme\n- .gemini/skills/async-pr-review/SKILL.md\n- .gemini/skills/behavioral-evals/SKILL.md\n- .gemini/skills/ci/SKILL.md\n- .gemini/skills/code-reviewer/SKILL.md\n- .gemini/skills/docs-changelog/SKILL.md\n- .gemini/skills/docs-writer/SKILL.md\n- .gemini/skills/github-issue-creator/SKILL.md\n- .gemini/skills/pr-address-comments/SKILL.md\n- .gemini/skills/pr-creator/SKILL.md\n- .gemini/skills/review-duplication/SKILL.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 gemini-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: CLI on start picks wrong default model（https://github.com/google-gemini/gemini-cli/issues/26971）；github/github_issue: All model quotas not resetting, even after days（https://github.com/google-gemini/gemini-cli/issues/26967）；github/github_issue: Eats tokes insanely, hangs with response waiting for infinite time.（https://github.com/google-gemini/gemini-cli/issues/26970）；github/github_issue: Your idiotic AI disobeyed me completely lied and has now cost me 300 dol（https://github.com/google-gemini/gemini-cli/issues/26856）；github/github_issue: Gemini CLI 0.42.0-preview.1: [API Error: ..... v1internal:generateConten（https://github.com/google-gemini/gemini-cli/issues/26572）；github/github_issue: context overflow (????)（https://github.com/google-gemini/gemini-cli/issues/26969）；github/github_issue: feat(cli): expose model thinking events in --output-format stream-json（https://github.com/google-gemini/gemini-cli/issues/22083）；github/github_issue: Tool \"save_memory\" not found.（https://github.com/google-gemini/gemini-cli/issues/26563）；github/github_issue: Add deterministic redaction and reduce Auto Memory logging（https://github.com/google-gemini/gemini-cli/issues/26525）；github/github_issue: Surface or quarantine invalid Auto Memory inbox patches（https://github.com/google-gemini/gemini-cli/issues/26523）；github/github_issue: Stop Auto Memory from retrying low-signal sessions indefinitely（https://github.com/google-gemini/gemini-cli/issues/26522）；github/github_issue: Memory system bugs and quality improvements（https://github.com/google-gemini/gemini-cli/issues/26516）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "CLI on start picks wrong default model",
"url": "https://github.com/google-gemini/gemini-cli/issues/26971"
},
{
"kind": "github_issue",
"source": "github",
"title": "All model quotas not resetting, even after days",
"url": "https://github.com/google-gemini/gemini-cli/issues/26967"
},
{
"kind": "github_issue",
"source": "github",
"title": "Eats tokes insanely, hangs with response waiting for infinite time.",
"url": "https://github.com/google-gemini/gemini-cli/issues/26970"
},
{
"kind": "github_issue",
"source": "github",
"title": "Your idiotic AI disobeyed me completely lied and has now cost me 300 dol",
"url": "https://github.com/google-gemini/gemini-cli/issues/26856"
},
{
"kind": "github_issue",
"source": "github",
"title": "Gemini CLI 0.42.0-preview.1: [API Error: ..... v1internal:generateConten",
"url": "https://github.com/google-gemini/gemini-cli/issues/26572"
},
{
"kind": "github_issue",
"source": "github",
"title": "context overflow (????)",
"url": "https://github.com/google-gemini/gemini-cli/issues/26969"
},
{
"kind": "github_issue",
"source": "github",
"title": "feat(cli): expose model thinking events in --output-format stream-json",
"url": "https://github.com/google-gemini/gemini-cli/issues/22083"
},
{
"kind": "github_issue",
"source": "github",
"title": "Tool \"save_memory\" not found.",
"url": "https://github.com/google-gemini/gemini-cli/issues/26563"
},
{
"kind": "github_issue",
"source": "github",
"title": "Add deterministic redaction and reduce Auto Memory logging",
"url": "https://github.com/google-gemini/gemini-cli/issues/26525"
},
{
"kind": "github_issue",
"source": "github",
"title": "Surface or quarantine invalid Auto Memory inbox patches",
"url": "https://github.com/google-gemini/gemini-cli/issues/26523"
},
{
"kind": "github_issue",
"source": "github",
"title": "Stop Auto Memory from retrying low-signal sessions indefinitely",
"url": "https://github.com/google-gemini/gemini-cli/issues/26522"
},
{
"kind": "github_issue",
"source": "github",
"title": "Memory system bugs and quality improvements",
"url": "https://github.com/google-gemini/gemini-cli/issues/26516"
}
],
"status": "已收录 13 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "An open-source AI agent that brings the power of Gemini directly into your terminal.",
"effort": "安装已验证",
"forks": 13621,
"icon": "code",
"name": "gemini-cli 能力包",
"risk": "可发布",
"slug": "gemini-cli",
"stars": 103838,
"tags": [
"浏览器 Agent",
"网页任务自动化",
"浏览器自动化",
"页面观察与动作规划",
"评测体系"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/google-gemini/gemini-cli 项目说明书\n\n生成时间：2026-05-13 09:42:22 UTC\n\n## 目录\n\n- [项目概述](#page-overview)\n- [安装与配置](#page-installation)\n- [系统架构](#page-architecture)\n- [包结构详解](#page-package-structure)\n- [核心工具集](#page-tools)\n- [代理系统与子代理](#page-agent-system)\n- [上下文管理与压缩](#page-context-management)\n- [CLI用户界面](#page-cli-ui)\n- [命令系统](#page-commands)\n- [安全策略与策略引擎](#page-security-policy)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[安装与配置](#page-installation), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/google-gemini/gemini-cli/blob/main/README.md)\n- [packages/cli/src/ui/components/AboutBox.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/AboutBox.tsx)\n- [packages/cli/src/ui/components/AppHeader.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/AppHeader.tsx)\n- [packages/core/src/agents/skill-extraction-agent.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/skill-extraction-agent.ts)\n- [packages/core/src/services/chatRecordingService.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/services/chatRecordingService.ts)\n- [packages/core/src/skills/builtin/skill-creator/SKILL.md](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/skills/builtin/skill-creator/SKILL.md)\n \n\n# 项目概述\n\n## 项目简介\n\nGemini CLI 是由 Google 开发的一款命令行工具，它将 Gemini AI 的强大能力直接带到终端环境中。通过自然语言交互，开发者可以在不离开命令行界面的情况下完成代码理解、生成、调试以及自动化任务执行等多种工作。资料来源：[README.md:1-50]()\n\n该项目采用 TypeScript/Node.js 构建，支持多平台运行（Windows、macOS、Linux），并提供 npm、Homebrew、MacPorts 和 Conda 等多种安装方式。资料来源：[README.md:150-200]()\n\n## 系统架构\n\nGemini CLI 采用模块化架构设计，主要由以下几个核心包组成：\n\n| 包名称 | 职责描述 |\n|--------|----------|\n| `packages/cli` | 命令行界面实现，包含 UI 组件、用户交互和身份验证 |\n| `packages/core` | 核心业务逻辑，包含 Agent 系统、技能管理和上下文管理 |\n| `packages/devtools` | 开发工具组件，提供调试和网络请求分析功能 |\n\n```mermaid\ngraph TD\n A[用户终端] --> B[CLI 入口层]\n B --> C[UI 组件层]\n C --> D[核心业务层]\n D --> E[Agent 代理层]\n E --> F[模型服务层]\n E --> G[技能系统层]\n E --> H[上下文管理]\n \n F --> I[Gemini API]\n G --> J[本地技能存储]\n H --> K[对话记录服务]\n```\n\n资料来源：[packages/cli/src/gemini.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/gemini.tsx)\n\n## 核心功能模块\n\n### 1. 用户界面系统\n\nGemini CLI 提供了一个功能丰富的终端用户界面，使用 React 风格组件构建。主要界面组件包括：\n\n**头部组件 (AppHeader)**\n\n显示应用状态信息，包括版本号、更新状态和用户身份信息。资料来源：[packages/cli/src/ui/components/AppHeader.tsx:1-80]()\n\n```typescript\n// AppHeader 核心数据结构\ninterface AppHeaderProps {\n showHeader: boolean;\n showDetails: boolean;\n config: Settings;\n updateInfo?: UpdateInfo;\n bannerVisible: boolean;\n bannerText?: string;\n}\n```\n\n**关于对话框 (AboutBox)**\n\n展示详细的系统信息，包括 CLI 版本、Git 提交信息、当前使用的模型、沙箱环境配置和操作系统信息。资料来源：[packages/cli/src/ui/components/AboutBox.tsx:1-60]()\n\n### 2. 认证与隐私系统\n\n认证流程通过 `AuthDialog` 组件管理，支持多种认证方式。用户首次使用时会看到服务条款和隐私声明提示。资料来源：[packages/cli/src/ui/auth/AuthDialog.tsx:1-80]()\n\n隐私声明文件包括：\n\n- **GeminiPrivacyNotice.tsx** - Gemini API 隐私条款\n- **CloudFreePrivacyNotice.tsx** - 免费服务隐私通知\n\n这些组件向用户明确说明数据收集范围和使用目的，包括人类审阅者可能阅读处理数据以提升产品质量的机制。资料来源：[packages/cli/src/ui/privacy/CloudFreePrivacyNotice.tsx:1-50]()\n\n### 3. 技能（Skills）系统\n\n技能系统是 Gemini CLI 的核心扩展机制，允许用户创建和管理可重用的任务模板。\n\n**技能创建器 (Skill Creator)**\n\n内置的技能创建器指导用户如何构建高质量技能。一个完整的技能包包含以下结构：资料来源：[packages/core/src/skills/builtin/skill-creator/SKILL.md:1-100]()\n\n```\nskill-name/\n├── SKILL.md # 必需：技能定义和触发条件\n├── scripts/ # 可选：确定性执行脚本\n├── references/ # 可选：参考文档\n└── assets/ # 可选：资源文件\n```\n\n**技能提取代理 (Skill Extraction Agent)**\n\n智能地从对话历史中提取有价值的工作流程，并将其转换为可重用的技能。该代理使用结构化的 patch 格式来记录文件变更。资料来源：[packages/core/src/agents/skill-extraction-agent.ts:1-50]()\n\n### 4. 对话录制服务\n\n`ChatRecordingService` 负责管理会话历史，支持会话的保存、加载和恢复。每个会话记录包含：资料来源：[packages/core/src/services/chatRecordingService.ts:1-80]()\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| sessionId | string | 会话唯一标识符 |\n| projectHash | string | 项目哈希值 |\n| startTime | string | 会话开始时间 |\n| lastUpdated | string | 最后更新时间 |\n| messages | Message[] | 完整消息历史 |\n| memoryScratchpad | string | 记忆便签内容 |\n\n```mermaid\ngraph LR\n A[用户对话] --> B[ChatRecordingService]\n B --> C[JSONL 文件存储]\n D[会话恢复] --> B\n B --> E[上下文加载]\n E --> F[Agent 处理]\n```\n\n### 5. 上下文图构建\n\n`toGraph.ts` 模块负责将对话历史转换为结构化的上下文图，支持消息去重和历史追溯。系统通过 MD5 哈希生成稳定的轮次标识，确保相同内容的消息能够被正确识别。资料来源：[packages/core/src/context/graph/toGraph.ts:1-80]()\n\n### 6. 扩展系统\n\nGemini CLI 支持 MCP（Model Context Protocol）扩展，允许第三方开发者扩展功能。扩展详情界面 (`ExtensionDetails`) 显示每个扩展的版本、星级、Google 拥有标识以及支持的特性标签。资料来源：[packages/cli/src/ui/components/views/ExtensionDetails.tsx:1-100]()\n\n## 主要功能特性\n\n### 代码理解与生成\n\n- 查询和编辑大型代码库\n- 使用多模态能力从 PDF、图片或草图生成新应用\n- 使用自然语言调试和排除问题\n\n### 自动化与集成\n\n- 自动化运维任务，如查询 Pull Request 或处理复杂变基\n- 通过 MCP 服务器连接新能力，包括使用 Imagen、Veo 或 Lyria 进行媒体生成\n- 在脚本中非交互式运行，实现工作流自动化\n\n### 高级能力\n\n- 内置 Google Search 集成，获取实时信息\n- 对话检查点功能，保存和恢复复杂会话\n- 自定义上下文文件（GEMINI.md），为项目定制行为\n\n### GitHub 集成\n\n可通过 Gemini CLI GitHub Action 直接将 Gemini CLI 集成到 GitHub 工作流中。资料来源：[README.md:80-120]()\n\n## 发布渠道\n\n| 渠道 | 发布频率 | 特点 |\n|------|----------|------|\n| Preview | 每周二 UTC 23:59 | 未经完全验证，可能存在回归问题 |\n| Stable | 每周二 UTC 20:00 | 经过验证的稳定版本 |\n| Nightly | 每日 UTC 00:00 | 主分支最新变更，可能包含未解决问题 |\n\n资料来源：[README.md:180-220]()\n\n## 安装方式\n\nGemini CLI 支持多种安装途径：\n\n| 安装方式 | 命令 |\n|----------|------|\n| npm 全局安装 | `npm install -g @google/gemini-cli` |\n| Homebrew | `brew install gemini-cli` |\n| MacPorts | `sudo port install gemini-cli` |\n| Conda 环境 | 通过 conda 环境安装 nodejs 后使用 npm |\n\n资料来源：[README.md:140-170]()\n\n## 技术栈概览\n\n- **运行时**: Node.js\n- **UI 框架**: React + TypeScript\n- **终端渲染**: Ink（React for CLI）\n- **包管理**: npm workspaces\n- **语言**: TypeScript\n\n---\n\n\n\n## 安装与配置\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/google-gemini/gemini-cli/blob/main/README.md)\n- [packages/cli/src/ui/auth/AuthDialog.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/auth/AuthDialog.tsx)\n- [packages/cli/src/ui/auth/LoginRestartDialog.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/auth/LoginRestartDialog.tsx)\n- [packages/cli/src/ui/components/AboutBox.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/AboutBox.tsx)\n \n\n# 安装与配置\n\nGemini CLI 是 Google 开发的命令行工具，为开发者提供基于 AI 的代码理解和生成能力。本页面详细介绍 Gemini CLI 的多种安装方式、认证配置以及基础设置，帮助用户快速上手使用。\n\n## 系统要求\n\n在开始安装之前，请确保系统满足以下要求：\n\n| 要求项 | 说明 |\n|--------|------|\n| Node.js | 推荐 Node.js 18.x 或更高版本 |\n| 包管理器 | npm、yarn 或 pnpm |\n| 操作系统 | macOS、Linux、Windows |\n| 网络 | 能够访问 npm registry 和 Google AI 服务 |\n\n## 安装方式\n\nGemini CLI 支持多种安装方式，用户可根据自身环境选择最适合的方法。\n\n### 通过 npm 全局安装\n\n最直接的安装方式是通过 npm 进行全局安装：\n\n```bash\nnpm install -g @google/gemini-cli\n```\n\n资料来源：[README.md:1]()\n\n### 通过 Homebrew 安装（macOS/Linux）\n\nmacOS 和 Linux 用户可使用 Homebrew 进行安装：\n\n```bash\nbrew install gemini-cli\n```\n\n资料来源：[README.md:1]()\n\n### 通过 MacPorts 安装（macOS）\n\nmacOS 用户也可选择 MacPorts 方式：\n\n```bash\nsudo port install gemini-cli\n```\n\n资料来源：[README.md:1]()\n\n### 通过 Anaconda 安装（受限环境）\n\n对于受限环境，Anaconda 提供了隔离的安装方案：\n\n```bash\n# 创建并激活新环境\nconda create -y -n gemini_env -c conda-forge nodejs\nconda activate gemini_env\n\n# 在环境内通过 npm 全局安装 Gemini CLI\nnpm install -g @google/gemini-cli\n```\n\n资料来源：[README.md:1]()\n\n## 发布渠道\n\nGemini CLI 提供三种发布渠道，用户可根据需求选择不同的版本。\n\n### 预览版（Preview）\n\n新的预览版本每周二 UTC 23:59 发布，这些版本可能包含回归问题或其他待解决的问题。适合希望测试最新功能的用户：\n\n```bash\nnpm install -g @google/gemini-cli@preview\n```\n\n资料来源：[README.md:1]()\n\n### 稳定版（Stable）\n\n新的稳定版本每周二 UTC 20:00 发布，这是对上周预览版的完整升级，并包含所有 bug 修复和验证：\n\n```bash\nnpm install -g @google/gemini-cli@latest\n```\n\n资料来源：[README.md:1]()\n\n### 夜间版（Nightly）\n\n每日 UTC 00:00 发布，包含主分支的所有最新更改：\n\n```bash\nnpm install -g @google/gemini-cli@nightly\n```\n\n资料来源：[README.md:1]()\n\n## 认证配置\n\n首次使用 Gemini CLI 时需要进行身份验证。工具支持多种认证方式。\n\n### 认证方式选择\n\n启动 Gemini CLI 后，系统会显示认证对话框，提示选择认证方式：\n\n```bash\ngemini\n```\n\n认证界面会展示以下选项供用户选择：\n\n- Google 账号登录\n- API Key 认证（适用于企业用户）\n- 其他认证方式\n\n用户可使用 Enter 键进行选择。资料来源：[AuthDialog.tsx:1]()\n\n### Google 登录流程\n\n选择 Google 账号登录后，系统会显示登录进度：\n\n```\n使用 Google 账号登录中... 正在重启 Gemini CLI 以继续。\n```\n\n登录成功后需要重启 CLI 以完成认证流程：\n\n```\n您已成功使用 Google 账号登录。Gemini CLI 需要重新启动。\n请按 R 重启，或按 Esc 选择其他认证方式。\n```\n\n资料来源：[LoginRestartDialog.tsx:1]()\n\n### 服务条款与隐私声明\n\n在认证过程中，用户需要阅读并同意以下服务条款：\n\n| 条款 | 链接 |\n|------|------|\n| Gemini API 概述 | https://ai.google.dev/docs/gemini_api_overview |\n| AI Studio 服务条款 | https://aistudio.google.com/ |\n| Google 开发者服务条款 | https://developers.google.com/terms |\n| Gemini API 附加服务条款 | https://ai.google.dev/gemini-api/terms |\n\n资料来源：[packages/cli/src/ui/privacy/GeminiPrivacyNotice.tsx:1]()\n\n### 数据收集与隐私\n\nGemini CLI 会收集以下数据用于改进产品和服务：\n\n- 您的提示词及相关代码\n- 生成的输出和代码编辑\n- 相关功能使用信息\n- 您的反馈\n\n为确保质量并改进产品，人工审核员可能会阅读、标注和处理收集的数据。Google 会采取措施在审核前断开数据与 Google 账号的关联，存储期限最长为 18 个月。\n\n资料来源：[packages/cli/src/ui/privacy/CloudFreePrivacyNotice.tsx:1]()\n\n## 配置文件\n\n### 设置文件位置\n\nGemini CLI 的配置文件位于用户主目录下的 `~/.gemini/settings.json`。此文件可自定义工具的各种行为和选项。\n\n资料来源：[README.md:1]()\n\n### MCP 服务器配置\n\n通过 MCP（Model Context Protocol）服务器配置，可以扩展 Gemini CLI 的功能：\n\n```json\n{\n \"mcpServers\": {\n \"@github\": {},\n \"@slack\": {},\n \"@database\": {}\n }\n}\n```\n\n配置后即可在对话中使用 MCP 服务器功能：\n\n```\n> @github 列出我的开放拉取请求\n> @slack 发送今日提交的摘要到 #dev 频道\n> @database 运行查询以查找非活跃用户\n```\n\n资料来源：[README.md:1]()\n\n## 验证安装\n\n安装完成后，可通过以下方式验证安装是否成功并查看版本信息。\n\n### 查看版本信息\n\n```bash\ngemini --version\n```\n\n或启动交互式会话后，在关于对话框中查看：\n\n| 信息项 | 说明 |\n|--------|------|\n| CLI 版本 | 当前安装的版本号 |\n| Git 提交 | 源代码的 Git 提交哈希 |\n| 模型 | 当前使用的 AI 模型 |\n| 沙盒环境 | 沙盒配置信息 |\n| 操作系统 | 当前操作系统信息 |\n\n资料来源：[AboutBox.tsx:1]()\n\n### 快速测试\n\n创建测试目录并启动 Gemini CLI：\n\n```bash\ncd new-project/\ngemini\n> 写一个简单的问候程序\n```\n\n如果程序能够正常响应，说明安装和配置均已成功。\n\n资料来源：[README.md:1]()\n\n## 卸载指南\n\n如需卸载 Gemini CLI，请参阅官方卸载指南：https://www.geminicli.com/docs/resources/uninstall\n\n资料来源：[README.md:1]()\n\n## 故障排除\n\n### 常见安装问题\n\n| 问题 | 解决方案 |\n|------|----------|\n| 权限错误 | 使用 `sudo` 或配置 npm 全局路径 |\n| Node.js 版本不兼容 | 升级到 Node.js 18.x 或更高版本 |\n| 网络连接失败 | 检查代理设置或使用国内镜像 |\n\n### 认证问题\n\n如果认证过程中遇到问题：\n\n1. 确保 Google 账号可以正常访问 Google AI 服务\n2. 检查网络连接是否正常\n3. 清除浏览器缓存后重试\n4. 使用 `/bug` 命令直接从 CLI 报告问题\n\n## 下一步\n\n安装和配置完成后，您可以：\n\n- 阅读[命令参考文档](https://www.geminicli.com/docs/reference/commands)了解所有可用命令\n- 配置 [MCP 服务器](https://www.geminicli.com/docs/tools/mcp-server) 扩展功能\n- 设置 [GEMINI.md 文件](https://www.geminicli.com/docs/cli/gemini-md) 为项目提供持久上下文\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[包结构详解](#page-package-structure), [核心工具集](#page-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/cli/src/ui/components/AboutBox.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/AboutBox.tsx)\n- [packages/cli/src/ui/components/AppHeader.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/AppHeader.tsx)\n- [packages/cli/src/ui/auth/AuthDialog.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/auth/AuthDialog.tsx)\n- [packages/core/src/agents/skill-extraction-agent.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/skill-extraction-agent.ts)\n- [packages/core/src/services/chatRecordingService.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/services/chatRecordingService.ts)\n- [packages/cli/src/ui/components/views/ExtensionDetails.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/views/ExtensionDetails.tsx)\n \n\n# 系统架构\n\n## 概述\n\nGemini CLI 是 Google 开发的一款命令行工具，旨在通过自然语言交互帮助开发者完成代码理解、生成、调试和自动化任务。该工具基于 Gemini 模型构建，支持交互式和非交互式两种运行模式，可无缝集成到各类开发工作流中。\n\n系统的核心架构分为三大层次：**CLI 层**（命令行接口和 UI 渲染）、**Core 层**（核心业务逻辑和代理系统）以及**扩展层**（技能系统、MCP 服务器和自定义命令）。这种分层设计确保了各模块的职责清晰，便于维护和扩展。\n\n资料来源：[packages/cli/src/ui/components/AboutBox.tsx:1-50]()\n\n## 核心组件架构\n\n### 组件层次结构\n\nGemini CLI 采用 monorepo 结构，主要包含以下核心包：\n\n| 包名 | 职责 | 主要功能 |\n|------|------|----------|\n| `packages/cli` | 命令行接口层 | CLI 入口、UI 组件、交互处理、配置管理 |\n| `packages/core` | 核心业务层 | 代理系统、技能提取、聊天录制、服务层 |\n| `packages/devtools` | 开发者工具 | API 调试、日志查看、请求监控 |\n\n资料来源：[README.md:1-100]()\n\n### 包间依赖关系\n\n```mermaid\ngraph TD\n A[packages/cli] --> B[packages/core]\n A --> C[packages/devtools]\n B --> D[Gemini API]\n C --> B\n A --> E[用户终端]\n```\n\nCLI 包依赖于 Core 包提供核心功能，同时通过 devtools 包提供调试能力。用户通过终端与 CLI 层交互，CLI 层调用 Core 层处理业务逻辑，最终与外部 Gemini API 通信。\n\n## CLI 层架构\n\n### 入口点设计\n\nCLI 层提供两种运行模式以适应不同的使用场景：\n\n| 模式 | 文件位置 | 用途 |\n|------|----------|------|\n| 交互模式 | `packages/cli/src/interactiveCli.tsx` | 实时对话、工具确认、用户交互 |\n| 非交互模式 | `packages/cli/src/nonInteractiveCli.ts` | 脚本集成、自动化任务、CI/CD |\n\n交互模式使用 React 组件渲染终端 UI，支持键盘导航和实时反馈；非交互模式则专注于参数解析和一次性任务执行。\n\n资料来源：[packages/cli/src/ui/components/AboutBox.tsx:1-30]()\n\n### UI 组件体系\n\nUI 层基于 React 和 Ink（终端 React）构建，主要组件包括：\n\n```mermaid\ngraph TD\n A[AppHeader] --> B[UserIdentity]\n A --> C[Banner]\n D[Dialogs] --> E[AuthDialog]\n D --> F[FolderTrustDialog]\n D --> G[ModelDialog]\n D --> H[InboxDialog]\n I[Messages] --> J[ToolConfirmationMessage]\n I --> K[ScrollableDiffViewport]\n L[Views] --> M[ExtensionDetails]\n L --> N[GemmaStatus]\n```\n\n**核心 UI 组件说明：**\n\n- **AppHeader**：应用头部，显示版本信息（`v{version}`）、更新状态、用户身份和计划信息\n- **AuthDialog**：认证对话框，处理 Google 账户登录和服务条款确认\n- **FolderTrustDialog**：文件夹信任对话框，扫描并展示本地配置文件的安全警告\n- **ModelDialog**：模型选择对话框，显示 API 配额信息\n- **ToolConfirmationMessage**：工具确认消息，处理文件修改和外部编辑器集成\n\n资料来源：[packages/cli/src/ui/components/AppHeader.tsx:1-80]()\n资料来源：[packages/cli/src/ui/auth/AuthDialog.tsx:1-60]()\n\n### 应用头部组件\n\n`AppHeader` 组件负责渲染应用的主标识和元信息，支持两种布局模式：\n\n```typescript\n// 列布局：用于窄终端或存在 Logo 文本时\nconst useColumnLayout = !!logoTextArt || isNarrow;\n\n// 行布局：用于宽终端\nflexDirection={useColumnLayout ? 'column' : 'row'}\n```\n\n头部信息包括：CLI 版本号、模型版本、沙箱环境、操作系统信息以及可选的 Git 提交信息。\n\n资料来源：[packages/cli/src/ui/components/AboutBox.tsx:20-50]()\n资料来源：[packages/cli/src/ui/components/AppHeader.tsx:30-70]()\n\n## Core 层架构\n\n### 代理系统\n\nCore 层的核心是代理系统，负责处理用户请求、调用工具和管理对话状态。\n\n**技能提取代理**（`skill-extraction-agent.ts`）是该系统的关键组件：\n\n- 从对话中识别可复用的工作流程\n- 生成统一差异格式（unified diff）的补丁文件\n- 将补丁保存至 `~/.gemini/skills/.patch`\n- 支持技能合并、作用域管理和质量验证\n\n```mermaid\ngraph TD\n A[用户对话] --> B[技能提取代理]\n B --> C{分析有效性}\n C -->|有有效模式| D[生成补丁]\n C -->|无有效模式| E[静默丢弃]\n D --> F[验证补丁格式]\n F -->|通过| G[保存至 skills 目录]\n F -->|失败| E\n```\n\n资料来源：[packages/core/src/agents/skill-extraction-agent.ts:1-100]()\n\n### 聊天录制服务\n\n`ChatRecordingService` 负责管理和持久化对话记录：\n\n```typescript\nexport class ChatRecordingService {\n private conversationFile: string | null = null;\n private cachedConversation: ConversationRecord | null = null;\n private sessionId: string;\n private projectHash: string;\n}\n```\n\n对话记录包含以下元数据：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `sessionId` | string | 会话唯一标识 |\n| `projectHash` | string | 项目哈希值 |\n| `startTime` | ISO8601 | 会话开始时间 |\n| `lastUpdated` | ISO8601 | 最后更新时间 |\n| `memoryScratchpad` | string | 记忆便签内容 |\n| `messageCount` | number | 消息总数 |\n| `userMessageCount` | number | 用户消息数 |\n\n资料来源：[packages/core/src/services/chatRecordingService.ts:1-80]()\n\n## 认证与隐私系统\n\n### 认证流程\n\n认证系统通过 `AuthDialog` 组件引导用户完成登录流程：\n\n```mermaid\ngraph TD\n A[启动 CLI] --> B{检查认证状态}\n B -->|未认证| C[显示 AuthDialog]\n B -->|已认证| D[进入主界面]\n C --> D\n C --> E[选择认证方式]\n E --> F[完成登录]\n F --> D\n```\n\n认证对话框包含以下选项和处理逻辑：\n- Google 账户登录\n- 服务条款确认\n- 隐私政策链接展示\n\n资料来源：[packages/cli/src/ui/auth/AuthDialog.tsx:30-70]()\n\n### 隐私通知机制\n\n系统提供多层次的隐私通知：\n\n| 通知类型 | 触发条件 | 数据处理 |\n|----------|----------|----------|\n| `GeminiPrivacyNotice` | Gemini API 使用 | 展示 API 服务条款 |\n| `CloudFreePrivacyNotice` | 免费版用户 | 数据收集选项控制 |\n\n隐私通知展示相关链接和条款：\n\n- Gemini API 概述：https://ai.google.dev/docs/gemini_api_overview\n- API 服务条款：https://developers.google.com/terms\n- Gemini API 附加条款：https://ai.google.dev/gemini-api/terms\n\n资料来源：[packages/cli/src/ui/privacy/GeminiPrivacyNotice.tsx:1-30]()\n\n## 技能系统\n\n### 技能目录结构\n\n每个技能（Skill）遵循标准目录结构：\n\n```\n/\n├── SKILL.md # 技能定义（必需）\n├── scripts/ # 可执行脚本\n├── references/ # 参考文档\n└── assets/ # 静态资源\n```\n\n**SKILL.md 结构：**\n\n- **Frontmatter（YAML）**：包含 `name` 和 `description` 字段\n- **Body（Markdown）**：使用说明和指导，仅在技能触发后加载\n\n资料来源：[packages/core/src/skills/builtin/skill-creator/SKILL.md:1-80]()\n\n### 扩展功能标识\n\n扩展详情页面（`ExtensionDetails`）通过功能标签标识扩展能力：\n\n| 标签 | 标识颜色 | 功能说明 |\n|------|----------|----------|\n| MCP | 主题色 | MCP 服务器集成 |\n| Context | 错误色 | Context 文件支持 |\n| Hooks | 警告色 | 生命周期钩子 |\n| Skills | 成功色 | 技能系统支持 |\n| Commands | 主题色 | 自定义命令 |\n\n资料来源：[packages/cli/src/ui/components/views/ExtensionDetails.tsx:40-80]()\n\n## 配置与信任系统\n\n### 文件夹信任对话框\n\n`FolderTrustDialog` 负责扫描工作目录的安全配置：\n\n```mermaid\ngraph TD\n A[加载配置] --> B{发现配置}\n B -->|有错误| C[显示错误列表]\n B -->|有警告| D[显示安全警告]\n B -->|正常| E[列出已发现配置]\n C --> F{用户确认}\n D --> F\n E --> F\n F -->|信任| G[加载配置]\n F -->|取消| H[跳过]\n```\n\n信任配置包括：\n- 自定义命令（`.gemini/commands/`）\n- 钩子脚本（`.gemini/hooks/`）\n- MCP 服务器配置\n- 智能体技能\n- 项目设置\n\n资料来源：[packages/cli/src/ui/components/FolderTrustDialog.tsx:1-60]()\n\n## 部署与发布架构\n\n### 发布渠道\n\n系统支持三种发布渠道以满足不同用户需求：\n\n| 渠道 | 标签 | 发布周期 | 适用场景 |\n|------|------|----------|----------|\n| 预览版 | `preview` | 每周二 UTC 23:59 | 测试新功能 |\n| 稳定版 | `latest` | 每周二 UTC 20:00 | 生产环境 |\n| 每日版 | `nightly` | 每日 UTC 00:00 | 紧跟主分支 |\n\n安装命令示例：\n\n```bash\n# 预览版\nnpm install -g @google/gemini-cli@preview\n\n# 稳定版\nnpm install -g @google/gemini-cli@latest\n\n# 每日版\nnpm install -g @google/gemini-cli@nightly\n```\n\n### 多平台安装支持\n\n| 平台 | 安装方式 |\n|------|----------|\n| 通用 | `npm install -g @google/gemini-cli` |\n| macOS/Linux | `brew install gemini-cli` |\n| macOS | `sudo port install gemini-cli` |\n| 受限环境 | Anaconda + Node.js 环境 |\n\n资料来源：[README.md:100-180]()\n\n## 关键技术栈\n\n| 层级 | 技术选型 | 用途 |\n|------|----------|------|\n| CLI 框架 | Commander.js / Yargs | 命令行参数解析 |\n| UI 渲染 | Ink (React for CLI) | 终端界面渲染 |\n| 状态管理 | React Hooks | 组件状态管理 |\n| 核心逻辑 | TypeScript | 类型安全开发 |\n| API 调用 | Gemini SDK | 与 Gemini API 通信 |\n| 数据存储 | JSONL | 对话记录持久化 |\n\n## 总结\n\nGemini CLI 采用清晰的分层架构设计，通过 CLI 层处理用户交互和终端渲染，Core 层提供核心业务能力，扩展层支持技能系统和第三方集成。系统重视安全性和用户隐私，提供完善的认证流程和配置信任机制，同时支持多种发布渠道以适应不同用户的使用需求。\n\n---\n\n\n\n## 包结构详解\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/a2a-server/src/index.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/a2a-server/src/index.ts)\n- [packages/cli/src/index.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/index.ts)\n- [packages/core/src/index.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/index.ts)\n- [packages/sdk/src/index.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/sdk/src/index.ts)\n \n\n# 包结构详解\n\n## 概述\n\nGemini CLI 是一个基于 monorepo 架构的 Google 开源项目，采用了 pnpm workspace 模式进行多包管理。项目源码位于 `packages/` 目录下，包含四个主要子包：`cli`、`core`、`sdk` 和 `a2a-server`。这种模块化设计将命令行界面、核心业务逻辑、软件开发工具包和协议服务分离，使得各模块可以独立演进和测试，同时保持整体系统的内聚性。\n\n从项目配置文件和源码结构来看，Gemini CLI 的包设计遵循了清晰的关注点分离原则。`cli` 包负责终端 UI 渲染和用户交互，`core` 包实现代理逻辑、工具注册和配置管理，`sdk` 包提供对外编程接口，而 `a2a-server` 包则处理 Agent-to-Agent 通信协议。这种分层架构使得开发者可以根据需求选择性地使用或扩展特定模块。\n\n## 包架构总览\n\nGemini CLI 的包结构可以划分为四个核心模块，每个模块承担不同的职责。\n\n| 包名称 | 主要职责 | 依赖关系 |\n|--------|----------|----------|\n| `cli` | 命令行界面、UI 组件、用户交互 | 依赖 core、sdk |\n| `core` | 代理逻辑、工具注册、配置管理、聊天录制 | 基础包，无 core 外依赖 |\n| `sdk` | 外部 SDK 接口封装 | 依赖 core |\n| `a2a-server` | Agent 间通信协议服务 | 独立运行 |\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ Gemini CLI Monorepo │\n├──────────────┬──────────────┬──────────────┬────────────┤\n│ cli │ core │ sdk │ a2a-server│\n├──────────────┼──────────────┼──────────────┼────────────┤\n│ UI 组件 │ Agent 逻辑 │ 外部接口 │ 协议服务 │\n│ 隐私通知 │ 工具系统 │ API 封装 │ MCP 集成 │\n│ 帮助系统 │ 配置管理 │ 开发者工具 │ 通信路由 │\n│ 状态显示 │ 聊天录制 │ │ │\n└──────────────┴──────────────┴──────────────┴────────────┘\n```\n\n## CLI 包详解\n\n`packages/cli` 是用户直接交互的前端包，负责所有终端界面的渲染和命令解析。该包的源码组织遵循功能模块化原则，将不同类型的 UI 组件放置在相应的目录结构中。\n\n### 目录结构\n\nCLI 包的主要目录包括 `ui/` 目录下的多个子模块：`components/` 存放通用 UI 组件，`privacy/` 处理隐私政策展示，`views/` 包含特定视图组件如状态页面和扩展详情页。这种组织方式使得代码易于导航和维护。\n\n### UI 组件体系\n\nCLI 包的 UI 组件采用了分层设计模式。从源码中可以看到几个关键的 UI 组件类型：\n\n**AboutBox 组件**负责显示应用元信息，包括 CLI 版本、Git 提交信息、模型版本、沙盒环境和操作系统信息。该组件从配置文件和构建时注入的环境变量中获取数据，并使用主题化的样式进行展示。\n\n```tsx\n// 显示应用信息的结构示例\ninterface AppInfo {\n cliVersion: string; // CLI 版本号\n gitCommit: string; // Git 提交哈希\n modelVersion: string; // 使用的模型版本\n sandboxEnv: string; // 沙盒环境类型\n os: string; // 操作系统\n}\n```\n\n**AppHeader 组件**是应用的主头部，负责渲染横幅、Logo 和用户身份信息。该组件支持两种布局模式：列布局（column）和行布局（row），根据终端宽度和 Logo 存在与否自动切换。当显示更新状态时，还会在头部右侧显示更新进度指示器。\n\n**GemmaStatus 组件**专门用于显示 Gemma 模型的运行状态，包括二进制文件路径、模型下载状态、服务器运行状态和设置启用状态。每个状态项都配有状态指示点，直观地反映各组件的运行情况。\n\n**Help 组件**提供交互式帮助信息，展示所有可用的斜杠命令及其描述。该组件支持命令隐藏、分类显示和子命令展开等高级功能，帮助用户快速了解 CLI 的使用方式。\n\n### 隐私通知系统\n\nGemini CLI 实现了多套隐私通知界面以适应不同的使用场景。**CloudFreePrivacyNotice 组件**用于免费版本，向用户清晰说明数据收集政策，并提供数据收集选项的开关控制。该组件使用单选按钮让用户在允许或禁止 Google 使用数据之间做出选择，并将用户偏好持久化到配置系统中。\n\n**GeminiPrivacyNotice 组件**则提供更详细的法律条款链接，包括 Gemini API 概述、Google AI Studio 使用条款、API 服务条款和 Gemini API 附加服务条款。这些链接帮助用户在法律层面了解使用 Gemini CLI 的权利和义务。\n\n### 扩展详情展示\n\n**ExtensionDetails 组件**负责渲染扩展市场的扩展卡片信息。该组件显示扩展名称、版本、GitHub 星标数、Google 拥有标识以及扩展支持的特性标签。支持的特性标签包括 MCP（模型上下文协议）、Context file（上下文文件）、Hooks（钩子）、Skills（技能）和 Custom Commands（自定义命令），每种特性用不同的颜色区分。\n\n## Core 包详解\n\n`packages/core` 是整个项目的基础层，包含了代理逻辑、工具系统、配置管理和聊天录制等核心功能。该包不依赖其他内部包，而是作为其他包的基础依赖。\n\n### 代理与工具系统\n\n**config.ts** 文件实现了核心的配置管理和工具注册系统。该系统支持灵活的工具有条件注册机制，开发者可以通过配置指定启用哪些工具。工具注册采用工厂模式，通过 `maybeRegister` 函数包装，在满足配置条件时才执行实际注册。\n\n```typescript\n// 工具注册的条件判断逻辑示例\nconst maybeRegister = (toolName: string, coreTools: string[] | undefined, \n normalizedClassName: string, registerFn: () => void) => {\n let isEnabled = false;\n if (coreTools) {\n isEnabled = coreTools.some(\n (tool) =>\n tool === toolName ||\n tool === normalizedClassName ||\n tool.startsWith(`${toolName}(`) ||\n tool.startsWith(`${normalizedClassName}(`)\n );\n }\n if (isEnabled) {\n registerFn();\n }\n};\n```\n\n配置系统还支持工具的回退机制。以 Ripgrep 为例，当配置启用 Ripgrep 但系统检测到不可用时，会自动回退到 GrepTool 并记录警告日志，同时触发 `RipgrepFallbackEvent` 事件供监控使用。\n\n### 聊天录制服务\n\n**chatRecordingService.ts** 实现了会话持久化和恢复功能。该服务负责将聊天记录以 JSONL 格式存储到文件系统，并在需要时加载和重建会话状态。服务返回的会话记录包含丰富的元数据：\n\n```typescript\ninterface ConversationRecord {\n sessionId: string; // 会话唯一标识\n projectHash: string; // 项目哈希值\n startTime: string; // 开始时间 ISO 格式\n lastUpdated: string; // 最后更新时间\n summary: string | undefined; // 会话摘要\n memoryScratchpad: string; // 记忆便签\n directories: string[]; // 关联目录列表\n kind: string; // 会话类型\n messages: Message[]; // 消息列表\n messageCount: number; // 消息总数\n userMessageCount: number; // 用户消息数\n firstUserMessage: string; // 首个用户消息\n hasUserOrAssistantMessage: boolean; // 是否有人机对话\n}\n```\n\n### 技能提取代理\n\n**skill-extraction-agent.ts** 实现了从对话历史中自动提取技能的功能。该代理使用统一的 diff 补丁格式来描述技能文件的创建和更新操作，补丁文件存储在 `~/.gemini/skills/.patch` 路径下。代理遵循严格的质量规则，包括合并重复技能、保持职责清晰、确保每个技能包含触发条件、执行步骤和验证方法。\n\n### 策略辅助系统\n\n**policyHelpers.test.ts** 揭示了模型路由策略的实现细节。系统支持单模型直接返回和模型链策略两种模式。当配置使用 \"auto\" 模型时，系统会返回默认的模型链 `[Pro, Flash]`，优先使用高级模型，在资源受限或性能要求时自动降级。这种设计使得 CLI 能够适应不同的使用场景和资源限制。\n\n## SDK 包详解\n\n`packages/sdk` 为开发者提供编程接口封装，使得第三方应用可以集成 Gemini CLI 的核心能力。该包的封装层次更高，屏蔽了内部实现细节，提供稳定对外的 API。\n\nSDK 包作为核心功能与外部消费者之间的桥梁，其设计目标是保持 API 稳定性，使得依赖该 SDK 的应用能够在 CLI 版本升级时保持兼容。\n\n## A2A Server 包详解\n\n`packages/a2a-server` 实现了 Agent-to-Agent 通信协议服务。该包独立运行，提供标准的通信接口，使得不同的 AI Agent 能够相互发现和交互。A2A 协议支持 MCP（Model Context Protocol）服务器的集成，允许 Gemini CLI 扩展其能力边界，包括 Imagen 图像生成、Veo 视频生成和 Lyria 音乐生成等高级功能。\n\n## 包间依赖关系\n\n各包之间的依赖关系经过精心设计，形成了清晰的层次结构：\n\n```mermaid\ngraph TD\n A[cli 包] --> B[core 包]\n A --> C[sdk 包]\n B --> C\n D[a2a-server 包] --> B\n D --> C\n E[外部依赖] --> B\n E --> C\n E --> A\n```\n\n核心依赖原则包括：CLI 包依赖 core 和 sdk 以复用核心逻辑；core 包作为基础层不依赖其他内部包；sdk 包依赖 core 提供编程接口；a2a-server 独立运行但可与 core 交互以获取代理能力。\n\n## 安装与发布\n\nGemini CLI 支持多种安装渠道，满足不同用户的需求：\n\n| 渠道 | 发布频率 | 稳定性 | 安装命令 |\n|------|----------|--------|----------|\n| Preview | 每周二 UTC 23:59 | 未经完全测试 | `npm install -g @google/gemini-cli@preview` |\n| Stable | 每周二 UTC 20:00 | 经过验证 | `npm install -g @google/gemini-cli@latest` |\n| Nightly | 每日 UTC 00:00 | 可能存在问题 | `npm install -g @google/gemini-cli@nightly` |\n\n除 npm 外，项目还支持 Homebrew、MacPorts 和 Anaconda 等安装方式，适应不同的操作系统和环境限制。这种多渠道发布策略使得用户可以根据对稳定性的要求选择合适的版本，同时也为测试新功能提供了便捷的途径。\n\n## 源码文件对应关系\n\n根据项目结构和源码分析，各主要功能模块与源码文件的对应关系如下：\n\n| 功能模块 | 主要源文件 | 所在包 |\n|----------|------------|--------|\n| 命令行入口 | `packages/cli/src/index.ts` | cli |\n| UI 组件库 | `packages/cli/src/ui/components/` | cli |\n| 隐私通知 | `packages/cli/src/ui/privacy/` | cli |\n| 配置管理 | `packages/core/src/config/config.ts` | core |\n| 工具注册 | `packages/core/src/config/config.ts` | core |\n| 聊天录制 | `packages/core/src/services/chatRecordingService.ts` | core |\n| 技能提取 | `packages/core/src/agents/skill-extraction-agent.ts` | core |\n| 策略路由 | `packages/core/src/availability/policyHelpers.test.ts` | core |\n| SDK 接口 | `packages/sdk/src/index.ts` | sdk |\n| A2A 服务 | `packages/a2a-server/src/index.ts` | a2a-server |\n\n## 开发指南\n\n基于包结构设计，开发者在添加新功能时应遵循以下原则：\n\n**包边界原则**：避免使用相对路径跨包导入，优先通过包名导入。这种设计确保了包的边界清晰，便于未来的包拆分和独立发布。\n\n**协议设计**：新增 RPC 方法应添加到 `acpRpcDispatcher.ts`，会话状态存储在 `acpSession.ts`，协议辅助函数添加到 `acpUtils.ts`。\n\n**代码规范**：所有新文件必须包含 Apache-2.0 许可证头，使用 Zod 模式验证不可信输入，避免使用 `any` 类型断言。测试文件应放置在源码同目录下，使用 `.test.ts` 扩展名。\n\n## 总结\n\nGemini CLI 的包结构设计体现了现代 monorepo 项目的最佳实践。通过将 CLI 界面、核心逻辑、SDK 接口和协议服务分离，项目实现了关注点清晰、职责明确、易于测试和扩展的目标。各包之间的依赖关系经过精心规划，形成了稳定的基础层（core）支撑上层应用（cli、sdk、a2a-server）的架构模式。\n\n---\n\n\n\n## 核心工具集\n\n### 相关页面\n\n相关主题：[代理系统与子代理](#page-agent-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/src/config/config.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/config/config.ts)\n- [packages/core/src/tools/shell.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/tools/shell.ts) *(项目引用)*\n- [packages/core/src/agents/skill-extraction-agent.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/skill-extraction-agent.ts)\n- [packages/cli/src/ui/components/messages/ToolConfirmationMessage.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/messages/ToolConfirmationMessage.tsx)\n- [packages/core/src/context/graph/toGraph.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/context/graph/toGraph.ts)\n- [packages/core/src/services/chatRecordingService.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/services/chatRecordingService.ts)\n \n\n# 核心工具集\n\n## 概述\n\nGemini CLI 的核心工具集是 CLI 与用户代码库进行交互的基础能力层。这些工具提供了文件读写、代码搜索、Shell 命令执行、网络搜索与内容获取等核心功能，使 AI Agent 能够理解、修改和分析用户的代码环境。\n\n工具注册采用动态机制，通过配置类 `CoreConfig` 的 `registerTools()` 方法根据用户配置选择性注册可用工具。工具实现遵循统一的注册接口，每个工具继承自基础工具类并与消息总线 (`MessageBus`) 集成以实现事件驱动的通信。\n\n## 工具注册架构\n\n### 动态注册机制\n\n工具注册通过 `maybeRegister` 辅助函数实现，该函数检查工具是否在 `coreTools` 配置列表中启用，只有启用状态下才会调用注册函数将工具实例添加到注册表：\n\n```typescript\nconst maybeRegister = (\n toolClass: ToolConstructor,\n registerFn: () => void\n) => {\n let isEnabled = false;\n \n if (!coreTools) {\n isEnabled = true;\n } else if (coreTools) {\n isEnabled = coreTools.some(\n (tool) =>\n tool === toolName ||\n tool === normalizedClassName ||\n tool.startsWith(`${toolName}(`) ||\n tool.startsWith(`${normalizedClassName}(`),\n );\n }\n \n if (isEnabled) {\n registerFn();\n }\n};\n```\n\n资料来源：[packages/core/src/config/config.ts:120-147]()\n\n### 工具注册流程图\n\n```mermaid\ngraph TD\n A[CoreConfig 初始化] --> B[调用 registerTools]\n B --> C{检查 coreTools 配置}\n C -->|未配置| D[默认启用所有工具]\n C -->|已配置| E{遍历 coreTools 列表}\n E -->|工具匹配| F[调用 maybeRegister]\n F --> G{工具已启用?}\n G -->|是| H[注册工具到 Registry]\n G -->|否| I[跳过注册]\n H --> J[工具可用]\n```\n\n## 核心工具类型\n\n### 文件操作工具\n\n| 工具名称 | 类名 | 功能描述 |\n|---------|------|---------|\n| 文件列表 | `LSTool` | 列出目录内容和文件结构 |\n| 文件读取 | `ReadFileTool` | 读取指定路径的文件内容 |\n| 文件写入 | `WriteFileTool` | 创建或更新文件内容 |\n\n#### 文件工具的 Patch 格式\n\n在技能提取和文件更新场景中，工具使用统一的 unified diff patch 格式：\n\n```diff\n--- /absolute/path/to/original/SKILL.md\n+++ /absolute/path/to/original/SKILL.md\n@@ -, +, @@\n \n -\n +\n \n```\n\nPatch 规则要点：\n- 使用绝对路径，禁止 `a/` 或 `b/` 前缀\n- 每个 hunk 需要包含 3 行上下文\n- `@@` 头部行数必须准确\n- 新文件使用 `/dev/null` 作为源路径\n\n资料来源：[packages/core/src/agents/skill-extraction-agent.ts]()\n\n### 搜索工具\n\n| 工具名称 | 类名 | 优先级 | 回退方案 |\n|---------|------|--------|---------|\n| 高级搜索 | `RipGrepTool` | 高 | 依赖系统 ripgrep |\n| 基础搜索 | `GrepTool` | 低 | 默认 GrepTool |\n\n#### Ripgrep 回退机制\n\n当检测到 `useRipgrep` 配置启用时，系统会尝试注册 `RipGrepTool`。若系统不具备 ripgrep 能力，则自动回退到 `GrepTool`：\n\n```typescript\nif (this.getUseRipgrep()) {\n let useRipgrep = false;\n try {\n useRipgrep = await canUseRipgrep();\n } catch (error: unknown) {\n errorString = String(error);\n }\n if (useRipgrep) {\n maybeRegister(RipGrepTool, () =>\n registry.registerTool(new RipGrepTool(this, this.messageBus)),\n );\n } else {\n debugLogger.warn(`Ripgrep is not available. Falling back to GrepTool.`);\n maybeRegister(GrepTool, () =>\n registry.registerTool(new GrepTool(this, this.messageBus)),\n );\n }\n}\n```\n\n资料来源：[packages/core/src/config/config.ts:130-146]()\n\n### Shell 执行工具\n\nShell 工具允许 AI Agent 执行系统命令。执行前需要用户确认权限，权限范围包括：\n\n| 权限类型 | 说明 |\n|---------|------|\n| 网络访问 | 允许访问所有 URL |\n| 写权限 | 允许写入的路径列表 |\n| 读权限 | 允许读取的路径列表 |\n\n工具确认消息格式示例：\n\n```tsx\n\n • Network: All Urls\n\n\n • Write: /path/to/project\n\n\n • Read: /path/to/project\n\n```\n\n资料来源：[packages/cli/src/ui/components/messages/ToolConfirmationMessage.tsx]()\n\n### 网络工具\n\n| 工具名称 | 功能 |\n|---------|------|\n| `WebSearch` | 执行 Google 搜索，获取实时信息 |\n| `WebFetch` | 获取指定 URL 的网页内容 |\n\n## 工具确认与权限管理\n\n### 权限确认流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Tool as 工具调用\n participant UI as 确认界面\n participant Core as 核心引擎\n \n Tool->>Core: 请求执行命令\n Core->>UI: 显示 ToolConfirmationMessage\n User->>UI: 批准/拒绝\n alt 批准\n UI->>Core: 确认执行\n Core->>Tool: 放行执行\n Tool->>User: 返回结果\n else 拒绝\n UI->>Core: 拒绝执行\n Core->>Tool: 终止操作\n end\n```\n\n### 自动编辑模式\n\n当配置 `ApprovalMode` 设置为 `YOLO` 或 `AUTO_EDIT` 时，系统会自动批准工具执行，无需用户手动确认：\n\n```typescript\nconst isAutoEdit =\n config.getApprovalMode() === ApprovalMode.YOLO ||\n config.getApprovalMode() === ApprovalMode.AUTO_EDIT;\n```\n\n资料来源：[packages/cli/src/ui/components/messages/ToolConfirmationMessage.tsx]()\n\n## 工具与消息总线\n\n工具通过 `MessageBus` 实现事件驱动的通信架构。每个工具实例在注册时接收消息总线引用，支持以下事件类型：\n\n- `ToolStarted` - 工具开始执行\n- `ToolCompleted` - 工具执行完成\n- `ToolError` - 工具执行错误\n- `ToolConfirmationRequired` - 需要用户确认\n\n工具实例接收消息总线的方式：\n\n```typescript\nregistry.registerTool(new ReadFileTool(this, this.messageBus));\nregistry.registerTool(new LSTool(this, this.messageBus));\n```\n\n资料来源：[packages/core/src/config/config.ts:139-146]()\n\n## 对话上下文中的工具调用\n\n### Turn ID 生成机制\n\n每次工具调用都会生成稳定的唯一标识符，用于追踪对话历史：\n\n```typescript\nconst turnContent = JSON.stringify(msg.parts);\nconst h = createHash('md5')\n .update(`${msg.role}:${turnContent}`)\n .digest('hex');\nconst occurrence = (seenHashes.get(h) || 0) + 1;\nseenHashes.set(h, occurrence);\nconst turnSalt = `${h}_${occurrence}`;\nconst turnId = getStableId(msg, this.nodeIdentityMap, turnSalt, -1);\n```\n\n资料来源：[packages/core/src/context/graph/toGraph.ts]()\n\n### 函数调用标识\n\n函数调用和函数响应在对话图中使用不同前缀的标识符：\n\n| 调用类型 | 标识符格式 |\n|---------|-----------|\n| 函数调用 | `call_${functionCall.id}_${turnSalt}_${partIdx}` |\n| 函数响应 | `resp_${functionResponse.id}_${turnSalt}_${partIdx}` |\n\n## 会话记录与工具调用追溯\n\n`ChatRecordingService` 负责记录工具调用历史，保存到 JSONL 文件格式：\n\n```typescript\nexport interface ConversationRecord {\n sessionId: string;\n projectHash: string;\n startTime: string;\n lastUpdated: string;\n summary?: string;\n memoryScratchpad?: string;\n directories?: string[];\n kind: string;\n messages: Message[];\n messageCount: number;\n userMessageCount: number;\n firstUserMessage?: string;\n hasUserOrAssistantMessage: boolean;\n}\n```\n\n资料来源：[packages/core/src/services/chatRecordingService.ts]()\n\n## 配置参考\n\n### coreTools 配置选项\n\n```typescript\ninterface CoreToolsConfig {\n coreTools?: Array<\n | 'read_file'\n | 'read_file(...)'\n | 'write_file'\n | 'write_file(...)'\n | 'ls'\n | 'ls(...)'\n | 'grep'\n | 'grep(...)'\n | 'ripgrep'\n | 'ripgrep(...)'\n | 'web_search'\n | 'web_search(...)'\n | 'web_fetch'\n | 'web_fetch(...)'\n >;\n useRipgrep?: boolean;\n}\n```\n\n### ApprovalMode 配置\n\n| 模式 | 行为 |\n|------|------|\n| `MANUAL` | 所有操作需要用户手动确认 |\n| `AUTO_EDIT` | 编辑操作自动批准 |\n| `YOLO` | 所有操作自动批准 |\n| `DISABLED` | 禁用确认机制 |\n\n## 扩展与 MCP 集成\n\n核心工具集支持通过 MCP (Model Context Protocol) 服务器进行扩展。MCP 提示命令在帮助界面中带有 `[MCP]` 标签标识：\n\n```tsx\n{command.kind === CommandKind.MCP_PROMPT && (\n [MCP]\n)}\n```\n\n扩展工具可添加的能力标签：\n\n| 标签 | 含义 |\n|------|------|\n| `MCP` | MCP 服务器集成 |\n| `Context file` | 支持上下文文件 |\n| `Hooks` | 支持生命周期钩子 |\n| `Skills` | 支持技能系统 |\n| `Commands` | 支持自定义命令 |\n\n资料来源：[packages/cli/src/ui/components/Help.tsx]()\n\n---\n\n\n\n## 代理系统与子代理\n\n### 相关页面\n\n相关主题：[核心工具集](#page-tools), [上下文管理与压缩](#page-context-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/src/agent/agent-session.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agent/agent-session.ts)\n- [packages/core/src/agents/registry.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/registry.ts)\n- [packages/core/src/agents/agent-scheduler.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/agent-scheduler.ts)\n- [packages/core/src/agents/generalist-agent.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/generalist-agent.ts)\n- [packages/core/src/agents/a2a-client-manager.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/a2a-client-manager.ts)\n- [packages/core/src/agents/skill-extraction-agent.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/skill-extraction-agent.ts)\n- [packages/core/src/config/config.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/config/config.ts)\n- [packages/core/src/prompts/snippets.legacy.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/prompts/snippets.legacy.ts)\n- [packages/core/src/availability/policyHelpers.test.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/availability/policyHelpers.test.ts)\n- [packages/sdk/src/tool.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/sdk/src/tool.ts)\n \n\n# 代理系统与子代理\n\n## 概述\n\nGemini CLI 的代理系统（Agent System）是整个命令-line 工具的核心架构，负责协调用户交互、任务执行和工具调用。该系统采用模块化设计，支持多种类型的代理（Agent），包括通用代理（Generalist Agent）和专业技能提取代理（Skill Extraction Agent）。代理系统通过注册机制（Registry）和调度器（Scheduler）统一管理所有代理的生命周期，实现灵活的扩展性和高度的可维护性。\n\n## 系统架构\n\n### 核心组件关系\n\n```mermaid\ngraph TD\n User[用户交互] --> CLI[CLI 界面层]\n CLI --> Session[AgentSession]\n Session --> Registry[AgentRegistry]\n Registry --> Scheduler[AgentScheduler]\n Scheduler --> GeneralistAgent[通用代理]\n Scheduler --> SkillExtractionAgent[技能提取代理]\n GeneralistAgent --> Tools[工具集]\n SkillExtractionAgent --> SkillManager[技能管理器]\n Tools --> FileSystem[文件系统工具]\n Tools --> Shell[Shell 执行工具]\n Tools --> Grep[RipGrep/Grep 工具]\n Tools --> MCP[MCP 服务器工具]\n```\n\n### 代理类型体系\n\n| 代理类型 | 文件位置 | 职责描述 |\n|---------|---------|---------|\n| GeneralistAgent | `packages/core/src/agents/generalist-agent.ts` | 通用任务处理，支持代码理解、生成、调试 |\n| SkillExtractionAgent | `packages/core/src/agents/skill-extraction-agent.ts` | 从会话历史中提取可复用的技能模式 |\n| 未来扩展代理 | `packages/core/src/agents/` 目录 | 通过注册机制动态加载 |\n\n## 代理注册机制\n\n### 注册表（AgentRegistry）\n\n代理系统通过 `AgentRegistry` 实现代理的注册和管理。该注册表维护了一个代理实例的映射表，支持按类型动态查询和实例化。\n\n```mermaid\nclassDiagram\n class AgentRegistry {\n -Map~string, Agent~ agents\n +registerAgent(agent: Agent): void\n +getAgent(type: string): Agent\n +listAgents(): Agent[]\n }\n```\n\n注册表的核心方法包括：\n\n- **registerAgent()** - 将新代理实例注册到系统中\n- **getAgent()** - 根据代理类型获取对应实例\n- **listAgents()** - 列出所有已注册的代理\n\n### 调度器（AgentScheduler）\n\n`AgentScheduler` 负责协调多个代理之间的工作分配和执行顺序。它维护一个任务队列，并根据代理的能力和当前系统状态将任务路由到合适的代理。\n\n## 通用代理（Generalist Agent）\n\n### 核心职责\n\n通用代理是 Gemini CLI 的主要工作代理，负责处理用户的各种自然语言请求。其主要功能包括：\n\n| 功能类别 | 具体能力 |\n|---------|---------|\n| 代码理解 | 分析代码库结构、理解模块依赖、解释算法逻辑 |\n| 代码生成 | 根据描述生成新代码、模板、配置文件 |\n| 调试排错 | 定位问题、分析错误原因、提供修复建议 |\n| 任务自动化 | 执行命令行操作、处理 Git 工作流、查询 Pull Request |\n\n### 工具集成\n\n通用代理通过 `Tool` 接口与各种工具进行交互。核心工具包括：\n\n| 工具名称 | 实现文件 | 功能描述 |\n|---------|---------|---------|\n| LSTool | `config.ts` | 列出目录内容和文件结构 |\n| ReadFileTool | `config.ts` | 读取文件内容 |\n| RipGrepTool | `config.ts` | 使用 Ripgrep 进行正则搜索（优先） |\n| GrepTool | `config.ts` | 使用标准 Grep 进行搜索（回退方案） |\n| UpdateTopicTool | `config.ts` | 更新会话主题 |\n\n工具注册采用条件注册模式，根据系统环境自动选择最优实现：\n\n```typescript\n// 资料来源：packages/core/src/config/config.ts\nif (this.getUseRipgrep()) {\n let useRipgrep = false;\n try {\n useRipgrep = await canUseRipgrep();\n } catch (error: unknown) {\n errorString = String(error);\n }\n if (useRipgrep) {\n maybeRegister(RipGrepTool, () =>\n registry.registerTool(new RipGrepTool(this, this.messageBus)),\n );\n } else {\n debugLogger.warn(`Ripgrep is not available. Falling back to GrepTool.`);\n maybeRegister(GrepTool, () =>\n registry.registerTool(new GrepTool(this, this.messageBus)),\n );\n }\n}\n```\n\n## 技能提取代理（Skill Extraction Agent）\n\n### 概述\n\n技能提取代理（Skill Extraction Agent）是一个专门的子代理，负责从用户与通用代理的会话历史中自动识别和提取可复用的技能模式。这些提取的技能可以被保存为 `SKILL.md` 文件，供将来类似任务使用。\n\n### 工作流程\n\n```mermaid\ngraph TD\n Start[会话进行中] --> Analyze{分析会话历史}\n Analyze --> |发现模式| CreateSkill[创建技能]\n CreateSkill --> GeneratePatch[生成 Patch 文件]\n GeneratePatch --> ValidatePatch[验证 Patch 有效性]\n ValidatePatch --> |通过| SaveSkill[保存技能到 .inbox]\n ValidatePatch --> |失败| Discard[静默丢弃]\n Analyze --> |无明显模式| NoOp[不创建技能]\n SaveSkill --> End[技能可用]\n NoOp --> End\n```\n\n### 技能文件结构\n\n技能代理创建的技能文件遵循标准化结构：\n\n| 文件类型 | 用途 | 加载时机 |\n|---------|-----|---------|\n| `FORMS.md` | 表单定义和交互规范 | 特定命令需要时 |\n| `REFERENCE.md` | API 参考和详细文档 | 引用时按需加载 |\n| `EXAMPLES.md` | 代码示例和使用模式 | 示例请求时 |\n| `SKILL.md` | 主入口，包含元数据和导航 | 始终加载 |\n\n### Patch 文件格式\n\n技能代理使用标准化的统一 diff 格式（Unified Diff）来描述文件变更：\n\n```diff\n--- /absolute/path/to/original/SKILL.md\n+++ /absolute/path/to/original/SKILL.md\n@@ -, +, @@\n \n-\n+\n \n```\n\n**关键规则**：\n\n- 必须使用绝对路径，禁止使用 `a/` 或 `b/` 前缀\n- 每个变更块需要包含 3 行上下文\n- `@@` 头部的行数必须精确匹配\n- Patch 文件名必须为 `extraction.patch`\n- 路径必须在允许的根目录下\n\n### 质量规则\n\n技能提取代理实施严格的质量控制：\n\n| 规则 | 描述 |\n|-----|------|\n| 去重合并 | 优先合并相似技能而非创建新技能 |\n| 职责明确 | 避免创建\"万能\"技能，保持职责单一 |\n| 必需元素 | 每个技能必须包含：触发条件、处理流程、注意事项、验证步骤 |\n| 证据驱动 | 必须有来自会话历史的明确证据支持技能创建 |\n| 空操作正常 | 创建 0 个技能是正常结果，不应强制创建 |\n\n## 代理会话（AgentSession）\n\n### 会话管理\n\n`AgentSession` 是用户与代理系统交互的主要入口点，负责维护对话状态和消息历史。\n\n```mermaid\ngraph LR\n User[用户消息] --> Session[AgentSession]\n Session --> Record[ChatRecordingService]\n Record --> Storage[JSONL 文件]\n Session --> Graph[ContextGraphBuilder]\n Graph --> Context[上下文图]\n Context --> Model[AI 模型]\n Model --> Response[代理响应]\n```\n\n### 会话记录服务\n\n`ChatRecordingService` 负责持久化会话数据，支持以下功能：\n\n| 功能 | 描述 |\n|-----|------|\n| 消息存储 | 将用户和代理消息保存到 JSONL 文件 |\n| 元数据管理 | 维护 sessionId、projectHash、startTime 等元信息 |\n| 条件加载 | 支持仅加载元数据或完整消息 |\n| 增量更新 | 追踪最后更新时间，支持断点续传 |\n\n会话元数据结构：\n\n```typescript\ninterface ConversationMetadata {\n sessionId: string;\n projectHash: string;\n startTime: string;\n lastUpdated: string;\n summary?: string;\n memoryScratchpad?: string;\n directories?: string[];\n kind?: string;\n messageCount: number;\n userMessageCount: number;\n firstUserMessage?: string;\n hasUserOrAssistantMessage: boolean;\n}\n```\n\n## A2A 客户端管理器\n\n### Agent-to-Agent 通信\n\n`a2a-client-manager.ts` 实现了代理之间的通信协议，支持多代理协作场景。\n\n### 核心功能\n\nA2A 客户端管理器处理以下类型的通信：\n\n- **任务委托** - 将复杂任务分解并委托给专业代理\n- **结果聚合** - 收集多个子代理的执行结果\n- **状态同步** - 保持代理间的状态一致性\n\n## 策略与配置\n\n### 模型策略链\n\n代理系统使用策略链（Policy Chain）来选择合适的 AI 模型：\n\n```typescript\n// 资料来源：packages/core/src/availability/policyHelpers.test.ts\ndescribe('policyHelpers', () => {\n describe('resolvePolicyChain', () => {\n it('returns a single-model chain for a custom model', () => {\n const config = createMockConfig({\n getModel: () => 'custom-model',\n });\n const chain = resolvePolicyChain(config);\n expect(chain).toHaveLength(1);\n expect(chain[0]?.model).toBe('custom-model');\n });\n\n it('returns the default chain when active model is \"auto\"', () => {\n const config = createMockConfig({\n getModel: () => DEFAULT_GEMINI_MODEL_AUTO,\n });\n const chain = resolvePolicyChain(config);\n // Expect default chain [Pro, Flash]\n expect(chain).toHaveLength(2);\n });\n });\n});\n```\n\n### 策略链规则\n\n| 模型设置 | 策略行为 |\n|---------|---------|\n| 自定义模型 | 返回单模型链，直接使用指定模型 |\n| 自动模式 (`auto`) | 返回默认链 [Pro, Flash]，自动降级 |\n| Pro 不可用 | 自动切换到 Flash |\n\n### 工具配置\n\n工具注册支持细粒度控制：\n\n| 配置项 | 描述 |\n|-------|------|\n| `coreTools` | 显式启用/禁用核心工具列表 |\n| 模式匹配 | 支持 `toolName`、`ClassName`、`toolName(params)` 三种匹配方式 |\n| Ripgrep 回退 | 自动检测 Ripgrep 可用性，无则回退到 GrepTool |\n\n## 规划模式（Plan Mode）\n\n### 工作流程\n\n当启用规划模式时，系统使用专门的提示模板来引导代理进行结构化规划：\n\n```typescript\n// 资料来源：packages/core/src/prompts/snippets.legacy.ts\nexport function renderPlanningWorkflow(\n options?: PlanningWorkflowOptions,\n): string {\n if (!options) return '';\n return `\n# Active Approval Mode: Plan\n\nYou are operating in **Plan Mode** - a structured planning workflow for designing implementation strategies before execution.\n\n## Available Tools\nThe following read-only tools are available in Plan Mode:\n${options.planModeToolsList}\n- \\`${WRITE_FILE_TOOL_NAME}\\` - Save plans to the plans directory\n- \\`${EDIT_TOOL_NAME}\\` - Update plans in the plans directory\n...\n`;\n}\n```\n\n### 规划模式特点\n\n| 特性 | 描述 |\n|-----|------|\n| 只读工具 | 仅允许使用查看类工具 |\n| 计划存储 | 允许写入计划文件到 plans 目录 |\n| 审批流程 | 计划需用户审批后才能执行 |\n\n## SDK 工具集成\n\n### 工具定义与执行\n\n通过 SDK，第三方可以扩展代理系统的工具集：\n\n```typescript\n// 资料来源：packages/sdk/src/tool.ts\nbindContext(context: SessionContext): SdkTool {\n return new SdkTool(this.definition, this.messageBus, undefined, context);\n}\n\ncreateInvocationWithContext(\n params: z.infer,\n messageBus: MessageBus,\n context: SessionContext | undefined,\n toolName?: string,\n): ToolInvocation, ToolResult> {\n return new SdkToolInvocation(\n params,\n messageBus,\n this.definition.action,\n context || this.context,\n toolName || this.name,\n this.definition.sendErrorsToModel,\n );\n}\n```\n\n### 工具创建示例\n\nSDK 提供了简化工具创建的辅助函数：\n\n```typescript\nimport { z, tool } from '@google/gemini-cli-sdk';\n\nconst myTool = tool({\n name: 'myTool',\n description: 'A custom tool for specific tasks',\n inputSchema: z.object({\n param1: z.string(),\n param2: z.number().optional(),\n }),\n async action(params) {\n // Tool implementation\n return { result: 'success' };\n },\n});\n```\n\n## 总结\n\nGemini CLI 的代理系统采用分层架构设计，通过注册机制实现了高度的可扩展性。通用代理负责处理日常任务，技能提取代理则通过智能分析会话历史自动构建知识库，两者协同工作为用户提供智能化的命令行辅助体验。系统支持通过 SDK 扩展工具集，并通过策略链机制灵活选择 AI 模型，确保在不同场景下都能提供最优的性能和结果质量。\n\n---\n\n\n\n## 上下文管理与压缩\n\n### 相关页面\n\n相关主题：[代理系统与子代理](#page-agent-system), [核心工具集](#page-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/src/context/graph/toGraph.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/context/graph/toGraph.ts)\n- [packages/core/src/services/chatRecordingService.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/services/chatRecordingService.ts)\n- [packages/core/src/context/graph/render.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/context/processors/rollingSummaryProcessor.ts)\n- [packages/core/src/agents/cli-help-agent.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/cli-help-agent.ts)\n \n\n# 上下文管理与压缩\n\n## 概述\n\n在 Gemini CLI 中，上下文管理是确保大型对话会话能够持续运行而不会超出模型令牌限制的核心机制。系统通过多种策略组合，包括对话历史压缩、消息去重、上下文图构建和滚动摘要，来高效管理对话状态。\n\n## 核心组件架构\n\n### 上下文管理系统\n\n上下文管理由多个协同工作的组件构成：\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| ContextGraphBuilder | `packages/core/src/context/graph/toGraph.ts` | 构建对话消息图，处理历史消息转换 |\n| ChatRecordingService | `packages/core/src/services/chatRecordingService.ts` | 会话持久化和元数据管理 |\n| ChatCompressionService | `packages/core/src/context/chatCompressionService.ts` | 对话内容压缩和摘要生成 |\n| RollingSummaryProcessor | `packages/core/src/context/processors/rollingSummaryProcessor.ts` | 滚动式摘要处理 |\n\n## 对话历史处理流程\n\n### 消息图构建机制\n\n系统通过 `ContextGraphBuilder` 将原始对话历史转换为优化的图结构：\n\n```mermaid\ngraph TD\n A[原始消息历史] --> B[Legacy环境头检查]\n B --> C{是否为遗留格式?}\n C -->|是| D[跳过该消息轮次]\n C -->|否| E[遍历消息部件]\n E --> F[生成消息哈希]\n F --> G[计算出现次数]\n G --> H[生成稳定TurnID]\n H --> I[用户消息处理]\n H --> J[函数调用/响应处理]\n I --> K[构建上下文图]\n J --> K\n```\n\n### 消息标识生成策略\n\n每个对话轮次都会生成稳定的唯一标识符，确保会话恢复和状态追踪的可靠性：\n\n1. **内容哈希**：使用 MD5 哈希基于 `角色:内容` 组合生成唯一指纹\n2. **出现计数**：同一条消息可能出现多次，系统通过计数区分\n3. **盐值生成：`turnSalt` = `${哈希}_${出现次数}` 格式\n4. **稳定ID：通过 `getStableId` 函数结合节点标识映射生成最终ID\n\n资料来源：[packages/core/src/context/graph/toGraph.ts:1-50]()\n\n### 遗留环境头处理\n\n系统包含对旧版环境头的兼容性处理：\n\n```typescript\n// 防御性检查：跳过遗留环境头，无论其出现在对话中的哪个位置\nif (msg.role === 'user' && msg.parts.length === 1) {\n const text = msg.parts[0].text;\n if (\n text?.startsWith('') &&\n text?.includes('This is the Gemini CLI')\n ) {\n debugLogger.log(\n '[ContextGraphBuilder] Skipping legacy environment header turn from graph.',\n );\n continue;\n }\n}\n```\n\n这种设计确保了系统演进过程中的向后兼容性，同时维护上下文图的干净结构。\n\n## 会话持久化与服务\n\n### ChatRecordingService 的角色\n\n`ChatRecordingService` 负责会话的持久化存储和元数据管理：\n\n| 功能 | 描述 |\n|------|------|\n| 会话ID管理 | 为每个对话会话分配唯一标识符 |\n| 项目哈希 | 基于项目目录生成唯一项目标识 |\n| 时间戳追踪 | 记录会话开始时间、最后更新时间 |\n| 摘要管理 | 支持会话摘要的存储和检索 |\n| 消息统计 | 追踪用户消息数、总消息数 |\n\n### 对话记录数据结构\n\n```typescript\ninterface ConversationRecord {\n sessionId: string; // 会话唯一标识\n projectHash: string; // 项目标识哈希\n startTime: string; // ISO格式开始时间\n lastUpdated: string; // 最后更新时间\n summary?: string; // 会话摘要\n memoryScratchpad?: string; // 记忆便签\n directories: string[]; // 相关目录\n kind: string; // 会话类型\n messages: Message[]; // 实际消息内容\n messageCount: number; // 总消息数\n userMessageCount: number; // 用户消息数\n firstUserMessage?: string; // 首条用户消息\n hasUserOrAssistantMessage: boolean; // 是否有用户/助手消息\n}\n```\n\n### 元数据模式\n\n系统支持两种加载模式以优化性能：\n\n1. **完整模式 (`metadataOnly: false`)**：加载所有消息内容和元数据\n2. **仅元数据模式 (`metadataOnly: true`)**：仅加载元数据，用于快速列表展示\n\n```typescript\nreturn {\n messages: options?.metadataOnly ? [] : loadedMessages,\n messageCount: options?.metadataOnly\n ? metadataMessages.length || messageIds.length\n : loadedMessages.length,\n};\n```\n\n资料来源：[packages/core/src/services/chatRecordingService.ts:1-100]()\n\n## 上下文压缩策略\n\n### 压缩服务架构\n\n虽然完整的压缩服务源码未在当前上下文中，但根据系统设计模式，上下文压缩通常包括：\n\n| 压缩策略 | 应用场景 |\n|----------|----------|\n| 滚动摘要 | 长对话的历史消息压缩 |\n| 选择性保留 | 保留关键系统消息和最后N条消息 |\n| 消息合并 | 合并连续的同类消息 |\n| 元数据裁剪 | 移除冗余的元数据字段 |\n\n### 摘要处理器\n\n`RollingSummaryProcessor` 实现滚动式摘要生成，周期性地将早期对话内容压缩为摘要，同时保留会话的关键上下文。\n\n## CLI Help Agent 与上下文\n\nCLI Help Agent 是上下文管理的一个典型应用场景，它利用上下文信息提供准确的帮助响应：\n\n```\n### Runtime Context\n- **CLI Version:** ${cliVersion}\n- **Active Model:** ${activeModel}\n- **Today's Date:** ${today}\n```\n\n代理通过内部文档工具 `get_internal_docs` 获取最新文档，并结合运行时上下文给出精确答案。这种设计确保了帮助信息的准确性和时效性。\n\n资料来源：[packages/core/src/agents/cli-help-agent.ts:1-30]()\n\n## 关键设计模式\n\n### 1. 延迟加载模式\n\n通过 `metadataOnly` 选项，系统可以仅在需要时加载完整消息内容，显著降低内存占用。\n\n### 2. 稳定标识符系统\n\n使用哈希+计数的组合方式确保即使相同内容的消息也能获得唯一标识：\n\n```typescript\nconst turnContent = JSON.stringify(msg.parts);\nconst h = createHash('md5')\n .update(`${msg.role}:${turnContent}`)\n .digest('hex');\nconst occurrence = (seenHashes.get(h) || 0) + 1;\nseenHashes.set(h, occurrence);\nconst turnSalt = `${h}_${occurrence}`;\n```\n\n### 3. 向后兼容性\n\n通过显式检测和跳过遗留格式，系统可以在不破坏现有会话的情况下演进。\n\n## 配置与使用\n\n### 上下文相关配置\n\n| 配置项 | 位置 | 说明 |\n|--------|------|------|\n| `showUserIdentity` | UI设置 | 控制用户身份信息显示 |\n| 会话存储路径 | 用户目录 | `~/.gemini/` 下的会话文件 |\n\n### 上下文持久化\n\n会话检查点保存在用户目录：\n\n```\n~/.gemini/\n├── policies/\n│ └── auto-saved.toml # 自动保存的策略配置\n└── [会话数据文件] # JSONL格式的会话记录\n```\n\n## 错误处理与调试\n\n系统包含完善的调试日志机制：\n\n```typescript\ndebugLogger.log('[ContextGraphBuilder] Skipping legacy environment header turn from graph.');\ndebugLogger.error('Error loading conversation record from JSONL:', error);\n```\n\n开发者可以通过设置适当的日志级别来监控上下文管理行为。\n\n## 总结\n\nGemini CLI 的上下文管理与压缩系统通过以下核心机制确保高效运行：\n\n1. **图结构存储**：将对话历史转换为优化的图数据结构\n2. **稳定标识**：基于内容哈希的稳定ID生成确保会话一致性\n3. **分层加载**：支持元数据和完整内容的两级加载模式\n4. **滚动压缩**：周期性摘要生成防止上下文无限增长\n5. **向后兼容**：优雅处理历史格式和演进中的数据结构\n\n---\n\n\n\n## CLI用户界面\n\n### 相关页面\n\n相关主题：[命令系统](#page-commands), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/cli/src/ui/App.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/App.tsx)\n- [packages/cli/src/ui/components/Composer.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/Composer.tsx)\n- [packages/cli/src/ui/components/MainContent.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/MainContent.tsx)\n- [packages/cli/src/ui/components/ToolConfirmationQueue.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/ToolConfirmationQueue.tsx)\n- [packages/cli/src/ui/themes/theme-manager.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/themes/theme-manager.ts)\n \n\n# CLI用户界面\n\n## 概述\n\nGemini CLI 的用户界面（UI）是基于终端的交互式命令行工具界面，采用 React 风格组件化架构构建在 Node.js 运行时之上。界面设计遵循终端友好原则，使用 `ink`（React for CLI）框架实现完整的交互式用户体验，支持富文本渲染、颜色主题、键盘快捷键和多区域布局管理。\n\nUI 系统的核心职责包括：\n\n- 提供消息对话区域，展示用户输入、模型响应和工具调用结果\n- 实现 Composer（输入组合器）处理用户命令和自然语言输入\n- 管理工具确认流程，包括文件读写、网络访问等权限审批\n- 应用主题和配色方案，保持视觉一致性\n- 处理键盘快捷键和导航交互\n\n资料来源：[packages/cli/src/ui/App.tsx:1-50]()\n\n## 架构设计\n\n### 整体架构\n\nCLI UI 采用分层架构，从上至下分为四个主要层次：\n\n```mermaid\ngraph TD\n A[App 根组件] --> B[AppHeader 头部区域]\n A --> C[MainContent 主内容区域]\n A --> D[Composer 输入组合器]\n A --> E[工具确认队列]\n \n B --> B1[Logo 显示]\n B --> B2[版本信息]\n B --> B3[用户身份]\n B --> B4[横幅通知]\n \n C --> C1[消息列表]\n C --> C2[工具执行结果]\n C --> C3[对话框层]\n \n D --> D1[多行输入框]\n D --> D2[快捷方式按钮]\n D --> D3[发送按钮]\n```\n\n### 组件层次结构\n\n```\nApp\n├── AppHeader\n│ ├── Logo/版本信息\n│ ├── UserIdentity\n│ └── Banner\n├── MainContent\n│ ├── Messages\n│ │ ├── UserMessage\n│ │ ├── ModelMessage\n│ │ └── ToolResultMessage\n│ ├── Dialogs\n│ │ ├── InboxDialog\n│ │ ├── FolderTrustDialog\n│ │ └── ExtensionRegistryView\n│ └── Views\n│ ├── GemmaStatus\n│ └── ExtensionDetails\n├── ToolConfirmationQueue\n└── Composer\n ├── InputArea\n └── ActionButtons\n```\n\n资料来源：[packages/cli/src/ui/App.tsx:50-150]()\n\n## 核心组件详解\n\n### App 根组件\n\n`App` 是整个 CLI 界面的根组件，负责协调所有子组件的状态和布局。它维护以下关键状态：\n\n| 状态字段 | 类型 | 说明 |\n|---------|------|------|\n| `showHeader` | boolean | 控制头部区域显示 |\n| `showComposer` | boolean | 控制输入区域显示 |\n| `toolConfirmations` | array | 待确认的工具调用队列 |\n| `activeDialog` | DialogType | 当前激活的对话框类型 |\n\n根组件通过 React Context 向下传递配置和主题信息，确保所有子组件能够访问统一的应用状态。\n\n资料来源：[packages/cli/src/ui/App.tsx:100-200]()\n\n### MainContent 主内容区域\n\n`MainContent` 组件是消息显示和对话框渲染的核心容器。它根据当前状态渲染三种不同的内容模式：\n\n1. **消息模式**：展示对话历史和工具执行结果\n2. **对话框模式**：叠加显示各类交互对话框\n3. **混合模式**：消息列表配合悬浮对话框\n\n组件支持平滑的内容切换动画，通过 `useLayoutEffect` 优化重渲染性能。\n\n资料来源：[packages/cli/src/ui/components/MainContent.tsx:1-80]()\n\n### Composer 输入组合器\n\n`Composer` 是用户输入的核心交互组件，提供类终端的输入体验：\n\n| 功能 | 快捷键 | 说明 |\n|------|--------|------|\n| 发送消息 | Enter/⌘+Enter | 提交当前输入 |\n| 多行输入 | Shift+Enter | 换行继续输入 |\n| 自然语言命令 | 普通文本 | 自动解析执行意图 |\n| Shell 命令 | `!` 前缀 | 执行 shell 命令 |\n| 文件引用 | `@` 前缀 | 引用特定文件 |\n| 取消操作 | Esc (双击) | 清空输入或取消当前操作 |\n\nComposer 支持通过配置切换不同的输入模式，包括标准模式、YOLO 模式（自动接受所有操作）和审核模式。\n\n资料来源：[packages/cli/src/ui/components/Composer.tsx:1-120]()\n\n### ToolConfirmationQueue 工具确认队列\n\n工具确认队列负责管理和展示需要用户授权的操作请求。主要确认类型包括：\n\n| 确认类型 | 显示内容 | 典型场景 |\n|---------|---------|---------|\n| `file-read` | 文件路径列表 | 读取项目文件 |\n| `file-write` | 目标文件列表 | 创建或修改文件 |\n| `network` | 访问的 URL | HTTP 请求 |\n| `exec` | 命令详情 | Shell 命令执行 |\n\n每个确认项包含以下属性：\n- `toolName`：工具名称\n- `confirmationDetails`：详细确认信息\n- `onApprove`：批准回调\n- `onDeny`：拒绝回调\n\n资料来源：[packages/cli/src/ui/components/ToolConfirmationQueue.tsx:1-100]()\n\n## 主题系统\n\n### ThemeManager 主题管理器\n\n`ThemeManager` 负责统一管理 CLI 界面的视觉呈现，采用声明式主题配置：\n\n```typescript\ninterface Theme {\n text: {\n primary: string;\n secondary: string;\n link: string;\n accent: string;\n };\n status: {\n success: string;\n warning: string;\n error: string;\n };\n bg: string;\n border: string;\n}\n```\n\n### 内置主题变体\n\n| 主题名称 | 适用场景 | 特点 |\n|---------|---------|------|\n| `dark` | 深色终端背景 | 高对比度文字 |\n| `light` | 浅色终端背景 | 柔和配色 |\n| `nord` | Nord 配色方案 | 蓝灰色调 |\n| `dracula` | Dracula 配色 | 紫色主调 |\n\n主题支持通过 `GEMINI_THEME` 环境变量或配置文件进行切换。\n\n资料来源：[packages/cli/src/ui/themes/theme-manager.ts:1-80]()\n\n## 交互流程\n\n### 对话交互流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Composer as Composer组件\n participant App as App根组件\n participant Core as Core引擎\n participant Model as Gemini模型\n \n User->>Composer: 输入文本/命令\n Composer->>App: 提交消息\n App->>Core: 发送请求\n Core->>Model: 流式请求\n Model-->>Core: 流式响应\n Core-->>App: 消息片段\n App->>Composer: 清空输入\n App-->>User: 显示消息\n \n Note over Core,Model: 工具调用阶段\n Core->>App: 请求工具确认\n App->>User: 显示确认对话框\n User->>App: 批准/拒绝\n App-->>Core: 确认结果\n```\n\n### 工具确认流程\n\n当模型请求执行敏感操作时，UI 层按以下步骤处理：\n\n1. **检测请求**：Core 引擎识别需要确认的工具调用\n2. **创建确认项**：生成包含操作详情的确认对象\n3. **添加到队列**：将确认项加入 `ToolConfirmationQueue`\n4. **用户决策**：用户查看详情并做出选择\n5. **执行反馈**：根据用户决策执行或拒绝操作\n6. **状态更新**：更新消息状态为已完成/已拒绝\n\n资料来源：[packages/cli/src/ui/App.tsx:200-280]()\n\n## 组件通信机制\n\n### Props Drilling 与 Context\n\nCLI UI 采用混合状态管理策略：\n\n- **Props Drilling**：用于紧密耦合的父子组件间通信\n- **React Context**：用于跨层级状态共享\n - `ConfigContext`：应用配置\n - `ThemeContext`：主题信息\n - `MessagesContext`：消息历史\n\n### 事件流处理\n\n| 事件类型 | 处理层级 | 传播方向 |\n|---------|---------|---------|\n| 键盘事件 | Composer | 组件内处理 |\n| 对话事件 | App | 根组件协调 |\n| 确认事件 | ToolConfirmationQueue | 队列内部处理 |\n\n资料来源：[packages/cli/src/ui/components/ToolConfirmationQueue.tsx:50-80]()\n\n## 界面布局与响应式设计\n\n### 固定布局模式\n\nCLI UI 采用固定布局设计，针对标准终端尺寸优化：\n\n| 区域 | 固定属性 | 说明 |\n|-----|---------|------|\n| 头部 | 固定高度 | Logo、版本、状态 |\n| 消息区 | 弹性高度 | 占据主要内容空间 |\n| 输入区 | 固定高度 | Composer 组件 |\n\n### 宽度自适应\n\n界面支持宽度自适应调整，当终端宽度小于阈值时自动切换为紧凑布局模式。Logo 和元数据从水平排列改为垂直堆叠。\n\n资料来源：[packages/cli/src/ui/components/AppHeader.tsx:30-60]()\n\n## 隐私通知组件\n\n### 双隐私体系\n\nGemini CLI 根据用户使用模式展示不同的隐私声明：\n\n| 隐私通知 | 适用场景 | 内容重点 |\n|---------|---------|---------|\n| `CloudFreePrivacyNotice` | 免费用户 | 数据收集和使用说明 |\n| `GeminiPrivacyNotice` | 付费/企业用户 | API 服务条款引用 |\n\n隐私通知在首次使用或设置变更时显示，包含以下核心内容：\n- 数据收集范围说明\n- 人类审核流程披露\n- 数据保留期限（18个月）\n- 退出选项\n\n资料来源：[packages/cli/src/ui/privacy/CloudFreePrivacyNotice.tsx:1-50]()\n\n## 辅助功能与可达性\n\n### 键盘导航支持\n\n完整的键盘操作支持确保纯键盘用户的可用性：\n\n- **Tab 导航**：在可交互元素间切换\n- **方向键**：列表项选择\n- **Enter**：确认选择\n- **Escape**：取消/返回\n\n### 屏幕阅读器兼容\n\nUI 元素包含语义化的 `aria-*` 属性标注，支持辅助技术正确解读界面结构。\n\n## 扩展机制\n\n### 对话框扩展\n\nCLI UI 提供对话框扩展点，允许注册自定义对话框类型：\n\n| 扩展类型 | 注册方式 | 典型用途 |\n|---------|---------|---------|\n| `InboxDialog` | 技能/补丁通知 | 技能安装确认 |\n| `FolderTrustDialog` | 文件夹信任 | 本地配置加载确认 |\n| `ExtensionRegistryView` | 扩展管理 | 扩展浏览和安装 |\n\n### 视图扩展\n\n`ExtensionDetails` 和 `ExtensionRegistryView` 组件支持展示扩展元数据，包括版本号、星级评分、功能标签等。\n\n资料来源：[packages/cli/src/ui/components/views/ExtensionDetails.tsx:1-60]()\n\n## 总结\n\nGemini CLI 用户界面是一个功能完备的终端交互系统，通过组件化架构实现了清晰的功能分离和良好的可维护性。界面设计充分考虑了终端环境的特殊性，在有限的视觉表现空间内提供了丰富的交互功能，包括对话管理、工具确认、主题定制和扩展支持等核心能力。\n\n---\n\n\n\n## 命令系统\n\n### 相关页面\n\n相关主题：[CLI用户界面](#page-cli-ui)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/cli/src/ui/components/Help.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/Help.tsx)\n- [packages/cli/src/ui/components/messages/ToolConfirmationMessage.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/messages/ToolConfirmationMessage.tsx)\n- [packages/core/src/agents/skill-extraction-agent.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/skill-extraction-agent.ts)\n- [packages/cli/src/ui/components/AboutBox.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/AboutBox.tsx)\n- [README.md](https://github.com/google-gemini/gemini-cli/blob/main/README.md)\n \n\n# 命令系统\n\n## 概述\n\nGemini CLI 的命令系统是用户与 CLI 交互的核心机制，提供了一套完整的命令执行框架。该系统支持多种命令类型，包括内置命令（Built-in Commands）、自定义命令（Custom Commands）和 MCP 命令（Model Context Protocol Commands）。命令系统设计为模块化架构，允许用户通过斜杠命令（`/`前缀）快速调用各种功能，同时支持自然语言执行 shell 命令。\n\n命令系统的主要职责包括命令的注册、解析、路由和执行。通过统一的消息总线（MessageBus）架构，命令系统与工具系统紧密集成，实现了命令执行与 AI 模型响应的无缝衔接。系统还提供了完善的确认机制，确保涉及敏感操作（如网络访问、文件写入）的命令在执行前获得用户授权。\n\n## 命令类型\n\n### 内置命令\n\n内置命令是 Gemini CLI 预置的标准功能集，提供了 CLI 核心操作的入口点。这些命令覆盖了帮助信息、聊天管理、系统设置等常用功能。用户可以通过在输入框中输入 `/commandname` 的方式直接调用这些命令。\n\n内置命令的显示格式包含命令名称和描述信息，部分命令还支持子命令（subCommands）。系统会自动过滤掉标记为隐藏（hidden）的命令，只向用户展示可用的命令选项。命令的分类和组织便于用户快速找到所需功能。\n\n| 命令类型 | 触发方式 | 可见性 |\n|---------|---------|-------|\n| 主命令 | `/commandname` | 默认显示 |\n| 子命令 | `/commandname subcommand` | 嵌套显示 |\n| MCP命令 | `/commandname [MCP]` | 带MCP标识 |\n| Shell命令 | `!command` | 使用感叹号前缀 |\n\n### MCP 命令\n\nMCP（Model Context Protocol）命令是来自外部 MCP 服务器的命令。系统通过 MCP 协议与外部服务器通信，获取这些命令的定义和功能描述。MCP 命令在帮助界面中以 `[MCP]` 标签标识，便于用户识别其来源。\n\nMCP 命令的确认流程与内置命令类似，但在工具确认界面中会明确标注为 MCP 类型。当 MCP 命令涉及网络访问或文件操作时，系统会显示相应的警告信息，提示用户注意安全风险。\n\n### Shell 命令\n\nShell 命令允许用户直接在 CLI 环境中执行系统 shell 命令。用户可以通过两种方式触发 shell 命令：使用 `!` 前缀（如 `!npm run start`），或使用自然语言描述（如 \"start server\"）。\n\nShell 命令在确认界面中以黄色警告色标识，突出显示其潜在风险。系统会对每个 shell 命令进行安全检查，确认其是否涉及网络访问、文件读写等敏感操作。\n\n## 命令解析机制\n\n### 命令解析器架构\n\n命令解析器（SlashCommandResolver）是命令系统的核心组件，负责将用户输入转换为可执行的命令对象。当用户在 CLI 输入框中输入以 `/` 开头的文本时，系统会触发命令解析流程。\n\n解析器首先识别命令前缀，然后匹配用户输入与已注册的命令名称。如果找到完全匹配的命令，则直接返回该命令对象；如果未找到完全匹配，则可能触发命令建议或错误提示。\n\n```\ngraph TD\n A[用户输入 /command] --> B[命令解析器接收]\n B --> C{命令类型判断}\n C -->|内置命令| D[查找内置命令注册表]\n C -->|MCP命令| E[查询MCP服务器]\n C -->|自定义命令| F[搜索自定义命令目录]\n D --> G[返回命令对象]\n E --> G\n F --> G\n G --> H[执行命令处理器]\n H --> I[返回执行结果]\n```\n\n### 命令注册流程\n\n内置命令通过 BuiltinCommandLoader 在 CLI 启动时自动注册到命令系统中。加载器扫描预定义的命令模块，将每个命令及其元数据（名称、描述、子命令等）添加到命令注册表中。\n\n自定义命令则通过文件系统监控实现动态加载。当用户在 `.gemini/commands` 目录下创建新的命令定义文件时，系统会自动检测并注册这些命令，无需重启 CLI。\n\n## 命令确认机制\n\n### 工具确认界面\n\n当命令涉及敏感操作时，系统会显示工具确认界面（ToolConfirmationMessage）供用户审核。该界面清晰列出命令将执行的各项操作及其权限范围。\n\n确认界面显示的信息包括：\n\n- **命令名称**：显示即将执行的命令名称\n- **网络访问**：如果命令需要网络访问，标注为 \"Network: All Urls\"\n- **写入路径**：列出所有将被写入的文件路径\n- **读取路径**：列出所有将被读取的文件路径\n\n### 安全提示\n\nShell 命令在确认界面中以黄色警告色高亮显示，提醒用户这些命令将在系统级别执行。系统会根据 `ApprovalMode` 配置决定是否需要用户手动确认：\n\n- **Manual 模式**：所有敏感操作都需要用户手动确认\n- **Auto-Edit 模式**：自动批准编辑类操作\n- **YOLO 模式**：跳过所有确认直接执行（不推荐）\n\n| 确认模式 | 网络访问 | 文件写入 | 文件读取 |\n|---------|---------|---------|---------|\n| Manual | 需确认 | 需确认 | 需确认 |\n| Auto-Edit | 需确认 | 自动批准 | 自动批准 |\n| YOLO | 自动批准 | 自动批准 | 自动批准 |\n\n## 自定义命令\n\n### 命令定义\n\nGemini CLI 支持用户创建自定义命令来扩展功能。自定义命令存储在项目根目录的 `.gemini/commands` 目录下（资料来源：[README.md:1-100]()）。每个自定义命令都是一个独立的文件，可以包含特定的提示词和执行逻辑。\n\n自定义命令的主要用途包括：\n\n- 封装常用的复杂工作流程为一键操作\n- 为特定项目创建专用命令集\n- 共享和复用团队的最佳实践\n\n### 创建流程\n\n用户可以通过自然语言描述想要创建的命令功能，Gemini CLI 会自动生成相应的命令定义文件。创建过程中，系统会引导用户完善以下信息：\n\n1. **触发条件（Triggers）**：定义命令被激活的关键词或模式\n2. **执行步骤（Procedure）**：详细描述命令的执行逻辑\n3. **注意事项（Pitfalls）**：提醒用户可能遇到的问题\n4. **验证步骤（Verification）**：如何确认命令执行成功\n\n### 技能提取与命令生成\n\nskill-extraction-agent 模块（资料来源：[packages/core/src/agents/skill-extraction-agent.ts:1-100]()）负责从用户的对话历史中提取有价值的工作流程，并将其转化为可复用的技能或命令。该智能体分析会话内容，识别重复性操作，并建议用户是否需要创建自定义命令来简化这些操作。\n\n## 命令显示组件\n\n### 帮助界面\n\nHelp.tsx（资料来源：[packages/cli/src/ui/components/Help.tsx:1-100]()）组件负责渲染命令帮助界面。该组件从命令注册表中获取所有可用命令，过滤隐藏命令后按类别展示给用户。\n\n帮助界面的布局特点：\n\n- 主命令以粗体显示，带有强调色标识\n- 子命令通过缩进和斜线前缀区分\n- MCP 命令标注 `[MCP]` 标签\n- Shell 命令使用 `!` 前缀标识\n\n### 关于界面\n\nAboutBox.tsx（资料来源：[packages/cli/src/ui/components/AboutBox.tsx:1-100]()）组件显示 CLI 版本信息和系统配置状态。该界面虽然不直接处理命令执行，但为用户提供当前会话的技术上下文，包括：\n\n- CLI 版本号\n- Git 提交信息\n- 当前使用的模型版本\n- Sandbox 环境配置\n- 操作系统信息\n\n## 键盘快捷键\n\n命令系统与输入处理系统紧密集成，提供了丰富的键盘快捷键来提升操作效率：\n\n| 快捷键 | 功能 | 说明 |\n|-------|------|------|\n| `Ctrl+Left/Right` | 单词跳转 | 在输入框中按单词快速移动光标 |\n| `Ctrl+C` | 退出 | 退出当前 CLI 会话 |\n| `/` | 命令触发 | 开始输入斜杠命令 |\n\n## 扩展机制\n\n### MCP 服务器集成\n\nGemini CLI 通过 MCP（Model Context Protocol）协议支持扩展服务器。用户可以配置额外的 MCP 服务器来引入新的命令和能力。官方示例包括与 Google Cloud Platform 的 Vertex AI Creative Studio 集成，支持媒体生成功能（Imagen、Veo、Lyria）。\n\nMCP 服务器的配置通过标准 MCP 配置格式管理，CLI 启动时自动发现并注册可用的 MCP 命令。\n\n### 工具绑定\n\n命令系统与工具系统共享相同的消息总线架构。命令可以调用底层工具来完成具体操作，如文件读写、shell 执行、网络请求等。这种设计实现了命令层与功能层的分离，便于维护和扩展。\n\n## 数据流\n\n```\ngraph LR\n A[用户输入] --> B{输入解析}\n B -->|/command| C[内置命令]\n B -->|!command| D[Shell命令]\n B -->|自然语言| E[AI模型处理]\n C --> F[命令执行器]\n D --> G[Shell执行器]\n E --> H[意图识别]\n H --> I[工具调用]\n F --> J[结果展示]\n G --> J\n I --> J\n J --> K[UI更新]\n```\n\n## 最佳实践\n\n### 命令命名规范\n\n创建自定义命令时，建议遵循以下命名规范：\n\n- 使用小写字母和连字符（如 `my-custom-command`）\n- 避免与内置命令名称冲突\n- 使用描述性名称，使命令用途一目了然\n\n### 安全考虑\n\n- 谨慎使用 YOLO 模式，该模式跳过所有安全确认\n- 创建涉及文件操作的命令时，明确指定允许的路径范围\n- 定期检查已注册的命令列表，确保没有未授权的命令\n\n### 性能优化\n\n- 避免在命令中执行过于复杂的逻辑\n- 将耗时操作拆分为多个独立命令\n- 使用子命令组织复杂的功能集\n\n## 参考资料\n\n- Gemini CLI 官方文档：https://www.geminicli.com/docs/reference/commands\n- 自定义命令指南：https://www.geminicli.com/docs/cli/custom-commands\n- 键盘快捷键参考：https://www.geminicli.com/docs/reference/keyboard-shortcuts\n\n---\n\n\n\n## 安全策略与策略引擎\n\n### 相关页面\n\n相关主题：[代理系统与子代理](#page-agent-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/src/policy/policy-engine.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/policy/policy-engine.ts)\n- [packages/core/src/policy/toml-loader.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/policy/toml-loader.ts)\n- [packages/core/src/policy/shell-safety.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/policy/shell-safety.ts)\n- [packages/core/src/policy/sandboxPolicyManager.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/policy/sandboxPolicyManager.ts)\n- [packages/core/src/availability/policyHelpers.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/availability/policyHelpers.ts)\n- [packages/core/src/config/config.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/config/config.ts)\n- [packages/cli/src/commands/extensions/examples/policies/README.md](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/commands/extensions/examples/policies/README.md)\n \n\n# 安全策略与策略引擎\n\n## 概述\n\nGemini CLI 的安全策略与策略引擎是保护用户系统安全的核心组件。该系统通过 TOML 配置文件定义安全规则，并在 CLI 执行命令前进行安全检查，防止恶意或危险操作执行。\n\n策略引擎的核心职责包括：\n\n- 加载和解析 `.toml` 格式的策略文件\n- 在命令执行前进行安全验证\n- 管理沙箱环境的访问权限\n- 处理 shell 命令的安全性评估\n- 支持扩展程序贡献额外的安全规则\n\n## 架构设计\n\n```mermaid\ngraph TD\n A[用户命令] --> B[策略引擎 PolicyEngine]\n B --> C{TOML 加载器
TomlLoader}\n C --> D[核心策略文件]\n C --> E[扩展策略文件]\n C --> F[用户自定义策略]\n D --> G[规则引擎]\n E --> G\n F --> G\n G --> H{安全检查}\n H -->|通过| I[命令执行]\n H -->|拒绝| J[安全警告]\n H -->|需要确认| K[用户确认对话框]\n \n L[ShellSafety] --> G\n M[SandboxPolicyManager] --> G\n```\n\n### 核心组件\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| PolicyEngine | `packages/core/src/policy/policy-engine.ts` | 主策略引擎，协调所有策略检查 |\n| TomlLoader | `packages/core/src/policy/toml-loader.ts` | 解析 TOML 格式的策略配置文件 |\n| ShellSafety | `packages/core/src/policy/shell-safety.ts` | Shell 命令安全性检查 |\n| SandboxPolicyManager | `packages/core/src/policy/sandboxPolicyManager.ts` | 沙箱环境策略管理 |\n| policyHelpers | `packages/core/src/availability/policyHelpers.ts` | 策略链解析和辅助函数 |\n\n## 策略文件格式\n\n### TOML 配置文件结构\n\n策略引擎使用 TOML 格式定义安全规则。每个策略文件包含以下核心部分：\n\n```toml\n# 规则定义\n[rules]\n# 规则名称 = 规则类型\n\n# 确认要求\n[confirm]\n# 命令模式 = 确认消息\n\n# 拒绝规则\n[deny]\n# 命令模式 = 拒绝消息\n\n# 允许路径\n[allowed_paths]\n# 列出允许访问的目录\n```\n\n### 策略文件位置\n\n策略文件按优先级从低到高搜索：\n\n1. **内置核心策略** - CLI 内置的安全规则\n2. **扩展贡献的策略** - 第三方扩展添加的策略\n3. **用户自定义策略** - 用户本地配置的策略\n\n资料来源：[packages/cli/src/commands/extensions/examples/policies/README.md]()\n\n## 策略类型\n\n### 1. 确认规则 (Confirm Rules)\n\n需要用户确认才能执行的命令。配置格式：\n\n```toml\n[confirm]\n\"rm -rf\" = \"此命令将递归删除文件，是否继续？\"\n\"sudo\" = \"即将以管理员权限执行命令\"\n```\n\n当策略引擎检测到匹配的命令模式时，会暂停执行并显示确认对话框。\n\n### 2. 拒绝规则 (Deny Rules)\n\n完全禁止执行的命令。\n\n```toml\n[deny]\n\"grep.*\\\\.env\" = \"禁止搜索敏感文件\"\n\"*credential*\" = \"禁止访问凭证相关文件\"\n```\n\n资料来源：[packages/cli/src/commands/extensions/examples/policies/README.md]()\n\n### 3. 路径限制规则 (Path Restrictions)\n\n限制文件操作在特定目录范围内。\n\n```toml\n[allowed_paths]\nread = [\"/home/user/project\", \"/tmp\"]\nwrite = [\"/home/user/project/src\"]\n```\n\n### 4. 安全检查器 (Safety Checkers)\n\n自定义的安全检查器函数，在特定操作前执行：\n\n```toml\n[safety_checkers]\nallowed_path = true # 启用路径验证检查器\n```\n\n## 策略引擎核心流程\n\n```mermaid\nsequenceDiagram\n participant CLI as Gemini CLI\n participant PE as PolicyEngine\n participant TL as TomlLoader\n participant SS as ShellSafety\n participant SPM as SandboxPolicyManager\n \n CLI->>PE: 执行命令请求\n PE->>TL: 加载策略配置\n TL-->>PE: 返回策略规则列表\n PE->>SS: 检查 Shell 安全性\n SS-->>PE: 安全检查结果\n PE->>SPM: 验证沙箱权限\n SPM-->>PE: 沙箱检查结果\n PE->>PE: 综合评估\n alt 所有检查通过\n PE-->>CLI: 允许执行\n else 存在风险\n PE-->>CLI: 请求用户确认\n else 违反规则\n PE-->>CLI: 拒绝执行\n end\n```\n\n### 主要检查步骤\n\n1. **策略加载阶段** - 收集所有适用策略\n2. **模式匹配阶段** - 匹配命令与规则模式\n3. **安全评估阶段** - 评估命令风险等级\n4. **决策输出阶段** - 返回执行决策\n\n## 沙箱策略管理\n\n### SandboxPolicyManager\n\n`SandboxPolicyManager` 负责管理沙箱执行环境的访问控制策略。\n\n主要功能：\n\n- **目录访问控制** - 限制沙箱内进程的文件系统访问\n- **网络访问限制** - 控制沙箱进程的网络通信\n- **进程隔离** - 管理沙箱内进程的执行权限\n\n资料来源：[packages/core/src/policy/sandboxPolicyManager.ts]()\n\n### 沙箱模式\n\n| 模式 | 描述 | 安全性 |\n|------|------|--------|\n| unrestricted | 无限制模式 | 低 |\n| restricted | 限制模式，仅允许预定义操作 | 中 |\n| sandboxed | 完全沙箱模式，最严格限制 | 高 |\n\n## Shell 安全检查\n\n### ShellSafety 模块\n\n`ShellSafety` 模块专门处理 Shell 命令的安全性评估。\n\n```typescript\ninterface ShellSafetyCheck {\n command: string; // 待检查的命令\n riskLevel: RiskLevel; // 风险等级\n matchedRules: string[]; // 匹配的规则列表\n requiresConfirmation: boolean; // 是否需要确认\n canDeny: boolean; // 是否可以拒绝\n}\n```\n\n### 内置危险命令检测\n\n策略引擎内置以下危险命令的自动检测：\n\n- `rm -rf` - 递归删除文件\n- `dd` - 直接磁盘写入\n- `mkfs` - 格式化文件系统\n- `> /dev/sd*` - 直接写入设备文件\n\n## 策略扩展机制\n\n### 扩展贡献策略\n\n第三方扩展可以通过 `gemini-extension.json` 清单文件贡献安全策略：\n\n```json\n{\n \"policies\": [\n \"policies/*.toml\"\n ]\n}\n```\n\n扩展贡献的策略文件必须位于扩展目录的 `policies/` 子目录中。\n\n### 安全限制\n\n**重要安全约束**：Gemini CLI 会忽略扩展贡献的任何 `allow` 决策或 `yolo` 模式配置。这确保了扩展只能增强安全性，而不能绕过用户确认机制。\n\n资料来源：[packages/cli/src/commands/extensions/examples/policies/README.md]()\n\n## 配置与集成\n\n### 工具注册中的策略应用\n\n策略引擎与工具注册系统集成，在工具注册时应用策略配置：\n\n```typescript\nmaybeRegister(UpdateTopicTool, () =>\n registry.registerTool(new UpdateTopicTool(this, this.messageBus)),\n);\n\nmaybeRegister(LSTool, () =>\n registry.registerTool(new LSTool(this, this.messageBus)),\n);\n\nmaybeRegister(ReadFileTool, () =>\n registry.registerTool(new ReadFileTool(this, this.messageBus)),\n);\n```\n\n资料来源：[packages/core/src/config/config.ts:45-55]()\n\n### 策略链解析\n\n`policyHelpers` 模块提供策略链解析功能，支持多模型场景下的策略协调：\n\n```typescript\nfunction resolvePolicyChain(config: Config): PolicyChain {\n // 根据当前配置返回适用的策略链\n // 支持自定义模型和目录模型的策略分发\n}\n```\n\n资料来源：[packages/core/src/availability/policyHelpers.ts]()\n\n## 错误处理\n\n### 策略验证失败\n\n策略引擎会对加载的策略进行验证：\n\n- TOML 语法验证\n- 规则模式语法检查\n- 路径有效性验证\n- 冲突规则检测\n\n验证失败的策略会被静默丢弃，不会影响其他策略的执行。\n\n### 运行时错误\n\n当策略检查过程中发生错误时：\n\n1. 记录详细错误日志\n2. 返回保守的安全决策（拒绝执行）\n3. 向用户显示友好的错误提示\n\n## 最佳实践\n\n### 为扩展编写策略\n\n1. **明确作用域** - 每个策略文件应有单一明确的目的\n2. **使用具体模式** - 避免过于宽泛的通配符匹配\n3. **提供清晰消息** - 拒绝和确认消息应清楚说明原因\n4. **包含验证步骤** - 添加验证或陷阱步骤确保规则有效\n\n### 用户自定义策略\n\n用户可以在本地配置目录中创建自定义策略文件：\n\n```\n~/.gemini-cli/\n├── policies/\n│ ├── custom-deny.toml\n│ └── project-rules.toml\n```\n\n## 总结\n\nGemini CLI 的安全策略与策略引擎通过模块化设计实现了灵活且强大的安全控制机制。TOML 格式的配置文件提供了易于维护的策略定义方式，而多层级的策略加载和验证流程确保了系统安全性。扩展机制允许社区贡献额外的安全规则，同时保持了核心安全约束不被绕过。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：google-gemini/gemini-cli\n\n摘要：发现 23 个潜在踩坑项，其中 14 个为 high/blocking；最高优先级：安装坑 - 来源证据：Surface or quarantine invalid Auto Memory inbox patches。\n\n## 1. 安装坑 · 来源证据：Surface or quarantine invalid Auto Memory inbox patches\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Surface or quarantine invalid Auto Memory inbox patches\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_58be51e305414f12a3dd5f6c39b5e777 | https://github.com/google-gemini/gemini-cli/issues/26523 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：Memory system bugs and quality improvements\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Memory system bugs and quality improvements\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_956d952c67c7469189ec67aef86139d4 | https://github.com/google-gemini/gemini-cli/issues/26516 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 运行坑 · 来源证据：Change the steering eval test to always pass\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Change the steering eval test to always pass\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e480448796b34a7da894c9769d69b46c | https://github.com/google-gemini/gemini-cli/issues/23313 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 运行坑 · 来源证据：Model frequently creates tmp scripts in random spots\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Model frequently creates tmp scripts in random spots\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_abead6f384f94be497a8893d52d0ca2b | https://github.com/google-gemini/gemini-cli/issues/23571 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 维护坑 · 来源证据：Gemini CLI encounters 400 error with > 128 tools\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Gemini CLI encounters 400 error with > 128 tools\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1e04a5efd78143d79b2ef38a564c428f | https://github.com/google-gemini/gemini-cli/issues/24246 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安全/权限坑 · 来源证据：Add deterministic redaction and reduce Auto Memory logging\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add deterministic redaction and reduce Auto Memory logging\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_33c66a37dc674c5084470c52157d3f4b | https://github.com/google-gemini/gemini-cli/issues/26525 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 7. 安全/权限坑 · 来源证据：All model quotas not resetting, even after days\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：All model quotas not resetting, even after days\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1ed06494b0e8487e9f5b9b5faa68374c | https://github.com/google-gemini/gemini-cli/issues/26967 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。\n\n## 8. 安全/权限坑 · 来源证据：Gemini CLI 0.42.0-preview.1: [API Error: ..... v1internal:generateContent failed, reason: ] Request contains an invalid…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Gemini CLI 0.42.0-preview.1: [API Error: ..... v1internal:generateContent failed, reason: ] Request contains an invalid argument at process.processTicksAndReje…\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9f0cc269f15147bf94171001a3d0a145 | https://github.com/google-gemini/gemini-cli/issues/26572 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 9. 安全/权限坑 · 来源证据：Gemini failed to open in a temporary path A:\\\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Gemini failed to open in a temporary path A:\\\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b7b6d80c305d48d2a7548e12a6621b72 | https://github.com/google-gemini/gemini-cli/issues/25216 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 10. 安全/权限坑 · 来源证据：Robust component level evalutions\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Robust component level evalutions\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0b7e5ce9e4de49d1aae81349f2856cd7 | https://github.com/google-gemini/gemini-cli/issues/24353 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. 安全/权限坑 · 来源证据：Shell command execution gets stuck with \"Waiting input\" after command completes\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Shell command execution gets stuck with \"Waiting input\" after command completes\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_73f28f340a29499e9a1718d38d5500ad | https://github.com/google-gemini/gemini-cli/issues/25166 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 12. 安全/权限坑 · 来源证据：Stop Auto Memory from retrying low-signal sessions indefinitely\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Stop Auto Memory from retrying low-signal sessions indefinitely\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fb1dec66ee3c4a9f9faf5cb91b286667 | https://github.com/google-gemini/gemini-cli/issues/26522 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 13. 安全/权限坑 · 来源证据：Tool \"save_memory\" not found.\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Tool \"save_memory\" not found.\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7b0f9e9404664597ab5f60b481da55fe | https://github.com/google-gemini/gemini-cli/issues/26563 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。\n\n## 14. 安全/权限坑 · 来源证据：Your idiotic AI disobeyed me completely lied and has now cost me 300 dollars worth of work that went into my obsidian -…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Your idiotic AI disobeyed me completely lied and has now cost me 300 dollars worth of work that went into my obsidian - 10000s of files and work deleted not re…\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4bdaf010293245ac9e6f4ceece341d76 | https://github.com/google-gemini/gemini-cli/issues/26856 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 安装坑 · 来源证据：feat(cli): expose model thinking events in --output-format stream-json\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat(cli): expose model thinking events in --output-format stream-json\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5c2ad6806ee6413dbf441b91f6862364 | https://github.com/google-gemini/gemini-cli/issues/22083 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 16. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:968197216 | https://github.com/google-gemini/gemini-cli | README/documentation is current enough for a first validation pass.\n\n## 17. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:968197216 | https://github.com/google-gemini/gemini-cli | last_activity_observed missing\n\n## 18. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:968197216 | https://github.com/google-gemini/gemini-cli | no_demo; severity=medium\n\n## 19. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:968197216 | https://github.com/google-gemini/gemini-cli | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 20. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:968197216 | https://github.com/google-gemini/gemini-cli | no_demo; severity=medium\n\n## 21. 安全/权限坑 · 来源证据：CLI on start picks wrong default model\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：CLI on start picks wrong default model\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4285a488cff443c1a1e3586dbea13786 | https://github.com/google-gemini/gemini-cli/issues/26971 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 22. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:968197216 | https://github.com/google-gemini/gemini-cli | issue_or_pr_quality=unknown\n\n## 23. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:968197216 | https://github.com/google-gemini/gemini-cli | release_recency=unknown\n\n\n",
"markdown_key": "gemini-cli",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:968197216",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/google-gemini/gemini-cli"
},
{
"evidence_id": "art_bd6e7af3ffc4457586f0e469d5773faa",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/google-gemini/gemini-cli#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "gemini-cli 说明书",
"toc": [
"https://github.com/google-gemini/gemini-cli 项目说明书",
"目录",
"项目概述",
"项目简介",
"系统架构",
"核心功能模块",
"主要功能特性",
"发布渠道",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "8cda688fe24de99a0add72d70ed54c19c2e9f5c0",
"repo_inspection_error": null,
"repo_inspection_files": [
"Dockerfile",
"package.json",
"README.md",
"docs/index.md",
"docs/local-development.md",
"docs/redirects.json",
"docs/npm.md",
"docs/integration-tests.md",
"docs/releases.md",
"docs/issue-and-pr-automation.md",
"docs/CONTRIBUTING.md",
"docs/release-confidence.md",
"docs/sidebar.json",
"docs/cli/system-prompt.md",
"docs/cli/skills-best-practices.md",
"docs/cli/token-caching.md",
"docs/cli/model-routing.md",
"docs/cli/notifications.md",
"docs/cli/acp-mode.md",
"docs/cli/gemini-ignore.md",
"docs/cli/git-worktrees.md",
"docs/cli/cli-reference.md",
"docs/cli/model-steering.md",
"docs/cli/using-agent-skills.md",
"docs/cli/skills.md",
"docs/cli/headless.md",
"docs/cli/sandbox.md",
"docs/cli/auto-memory.md",
"docs/cli/checkpointing.md",
"docs/cli/custom-commands.md",
"docs/cli/rewind.md",
"docs/cli/enterprise.md",
"docs/cli/gemini-md.md",
"docs/cli/creating-skills.md",
"docs/cli/model.md",
"docs/cli/telemetry.md",
"docs/cli/trusted-folders.md",
"docs/cli/settings.md",
"docs/cli/generation-settings.md",
"docs/cli/plan-mode.md"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# @google/gemini-cli - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 @google/gemini-cli 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`.gemini/skills/async-pr-review/SKILL.md`, `.gemini/skills/behavioral-evals/SKILL.md`, `.gemini/skills/ci/SKILL.md`, `.gemini/skills/code-reviewer/SKILL.md` 等 Claim：`clm_0004` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`.gemini/skills/async-pr-review/SKILL.md`, `.gemini/skills/behavioral-evals/SKILL.md`, `.gemini/skills/ci/SKILL.md`, `.gemini/skills/code-reviewer/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md`, `packages/sdk/README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `npx @google/gemini-cli` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `npm install -g @google/gemini-cli` 证据：`README.md` Claim：`clm_0006` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86, `clm_0009` supported 0.86\n- `npm install -g @google/gemini-cli@preview` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `npm install -g @google/gemini-cli@latest` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `npm install -g @google/gemini-cli@nightly` 证据：`README.md` Claim：`clm_0009` supported 0.86\n- `git clone https://github.com/google-gemini/gemini-cli` 证据：`README.md` Claim：`clm_0010` supported 0.86\n- `npm install @google/gemini-cli-sdk` 证据：`packages/sdk/README.md` Claim：`clm_0011` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：仅建议沙盒试装\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：仅建议沙盒试装\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：真实输出质量不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`.gemini/skills/async-pr-review/SKILL.md`, `.gemini/skills/behavioral-evals/SKILL.md`, `.gemini/skills/ci/SKILL.md`, `.gemini/skills/code-reviewer/SKILL.md` 等 Claim：`clm_0004` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.gemini/skills/async-pr-review/SKILL.md`, `.gemini/skills/behavioral-evals/SKILL.md`, `.gemini/skills/ci/SKILL.md`, `.gemini/skills/code-reviewer/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md`, `packages/sdk/README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0005` supported 0.86\n\n### 现在还不能相信\n\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.gemini/skills/async-pr-review/SKILL.md`, `.gemini/skills/behavioral-evals/SKILL.md`, `.gemini/skills/ci/SKILL.md`, `.gemini/skills/code-reviewer/SKILL.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`, `packages/sdk/README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.gemini/skills/async-pr-review/SKILL.md`, `.gemini/skills/behavioral-evals/SKILL.md`, `.gemini/skills/ci/SKILL.md`, `.gemini/skills/code-reviewer/SKILL.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`, `packages/sdk/README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0012` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md`, `packages/sdk/README.md` Claim：`clm_0013` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`.gemini/skills/async-pr-review/SKILL.md`, `.gemini/skills/behavioral-evals/SKILL.md`, `.gemini/skills/ci/SKILL.md`, `.gemini/skills/code-reviewer/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md`, `packages/sdk/README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：2670\n- 重要文件覆盖：40/2670\n- 证据索引条目：80\n- 角色 / Skill 条目：14\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 @google/gemini-cli 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 @google/gemini-cli 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 @google/gemini-cli 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 14 个角色 / Skill / 项目文档条目。\n\n- **async-pr-review**（skill）：Trigger this skill when the user wants to start an asynchronous PR review, run background checks on a PR, or check the status of a previously started async PR review. 激活提示：当用户任务与“async-pr-review”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.gemini/skills/async-pr-review/SKILL.md`\n- **behavioral-evals**（skill）：Guidance for creating, running, fixing, and promoting behavioral evaluations. Use when verifying agent decision logic, debugging failures, debugging prompt steering, or adding workspace regression tests. 激活提示：当用户任务与“behavioral-evals”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.gemini/skills/behavioral-evals/SKILL.md`\n- **ci**（skill）：This skill enables the agent to efficiently monitor GitHub Actions, triage failures, and bridge remote CI errors to local development. It defaults to automatic replication of failures to streamline the fix cycle. 激活提示：当用户任务与“ci”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.gemini/skills/ci/SKILL.md`\n- **code-reviewer**（skill）：This skill guides the agent in conducting professional and thorough code reviews for both local development and remote Pull Requests. 激活提示：当用户任务与“code-reviewer”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.gemini/skills/code-reviewer/SKILL.md`\n- **docs-changelog**（skill）：- 激活提示：当用户任务与“docs-changelog”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.gemini/skills/docs-changelog/SKILL.md`\n- **docs-writer**（skill）：As an expert technical writer and editor for the Gemini CLI project, you produce accurate, clear, and consistent documentation. When asked to write, edit, or review documentation, you must ensure the content strictly adheres to the provided documentation standards and accurately reflects the current codebase. Adhere to the contribution process in CONTRIBUTING.md and the following project standards. 激活提示：当用户任务与“docs-writer”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.gemini/skills/docs-writer/SKILL.md`\n- **github-issue-creator**（skill）：This skill guides the creation of high-quality GitHub issues that adhere to the repository's standards and use the appropriate templates. 激活提示：当用户任务与“github-issue-creator”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.gemini/skills/github-issue-creator/SKILL.md`\n- **pr-address-comments**（skill）：Use this skill if the user asks you to help them address GitHub PR comments for their current branch of the Gemini CLI. Requires gh CLI tool. 激活提示：当用户任务与“pr-address-comments”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.gemini/skills/pr-address-comments/SKILL.md`\n- **pr-creator**（skill）：This skill guides the creation of high-quality Pull Requests that adhere to the repository's standards. 激活提示：当用户任务与“pr-creator”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.gemini/skills/pr-creator/SKILL.md`\n- **review-duplication**（skill）：Use this skill during code reviews to proactively investigate the codebase for duplicated functionality, reinvented wheels, or failure to reuse existing project best practices and shared utilities. 激活提示：当用户任务与“review-duplication”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.gemini/skills/review-duplication/SKILL.md`\n- **string-reviewer**（skill）： 激活提示：当用户任务与“string-reviewer”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.gemini/skills/string-reviewer/SKILL.md`\n- **greeter**（skill）：A friendly greeter skill 激活提示：当用户任务与“greeter”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/cli/src/commands/extensions/examples/skills/skills/greeter/SKILL.md`\n- **skill-creator**（skill）：Guide for creating effective skills. This skill should be used when users want to create a new skill or update an existing skill that extends Gemini CLI's capabilities with specialized knowledge, workflows, or tool integrations. 激活提示：当用户任务与“skill-creator”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/core/src/skills/builtin/skill-creator/SKILL.md`\n- **pirate-skill**（skill）：Speak like a pirate. 激活提示：当用户任务与“pirate-skill”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/sdk/test-data/skills/pirate-skill/SKILL.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **Gemini CLI Project Context**（documentation）：Gemini CLI is an open-source AI agent that brings the power of Gemini directly into the terminal. It is designed to be a terminal-first, extensible, and powerful tool for developers. 证据：`GEMINI.md`\n- **Gemini CLI**（documentation）：! Gemini CLI CI https://github.com/google-gemini/gemini-cli/actions/workflows/ci.yml/badge.svg https://github.com/google-gemini/gemini-cli/actions/workflows/ci.yml ! Gemini CLI E2E Chained https://github.com/google-gemini/gemini-cli/actions/workflows/chained e2e.yml/badge.svg https://github.com/google-gemini/gemini-cli/actions/workflows/chained e2e.yml ! Version https://img.shields.io/npm/v/@google/gemini-cli https://www.npmjs.com/package/@google/gemini-cli ! License https://img.shields.io/github/license/google-gemini/gemini-cli https://github.com/google-gemini/gemini-cli/blob/main/LICENSE ! View Code Wiki https://assets.codewiki.google/readme-badge/static.svg https://codewiki.google/github… 证据：`README.md`\n- **Behavioral Evals**（documentation）：Behavioral evaluations evals are tests designed to validate the agent's behavior in response to specific prompts. They serve as a critical feedback loop for changes to system prompts, tool definitions, and other model-steering mechanisms, and as a tool for assessing feature reliability by model, and preventing regressions. 证据：`evals/README.md`\n- **CPU Performance Integration Test Harness**（documentation）：CPU Performance Integration Test Harness 证据：`perf-tests/README.md`\n- **Gemini CLI A2A Server @google/gemini-cli-a2a-server**（documentation）：Gemini CLI A2A Server @google/gemini-cli-a2a-server 证据：`packages/a2a-server/GEMINI.md`\n- **Gemini CLI A2A Server**（documentation）：All code in this package is experimental and under active development 证据：`packages/a2a-server/README.md`\n- **React & Ink CLI UI**（documentation）：- Side Effects : Use reducers for complex state transitions; avoid setState triggers in callbacks. - Always fix react-hooks/exhaustive-deps lint errors by adding the missing dependencies. - Shortcuts : only define keyboard shortcuts in packages/cli/src/ui/key/keyBindings.ts - Do not implement any logic performing custom string measurement or string truncation. Use Ink layout instead leveraging ResizeObserver as needed. When using ResizeObserver , prefer the useCallback ref pattern as seen in MaxSizedBox.tsx to ensure size measurements are captured as soon as the element is available, avoiding potential rendering timing issues. - Avoid prop drilling when at all possible. 证据：`packages/cli/GEMINI.md`\n- **Agent Client Protocol ACP Implementation**（documentation）：Agent Client Protocol ACP Implementation 证据：`packages/cli/src/acp/README.md`\n- **MCP Server Example**（documentation）：This is a basic example of an MCP Model Context Protocol server used as a Gemini CLI extension. It demonstrates how to expose tools and prompts to the Gemini CLI. 证据：`packages/cli/src/commands/extensions/examples/mcp-server/README.md`\n- **Policy engine example extension**（documentation）：This extension demonstrates how to contribute security rules and safety checkers to the Gemini CLI Policy Engine. 证据：`packages/cli/src/commands/extensions/examples/policies/README.md`\n- **Themes Example**（documentation）：This is an example of a Gemini CLI extension that adds a custom theme. 证据：`packages/cli/src/commands/extensions/examples/themes-example/README.md`\n- **Gemini CLI Core @google/gemini-cli-core**（documentation）：Gemini CLI Core @google/gemini-cli-core 证据：`packages/core/GEMINI.md`\n- **Gemini CLI DevTools**（documentation）：Integrated Developer Tools for Gemini CLI, providing a Chrome DevTools-like interface for Network and Console inspection. Launched automatically when the general.devtools setting is enabled. 证据：`packages/devtools/GEMINI.md`\n- **Gemini CLI SDK @google/gemini-cli-sdk**（documentation）：Gemini CLI SDK @google/gemini-cli-sdk 证据：`packages/sdk/GEMINI.md`\n- **@google/gemini-cli-sdk**（documentation）：The Gemini CLI SDK provides a programmatic interface to interact with Gemini models and tools. 证据：`packages/sdk/README.md`\n- **Gemini CLI VS Code Companion gemini-cli-vscode-ide-companion**（documentation）：Gemini CLI VS Code Companion gemini-cli-vscode-ide-companion 证据：`packages/vscode-ide-companion/GEMINI.md`\n- **Gemini CLI Companion**（documentation）：The Gemini CLI Companion extension pairs with Gemini CLI https://github.com/google-gemini/gemini-cli . This extension is compatible with both VS Code and VS Code forks. 证据：`packages/vscode-ide-companion/README.md`\n- **Gemini CLI Bot Cognitive Repository**（documentation）：Gemini CLI Bot Cognitive Repository 证据：`tools/gemini-cli-bot/README.md`\n- **Package**（package_manifest）：{ \"name\": \"@google/gemini-cli\", \"version\": \"0.44.0-nightly.20260512.g022e8baef\", \"engines\": { \"node\": \" =20.0.0\" }, \"type\": \"module\", \"workspaces\": \"packages/ \" , \"private\": \"true\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/google-gemini/gemini-cli.git\" }, \"config\": { \"sandboxImageUri\": \"us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.44.0-nightly.20260512.g022e8baef\" }, \"scripts\": { \"start\": \"cross-env NODE ENV=development node scripts/start.js\", \"start:prod\": \"cross-env NODE ENV=production node scripts/start.js\", \"start:a2a-server\": \"CODER AGENT PORT=41242 npm run start --workspace @google/gemini-cli-a2a-server\", \"debug\": \"cross-env DEBUG=1 node --inspect-brk sc… 证据：`package.json`\n- **How to contribute**（documentation）：We would love to accept your patches and contributions to this project. This document includes: 证据：`CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"name\": \"@google/gemini-cli-a2a-server\", \"version\": \"0.44.0-nightly.20260512.g022e8baef\", \"description\": \"Gemini CLI A2A Server\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/google-gemini/gemini-cli.git\", \"directory\": \"packages/a2a-server\" }, \"type\": \"module\", \"main\": \"dist/index.js\", \"bin\": { \"gemini-cli-a2a-server\": \"dist/a2a-server.mjs\" }, \"scripts\": { \"build\": \"node ../../scripts/build package.js\", \"start\": \"node dist/src/http/server.js\", \"lint\": \"eslint . --ext .ts,.tsx\", \"format\": \"prettier --write .\", \"test\": \"vitest run\", \"test:ci\": \"vitest run --coverage\", \"typecheck\": \"tsc --noEmit\" }, \"files\": \"dist\" , \"dependencies\": { \"@a2a-js/sdk\": \"0.3.11\", \"@google-cloud/… 证据：`packages/a2a-server/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@google/gemini-cli\", \"version\": \"0.44.0-nightly.20260512.g022e8baef\", \"description\": \"Gemini CLI\", \"license\": \"Apache-2.0\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/google-gemini/gemini-cli.git\" }, \"type\": \"module\", \"main\": \"dist/index.js\", \"bin\": { \"gemini\": \"dist/index.js\" }, \"scripts\": { \"build\": \"node ../../scripts/build package.js\", \"start\": \"node dist/index.js\", \"debug\": \"node --inspect-brk dist/index.js\", \"lint\": \"eslint . --ext .ts,.tsx\", \"format\": \"prettier --write .\", \"test\": \"vitest run\", \"test:ci\": \"vitest run\", \"posttest\": \"npm run build\", \"typecheck\": \"tsc --noEmit\" }, \"files\": \"dist\" , \"config\": { \"sandboxImageUri\": \"us-docker.pkg.dev/gemini-co… 证据：`packages/cli/package.json`\n- **Package**（package_manifest）：{ \"name\": \"mcp-server-example\", \"version\": \"1.0.0\", \"description\": \"Example MCP Server for Gemini CLI Extension\", \"type\": \"module\", \"main\": \"example.js\", \"dependencies\": { \"@modelcontextprotocol/sdk\": \"^1.23.0\", \"zod\": \"^3.22.4\" } } 证据：`packages/cli/src/commands/extensions/examples/mcp-server/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@google/gemini-cli-core\", \"version\": \"0.44.0-nightly.20260512.g022e8baef\", \"description\": \"Gemini CLI Core\", \"license\": \"Apache-2.0\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/google-gemini/gemini-cli.git\" }, \"type\": \"module\", \"main\": \"dist/index.js\", \"scripts\": { \"bundle:browser-mcp\": \"node scripts/bundle-browser-mcp.mjs\", \"build\": \"node ../../scripts/build package.js\", \"lint\": \"eslint . --ext .ts,.tsx\", \"format\": \"prettier --write .\", \"test\": \"vitest run\", \"test:ci\": \"vitest run\", \"posttest\": \"npm run build\", \"typecheck\": \"tsc --noEmit\" }, \"files\": \"dist\" , \"dependencies\": { \"@a2a-js/sdk\": \"0.3.11\", \"@bufbuild/protobuf\": \"^2.11.0\", \"@google-cloud/logging\": \"… 证据：`packages/core/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@google/gemini-cli-devtools\", \"version\": \"0.44.0-nightly.20260512.g022e8baef\", \"license\": \"Apache-2.0\", \"type\": \"module\", \"main\": \"dist/src/index.js\", \"types\": \"dist/src/index.d.ts\", \"exports\": { \".\": { \"types\": \"./dist/src/index.d.ts\", \"default\": \"./dist/src/index.js\" } }, \"scripts\": { \"build\": \"npm run build:client && tsc -p tsconfig.build.json\", \"build:client\": \"node esbuild.client.js\" }, \"files\": \"dist\", \"client/index.html\" , \"engines\": { \"node\": \" =20\" }, \"devDependencies\": { \"react\": \"^19.2.0\", \"react-dom\": \"^19.2.0\" }, \"dependencies\": { \"ws\": \"^8.16.0\" } } 证据：`packages/devtools/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@google/gemini-cli-sdk\", \"version\": \"0.44.0-nightly.20260512.g022e8baef\", \"description\": \"Gemini CLI SDK\", \"license\": \"Apache-2.0\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/google-gemini/gemini-cli.git\" }, \"type\": \"module\", \"main\": \"dist/index.js\", \"types\": \"dist/index.d.ts\", \"scripts\": { \"build\": \"node ../../scripts/build package.js\", \"lint\": \"eslint . --ext .ts,.tsx\", \"format\": \"prettier --write .\", \"test\": \"vitest run\", \"test:ci\": \"vitest run\", \"typecheck\": \"tsc --noEmit\" }, \"files\": \"dist\" , \"dependencies\": { \"@google/gemini-cli-core\": \"file:../core\", \"zod\": \"^3.23.8\", \"zod-to-json-schema\": \"^3.23.1\" }, \"devDependencies\": { \"typescript\": \"^5.3.3\", \"vitest… 证据：`packages/sdk/package.json`\n- **Package**（package_manifest）：{ \"name\": \"gemini-cli-vscode-ide-companion\", \"displayName\": \"Gemini CLI Companion\", \"description\": \"Enable Gemini CLI with direct access to your IDE workspace.\", \"version\": \"0.44.0-nightly.20260512.g022e8baef\", \"publisher\": \"google\", \"icon\": \"assets/icon.png\", \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/google-gemini/gemini-cli.git\", \"directory\": \"packages/vscode-ide-companion\" }, \"engines\": { \"vscode\": \"^1.99.0\" }, \"license\": \"LICENSE\", \"preview\": true, \"categories\": \"AI\" , \"keywords\": \"gemini-cli\", \"gemini cli\", \"gemini\", \"gemini code\", \"cli\", \"ide integration\", \"ide companion\" , \"activationEvents\": \"onStartupFinished\" , \"contributes\": { \"configuration\": { \"title\": \"Gemini C… 证据：`packages/vscode-ide-companion/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@lvce-editor/ripgrep\", \"version\": \"0.0.0-dev\", \"description\": \"A module for using ripgrep in a Node project\", \"main\": \"src/index.js\", \"typings\": \"src/index.d.ts\", \"type\": \"module\", \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/lvce-editor/ripgrep\" }, \"scripts\": { \"postinstall\": \"node ./src/postinstall.js\", \"test\": \"node --experimental-vm-modules node modules/jest/bin/jest.js\", \"test:watch\": \"node --experimental-vm-modules node modules/jest/bin/jest.js --watch\", \"format\": \"prettier --write .\" }, \"keywords\": \"lvce-editor\", \"ripgrep\" , \"author\": \"Lvce Editor\", \"license\": \"MIT\", \"dependencies\": { \"@lvce-editor/verror\": \"^1.6.0\", \"execa\": \"^9.5.2\", \"extract-zip\": \"^2.0.1\",… 证据：`third_party/get-ripgrep/package.json`\n- **Async PR Review**（skill_instruction）：This skill provides a set of tools to asynchronously review a Pull Request. It will create a background job to run the project's preflight checks, execute Gemini-powered test plans, and perform a comprehensive code review using custom prompts. 证据：`.gemini/skills/async-pr-review/SKILL.md`\n- **Behavioral Evals**（skill_instruction）：Behavioral evaluations evals are tests that validate the agent's decision-making e.g., tool choice rather than pure functionality. They are critical for verifying prompt changes, debugging steerability, and preventing regressions. 证据：`.gemini/skills/behavioral-evals/SKILL.md`\n- **CI Replicate & Status**（skill_instruction）：This skill enables the agent to efficiently monitor GitHub Actions, triage failures, and bridge remote CI errors to local development. It defaults to automatic replication of failures to streamline the fix cycle. 证据：`.gemini/skills/ci/SKILL.md`\n- **Code Reviewer**（skill_instruction）：This skill guides the agent in conducting professional and thorough code reviews for both local development and remote Pull Requests. 证据：`.gemini/skills/code-reviewer/SKILL.md`\n- **Procedure: Updating Changelog for New Releases**（skill_instruction）：Procedure: Updating Changelog for New Releases 证据：`.gemini/skills/docs-changelog/SKILL.md`\n- **docs-writer skill instructions**（skill_instruction）：As an expert technical writer and editor for the Gemini CLI project, you produce accurate, clear, and consistent documentation. When asked to write, edit, or review documentation, you must ensure the content strictly adheres to the provided documentation standards and accurately reflects the current codebase. Adhere to the contribution process in CONTRIBUTING.md and the following project standards. 证据：`.gemini/skills/docs-writer/SKILL.md`\n- **GitHub Issue Creator**（skill_instruction）：This skill guides the creation of high-quality GitHub issues that adhere to the repository's standards and use the appropriate templates. 证据：`.gemini/skills/github-issue-creator/SKILL.md`\n- **Comment Review Procedure**（skill_instruction）：You are helping the user address comments on their Pull Request. These comments may have come from an automated review agent or a team member. 证据：`.gemini/skills/pr-address-comments/SKILL.md`\n- **Pull Request Creator**（skill_instruction）：This skill guides the creation of high-quality Pull Requests that adhere to the repository's standards. 证据：`.gemini/skills/pr-creator/SKILL.md`\n- **Review Duplication**（skill_instruction）：This skill provides a structured workflow for investigating a codebase during a code review to identify duplicated logic, reinvented utilities, and missed opportunities to reuse established patterns. By executing this workflow, you ensure that new code integrates seamlessly with the existing project architecture. 证据：`.gemini/skills/review-duplication/SKILL.md`\n- **String Reviewer**（skill_instruction）：Act as a Senior UX Writer. Look for user-facing strings that are too long, unclear, or inconsistent. This includes inline text, error messages, and other user-facing text. 证据：`.gemini/skills/string-reviewer/SKILL.md`\n- **Skill**（skill_instruction）：You are a friendly greeter. When the user says \"hello\" or asks for a greeting, you should reply with: \"Greetings from the skills-example extension! 👋\" 证据：`packages/cli/src/commands/extensions/examples/skills/skills/greeter/SKILL.md`\n- **Skill Creator**（skill_instruction）：This skill provides guidance for creating effective skills. 证据：`packages/core/src/skills/builtin/skill-creator/SKILL.md`\n- **Gemini CLI Test Utils @google/gemini-cli-test-utils**（documentation）：Gemini CLI Test Utils @google/gemini-cli-test-utils 证据：`packages/test-utils/GEMINI.md`\n- **Package**（package_manifest）：{ \"name\": \"@google/gemini-cli-test-utils\", \"version\": \"0.44.0-nightly.20260512.g022e8baef\", \"private\": true, \"main\": \"src/index.ts\", \"license\": \"Apache-2.0\", \"type\": \"module\", \"scripts\": { \"build\": \"node ../../scripts/build package.js\", \"typecheck\": \"tsc --noEmit\" }, \"dependencies\": { \"@google/gemini-cli-core\": \"file:../core\", \"@lydell/node-pty\": \"1.1.0\", \"asciichart\": \"^1.5.25\", \"strip-ansi\": \"^7.1.2\", \"vitest\": \"^3.2.4\" }, \"devDependencies\": { \"typescript\": \"^5.3.3\" }, \"engines\": { \"node\": \" =20\" } } 证据：`packages/test-utils/package.json`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **Skill**（skill_instruction）：You are a pirate. Respond to everything in pirate speak. Always mention \"Arrr\". 证据：`packages/sdk/test-data/skills/pirate-skill/SKILL.md`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`packages/vscode-ide-companion/LICENSE`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`third_party/get-ripgrep/LICENSE`\n- **Gemini CLI documentation**（documentation）：Gemini CLI brings the power of Gemini models directly into your terminal. Use it to understand code, automate tasks, and build workflows with your local project context. 证据：`docs/index.md`\n- **Integration tests**（documentation）：This document provides information about the integration testing framework used in this project. 证据：`docs/integration-tests.md`\n- **Automation and triage processes**（documentation）：This document provides a detailed overview of the automated processes we use to manage and triage issues and pull requests. Our goal is to provide prompt feedback and ensure that contributions are reviewed and integrated efficiently. Understanding this automation will help you as a contributor know what to expect and how to best interact with our repository bots. 证据：`docs/issue-and-pr-automation.md`\n- **Local development guide**（documentation）：This guide provides instructions for setting up and using local development features for Gemini CLI. 证据：`docs/local-development.md`\n- **Package overview**（documentation）：This monorepo contains two main packages: @google/gemini-cli and @google/gemini-cli-core . 证据：`docs/npm.md`\n- **Release confidence strategy**（documentation）：This document outlines the strategy for gaining confidence in every release of Gemini CLI. It serves as a checklist and quality gate for release manager to ensure we are shipping a high-quality product. 证据：`docs/release-confidence.md`\n- **Gemini CLI releases**（documentation）：!IMPORTANT Coordinate with the Release Manager: The release manager is responsible for coordinating patches and releases. Please update them before performing any of the release actions described in this document. 证据：`docs/releases.md`\n- **Enterprise Admin Controls**（documentation）：Gemini CLI empowers enterprise administrators to manage and enforce security policies and configuration settings across their entire organization. Secure defaults are enabled automatically for all enterprise users, but can be customized via the Management Console https://goo.gle/manage-gemini-cli . 证据：`docs/admin/enterprise-controls.md`\n- **Gemini CLI release notes**（documentation）：Gemini CLI has three major release channels: nightly, preview, and stable. For most users, we recommend the stable release. 证据：`docs/changelogs/index.md`\n- **Latest stable release: v0.42.0**（documentation）：For most users, our latest stable release is the recommended release. Install the latest stable version with: 证据：`docs/changelogs/latest.md`\n- **Preview release: v0.43.0-preview.0**（documentation）：Our preview release includes the latest, new, and experimental features. This release may not be as stable as our latest weekly release latest.md . 证据：`docs/changelogs/preview.md`\n- **ACP Mode**（documentation）：ACP Agent Client Protocol mode is a special operational mode of Gemini CLI designed for programmatic control, primarily for IDE and other developer tool integrations. It uses a JSON-RPC protocol over stdio to communicate between Gemini CLI agent and a client. 证据：`docs/cli/acp-mode.md`\n- **Auto Memory**（documentation）：Auto Memory is an experimental feature that mines your past Gemini CLI sessions in the background and proposes durable memory updates and reusable Agent Skills ./skills.md . You review each candidate before it becomes available to future sessions: apply memory updates, promote skills, or discard anything you do not want. 证据：`docs/cli/auto-memory.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`GEMINI.md`, `README.md`, `evals/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`GEMINI.md`, `README.md`, `evals/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概述**：importance `high`\n - source_paths: README.md, package.json, packages/cli/src/gemini.tsx\n- **安装与配置**：importance `high`\n - source_paths: docs/get-started/installation.mdx, docs/get-started/authentication.mdx, package.json\n- **系统架构**：importance `high`\n - source_paths: packages/cli/index.ts, packages/core/index.ts, packages/cli/src/interactiveCli.tsx, packages/cli/src/nonInteractiveCli.ts\n- **包结构详解**：importance `medium`\n - source_paths: packages/a2a-server/src/index.ts, packages/cli/src/index.ts, packages/core/src/index.ts, packages/sdk/src/index.ts\n- **核心工具集**：importance `high`\n - source_paths: packages/core/src/tools/definitions/coreTools.ts, packages/core/src/tools/shell.ts, packages/core/src/tools/read-file.ts, packages/core/src/tools/write-file.ts, packages/core/src/tools/web-search.ts\n- **代理系统与子代理**：importance `high`\n - source_paths: packages/core/src/agent/agent-session.ts, packages/core/src/agents/registry.ts, packages/core/src/agents/agent-scheduler.ts, packages/core/src/agents/generalist-agent.ts, packages/core/src/agents/a2a-client-manager.ts\n- **上下文管理与压缩**：importance `high`\n - source_paths: packages/core/src/context/contextManager.ts, packages/core/src/context/chatCompressionService.ts, packages/core/src/context/graph/render.ts, packages/core/src/context/processors/rollingSummaryProcessor.ts\n- **CLI用户界面**：importance `medium`\n - source_paths: packages/cli/src/ui/App.tsx, packages/cli/src/ui/components/Composer.tsx, packages/cli/src/ui/components/MainContent.tsx, packages/cli/src/ui/components/ToolConfirmationQueue.tsx, packages/cli/src/ui/themes/theme-manager.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `8cda688fe24de99a0add72d70ed54c19c2e9f5c0`\n- inspected_files: `Dockerfile`, `package.json`, `README.md`, `docs/index.md`, `docs/local-development.md`, `docs/redirects.json`, `docs/npm.md`, `docs/integration-tests.md`, `docs/releases.md`, `docs/issue-and-pr-automation.md`, `docs/CONTRIBUTING.md`, `docs/release-confidence.md`, `docs/sidebar.json`, `docs/cli/system-prompt.md`, `docs/cli/skills-best-practices.md`, `docs/cli/token-caching.md`, `docs/cli/model-routing.md`, `docs/cli/notifications.md`, `docs/cli/acp-mode.md`, `docs/cli/gemini-ignore.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：Surface or quarantine invalid Auto Memory inbox patches\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Surface or quarantine invalid Auto Memory inbox patches\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_58be51e305414f12a3dd5f6c39b5e777 | https://github.com/google-gemini/gemini-cli/issues/26523 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：Memory system bugs and quality improvements\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Memory system bugs and quality improvements\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_956d952c67c7469189ec67aef86139d4 | https://github.com/google-gemini/gemini-cli/issues/26516 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：Change the steering eval test to always pass\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Change the steering eval test to always pass\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_e480448796b34a7da894c9769d69b46c | https://github.com/google-gemini/gemini-cli/issues/23313 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：Model frequently creates tmp scripts in random spots\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Model frequently creates tmp scripts in random spots\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_abead6f384f94be497a8893d52d0ca2b | https://github.com/google-gemini/gemini-cli/issues/23571 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：Gemini CLI encounters 400 error with > 128 tools\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Gemini CLI encounters 400 error with > 128 tools\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_1e04a5efd78143d79b2ef38a564c428f | https://github.com/google-gemini/gemini-cli/issues/24246 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：Add deterministic redaction and reduce Auto Memory logging\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add deterministic redaction and reduce Auto Memory logging\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_33c66a37dc674c5084470c52157d3f4b | https://github.com/google-gemini/gemini-cli/issues/26525 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：All model quotas not resetting, even after days\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：All model quotas not resetting, even after days\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_1ed06494b0e8487e9f5b9b5faa68374c | https://github.com/google-gemini/gemini-cli/issues/26967 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：Gemini CLI 0.42.0-preview.1: [API Error: ..... v1internal:generateContent failed, reason: ] Request contains an invalid…\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Gemini CLI 0.42.0-preview.1: [API Error: ..... v1internal:generateContent failed, reason: ] Request contains an invalid argument at process.processTicksAndReje…\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_9f0cc269f15147bf94171001a3d0a145 | https://github.com/google-gemini/gemini-cli/issues/26572 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：Gemini failed to open in a temporary path A:\\\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Gemini failed to open in a temporary path A:\\\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_b7b6d80c305d48d2a7548e12a6621b72 | https://github.com/google-gemini/gemini-cli/issues/25216 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：Robust component level evalutions\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Robust component level evalutions\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_0b7e5ce9e4de49d1aae81349f2856cd7 | https://github.com/google-gemini/gemini-cli/issues/24353 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：google-gemini/gemini-cli\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：Surface or quarantine invalid Auto Memory inbox patches（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Memory system bugs and quality improvements（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Change the steering eval test to always pass（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Model frequently creates tmp scripts in random spots（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Gemini CLI encounters 400 error with > 128 tools（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/google-gemini/gemini-cli 项目说明书\n\n生成时间：2026-05-13 09:42:22 UTC\n\n## 目录\n\n- [项目概述](#page-overview)\n- [安装与配置](#page-installation)\n- [系统架构](#page-architecture)\n- [包结构详解](#page-package-structure)\n- [核心工具集](#page-tools)\n- [代理系统与子代理](#page-agent-system)\n- [上下文管理与压缩](#page-context-management)\n- [CLI用户界面](#page-cli-ui)\n- [命令系统](#page-commands)\n- [安全策略与策略引擎](#page-security-policy)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[安装与配置](#page-installation), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/google-gemini/gemini-cli/blob/main/README.md)\n- [packages/cli/src/ui/components/AboutBox.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/AboutBox.tsx)\n- [packages/cli/src/ui/components/AppHeader.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/AppHeader.tsx)\n- [packages/core/src/agents/skill-extraction-agent.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/skill-extraction-agent.ts)\n- [packages/core/src/services/chatRecordingService.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/services/chatRecordingService.ts)\n- [packages/core/src/skills/builtin/skill-creator/SKILL.md](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/skills/builtin/skill-creator/SKILL.md)\n \n\n# 项目概述\n\n## 项目简介\n\nGemini CLI 是由 Google 开发的一款命令行工具，它将 Gemini AI 的强大能力直接带到终端环境中。通过自然语言交互，开发者可以在不离开命令行界面的情况下完成代码理解、生成、调试以及自动化任务执行等多种工作。资料来源：[README.md:1-50]()\n\n该项目采用 TypeScript/Node.js 构建，支持多平台运行（Windows、macOS、Linux），并提供 npm、Homebrew、MacPorts 和 Conda 等多种安装方式。资料来源：[README.md:150-200]()\n\n## 系统架构\n\nGemini CLI 采用模块化架构设计，主要由以下几个核心包组成：\n\n| 包名称 | 职责描述 |\n|--------|----------|\n| `packages/cli` | 命令行界面实现，包含 UI 组件、用户交互和身份验证 |\n| `packages/core` | 核心业务逻辑，包含 Agent 系统、技能管理和上下文管理 |\n| `packages/devtools` | 开发工具组件，提供调试和网络请求分析功能 |\n\n```mermaid\ngraph TD\n A[用户终端] --> B[CLI 入口层]\n B --> C[UI 组件层]\n C --> D[核心业务层]\n D --> E[Agent 代理层]\n E --> F[模型服务层]\n E --> G[技能系统层]\n E --> H[上下文管理]\n \n F --> I[Gemini API]\n G --> J[本地技能存储]\n H --> K[对话记录服务]\n```\n\n资料来源：[packages/cli/src/gemini.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/gemini.tsx)\n\n## 核心功能模块\n\n### 1. 用户界面系统\n\nGemini CLI 提供了一个功能丰富的终端用户界面，使用 React 风格组件构建。主要界面组件包括：\n\n**头部组件 (AppHeader)**\n\n显示应用状态信息，包括版本号、更新状态和用户身份信息。资料来源：[packages/cli/src/ui/components/AppHeader.tsx:1-80]()\n\n```typescript\n// AppHeader 核心数据结构\ninterface AppHeaderProps {\n showHeader: boolean;\n showDetails: boolean;\n config: Settings;\n updateInfo?: UpdateInfo;\n bannerVisible: boolean;\n bannerText?: string;\n}\n```\n\n**关于对话框 (AboutBox)**\n\n展示详细的系统信息，包括 CLI 版本、Git 提交信息、当前使用的模型、沙箱环境配置和操作系统信息。资料来源：[packages/cli/src/ui/components/AboutBox.tsx:1-60]()\n\n### 2. 认证与隐私系统\n\n认证流程通过 `AuthDialog` 组件管理，支持多种认证方式。用户首次使用时会看到服务条款和隐私声明提示。资料来源：[packages/cli/src/ui/auth/AuthDialog.tsx:1-80]()\n\n隐私声明文件包括：\n\n- **GeminiPrivacyNotice.tsx** - Gemini API 隐私条款\n- **CloudFreePrivacyNotice.tsx** - 免费服务隐私通知\n\n这些组件向用户明确说明数据收集范围和使用目的，包括人类审阅者可能阅读处理数据以提升产品质量的机制。资料来源：[packages/cli/src/ui/privacy/CloudFreePrivacyNotice.tsx:1-50]()\n\n### 3. 技能（Skills）系统\n\n技能系统是 Gemini CLI 的核心扩展机制，允许用户创建和管理可重用的任务模板。\n\n**技能创建器 (Skill Creator)**\n\n内置的技能创建器指导用户如何构建高质量技能。一个完整的技能包包含以下结构：资料来源：[packages/core/src/skills/builtin/skill-creator/SKILL.md:1-100]()\n\n```\nskill-name/\n├── SKILL.md # 必需：技能定义和触发条件\n├── scripts/ # 可选：确定性执行脚本\n├── references/ # 可选：参考文档\n└── assets/ # 可选：资源文件\n```\n\n**技能提取代理 (Skill Extraction Agent)**\n\n智能地从对话历史中提取有价值的工作流程，并将其转换为可重用的技能。该代理使用结构化的 patch 格式来记录文件变更。资料来源：[packages/core/src/agents/skill-extraction-agent.ts:1-50]()\n\n### 4. 对话录制服务\n\n`ChatRecordingService` 负责管理会话历史，支持会话的保存、加载和恢复。每个会话记录包含：资料来源：[packages/core/src/services/chatRecordingService.ts:1-80]()\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| sessionId | string | 会话唯一标识符 |\n| projectHash | string | 项目哈希值 |\n| startTime | string | 会话开始时间 |\n| lastUpdated | string | 最后更新时间 |\n| messages | Message[] | 完整消息历史 |\n| memoryScratchpad | string | 记忆便签内容 |\n\n```mermaid\ngraph LR\n A[用户对话] --> B[ChatRecordingService]\n B --> C[JSONL 文件存储]\n D[会话恢复] --> B\n B --> E[上下文加载]\n E --> F[Agent 处理]\n```\n\n### 5. 上下文图构建\n\n`toGraph.ts` 模块负责将对话历史转换为结构化的上下文图，支持消息去重和历史追溯。系统通过 MD5 哈希生成稳定的轮次标识，确保相同内容的消息能够被正确识别。资料来源：[packages/core/src/context/graph/toGraph.ts:1-80]()\n\n### 6. 扩展系统\n\nGemini CLI 支持 MCP（Model Context Protocol）扩展，允许第三方开发者扩展功能。扩展详情界面 (`ExtensionDetails`) 显示每个扩展的版本、星级、Google 拥有标识以及支持的特性标签。资料来源：[packages/cli/src/ui/components/views/ExtensionDetails.tsx:1-100]()\n\n## 主要功能特性\n\n### 代码理解与生成\n\n- 查询和编辑大型代码库\n- 使用多模态能力从 PDF、图片或草图生成新应用\n- 使用自然语言调试和排除问题\n\n### 自动化与集成\n\n- 自动化运维任务，如查询 Pull Request 或处理复杂变基\n- 通过 MCP 服务器连接新能力，包括使用 Imagen、Veo 或 Lyria 进行媒体生成\n- 在脚本中非交互式运行，实现工作流自动化\n\n### 高级能力\n\n- 内置 Google Search 集成，获取实时信息\n- 对话检查点功能，保存和恢复复杂会话\n- 自定义上下文文件（GEMINI.md），为项目定制行为\n\n### GitHub 集成\n\n可通过 Gemini CLI GitHub Action 直接将 Gemini CLI 集成到 GitHub 工作流中。资料来源：[README.md:80-120]()\n\n## 发布渠道\n\n| 渠道 | 发布频率 | 特点 |\n|------|----------|------|\n| Preview | 每周二 UTC 23:59 | 未经完全验证，可能存在回归问题 |\n| Stable | 每周二 UTC 20:00 | 经过验证的稳定版本 |\n| Nightly | 每日 UTC 00:00 | 主分支最新变更，可能包含未解决问题 |\n\n资料来源：[README.md:180-220]()\n\n## 安装方式\n\nGemini CLI 支持多种安装途径：\n\n| 安装方式 | 命令 |\n|----------|------|\n| npm 全局安装 | `npm install -g @google/gemini-cli` |\n| Homebrew | `brew install gemini-cli` |\n| MacPorts | `sudo port install gemini-cli` |\n| Conda 环境 | 通过 conda 环境安装 nodejs 后使用 npm |\n\n资料来源：[README.md:140-170]()\n\n## 技术栈概览\n\n- **运行时**: Node.js\n- **UI 框架**: React + TypeScript\n- **终端渲染**: Ink（React for CLI）\n- **包管理**: npm workspaces\n- **语言**: TypeScript\n\n---\n\n\n\n## 安装与配置\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/google-gemini/gemini-cli/blob/main/README.md)\n- [packages/cli/src/ui/auth/AuthDialog.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/auth/AuthDialog.tsx)\n- [packages/cli/src/ui/auth/LoginRestartDialog.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/auth/LoginRestartDialog.tsx)\n- [packages/cli/src/ui/components/AboutBox.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/AboutBox.tsx)\n \n\n# 安装与配置\n\nGemini CLI 是 Google 开发的命令行工具，为开发者提供基于 AI 的代码理解和生成能力。本页面详细介绍 Gemini CLI 的多种安装方式、认证配置以及基础设置，帮助用户快速上手使用。\n\n## 系统要求\n\n在开始安装之前，请确保系统满足以下要求：\n\n| 要求项 | 说明 |\n|--------|------|\n| Node.js | 推荐 Node.js 18.x 或更高版本 |\n| 包管理器 | npm、yarn 或 pnpm |\n| 操作系统 | macOS、Linux、Windows |\n| 网络 | 能够访问 npm registry 和 Google AI 服务 |\n\n## 安装方式\n\nGemini CLI 支持多种安装方式，用户可根据自身环境选择最适合的方法。\n\n### 通过 npm 全局安装\n\n最直接的安装方式是通过 npm 进行全局安装：\n\n```bash\nnpm install -g @google/gemini-cli\n```\n\n资料来源：[README.md:1]()\n\n### 通过 Homebrew 安装（macOS/Linux）\n\nmacOS 和 Linux 用户可使用 Homebrew 进行安装：\n\n```bash\nbrew install gemini-cli\n```\n\n资料来源：[README.md:1]()\n\n### 通过 MacPorts 安装（macOS）\n\nmacOS 用户也可选择 MacPorts 方式：\n\n```bash\nsudo port install gemini-cli\n```\n\n资料来源：[README.md:1]()\n\n### 通过 Anaconda 安装（受限环境）\n\n对于受限环境，Anaconda 提供了隔离的安装方案：\n\n```bash\n# 创建并激活新环境\nconda create -y -n gemini_env -c conda-forge nodejs\nconda activate gemini_env\n\n# 在环境内通过 npm 全局安装 Gemini CLI\nnpm install -g @google/gemini-cli\n```\n\n资料来源：[README.md:1]()\n\n## 发布渠道\n\nGemini CLI 提供三种发布渠道，用户可根据需求选择不同的版本。\n\n### 预览版（Preview）\n\n新的预览版本每周二 UTC 23:59 发布，这些版本可能包含回归问题或其他待解决的问题。适合希望测试最新功能的用户：\n\n```bash\nnpm install -g @google/gemini-cli@preview\n```\n\n资料来源：[README.md:1]()\n\n### 稳定版（Stable）\n\n新的稳定版本每周二 UTC 20:00 发布，这是对上周预览版的完整升级，并包含所有 bug 修复和验证：\n\n```bash\nnpm install -g @google/gemini-cli@latest\n```\n\n资料来源：[README.md:1]()\n\n### 夜间版（Nightly）\n\n每日 UTC 00:00 发布，包含主分支的所有最新更改：\n\n```bash\nnpm install -g @google/gemini-cli@nightly\n```\n\n资料来源：[README.md:1]()\n\n## 认证配置\n\n首次使用 Gemini CLI 时需要进行身份验证。工具支持多种认证方式。\n\n### 认证方式选择\n\n启动 Gemini CLI 后，系统会显示认证对话框，提示选择认证方式：\n\n```bash\ngemini\n```\n\n认证界面会展示以下选项供用户选择：\n\n- Google 账号登录\n- API Key 认证（适用于企业用户）\n- 其他认证方式\n\n用户可使用 Enter 键进行选择。资料来源：[AuthDialog.tsx:1]()\n\n### Google 登录流程\n\n选择 Google 账号登录后，系统会显示登录进度：\n\n```\n使用 Google 账号登录中... 正在重启 Gemini CLI 以继续。\n```\n\n登录成功后需要重启 CLI 以完成认证流程：\n\n```\n您已成功使用 Google 账号登录。Gemini CLI 需要重新启动。\n请按 R 重启，或按 Esc 选择其他认证方式。\n```\n\n资料来源：[LoginRestartDialog.tsx:1]()\n\n### 服务条款与隐私声明\n\n在认证过程中，用户需要阅读并同意以下服务条款：\n\n| 条款 | 链接 |\n|------|------|\n| Gemini API 概述 | https://ai.google.dev/docs/gemini_api_overview |\n| AI Studio 服务条款 | https://aistudio.google.com/ |\n| Google 开发者服务条款 | https://developers.google.com/terms |\n| Gemini API 附加服务条款 | https://ai.google.dev/gemini-api/terms |\n\n资料来源：[packages/cli/src/ui/privacy/GeminiPrivacyNotice.tsx:1]()\n\n### 数据收集与隐私\n\nGemini CLI 会收集以下数据用于改进产品和服务：\n\n- 您的提示词及相关代码\n- 生成的输出和代码编辑\n- 相关功能使用信息\n- 您的反馈\n\n为确保质量并改进产品，人工审核员可能会阅读、标注和处理收集的数据。Google 会采取措施在审核前断开数据与 Google 账号的关联，存储期限最长为 18 个月。\n\n资料来源：[packages/cli/src/ui/privacy/CloudFreePrivacyNotice.tsx:1]()\n\n## 配置文件\n\n### 设置文件位置\n\nGemini CLI 的配置文件位于用户主目录下的 `~/.gemini/settings.json`。此文件可自定义工具的各种行为和选项。\n\n资料来源：[README.md:1]()\n\n### MCP 服务器配置\n\n通过 MCP（Model Context Protocol）服务器配置，可以扩展 Gemini CLI 的功能：\n\n```json\n{\n \"mcpServers\": {\n \"@github\": {},\n \"@slack\": {},\n \"@database\": {}\n }\n}\n```\n\n配置后即可在对话中使用 MCP 服务器功能：\n\n```\n> @github 列出我的开放拉取请求\n> @slack 发送今日提交的摘要到 #dev 频道\n> @database 运行查询以查找非活跃用户\n```\n\n资料来源：[README.md:1]()\n\n## 验证安装\n\n安装完成后，可通过以下方式验证安装是否成功并查看版本信息。\n\n### 查看版本信息\n\n```bash\ngemini --version\n```\n\n或启动交互式会话后，在关于对话框中查看：\n\n| 信息项 | 说明 |\n|--------|------|\n| CLI 版本 | 当前安装的版本号 |\n| Git 提交 | 源代码的 Git 提交哈希 |\n| 模型 | 当前使用的 AI 模型 |\n| 沙盒环境 | 沙盒配置信息 |\n| 操作系统 | 当前操作系统信息 |\n\n资料来源：[AboutBox.tsx:1]()\n\n### 快速测试\n\n创建测试目录并启动 Gemini CLI：\n\n```bash\ncd new-project/\ngemini\n> 写一个简单的问候程序\n```\n\n如果程序能够正常响应，说明安装和配置均已成功。\n\n资料来源：[README.md:1]()\n\n## 卸载指南\n\n如需卸载 Gemini CLI，请参阅官方卸载指南：https://www.geminicli.com/docs/resources/uninstall\n\n资料来源：[README.md:1]()\n\n## 故障排除\n\n### 常见安装问题\n\n| 问题 | 解决方案 |\n|------|----------|\n| 权限错误 | 使用 `sudo` 或配置 npm 全局路径 |\n| Node.js 版本不兼容 | 升级到 Node.js 18.x 或更高版本 |\n| 网络连接失败 | 检查代理设置或使用国内镜像 |\n\n### 认证问题\n\n如果认证过程中遇到问题：\n\n1. 确保 Google 账号可以正常访问 Google AI 服务\n2. 检查网络连接是否正常\n3. 清除浏览器缓存后重试\n4. 使用 `/bug` 命令直接从 CLI 报告问题\n\n## 下一步\n\n安装和配置完成后，您可以：\n\n- 阅读[命令参考文档](https://www.geminicli.com/docs/reference/commands)了解所有可用命令\n- 配置 [MCP 服务器](https://www.geminicli.com/docs/tools/mcp-server) 扩展功能\n- 设置 [GEMINI.md 文件](https://www.geminicli.com/docs/cli/gemini-md) 为项目提供持久上下文\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[包结构详解](#page-package-structure), [核心工具集](#page-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/cli/src/ui/components/AboutBox.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/AboutBox.tsx)\n- [packages/cli/src/ui/components/AppHeader.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/AppHeader.tsx)\n- [packages/cli/src/ui/auth/AuthDialog.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/auth/AuthDialog.tsx)\n- [packages/core/src/agents/skill-extraction-agent.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/skill-extraction-agent.ts)\n- [packages/core/src/services/chatRecordingService.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/services/chatRecordingService.ts)\n- [packages/cli/src/ui/components/views/ExtensionDetails.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/views/ExtensionDetails.tsx)\n \n\n# 系统架构\n\n## 概述\n\nGemini CLI 是 Google 开发的一款命令行工具，旨在通过自然语言交互帮助开发者完成代码理解、生成、调试和自动化任务。该工具基于 Gemini 模型构建，支持交互式和非交互式两种运行模式，可无缝集成到各类开发工作流中。\n\n系统的核心架构分为三大层次：**CLI 层**（命令行接口和 UI 渲染）、**Core 层**（核心业务逻辑和代理系统）以及**扩展层**（技能系统、MCP 服务器和自定义命令）。这种分层设计确保了各模块的职责清晰，便于维护和扩展。\n\n资料来源：[packages/cli/src/ui/components/AboutBox.tsx:1-50]()\n\n## 核心组件架构\n\n### 组件层次结构\n\nGemini CLI 采用 monorepo 结构，主要包含以下核心包：\n\n| 包名 | 职责 | 主要功能 |\n|------|------|----------|\n| `packages/cli` | 命令行接口层 | CLI 入口、UI 组件、交互处理、配置管理 |\n| `packages/core` | 核心业务层 | 代理系统、技能提取、聊天录制、服务层 |\n| `packages/devtools` | 开发者工具 | API 调试、日志查看、请求监控 |\n\n资料来源：[README.md:1-100]()\n\n### 包间依赖关系\n\n```mermaid\ngraph TD\n A[packages/cli] --> B[packages/core]\n A --> C[packages/devtools]\n B --> D[Gemini API]\n C --> B\n A --> E[用户终端]\n```\n\nCLI 包依赖于 Core 包提供核心功能，同时通过 devtools 包提供调试能力。用户通过终端与 CLI 层交互，CLI 层调用 Core 层处理业务逻辑，最终与外部 Gemini API 通信。\n\n## CLI 层架构\n\n### 入口点设计\n\nCLI 层提供两种运行模式以适应不同的使用场景：\n\n| 模式 | 文件位置 | 用途 |\n|------|----------|------|\n| 交互模式 | `packages/cli/src/interactiveCli.tsx` | 实时对话、工具确认、用户交互 |\n| 非交互模式 | `packages/cli/src/nonInteractiveCli.ts` | 脚本集成、自动化任务、CI/CD |\n\n交互模式使用 React 组件渲染终端 UI，支持键盘导航和实时反馈；非交互模式则专注于参数解析和一次性任务执行。\n\n资料来源：[packages/cli/src/ui/components/AboutBox.tsx:1-30]()\n\n### UI 组件体系\n\nUI 层基于 React 和 Ink（终端 React）构建，主要组件包括：\n\n```mermaid\ngraph TD\n A[AppHeader] --> B[UserIdentity]\n A --> C[Banner]\n D[Dialogs] --> E[AuthDialog]\n D --> F[FolderTrustDialog]\n D --> G[ModelDialog]\n D --> H[InboxDialog]\n I[Messages] --> J[ToolConfirmationMessage]\n I --> K[ScrollableDiffViewport]\n L[Views] --> M[ExtensionDetails]\n L --> N[GemmaStatus]\n```\n\n**核心 UI 组件说明：**\n\n- **AppHeader**：应用头部，显示版本信息（`v{version}`）、更新状态、用户身份和计划信息\n- **AuthDialog**：认证对话框，处理 Google 账户登录和服务条款确认\n- **FolderTrustDialog**：文件夹信任对话框，扫描并展示本地配置文件的安全警告\n- **ModelDialog**：模型选择对话框，显示 API 配额信息\n- **ToolConfirmationMessage**：工具确认消息，处理文件修改和外部编辑器集成\n\n资料来源：[packages/cli/src/ui/components/AppHeader.tsx:1-80]()\n资料来源：[packages/cli/src/ui/auth/AuthDialog.tsx:1-60]()\n\n### 应用头部组件\n\n`AppHeader` 组件负责渲染应用的主标识和元信息，支持两种布局模式：\n\n```typescript\n// 列布局：用于窄终端或存在 Logo 文本时\nconst useColumnLayout = !!logoTextArt || isNarrow;\n\n// 行布局：用于宽终端\nflexDirection={useColumnLayout ? 'column' : 'row'}\n```\n\n头部信息包括：CLI 版本号、模型版本、沙箱环境、操作系统信息以及可选的 Git 提交信息。\n\n资料来源：[packages/cli/src/ui/components/AboutBox.tsx:20-50]()\n资料来源：[packages/cli/src/ui/components/AppHeader.tsx:30-70]()\n\n## Core 层架构\n\n### 代理系统\n\nCore 层的核心是代理系统，负责处理用户请求、调用工具和管理对话状态。\n\n**技能提取代理**（`skill-extraction-agent.ts`）是该系统的关键组件：\n\n- 从对话中识别可复用的工作流程\n- 生成统一差异格式（unified diff）的补丁文件\n- 将补丁保存至 `~/.gemini/skills/.patch`\n- 支持技能合并、作用域管理和质量验证\n\n```mermaid\ngraph TD\n A[用户对话] --> B[技能提取代理]\n B --> C{分析有效性}\n C -->|有有效模式| D[生成补丁]\n C -->|无有效模式| E[静默丢弃]\n D --> F[验证补丁格式]\n F -->|通过| G[保存至 skills 目录]\n F -->|失败| E\n```\n\n资料来源：[packages/core/src/agents/skill-extraction-agent.ts:1-100]()\n\n### 聊天录制服务\n\n`ChatRecordingService` 负责管理和持久化对话记录：\n\n```typescript\nexport class ChatRecordingService {\n private conversationFile: string | null = null;\n private cachedConversation: ConversationRecord | null = null;\n private sessionId: string;\n private projectHash: string;\n}\n```\n\n对话记录包含以下元数据：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `sessionId` | string | 会话唯一标识 |\n| `projectHash` | string | 项目哈希值 |\n| `startTime` | ISO8601 | 会话开始时间 |\n| `lastUpdated` | ISO8601 | 最后更新时间 |\n| `memoryScratchpad` | string | 记忆便签内容 |\n| `messageCount` | number | 消息总数 |\n| `userMessageCount` | number | 用户消息数 |\n\n资料来源：[packages/core/src/services/chatRecordingService.ts:1-80]()\n\n## 认证与隐私系统\n\n### 认证流程\n\n认证系统通过 `AuthDialog` 组件引导用户完成登录流程：\n\n```mermaid\ngraph TD\n A[启动 CLI] --> B{检查认证状态}\n B -->|未认证| C[显示 AuthDialog]\n B -->|已认证| D[进入主界面]\n C --> D\n C --> E[选择认证方式]\n E --> F[完成登录]\n F --> D\n```\n\n认证对话框包含以下选项和处理逻辑：\n- Google 账户登录\n- 服务条款确认\n- 隐私政策链接展示\n\n资料来源：[packages/cli/src/ui/auth/AuthDialog.tsx:30-70]()\n\n### 隐私通知机制\n\n系统提供多层次的隐私通知：\n\n| 通知类型 | 触发条件 | 数据处理 |\n|----------|----------|----------|\n| `GeminiPrivacyNotice` | Gemini API 使用 | 展示 API 服务条款 |\n| `CloudFreePrivacyNotice` | 免费版用户 | 数据收集选项控制 |\n\n隐私通知展示相关链接和条款：\n\n- Gemini API 概述：https://ai.google.dev/docs/gemini_api_overview\n- API 服务条款：https://developers.google.com/terms\n- Gemini API 附加条款：https://ai.google.dev/gemini-api/terms\n\n资料来源：[packages/cli/src/ui/privacy/GeminiPrivacyNotice.tsx:1-30]()\n\n## 技能系统\n\n### 技能目录结构\n\n每个技能（Skill）遵循标准目录结构：\n\n```\n/\n├── SKILL.md # 技能定义（必需）\n├── scripts/ # 可执行脚本\n├── references/ # 参考文档\n└── assets/ # 静态资源\n```\n\n**SKILL.md 结构：**\n\n- **Frontmatter（YAML）**：包含 `name` 和 `description` 字段\n- **Body（Markdown）**：使用说明和指导，仅在技能触发后加载\n\n资料来源：[packages/core/src/skills/builtin/skill-creator/SKILL.md:1-80]()\n\n### 扩展功能标识\n\n扩展详情页面（`ExtensionDetails`）通过功能标签标识扩展能力：\n\n| 标签 | 标识颜色 | 功能说明 |\n|------|----------|----------|\n| MCP | 主题色 | MCP 服务器集成 |\n| Context | 错误色 | Context 文件支持 |\n| Hooks | 警告色 | 生命周期钩子 |\n| Skills | 成功色 | 技能系统支持 |\n| Commands | 主题色 | 自定义命令 |\n\n资料来源：[packages/cli/src/ui/components/views/ExtensionDetails.tsx:40-80]()\n\n## 配置与信任系统\n\n### 文件夹信任对话框\n\n`FolderTrustDialog` 负责扫描工作目录的安全配置：\n\n```mermaid\ngraph TD\n A[加载配置] --> B{发现配置}\n B -->|有错误| C[显示错误列表]\n B -->|有警告| D[显示安全警告]\n B -->|正常| E[列出已发现配置]\n C --> F{用户确认}\n D --> F\n E --> F\n F -->|信任| G[加载配置]\n F -->|取消| H[跳过]\n```\n\n信任配置包括：\n- 自定义命令（`.gemini/commands/`）\n- 钩子脚本（`.gemini/hooks/`）\n- MCP 服务器配置\n- 智能体技能\n- 项目设置\n\n资料来源：[packages/cli/src/ui/components/FolderTrustDialog.tsx:1-60]()\n\n## 部署与发布架构\n\n### 发布渠道\n\n系统支持三种发布渠道以满足不同用户需求：\n\n| 渠道 | 标签 | 发布周期 | 适用场景 |\n|------|------|----------|----------|\n| 预览版 | `preview` | 每周二 UTC 23:59 | 测试新功能 |\n| 稳定版 | `latest` | 每周二 UTC 20:00 | 生产环境 |\n| 每日版 | `nightly` | 每日 UTC 00:00 | 紧跟主分支 |\n\n安装命令示例：\n\n```bash\n# 预览版\nnpm install -g @google/gemini-cli@preview\n\n# 稳定版\nnpm install -g @google/gemini-cli@latest\n\n# 每日版\nnpm install -g @google/gemini-cli@nightly\n```\n\n### 多平台安装支持\n\n| 平台 | 安装方式 |\n|------|----------|\n| 通用 | `npm install -g @google/gemini-cli` |\n| macOS/Linux | `brew install gemini-cli` |\n| macOS | `sudo port install gemini-cli` |\n| 受限环境 | Anaconda + Node.js 环境 |\n\n资料来源：[README.md:100-180]()\n\n## 关键技术栈\n\n| 层级 | 技术选型 | 用途 |\n|------|----------|------|\n| CLI 框架 | Commander.js / Yargs | 命令行参数解析 |\n| UI 渲染 | Ink (React for CLI) | 终端界面渲染 |\n| 状态管理 | React Hooks | 组件状态管理 |\n| 核心逻辑 | TypeScript | 类型安全开发 |\n| API 调用 | Gemini SDK | 与 Gemini API 通信 |\n| 数据存储 | JSONL | 对话记录持久化 |\n\n## 总结\n\nGemini CLI 采用清晰的分层架构设计，通过 CLI 层处理用户交互和终端渲染，Core 层提供核心业务能力，扩展层支持技能系统和第三方集成。系统重视安全性和用户隐私，提供完善的认证流程和配置信任机制，同时支持多种发布渠道以适应不同用户的使用需求。\n\n---\n\n\n\n## 包结构详解\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/a2a-server/src/index.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/a2a-server/src/index.ts)\n- [packages/cli/src/index.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/index.ts)\n- [packages/core/src/index.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/index.ts)\n- [packages/sdk/src/index.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/sdk/src/index.ts)\n \n\n# 包结构详解\n\n## 概述\n\nGemini CLI 是一个基于 monorepo 架构的 Google 开源项目，采用了 pnpm workspace 模式进行多包管理。项目源码位于 `packages/` 目录下，包含四个主要子包：`cli`、`core`、`sdk` 和 `a2a-server`。这种模块化设计将命令行界面、核心业务逻辑、软件开发工具包和协议服务分离，使得各模块可以独立演进和测试，同时保持整体系统的内聚性。\n\n从项目配置文件和源码结构来看，Gemini CLI 的包设计遵循了清晰的关注点分离原则。`cli` 包负责终端 UI 渲染和用户交互，`core` 包实现代理逻辑、工具注册和配置管理，`sdk` 包提供对外编程接口，而 `a2a-server` 包则处理 Agent-to-Agent 通信协议。这种分层架构使得开发者可以根据需求选择性地使用或扩展特定模块。\n\n## 包架构总览\n\nGemini CLI 的包结构可以划分为四个核心模块，每个模块承担不同的职责。\n\n| 包名称 | 主要职责 | 依赖关系 |\n|--------|----------|----------|\n| `cli` | 命令行界面、UI 组件、用户交互 | 依赖 core、sdk |\n| `core` | 代理逻辑、工具注册、配置管理、聊天录制 | 基础包，无 core 外依赖 |\n| `sdk` | 外部 SDK 接口封装 | 依赖 core |\n| `a2a-server` | Agent 间通信协议服务 | 独立运行 |\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ Gemini CLI Monorepo │\n├──────────────┬──────────────┬──────────────┬────────────┤\n│ cli │ core │ sdk │ a2a-server│\n├──────────────┼──────────────┼──────────────┼────────────┤\n│ UI 组件 │ Agent 逻辑 │ 外部接口 │ 协议服务 │\n│ 隐私通知 │ 工具系统 │ API 封装 │ MCP 集成 │\n│ 帮助系统 │ 配置管理 │ 开发者工具 │ 通信路由 │\n│ 状态显示 │ 聊天录制 │ │ │\n└──────────────┴──────────────┴──────────────┴────────────┘\n```\n\n## CLI 包详解\n\n`packages/cli` 是用户直接交互的前端包，负责所有终端界面的渲染和命令解析。该包的源码组织遵循功能模块化原则，将不同类型的 UI 组件放置在相应的目录结构中。\n\n### 目录结构\n\nCLI 包的主要目录包括 `ui/` 目录下的多个子模块：`components/` 存放通用 UI 组件，`privacy/` 处理隐私政策展示，`views/` 包含特定视图组件如状态页面和扩展详情页。这种组织方式使得代码易于导航和维护。\n\n### UI 组件体系\n\nCLI 包的 UI 组件采用了分层设计模式。从源码中可以看到几个关键的 UI 组件类型：\n\n**AboutBox 组件**负责显示应用元信息，包括 CLI 版本、Git 提交信息、模型版本、沙盒环境和操作系统信息。该组件从配置文件和构建时注入的环境变量中获取数据，并使用主题化的样式进行展示。\n\n```tsx\n// 显示应用信息的结构示例\ninterface AppInfo {\n cliVersion: string; // CLI 版本号\n gitCommit: string; // Git 提交哈希\n modelVersion: string; // 使用的模型版本\n sandboxEnv: string; // 沙盒环境类型\n os: string; // 操作系统\n}\n```\n\n**AppHeader 组件**是应用的主头部，负责渲染横幅、Logo 和用户身份信息。该组件支持两种布局模式：列布局（column）和行布局（row），根据终端宽度和 Logo 存在与否自动切换。当显示更新状态时，还会在头部右侧显示更新进度指示器。\n\n**GemmaStatus 组件**专门用于显示 Gemma 模型的运行状态，包括二进制文件路径、模型下载状态、服务器运行状态和设置启用状态。每个状态项都配有状态指示点，直观地反映各组件的运行情况。\n\n**Help 组件**提供交互式帮助信息，展示所有可用的斜杠命令及其描述。该组件支持命令隐藏、分类显示和子命令展开等高级功能，帮助用户快速了解 CLI 的使用方式。\n\n### 隐私通知系统\n\nGemini CLI 实现了多套隐私通知界面以适应不同的使用场景。**CloudFreePrivacyNotice 组件**用于免费版本，向用户清晰说明数据收集政策，并提供数据收集选项的开关控制。该组件使用单选按钮让用户在允许或禁止 Google 使用数据之间做出选择，并将用户偏好持久化到配置系统中。\n\n**GeminiPrivacyNotice 组件**则提供更详细的法律条款链接，包括 Gemini API 概述、Google AI Studio 使用条款、API 服务条款和 Gemini API 附加服务条款。这些链接帮助用户在法律层面了解使用 Gemini CLI 的权利和义务。\n\n### 扩展详情展示\n\n**ExtensionDetails 组件**负责渲染扩展市场的扩展卡片信息。该组件显示扩展名称、版本、GitHub 星标数、Google 拥有标识以及扩展支持的特性标签。支持的特性标签包括 MCP（模型上下文协议）、Context file（上下文文件）、Hooks（钩子）、Skills（技能）和 Custom Commands（自定义命令），每种特性用不同的颜色区分。\n\n## Core 包详解\n\n`packages/core` 是整个项目的基础层，包含了代理逻辑、工具系统、配置管理和聊天录制等核心功能。该包不依赖其他内部包，而是作为其他包的基础依赖。\n\n### 代理与工具系统\n\n**config.ts** 文件实现了核心的配置管理和工具注册系统。该系统支持灵活的工具有条件注册机制，开发者可以通过配置指定启用哪些工具。工具注册采用工厂模式，通过 `maybeRegister` 函数包装，在满足配置条件时才执行实际注册。\n\n```typescript\n// 工具注册的条件判断逻辑示例\nconst maybeRegister = (toolName: string, coreTools: string[] | undefined, \n normalizedClassName: string, registerFn: () => void) => {\n let isEnabled = false;\n if (coreTools) {\n isEnabled = coreTools.some(\n (tool) =>\n tool === toolName ||\n tool === normalizedClassName ||\n tool.startsWith(`${toolName}(`) ||\n tool.startsWith(`${normalizedClassName}(`)\n );\n }\n if (isEnabled) {\n registerFn();\n }\n};\n```\n\n配置系统还支持工具的回退机制。以 Ripgrep 为例，当配置启用 Ripgrep 但系统检测到不可用时，会自动回退到 GrepTool 并记录警告日志，同时触发 `RipgrepFallbackEvent` 事件供监控使用。\n\n### 聊天录制服务\n\n**chatRecordingService.ts** 实现了会话持久化和恢复功能。该服务负责将聊天记录以 JSONL 格式存储到文件系统，并在需要时加载和重建会话状态。服务返回的会话记录包含丰富的元数据：\n\n```typescript\ninterface ConversationRecord {\n sessionId: string; // 会话唯一标识\n projectHash: string; // 项目哈希值\n startTime: string; // 开始时间 ISO 格式\n lastUpdated: string; // 最后更新时间\n summary: string | undefined; // 会话摘要\n memoryScratchpad: string; // 记忆便签\n directories: string[]; // 关联目录列表\n kind: string; // 会话类型\n messages: Message[]; // 消息列表\n messageCount: number; // 消息总数\n userMessageCount: number; // 用户消息数\n firstUserMessage: string; // 首个用户消息\n hasUserOrAssistantMessage: boolean; // 是否有人机对话\n}\n```\n\n### 技能提取代理\n\n**skill-extraction-agent.ts** 实现了从对话历史中自动提取技能的功能。该代理使用统一的 diff 补丁格式来描述技能文件的创建和更新操作，补丁文件存储在 `~/.gemini/skills/.patch` 路径下。代理遵循严格的质量规则，包括合并重复技能、保持职责清晰、确保每个技能包含触发条件、执行步骤和验证方法。\n\n### 策略辅助系统\n\n**policyHelpers.test.ts** 揭示了模型路由策略的实现细节。系统支持单模型直接返回和模型链策略两种模式。当配置使用 \"auto\" 模型时，系统会返回默认的模型链 `[Pro, Flash]`，优先使用高级模型，在资源受限或性能要求时自动降级。这种设计使得 CLI 能够适应不同的使用场景和资源限制。\n\n## SDK 包详解\n\n`packages/sdk` 为开发者提供编程接口封装，使得第三方应用可以集成 Gemini CLI 的核心能力。该包的封装层次更高，屏蔽了内部实现细节，提供稳定对外的 API。\n\nSDK 包作为核心功能与外部消费者之间的桥梁，其设计目标是保持 API 稳定性，使得依赖该 SDK 的应用能够在 CLI 版本升级时保持兼容。\n\n## A2A Server 包详解\n\n`packages/a2a-server` 实现了 Agent-to-Agent 通信协议服务。该包独立运行，提供标准的通信接口，使得不同的 AI Agent 能够相互发现和交互。A2A 协议支持 MCP（Model Context Protocol）服务器的集成，允许 Gemini CLI 扩展其能力边界，包括 Imagen 图像生成、Veo 视频生成和 Lyria 音乐生成等高级功能。\n\n## 包间依赖关系\n\n各包之间的依赖关系经过精心设计，形成了清晰的层次结构：\n\n```mermaid\ngraph TD\n A[cli 包] --> B[core 包]\n A --> C[sdk 包]\n B --> C\n D[a2a-server 包] --> B\n D --> C\n E[外部依赖] --> B\n E --> C\n E --> A\n```\n\n核心依赖原则包括：CLI 包依赖 core 和 sdk 以复用核心逻辑；core 包作为基础层不依赖其他内部包；sdk 包依赖 core 提供编程接口；a2a-server 独立运行但可与 core 交互以获取代理能力。\n\n## 安装与发布\n\nGemini CLI 支持多种安装渠道，满足不同用户的需求：\n\n| 渠道 | 发布频率 | 稳定性 | 安装命令 |\n|------|----------|--------|----------|\n| Preview | 每周二 UTC 23:59 | 未经完全测试 | `npm install -g @google/gemini-cli@preview` |\n| Stable | 每周二 UTC 20:00 | 经过验证 | `npm install -g @google/gemini-cli@latest` |\n| Nightly | 每日 UTC 00:00 | 可能存在问题 | `npm install -g @google/gemini-cli@nightly` |\n\n除 npm 外，项目还支持 Homebrew、MacPorts 和 Anaconda 等安装方式，适应不同的操作系统和环境限制。这种多渠道发布策略使得用户可以根据对稳定性的要求选择合适的版本，同时也为测试新功能提供了便捷的途径。\n\n## 源码文件对应关系\n\n根据项目结构和源码分析，各主要功能模块与源码文件的对应关系如下：\n\n| 功能模块 | 主要源文件 | 所在包 |\n|----------|------------|--------|\n| 命令行入口 | `packages/cli/src/index.ts` | cli |\n| UI 组件库 | `packages/cli/src/ui/components/` | cli |\n| 隐私通知 | `packages/cli/src/ui/privacy/` | cli |\n| 配置管理 | `packages/core/src/config/config.ts` | core |\n| 工具注册 | `packages/core/src/config/config.ts` | core |\n| 聊天录制 | `packages/core/src/services/chatRecordingService.ts` | core |\n| 技能提取 | `packages/core/src/agents/skill-extraction-agent.ts` | core |\n| 策略路由 | `packages/core/src/availability/policyHelpers.test.ts` | core |\n| SDK 接口 | `packages/sdk/src/index.ts` | sdk |\n| A2A 服务 | `packages/a2a-server/src/index.ts` | a2a-server |\n\n## 开发指南\n\n基于包结构设计，开发者在添加新功能时应遵循以下原则：\n\n**包边界原则**：避免使用相对路径跨包导入，优先通过包名导入。这种设计确保了包的边界清晰，便于未来的包拆分和独立发布。\n\n**协议设计**：新增 RPC 方法应添加到 `acpRpcDispatcher.ts`，会话状态存储在 `acpSession.ts`，协议辅助函数添加到 `acpUtils.ts`。\n\n**代码规范**：所有新文件必须包含 Apache-2.0 许可证头，使用 Zod 模式验证不可信输入，避免使用 `any` 类型断言。测试文件应放置在源码同目录下，使用 `.test.ts` 扩展名。\n\n## 总结\n\nGemini CLI 的包结构设计体现了现代 monorepo 项目的最佳实践。通过将 CLI 界面、核心逻辑、SDK 接口和协议服务分离，项目实现了关注点清晰、职责明确、易于测试和扩展的目标。各包之间的依赖关系经过精心规划，形成了稳定的基础层（core）支撑上层应用（cli、sdk、a2a-server）的架构模式。\n\n---\n\n\n\n## 核心工具集\n\n### 相关页面\n\n相关主题：[代理系统与子代理](#page-agent-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/src/config/config.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/config/config.ts)\n- [packages/core/src/tools/shell.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/tools/shell.ts) *(项目引用)*\n- [packages/core/src/agents/skill-extraction-agent.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/skill-extraction-agent.ts)\n- [packages/cli/src/ui/components/messages/ToolConfirmationMessage.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/messages/ToolConfirmationMessage.tsx)\n- [packages/core/src/context/graph/toGraph.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/context/graph/toGraph.ts)\n- [packages/core/src/services/chatRecordingService.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/services/chatRecordingService.ts)\n \n\n# 核心工具集\n\n## 概述\n\nGemini CLI 的核心工具集是 CLI 与用户代码库进行交互的基础能力层。这些工具提供了文件读写、代码搜索、Shell 命令执行、网络搜索与内容获取等核心功能，使 AI Agent 能够理解、修改和分析用户的代码环境。\n\n工具注册采用动态机制，通过配置类 `CoreConfig` 的 `registerTools()` 方法根据用户配置选择性注册可用工具。工具实现遵循统一的注册接口，每个工具继承自基础工具类并与消息总线 (`MessageBus`) 集成以实现事件驱动的通信。\n\n## 工具注册架构\n\n### 动态注册机制\n\n工具注册通过 `maybeRegister` 辅助函数实现，该函数检查工具是否在 `coreTools` 配置列表中启用，只有启用状态下才会调用注册函数将工具实例添加到注册表：\n\n```typescript\nconst maybeRegister = (\n toolClass: ToolConstructor,\n registerFn: () => void\n) => {\n let isEnabled = false;\n \n if (!coreTools) {\n isEnabled = true;\n } else if (coreTools) {\n isEnabled = coreTools.some(\n (tool) =>\n tool === toolName ||\n tool === normalizedClassName ||\n tool.startsWith(`${toolName}(`) ||\n tool.startsWith(`${normalizedClassName}(`),\n );\n }\n \n if (isEnabled) {\n registerFn();\n }\n};\n```\n\n资料来源：[packages/core/src/config/config.ts:120-147]()\n\n### 工具注册流程图\n\n```mermaid\ngraph TD\n A[CoreConfig 初始化] --> B[调用 registerTools]\n B --> C{检查 coreTools 配置}\n C -->|未配置| D[默认启用所有工具]\n C -->|已配置| E{遍历 coreTools 列表}\n E -->|工具匹配| F[调用 maybeRegister]\n F --> G{工具已启用?}\n G -->|是| H[注册工具到 Registry]\n G -->|否| I[跳过注册]\n H --> J[工具可用]\n```\n\n## 核心工具类型\n\n### 文件操作工具\n\n| 工具名称 | 类名 | 功能描述 |\n|---------|------|---------|\n| 文件列表 | `LSTool` | 列出目录内容和文件结构 |\n| 文件读取 | `ReadFileTool` | 读取指定路径的文件内容 |\n| 文件写入 | `WriteFileTool` | 创建或更新文件内容 |\n\n#### 文件工具的 Patch 格式\n\n在技能提取和文件更新场景中，工具使用统一的 unified diff patch 格式：\n\n```diff\n--- /absolute/path/to/original/SKILL.md\n+++ /absolute/path/to/original/SKILL.md\n@@ -, +, @@\n \n -\n +\n \n```\n\nPatch 规则要点：\n- 使用绝对路径，禁止 `a/` 或 `b/` 前缀\n- 每个 hunk 需要包含 3 行上下文\n- `@@` 头部行数必须准确\n- 新文件使用 `/dev/null` 作为源路径\n\n资料来源：[packages/core/src/agents/skill-extraction-agent.ts]()\n\n### 搜索工具\n\n| 工具名称 | 类名 | 优先级 | 回退方案 |\n|---------|------|--------|---------|\n| 高级搜索 | `RipGrepTool` | 高 | 依赖系统 ripgrep |\n| 基础搜索 | `GrepTool` | 低 | 默认 GrepTool |\n\n#### Ripgrep 回退机制\n\n当检测到 `useRipgrep` 配置启用时，系统会尝试注册 `RipGrepTool`。若系统不具备 ripgrep 能力，则自动回退到 `GrepTool`：\n\n```typescript\nif (this.getUseRipgrep()) {\n let useRipgrep = false;\n try {\n useRipgrep = await canUseRipgrep();\n } catch (error: unknown) {\n errorString = String(error);\n }\n if (useRipgrep) {\n maybeRegister(RipGrepTool, () =>\n registry.registerTool(new RipGrepTool(this, this.messageBus)),\n );\n } else {\n debugLogger.warn(`Ripgrep is not available. Falling back to GrepTool.`);\n maybeRegister(GrepTool, () =>\n registry.registerTool(new GrepTool(this, this.messageBus)),\n );\n }\n}\n```\n\n资料来源：[packages/core/src/config/config.ts:130-146]()\n\n### Shell 执行工具\n\nShell 工具允许 AI Agent 执行系统命令。执行前需要用户确认权限，权限范围包括：\n\n| 权限类型 | 说明 |\n|---------|------|\n| 网络访问 | 允许访问所有 URL |\n| 写权限 | 允许写入的路径列表 |\n| 读权限 | 允许读取的路径列表 |\n\n工具确认消息格式示例：\n\n```tsx\n\n • Network: All Urls\n\n\n • Write: /path/to/project\n\n\n • Read: /path/to/project\n\n```\n\n资料来源：[packages/cli/src/ui/components/messages/ToolConfirmationMessage.tsx]()\n\n### 网络工具\n\n| 工具名称 | 功能 |\n|---------|------|\n| `WebSearch` | 执行 Google 搜索，获取实时信息 |\n| `WebFetch` | 获取指定 URL 的网页内容 |\n\n## 工具确认与权限管理\n\n### 权限确认流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Tool as 工具调用\n participant UI as 确认界面\n participant Core as 核心引擎\n \n Tool->>Core: 请求执行命令\n Core->>UI: 显示 ToolConfirmationMessage\n User->>UI: 批准/拒绝\n alt 批准\n UI->>Core: 确认执行\n Core->>Tool: 放行执行\n Tool->>User: 返回结果\n else 拒绝\n UI->>Core: 拒绝执行\n Core->>Tool: 终止操作\n end\n```\n\n### 自动编辑模式\n\n当配置 `ApprovalMode` 设置为 `YOLO` 或 `AUTO_EDIT` 时，系统会自动批准工具执行，无需用户手动确认：\n\n```typescript\nconst isAutoEdit =\n config.getApprovalMode() === ApprovalMode.YOLO ||\n config.getApprovalMode() === ApprovalMode.AUTO_EDIT;\n```\n\n资料来源：[packages/cli/src/ui/components/messages/ToolConfirmationMessage.tsx]()\n\n## 工具与消息总线\n\n工具通过 `MessageBus` 实现事件驱动的通信架构。每个工具实例在注册时接收消息总线引用，支持以下事件类型：\n\n- `ToolStarted` - 工具开始执行\n- `ToolCompleted` - 工具执行完成\n- `ToolError` - 工具执行错误\n- `ToolConfirmationRequired` - 需要用户确认\n\n工具实例接收消息总线的方式：\n\n```typescript\nregistry.registerTool(new ReadFileTool(this, this.messageBus));\nregistry.registerTool(new LSTool(this, this.messageBus));\n```\n\n资料来源：[packages/core/src/config/config.ts:139-146]()\n\n## 对话上下文中的工具调用\n\n### Turn ID 生成机制\n\n每次工具调用都会生成稳定的唯一标识符，用于追踪对话历史：\n\n```typescript\nconst turnContent = JSON.stringify(msg.parts);\nconst h = createHash('md5')\n .update(`${msg.role}:${turnContent}`)\n .digest('hex');\nconst occurrence = (seenHashes.get(h) || 0) + 1;\nseenHashes.set(h, occurrence);\nconst turnSalt = `${h}_${occurrence}`;\nconst turnId = getStableId(msg, this.nodeIdentityMap, turnSalt, -1);\n```\n\n资料来源：[packages/core/src/context/graph/toGraph.ts]()\n\n### 函数调用标识\n\n函数调用和函数响应在对话图中使用不同前缀的标识符：\n\n| 调用类型 | 标识符格式 |\n|---------|-----------|\n| 函数调用 | `call_${functionCall.id}_${turnSalt}_${partIdx}` |\n| 函数响应 | `resp_${functionResponse.id}_${turnSalt}_${partIdx}` |\n\n## 会话记录与工具调用追溯\n\n`ChatRecordingService` 负责记录工具调用历史，保存到 JSONL 文件格式：\n\n```typescript\nexport interface ConversationRecord {\n sessionId: string;\n projectHash: string;\n startTime: string;\n lastUpdated: string;\n summary?: string;\n memoryScratchpad?: string;\n directories?: string[];\n kind: string;\n messages: Message[];\n messageCount: number;\n userMessageCount: number;\n firstUserMessage?: string;\n hasUserOrAssistantMessage: boolean;\n}\n```\n\n资料来源：[packages/core/src/services/chatRecordingService.ts]()\n\n## 配置参考\n\n### coreTools 配置选项\n\n```typescript\ninterface CoreToolsConfig {\n coreTools?: Array<\n | 'read_file'\n | 'read_file(...)'\n | 'write_file'\n | 'write_file(...)'\n | 'ls'\n | 'ls(...)'\n | 'grep'\n | 'grep(...)'\n | 'ripgrep'\n | 'ripgrep(...)'\n | 'web_search'\n | 'web_search(...)'\n | 'web_fetch'\n | 'web_fetch(...)'\n >;\n useRipgrep?: boolean;\n}\n```\n\n### ApprovalMode 配置\n\n| 模式 | 行为 |\n|------|------|\n| `MANUAL` | 所有操作需要用户手动确认 |\n| `AUTO_EDIT` | 编辑操作自动批准 |\n| `YOLO` | 所有操作自动批准 |\n| `DISABLED` | 禁用确认机制 |\n\n## 扩展与 MCP 集成\n\n核心工具集支持通过 MCP (Model Context Protocol) 服务器进行扩展。MCP 提示命令在帮助界面中带有 `[MCP]` 标签标识：\n\n```tsx\n{command.kind === CommandKind.MCP_PROMPT && (\n [MCP]\n)}\n```\n\n扩展工具可添加的能力标签：\n\n| 标签 | 含义 |\n|------|------|\n| `MCP` | MCP 服务器集成 |\n| `Context file` | 支持上下文文件 |\n| `Hooks` | 支持生命周期钩子 |\n| `Skills` | 支持技能系统 |\n| `Commands` | 支持自定义命令 |\n\n资料来源：[packages/cli/src/ui/components/Help.tsx]()\n\n---\n\n\n\n## 代理系统与子代理\n\n### 相关页面\n\n相关主题：[核心工具集](#page-tools), [上下文管理与压缩](#page-context-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/src/agent/agent-session.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agent/agent-session.ts)\n- [packages/core/src/agents/registry.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/registry.ts)\n- [packages/core/src/agents/agent-scheduler.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/agent-scheduler.ts)\n- [packages/core/src/agents/generalist-agent.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/generalist-agent.ts)\n- [packages/core/src/agents/a2a-client-manager.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/a2a-client-manager.ts)\n- [packages/core/src/agents/skill-extraction-agent.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/skill-extraction-agent.ts)\n- [packages/core/src/config/config.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/config/config.ts)\n- [packages/core/src/prompts/snippets.legacy.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/prompts/snippets.legacy.ts)\n- [packages/core/src/availability/policyHelpers.test.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/availability/policyHelpers.test.ts)\n- [packages/sdk/src/tool.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/sdk/src/tool.ts)\n \n\n# 代理系统与子代理\n\n## 概述\n\nGemini CLI 的代理系统（Agent System）是整个命令-line 工具的核心架构，负责协调用户交互、任务执行和工具调用。该系统采用模块化设计，支持多种类型的代理（Agent），包括通用代理（Generalist Agent）和专业技能提取代理（Skill Extraction Agent）。代理系统通过注册机制（Registry）和调度器（Scheduler）统一管理所有代理的生命周期，实现灵活的扩展性和高度的可维护性。\n\n## 系统架构\n\n### 核心组件关系\n\n```mermaid\ngraph TD\n User[用户交互] --> CLI[CLI 界面层]\n CLI --> Session[AgentSession]\n Session --> Registry[AgentRegistry]\n Registry --> Scheduler[AgentScheduler]\n Scheduler --> GeneralistAgent[通用代理]\n Scheduler --> SkillExtractionAgent[技能提取代理]\n GeneralistAgent --> Tools[工具集]\n SkillExtractionAgent --> SkillManager[技能管理器]\n Tools --> FileSystem[文件系统工具]\n Tools --> Shell[Shell 执行工具]\n Tools --> Grep[RipGrep/Grep 工具]\n Tools --> MCP[MCP 服务器工具]\n```\n\n### 代理类型体系\n\n| 代理类型 | 文件位置 | 职责描述 |\n|---------|---------|---------|\n| GeneralistAgent | `packages/core/src/agents/generalist-agent.ts` | 通用任务处理，支持代码理解、生成、调试 |\n| SkillExtractionAgent | `packages/core/src/agents/skill-extraction-agent.ts` | 从会话历史中提取可复用的技能模式 |\n| 未来扩展代理 | `packages/core/src/agents/` 目录 | 通过注册机制动态加载 |\n\n## 代理注册机制\n\n### 注册表（AgentRegistry）\n\n代理系统通过 `AgentRegistry` 实现代理的注册和管理。该注册表维护了一个代理实例的映射表，支持按类型动态查询和实例化。\n\n```mermaid\nclassDiagram\n class AgentRegistry {\n -Map~string, Agent~ agents\n +registerAgent(agent: Agent): void\n +getAgent(type: string): Agent\n +listAgents(): Agent[]\n }\n```\n\n注册表的核心方法包括：\n\n- **registerAgent()** - 将新代理实例注册到系统中\n- **getAgent()** - 根据代理类型获取对应实例\n- **listAgents()** - 列出所有已注册的代理\n\n### 调度器（AgentScheduler）\n\n`AgentScheduler` 负责协调多个代理之间的工作分配和执行顺序。它维护一个任务队列，并根据代理的能力和当前系统状态将任务路由到合适的代理。\n\n## 通用代理（Generalist Agent）\n\n### 核心职责\n\n通用代理是 Gemini CLI 的主要工作代理，负责处理用户的各种自然语言请求。其主要功能包括：\n\n| 功能类别 | 具体能力 |\n|---------|---------|\n| 代码理解 | 分析代码库结构、理解模块依赖、解释算法逻辑 |\n| 代码生成 | 根据描述生成新代码、模板、配置文件 |\n| 调试排错 | 定位问题、分析错误原因、提供修复建议 |\n| 任务自动化 | 执行命令行操作、处理 Git 工作流、查询 Pull Request |\n\n### 工具集成\n\n通用代理通过 `Tool` 接口与各种工具进行交互。核心工具包括：\n\n| 工具名称 | 实现文件 | 功能描述 |\n|---------|---------|---------|\n| LSTool | `config.ts` | 列出目录内容和文件结构 |\n| ReadFileTool | `config.ts` | 读取文件内容 |\n| RipGrepTool | `config.ts` | 使用 Ripgrep 进行正则搜索（优先） |\n| GrepTool | `config.ts` | 使用标准 Grep 进行搜索（回退方案） |\n| UpdateTopicTool | `config.ts` | 更新会话主题 |\n\n工具注册采用条件注册模式，根据系统环境自动选择最优实现：\n\n```typescript\n// 资料来源：packages/core/src/config/config.ts\nif (this.getUseRipgrep()) {\n let useRipgrep = false;\n try {\n useRipgrep = await canUseRipgrep();\n } catch (error: unknown) {\n errorString = String(error);\n }\n if (useRipgrep) {\n maybeRegister(RipGrepTool, () =>\n registry.registerTool(new RipGrepTool(this, this.messageBus)),\n );\n } else {\n debugLogger.warn(`Ripgrep is not available. Falling back to GrepTool.`);\n maybeRegister(GrepTool, () =>\n registry.registerTool(new GrepTool(this, this.messageBus)),\n );\n }\n}\n```\n\n## 技能提取代理（Skill Extraction Agent）\n\n### 概述\n\n技能提取代理（Skill Extraction Agent）是一个专门的子代理，负责从用户与通用代理的会话历史中自动识别和提取可复用的技能模式。这些提取的技能可以被保存为 `SKILL.md` 文件，供将来类似任务使用。\n\n### 工作流程\n\n```mermaid\ngraph TD\n Start[会话进行中] --> Analyze{分析会话历史}\n Analyze --> |发现模式| CreateSkill[创建技能]\n CreateSkill --> GeneratePatch[生成 Patch 文件]\n GeneratePatch --> ValidatePatch[验证 Patch 有效性]\n ValidatePatch --> |通过| SaveSkill[保存技能到 .inbox]\n ValidatePatch --> |失败| Discard[静默丢弃]\n Analyze --> |无明显模式| NoOp[不创建技能]\n SaveSkill --> End[技能可用]\n NoOp --> End\n```\n\n### 技能文件结构\n\n技能代理创建的技能文件遵循标准化结构：\n\n| 文件类型 | 用途 | 加载时机 |\n|---------|-----|---------|\n| `FORMS.md` | 表单定义和交互规范 | 特定命令需要时 |\n| `REFERENCE.md` | API 参考和详细文档 | 引用时按需加载 |\n| `EXAMPLES.md` | 代码示例和使用模式 | 示例请求时 |\n| `SKILL.md` | 主入口，包含元数据和导航 | 始终加载 |\n\n### Patch 文件格式\n\n技能代理使用标准化的统一 diff 格式（Unified Diff）来描述文件变更：\n\n```diff\n--- /absolute/path/to/original/SKILL.md\n+++ /absolute/path/to/original/SKILL.md\n@@ -, +, @@\n \n-\n+\n \n```\n\n**关键规则**：\n\n- 必须使用绝对路径，禁止使用 `a/` 或 `b/` 前缀\n- 每个变更块需要包含 3 行上下文\n- `@@` 头部的行数必须精确匹配\n- Patch 文件名必须为 `extraction.patch`\n- 路径必须在允许的根目录下\n\n### 质量规则\n\n技能提取代理实施严格的质量控制：\n\n| 规则 | 描述 |\n|-----|------|\n| 去重合并 | 优先合并相似技能而非创建新技能 |\n| 职责明确 | 避免创建\"万能\"技能，保持职责单一 |\n| 必需元素 | 每个技能必须包含：触发条件、处理流程、注意事项、验证步骤 |\n| 证据驱动 | 必须有来自会话历史的明确证据支持技能创建 |\n| 空操作正常 | 创建 0 个技能是正常结果，不应强制创建 |\n\n## 代理会话（AgentSession）\n\n### 会话管理\n\n`AgentSession` 是用户与代理系统交互的主要入口点，负责维护对话状态和消息历史。\n\n```mermaid\ngraph LR\n User[用户消息] --> Session[AgentSession]\n Session --> Record[ChatRecordingService]\n Record --> Storage[JSONL 文件]\n Session --> Graph[ContextGraphBuilder]\n Graph --> Context[上下文图]\n Context --> Model[AI 模型]\n Model --> Response[代理响应]\n```\n\n### 会话记录服务\n\n`ChatRecordingService` 负责持久化会话数据，支持以下功能：\n\n| 功能 | 描述 |\n|-----|------|\n| 消息存储 | 将用户和代理消息保存到 JSONL 文件 |\n| 元数据管理 | 维护 sessionId、projectHash、startTime 等元信息 |\n| 条件加载 | 支持仅加载元数据或完整消息 |\n| 增量更新 | 追踪最后更新时间，支持断点续传 |\n\n会话元数据结构：\n\n```typescript\ninterface ConversationMetadata {\n sessionId: string;\n projectHash: string;\n startTime: string;\n lastUpdated: string;\n summary?: string;\n memoryScratchpad?: string;\n directories?: string[];\n kind?: string;\n messageCount: number;\n userMessageCount: number;\n firstUserMessage?: string;\n hasUserOrAssistantMessage: boolean;\n}\n```\n\n## A2A 客户端管理器\n\n### Agent-to-Agent 通信\n\n`a2a-client-manager.ts` 实现了代理之间的通信协议，支持多代理协作场景。\n\n### 核心功能\n\nA2A 客户端管理器处理以下类型的通信：\n\n- **任务委托** - 将复杂任务分解并委托给专业代理\n- **结果聚合** - 收集多个子代理的执行结果\n- **状态同步** - 保持代理间的状态一致性\n\n## 策略与配置\n\n### 模型策略链\n\n代理系统使用策略链（Policy Chain）来选择合适的 AI 模型：\n\n```typescript\n// 资料来源：packages/core/src/availability/policyHelpers.test.ts\ndescribe('policyHelpers', () => {\n describe('resolvePolicyChain', () => {\n it('returns a single-model chain for a custom model', () => {\n const config = createMockConfig({\n getModel: () => 'custom-model',\n });\n const chain = resolvePolicyChain(config);\n expect(chain).toHaveLength(1);\n expect(chain[0]?.model).toBe('custom-model');\n });\n\n it('returns the default chain when active model is \"auto\"', () => {\n const config = createMockConfig({\n getModel: () => DEFAULT_GEMINI_MODEL_AUTO,\n });\n const chain = resolvePolicyChain(config);\n // Expect default chain [Pro, Flash]\n expect(chain).toHaveLength(2);\n });\n });\n});\n```\n\n### 策略链规则\n\n| 模型设置 | 策略行为 |\n|---------|---------|\n| 自定义模型 | 返回单模型链，直接使用指定模型 |\n| 自动模式 (`auto`) | 返回默认链 [Pro, Flash]，自动降级 |\n| Pro 不可用 | 自动切换到 Flash |\n\n### 工具配置\n\n工具注册支持细粒度控制：\n\n| 配置项 | 描述 |\n|-------|------|\n| `coreTools` | 显式启用/禁用核心工具列表 |\n| 模式匹配 | 支持 `toolName`、`ClassName`、`toolName(params)` 三种匹配方式 |\n| Ripgrep 回退 | 自动检测 Ripgrep 可用性，无则回退到 GrepTool |\n\n## 规划模式（Plan Mode）\n\n### 工作流程\n\n当启用规划模式时，系统使用专门的提示模板来引导代理进行结构化规划：\n\n```typescript\n// 资料来源：packages/core/src/prompts/snippets.legacy.ts\nexport function renderPlanningWorkflow(\n options?: PlanningWorkflowOptions,\n): string {\n if (!options) return '';\n return `\n# Active Approval Mode: Plan\n\nYou are operating in **Plan Mode** - a structured planning workflow for designing implementation strategies before execution.\n\n## Available Tools\nThe following read-only tools are available in Plan Mode:\n${options.planModeToolsList}\n- \\`${WRITE_FILE_TOOL_NAME}\\` - Save plans to the plans directory\n- \\`${EDIT_TOOL_NAME}\\` - Update plans in the plans directory\n...\n`;\n}\n```\n\n### 规划模式特点\n\n| 特性 | 描述 |\n|-----|------|\n| 只读工具 | 仅允许使用查看类工具 |\n| 计划存储 | 允许写入计划文件到 plans 目录 |\n| 审批流程 | 计划需用户审批后才能执行 |\n\n## SDK 工具集成\n\n### 工具定义与执行\n\n通过 SDK，第三方可以扩展代理系统的工具集：\n\n```typescript\n// 资料来源：packages/sdk/src/tool.ts\nbindContext(context: SessionContext): SdkTool {\n return new SdkTool(this.definition, this.messageBus, undefined, context);\n}\n\ncreateInvocationWithContext(\n params: z.infer,\n messageBus: MessageBus,\n context: SessionContext | undefined,\n toolName?: string,\n): ToolInvocation, ToolResult> {\n return new SdkToolInvocation(\n params,\n messageBus,\n this.definition.action,\n context || this.context,\n toolName || this.name,\n this.definition.sendErrorsToModel,\n );\n}\n```\n\n### 工具创建示例\n\nSDK 提供了简化工具创建的辅助函数：\n\n```typescript\nimport { z, tool } from '@google/gemini-cli-sdk';\n\nconst myTool = tool({\n name: 'myTool',\n description: 'A custom tool for specific tasks',\n inputSchema: z.object({\n param1: z.string(),\n param2: z.number().optional(),\n }),\n async action(params) {\n // Tool implementation\n return { result: 'success' };\n },\n});\n```\n\n## 总结\n\nGemini CLI 的代理系统采用分层架构设计，通过注册机制实现了高度的可扩展性。通用代理负责处理日常任务，技能提取代理则通过智能分析会话历史自动构建知识库，两者协同工作为用户提供智能化的命令行辅助体验。系统支持通过 SDK 扩展工具集，并通过策略链机制灵活选择 AI 模型，确保在不同场景下都能提供最优的性能和结果质量。\n\n---\n\n\n\n## 上下文管理与压缩\n\n### 相关页面\n\n相关主题：[代理系统与子代理](#page-agent-system), [核心工具集](#page-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/src/context/graph/toGraph.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/context/graph/toGraph.ts)\n- [packages/core/src/services/chatRecordingService.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/services/chatRecordingService.ts)\n- [packages/core/src/context/graph/render.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/context/processors/rollingSummaryProcessor.ts)\n- [packages/core/src/agents/cli-help-agent.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/cli-help-agent.ts)\n \n\n# 上下文管理与压缩\n\n## 概述\n\n在 Gemini CLI 中，上下文管理是确保大型对话会话能够持续运行而不会超出模型令牌限制的核心机制。系统通过多种策略组合，包括对话历史压缩、消息去重、上下文图构建和滚动摘要，来高效管理对话状态。\n\n## 核心组件架构\n\n### 上下文管理系统\n\n上下文管理由多个协同工作的组件构成：\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| ContextGraphBuilder | `packages/core/src/context/graph/toGraph.ts` | 构建对话消息图，处理历史消息转换 |\n| ChatRecordingService | `packages/core/src/services/chatRecordingService.ts` | 会话持久化和元数据管理 |\n| ChatCompressionService | `packages/core/src/context/chatCompressionService.ts` | 对话内容压缩和摘要生成 |\n| RollingSummaryProcessor | `packages/core/src/context/processors/rollingSummaryProcessor.ts` | 滚动式摘要处理 |\n\n## 对话历史处理流程\n\n### 消息图构建机制\n\n系统通过 `ContextGraphBuilder` 将原始对话历史转换为优化的图结构：\n\n```mermaid\ngraph TD\n A[原始消息历史] --> B[Legacy环境头检查]\n B --> C{是否为遗留格式?}\n C -->|是| D[跳过该消息轮次]\n C -->|否| E[遍历消息部件]\n E --> F[生成消息哈希]\n F --> G[计算出现次数]\n G --> H[生成稳定TurnID]\n H --> I[用户消息处理]\n H --> J[函数调用/响应处理]\n I --> K[构建上下文图]\n J --> K\n```\n\n### 消息标识生成策略\n\n每个对话轮次都会生成稳定的唯一标识符，确保会话恢复和状态追踪的可靠性：\n\n1. **内容哈希**：使用 MD5 哈希基于 `角色:内容` 组合生成唯一指纹\n2. **出现计数**：同一条消息可能出现多次，系统通过计数区分\n3. **盐值生成：`turnSalt` = `${哈希}_${出现次数}` 格式\n4. **稳定ID：通过 `getStableId` 函数结合节点标识映射生成最终ID\n\n资料来源：[packages/core/src/context/graph/toGraph.ts:1-50]()\n\n### 遗留环境头处理\n\n系统包含对旧版环境头的兼容性处理：\n\n```typescript\n// 防御性检查：跳过遗留环境头，无论其出现在对话中的哪个位置\nif (msg.role === 'user' && msg.parts.length === 1) {\n const text = msg.parts[0].text;\n if (\n text?.startsWith('') &&\n text?.includes('This is the Gemini CLI')\n ) {\n debugLogger.log(\n '[ContextGraphBuilder] Skipping legacy environment header turn from graph.',\n );\n continue;\n }\n}\n```\n\n这种设计确保了系统演进过程中的向后兼容性，同时维护上下文图的干净结构。\n\n## 会话持久化与服务\n\n### ChatRecordingService 的角色\n\n`ChatRecordingService` 负责会话的持久化存储和元数据管理：\n\n| 功能 | 描述 |\n|------|------|\n| 会话ID管理 | 为每个对话会话分配唯一标识符 |\n| 项目哈希 | 基于项目目录生成唯一项目标识 |\n| 时间戳追踪 | 记录会话开始时间、最后更新时间 |\n| 摘要管理 | 支持会话摘要的存储和检索 |\n| 消息统计 | 追踪用户消息数、总消息数 |\n\n### 对话记录数据结构\n\n```typescript\ninterface ConversationRecord {\n sessionId: string; // 会话唯一标识\n projectHash: string; // 项目标识哈希\n startTime: string; // ISO格式开始时间\n lastUpdated: string; // 最后更新时间\n summary?: string; // 会话摘要\n memoryScratchpad?: string; // 记忆便签\n directories: string[]; // 相关目录\n kind: string; // 会话类型\n messages: Message[]; // 实际消息内容\n messageCount: number; // 总消息数\n userMessageCount: number; // 用户消息数\n firstUserMessage?: string; // 首条用户消息\n hasUserOrAssistantMessage: boolean; // 是否有用户/助手消息\n}\n```\n\n### 元数据模式\n\n系统支持两种加载模式以优化性能：\n\n1. **完整模式 (`metadataOnly: false`)**：加载所有消息内容和元数据\n2. **仅元数据模式 (`metadataOnly: true`)**：仅加载元数据，用于快速列表展示\n\n```typescript\nreturn {\n messages: options?.metadataOnly ? [] : loadedMessages,\n messageCount: options?.metadataOnly\n ? metadataMessages.length || messageIds.length\n : loadedMessages.length,\n};\n```\n\n资料来源：[packages/core/src/services/chatRecordingService.ts:1-100]()\n\n## 上下文压缩策略\n\n### 压缩服务架构\n\n虽然完整的压缩服务源码未在当前上下文中，但根据系统设计模式，上下文压缩通常包括：\n\n| 压缩策略 | 应用场景 |\n|----------|----------|\n| 滚动摘要 | 长对话的历史消息压缩 |\n| 选择性保留 | 保留关键系统消息和最后N条消息 |\n| 消息合并 | 合并连续的同类消息 |\n| 元数据裁剪 | 移除冗余的元数据字段 |\n\n### 摘要处理器\n\n`RollingSummaryProcessor` 实现滚动式摘要生成，周期性地将早期对话内容压缩为摘要，同时保留会话的关键上下文。\n\n## CLI Help Agent 与上下文\n\nCLI Help Agent 是上下文管理的一个典型应用场景，它利用上下文信息提供准确的帮助响应：\n\n```\n### Runtime Context\n- **CLI Version:** ${cliVersion}\n- **Active Model:** ${activeModel}\n- **Today's Date:** ${today}\n```\n\n代理通过内部文档工具 `get_internal_docs` 获取最新文档，并结合运行时上下文给出精确答案。这种设计确保了帮助信息的准确性和时效性。\n\n资料来源：[packages/core/src/agents/cli-help-agent.ts:1-30]()\n\n## 关键设计模式\n\n### 1. 延迟加载模式\n\n通过 `metadataOnly` 选项，系统可以仅在需要时加载完整消息内容，显著降低内存占用。\n\n### 2. 稳定标识符系统\n\n使用哈希+计数的组合方式确保即使相同内容的消息也能获得唯一标识：\n\n```typescript\nconst turnContent = JSON.stringify(msg.parts);\nconst h = createHash('md5')\n .update(`${msg.role}:${turnContent}`)\n .digest('hex');\nconst occurrence = (seenHashes.get(h) || 0) + 1;\nseenHashes.set(h, occurrence);\nconst turnSalt = `${h}_${occurrence}`;\n```\n\n### 3. 向后兼容性\n\n通过显式检测和跳过遗留格式，系统可以在不破坏现有会话的情况下演进。\n\n## 配置与使用\n\n### 上下文相关配置\n\n| 配置项 | 位置 | 说明 |\n|--------|------|------|\n| `showUserIdentity` | UI设置 | 控制用户身份信息显示 |\n| 会话存储路径 | 用户目录 | `~/.gemini/` 下的会话文件 |\n\n### 上下文持久化\n\n会话检查点保存在用户目录：\n\n```\n~/.gemini/\n├── policies/\n│ └── auto-saved.toml # 自动保存的策略配置\n└── [会话数据文件] # JSONL格式的会话记录\n```\n\n## 错误处理与调试\n\n系统包含完善的调试日志机制：\n\n```typescript\ndebugLogger.log('[ContextGraphBuilder] Skipping legacy environment header turn from graph.');\ndebugLogger.error('Error loading conversation record from JSONL:', error);\n```\n\n开发者可以通过设置适当的日志级别来监控上下文管理行为。\n\n## 总结\n\nGemini CLI 的上下文管理与压缩系统通过以下核心机制确保高效运行：\n\n1. **图结构存储**：将对话历史转换为优化的图数据结构\n2. **稳定标识**：基于内容哈希的稳定ID生成确保会话一致性\n3. **分层加载**：支持元数据和完整内容的两级加载模式\n4. **滚动压缩**：周期性摘要生成防止上下文无限增长\n5. **向后兼容**：优雅处理历史格式和演进中的数据结构\n\n---\n\n\n\n## CLI用户界面\n\n### 相关页面\n\n相关主题：[命令系统](#page-commands), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/cli/src/ui/App.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/App.tsx)\n- [packages/cli/src/ui/components/Composer.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/Composer.tsx)\n- [packages/cli/src/ui/components/MainContent.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/MainContent.tsx)\n- [packages/cli/src/ui/components/ToolConfirmationQueue.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/ToolConfirmationQueue.tsx)\n- [packages/cli/src/ui/themes/theme-manager.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/themes/theme-manager.ts)\n \n\n# CLI用户界面\n\n## 概述\n\nGemini CLI 的用户界面（UI）是基于终端的交互式命令行工具界面，采用 React 风格组件化架构构建在 Node.js 运行时之上。界面设计遵循终端友好原则，使用 `ink`（React for CLI）框架实现完整的交互式用户体验，支持富文本渲染、颜色主题、键盘快捷键和多区域布局管理。\n\nUI 系统的核心职责包括：\n\n- 提供消息对话区域，展示用户输入、模型响应和工具调用结果\n- 实现 Composer（输入组合器）处理用户命令和自然语言输入\n- 管理工具确认流程，包括文件读写、网络访问等权限审批\n- 应用主题和配色方案，保持视觉一致性\n- 处理键盘快捷键和导航交互\n\n资料来源：[packages/cli/src/ui/App.tsx:1-50]()\n\n## 架构设计\n\n### 整体架构\n\nCLI UI 采用分层架构，从上至下分为四个主要层次：\n\n```mermaid\ngraph TD\n A[App 根组件] --> B[AppHeader 头部区域]\n A --> C[MainContent 主内容区域]\n A --> D[Composer 输入组合器]\n A --> E[工具确认队列]\n \n B --> B1[Logo 显示]\n B --> B2[版本信息]\n B --> B3[用户身份]\n B --> B4[横幅通知]\n \n C --> C1[消息列表]\n C --> C2[工具执行结果]\n C --> C3[对话框层]\n \n D --> D1[多行输入框]\n D --> D2[快捷方式按钮]\n D --> D3[发送按钮]\n```\n\n### 组件层次结构\n\n```\nApp\n├── AppHeader\n│ ├── Logo/版本信息\n│ ├── UserIdentity\n│ └── Banner\n├── MainContent\n│ ├── Messages\n│ │ ├── UserMessage\n│ │ ├── ModelMessage\n│ │ └── ToolResultMessage\n│ ├── Dialogs\n│ │ ├── InboxDialog\n│ │ ├── FolderTrustDialog\n│ │ └── ExtensionRegistryView\n│ └── Views\n│ ├── GemmaStatus\n│ └── ExtensionDetails\n├── ToolConfirmationQueue\n└── Composer\n ├── InputArea\n └── ActionButtons\n```\n\n资料来源：[packages/cli/src/ui/App.tsx:50-150]()\n\n## 核心组件详解\n\n### App 根组件\n\n`App` 是整个 CLI 界面的根组件，负责协调所有子组件的状态和布局。它维护以下关键状态：\n\n| 状态字段 | 类型 | 说明 |\n|---------|------|------|\n| `showHeader` | boolean | 控制头部区域显示 |\n| `showComposer` | boolean | 控制输入区域显示 |\n| `toolConfirmations` | array | 待确认的工具调用队列 |\n| `activeDialog` | DialogType | 当前激活的对话框类型 |\n\n根组件通过 React Context 向下传递配置和主题信息，确保所有子组件能够访问统一的应用状态。\n\n资料来源：[packages/cli/src/ui/App.tsx:100-200]()\n\n### MainContent 主内容区域\n\n`MainContent` 组件是消息显示和对话框渲染的核心容器。它根据当前状态渲染三种不同的内容模式：\n\n1. **消息模式**：展示对话历史和工具执行结果\n2. **对话框模式**：叠加显示各类交互对话框\n3. **混合模式**：消息列表配合悬浮对话框\n\n组件支持平滑的内容切换动画，通过 `useLayoutEffect` 优化重渲染性能。\n\n资料来源：[packages/cli/src/ui/components/MainContent.tsx:1-80]()\n\n### Composer 输入组合器\n\n`Composer` 是用户输入的核心交互组件，提供类终端的输入体验：\n\n| 功能 | 快捷键 | 说明 |\n|------|--------|------|\n| 发送消息 | Enter/⌘+Enter | 提交当前输入 |\n| 多行输入 | Shift+Enter | 换行继续输入 |\n| 自然语言命令 | 普通文本 | 自动解析执行意图 |\n| Shell 命令 | `!` 前缀 | 执行 shell 命令 |\n| 文件引用 | `@` 前缀 | 引用特定文件 |\n| 取消操作 | Esc (双击) | 清空输入或取消当前操作 |\n\nComposer 支持通过配置切换不同的输入模式，包括标准模式、YOLO 模式（自动接受所有操作）和审核模式。\n\n资料来源：[packages/cli/src/ui/components/Composer.tsx:1-120]()\n\n### ToolConfirmationQueue 工具确认队列\n\n工具确认队列负责管理和展示需要用户授权的操作请求。主要确认类型包括：\n\n| 确认类型 | 显示内容 | 典型场景 |\n|---------|---------|---------|\n| `file-read` | 文件路径列表 | 读取项目文件 |\n| `file-write` | 目标文件列表 | 创建或修改文件 |\n| `network` | 访问的 URL | HTTP 请求 |\n| `exec` | 命令详情 | Shell 命令执行 |\n\n每个确认项包含以下属性：\n- `toolName`：工具名称\n- `confirmationDetails`：详细确认信息\n- `onApprove`：批准回调\n- `onDeny`：拒绝回调\n\n资料来源：[packages/cli/src/ui/components/ToolConfirmationQueue.tsx:1-100]()\n\n## 主题系统\n\n### ThemeManager 主题管理器\n\n`ThemeManager` 负责统一管理 CLI 界面的视觉呈现，采用声明式主题配置：\n\n```typescript\ninterface Theme {\n text: {\n primary: string;\n secondary: string;\n link: string;\n accent: string;\n };\n status: {\n success: string;\n warning: string;\n error: string;\n };\n bg: string;\n border: string;\n}\n```\n\n### 内置主题变体\n\n| 主题名称 | 适用场景 | 特点 |\n|---------|---------|------|\n| `dark` | 深色终端背景 | 高对比度文字 |\n| `light` | 浅色终端背景 | 柔和配色 |\n| `nord` | Nord 配色方案 | 蓝灰色调 |\n| `dracula` | Dracula 配色 | 紫色主调 |\n\n主题支持通过 `GEMINI_THEME` 环境变量或配置文件进行切换。\n\n资料来源：[packages/cli/src/ui/themes/theme-manager.ts:1-80]()\n\n## 交互流程\n\n### 对话交互流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Composer as Composer组件\n participant App as App根组件\n participant Core as Core引擎\n participant Model as Gemini模型\n \n User->>Composer: 输入文本/命令\n Composer->>App: 提交消息\n App->>Core: 发送请求\n Core->>Model: 流式请求\n Model-->>Core: 流式响应\n Core-->>App: 消息片段\n App->>Composer: 清空输入\n App-->>User: 显示消息\n \n Note over Core,Model: 工具调用阶段\n Core->>App: 请求工具确认\n App->>User: 显示确认对话框\n User->>App: 批准/拒绝\n App-->>Core: 确认结果\n```\n\n### 工具确认流程\n\n当模型请求执行敏感操作时，UI 层按以下步骤处理：\n\n1. **检测请求**：Core 引擎识别需要确认的工具调用\n2. **创建确认项**：生成包含操作详情的确认对象\n3. **添加到队列**：将确认项加入 `ToolConfirmationQueue`\n4. **用户决策**：用户查看详情并做出选择\n5. **执行反馈**：根据用户决策执行或拒绝操作\n6. **状态更新**：更新消息状态为已完成/已拒绝\n\n资料来源：[packages/cli/src/ui/App.tsx:200-280]()\n\n## 组件通信机制\n\n### Props Drilling 与 Context\n\nCLI UI 采用混合状态管理策略：\n\n- **Props Drilling**：用于紧密耦合的父子组件间通信\n- **React Context**：用于跨层级状态共享\n - `ConfigContext`：应用配置\n - `ThemeContext`：主题信息\n - `MessagesContext`：消息历史\n\n### 事件流处理\n\n| 事件类型 | 处理层级 | 传播方向 |\n|---------|---------|---------|\n| 键盘事件 | Composer | 组件内处理 |\n| 对话事件 | App | 根组件协调 |\n| 确认事件 | ToolConfirmationQueue | 队列内部处理 |\n\n资料来源：[packages/cli/src/ui/components/ToolConfirmationQueue.tsx:50-80]()\n\n## 界面布局与响应式设计\n\n### 固定布局模式\n\nCLI UI 采用固定布局设计，针对标准终端尺寸优化：\n\n| 区域 | 固定属性 | 说明 |\n|-----|---------|------|\n| 头部 | 固定高度 | Logo、版本、状态 |\n| 消息区 | 弹性高度 | 占据主要内容空间 |\n| 输入区 | 固定高度 | Composer 组件 |\n\n### 宽度自适应\n\n界面支持宽度自适应调整，当终端宽度小于阈值时自动切换为紧凑布局模式。Logo 和元数据从水平排列改为垂直堆叠。\n\n资料来源：[packages/cli/src/ui/components/AppHeader.tsx:30-60]()\n\n## 隐私通知组件\n\n### 双隐私体系\n\nGemini CLI 根据用户使用模式展示不同的隐私声明：\n\n| 隐私通知 | 适用场景 | 内容重点 |\n|---------|---------|---------|\n| `CloudFreePrivacyNotice` | 免费用户 | 数据收集和使用说明 |\n| `GeminiPrivacyNotice` | 付费/企业用户 | API 服务条款引用 |\n\n隐私通知在首次使用或设置变更时显示，包含以下核心内容：\n- 数据收集范围说明\n- 人类审核流程披露\n- 数据保留期限（18个月）\n- 退出选项\n\n资料来源：[packages/cli/src/ui/privacy/CloudFreePrivacyNotice.tsx:1-50]()\n\n## 辅助功能与可达性\n\n### 键盘导航支持\n\n完整的键盘操作支持确保纯键盘用户的可用性：\n\n- **Tab 导航**：在可交互元素间切换\n- **方向键**：列表项选择\n- **Enter**：确认选择\n- **Escape**：取消/返回\n\n### 屏幕阅读器兼容\n\nUI 元素包含语义化的 `aria-*` 属性标注，支持辅助技术正确解读界面结构。\n\n## 扩展机制\n\n### 对话框扩展\n\nCLI UI 提供对话框扩展点，允许注册自定义对话框类型：\n\n| 扩展类型 | 注册方式 | 典型用途 |\n|---------|---------|---------|\n| `InboxDialog` | 技能/补丁通知 | 技能安装确认 |\n| `FolderTrustDialog` | 文件夹信任 | 本地配置加载确认 |\n| `ExtensionRegistryView` | 扩展管理 | 扩展浏览和安装 |\n\n### 视图扩展\n\n`ExtensionDetails` 和 `ExtensionRegistryView` 组件支持展示扩展元数据，包括版本号、星级评分、功能标签等。\n\n资料来源：[packages/cli/src/ui/components/views/ExtensionDetails.tsx:1-60]()\n\n## 总结\n\nGemini CLI 用户界面是一个功能完备的终端交互系统，通过组件化架构实现了清晰的功能分离和良好的可维护性。界面设计充分考虑了终端环境的特殊性，在有限的视觉表现空间内提供了丰富的交互功能，包括对话管理、工具确认、主题定制和扩展支持等核心能力。\n\n---\n\n\n\n## 命令系统\n\n### 相关页面\n\n相关主题：[CLI用户界面](#page-cli-ui)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/cli/src/ui/components/Help.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/Help.tsx)\n- [packages/cli/src/ui/components/messages/ToolConfirmationMessage.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/messages/ToolConfirmationMessage.tsx)\n- [packages/core/src/agents/skill-extraction-agent.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/agents/skill-extraction-agent.ts)\n- [packages/cli/src/ui/components/AboutBox.tsx](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/ui/components/AboutBox.tsx)\n- [README.md](https://github.com/google-gemini/gemini-cli/blob/main/README.md)\n \n\n# 命令系统\n\n## 概述\n\nGemini CLI 的命令系统是用户与 CLI 交互的核心机制，提供了一套完整的命令执行框架。该系统支持多种命令类型，包括内置命令（Built-in Commands）、自定义命令（Custom Commands）和 MCP 命令（Model Context Protocol Commands）。命令系统设计为模块化架构，允许用户通过斜杠命令（`/`前缀）快速调用各种功能，同时支持自然语言执行 shell 命令。\n\n命令系统的主要职责包括命令的注册、解析、路由和执行。通过统一的消息总线（MessageBus）架构，命令系统与工具系统紧密集成，实现了命令执行与 AI 模型响应的无缝衔接。系统还提供了完善的确认机制，确保涉及敏感操作（如网络访问、文件写入）的命令在执行前获得用户授权。\n\n## 命令类型\n\n### 内置命令\n\n内置命令是 Gemini CLI 预置的标准功能集，提供了 CLI 核心操作的入口点。这些命令覆盖了帮助信息、聊天管理、系统设置等常用功能。用户可以通过在输入框中输入 `/commandname` 的方式直接调用这些命令。\n\n内置命令的显示格式包含命令名称和描述信息，部分命令还支持子命令（subCommands）。系统会自动过滤掉标记为隐藏（hidden）的命令，只向用户展示可用的命令选项。命令的分类和组织便于用户快速找到所需功能。\n\n| 命令类型 | 触发方式 | 可见性 |\n|---------|---------|-------|\n| 主命令 | `/commandname` | 默认显示 |\n| 子命令 | `/commandname subcommand` | 嵌套显示 |\n| MCP命令 | `/commandname [MCP]` | 带MCP标识 |\n| Shell命令 | `!command` | 使用感叹号前缀 |\n\n### MCP 命令\n\nMCP（Model Context Protocol）命令是来自外部 MCP 服务器的命令。系统通过 MCP 协议与外部服务器通信，获取这些命令的定义和功能描述。MCP 命令在帮助界面中以 `[MCP]` 标签标识，便于用户识别其来源。\n\nMCP 命令的确认流程与内置命令类似，但在工具确认界面中会明确标注为 MCP 类型。当 MCP 命令涉及网络访问或文件操作时，系统会显示相应的警告信息，提示用户注意安全风险。\n\n### Shell 命令\n\nShell 命令允许用户直接在 CLI 环境中执行系统 shell 命令。用户可以通过两种方式触发 shell 命令：使用 `!` 前缀（如 `!npm run start`），或使用自然语言描述（如 \"start server\"）。\n\nShell 命令在确认界面中以黄色警告色标识，突出显示其潜在风险。系统会对每个 shell 命令进行安全检查，确认其是否涉及网络访问、文件读写等敏感操作。\n\n## 命令解析机制\n\n### 命令解析器架构\n\n命令解析器（SlashCommandResolver）是命令系统的核心组件，负责将用户输入转换为可执行的命令对象。当用户在 CLI 输入框中输入以 `/` 开头的文本时，系统会触发命令解析流程。\n\n解析器首先识别命令前缀，然后匹配用户输入与已注册的命令名称。如果找到完全匹配的命令，则直接返回该命令对象；如果未找到完全匹配，则可能触发命令建议或错误提示。\n\n```\ngraph TD\n A[用户输入 /command] --> B[命令解析器接收]\n B --> C{命令类型判断}\n C -->|内置命令| D[查找内置命令注册表]\n C -->|MCP命令| E[查询MCP服务器]\n C -->|自定义命令| F[搜索自定义命令目录]\n D --> G[返回命令对象]\n E --> G\n F --> G\n G --> H[执行命令处理器]\n H --> I[返回执行结果]\n```\n\n### 命令注册流程\n\n内置命令通过 BuiltinCommandLoader 在 CLI 启动时自动注册到命令系统中。加载器扫描预定义的命令模块，将每个命令及其元数据（名称、描述、子命令等）添加到命令注册表中。\n\n自定义命令则通过文件系统监控实现动态加载。当用户在 `.gemini/commands` 目录下创建新的命令定义文件时，系统会自动检测并注册这些命令，无需重启 CLI。\n\n## 命令确认机制\n\n### 工具确认界面\n\n当命令涉及敏感操作时，系统会显示工具确认界面（ToolConfirmationMessage）供用户审核。该界面清晰列出命令将执行的各项操作及其权限范围。\n\n确认界面显示的信息包括：\n\n- **命令名称**：显示即将执行的命令名称\n- **网络访问**：如果命令需要网络访问，标注为 \"Network: All Urls\"\n- **写入路径**：列出所有将被写入的文件路径\n- **读取路径**：列出所有将被读取的文件路径\n\n### 安全提示\n\nShell 命令在确认界面中以黄色警告色高亮显示，提醒用户这些命令将在系统级别执行。系统会根据 `ApprovalMode` 配置决定是否需要用户手动确认：\n\n- **Manual 模式**：所有敏感操作都需要用户手动确认\n- **Auto-Edit 模式**：自动批准编辑类操作\n- **YOLO 模式**：跳过所有确认直接执行（不推荐）\n\n| 确认模式 | 网络访问 | 文件写入 | 文件读取 |\n|---------|---------|---------|---------|\n| Manual | 需确认 | 需确认 | 需确认 |\n| Auto-Edit | 需确认 | 自动批准 | 自动批准 |\n| YOLO | 自动批准 | 自动批准 | 自动批准 |\n\n## 自定义命令\n\n### 命令定义\n\nGemini CLI 支持用户创建自定义命令来扩展功能。自定义命令存储在项目根目录的 `.gemini/commands` 目录下（资料来源：[README.md:1-100]()）。每个自定义命令都是一个独立的文件，可以包含特定的提示词和执行逻辑。\n\n自定义命令的主要用途包括：\n\n- 封装常用的复杂工作流程为一键操作\n- 为特定项目创建专用命令集\n- 共享和复用团队的最佳实践\n\n### 创建流程\n\n用户可以通过自然语言描述想要创建的命令功能，Gemini CLI 会自动生成相应的命令定义文件。创建过程中，系统会引导用户完善以下信息：\n\n1. **触发条件（Triggers）**：定义命令被激活的关键词或模式\n2. **执行步骤（Procedure）**：详细描述命令的执行逻辑\n3. **注意事项（Pitfalls）**：提醒用户可能遇到的问题\n4. **验证步骤（Verification）**：如何确认命令执行成功\n\n### 技能提取与命令生成\n\nskill-extraction-agent 模块（资料来源：[packages/core/src/agents/skill-extraction-agent.ts:1-100]()）负责从用户的对话历史中提取有价值的工作流程，并将其转化为可复用的技能或命令。该智能体分析会话内容，识别重复性操作，并建议用户是否需要创建自定义命令来简化这些操作。\n\n## 命令显示组件\n\n### 帮助界面\n\nHelp.tsx（资料来源：[packages/cli/src/ui/components/Help.tsx:1-100]()）组件负责渲染命令帮助界面。该组件从命令注册表中获取所有可用命令，过滤隐藏命令后按类别展示给用户。\n\n帮助界面的布局特点：\n\n- 主命令以粗体显示，带有强调色标识\n- 子命令通过缩进和斜线前缀区分\n- MCP 命令标注 `[MCP]` 标签\n- Shell 命令使用 `!` 前缀标识\n\n### 关于界面\n\nAboutBox.tsx（资料来源：[packages/cli/src/ui/components/AboutBox.tsx:1-100]()）组件显示 CLI 版本信息和系统配置状态。该界面虽然不直接处理命令执行，但为用户提供当前会话的技术上下文，包括：\n\n- CLI 版本号\n- Git 提交信息\n- 当前使用的模型版本\n- Sandbox 环境配置\n- 操作系统信息\n\n## 键盘快捷键\n\n命令系统与输入处理系统紧密集成，提供了丰富的键盘快捷键来提升操作效率：\n\n| 快捷键 | 功能 | 说明 |\n|-------|------|------|\n| `Ctrl+Left/Right` | 单词跳转 | 在输入框中按单词快速移动光标 |\n| `Ctrl+C` | 退出 | 退出当前 CLI 会话 |\n| `/` | 命令触发 | 开始输入斜杠命令 |\n\n## 扩展机制\n\n### MCP 服务器集成\n\nGemini CLI 通过 MCP（Model Context Protocol）协议支持扩展服务器。用户可以配置额外的 MCP 服务器来引入新的命令和能力。官方示例包括与 Google Cloud Platform 的 Vertex AI Creative Studio 集成，支持媒体生成功能（Imagen、Veo、Lyria）。\n\nMCP 服务器的配置通过标准 MCP 配置格式管理，CLI 启动时自动发现并注册可用的 MCP 命令。\n\n### 工具绑定\n\n命令系统与工具系统共享相同的消息总线架构。命令可以调用底层工具来完成具体操作，如文件读写、shell 执行、网络请求等。这种设计实现了命令层与功能层的分离，便于维护和扩展。\n\n## 数据流\n\n```\ngraph LR\n A[用户输入] --> B{输入解析}\n B -->|/command| C[内置命令]\n B -->|!command| D[Shell命令]\n B -->|自然语言| E[AI模型处理]\n C --> F[命令执行器]\n D --> G[Shell执行器]\n E --> H[意图识别]\n H --> I[工具调用]\n F --> J[结果展示]\n G --> J\n I --> J\n J --> K[UI更新]\n```\n\n## 最佳实践\n\n### 命令命名规范\n\n创建自定义命令时，建议遵循以下命名规范：\n\n- 使用小写字母和连字符（如 `my-custom-command`）\n- 避免与内置命令名称冲突\n- 使用描述性名称，使命令用途一目了然\n\n### 安全考虑\n\n- 谨慎使用 YOLO 模式，该模式跳过所有安全确认\n- 创建涉及文件操作的命令时，明确指定允许的路径范围\n- 定期检查已注册的命令列表，确保没有未授权的命令\n\n### 性能优化\n\n- 避免在命令中执行过于复杂的逻辑\n- 将耗时操作拆分为多个独立命令\n- 使用子命令组织复杂的功能集\n\n## 参考资料\n\n- Gemini CLI 官方文档：https://www.geminicli.com/docs/reference/commands\n- 自定义命令指南：https://www.geminicli.com/docs/cli/custom-commands\n- 键盘快捷键参考：https://www.geminicli.com/docs/reference/keyboard-shortcuts\n\n---\n\n\n\n## 安全策略与策略引擎\n\n### 相关页面\n\n相关主题：[代理系统与子代理](#page-agent-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/src/policy/policy-engine.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/policy/policy-engine.ts)\n- [packages/core/src/policy/toml-loader.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/policy/toml-loader.ts)\n- [packages/core/src/policy/shell-safety.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/policy/shell-safety.ts)\n- [packages/core/src/policy/sandboxPolicyManager.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/policy/sandboxPolicyManager.ts)\n- [packages/core/src/availability/policyHelpers.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/availability/policyHelpers.ts)\n- [packages/core/src/config/config.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/config/config.ts)\n- [packages/cli/src/commands/extensions/examples/policies/README.md](https://github.com/google-gemini/gemini-cli/blob/main/packages/cli/src/commands/extensions/examples/policies/README.md)\n \n\n# 安全策略与策略引擎\n\n## 概述\n\nGemini CLI 的安全策略与策略引擎是保护用户系统安全的核心组件。该系统通过 TOML 配置文件定义安全规则，并在 CLI 执行命令前进行安全检查，防止恶意或危险操作执行。\n\n策略引擎的核心职责包括：\n\n- 加载和解析 `.toml` 格式的策略文件\n- 在命令执行前进行安全验证\n- 管理沙箱环境的访问权限\n- 处理 shell 命令的安全性评估\n- 支持扩展程序贡献额外的安全规则\n\n## 架构设计\n\n```mermaid\ngraph TD\n A[用户命令] --> B[策略引擎 PolicyEngine]\n B --> C{TOML 加载器
TomlLoader}\n C --> D[核心策略文件]\n C --> E[扩展策略文件]\n C --> F[用户自定义策略]\n D --> G[规则引擎]\n E --> G\n F --> G\n G --> H{安全检查}\n H -->|通过| I[命令执行]\n H -->|拒绝| J[安全警告]\n H -->|需要确认| K[用户确认对话框]\n \n L[ShellSafety] --> G\n M[SandboxPolicyManager] --> G\n```\n\n### 核心组件\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| PolicyEngine | `packages/core/src/policy/policy-engine.ts` | 主策略引擎，协调所有策略检查 |\n| TomlLoader | `packages/core/src/policy/toml-loader.ts` | 解析 TOML 格式的策略配置文件 |\n| ShellSafety | `packages/core/src/policy/shell-safety.ts` | Shell 命令安全性检查 |\n| SandboxPolicyManager | `packages/core/src/policy/sandboxPolicyManager.ts` | 沙箱环境策略管理 |\n| policyHelpers | `packages/core/src/availability/policyHelpers.ts` | 策略链解析和辅助函数 |\n\n## 策略文件格式\n\n### TOML 配置文件结构\n\n策略引擎使用 TOML 格式定义安全规则。每个策略文件包含以下核心部分：\n\n```toml\n# 规则定义\n[rules]\n# 规则名称 = 规则类型\n\n# 确认要求\n[confirm]\n# 命令模式 = 确认消息\n\n# 拒绝规则\n[deny]\n# 命令模式 = 拒绝消息\n\n# 允许路径\n[allowed_paths]\n# 列出允许访问的目录\n```\n\n### 策略文件位置\n\n策略文件按优先级从低到高搜索：\n\n1. **内置核心策略** - CLI 内置的安全规则\n2. **扩展贡献的策略** - 第三方扩展添加的策略\n3. **用户自定义策略** - 用户本地配置的策略\n\n资料来源：[packages/cli/src/commands/extensions/examples/policies/README.md]()\n\n## 策略类型\n\n### 1. 确认规则 (Confirm Rules)\n\n需要用户确认才能执行的命令。配置格式：\n\n```toml\n[confirm]\n\"rm -rf\" = \"此命令将递归删除文件，是否继续？\"\n\"sudo\" = \"即将以管理员权限执行命令\"\n```\n\n当策略引擎检测到匹配的命令模式时，会暂停执行并显示确认对话框。\n\n### 2. 拒绝规则 (Deny Rules)\n\n完全禁止执行的命令。\n\n```toml\n[deny]\n\"grep.*\\\\.env\" = \"禁止搜索敏感文件\"\n\"*credential*\" = \"禁止访问凭证相关文件\"\n```\n\n资料来源：[packages/cli/src/commands/extensions/examples/policies/README.md]()\n\n### 3. 路径限制规则 (Path Restrictions)\n\n限制文件操作在特定目录范围内。\n\n```toml\n[allowed_paths]\nread = [\"/home/user/project\", \"/tmp\"]\nwrite = [\"/home/user/project/src\"]\n```\n\n### 4. 安全检查器 (Safety Checkers)\n\n自定义的安全检查器函数，在特定操作前执行：\n\n```toml\n[safety_checkers]\nallowed_path = true # 启用路径验证检查器\n```\n\n## 策略引擎核心流程\n\n```mermaid\nsequenceDiagram\n participant CLI as Gemini CLI\n participant PE as PolicyEngine\n participant TL as TomlLoader\n participant SS as ShellSafety\n participant SPM as SandboxPolicyManager\n \n CLI->>PE: 执行命令请求\n PE->>TL: 加载策略配置\n TL-->>PE: 返回策略规则列表\n PE->>SS: 检查 Shell 安全性\n SS-->>PE: 安全检查结果\n PE->>SPM: 验证沙箱权限\n SPM-->>PE: 沙箱检查结果\n PE->>PE: 综合评估\n alt 所有检查通过\n PE-->>CLI: 允许执行\n else 存在风险\n PE-->>CLI: 请求用户确认\n else 违反规则\n PE-->>CLI: 拒绝执行\n end\n```\n\n### 主要检查步骤\n\n1. **策略加载阶段** - 收集所有适用策略\n2. **模式匹配阶段** - 匹配命令与规则模式\n3. **安全评估阶段** - 评估命令风险等级\n4. **决策输出阶段** - 返回执行决策\n\n## 沙箱策略管理\n\n### SandboxPolicyManager\n\n`SandboxPolicyManager` 负责管理沙箱执行环境的访问控制策略。\n\n主要功能：\n\n- **目录访问控制** - 限制沙箱内进程的文件系统访问\n- **网络访问限制** - 控制沙箱进程的网络通信\n- **进程隔离** - 管理沙箱内进程的执行权限\n\n资料来源：[packages/core/src/policy/sandboxPolicyManager.ts]()\n\n### 沙箱模式\n\n| 模式 | 描述 | 安全性 |\n|------|------|--------|\n| unrestricted | 无限制模式 | 低 |\n| restricted | 限制模式，仅允许预定义操作 | 中 |\n| sandboxed | 完全沙箱模式，最严格限制 | 高 |\n\n## Shell 安全检查\n\n### ShellSafety 模块\n\n`ShellSafety` 模块专门处理 Shell 命令的安全性评估。\n\n```typescript\ninterface ShellSafetyCheck {\n command: string; // 待检查的命令\n riskLevel: RiskLevel; // 风险等级\n matchedRules: string[]; // 匹配的规则列表\n requiresConfirmation: boolean; // 是否需要确认\n canDeny: boolean; // 是否可以拒绝\n}\n```\n\n### 内置危险命令检测\n\n策略引擎内置以下危险命令的自动检测：\n\n- `rm -rf` - 递归删除文件\n- `dd` - 直接磁盘写入\n- `mkfs` - 格式化文件系统\n- `> /dev/sd*` - 直接写入设备文件\n\n## 策略扩展机制\n\n### 扩展贡献策略\n\n第三方扩展可以通过 `gemini-extension.json` 清单文件贡献安全策略：\n\n```json\n{\n \"policies\": [\n \"policies/*.toml\"\n ]\n}\n```\n\n扩展贡献的策略文件必须位于扩展目录的 `policies/` 子目录中。\n\n### 安全限制\n\n**重要安全约束**：Gemini CLI 会忽略扩展贡献的任何 `allow` 决策或 `yolo` 模式配置。这确保了扩展只能增强安全性，而不能绕过用户确认机制。\n\n资料来源：[packages/cli/src/commands/extensions/examples/policies/README.md]()\n\n## 配置与集成\n\n### 工具注册中的策略应用\n\n策略引擎与工具注册系统集成，在工具注册时应用策略配置：\n\n```typescript\nmaybeRegister(UpdateTopicTool, () =>\n registry.registerTool(new UpdateTopicTool(this, this.messageBus)),\n);\n\nmaybeRegister(LSTool, () =>\n registry.registerTool(new LSTool(this, this.messageBus)),\n);\n\nmaybeRegister(ReadFileTool, () =>\n registry.registerTool(new ReadFileTool(this, this.messageBus)),\n);\n```\n\n资料来源：[packages/core/src/config/config.ts:45-55]()\n\n### 策略链解析\n\n`policyHelpers` 模块提供策略链解析功能，支持多模型场景下的策略协调：\n\n```typescript\nfunction resolvePolicyChain(config: Config): PolicyChain {\n // 根据当前配置返回适用的策略链\n // 支持自定义模型和目录模型的策略分发\n}\n```\n\n资料来源：[packages/core/src/availability/policyHelpers.ts]()\n\n## 错误处理\n\n### 策略验证失败\n\n策略引擎会对加载的策略进行验证：\n\n- TOML 语法验证\n- 规则模式语法检查\n- 路径有效性验证\n- 冲突规则检测\n\n验证失败的策略会被静默丢弃，不会影响其他策略的执行。\n\n### 运行时错误\n\n当策略检查过程中发生错误时：\n\n1. 记录详细错误日志\n2. 返回保守的安全决策（拒绝执行）\n3. 向用户显示友好的错误提示\n\n## 最佳实践\n\n### 为扩展编写策略\n\n1. **明确作用域** - 每个策略文件应有单一明确的目的\n2. **使用具体模式** - 避免过于宽泛的通配符匹配\n3. **提供清晰消息** - 拒绝和确认消息应清楚说明原因\n4. **包含验证步骤** - 添加验证或陷阱步骤确保规则有效\n\n### 用户自定义策略\n\n用户可以在本地配置目录中创建自定义策略文件：\n\n```\n~/.gemini-cli/\n├── policies/\n│ ├── custom-deny.toml\n│ └── project-rules.toml\n```\n\n## 总结\n\nGemini CLI 的安全策略与策略引擎通过模块化设计实现了灵活且强大的安全控制机制。TOML 格式的配置文件提供了易于维护的策略定义方式，而多层级的策略加载和验证流程确保了系统安全性。扩展机制允许社区贡献额外的安全规则，同时保持了核心安全约束不被绕过。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：google-gemini/gemini-cli\n\n摘要：发现 23 个潜在踩坑项，其中 14 个为 high/blocking；最高优先级：安装坑 - 来源证据：Surface or quarantine invalid Auto Memory inbox patches。\n\n## 1. 安装坑 · 来源证据：Surface or quarantine invalid Auto Memory inbox patches\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Surface or quarantine invalid Auto Memory inbox patches\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_58be51e305414f12a3dd5f6c39b5e777 | https://github.com/google-gemini/gemini-cli/issues/26523 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：Memory system bugs and quality improvements\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Memory system bugs and quality improvements\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_956d952c67c7469189ec67aef86139d4 | https://github.com/google-gemini/gemini-cli/issues/26516 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 运行坑 · 来源证据：Change the steering eval test to always pass\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Change the steering eval test to always pass\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e480448796b34a7da894c9769d69b46c | https://github.com/google-gemini/gemini-cli/issues/23313 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 运行坑 · 来源证据：Model frequently creates tmp scripts in random spots\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Model frequently creates tmp scripts in random spots\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_abead6f384f94be497a8893d52d0ca2b | https://github.com/google-gemini/gemini-cli/issues/23571 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 维护坑 · 来源证据：Gemini CLI encounters 400 error with > 128 tools\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Gemini CLI encounters 400 error with > 128 tools\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1e04a5efd78143d79b2ef38a564c428f | https://github.com/google-gemini/gemini-cli/issues/24246 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安全/权限坑 · 来源证据：Add deterministic redaction and reduce Auto Memory logging\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add deterministic redaction and reduce Auto Memory logging\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_33c66a37dc674c5084470c52157d3f4b | https://github.com/google-gemini/gemini-cli/issues/26525 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 7. 安全/权限坑 · 来源证据：All model quotas not resetting, even after days\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：All model quotas not resetting, even after days\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1ed06494b0e8487e9f5b9b5faa68374c | https://github.com/google-gemini/gemini-cli/issues/26967 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。\n\n## 8. 安全/权限坑 · 来源证据：Gemini CLI 0.42.0-preview.1: [API Error: ..... v1internal:generateContent failed, reason: ] Request contains an invalid…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Gemini CLI 0.42.0-preview.1: [API Error: ..... v1internal:generateContent failed, reason: ] Request contains an invalid argument at process.processTicksAndReje…\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9f0cc269f15147bf94171001a3d0a145 | https://github.com/google-gemini/gemini-cli/issues/26572 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 9. 安全/权限坑 · 来源证据：Gemini failed to open in a temporary path A:\\\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Gemini failed to open in a temporary path A:\\\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b7b6d80c305d48d2a7548e12a6621b72 | https://github.com/google-gemini/gemini-cli/issues/25216 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 10. 安全/权限坑 · 来源证据：Robust component level evalutions\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Robust component level evalutions\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0b7e5ce9e4de49d1aae81349f2856cd7 | https://github.com/google-gemini/gemini-cli/issues/24353 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. 安全/权限坑 · 来源证据：Shell command execution gets stuck with \"Waiting input\" after command completes\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Shell command execution gets stuck with \"Waiting input\" after command completes\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_73f28f340a29499e9a1718d38d5500ad | https://github.com/google-gemini/gemini-cli/issues/25166 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 12. 安全/权限坑 · 来源证据：Stop Auto Memory from retrying low-signal sessions indefinitely\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Stop Auto Memory from retrying low-signal sessions indefinitely\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fb1dec66ee3c4a9f9faf5cb91b286667 | https://github.com/google-gemini/gemini-cli/issues/26522 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 13. 安全/权限坑 · 来源证据：Tool \"save_memory\" not found.\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Tool \"save_memory\" not found.\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7b0f9e9404664597ab5f60b481da55fe | https://github.com/google-gemini/gemini-cli/issues/26563 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。\n\n## 14. 安全/权限坑 · 来源证据：Your idiotic AI disobeyed me completely lied and has now cost me 300 dollars worth of work that went into my obsidian -…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Your idiotic AI disobeyed me completely lied and has now cost me 300 dollars worth of work that went into my obsidian - 10000s of files and work deleted not re…\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4bdaf010293245ac9e6f4ceece341d76 | https://github.com/google-gemini/gemini-cli/issues/26856 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 安装坑 · 来源证据：feat(cli): expose model thinking events in --output-format stream-json\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat(cli): expose model thinking events in --output-format stream-json\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5c2ad6806ee6413dbf441b91f6862364 | https://github.com/google-gemini/gemini-cli/issues/22083 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 16. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:968197216 | https://github.com/google-gemini/gemini-cli | README/documentation is current enough for a first validation pass.\n\n## 17. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:968197216 | https://github.com/google-gemini/gemini-cli | last_activity_observed missing\n\n## 18. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:968197216 | https://github.com/google-gemini/gemini-cli | no_demo; severity=medium\n\n## 19. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:968197216 | https://github.com/google-gemini/gemini-cli | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 20. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:968197216 | https://github.com/google-gemini/gemini-cli | no_demo; severity=medium\n\n## 21. 安全/权限坑 · 来源证据：CLI on start picks wrong default model\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：CLI on start picks wrong default model\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4285a488cff443c1a1e3586dbea13786 | https://github.com/google-gemini/gemini-cli/issues/26971 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 22. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:968197216 | https://github.com/google-gemini/gemini-cli | issue_or_pr_quality=unknown\n\n## 23. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:968197216 | https://github.com/google-gemini/gemini-cli | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：google-gemini/gemini-cli\n\n摘要：发现 23 个潜在踩坑项，其中 14 个为 high/blocking；最高优先级：安装坑 - 来源证据：Surface or quarantine invalid Auto Memory inbox patches。\n\n## 1. 安装坑 · 来源证据：Surface or quarantine invalid Auto Memory inbox patches\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Surface or quarantine invalid Auto Memory inbox patches\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_58be51e305414f12a3dd5f6c39b5e777 | https://github.com/google-gemini/gemini-cli/issues/26523 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：Memory system bugs and quality improvements\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Memory system bugs and quality improvements\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_956d952c67c7469189ec67aef86139d4 | https://github.com/google-gemini/gemini-cli/issues/26516 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 运行坑 · 来源证据：Change the steering eval test to always pass\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Change the steering eval test to always pass\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e480448796b34a7da894c9769d69b46c | https://github.com/google-gemini/gemini-cli/issues/23313 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 运行坑 · 来源证据：Model frequently creates tmp scripts in random spots\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Model frequently creates tmp scripts in random spots\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_abead6f384f94be497a8893d52d0ca2b | https://github.com/google-gemini/gemini-cli/issues/23571 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 维护坑 · 来源证据：Gemini CLI encounters 400 error with > 128 tools\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Gemini CLI encounters 400 error with > 128 tools\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1e04a5efd78143d79b2ef38a564c428f | https://github.com/google-gemini/gemini-cli/issues/24246 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安全/权限坑 · 来源证据：Add deterministic redaction and reduce Auto Memory logging\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add deterministic redaction and reduce Auto Memory logging\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_33c66a37dc674c5084470c52157d3f4b | https://github.com/google-gemini/gemini-cli/issues/26525 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 7. 安全/权限坑 · 来源证据：All model quotas not resetting, even after days\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：All model quotas not resetting, even after days\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1ed06494b0e8487e9f5b9b5faa68374c | https://github.com/google-gemini/gemini-cli/issues/26967 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。\n\n## 8. 安全/权限坑 · 来源证据：Gemini CLI 0.42.0-preview.1: [API Error: ..... v1internal:generateContent failed, reason: ] Request contains an invalid…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Gemini CLI 0.42.0-preview.1: [API Error: ..... v1internal:generateContent failed, reason: ] Request contains an invalid argument at process.processTicksAndReje…\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9f0cc269f15147bf94171001a3d0a145 | https://github.com/google-gemini/gemini-cli/issues/26572 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 9. 安全/权限坑 · 来源证据：Gemini failed to open in a temporary path A:\\\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Gemini failed to open in a temporary path A:\\\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b7b6d80c305d48d2a7548e12a6621b72 | https://github.com/google-gemini/gemini-cli/issues/25216 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 10. 安全/权限坑 · 来源证据：Robust component level evalutions\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Robust component level evalutions\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0b7e5ce9e4de49d1aae81349f2856cd7 | https://github.com/google-gemini/gemini-cli/issues/24353 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. 安全/权限坑 · 来源证据：Shell command execution gets stuck with \"Waiting input\" after command completes\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Shell command execution gets stuck with \"Waiting input\" after command completes\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_73f28f340a29499e9a1718d38d5500ad | https://github.com/google-gemini/gemini-cli/issues/25166 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 12. 安全/权限坑 · 来源证据：Stop Auto Memory from retrying low-signal sessions indefinitely\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Stop Auto Memory from retrying low-signal sessions indefinitely\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fb1dec66ee3c4a9f9faf5cb91b286667 | https://github.com/google-gemini/gemini-cli/issues/26522 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 13. 安全/权限坑 · 来源证据：Tool \"save_memory\" not found.\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Tool \"save_memory\" not found.\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7b0f9e9404664597ab5f60b481da55fe | https://github.com/google-gemini/gemini-cli/issues/26563 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。\n\n## 14. 安全/权限坑 · 来源证据：Your idiotic AI disobeyed me completely lied and has now cost me 300 dollars worth of work that went into my obsidian -…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Your idiotic AI disobeyed me completely lied and has now cost me 300 dollars worth of work that went into my obsidian - 10000s of files and work deleted not re…\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4bdaf010293245ac9e6f4ceece341d76 | https://github.com/google-gemini/gemini-cli/issues/26856 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 安装坑 · 来源证据：feat(cli): expose model thinking events in --output-format stream-json\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat(cli): expose model thinking events in --output-format stream-json\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5c2ad6806ee6413dbf441b91f6862364 | https://github.com/google-gemini/gemini-cli/issues/22083 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 16. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:968197216 | https://github.com/google-gemini/gemini-cli | README/documentation is current enough for a first validation pass.\n\n## 17. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:968197216 | https://github.com/google-gemini/gemini-cli | last_activity_observed missing\n\n## 18. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:968197216 | https://github.com/google-gemini/gemini-cli | no_demo; severity=medium\n\n## 19. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:968197216 | https://github.com/google-gemini/gemini-cli | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 20. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:968197216 | https://github.com/google-gemini/gemini-cli | no_demo; severity=medium\n\n## 21. 安全/权限坑 · 来源证据：CLI on start picks wrong default model\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：CLI on start picks wrong default model\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4285a488cff443c1a1e3586dbea13786 | https://github.com/google-gemini/gemini-cli/issues/26971 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 22. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:968197216 | https://github.com/google-gemini/gemini-cli | issue_or_pr_quality=unknown\n\n## 23. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:968197216 | https://github.com/google-gemini/gemini-cli | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# gemini-cli - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 gemini-cli 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：MCP Client\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. page-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装与配置。围绕“安装与配置”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-tools：核心工具集。围绕“核心工具集”模拟一次用户任务，不展示安装或运行结果。\n5. page-agent-system：代理系统与子代理。围绕“代理系统与子代理”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装与配置”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-tools\n输入：用户提供的“核心工具集”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-agent-system\n输入：用户提供的“代理系统与子代理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装与配置”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-tools：Step 4 必须围绕“核心工具集”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-agent-system：Step 5 必须围绕“代理系统与子代理”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/google-gemini/gemini-cli\n- https://github.com/google-gemini/gemini-cli#readme\n- .gemini/skills/async-pr-review/SKILL.md\n- .gemini/skills/behavioral-evals/SKILL.md\n- .gemini/skills/ci/SKILL.md\n- .gemini/skills/code-reviewer/SKILL.md\n- .gemini/skills/docs-changelog/SKILL.md\n- .gemini/skills/docs-writer/SKILL.md\n- .gemini/skills/github-issue-creator/SKILL.md\n- .gemini/skills/pr-address-comments/SKILL.md\n- .gemini/skills/pr-creator/SKILL.md\n- .gemini/skills/review-duplication/SKILL.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 gemini-cli 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：google-gemini/gemini-cli\n\n## 官方安装入口\n\n### Gemini CLI · 官方安装入口\n\n```bash\nnpx @google/gemini-cli\n```\n\n来源：https://github.com/google-gemini/gemini-cli#readme\n\n## 来源\n\n- repo: https://github.com/google-gemini/gemini-cli\n- docs: https://github.com/google-gemini/gemini-cli#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_db8319d8d7e54841875a82b94e0be05e"
}