{
  "canonical_name": "QwenLM/qwen-code",
  "compilation_id": "pack_1ee341901fd045ffb3462deaec4094dc",
  "created_at": "2026-05-14T05:31:06.254483+00:00",
  "created_by": "project-pack-compiler",
  "feedback": {
    "carrier_selection_notes": [
      "viable_asset_types=skill, recipe, host_instruction, eval, preflight",
      "recommended_asset_types=skill, recipe, host_instruction, eval, preflight"
    ],
    "evidence_delta": {
      "confirmed_claims": [
        "identity_anchor_present",
        "capability_and_host_targets_present",
        "install_path_declared_or_better"
      ],
      "missing_required_fields": [],
      "must_verify_forwarded": [
        "Run or inspect `npm install -g @qwen-code/qwen-code@latest` in an isolated environment.",
        "Confirm the project exposes the claimed capability to at least one target host."
      ],
      "quickstart_execution_scope": "allowlisted_sandbox_smoke",
      "sandbox_command": "npm install -g @qwen-code/qwen-code@latest",
      "sandbox_container_image": "node:22-slim",
      "sandbox_execution_backend": "docker",
      "sandbox_planner_decision": "deterministic_isolated_install",
      "sandbox_validation_id": "sbx_fcdedcc455ac4013aa0fe2b3eddf2f67"
    },
    "feedback_event_type": "project_pack_compilation_feedback",
    "learning_candidate_reasons": [],
    "template_gaps": []
  },
  "identity": {
    "canonical_id": "project_62115ea84d5368bcff8e5c95b5abcb06",
    "canonical_name": "QwenLM/qwen-code",
    "homepage_url": null,
    "license": "unknown",
    "repo_url": "https://github.com/QwenLM/qwen-code",
    "slug": "qwen-code",
    "source_packet_id": "phit_ddd2ea3a5cbd48288cf13d83edf73cc3",
    "source_validation_id": "dval_d750a4261ee247f2afff5933a37f8cf2"
  },
  "merchandising": {
    "best_for": "需要软件开发与交付能力，并使用 claude的用户",
    "github_forks": null,
    "github_stars": null,
    "one_liner_en": "<div align=\"center\">",
    "one_liner_zh": "<div align=\"center\">",
    "primary_category": {
      "category_id": "software-development",
      "confidence": "high",
      "name_en": "Software Development",
      "name_zh": "软件开发与交付",
      "reason": "matched_keywords:code, test, git"
    },
    "target_user": "使用 claude, claude_code, chatgpt 等宿主 AI 的用户",
    "title_en": "qwen-code",
    "title_zh": "qwen-code 能力包",
    "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": "Code Review",
        "label_zh": "代码审查",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "core_capability-code-review",
        "type": "core_capability"
      },
      {
        "label_en": "Node-based Workflow",
        "label_zh": "节点式流程编排",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "workflow_pattern-node-based-workflow",
        "type": "workflow_pattern"
      },
      {
        "label_en": "Local-first",
        "label_zh": "本地优先",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "selection_signal-local-first",
        "type": "selection_signal"
      }
    ]
  },
  "packet_id": "phit_ddd2ea3a5cbd48288cf13d83edf73cc3",
  "page_model": {
    "artifacts": {
      "artifact_slug": "qwen-code",
      "files": [
        "PROJECT_PACK.json",
        "QUICK_START.md",
        "PROMPT_PREVIEW.md",
        "HUMAN_MANUAL.md",
        "AI_CONTEXT_PACK.md",
        "BOUNDARY_RISK_CARD.md",
        "PITFALL_LOG.md",
        "REPO_INSPECTION.json",
        "REPO_INSPECTION.md",
        "CAPABILITY_CONTRACT.json",
        "EVIDENCE_INDEX.json",
        "CLAIM_GRAPH.json"
      ],
      "required_files": [
        "PROJECT_PACK.json",
        "QUICK_START.md",
        "PROMPT_PREVIEW.md",
        "HUMAN_MANUAL.md",
        "AI_CONTEXT_PACK.md",
        "BOUNDARY_RISK_CARD.md",
        "PITFALL_LOG.md",
        "REPO_INSPECTION.json"
      ]
    },
    "detail": {
      "capability_source": "Project Hit Packet + DownstreamValidationResult",
      "commands": [
        {
          "command": "npm install -g @qwen-code/qwen-code@latest",
          "label": "Node.js / npm · 官方安装入口",
          "source": "https://github.com/QwenLM/qwen-code#readme",
          "verified": true
        }
      ],
      "display_tags": [
        "浏览器 Agent",
        "网页任务自动化",
        "代码审查",
        "节点式流程编排",
        "本地优先"
      ],
      "eyebrow": "软件开发与交付",
      "glance": [
        {
          "body": "判断自己是不是目标用户。",
          "label": "最适合谁",
          "value": "需要软件开发与交付能力，并使用 claude的用户"
        },
        {
          "body": "先理解能力边界，再决定是否继续。",
          "label": "核心价值",
          "value": "<div align=\"center\">"
        },
        {
          "body": "未完成验证前保持审慎。",
          "label": "继续前",
          "value": "publish to Doramagic.ai project surfaces"
        }
      ],
      "guardrail_source": "Boundary & Risk Card",
      "guardrails": [
        {
          "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
          "label": "Check 1",
          "value": "不要把试用当真实运行"
        },
        {
          "body": "claude, claude_code, chatgpt",
          "label": "Check 2",
          "value": "确认宿主兼容"
        },
        {
          "body": "publish to Doramagic.ai project surfaces",
          "label": "Check 3",
          "value": "先隔离验证"
        }
      ],
      "mode": "skill, recipe, host_instruction, eval, preflight",
      "pitfall_log": {
        "items": [
          {
            "body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。",
            "category": "配置坑",
            "evidence": [
              "capability.host_targets | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | host_targets=claude, claude_code, chatgpt"
            ],
            "severity": "medium",
            "suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。",
            "title": "可能修改宿主 AI 配置",
            "user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。"
          },
          {
            "body": "README/documentation is current enough for a first validation pass.",
            "category": "能力坑",
            "evidence": [
              "capability.assumptions | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | README/documentation is current enough for a first validation pass."
            ],
            "severity": "medium",
            "suggested_check": "将假设转成下游验证清单。",
            "title": "能力判断依赖假设",
            "user_impact": "假设不成立时，用户拿不到承诺的能力。"
          },
          {
            "body": "未记录 last_activity_observed。",
            "category": "维护坑",
            "evidence": [
              "evidence.maintainer_signals | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | last_activity_observed missing"
            ],
            "severity": "medium",
            "suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
            "title": "维护活跃度未知",
            "user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
          },
          {
            "body": "no_demo",
            "category": "安全/权限坑",
            "evidence": [
              "downstream_validation.risk_items | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | no_demo; severity=medium"
            ],
            "severity": "medium",
            "suggested_check": "进入安全/权限治理复核队列。",
            "title": "下游验证发现风险项",
            "user_impact": "下游已经要求复核，不能在页面中弱化。"
          },
          {
            "body": "No sandbox install has been executed yet; downstream must verify before user use.",
            "category": "安全/权限坑",
            "evidence": [
              "risks.safety_notes | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | No sandbox install has been executed yet; downstream must verify before user use."
            ],
            "severity": "medium",
            "suggested_check": "转成明确权限清单和安全审查提示。",
            "title": "存在安全注意事项",
            "user_impact": "用户安装前需要知道权限边界和敏感操作。"
          },
          {
            "body": "no_demo",
            "category": "安全/权限坑",
            "evidence": [
              "risks.scoring_risks | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | no_demo; severity=medium"
            ],
            "severity": "medium",
            "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
            "title": "存在评分风险",
            "user_impact": "风险会影响是否适合普通用户安装。"
          },
          {
            "body": "issue_or_pr_quality=unknown。",
            "category": "维护坑",
            "evidence": [
              "evidence.maintainer_signals | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | issue_or_pr_quality=unknown"
            ],
            "severity": "low",
            "suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
            "title": "issue/PR 响应质量未知",
            "user_impact": "用户无法判断遇到问题后是否有人维护。"
          },
          {
            "body": "release_recency=unknown。",
            "category": "维护坑",
            "evidence": [
              "evidence.maintainer_signals | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | release_recency=unknown"
            ],
            "severity": "low",
            "suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
            "title": "发布节奏不明确",
            "user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
          }
        ],
        "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
        "summary": "发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。",
        "title": "踩坑日志"
      },
      "snapshot": {
        "contributors": null,
        "forks": null,
        "license": "unknown",
        "note": "站点快照，非实时质量证明；用于开工前背景判断。",
        "stars": null
      },
      "source_url": "https://github.com/QwenLM/qwen-code",
      "steps": [
        {
          "body": "不安装项目，先体验能力节奏。",
          "code": "preview",
          "title": "先试 Prompt"
        },
        {
          "body": "理解输入、输出、失败模式和边界。",
          "code": "manual",
          "title": "读说明书"
        },
        {
          "body": "把上下文交给宿主 AI 继续工作。",
          "code": "context",
          "title": "带给 AI"
        },
        {
          "body": "进入主力环境前先完成安装入口与风险边界验证。",
          "code": "verify",
          "title": "沙箱验证"
        }
      ],
      "subtitle": "<div align=\"center\">",
      "title": "qwen-code 能力包",
      "trial_prompt": "# qwen-code - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 qwen-code 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：claude / Claude Code / chatgpt\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. project-overview：项目概览。围绕“项目概览”模拟一次用户任务，不展示安装或运行结果。\n2. quick-start：快速入门。围绕“快速入门”模拟一次用户任务，不展示安装或运行结果。\n3. system-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. agent-runtime：智能体运行时。围绕“智能体运行时”模拟一次用户任务，不展示安装或运行结果。\n5. tool-system：工具系统。围绕“工具系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. project-overview\n输入：用户提供的“项目概览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quick-start\n输入：用户提供的“快速入门”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. system-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. agent-runtime\n输入：用户提供的“智能体运行时”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. tool-system\n输入：用户提供的“工具系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / project-overview：Step 1 必须围绕“项目概览”形成一个小中间产物，并等待用户确认。\n- Step 2 / quick-start：Step 2 必须围绕“快速入门”形成一个小中间产物，并等待用户确认。\n- Step 3 / system-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / agent-runtime：Step 4 必须围绕“智能体运行时”形成一个小中间产物，并等待用户确认。\n- Step 5 / tool-system：Step 5 必须围绕“工具系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/QwenLM/qwen-code#readme\n- .qwen/skills/bugfix/SKILL.md\n- .qwen/skills/codegraph/SKILL.md\n- .qwen/skills/docs-audit-and-refresh/SKILL.md\n- .qwen/skills/docs-update-from-diff/SKILL.md\n- .qwen/skills/e2e-testing/SKILL.md\n- .qwen/skills/feat-dev/SKILL.md\n- .qwen/skills/qwen-code-claw/SKILL.md\n- .qwen/skills/structured-debugging/SKILL.md\n- .qwen/skills/terminal-capture/SKILL.md\n- .qwen/skills/tmux-real-user-testing/SKILL.md\n- packages/cli/src/commands/extensions/examples/skills/skills/synonyms/SKILL.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 qwen-code 的核心服务。\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: /language output 切换后必须重启才能生效（https://github.com/QwenLM/qwen-code/issues/4142）；github/github_issue: node 26.0.0 - API Error: Connection error. (cause: fetch failed)（https://github.com/QwenLM/qwen-code/issues/4140）；github/github_issue: не работает сжатие контекста（https://github.com/QwenLM/qwen-code/issues/4141）；github/github_issue: 400 {\"type\":\"error\",\"error\":{\"type\":\"invalid_request_error\",\"message\":\"i（https://github.com/QwenLM/qwen-code/issues/4139）；github/github_issue: Daemon mode (qwen serve): proposal & open decisions（https://github.com/QwenLM/qwen-code/issues/3803）；github/github_release: Release v0.15.11（https://github.com/QwenLM/qwen-code/releases/tag/v0.15.11）；github/github_release: Release v0.15.11-preview.2（https://github.com/QwenLM/qwen-code/releases/tag/v0.15.11-preview.2）；github/github_release: Release v0.15.10-preview.1（https://github.com/QwenLM/qwen-code/releases/tag/v0.15.10-preview.1）；github/github_release: Release v0.15.10-nightly.20260513.14512080e（https://github.com/QwenLM/qwen-code/releases/tag/v0.15.10-nightly.20260513.14512080e）；github/github_release: Release v0.15.11-preview.1（https://github.com/QwenLM/qwen-code/releases/tag/v0.15.11-preview.1）；github/github_release: Release v0.15.11-preview.0（https://github.com/QwenLM/qwen-code/releases/tag/v0.15.11-preview.0）；github/github_release: Release v0.15.10-nightly.20260511.0a05ea800（https://github.com/QwenLM/qwen-code/releases/tag/v0.15.10-nightly.20260511.0a05ea800）。这些是项目级外部声音，不作为单独质量证明。",
          "items": [
            {
              "kind": "github_issue",
              "source": "github",
              "title": "/language output 切换后必须重启才能生效",
              "url": "https://github.com/QwenLM/qwen-code/issues/4142"
            },
            {
              "kind": "github_issue",
              "source": "github",
              "title": "node 26.0.0 - API Error: Connection error. (cause: fetch failed)",
              "url": "https://github.com/QwenLM/qwen-code/issues/4140"
            },
            {
              "kind": "github_issue",
              "source": "github",
              "title": "не работает сжатие контекста",
              "url": "https://github.com/QwenLM/qwen-code/issues/4141"
            },
            {
              "kind": "github_issue",
              "source": "github",
              "title": "400 {\"type\":\"error\",\"error\":{\"type\":\"invalid_request_error\",\"message\":\"i",
              "url": "https://github.com/QwenLM/qwen-code/issues/4139"
            },
            {
              "kind": "github_issue",
              "source": "github",
              "title": "Daemon mode (qwen serve): proposal & open decisions",
              "url": "https://github.com/QwenLM/qwen-code/issues/3803"
            },
            {
              "kind": "github_release",
              "source": "github",
              "title": "Release v0.15.11",
              "url": "https://github.com/QwenLM/qwen-code/releases/tag/v0.15.11"
            },
            {
              "kind": "github_release",
              "source": "github",
              "title": "Release v0.15.11-preview.2",
              "url": "https://github.com/QwenLM/qwen-code/releases/tag/v0.15.11-preview.2"
            },
            {
              "kind": "github_release",
              "source": "github",
              "title": "Release v0.15.10-preview.1",
              "url": "https://github.com/QwenLM/qwen-code/releases/tag/v0.15.10-preview.1"
            },
            {
              "kind": "github_release",
              "source": "github",
              "title": "Release v0.15.10-nightly.20260513.14512080e",
              "url": "https://github.com/QwenLM/qwen-code/releases/tag/v0.15.10-nightly.20260513.14512080e"
            },
            {
              "kind": "github_release",
              "source": "github",
              "title": "Release v0.15.11-preview.1",
              "url": "https://github.com/QwenLM/qwen-code/releases/tag/v0.15.11-preview.1"
            },
            {
              "kind": "github_release",
              "source": "github",
              "title": "Release v0.15.11-preview.0",
              "url": "https://github.com/QwenLM/qwen-code/releases/tag/v0.15.11-preview.0"
            },
            {
              "kind": "github_release",
              "source": "github",
              "title": "Release v0.15.10-nightly.20260511.0a05ea800",
              "url": "https://github.com/QwenLM/qwen-code/releases/tag/v0.15.10-nightly.20260511.0a05ea800"
            }
          ],
          "status": "已收录 13 条来源",
          "title": "社区讨论"
        }
      ]
    },
    "homepage_card": {
      "category": "软件开发与交付",
      "desc": "<div align=\"center\">",
      "effort": "安装已验证",
      "forks": null,
      "icon": "code",
      "name": "qwen-code 能力包",
      "risk": "可发布",
      "slug": "qwen-code",
      "stars": null,
      "tags": [
        "浏览器 Agent",
        "网页任务自动化",
        "代码审查",
        "节点式流程编排",
        "本地优先"
      ],
      "thumb": "gray",
      "type": "Skill Pack"
    },
    "manual": {
      "markdown": "# https://github.com/QwenLM/qwen-code 项目说明书\n\n生成时间：2026-05-14 05:02:28 UTC\n\n## 目录\n\n- [项目概览](#project-overview)\n- [快速入门](#quick-start)\n- [系统架构](#system-architecture)\n- [包结构详解](#packages-structure)\n- [智能体运行时](#agent-runtime)\n- [工具系统](#tool-system)\n- [模型集成](#model-integration)\n- [记忆系统](#memory-system)\n- [会话管理](#session-management)\n- [技能与钩子系统](#skills-hooks)\n\n<a id='project-overview'></a>\n\n## 项目概览\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [快速入门](#quick-start)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/QwenLM/qwen-code/blob/main/README.md)\n- [packages/webui/README.md](https://github.com/QwenLM/qwen-code/blob/main/packages/webui/README.md)\n- [docs-site/README.md](https://github.com/QwenLM/qwen-code/blob/main/docs-site/README.md)\n- [packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx)\n- [packages/cli/src/ui/components/subagents/create/CreationSummary.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/subagents/create/CreationSummary.tsx)\n</details>\n\n# 项目概览\n\n## 简介\n\nQwen Code 是一个基于大语言模型（LLM）的智能编程助手项目，由 Qwen 团队开发维护。该项目旨在为开发者提供高效的代码编写、理解和编辑能力，支持多种模型提供商和本地部署方案。\n\nQwen Code 采用模块化架构设计，核心包含命令行界面（CLI）包和 Web UI 组件库两个主要子系统，能够适应不同的使用场景和部署环境。资料来源：[README.md:1-10]()\n\n## 技术架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n    A[用户界面层] --> B[CLI 终端界面]\n    A --> C[Web UI 组件库]\n    B --> D[核心业务逻辑层]\n    C --> D\n    D --> E[模型交互层]\n    E --> F[多模型提供商]\n    F --> G[OpenAI 兼容 API]\n    F --> H[Ollama 本地模型]\n    F --> I[vLLM 服务]\n    F --> J[阿里云 ModelStudio]\n```\n\n### 核心包结构\n\n| 包名称 | 路径 | 功能描述 |\n|--------|------|----------|\n| `packages/cli` | `packages/cli/` | 命令行工具核心包，提供终端交互界面 |\n| `packages/webui` | `packages/webui/` | Web 界面组件库，包含 UI 基础组件 |\n| `docs-site` | `docs-site/` | 文档网站，基于 Next.js 和 Nextra 构建 |\n\n资料来源：[packages/webui/README.md:1-30]()\n\n## CLI 包架构\n\n### 目录结构\n\n```\npackages/cli/\n├── src/\n│   ├── ui/                    # 终端用户界面\n│   │   ├── components/         # UI 组件\n│   │   │   ├── arena/         # Arena 对比系统\n│   │   │   ├── subagents/     # 子代理管理\n│   │   │   ├── mcp/           # MCP 协议支持\n│   │   │   ├── extensions/    # 扩展系统\n│   │   │   ├── background-view/ # 后台任务视图\n│   │   │   └── views/         # 通用视图组件\n│   │   ├── hooks/             # 自定义 React Hooks\n│   │   └── keyMatchers.ts     # 键盘快捷键匹配\n│   ├── nonInteractiveCli.ts   # 非交互式 CLI\n│   └── ...\n```\n\n### UI 组件系统\n\nCLI 包采用 React 组件化设计，所有 UI 组件基于 `ink` 库构建，支持终端环境下的富文本渲染。\n\n**核心组件分类：**\n\n| 组件类别 | 文件路径 | 功能 |\n|----------|----------|------|\n| Arena 组件 | `ui/components/arena/` | Agent 对比选择、停止对话框、卡片展示 |\n| 子代理组件 | `ui/components/subagents/` | 创建、编辑、管理子代理 |\n| MCP 组件 | `ui/components/mcp/` | MCP 服务器工具列表和交互 |\n| 扩展组件 | `ui/components/extensions/` | 扩展详情展示 |\n| 统计组件 | `ui/components/StatsDisplay.tsx` | 性能统计和模型使用情况 |\n\n资料来源：[packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx:1-50]()\n\n### Arena 对比系统\n\nArena 是 Qwen Code 中的 Agent 对比评估模块，允许用户同时运行多个代理并比较它们的结果。\n\n**Arena 核心功能：**\n\n- **选择对话框** (`ArenaSelectDialog.tsx`)：展示可用代理列表，支持状态筛选\n- **停止对话框** (`ArenaStopDialog.tsx`)：提供清理或保留工作树的选项\n- **卡片展示** (`ArenaCards.tsx`)：显示对比结果和统计数据\n\n```mermaid\ngraph LR\n    A[启动 Arena] --> B[选择代理]\n    B --> C[运行对比]\n    C --> D[结果展示]\n    D --> E[选择获胜者]\n    E --> F{清理策略}\n    F -->|cleanup| G[清理工作树]\n    F -->|preserve| H[保留Artifacts]\n```\n\n资料来源：[packages/cli/src/ui/components/arena/ArenaStopDialog.tsx:1-60]()\n\n### 子代理系统\n\n子代理（Subagents）允许用户创建自定义的 AI 代理，配置专属的系统提示词、工具集和颜色标识。\n\n**子代理创建流程：**\n\n1. 配置基本信息（名称、描述）\n2. 选择可用工具集\n3. 设置系统提示词\n4. 选择存储位置（项目级或用户级）\n5. 保存并激活\n\n```typescript\ninterface SubagentConfig {\n  name: string;\n  description: string;\n  systemPrompt: string;\n  tools: string[];\n  color?: string;\n  location: 'project' | 'user';\n  model?: string;\n}\n```\n\n资料来源：[packages/cli/src/ui/components/subagents/create/CreationSummary.tsx:1-40]()\n\n### MCP 协议支持\n\nQwen Code 集成了 MCP（Model Context Protocol）协议，支持通过 MCP 服务器扩展工具能力。\n\n**MCP 功能特性：**\n\n| 功能 | 命令 | 说明 |\n|------|------|------|\n| 工具列表 | `/mcp` | 显示所有 MCP 工具 |\n| 工具详情 | `/mcp schema` | 显示工具参数模式 |\n| 隐藏描述 | `/mcp nodesc` | 隐藏工具描述信息 |\n| OAuth 认证 | `/mcp auth <server-name>` | MCP 服务器认证 |\n| 快捷开关 | `Ctrl+T` | 切换工具描述显示 |\n\n资料来源：[packages/cli/src/ui/components/views/McpStatus.tsx:1-50]()\n\n### 后台任务系统\n\n后台任务视图（BackgroundTasksDialog）提供了长时间运行任务的监控能力。\n\n**任务状态展示：**\n\n- **运行中**：显示进度文本和会话数量\n- **已完成**：显示执行时长和主题统计\n- **错误状态**：展示错误信息和警告\n- **锁释放警告**：提示可能的锁定问题\n\n```mermaid\nstateDiagram-v2\n    [*] --> Running: 启动任务\n    Running --> Completed: 成功完成\n    Running --> Failed: 发生错误\n    Completed --> [*]: 清理\n    Failed --> [*]: 清理\n    Completed --> LockWarning: 锁释放失败\n```\n\n资料来源：[packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx:1-80]()\n\n## Web UI 组件库\n\n### 组件分类\n\n| 类别 | 组件列表 | 用途 |\n|------|----------|------|\n| 图标组件 | FileIcon, FolderIcon, CheckIcon, ErrorIcon | 基础视觉元素 |\n| 布局组件 | Container, Header, Footer, Sidebar | 页面结构布局 |\n| 消息组件 | Message, MessageList, MessageInput | 对话交互 |\n| 工具调用 | ToolCallCard, ToolCallRow | 工具执行展示 |\n\n资料来源：[packages/webui/README.md:50-100]()\n\n### 平台上下文\n\nWebUI 提供 Platform Context 作为平台抽象层，支持不同运行环境的适配：\n\n```tsx\nimport { PlatformProvider, usePlatform } from '@qwen-code/webui/context';\n```\n\n### 主题系统\n\n组件支持自定义主题配置，包括：\n\n- **颜色系统**：主色、强调色、状态色（成功/错误/警告）\n- **尺寸变体**：`sm` | `md` | `lg`\n- **状态标识**：错误状态、加载状态、空状态\n\n## 文档站点\n\n文档网站采用以下技术栈：\n\n| 技术 | 用途 |\n|------|------|\n| Next.js | React 框架和路由系统 |\n| Nextra | MDX 文档框架 |\n| TypeScript | 类型安全 |\n\n**开发命令：**\n\n```bash\nnpm install    # 安装依赖\nnpm run link   # 链接 docs 目录内容\nnpm run dev    # 启动开发服务器\n```\n\n资料来源：[docs-site/README.md:1-40]()\n\n## 配置系统\n\n### 模型配置\n\nQwen Code 支持配置多个模型提供商，通过 `~/.qwen/settings.json` 文件管理：\n\n```json\n{\n  \"modelProviders\": {\n    \"openai\": [\n      {\n        \"id\": \"qwen3:32b\",\n        \"name\": \"Qwen3 32B (Ollama)\",\n        \"baseUrl\": \"http://localhost:11434/v1\",\n        \"generationConfig\": {\n          \"contextWindowSize\": 131072\n        }\n      }\n    ]\n  },\n  \"model\": {\n    \"name\": \"qwen3:32b\"\n  }\n}\n```\n\n### 键盘快捷键\n\n| 命令 | 快捷键 | 功能 |\n|------|--------|------|\n| 提交输入 | `Enter` | 发送消息 |\n| 取消/返回 | `Escape` | 关闭对话框 |\n| 预览切换 | `p` | 切换预览视图 |\n| 详细差异 | `d` | 切换详细差异视图 |\n| 历史上翻 | `Ctrl+P` | 命令历史向上 |\n| 历史下翻 | `Ctrl+N` | 命令历史向下 |\n| 清屏 | `Ctrl+L` | 清除屏幕 |\n\n资料来源：[packages/cli/src/ui/keyMatchers.test.ts:1-40]()\n\n## 性能统计\n\nStatsDisplay 组件展示任务执行的详细性能数据：\n\n| 统计项 | 说明 |\n|--------|------|\n| Wall Time | 任务总耗时 |\n| Agent Active | Agent 活跃时间 |\n| API Time | LLM API 调用耗时及占比 |\n| Tool Time | 工具执行耗时及占比 |\n| Token 统计 | 输入/输出/缓存 Token 数量 |\n| Cache Efficiency | 缓存命中率 |\n\n资料来源：[packages/cli/src/ui/components/StatsDisplay.tsx:1-60]()\n\n## 扩展系统\n\nQwen Code 支持通过扩展（Extensions）机制增强功能，每个扩展包含：\n\n| 属性 | 说明 |\n|------|------|\n| name | 扩展名称 |\n| version | 版本号 |\n| path | 安装路径 |\n| source | 安装来源（npm/local） |\n| mcpServers | 关联的 MCP 服务器 |\n| commands | 可用命令列表 |\n\n资料来源：[packages/cli/src/ui/components/extensions/steps/ExtensionDetailStep.tsx:1-50]()\n\n## 技术栈总结\n\n| 层级 | 技术选型 |\n|------|----------|\n| CLI 界面 | React + Ink（终端 UI 框架） |\n| Web UI | React + Tailwind CSS |\n| 构建工具 | Vite（WebUI）、pkg（CLI 打包） |\n| 文档框架 | Next.js + Nextra |\n| 包管理 | npm workspace |\n\n## 总结\n\nQwen Code 项目采用现代化 monorepo 架构，通过 `packages/cli` 和 `packages/webui` 两个核心包分别服务终端用户和 Web 应用场景。丰富的组件系统（Arena、Subagents、MCP、Extensions）提供了强大的扩展能力，而统一的配置系统和键盘快捷键设计确保了用户体验的一致性。\n\n---\n\n<a id='quick-start'></a>\n\n## 快速入门\n\n### 相关页面\n\n相关主题：[项目概览](#project-overview)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/QwenLM/qwen-code/blob/main/README.md)\n- [packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx)\n- [packages/cli/src/ui/components/extensions/steps/ExtensionDetailStep.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/extensions/steps/ExtensionDetailStep.tsx)\n- [packages/cli/src/ui/components/subagents/create/CreationSummary.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/subagents/create/CreationSummary.tsx)\n- [packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx)\n- [packages/cli/src/ui/components/StatsDisplay.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/StatsDisplay.tsx)\n- [packages/cli/src/ui/components/views/McpStatus.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/views/McpStatus.tsx)\n- [packages/cli/src/ui/components/mcp/steps/ToolListStep.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/mcp/steps/ToolListStep.tsx)\n- [packages/cli/src/ui/components/mcp/steps/ServerListStep.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/mcp/steps/ServerListStep.tsx)\n- [packages/cli/src/ui/keyMatchers.test.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/keyMatchers.test.ts)\n- [packages/webui/README.md](https://github.com/QwenLM/qwen-code/blob/main/packages/webui/README.md)\n</details>\n\n# 快速入门\n\nQwen Code 是一个基于 AI 的智能编程助手，通过命令行界面（CLI）为开发者提供代码生成、补全、调试和重构等功能。本页将帮助用户快速上手 Qwen Code，掌握从安装到日常使用的完整流程。\n\n## 环境要求\n\n在开始使用 Qwen Code 之前，请确保您的开发环境满足以下要求：\n\n| 要求项 | 最低版本 | 说明 |\n|--------|----------|------|\n| Node.js | 18.0.0 | 运行时环境 |\n| npm/yarn/pnpm | 最新稳定版 | 包管理工具 |\n| 操作系统 | macOS/Linux/Windows | 跨平台支持 |\n| 网络 | 可访问 AI 服务 | 用于 API 调用 |\n\n资料来源：[packages/webui/README.md]()\n\n## 安装步骤\n\n### 方式一：通过 npm 全局安装\n\n```bash\nnpm install -g @qwen-code/cli\n```\n\n安装完成后，运行以下命令验证安装：\n\n```bash\nqwen --version\n```\n\n### 方式二：通过包管理器安装\n\n根据您使用的包管理器选择相应命令：\n\n```bash\n# 使用 npm\nnpm install\n\n# 使用 yarn\nyarn install\n\n# 使用 pnpm\npnpm install\n```\n\n资料来源：[README.md](https://github.com/QwenLM/qwen-code/blob/main/README.md)\n\n## 首次配置\n\n### 配置模型提供商\n\nQwen Code 支持配置多个模型提供商，您需要在配置文件中添加 API 密钥和模型信息：\n\n```json\n{\n  \"modelProviders\": {\n    \"openai\": [\n      {\n        \"id\": \"qwen3.6-plus\",\n        \"name\": \"qwen3.6-plus\",\n        \"baseUrl\": \"https://api.example.com/v1\",\n        \"description\": \"Qwen 3.6 Plus 模型\",\n        \"envKey\": \"YOUR_API_KEY\"\n      }\n    ]\n  }\n}\n```\n\n配置文件的默认位置为 `~/.qwen/config.json`（用户级别）或项目目录下的 `.qwen/config.json`（项目级别）。\n\n资料来源：[README.md](https://github.com/QwenLM/qwen-code/blob/main/README.md)\n\n### 配置环境变量\n\n将您的 API 密钥设置为环境变量：\n\n```bash\nexport YOUR_API_KEY=\"your-api-key-here\"\n```\n\n支持的认证方式包括：\n\n| 认证类型 | 说明 | 配置位置 |\n|----------|------|----------|\n| API Key | 标准 API 密钥认证 | `envKey` 字段 |\n| OAuth | OAuth 2.0 认证 | MCP 服务器配置 |\n| 环境变量 | 通过环境变量传递 | 系统环境 |\n\n资料来源：[packages/cli/src/ui/auth/AuthDialog.tsx]()\n\n## 启动应用\n\n配置完成后，通过以下命令启动 Qwen Code：\n\n```bash\nqwen\n```\n\n启动后将进入交互式命令行界面，您可以直接输入自然语言描述来生成代码。\n\n资料来源：[README.md](https://github.com/QwenLM/qwen-code/blob/main/README.md)\n\n## 基本操作\n\n### 切换模型\n\n使用 `/model` 命令可以在已配置的模型之间切换：\n\n```\n/model\n```\n\n系统将显示可用模型列表，供您选择。\n\n资料来源：[README.md](https://github.com/QwenLM/qwen-code/blob/main/README.md)\n\n### 管理子代理\n\nQwen Code 支持创建和管理子代理（Subagents），用于处理特定任务：\n\n```mermaid\ngraph TD\n    A[创建子代理] --> B[配置工具]\n    B --> C[设置系统提示词]\n    C --> D[生成描述]\n    D --> E[保存到项目或用户级别]\n    \n    F[项目级别] --> E\n    G[用户级别] --> E\n```\n\n子代理配置包括以下选项：\n\n| 配置项 | 说明 | 可选值 |\n|--------|------|--------|\n| location | 存储位置 | project / user |\n| tools | 启用的工具 | Read/Edit/Web/Search 等 |\n| color | 显示颜色 | 预定义颜色值 |\n| description | 代理描述 | 自动生成或手动输入 |\n| systemPrompt | 系统提示词 | 自定义指令 |\n\n资料来源：[packages/cli/src/ui/components/subagents/create/CreationSummary.tsx]()\n\n### MCP 服务器集成\n\nQwen Code 支持 MCP（Model Context Protocol）服务器，可扩展工具能力：\n\n```mermaid\ngraph LR\n    A[MCP 服务器] --> B[工具注册]\n    B --> C[状态监控]\n    C --> D{连接状态}\n    D -->|已连接| E[可用工具列表]\n    D -->|断开连接| F[显示错误日志]\n```\n\n常用 MCP 命令：\n\n| 命令 | 功能 |\n|------|------|\n| `/mcp list` | 列出所有 MCP 服务器 |\n| `/mcp schema` | 显示工具参数模式 |\n| `/mcp nodesc` | 隐藏工具描述 |\n| `/mcp auth <server>` | OAuth 认证 |\n| `Ctrl+T` | 切换工具描述显示 |\n\n资料来源：[packages/cli/src/ui/components/views/McpStatus.tsx]()\n资料来源：[packages/cli/src/ui/components/mcp/steps/ToolListStep.tsx]()\n\n## 交互界面\n\n### 工具调用显示\n\n工具调用结果在界面中以卡片形式展示：\n\n| 状态 | 颜色 | 说明 |\n|------|------|------|\n| success | 绿色 | 执行成功 |\n| error | 红色 | 执行失败 |\n| warning | 黄色 | 警告信息 |\n| loading | 蓝色 | 执行中 |\n| pending | 灰色 | 等待中 |\n\n对于文件操作类工具，系统会显示操作结果和文件列表：\n\n```\nToolCallContainer\n├── 状态标志\n├── 操作描述\n└── 文件位置列表\n```\n\n资料来源：[packages/webui/src/components/toolcalls/GenericToolCall.tsx]()\n\n### 性能统计\n\nQwen Code 提供实时性能统计功能：\n\n| 统计项 | 说明 |\n|--------|------|\n| Wall Time | 总耗时 |\n| Agent Active | 代理活跃时间 |\n| API Time | API 调用耗时及占比 |\n| Tool Time | 工具执行耗时及占比 |\n| Token Usage | Token 使用量 |\n| Cache Efficiency | 缓存效率 |\n\n资料来源：[packages/cli/src/ui/components/StatsDisplay.tsx]()\n\n### 键盘快捷键\n\n| 功能 | 快捷键 |\n|------|--------|\n| 确认建议 | `Tab` 或 `Enter` |\n| 取消操作 | `Escape` |\n| 历史记录上 | `Ctrl+P` |\n| 历史记录下 | `Ctrl+N` |\n| 导航上 | `Up` |\n| 导航下 | `Down` |\n| 删除整行 | `Ctrl+U` |\n| 清屏 | `Ctrl+L` |\n| 提交输入 | `Enter`（无修饰键） |\n\n资料来源：[packages/cli/src/ui/keyMatchers.test.ts]()\n\n## Arena 对战模式\n\nArena 是 Qwen Code 的代码对比评估功能，可比较不同代理的代码生成结果：\n\n```mermaid\ngraph TD\n    A[进入 Arena] --> B[选择代理]\n    B --> C[执行任务]\n    C --> D[生成差异对比]\n    D --> E[选择获胜者]\n    E --> F[查看性能统计]\n```\n\nArena 界面显示：\n\n- **状态信息**：执行状态、耗时、Token 数量、文件数量\n- **差异统计**：代码增删行数（绿色添加/红色删除）\n- **Token 效率**：各代理的 Token 使用量和运行时间对比\n\n资料来源：[packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx]()\n资料来源：[packages/cli/src/ui/components/arena/ArenaCards.tsx]()\n\n## 后台任务管理\n\nQwen Code 支持后台任务执行，适合长时间运行的任务：\n\n```mermaid\ngraph TD\n    A[提交任务] --> B[锁定资源]\n    B --> C{执行状态}\n    C -->|成功| D[释放锁]\n    C -->|失败| E[记录错误]\n    C -->|警告| F[锁释放警告]\n    C -->|警告| G[元数据写入警告]\n```\n\n后台任务显示信息包括：\n\n| 信息类型 | 说明 |\n|----------|------|\n| 会话数量 | 正在审查的会话数 |\n| 进度文本 | 当前任务进度 |\n| 触达主题 | 已处理的主题列表 |\n| 锁定警告 | 锁释放失败提示 |\n| 元数据警告 | 元数据写入失败提示 |\n\n资料来源：[packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx]()\n\n## 扩展管理\n\nQwen Code 支持通过扩展增强功能：\n\n| 扩展属性 | 说明 |\n|----------|------|\n| name | 扩展名称 |\n| version | 版本号 |\n| status | 启用状态 |\n| path | 安装路径 |\n| source | 来源信息 |\n| mcpServers | 关联的 MCP 服务器 |\n| commands | 可用命令列表 |\n\n资料来源：[packages/cli/src/ui/components/extensions/steps/ExtensionDetailStep.tsx]()\n\n## 下一步\n\n完成快速入门后，建议继续阅读以下文档：\n\n- **配置指南**：深入了解配置文件格式和高级选项\n- **认证配置**：学习如何配置各种认证方式\n- **扩展开发**：了解如何开发自定义扩展\n- **API 参考**：查看完整的命令行接口文档\n\n---\n\n<a id='system-architecture'></a>\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目概览](#project-overview), [包结构详解](#packages-structure), [智能体运行时](#agent-runtime)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx)\n- [packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx)\n- [packages/cli/src/ui/components/mcp/steps/ServerListStep.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/mcp/steps/ServerListStep.tsx)\n- [packages/cli/src/ui/components/StatsDisplay.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/StatsDisplay.tsx)\n- [packages/core/src/memory/extractionAgentPlanner.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/memory/extractionAgentPlanner.ts)\n- [README.md](https://github.com/QwenLM/qwen-code/blob/main/README.md)\n</details>\n\n# 系统架构\n\n## 概述\n\nQwen Code 是一个模块化的命令行 AI 编程助手，采用多包架构设计以实现核心逻辑与用户界面的分离。项目主要由 `packages/cli`、`packages/core` 和 `packages/webui` 三个核心包组成，支持扩展机制、后台任务管理、代理（Agent）编排以及 MCP（Model Context Protocol）协议集成。\n\n## 整体架构\n\n```mermaid\ngraph TD\n    User[用户] --> CLI[packages/cli<br/>命令行界面]\n    CLI --> WebUI[packages/webui<br/>Web UI 组件]\n    CLI --> Core[packages/core<br/>核心逻辑]\n    Core --> Memory[记忆管理模块]\n    Core --> Planner[任务规划模块]\n    Core --> Tools[工具系统]\n    CLI --> Mcp[MCP 服务器集成]\n    Mcp --> Servers[外部 MCP 服务]\n```\n\n## 核心包结构\n\n### packages/core — 核心逻辑层\n\n核心包负责 AI 代理的核心功能实现，包括任务规划、记忆管理和工具调用。\n\n| 模块 | 路径 | 功能描述 |\n|------|------|----------|\n| 记忆管理 | `src/memory/` | 管理代理的持久化记忆，包括主题文档自动扫描 |\n| 任务规划 | `src/planner/` | 构建和管理任务执行的提示词 |\n| 工具系统 | `src/tools/` | 代理可调用的内置工具集合 |\n\n**记忆管理模块**\n\n`extractionAgentPlanner.ts` 实现了记忆提取代理，规划器会扫描项目中的自动记忆主题文档并生成摘要块。该模块支持以下功能：\n\n- 扫描 `auto-memory` 主题文档\n- 截断长文本以控制上下文长度\n- 构建 Markdown 格式的记忆摘要\n\n资料来源：[packages/core/src/memory/extractionAgentPlanner.ts:1-30]()\n\n### packages/cli — 命令行界面\n\nCLI 包提供终端用户界面，处理用户输入、命令解析和状态展示。\n\n| 组件目录 | 功能 |\n|----------|------|\n| `ui/components/arena/` | 对战竞技场界面，支持代理选择、对话预览、差异对比 |\n| `ui/components/background-view/` | 后台任务对话框，显示进度、错误、锁定警告 |\n| `ui/components/mcp/` | MCP 服务器和工具列表管理 |\n| `ui/components/extensions/` | 扩展详情展示 |\n| `ui/components/subagents/` | 子代理创建和配置 |\n| `ui/components/views/` | 状态视图组件 |\n\n**Arena 竞技场组件**\n\nArena 模块支持多代理并行对比功能。`ArenaSelectDialog.tsx` 实现了代理选择对话框，提供以下状态信息展示：\n\n- 运行状态及颜色编码\n- 运行时长\n- Token 消耗统计\n- 代码变更（增加/删除行数）\n- 涉及文件数量\n\n资料来源：[packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx:1-40]()\n\n**后台任务管理**\n\n`BackgroundTasksDialog.tsx` 实现了后台任务监控界面，支持以下功能：\n\n- 任务进度文本显示\n- Session 计数展示\n- 主题追踪列表\n- 错误状态展示\n- 锁定释放警告\n- 元数据写入警告\n\n资料来源：[packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx:1-80]()\n\n**MCP 集成**\n\nMCP 模块负责与外部 MCP 服务器的通信：\n\n```mermaid\ngraph LR\n    CLI[CLI] --> ServerList[服务器列表]\n    CLI --> ToolList[工具列表]\n    ServerList --> Status[连接状态]\n    ToolList --> Validation[工具验证]\n    Status -->|disconnected| Debug[调试提示]\n```\n\n- `ServerListStep.tsx`: 显示 MCP 服务器列表及连接状态\n- `ToolListStep.tsx`: 显示可用工具列表，支持滚动和选择\n- 无效工具显示警告信息及原因\n\n资料来源：[packages/cli/src/ui/components/mcp/steps/ServerListStep.tsx:1-50]()\n资料来源：[packages/cli/src/ui/components/mcp/steps/ToolListStep.tsx:1-60]()\n\n### packages/webui — Web UI 组件库\n\nWebUI 包提供可复用的 React 组件，支持 Storybook 文档化。\n\n| 组件类别 | 组件 |\n|----------|------|\n| 图标 | FileIcon, FolderIcon, CheckIcon, ErrorIcon, WarningIcon |\n| 布局 | Container, Header, Footer, Sidebar, Main |\n| 消息 | Message, MessageList, MessageInput, WaitingMessage |\n| 工具调用 | ToolCallCard, ToolCallRow |\n\n**Platform Context**\n\n提供平台特定能力的抽象层：\n\n```tsx\nimport { PlatformProvider, usePlatform } from '@qwen-code/webui/context';\n```\n\n## 统计与性能监控\n\n`StatsDisplay.tsx` 组件负责展示运行统计数据：\n\n| 统计类别 | 指标 |\n|----------|------|\n| 代码变更 | 新增行数、删除行数 |\n| 性能 | 墙钟时间、代理活跃时间 |\n| 时间分析 | API 调用时间及占比、工具调用时间及占比 |\n| 模型使用 | 各模型 Token 消耗、缓存效率 |\n\n资料来源：[packages/cli/src/ui/components/StatsDisplay.tsx:1-60]()\n\n## 扩展机制\n\n扩展系统支持自定义功能和 MCP 服务器集成：\n\n- 扩展版本和路径信息展示\n- 激活状态管理\n- MCP 服务器关联配置\n- 自定义命令注册\n\n资料来源：[packages/cli/src/ui/components/extensions/steps/ExtensionDetailStep.tsx:1-50]()\n\n## 键盘交互系统\n\nCLI 实现了一套完整的键盘快捷键匹配系统：\n\n| 命令 | 快捷键 |\n|------|--------|\n| 接受建议 | Tab / Enter |\n| 清除输入 | Ctrl+C |\n| 历史上一条 | Ctrl+P |\n| 历史下一条 | Ctrl+N |\n| 导航上/下 | 方向键 |\n| 退出 | Escape |\n\n## 子代理创建流程\n\n`CreationSummary.tsx` 组件展示子代理创建的配置摘要：\n\n- 位置选择：项目级（`.qwen/agents/`）或用户级（`~/.qwen/agents/`）\n- 工具配置显示\n- 颜色标识\n- 系统提示词和描述预览\n\n资料来源：[packages/cli/src/ui/components/subagents/create/CreationSummary.tsx:1-50]()\n\n## 数据流架构\n\n```mermaid\ngraph TD\n    Input[用户输入] --> AtCmd[@ 命令处理]\n    AtCmd --> Processor[命令处理器]\n    Processor --> Config[配置系统]\n    Config --> Agent[代理执行]\n    Agent --> Tools[工具调用]\n    Tools --> Mcp[MCP 协议]\n    Mcp --> External[外部服务]\n    Agent --> Memory[记忆更新]\n    Memory --> UI[UI 更新]\n    UI --> Stats[统计展示]\n```\n\n## 配置模型\n\n项目支持灵活的配置模型，支持多个模型提供商：\n\n```json\n{\n  \"modelProviders\": {\n    \"openai\": [\n      {\n        \"id\": \"qwen3.6-plus\",\n        \"name\": \"qwen3.6-plus\",\n        \"baseUrl\": \"https://...\",\n        \"envKey\": \"API_KEY\",\n        \"generationConfig\": {}\n      }\n    ]\n  }\n}\n```\n\n支持的配置项：\n\n- 模型 ID 和名称\n- API Base URL\n- 环境变量密钥\n- 生成配置（温度、最大 token 等）\n- 思考模式启用\n\n资料来源：[README.md:1-50]()\n\n## 技术栈总结\n\n| 层级 | 技术 |\n|------|------|\n| 核心运行时 | TypeScript/Node.js |\n| CLI 界面 | React + Ink（终端 UI 框架） |\n| Web UI | React + Tailwind CSS |\n| 构建工具 | Vite |\n| 文档站点 | Next.js + Nextra |\n| 测试 | Vitest |\n\n---\n\n<a id='packages-structure'></a>\n\n## 包结构详解\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/cli/README.md](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/README.md)\n- [packages/webui/README.md](https://github.com/QwenLM/qwen-code/blob/main/packages/webui/README.md)\n- [docs-site/README.md](https://github.com/QwenLM/qwen-code/blob/main/docs-site/README.md)\n- [packages/core/src/memory/extractionAgentPlanner.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/memory/extractionAgentPlanner.ts)\n- [packages/core/src/utils/toml-to-markdown-converter.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/utils/toml-to-markdown-converter.ts)\n- [README.md](https://github.com/QwenLM/qwen-code/blob/main/README.md)\n</details>\n\n# 包结构详解\n\n## 项目概述\n\nQwen Code 是一个采用 Monorepo（单仓库）结构管理的多语言 SDK 项目。根据项目根目录的 `README.md` 和各子包的文档，该项目包含了 **CLI 命令行工具**、**WebUI 界面**、**Core 核心库**、**文档站点** 等多个子包。\n\n资料来源：[README.md:1-50]()\n\n## 整体架构\n\nQwen Code 采用 monorepo 结构组织代码，所有子包位于 `packages/` 目录下。核心子包包括：\n\n| 子包名称 | 路径 | 技术栈 | 用途 |\n|---------|------|--------|------|\n| cli | `packages/cli/` | TypeScript/Node.js | 命令行交互界面 |\n| webui | `packages/webui/` | React/Vite/TypeScript | Web 图形界面 |\n| core | `packages/core/` | TypeScript | 核心逻辑与 API |\n| docs-site | `docs-site/` | Next.js/MDX | 文档网站 |\n\n资料来源：[packages/webui/README.md:1-30]()\n\n## 子包详细结构\n\n### packages/cli\n\nCLI 子包是用户与 Qwen Code 交互的主要入口，提供终端 UI 界面。\n\n```\npackages/cli/\n├── src/\n│   ├── ui/\n│   │   ├── components/        # UI 组件目录\n│   │   │   ├── arena/         # Arena 对战组件\n│   │   │   ├── background-view/  # 后台任务视图\n│   │   │   ├── extensions/    # 扩展管理组件\n│   │   │   ├── subagents/     # 子代理创建组件\n│   │   │   ├── mcp/           # MCP 服务器管理组件\n│   │   │   ├── messages/      # 消息渲染组件\n│   │   │   ├── hooks/         # Hook 配置组件\n│   │   │   ├── views/         # 状态视图组件\n│   │   │   └── DiffRenderer.tsx  # 差异渲染器\n│   │   ├── commands/          # 命令定义\n│   │   └── App.tsx            # 主应用组件\n│   ├── i18n/                  # 国际化配置\n│   │   ├── locales/           # 语言文件\n│   │   └── mustTranslateKeys.test.ts  # 翻译覆盖测试\n│   └── hooks/                 # 自定义 Hooks\n└── package.json\n```\n\n核心 UI 组件功能说明：\n\n| 组件 | 文件路径 | 功能 |\n|------|----------|------|\n| ArenaSelectDialog | `ui/components/arena/ArenaSelectDialog.tsx` | Agent 对战选择对话框 |\n| BackgroundTasksDialog | `ui/components/background-view/BackgroundTasksDialog.tsx` | 后台任务管理 |\n| ExtensionDetailStep | `ui/components/extensions/steps/ExtensionDetailStep.tsx` | 扩展详情步骤 |\n| ServerListStep | `ui/components/mcp/steps/ServerListStep.tsx` | MCP 服务器列表 |\n| ToolListStep | `ui/components/mcp/steps/ToolListStep.tsx` | 工具列表显示 |\n| McpStatus | `ui/components/views/McpStatus.tsx` | MCP 状态视图 |\n| StatsDisplay | `ui/components/StatsDisplay.tsx` | 统计信息展示 |\n\n资料来源：[packages/cli/README.md](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/README.md)\n\n### packages/webui\n\nWebUI 子包提供基于 React 的图形化界面，支持 Storybook 组件预览。\n\n```\npackages/webui/\n├── src/\n│   ├── components/\n│   │   ├── icons/             # 图标组件\n│   │   ├── layout/            # 布局组件\n│   │   ├── messages/          # 消息组件\n│   │   └── ui/                # UI 基础组件\n│   ├── context/               # 平台上下文\n│   ├── hooks/                 # 自定义 React Hooks\n│   └── types/                 # TypeScript 类型定义\n├── .storybook/                # Storybook 配置\n├── tailwind.preset.cjs        # Tailwind 预设\n└── vite.config.ts             # Vite 构建配置\n```\n\n开发命令：\n\n```bash\n# 启动 Storybook\ncd packages/webui && npm run storybook\n\n# 构建生产版本\nnpm run build\n\n# 类型检查\nnpm run typecheck\n```\n\n资料来源：[packages/webui/README.md:1-60]()\n\n### packages/core\n\nCore 子包包含核心业务逻辑，包括内存管理、内容生成等功能。\n\n```\npackages/core/\n├── src/\n│   ├── memory/\n│   │   ├── prompt.ts              # 内存提示词配置\n│   │   └── extractionAgentPlanner.ts  # 提取代理规划器\n│   ├── core/\n│   │   └── openaiContentGenerator/  # OpenAI 内容生成器\n│   └── utils/\n│       └── toml-to-markdown-converter.ts  # TOML 转 Markdown 工具\n```\n\n核心模块说明：\n\n**内存管理模块 (`memory/`)**\n\n内存管理模块负责管理对话中的持久化记忆，支持外部系统引用、主题文档扫描等功能。\n\n- `prompt.ts` - 定义内存保存的规则和示例，包含 WHAT_NOT_TO_SAVE_SECTION 等常量\n- `extractionAgentPlanner.ts` - 提供 `buildTopicSummaryBlock` 和 `buildTaskPrompt` 等函数用于构建主题摘要\n\n**内容生成模块 (`openaiContentGenerator/`)**\n\n`openaiContentGenerator.ts` 实现内容嵌入和生成功能：\n\n```typescript\nconst embedding = await this.pipeline.client.embeddings.create({\n  model: 'text-embedding-ada-002',\n  input: text,\n});\n```\n\n**工具函数 (`utils/`)**\n\n`toml-to-markdown-converter.ts` 提供 TOML 格式检测和转换功能：\n\n- `isTomlFormat(content: string): boolean` - 检测内容是否为 TOML 格式\n\n资料来源：[packages/core/src/memory/prompt.ts:1-30]()\n\n### docs-site\n\n文档站点基于 Next.js 和 Nextra 构建，提供项目文档的 Web 展示。\n\n```\ndocs-site/\n├── src/\n│   └── app/\n│       ├── [[...mdxPath]]/        # 动态 MDX 路由\n│       │   └── page.jsx\n│       └── layout.jsx             # 根布局\n├── mdx-components.js               # MDX 组件配置\n├── next.config.mjs                # Next.js 配置\n└── package.json\n```\n\n文档内容通过符号链接从 `../docs` 目录挂载：\n\n```bash\nnpm run link  # 创建符号链接\nnpm run dev   # 启动开发服务器\n```\n\n资料来源：[docs-site/README.md:1-40]()\n\n## 依赖关系图\n\n```mermaid\ngraph TD\n    A[docs-site] --> B[docs]\n    C[CLI] --> D[Core]\n    C --> E[WebUI]\n    E --> D\n    F[webui] --> G[Core]\n    \n    style A fill:#e1f5fe\n    style C fill:#fff3e0\n    style E fill:#f3e5f5\n    style G fill:#e8f5e9\n```\n\n## 技术栈总结\n\n| 层级 | 技术选型 |\n|------|----------|\n| 基础语言 | TypeScript |\n| 前端框架 | React 18+ |\n| 构建工具 | Vite (webui) / Next.js (docs) |\n| UI 框架 | Tailwind CSS |\n| 组件测试 | Storybook |\n| 国际化 | 自定义 i18n 方案 |\n| 包管理 | npm |\n\n## 许可证\n\nQwen Code 项目采用 Apache-2.0 许可证发布。\n\n资料来源：[packages/webui/README.md:60]()\n\n---\n\n**注意**：以上包结构基于仓库中实际存在的文件和目录结构整理。部分高级包（如 `channels/`、`sdk-typescript/`、`sdk-python/`、`sdk-java/`）在当前代码快照中未包含详细源码，如需深入了解请查阅对应子包的完整源码。\n\n---\n\n<a id='agent-runtime'></a>\n\n## 智能体运行时\n\n### 相关页面\n\n相关主题：[工具系统](#tool-system), [模型集成](#model-integration), [会话管理](#session-management)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx)\n- [packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx)\n- [packages/cli/src/ui/components/messages/ToolGroupMessage.test.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/messages/ToolGroupMessage.test.tsx)\n- [packages/cli/src/ui/components/StatsDisplay.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/StatsDisplay.tsx)\n- [packages/cli/src/ui/contexts/UIActionsContext.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/contexts/UIActionsContext.tsx)\n- [packages/core/src/memory/prompt.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/memory/prompt.ts)\n</details>\n\n# 智能体运行时\n\n## 概述\n\n智能体运行时（Agent Runtime）是 Qwen Code 系统中负责协调和管理智能体（Agent）生命周期、任务执行、工具调用的核心模块。它提供了智能体的交互式执行环境、后台任务管理、权限控制、以及运行时状态监控等功能。智能体运行时与 UI 层紧密集成，通过事件驱动的架构实现用户与智能体之间的实时交互。\n\n智能体运行时的设计目标是为 AI 编程助手提供一个可扩展、安全且响应迅速的执行环境，支持单智能体任务执行和多智能体协作（如 Arena 对战模式）。\n\n## 核心架构\n\n### 组件层次\n\n```mermaid\ngraph TD\n    subgraph \"UI 层\"\n        ArenaSelectDialog[Arena 选择对话框]\n        BackgroundTasksDialog[后台任务对话框]\n        StatsDisplay[统计信息显示]\n    end\n    \n    subgraph \"状态管理层\"\n        UIActionsContext[UI 操作上下文]\n        AgentViewContext[智能体视图上下文]\n    end\n    \n    subgraph \"运行时核心\"\n        AgentCore[智能体核心]\n        ToolScheduler[工具调度器]\n        PermissionFlow[权限流程]\n    end\n    \n    subgraph \"执行层\"\n        ToolCalls[工具调用]\n        SubAgents[子智能体]\n        Monitors[监控器]\n    end\n    \n    ArenaSelectDialog --> UIActionsContext\n    BackgroundTasksDialog --> UIActionsContext\n    UIActionsContext --> AgentCore\n    AgentCore --> ToolScheduler\n    AgentCore --> PermissionFlow\n    ToolScheduler --> ToolCalls\n    AgentCore --> SubAgents\n    AgentCore --> Monitors\n```\n\n### 智能体状态模型\n\n智能体运行时通过 `AgentResultDisplay` 类型定义智能体的执行状态：\n\n| 状态值 | 含义 | UI 显示 |\n|--------|------|---------|\n| `running` | 任务正在执行中 | 显示进度条和活动指示器 |\n| `completed` | 任务已完成 | 显示成功状态和结果摘要 |\n| `failed` | 任务执行失败 | 显示错误信息 |\n| `cancelled` | 任务被取消 | 显示取消状态 |\n\n资料来源：[packages/cli/src/ui/components/messages/ToolGroupMessage.test.tsx:9-25]()\n\n```typescript\ninterface AgentResultDisplay {\n  type: 'task_execution';\n  subagentName: string;\n  taskDescription: string;\n  taskPrompt: string;\n  status: 'running' | 'completed' | 'failed' | 'cancelled';\n  toolCalls: ToolCall[];\n}\n```\n\n## 任务执行机制\n\n### 工具调用链\n\n智能体运行时通过 `ToolCall` 结构管理所有工具调用操作。每个工具调用包含唯一标识符、调用名称、执行状态和结果描述。\n\n```mermaid\ngraph LR\n    UserInput[用户输入] --> AgentCore\n    AgentCore --> ToolScheduler\n    ToolScheduler --> Tool1[工具: read_file]\n    ToolScheduler --> Tool2[工具: write_file]\n    ToolScheduler --> Tool3[工具: bash]\n    Tool1 --> Result1[成功/失败]\n    Tool2 --> Result2[成功/失败]\n    Tool3 --> Result3[成功/失败]\n    Result1 --> StatsDisplay[统计显示]\n    Result2 --> StatsDisplay\n    Result3 --> StatsDisplay\n```\n\n### 工具调用数据结构\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `callId` | string | 唯一调用标识符 |\n| `name` | string | 工具名称（如 `read_file`、`agent`） |\n| `status` | ToolCallStatus | 执行状态（executing、success、error） |\n| `description` | string | 调用描述信息 |\n| `resultDisplay` | AgentResultDisplay | 子智能体结果展示（可选） |\n\n资料来源：[packages/cli/src/ui/components/messages/ToolGroupMessage.test.tsx:27-34]()\n\n### 子智能体任务\n\n当智能体调用 `agent` 工具时，运行时会创建子智能体任务。子智能体继承父智能体的上下文，可以独立执行特定任务：\n\n```typescript\n// 子智能体任务创建示例\n{\n  type: 'task_execution',\n  subagentName: 'reviewer',\n  taskDescription: 'reviewer task',\n  taskPrompt: 'Run reviewer',\n  status: 'running',\n  toolCalls: [\n    {\n      callId: 'reviewer-read-1',\n      name: 'read_file',\n      status: 'success',\n      description: 'Read file'\n    }\n  ]\n}\n```\n\n子智能体运行时保持了焦点机制，使 Ctrl+E 快捷键可以展开查看详细信息。运行中的子智能体显示为 `focused=true`，而完成的子智能体可以正常折叠。\n\n资料来源：[packages/cli/src/ui/components/messages/ToolGroupMessage.test.tsx:63-68]()\n\n## Arena 模式\n\n### Arena 选择对话框\n\nArena 是 Qwen Code 支持的多智能体对战模式。用户可以通过 Arena 选择对话框选择不同的智能体进行对比测试或对战。\n\n```mermaid\ngraph TD\n    UserOpen[打开 Arena 对话框] --> ArenaSelectDialog\n    ArenaSelectDialog --> FetchAgents[获取智能体列表]\n    FetchAgents --> FilterAgents[筛选成功状态的智能体]\n    FilterAgents --> DisplayList[显示智能体列表]\n    DisplayList --> UserSelect{用户选择}\n    UserSelect -->|选中| RunComparison[运行对比]\n    UserSelect -->|Escape| CloseDialog[关闭对话框]\n    RunComparison --> ShowResults[展示结果]\n```\n\n### 智能体选择状态\n\nArena 对话框中的每个智能体选项显示以下信息：\n\n| 显示字段 | 数据来源 | 说明 |\n|----------|----------|------|\n| 状态图标 | `statusInfo.color` / `statusInfo.text` | 根据状态着色 |\n| 执行时长 | `duration` | 任务耗时 |\n| Token 数量 | `tokens` | 消耗的 Token 数 |\n| 文件数量 | `fileCount` | 涉及的文件数 |\n| 代码变更 | `diffAdditions` / `diffDeletions` | 新增/删除行数 |\n\n资料来源：[packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx:1-22]()\n\n### 快捷键绑定\n\nArena 对话框支持以下键盘交互：\n\n| 快捷键 | 功能 |\n|--------|------|\n| `Escape` | 关闭 Arena 对话框 |\n| `P` | 切换预览视图（Show/Hide Preview） |\n| `D` | 切换详细 Diff 视图 |\n\n资料来源：[packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx:39-50]()\n\n### Arena 操作上下文\n\nArena 相关的操作通过 `UIActionsContext` 统一管理：\n\n| 方法 | 功能 |\n|------|------|\n| `openArenaDialog(type)` | 打开指定类型的 Arena 对话框 |\n| `closeArenaDialog()` | 关闭 Arena 对话框 |\n| `handleArenaModelsSelected(models)` | 处理用户选择的模型列表 |\n\n资料来源：[packages/cli/src/ui/contexts/UIActionsContext.tsx:31-33]()\n\n## 后台任务管理\n\n### 后台任务对话框\n\nBackgroundTasksDialog 组件负责展示和管理后台运行的智能体任务，包括长时间运行的任务、监控事件和会话状态。\n\n```mermaid\ngraph TD\n    Entry[任务条目] --> CheckStatus{状态检查}\n    CheckStatus -->|有错误| ShowError[显示错误信息]\n    CheckStatus -->|有警告| ShowWarning[显示警告信息]\n    CheckStatus -->|正常| CheckTopics{有主题?}\n    CheckTopics -->|是| ShowTopics[显示触及的主题]\n    CheckTopics -->|否| CheckProgress{有进度?}\n    CheckProgress -->|是| ShowProgress[显示进度文本]\n    ShowTopics --> DisplaySummary[显示摘要]\n    ShowProgress --> DisplaySummary\n    ShowWarning --> DisplaySummary\n```\n\n### 任务状态展示\n\n| 组件 | 显示内容 | 样式 |\n|------|----------|------|\n| 状态文本 | 状态描述文字 | 根据状态着色 |\n| Sessions reviewing | 活跃会话数 | 加粗、次要颜色 |\n| Progress | 进度文本 | 单独区块 |\n| Topics touched | 涉及的主题列表 | 缩进列表形式 |\n| Error | 错误信息 | 红色高亮 |\n| Lock release warning | 锁释放警告 | 黄色警告色 |\n\n资料来源：[packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx:1-80]()\n\n### 锁释放错误处理\n\n当任务执行过程中出现锁释放错误时，系统会显示专门的警告信息：\n\n```\nLock release warning: <错误描述>\nSubsequent dreams may be skipped as locked until the next session's staleness sweep cleans the file.\n```\n\n这种设计确保终端状态保持为\"已完成\"，同时通过警告形式解释后续任务可能被跳过的原因。\n\n资料来源：[packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx:37-50]()\n\n## 监控器系统\n\n### 监控通知机制\n\n智能体运行时支持监控器（Monitor）功能，用于追踪长时间运行的任务和事件流。监控通知通过 XML 格式的回调函数传递：\n\n```typescript\ntype MonitorNotificationCallback = (\n  displayText: string,        // 显示给用户的文本\n  modelText: string,          // 模型原始文本\n  meta: {\n    monitorId: string;        // 监控器 ID\n    toolUseId?: string;       // 关联的工具调用 ID\n    status: 'running' | 'completed' | 'failed' | 'cancelled';\n    eventCount: number;       // 事件计数\n  }\n) => void;\n```\n\n### 监控通知 XML 格式\n\n```xml\n<task-notification>\n  <task-id>mon_1</task-id>\n  <kind>monitor</kind>\n  <status>running</status>\n  <summary>Monitor emitted event #1.</summary>\n  <result>ready</result>\n</task-notification>\n```\n\n### 监控器生命周期\n\n| 状态 | 含义 |\n|------|------|\n| `running` | 监控器正在运行，持续接收事件 |\n| `completed` | 监控任务已完成 |\n| `failed` | 监控执行失败 |\n| `cancelled` | 监控被用户取消 |\n\n资料来源：[packages/cli/src/nonInteractiveCli.test.ts:1-50]()\n\n## 性能统计\n\n### 统计信息显示\n\nStatsDisplay 组件展示智能体运行时的性能指标：\n\n| 指标类别 | 具体指标 | 说明 |\n|----------|----------|------|\n| **代码变更** | totalLinesAdded / totalLinesRemoved | 新增和删除的代码行数 |\n| **时间统计** | Wall Time | 墙上时钟时间 |\n| | Agent Active Time | 智能体活跃时间 |\n| | API Time | API 调用耗时及占比 |\n| | Tool Time | 工具执行耗时及占比 |\n| **缓存效率** | totalCachedTokens | 缓存的 Token 总数 |\n| | cacheEfficiency | 缓存命中率 |\n\n资料来源：[packages/cli/src/ui/components/StatsDisplay.tsx:1-50]()\n\n### 百分比计算\n\n性能统计中的百分比通过以下公式计算：\n\n```\napiTimePercent = (totalApiTime / agentActiveTime) × 100\ntoolTimePercent = (totalToolTime / agentActiveTime) × 100\ncacheEfficiency = (cachedTokens / totalTokens) × 100\n```\n\n## 权限与安全\n\n### 权限流程\n\n智能体运行时通过 PermissionFlow 模块管理工具调用的权限请求。当智能体尝试执行受限操作（如文件写入、终端命令）时，系统会弹出权限请求对话框。\n\n| 权限模式 | 说明 |\n|----------|------|\n| 授权所有 | 自动批准所有权限请求 |\n| 逐个确认 | 每个权限请求都需要用户确认 |\n| 拒绝所有 | 拒绝所有权限请求 |\n\n资料来源：[packages/core/src/core/permissionFlow.ts]()\n\n### 设置作用域\n\n权限和其他设置支持两种作用域：\n\n| 作用域 | 说明 |\n|--------|------|\n| `project` | 项目级别设置（`.qwen/` 目录） |\n| `user` | 用户级别设置（`~/.qwen/` 目录） |\n\n## 配置与扩展\n\n### MCP 服务器集成\n\n智能体运行时支持 MCP（Model Context Protocol）服务器扩展。运行时通过 `mcpServers` 配置连接外部工具服务：\n\n| 配置项 | 说明 |\n|--------|------|\n| `path` | MCP 服务器路径 |\n| `source` | 安装来源 |\n| `commands` | 可用命令列表 |\n| `status` | 连接状态（connected/disconnected） |\n\n资料来源：[packages/cli/src/ui/components/extensions/steps/ExtensionDetailStep.tsx:1-40]()\n\n### MCP 服务器状态处理\n\n当存在断开的 MCP 服务器时，系统显示提示信息：\n\n```\n※ Run qwen --debug to see error logs\n```\n\n资料来源：[packages/cli/src/ui/components/mcp/steps/ServerListStep.tsx:1-30]()\n\n## 总结\n\n智能体运行时是 Qwen Code 系统的核心执行引擎，它协调管理智能体的生命周期、任务调度、工具调用、权限控制和状态监控。该系统通过以下特性提供可靠的 AI 编程辅助体验：\n\n- **状态驱动**：清晰的状态模型支持 UI 层实时反映任务执行状态\n- **工具调度**：统一的工具调度器管理所有工具调用和子智能体任务\n- **Arena 模式**：支持多智能体对比和协作\n- **后台任务**：长时间运行任务的后台管理，减少对主界面的干扰\n- **监控通知**：实时事件通知机制，支持长时间任务的追踪\n- **性能统计**：详细的运行时性能指标，帮助用户了解资源消耗\n\n---\n\n<a id='tool-system'></a>\n\n## 工具系统\n\n### 相关页面\n\n相关主题：[智能体运行时](#agent-runtime)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx)\n- [packages/cli/src/ui/components/extensions/steps/ExtensionDetailStep.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/extensions/steps/ExtensionDetailStep.tsx)\n- [packages/cli/src/ui/components/mcp/steps/ToolListStep.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/mcp/steps/ToolListStep.tsx)\n- [packages/cli/src/ui/components/views/McpStatus.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/views/McpStatus.tsx)\n- [packages/cli/src/ui/components/arena/ArenaCards.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/arena/ArenaCards.tsx)\n- [packages/cli/src/ui/components/views/ContextUsage.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/views/ContextUsage.tsx)\n- [packages/cli/src/ui/keyMatchers.test.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/keyMatchers.test.ts)\n- [packages/cli/src/ui/components/subagents/create/CreationSummary.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/subagents/create/CreationSummary.tsx)\n</details>\n\n# 工具系统\n\n## 概述\n\nQwen Code 的工具系统是整个代码智能助手的核心能力模块，它为 AI Agent 提供了与代码库、文件系统、外部服务交互的能力。该系统支持多种类型的工具调用，包括内置工具（如 Shell 执行、文件编辑、LSP 通信）、MCP（Model Context Protocol）服务器工具以及子代理（Subagent）自定义工具。\n\n工具系统在 UI 层通过 `ToolListStep` 组件呈现交互式列表界面，支持工具搜索、选择、滚动浏览等功能。同时，工具使用情况会在 `ContextUsage` 组件中单独统计，显示每个工具消耗的 token 数量。资料来源：[packages/cli/src/ui/components/mcp/steps/ToolListStep.tsx:1-80](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/mcp/steps/ToolListStep.tsx)，[packages/cli/src/ui/components/views/ContextUsage.tsx:1-100](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/views/ContextUsage.tsx)\n\n---\n\n## 架构设计\n\n### 系统分层\n\n工具系统采用分层架构设计，从底层到上层依次为：\n\n```mermaid\ngraph TD\n    A[工具定义层] --> B[工具注册层]\n    B --> C[工具执行层]\n    C --> D[UI 展示层]\n    \n    A1[内置工具<br/>Shell/Edit/LSP] --> A\n    A2[MCP 服务器工具] --> A\n    A3[子代理自定义工具] --> A\n```\n\n### 工具分类\n\n根据工具的来源和用途，系统中的工具可分为以下几类：\n\n| 类别 | 说明 | 典型示例 |\n|------|------|----------|\n| 内置工具 | 系统核心能力，硬编码实现 | Shell、Edit、LSP |\n| MCP 工具 | 通过 MCP 协议扩展的工具 | 文件系统、Git、数据库等 |\n| 子代理工具 | 用户自定义子代理暴露的工具 | 用户定义的各类能力 |\n| 技能工具 | 预定义的技能集成 | 代码搜索、测试生成等 |\n\n资料来源：[packages/cli/src/ui/components/subagents/create/CreationSummary.tsx:1-50](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/subagents/create/CreationSummary.tsx)\n\n---\n\n## 工具注册机制\n\n### 工具注册表\n\n工具通过注册表模式进行统一管理，确保工具的可用性、唯一性和可发现性。注册表维护了所有已注册工具的元数据，包括工具名称、描述、参数模式和有效性状态。\n\n### 工具验证\n\n每个工具在注册时都会经过验证流程：\n\n```mermaid\ngraph LR\n    A[工具注册] --> B{参数校验}\n    B -->|通过| C[标记有效]\n    B -->|失败| D[标记无效<br/>记录原因]\n    C --> E[可用]\n    D --> F[禁用显示警告]\n```\n\n工具的有效性状态直接影响其在 UI 中的展示方式：\n\n```tsx\n// 工具列表中无效工具的显示逻辑\n{!tool.isValid && (\n  <Text color={theme.status.warning}>\n    {t('invalid: {{reason}}', {\n      reason: tool.invalidReason || t('unknown'),\n    })}\n  </Text>\n)}\n```\n\n资料来源：[packages/cli/src/ui/components/mcp/steps/ToolListStep.tsx:45-52](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/mcp/steps/ToolListStep.tsx)\n\n---\n\n## 内置工具\n\n### Shell 工具\n\nShell 工具提供了在宿主系统上执行命令的能力，是 AI Agent 与操作系统交互的主要通道。\n\n### Edit 工具\n\nEdit 工具负责文件内容的读取、创建、修改和删除操作，是代码修改的核心能力。\n\n### LSP 工具\n\nLSP（Language Server Protocol）工具集成了语言服务器协议，提供了代码补全、跳转到定义、查找引用等 IDE 级别的功能。\n\n---\n\n## MCP 工具集成\n\n### MCP 协议概述\n\nMCP（Model Context Protocol）是一种标准化的工具扩展协议，允许第三方服务通过标准接口向 Qwen Code 提供工具能力。\n\n### MCP 服务器配置\n\nMCP 服务器在 `ExtensionDetailStep` 组件中展示，包括以下配置项：\n\n| 配置项 | 说明 |\n|--------|------|\n| `name` | 服务器名称 |\n| `version` | 服务器版本 |\n| `path` | 服务器路径 |\n| `source` | 安装来源 |\n| `mcpServers` | 包含的服务器列表 |\n\n```tsx\n{ext.mcpServers && Object.keys(ext.mcpServers).length > 0 && (\n  <Box>\n    <Box width={LABEL_WIDTH} flexShrink={0}>\n      <Text color={theme.text.primary}>{t('MCP Servers:')}</Text>\n    </Box>\n    <Text>{Object.keys(ext.mcpServers).join(', ')}</Text>\n  </Box>\n)}\n```\n\n资料来源：[packages/cli/src/ui/components/extensions/steps/ExtensionDetailStep.tsx:30-45](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/extensions/steps/ExtensionDetailStep.tsx)\n\n### MCP 工具使用\n\n在 Agent Arena 界面中，MCP 工具的使用情况会详细展示：\n\n```tsx\n{agent.toolCalls > 0 && (\n  <Text color={theme.text.secondary}>\n    {agent.toolCalls === 1 ? '1 tool call)' : `${agent.toolCalls} tool calls)`}\n  </Text>\n)}\n```\n\n资料来源：[packages/cli/src/ui/components/arena/ArenaCards.tsx:1-50](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/arena/ArenaCards.tsx)\n\n---\n\n## 子代理工具\n\n### 子代理定义\n\n子代理是用户自定义的 AI Agent，具备独立的系统提示、工具集和描述信息。\n\n### 子代理工具配置\n\n创建子代理时可以为其配置以下工具属性：\n\n```tsx\n<Box>\n  <Text color={theme.text.primary}>{t('Tools: ')}</Text>\n  <Text>{toolsDisplay}</Text>\n</Box>\n```\n\n子代理支持选择性地启用或禁用特定工具，工具配置存储在子代理定义文件中，位于项目级（`.qwen/agents/`）或用户级（`~/.qwen/agents/`）目录。资料来源：[packages/cli/src/ui/components/subagents/create/CreationSummary.tsx:15-25](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/subagents/create/CreationSummary.tsx)\n\n---\n\n## 工具展示界面\n\n### 工具列表视图\n\n`ToolListStep` 组件提供了交互式工具列表界面：\n\n| 功能 | 说明 |\n|------|------|\n| 工具名称显示 | 固定宽度列，支持截断显示 |\n| 选择指示器 | `❯` 符号标识当前选中 |\n| 无效警告 | 显示工具验证失败的原因 |\n| 滚动提示 | 显示当前索引和总数 |\n| 键盘导航 | 支持上下箭头选择 |\n\n```tsx\n// 滚动提示的显示逻辑\n{tools.length > VISIBLE_TOOLS_COUNT && (\n  <Box marginTop={1}>\n    <Text color={theme.text.secondary}>\n      {scrollOffset > 0 ? '↑ ' : '  '}\n      {t('{{current}}/{{total}}', {\n        current: (selectedIndex + 1).toString(),\n        total: tools.length.toString(),\n      })}\n      {scrollOffset + VISIBLE_TOOLS_COUNT < tools.length ? ' ↓' : ''}\n    </Text>\n  </Box>\n)}\n```\n\n资料来源：[packages/cli/src/ui/components/mcp/steps/ToolListStep.tsx:65-78](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/mcp/steps/ToolListStep.tsx)\n\n### MCP 状态视图\n\n`McpStatus` 组件展示了 MCP 工具的详细使用说明：\n\n```tsx\n<Text>- {t('Use')} <Text color={theme.text.accent}>/mcp</Text> {t('to list all available tools')}</Text>\n<Text>- {t('Use')} <Text color={theme.text.accent}>/mcp schema</Text> {t('to show tool parameter schemas')}</Text>\n<Text>- {t('Use')} <Text color={theme.text.accent}>/mcp nodesc</Text> {t('to hide descriptions')}</Text>\n<Text>- {t('Use')} <Text color={theme.text.accent}>/mcp auth &lt;server-name&gt;</Text> {t('to authenticate with OAuth-enabled servers')}</Text>\n```\n\n资料来源：[packages/cli/src/ui/components/views/McpStatus.tsx:1-30](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/views/McpStatus.tsx)\n\n### 上下文使用统计\n\n`ContextUsage` 组件将工具使用情况纳入上下文统计：\n\n```tsx\n{/* MCP Tools detail */}\n{sortedMcpTools.length > 0 && (\n  <Box flexDirection=\"column\" marginTop={1}>\n    <Text bold color={theme.text.primary}>\n      {t('MCP tools')}\n    </Text>\n    {sortedMcpTools.map((tool) => (\n      <DetailRow\n        key={tool.name}\n        name={tool.name}\n        tokens={tool.tokens}\n      />\n    ))}\n  </Box>\n)}\n```\n\n资料来源：[packages/cli/src/ui/components/views/ContextUsage.tsx:40-55](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/views/ContextUsage.tsx)\n\n---\n\n## 键盘快捷键\n\n工具系统支持以下键盘快捷键操作：\n\n| 快捷键 | 功能 |\n|--------|------|\n| `Ctrl+T` | 切换工具描述显示/隐藏 |\n| `Ctrl+G` | 切换 IDE 上下文详情 |\n| `↑/↓` | 导航工具列表 |\n| `Escape` | 关闭工具对话框 |\n| `Tab` 或 `Enter` | 接受工具建议 |\n\n```ts\n[Command.TOGGLE_TOOL_DESCRIPTIONS]: (key: Key) =>\n  key.ctrl && key.name === 't',\n[Command.TOGGLE_IDE_CONTEXT_DETAIL]: (key: Key) =>\n  key.ctrl && key.name === 'g',\n```\n\n资料来源：[packages/cli/src/ui/keyMatchers.test.ts:1-50](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/keyMatchers.test.ts)\n\n---\n\n## Arena 场景中的工具使用\n\n在 Agent Arena 对比场景中，工具使用情况会被详细记录和展示：\n\n```mermaid\ngraph LR\n    A[Agent 执行] --> B[工具调用]\n    B --> C{工具类型}\n    C -->|Shell| D[命令执行]\n    C -->|Edit| E[文件修改]\n    C -->|MCP| F[外部服务]\n    \n    D --> G[统计面板]\n    E --> G\n    F --> G\n```\n\nArena 界面展示每个 Agent 的工具调用统计：\n\n- **工具调用次数**：显示每个 Agent 执行了多少次工具调用\n- **Token 效率**：统计总 token 消耗和运行时长\n- **Diff 统计**：显示代码变更的行数（新增/删除）\n\n```tsx\n<Box flexDirection=\"column\">\n  <Text bold color={theme.text.primary}>\n    Token Efficiency:\n  </Text>\n  {agents.map((agent, index) => (\n    <Box key={agent.label} marginLeft={2}>\n      <Text color={theme.text.secondary}>\n        {index === agents.length - 1 ? '└─' : '├─'} {agent.label}:{' '}\n      </Text>\n      <Text color={theme.text.primary}>\n        {agent.totalTokens.toLocaleString()} tokens · runtime {formatDuration(agent.durationMs)}\n      </Text>\n    </Box>\n  ))}\n</Box>\n```\n\n资料来源：[packages/cli/src/ui/components/arena/ArenaCards.tsx:50-70](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/arena/ArenaCards.tsx)\n\n---\n\n## 扩展性设计\n\n### 工具扩展点\n\n工具系统设计了多个扩展点以支持第三方集成：\n\n1. **MCP 服务器插件**：通过 MCP 协议接入外部工具服务\n2. **子代理自定义**：用户可定义专属工具集\n3. **内置工具扩展**：系统内置工具支持扩展配置\n\n### 错误处理\n\n工具执行过程中的错误会通过统一的错误展示界面呈现：\n\n```tsx\n{hasError && (\n  <Fragment>\n    <Box />\n    <Box>\n      <Text bold color={theme.status.error}>\n        {t('Error')}\n      </Text>\n    </Box>\n    <Box>\n      <Text color={theme.status.error} wrap=\"wrap\">\n        {entry.error}\n      </Text>\n    </Box>\n  </Fragment>\n)}\n```\n\n---\n\n## 配置管理\n\n### 工具配置文件\n\n工具系统的配置通过以下位置管理：\n\n| 配置位置 | 范围 | 说明 |\n|----------|------|------|\n| `.qwen/agents/` | 项目级 | 项目专属工具配置 |\n| `~/.qwen/agents/` | 用户级 | 全局工具配置 |\n\n### 工具描述控制\n\n工具描述的显示可通过命令行参数控制：\n\n- `/mcp` - 列出所有可用工具\n- `/mcp schema` - 显示工具参数模式\n- `/mcp nodesc` - 隐藏工具描述\n- `Ctrl+T` - 切换工具描述显示\n\n---\n\n## 总结\n\nQwen Code 的工具系统采用了模块化、分层式的架构设计，通过统一的注册机制管理内置工具、MCP 工具和子代理工具。系统提供了丰富的 UI 组件用于工具的展示、选择和统计，同时支持通过键盘快捷键进行高效操作。工具系统的扩展性设计使得第三方服务能够方便地通过 MCP 协议接入，为 AI Agent 提供更强大的能力。\n\n---\n\n<a id='model-integration'></a>\n\n## 模型集成\n\n### 相关页面\n\n相关主题：[智能体运行时](#agent-runtime), [快速入门](#quick-start)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/src/core/openaiContentGenerator/openaiContentGenerator.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/core/openaiContentGenerator/openaiContentGenerator.ts)\n- [packages/core/src/core/openaiContentGenerator/provider/dashscope.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/core/openaiContentGenerator/provider/dashscope.ts)\n- [packages/core/src/core/openaiContentGenerator/provider/openrouter.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/core/openaiContentGenerator/provider/openrouter.ts)\n- [packages/core/src/core/geminiChat.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/core/geminiChat.ts)\n- [packages/core/src/core/anthropicContentGenerator/anthropicContentGenerator.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/core/anthropicContentGenerator/anthropicContentGenerator.ts)\n- [README.md](https://github.com/QwenLM/qwen-code/blob/main/README.md)\n- [packages/core/src/memory/extractionAgentPlanner.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/memory/extractionAgentPlanner.ts)\n</details>\n\n# 模型集成\n\n## 概述\n\n模型集成是 Qwen Code 框架的核心子系统，负责与各类大语言模型（LLM）提供商建立通信连接、发送请求并处理响应。该系统通过统一的内容生成器接口抽象不同提供商的实现细节，使上层业务逻辑能够以一致的方式调用各种模型服务。资料来源：[packages/core/src/core/openaiContentGenerator/openaiContentGenerator.ts]()\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n    A[业务层] --> B[ContentGenerator 接口]\n    B --> C[OpenAI ContentGenerator]\n    B --> D[Anthropic ContentGenerator]\n    B --> E[Gemini Chat]\n    C --> F[Provider 层]\n    F --> G[DashScope Provider]\n    F --> H[OpenRouter Provider]\n    F --> I[OpenAI Compatible Provider]\n```\n\n### 核心接口抽象\n\n系统定义了统一的内容生成器接口，所有具体实现必须遵循该契约：\n\n| 接口方法 | 功能描述 | 参数 |\n|---------|---------|------|\n| `generate(prompt, options)` | 生成内容 | 提示词、生成配置 |\n| `stream(prompt, options)` | 流式生成 | 提示词、生成配置 |\n| `getModel()` | 获取当前模型 | 无 |\n| `getName()` | 获取生成器名称 | 无 |\n\n资料来源：[packages/core/src/core/openaiContentGenerator/openaiContentGenerator.ts:30-80]()\n\n## Provider 实现体系\n\n### DashScope Provider（阿里云）\n\nDashScope 是阿里云提供的大模型服务，Qwen Code 通过专门的 Provider 进行集成：\n\n```typescript\n// packages/core/src/core/openaiContentGenerator/provider/dashscope.ts\nexport class DashScopeProvider implements ModelProvider {\n  readonly baseUrl = 'https://dashscope.aliyuncs.com/compatible-mode/v1';\n  \n  async chat(params: ChatParams): Promise<ChatResponse> {\n    // 实现与阿里云 DashScope API 的通信\n  }\n}\n```\n\n**配置示例：**\n\n```json\n{\n  \"modelProviders\": {\n    \"openai\": [\n      {\n        \"id\": \"qwen3.6-plus\",\n        \"name\": \"qwen3.6-plus (Coding Plan)\",\n        \"baseUrl\": \"https://coding.dashscope.aliyuncs.com/v1\",\n        \"description\": \"qwen3.6-plus from ModelStudio Coding Plan\",\n        \"envKey\": \"BAILIAN_CODING_PLAN_API_KEY\"\n      }\n    ]\n  }\n}\n```\n\n资料来源：[packages/core/src/core/openaiContentGenerator/provider/dashscope.ts]()\n\n### OpenRouter Provider\n\nOpenRouter 提供对多种模型的统一访问接口：\n\n```typescript\n// packages/core/src/core/openaiContentGenerator/provider/openrouter.ts\nexport class OpenRouterProvider implements ModelProvider {\n  readonly baseUrl = 'https://openrouter.ai/api/v1';\n  \n  async chat(params: ChatParams): Promise<ChatResponse> {\n    // 实现与 OpenRouter API 的通信\n  }\n}\n```\n\n资料来源：[packages/core/src/core/openaiContentGenerator/provider/openrouter.ts]()\n\n### OpenAI 兼容 Provider\n\n通用的 OpenAI API 兼容实现，可连接任何遵循 OpenAI API 规范的服务：\n\n```mermaid\ngraph LR\n    A[请求] --> B[OpenAI Compatible Provider]\n    B --> C{目标服务}\n    C --> D[本地部署模型]\n    C --> E[vLLM]\n    C --> F[Ollama]\n    C --> G[其他兼容服务]\n```\n\n**vLLM 配置示例：**\n\n```json\n{\n  \"modelProviders\": {\n    \"openai\": [\n      {\n        \"id\": \"Qwen/Qwen3-32B\",\n        \"name\": \"Qwen3 32B (vLLM)\",\n        \"baseUrl\": \"http://localhost:8000/v1\",\n        \"description\": \"Qwen3 32B running locally via vLLM\",\n        \"generationConfig\": {\n          \"contextWindowSize\": 131072\n        }\n      }\n    ]\n  }\n}\n```\n\n**Ollama 配置示例：**\n\n```json\n{\n  \"modelProviders\": {\n    \"openai\": [\n      {\n        \"id\": \"qwen3:32b\",\n        \"name\": \"Qwen3 32B (Ollama)\",\n        \"baseUrl\": \"http://localhost:11434/v1\",\n        \"description\": \"Qwen3 32B running locally via Ollama\",\n        \"generationConfig\": {\n          \"contextWindowSize\": 131072\n        }\n      }\n    ]\n  }\n}\n```\n\n资料来源：[README.md:50-120]()\n\n## Anthropic Claude 集成\n\n### 内容生成器实现\n\nAnthropic Claude 通过专门的内容生成器进行集成：\n\n```typescript\n// packages/core/src/core/anthropicContentGenerator/anthropicContentGenerator.ts\nexport class AnthropicContentGenerator implements ContentGenerator {\n  private readonly client: Anthropic;\n  \n  async generate(\n    prompt: string,\n    options?: GenerationOptions\n  ): Promise<GenerationResult> {\n    const message = await this.client.messages.create({\n      model: this.model,\n      max_tokens: options?.maxTokens ?? 4096,\n      messages: [{ role: 'user', content: prompt }],\n    });\n    \n    return {\n      content: message.content[0].text,\n      usage: {\n        inputTokens: message.usage.input_tokens,\n        outputTokens: message.usage.output_tokens,\n      },\n    };\n  }\n}\n```\n\n### 特性支持\n\n| 特性 | 支持状态 | 说明 |\n|-----|---------|------|\n| 标准生成 | ✅ 支持 | 基础文本生成能力 |\n| 流式输出 | ✅ 支持 | 支持 Server-Sent Events |\n| Thinking Mode | ✅ 支持 | Claude 3.7+ 支持思考模式 |\n| Tool Use | 🔄 计划中 | 工具调用功能 |\n\n资料来源：[packages/core/src/core/anthropicContentGenerator/anthropicContentGenerator.ts]()\n\n## Google Gemini 集成\n\n### 聊天实现\n\nGemini 通过专门的聊天模块进行集成：\n\n```typescript\n// packages/core/src/core/geminiChat.ts\nexport class GeminiChat {\n  private readonly model: GenerativeModel;\n  \n  async generateContent(\n    prompt: string,\n    config?: GenerationConfig\n  ): Promise<GenerateContentResult> {\n    const result = await this.model.generateContent(prompt);\n    return result;\n  }\n  \n  async streamGenerateContent(\n    prompt: string,\n    config?: GenerationConfig\n  ): Promise<AsyncIterable<string>> {\n    const result = await this.model.generateContentStream(prompt);\n    // 返回流式响应\n  }\n}\n```\n\n资料来源：[packages/core/src/core/geminiChat.ts]()\n\n## 配置管理\n\n### 配置文件结构\n\n模型集成通过 `~/.qwen/settings.json` 进行统一配置：\n\n```json\n{\n  \"modelProviders\": {\n    \"openai\": [...],\n    \"anthropic\": {\n      \"apiKey\": \"sk-...\"\n    },\n    \"google\": {\n      \"apiKey\": \"...\"\n    }\n  },\n  \"security\": {\n    \"auth\": {\n      \"selectedType\": \"openai\"\n    }\n  },\n  \"model\": {\n    \"name\": \"qwen3:32b\"\n  }\n}\n```\n\n### 模型切换\n\n用户可以通过 `/model` 命令在运行时切换不同模型：\n\n```bash\nqwen\n> /model qwen3.6-plus\n```\n\n资料来源：[README.md:100-150]()\n\n## 请求处理流程\n\n### 标准生成流程\n\n```mermaid\nsequenceDiagram\n    participant U as 用户\n    participant G as ContentGenerator\n    participant P as Provider\n    participant API as 外部API\n    \n    U->>G: generate(prompt, options)\n    G->>P: chat(params)\n    P->>API: HTTP POST /chat/completions\n    API-->>P: Response\n    P-->>G: ChatResponse\n    G-->>U: GenerationResult\n```\n\n### 错误处理\n\n| 错误类型 | 处理策略 | 重试机制 |\n|---------|---------|---------|\n| 网络超时 | 自动重试 | 3次指数退避 |\n| Rate Limit | 等待后重试 | 尊重 Retry-After |\n| 认证失败 | 提示用户 | 无重试 |\n| 服务不可用 | 切换 Provider | 如配置多 Provider |\n\n资料来源：[packages/core/src/core/openaiContentGenerator/openaiContentGenerator.ts:100-150]()\n\n## 与记忆系统的集成\n\n模型集成与记忆系统深度协作，支持上下文管理和持久化：\n\n```typescript\n// packages/core/src/memory/extractionAgentPlanner.ts\nasync function buildTopicSummaryBlock(projectRoot: string): Promise<string> {\n  const docs = await scanAutoMemoryTopicDocuments(projectRoot);\n  return docs.map((doc) => {\n    return [\n      `- [${doc.title}](${doc.relativePath})`,\n      `  topic=${doc.type}`,\n      `  current=${doc.body}`,\n    ].join('\\n');\n  }).join('\\n\\n');\n}\n```\n\n资料来源：[packages/core/src/memory/extractionAgentPlanner.ts:20-60]()\n\n## 总结\n\n模型集成模块是 Qwen Code 连接各类大语言模型服务的桥梁，通过标准化的 Provider 接口设计，系统能够灵活支持多种模型提供商，包括阿里云 DashScope、OpenRouter、OpenAI 兼容接口、Google Gemini 和 Anthropic Claude 等。该设计遵循开闭原则，便于后续扩展新的模型提供商。\n\n---\n\n<a id='memory-system'></a>\n\n## 记忆系统\n\n### 相关页面\n\n相关主题：[会话管理](#session-management), [技能与钩子系统](#skills-hooks)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/src/memory/manager.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/memory/manager.ts)\n- [packages/core/src/memory/recall.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/memory/recall.ts)\n- [packages/core/src/memory/extract.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/memory/extract.ts)\n- [packages/core/src/memory/indexer.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/memory/indexer.ts)\n- [packages/core/src/memory/dream.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/memory/dream.ts)\n- [packages/core/src/memory/prompt.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/memory/prompt.ts)\n- [packages/core/src/telemetry/metrics.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/telemetry/metrics.ts)\n</details>\n\n# 记忆系统\n\n## 概述\n\n记忆系统是 Qwen Code 的核心组件之一，负责在 AI 与用户的交互过程中自动捕获、存储和检索有用的上下文信息。该系统通过智能记忆提取、定期梦境整理和上下文召回三大机制，帮助 AI 保持对项目、用户偏好、外部系统引用等长期信息的感知能力。\n\n记忆系统的主要目标包括：\n\n- **减少重复信息传递**：用户无需反复告知 AI 相同的背景信息\n- **维护项目上下文**：保存项目相关的架构决策、外部依赖和重要约定\n- **个性化体验**：记住用户的偏好和工作习惯\n- **外部系统追踪**：记录对外部系统（如 Linear、Grafana）的引用关系\n\n资料来源：[packages/core/src/memory/prompt.ts:1-50]()\n\n## 系统架构\n\n记忆系统采用分层架构，包含五个核心模块，各模块职责分明、协同工作。\n\n```mermaid\ngraph TD\n    subgraph 记忆系统架构\n        A[记忆管理器<br/>manager.ts] --> B[提取模块<br/>extract.ts]\n        A --> C[召回模块<br/>recall.ts]\n        A --> D[梦境模块<br/>dream.ts]\n        A --> E[索引模块<br/>indexer.ts]\n    end\n    \n    subgraph 外部交互\n        E --> F[记忆存储<br/>文件系统]\n        F --> C\n        B --> G[对话历史]\n        D --> F\n    end\n    \n    style A fill:#e1f5fe\n    style F fill:#fff3e0\n```\n\n### 组件职责矩阵\n\n| 模块 | 文件 | 主要职责 |\n|------|------|----------|\n| manager.ts | 记忆管理器 | 协调各模块、初始化、配置管理 |\n| extract.ts | 提取模块 | 从对话中识别并提取需要记忆的信息 |\n| recall.ts | 召回模块 | 根据上下文检索相关记忆 |\n| dream.ts | 梦境模块 | 定期整理和强化记忆 |\n| indexer.ts | 索引模块 | 管理记忆文件的索引和元数据 |\n\n资料来源：[packages/core/src/memory/manager.ts](), [packages/core/src/memory/indexer.ts]()\n\n## 核心功能模块\n\n### 1. 记忆提取（Extract）\n\n记忆提取模块负责从对话历史中自动识别有价值的信息片段。该模块通过专门的提示词工程（Prompt Engineering）引导 AI 理解何时应该保存记忆、保存什么类型的信息。\n\n#### 提取的记忆类型\n\n根据 prompt.ts 中的定义，系统将记忆分为以下几类：\n\n```mermaid\ngraph LR\n    subgraph 记忆分类\n        A[user] --> E[用户偏好]\n        B[feedback] --> F[反馈信息]\n        C[project] --> G[项目信息]\n        D[reference] --> H[外部引用]\n    end\n    \n    style E fill:#c8e6c9\n    style F fill:#ffe0b2\n    style G fill:#bbdefb\n    style H fill:#e1bee7\n```\n\n**用户偏好（user/）**：存储用户的个人偏好、工作习惯和配置选择\n\n**反馈信息（feedback/）**：记录用户对 AI 回复的纠正和调整\n\n**项目信息（project/）**：保存项目相关的架构决策、技术选型和重要约定\n\n**外部引用（reference/）**：追踪对外部系统的引用（如缺陷追踪系统、监控系统）\n\n资料来源：[packages/core/src/memory/prompt.ts:1-80]()\n\n#### 提取时机与策略\n\n系统仅在特定情况下触发记忆提取：\n\n- **外部系统引用**：当用户提到 bugs 在 Linear 中跟踪或反馈在某个 Slack 频道时\n- **架构决策**：当用户描述项目的技术选型或设计模式时\n- **配置变更**：当用户修改了项目配置或工具设置时\n\n提取模块遵循以下原则：\n\n- 仅保存非显而易见的长期信息\n- 不保存代码模式、文件路径等可从代码库推导的内容\n- 不保存 Git 历史或调试解决方案（这些可通过 git log 等命令获取）\n- 保持每类记忆的唯一性，避免重复\n\n资料来源：[packages/core/src/memory/prompt.ts:85-100]()\n\n### 2. 记忆召回（Recall）\n\n召回模块是记忆系统的\"读取\"端，负责在需要时检索相关记忆。\n\n#### 召回流程\n\n```mermaid\nsequenceDiagram\n    participant AI as AI 代理\n    participant Recall as 召回模块\n    participant Index as 索引模块\n    participant Storage as 记忆存储\n    \n    AI->>Recall: 请求召回相关记忆\n    Recall->>Index: 查询索引\n    Index-->>Recall: 返回记忆文件列表\n    Recall->>Storage: 读取记忆内容\n    Storage-->>Recall: 返回记忆内容\n    Recall-->>AI: 提供相关上下文\n```\n\n#### 召回触发场景\n\n召回机制在以下场景被激活：\n\n1. **用户消息预处理**：在处理用户输入前，先检索可能相关的记忆\n2. **上下文窗口构建**：将相关记忆注入 AI 的上下文窗口\n3. **决策参考**：当 AI 需要做出影响用户的决策时获取背景信息\n\n资料来源：[packages/core/src/memory/recall.ts](), [packages/core/src/memory/indexer.ts]()\n\n### 3. 梦境模块（Dream）\n\n梦境模块是记忆系统的维护组件，定期对记忆进行整理和强化。\n\n#### 梦境机制\n\n```mermaid\ngraph TD\n    A[定时触发] --> B{锁定记忆文件}\n    B --> C[读取所有记忆]\n    C --> D[分析记忆关联性]\n    D --> E[强化重要记忆]\n    E --> F[清理过时信息]\n    F --> G[更新索引]\n    G --> H[释放文件锁]\n    \n    style A fill:#ffecb3\n    style H fill:#c8e6c9\n```\n\n#### 梦境行为说明\n\n- **文件锁定**：防止在整理过程中被其他进程修改\n- **关联分析**：识别记忆间的关联关系，优化检索效率\n- **强化机制**：对频繁访问的记忆增加访问优先级\n- **清理机制**：移除不再相关或已被覆盖的记忆条目\n\n> 注意：梦境操作可能导致锁释放失败或元数据写入失败。锁释放失败会使后续梦境被静默跳过，元数据写入失败可能导致调度器无法获取最新运行状态。\n\n资料来源：[packages/core/src/memory/dream.ts](), [packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx:50-75]()\n\n### 4. 索引管理（Indexer）\n\n索引模块负责维护记忆文件的元数据索引，支持高效的召回查询。\n\n#### 索引结构\n\n索引文件采用 Markdown 链接格式，每行代表一个记忆条目：\n\n```markdown\n- [记忆标题](relative/path.md) — 一句话描述\n```\n\n索引遵循以下规则：\n\n- 每个记忆文件必须有对应的索引条目\n- 索引条目必须包含标题、相对路径和一句话描述\n- 创建或删除记忆文件时必须同步更新索引\n- 索引本身不是记忆，内容不直接写入\n\n资料来源：[packages/core/src/memory/extractionAgentPlanner.ts:1-30](), [packages/core/src/memory/extractionAgentPlanner.ts:35-60]()\n\n## 记忆存储结构\n\n记忆系统使用文件系统存储记忆，每个记忆类别对应一个子目录：\n\n```\n~/.qwen/memory/\n├── user/           # 用户偏好记忆\n├── feedback/       # 用户反馈记忆\n├── project/        # 项目信息记忆\n├── reference/      # 外部引用记忆\n└── index.md        # 记忆索引文件\n```\n\n### 记忆文件格式\n\n记忆文件采用 Markdown 格式，包含 YAML frontmatter 元数据：\n\n```yaml\n---\ntitle: 记忆标题\ntype: reference\nwhen_to_save: 何时应保存此记忆\nhow_to_use: 如何使用此记忆\n---\n# 记忆正文内容\n```\n\n资料来源：[packages/core/src/memory/prompt.ts:20-55]()\n\n## 遥测指标\n\n记忆系统集成了完整的遥测（Telemetry）支持，便于监控和调试。\n\n### 记忆相关指标\n\n| 指标名称 | 类型 | 描述 |\n|----------|------|------|\n| `memory.extract.count` | 计数器 | 记忆提取次数 |\n| `memory.extract.duration` | 直方图 | 记忆提取耗时 |\n| `memory.dream.count` | 计数器 | 梦境执行次数 |\n| `memory.dream.duration` | 直方图 | 梦境执行耗时 |\n| `memory.recall.count` | 计数器 | 记忆召回次数 |\n| `memory.recall.duration` | 直方图 | 记忆召回耗时 |\n\n资料来源：[packages/core/src/telemetry/metrics.ts:1-25]()\n\n### 指标属性\n\n记忆指标支持以下维度属性：\n\n- **session.id**：当前会话标识\n- **function_name**：函数名称（提取时）\n- **model**：使用的模型名称\n- **status_code**：状态码\n- **error_type**：错误类型\n\n## 配置与扩展\n\n### 记忆系统配置\n\n记忆系统通过 Config 接口集成到主配置体系：\n\n```typescript\ninterface MemoryConfig {\n  getMemoryEnabled: () => boolean;\n  getMemoryRoot: () => string;\n  getSessionId: () => string;\n}\n```\n\n### 扩展点\n\n记忆系统提供以下扩展点：\n\n1. **自定义提取器**：可扩展提取规则以支持特定类型的记忆\n2. **存储后端**：可替换文件系统存储为数据库等后端\n3. **索引策略**：可自定义索引算法以优化召回效率\n4. **调度策略**：可调整梦境执行频率和触发条件\n\n## 使用示例\n\n### 触发记忆保存\n\n```\n用户: bugs are tracked in Linear project \"INGEST\"\n助手: [saves reference memory: pipeline bugs are tracked in Linear project \"INGEST\"]\n```\n\n### 触发记忆召回\n\n```\n用户: where do we track pipeline bugs?\n助手: [recalls reference memory] → 引用之前保存的 Linear 项目信息\n```\n\n### 记忆预览\n\n在 Web UI 的 ToolCallCard 组件中，记忆操作会显示为带有 💭 图标的卡片：\n\n```tsx\nexport const ThinkingCard: Story = {\n  args: {\n    icon: '💭',\n    children: (\n      <ToolCallRow label=\"SaveMemory\">\n        <div className=\"italic opacity-90\">\n          The user wants to refactor the authentication module...\n        </div>\n      </ToolCallRow>\n    ),\n  },\n};\n```\n\n资料来源：[packages/webui/src/components/toolcalls/shared/ToolCallCard.stories.tsx:1-30]()\n\n## 常见问题与排查\n\n### 梦境被跳过（Lock Release Warning）\n\n**症状**：后台任务显示 \"Lock release warning\"，后续梦境被静默跳过\n\n**原因**：文件锁定失败导致\n\n**解决方案**：等待下一个会话的过期清理机制（staleness sweep）清理锁文件\n\n### 调度器无法获取最新状态\n\n**症状**：调度器无法检测到最新的梦境运行状态\n\n**原因**：元数据写入失败\n\n**排查方向**：\n\n- 检查文件系统权限\n- 检查磁盘空间\n- 查看日志中的具体错误信息\n\n资料来源：[packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx:55-70]()\n\n## 相关文档\n\n- [记忆系统架构设计](./architecture/memory-system.md)\n- [上下文管理](./context-management.md)\n- [工具调用扩展](./tool-extensions.md)\n- [遥测系统](./telemetry.md)\n\n---\n\n<a id='session-management'></a>\n\n## 会话管理\n\n### 相关页面\n\n相关主题：[记忆系统](#memory-system), [智能体运行时](#agent-runtime)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/src/services/sessionService.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/services/sessionService.ts)\n- [packages/core/src/services/chatCompressionService.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/services/chatCompressionService.ts)\n- [packages/core/src/services/sessionTitle.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/services/sessionTitle.ts)\n- [packages/cli/src/acp-integration/session/SubAgentTracker.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/acp-integration/session/SubAgentTracker.ts)\n- [packages/vscode-ide-companion/src/services/qwenAgentManager.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/vscode-ide-companion/src/services/qwenAgentManager.ts)\n- [packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx)\n</details>\n\n# 会话管理\n\n## 概述\n\n会话管理（Session Management）是 Qwen Code 核心系统之一，负责管理和维护用户与 AI 助手交互的所有对话历史。系统通过结构化的数据模型存储会话信息，支持会话分叉（Fork）、会话列表检索、后台任务状态跟踪等核心功能。\n\n会话数据以 JSONL（JSON Lines）格式持久化存储在项目目录的 `~/.qwen/chats/` 下，每个会话文件以会话 ID 命名，格式为 `{sessionId}.jsonl`。资料来源：[packages/core/src/services/sessionService.ts:1-50]()\n\n## 核心数据模型\n\n### ChatRecord 会话记录\n\n会话中的每条消息都被封装为 `ChatRecord` 结构，是会话持久化的基本单元：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `uuid` | `string` | 消息唯一标识符 |\n| `sessionId` | `string` | 所属会话 ID |\n| `parentUuid` | `string \\| null` | 父消息 UUID，用于构建消息链 |\n| `forkedFrom` | `ForkedFrom \\| null` | 分叉来源信息 |\n| `cwd` | `string` | 会话工作目录 |\n| `timestamp` | `number` | 消息时间戳 |\n\n资料来源：[packages/core/src/services/sessionService.ts:35-50]()\n\n### 会话元数据结构\n\n会话检索时返回的元数据结构包含以下关键字段：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | `string` | 会话唯一标识 |\n| `sessionId` | `string` | 会话 ID |\n| `title` | `string` | 会话标题 |\n| `name` | `string` | 会话名称 |\n| `startTime` | `number` | 会话开始时间 |\n| `lastUpdated` | `number` | 最后更新时间 |\n| `messageCount` | `number` | 消息总数 |\n| `projectHash` | `string` | 项目哈希值 |\n| `filePath` | `string` | 会话文件路径 |\n| `cwd` | `string` | 工作目录 |\n\n资料来源：[packages/vscode-ide-companion/src/services/qwenAgentManager.ts:30-45]()\n\n## 会话服务架构\n\n### SessionService 核心服务\n\n`SessionService` 是会话管理的核心服务类，负责：\n\n- 会话文件的读写操作\n- 会话 ID 验证与生成\n- 会话分叉（Fork）操作\n- 项目所有权验证\n\n```typescript\nclass SessionService {\n  private getChatsDir(): string;\n  private getSessionFilePath(sessionId: string): string;\n  private validateSessionId(newSessionId: string): void;\n  async forkSession(sourceSessionId: string, newSessionId: string): Promise<void>;\n}\n```\n\n资料来源：[packages/core/src/services/sessionService.ts:1-100]()\n\n### 会话文件模式验证\n\n系统使用正则表达式 `SESSION_FILE_PATTERN` 验证会话 ID 的合法性，确保文件名安全：\n\n```typescript\nSESSION_FILE_PATTERN.test(`${newSessionId}.jsonl`)\n```\n\n不合法的会话 ID 将抛出错误：`Invalid new sessionId: ${newSessionId}`\n\n资料来源：[packages/core/src/services/sessionService.ts:15-20]()\n\n## 会话分叉（Fork）\n\n### 分叉机制概述\n\n会话分叉允许从现有会话创建新会话，同时保持与原会话的消息血缘关系。分叉操作会重建父消息 UUID 链，确保新会话是原会话的线性后裔。\n\n### 分叉流程图\n\n```mermaid\ngraph TD\n    A[源会话] --> B[读取源会话记录]\n    B --> C[验证项目所有权]\n    C --> D{验证通过?}\n    D -->|否| E[抛出错误]\n    D -->|是| F[重建 parentUuid 链]\n    F --> G[设置 forkedFrom 元数据]\n    G --> H[创建新会话文件]\n    H --> I[分叉完成]\n```\n\n### forkedFrom 元数据结构\n\n分叉后的每条消息都记录其来源信息：\n\n```typescript\ninterface ForkedFrom {\n  sessionId: string;    // 来源会话 ID\n  messageUuid: string; // 来源消息 UUID\n}\n```\n\n资料来源：[packages/core/src/services/sessionService.ts:40-55]()\n\n### 分叉实现代码\n\n```typescript\nconst forked: ChatRecord[] = records.map((record) => {\n  const next: ChatRecord = {\n    ...record,\n    sessionId: newSessionId,\n    parentUuid: prevUuid,\n    forkedFrom: {\n      sessionId: sourceSessionId,\n      messageUuid: record.uuid,\n    },\n  };\n  prevUuid = record.uuid;\n  return next;\n});\n```\n\n资料来源：[packages/core/src/services/sessionService.ts:60-75]()\n\n## 会话标题管理\n\n### 标题生成服务\n\n`sessionTitle.ts` 负责为新会话生成有意义的标题。系统通过分析会话内容自动提取标题，便于用户快速识别和检索会话。\n\n### 标题生成策略\n\n- 分析首条用户消息的主题\n- 提取关键主题词作为标题\n- 支持自定义标题覆盖\n\n资料来源：[packages/core/src/services/sessionTitle.ts:1-30]()\n\n## 聊天压缩服务\n\n### 压缩机制\n\n`chatCompressionService.ts` 实现了会话历史压缩功能，当会话长度超过阈值时自动压缩早期消息，减少 token 消耗同时保留关键上下文。\n\n### 压缩触发条件\n\n| 条件 | 说明 |\n|------|------|\n| 消息数量超限 | 会话消息数达到配置阈值 |\n| Token 数量超限 | 累计 token 数超过限制 |\n\n资料来源：[packages/core/src/services/chatCompressionService.ts:1-50]()\n\n## 子代理追踪\n\n### SubAgentTracker\n\n`SubAgentTracker` 负责追踪会话中的子代理（Sub-Agent）活动。当主代理派生子代理完成任务时，跟踪器记录子代理的执行状态和结果。\n\n### 追踪数据结构\n\n```typescript\ninterface SubAgentInfo {\n  agentId: string;\n  parentAgentId: string;\n  status: 'running' | 'completed' | 'failed';\n  startTime: number;\n  endTime?: number;\n  result?: unknown;\n}\n```\n\n资料来源：[packages/cli/src/acp-integration/session/SubAgentTracker.ts:1-40]()\n\n## 后台任务与会话关联\n\n### 状态显示\n\n后台任务对话框显示与会话相关的状态信息：\n\n| 显示项 | 说明 |\n|--------|------|\n| 状态动词 | 如 Running、Completed、Failed |\n| 会话计数 | 当前正在审核的会话数 |\n| 进度文本 | 任务执行进度描述 |\n| 主题列表 | 会话涉及的主题标签 |\n\n资料来源：[packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx:20-60]()\n\n### 错误与警告展示\n\n系统会展示会话相关的错误和警告信息：\n\n- **错误状态**：显示 `entry.error` 内容\n- **锁定释放警告**：当锁定释放失败时提示后续梦境可能被跳过\n- **元数据写入警告**：Scheduler Gate 未获取最新运行的提示\n\n资料来源：[packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx:70-100]()\n\n## 会话检索机制\n\n### ACP 会话列表获取\n\n系统通过 ACP（Agent Communication Protocol）接口获取会话列表：\n\n```typescript\n// ACP 方式获取会话\nconst sessions = await acpClient.getSessions();\n\n// 文件系统方式获取（降级方案）\nconst sessions = await this.sessionReader.getAllSessions(undefined, true);\n```\n\n### 获取策略\n\n1. 优先尝试 ACP 接口获取会话列表\n2. ACP 获取失败时降级到文件系统直接读取\n3. 返回统一格式的会话元数据数组\n\n资料来源：[packages/vscode-ide-companion/src/services/qwenAgentManager.ts:20-50]()\n\n## VSCode IDE 集成\n\n### QwenAgentManager\n\nVSCode 扩展通过 `QwenAgentManager` 服务管理会话，集成以下功能：\n\n- 会话列表展示\n- 会话详情查看\n- 新会话创建\n- 会话切换\n\n### 服务初始化\n\n```typescript\nclass QwenAgentManager {\n  private sessionReader: SessionReader;\n  \n  async getAllSessions(): Promise<QwenSession[]>;\n  async getSessionById(sessionId: string): Promise<QwenSession | null>;\n}\n```\n\n资料来源：[packages/vscode-ide-companion/src/services/qwenAgentManager.ts:1-60]()\n\n## 最佳实践\n\n### 会话命名规范\n\n- 使用有意义的会话标题\n- 避免特殊字符在会话 ID 中\n- 定期清理不需要的会话文件\n\n### 会话分叉使用场景\n\n| 场景 | 建议操作 |\n|------|----------|\n| 探索不同解决方案 | 从原会话分叉 |\n| 修复错误方向 | 创建新分叉继续 |\n| A/B 测试方案 | 并行分叉对比 |\n\n### 性能优化\n\n- 及时压缩长会话减少内存占用\n- 使用项目哈希快速定位相关会话\n- 通过 `messageCount` 评估会话复杂度\n\n---\n\n<a id='skills-hooks'></a>\n\n## 技能与钩子系统\n\n### 相关页面\n\n相关主题：[工具系统](#tool-system)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/src/skills/skill-manager.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/skills/skill-manager.ts)\n- [packages/core/src/hooks/hookSystem.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/hooks/hookSystem.ts)\n- [packages/core/src/hooks/hookRegistry.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/hooks/hookRegistry.ts)\n- [packages/core/src/skills/skill-load.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/skills/skill-load.ts)\n- [packages/core/src/skills/skill-activation.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/skills/skill-activation.ts)\n</details>\n\n# 技能与钩子系统\n\n## 概述\n\n技能（Skills）与钩子（Hooks）系统是 Qwen Code 框架的核心扩展机制，旨在为 AI 编程助手提供高度模块化、可定制的功能扩展能力。技能系统允许开发者定义独立的工具集和功能模块，而钩子系统则在关键执行节点提供拦截、修改和增强行为的能力。\n\n技能与钩子系统的主要职责包括：\n\n- **动态加载**：在运行时从文件系统或远程源加载技能包\n- **生命周期管理**：管理技能的激活、停用和卸载流程\n- **事件拦截**：在工具执行、消息处理等关键节点注入自定义逻辑\n- **上下文注入**：向 AI 模型提供额外的系统提示和上下文信息\n- **错误处理增强**：通过钩子机制提供更细粒度的错误处理和恢复策略\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TB\n    subgraph \"技能层 Skill Layer\"\n        SM[技能管理器<br/>SkillManager]\n        SA[技能激活器<br/>SkillActivator]\n        SL[技能加载器<br/>SkillLoader]\n    end\n    \n    subgraph \"钩子层 Hook Layer\"\n        HS[钩子系统<br/>HookSystem]\n        HR[钩子注册表<br/>HookRegistry]\n        HP[钩子处理器<br/>HookProcessor]\n    end\n    \n    subgraph \"执行层 Execution Layer\"\n        TS[工具调度器<br/>ToolScheduler]\n        MB[消息总线<br/>MessageBus]\n    end\n    \n    subgraph \"工具层 Tool Layer\"\n        BT[内置工具<br/>BuiltinTools]\n        MCPT[MCP工具<br/>MCPTools]\n        SKT[技能工具<br/>SkillTools]\n    end\n    \n    SM --> SA\n    SL --> SM\n    SA --> TS\n    HS --> MB\n    HR --> HP\n    HP --> TS\n    BT --> TS\n    MCPT --> TS\n    SKT --> TS\n```\n\n### 技能系统架构\n\n技能系统采用管理器模式，通过 `SkillManager` 统一管理所有技能的生命周期。每个技能作为一个独立的功能单元，包含工具定义、系统提示和激活逻辑。\n\n```mermaid\ngraph LR\n    A[技能定义文件] --> B[技能加载器<br/>skill-load.ts]\n    B --> C[技能管理器<br/>skill-manager.ts]\n    C --> D[技能激活器<br/>skill-activation.ts]\n    D --> E[工具注册]\n    D --> F[上下文注入]\n    D --> G[系统提示增强]\n```\n\n### 钩子系统架构\n\n钩子系统基于发布-订阅模式，在关键执行节点注册回调函数，实现行为拦截和增强。\n\n```mermaid\ngraph TB\n    A[事件触发点] --> B{钩子类型检查}\n    B -->|预执行钩子| C[Pre-Hook]\n    B -->|后执行钩子| D[Post-Hook]\n    B -->|失败钩子| E[Failure-Hook]\n    \n    C --> F[执行前置逻辑]\n    D --> G[处理返回结果]\n    E --> H[错误处理增强]\n    \n    F --> I[继续执行]\n    G --> J[返回修改结果]\n    H --> K[返回错误上下文]\n```\n\n## 核心组件\n\n### 技能管理器 (SkillManager)\n\n技能管理器是技能系统的中央协调器，负责维护技能注册表、协调加载流程和提供统一的访问接口。\n\n| 方法/属性 | 类型 | 说明 |\n|-----------|------|------|\n| `skills` | `Map<string, Skill>` | 已注册技能集合 |\n| `register()` | `method` | 注册新技能 |\n| `unregister()` | `method` | 注销技能 |\n| `activate()` | `method` | 激活指定技能 |\n| `deactivate()` | `method` | 停用指定技能 |\n| `getActiveSkills()` | `method` | 获取当前活跃技能列表 |\n| `loadFromPath()` | `method` | 从指定路径加载技能 |\n\n资料来源：[packages/core/src/skills/skill-manager.ts]()\n\n### 技能加载器 (SkillLoader)\n\n技能加载器负责从各种来源加载技能定义，包括本地文件系统、远程 URL 和内置技能包。\n\n| 加载方式 | 来源类型 | 说明 |\n|----------|----------|------|\n| `file` | 本地文件系统 | 从 `.qwen/skills/` 目录加载 |\n| `user` | 用户目录 | 从 `~/.qwen/skills/` 目录加载 |\n| `builtin` | 内置技能 | 框架内置的默认技能 |\n| `remote` | 远程源 | 从远程服务器下载技能包 |\n\n资料来源：[packages/core/src/skills/skill-load.ts]()\n\n### 技能激活器 (SkillActivator)\n\n技能激活器负责将技能集成到运行时环境，包括工具注册、提示词注入和状态初始化。\n\n| 激活阶段 | 操作 | 说明 |\n|----------|------|------|\n| 初始化 | 状态重置 | 重置技能内部状态 |\n| 工具注册 | 注册工具函数 | 将技能工具添加到工具调度器 |\n| 提示注入 | 添加系统提示 | 向 AI 注入技能相关指令 |\n| 资源预加载 | 加载资源 | 预加载技能所需的资源文件 |\n\n资料来源：[packages/core/src/skills/skill-activation.ts]()\n\n### 钩子系统 (HookSystem)\n\n钩子系统提供在关键执行节点插入自定义逻辑的能力，支持同步和异步钩子执行。\n\n```typescript\ninterface HookConfig {\n  name: string;           // 钩子名称\n  priority: number;       // 执行优先级，数值越小越先执行\n  enabled: boolean;       // 是否启用\n  handler: HookHandler;   // 钩子处理函数\n}\n```\n\n| 钩子类型 | 触发时机 | 典型用途 |\n|----------|----------|----------|\n| `preToolUse` | 工具执行前 | 参数验证、权限检查 |\n| `postToolUse` | 工具执行后 | 结果转换、日志记录 |\n| `postToolUseFailure` | 工具执行失败 | 错误处理、重试逻辑 |\n| `preMessage` | 消息发送前 | 内容过滤、敏感词处理 |\n| `postMessage` | 消息接收后 | 响应增强、格式转换 |\n\n资料来源：[packages/core/src/hooks/hookSystem.ts]()\n\n### 钩子注册表 (HookRegistry)\n\n钩子注册表维护所有已注册的钩子实例，提供查询、排序和批量操作功能。\n\n| 功能 | 说明 |\n|------|------|\n| `register()` | 注册新钩子 |\n| `unregister()` | 注销钩子 |\n| `getHooks()` | 获取指定类型的钩子列表 |\n| `setEnabled()` | 启用/禁用钩子 |\n| `clear()` | 清空所有钩子 |\n\n资料来源：[packages/core/src/hooks/hookRegistry.ts]()\n\n## 执行流程\n\n### 技能激活流程\n\n```mermaid\nsequenceDiagram\n    participant User as 用户\n    participant SM as 技能管理器\n    participant SL as 技能加载器\n    participant SA as 技能激活器\n    participant TS as 工具调度器\n\n    User->>SM: 加载技能请求\n    SM->>SL: 调用 loadFromPath()\n    SL->>SL: 扫描技能目录\n    SL-->>SM: 返回技能定义列表\n    SM->>SA: 激活技能\n    SA->>SA: 初始化技能状态\n    SA->>TS: 注册技能工具\n    TS-->>SA: 注册成功\n    SA->>SA: 注入系统提示\n    SA-->>SM: 激活完成\n    SM-->>User: 返回激活结果\n```\n\n### 工具执行与钩子调用流程\n\n```mermaid\nsequenceDiagram\n    participant Agent as AI代理\n    participant HS as 钩子系统\n    participant TS as 工具调度器\n    participant Tool as 工具实现\n    participant MB as 消息总线\n\n    Agent->>TS: 请求执行工具\n    TS->>HS: 触发 preToolUse 钩子\n    HS->>HS: 执行前置钩子链\n    HS-->>TS: 钩子执行结果\n    \n    alt 钩子允许执行\n        TS->>Tool: 调用工具\n        Tool-->>TS: 返回结果\n        TS->>HS: 触发 postToolUse 钩子\n        HS->>HS: 执行后置钩子链\n        HS-->>TS: 处理后的结果\n        TS-->>Agent: 返回最终结果\n    else 钩子阻止执行\n        HS-->>TS: 返回阻止信号\n        TS-->>Agent: 返回错误响应\n    end\n    \n    Note over TS,MB: 失败处理流程\n    Tool-->>TS: 抛出异常\n    TS->>MB: 触发 postToolUseFailure 钩子\n    MB->>MB: 执行失败钩子链\n    MB-->>TS: 错误增强结果\n    TS-->>Agent: 返回带上下文的错误\n```\n\n## 数据模型\n\n### 技能定义结构\n\n```typescript\ninterface SkillDefinition {\n  id: string;                    // 唯一标识符\n  name: string;                  // 显示名称\n  version: string;               // 版本号\n  description: string;          // 功能描述\n  author?: string;               // 作者信息\n  tools: SkillTool[];            // 工具定义列表\n  systemPrompt?: string;         // 系统提示词片段\n  activationConfig?: object;     // 激活配置\n  resources?: string[];          // 依赖资源路径\n  dependencies?: string[];       // 依赖的其他技能\n}\n```\n\n### 工具结果结构\n\n技能工具返回的结果遵循统一的结构规范，包含返回内容和显示信息：\n\n```typescript\ninterface SkillToolResult {\n  returnDisplay: string;        // 返回值的文本表示\n  modelOverride?: string;       // 模型覆盖指令\n  error?: {\n    message: string;            // 错误消息\n    type: string;               // 错误类型\n  };\n}\n```\n\n资料来源：[packages/core/src/core/coreToolScheduler.ts:25-35]()\n\n### 钩子结果结构\n\n```typescript\ninterface HookResult {\n  continue: boolean;            // 是否继续执行后续钩子/主流程\n  modifiedContent?: string;     // 修改后的内容\n  additionalContext?: string;   // 附加的上下文信息\n  suppressError?: boolean;      // 是否抑制错误传播\n}\n```\n\n## 钩子类型详解\n\n### 工具执行钩子\n\n工具执行钩子在工具调用的生命周期中提供多个拦截点，支持精细化的行为控制。\n\n| 钩子名称 | 参数 | 返回值 | 说明 |\n|----------|------|--------|------|\n| `preToolUse` | `toolName`, `toolInput` | `HookResult` | 工具执行前调用，可修改参数或阻止执行 |\n| `postToolUse` | `toolName`, `toolInput`, `toolResult` | `HookResult` | 工具执行成功后调用，可修改返回结果 |\n| `postToolUseFailure` | `toolName`, `toolInput`, `error`, `willRetry` | `HookResult` | 工具执行失败后调用，可添加错误上下文 |\n\n### 消息处理钩子\n\n消息处理钩子拦截聊天消息的发送和接收过程，支持内容过滤和增强。\n\n| 钩子名称 | 触发条件 | 用途 |\n|----------|----------|------|\n| `preMessage` | 消息发送前 | 敏感词过滤、内容审核 |\n| `postMessage` | 消息接收后 | 响应格式化、Markdown 处理 |\n\n### 生命周期钩子\n\n生命周期钩子监听会话和系统的重要状态变化。\n\n| 钩子名称 | 触发时机 | 用途 |\n|----------|----------|------|\n| `onSessionStart` | 会话开始 | 初始化会话上下文 |\n| `onSessionEnd` | 会话结束 | 资源清理、状态保存 |\n| `onSkillActivated` | 技能激活 | 依赖技能加载 |\n| `onSkillDeactivated` | 技能停用 | 资源释放 |\n\n## 集成与扩展\n\n### 注册自定义技能\n\n开发者可以通过扩展技能系统来添加自定义功能：\n\n```typescript\nimport { SkillManager } from '@qwen-code/core';\n\nconst skillManager = SkillManager.getInstance();\n\n// 定义技能\nconst customSkill = {\n  id: 'my-custom-skill',\n  name: '自定义技能',\n  version: '1.0.0',\n  description: '演示自定义技能开发',\n  tools: [\n    {\n      name: 'customTool',\n      description: '自定义工具',\n      execute: async (input) => {\n        return { returnDisplay: `处理结果: ${input}` };\n      }\n    }\n  ],\n  systemPrompt: '你可以使用 customTool 工具来处理自定义任务。'\n};\n\n// 注册并激活\nawait skillManager.register(customSkill);\nawait skillManager.activate('my-custom-skill');\n```\n\n### 注册自定义钩子\n\n开发者可以在关键执行点注入自定义逻辑：\n\n```typescript\nimport { HookRegistry } from '@qwen-code/core';\n\nconst registry = HookRegistry.getInstance();\n\n// 注册前置钩子\nregistry.register({\n  name: 'parameter-validator',\n  type: 'preToolUse',\n  priority: 100,\n  enabled: true,\n  handler: async (toolName, toolInput) => {\n    // 参数验证逻辑\n    if (!validateInput(toolInput)) {\n      return {\n        continue: false,\n        additionalContext: '参数验证失败，请检查输入格式。'\n      };\n    }\n    return { continue: true };\n  }\n});\n```\n\n### 失败钩子的高级用法\n\n失败钩子支持在工具执行失败时添加上下文信息或执行重试逻辑：\n\n```typescript\nregistry.register({\n  name: 'error-enhancer',\n  type: 'postToolUseFailure',\n  priority: 50,\n  enabled: true,\n  handler: async (toolName, toolInput, error, willRetry) => {\n    let additionalContext = '';\n\n    // 为网络错误添加重试建议\n    if (error.message.includes('ECONNREFUSED')) {\n      additionalContext = '建议检查网络连接和目标服务状态。';\n    }\n\n    // 为权限错误添加帮助信息\n    if (error.message.includes('permission')) {\n      additionalContext = '请确保具有必要的操作权限。';\n    }\n\n    return {\n      continue: true,\n      additionalContext,\n      suppressError: false\n    };\n  }\n});\n```\n\n资料来源：[packages/core/src/core/coreToolScheduler.ts:45-70]()\n\n## 配置选项\n\n### 技能配置\n\n技能系统支持通过配置文件进行初始化：\n\n```json\n{\n  \"skills\": {\n    \"enabled\": true,\n    \"autoActivate\": true,\n    \"loadPaths\": [\n      \".qwen/skills\",\n      \"~/.qwen/skills\"\n    ],\n    \"excludedSkills\": []\n  }\n}\n```\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `enabled` | `boolean` | `true` | 是否启用技能系统 |\n| `autoActivate` | `boolean` | `true` | 是否自动激活已注册的技能 |\n| `loadPaths` | `string[]` | 系统默认路径 | 技能加载目录列表 |\n| `excludedSkills` | `string[]` | `[]` | 禁用的技能 ID 列表 |\n\n### 钩子配置\n\n钩子系统支持细粒度的启用/禁用控制：\n\n```json\n{\n  \"hooks\": {\n    \"enabled\": true,\n    \"globalTimeout\": 5000,\n    \"hooks\": {\n      \"preToolUse\": {\n        \"enabled\": true,\n        \"timeout\": 1000\n      },\n      \"postToolUse\": {\n        \"enabled\": true,\n        \"timeout\": 2000\n      },\n      \"postToolUseFailure\": {\n        \"enabled\": true,\n        \"timeout\": 3000\n      }\n    }\n  }\n}\n```\n\n## 最佳实践\n\n### 技能开发规范\n\n1. **单一职责**：每个技能应专注于特定功能领域\n2. **版本管理**：遵循语义化版本规范，清晰标注兼容性\n3. **依赖声明**：明确声明技能依赖的其他技能或资源\n4. **错误处理**：为工具实现提供完整的错误处理和用户友好的错误信息\n5. **资源清理**：在技能停用时正确释放资源\n\n### 钩子开发规范\n\n1. **执行效率**：钩子处理应尽可能高效，避免阻塞主流程\n2. **错误安全**：钩子内部应实现异常捕获，防止错误传播影响系统稳定性\n3. **优先级规划**：合理设置钩子优先级，确保执行顺序符合预期\n4. **幂等性**：确保钩子在重复执行时产生一致的结果\n5. **超时控制**：为可能耗时较长的操作设置合理的超时时间\n\n### 安全注意事项\n\n1. **输入验证**：在钩子中始终验证输入参数的安全性\n2. **权限检查**：敏感操作应配合权限钩子进行访问控制\n3. **日志审计**：记录关键钩子的执行情况，便于问题排查\n4. **沙箱隔离**：自定义技能应在受限环境中执行，防止恶意代码\n\n## 总结\n\n技能与钩子系统为 Qwen Code 提供了强大而灵活的扩展机制。技能系统通过模块化的设计允许开发者以插件形式添加新功能，而钩子系统则提供了在关键执行点进行拦截和增强的能力。两者协同工作，使得框架能够在保持核心简洁的同时支持高度定制化的使用场景。\n\n熟练掌握这两个系统的使用，将有助于开发者构建功能丰富、行为可控的 AI 编程辅助工具。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：QwenLM/qwen-code\n\n摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。\n\n## 1. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | host_targets=claude, claude_code, chatgpt\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在安全注意事项\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 | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 6. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | no_demo; severity=medium\n\n## 7. 维护坑 · 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 | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | issue_or_pr_quality=unknown\n\n## 8. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | release_recency=unknown\n\n<!-- canonical_name: QwenLM/qwen-code; human_manual_source: deepwiki_human_wiki -->\n",
      "markdown_key": "qwen-code",
      "pages": "draft",
      "source_refs": [
        {
          "evidence_id": "art_875e03abe4cc4cb58b4a8ef8603b8a0b",
          "kind": "docs",
          "supports_claim_ids": [
            "claim_identity",
            "claim_distribution",
            "claim_capability"
          ],
          "url": "https://github.com/QwenLM/qwen-code#readme"
        }
      ],
      "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
      "title": "qwen-code 说明书",
      "toc": [
        "https://github.com/QwenLM/qwen-code 项目说明书",
        "目录",
        "项目概览",
        "简介",
        "技术架构",
        "CLI 包架构",
        "Web UI 组件库",
        "文档站点",
        "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": false,
    "repo_commit": null,
    "repo_inspection_error": null,
    "repo_inspection_files": [],
    "repo_inspection_verified": false,
    "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": "# @qwen-code/qwen-code - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 @qwen-code/qwen-code 编译的 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 文档。 证据：`.qwen/skills/bugfix/SKILL.md`, `.qwen/skills/codegraph/SKILL.md`, `.qwen/skills/docs-audit-and-refresh/SKILL.md`, `.qwen/skills/docs-update-from-diff/SKILL.md` 等 Claim：`clm_0004` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`.qwen/skills/bugfix/SKILL.md`, `.qwen/skills/codegraph/SKILL.md`, `.qwen/skills/docs-audit-and-refresh/SKILL.md`, `.qwen/skills/docs-update-from-diff/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`AGENTS.md`, `README.md`, `docs/users/quickstart.md`, `packages/channels/base/README.md` 等 Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `npm install -g @qwen-code/qwen-code@latest` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `npm install @qwen-code/channel-base` 证据：`packages/channels/base/README.md` Claim：`clm_0006` supported 0.86\n- `npm install @qwen-code/channel-plugin-example` 证据：`packages/channels/plugin-example/README.md` Claim：`clm_0007` supported 0.86\n- `npx qwen-channel-plugin-example-server` 证据：`packages/channels/plugin-example/README.md` Claim：`clm_0008` supported 0.86\n- `curl -sX POST http://localhost:9200/message \\` 证据：`packages/channels/plugin-example/README.md` Claim：`clm_0009` supported 0.86\n- `pip install qwen-code-sdk` 证据：`packages/sdk-python/README.md` Claim：`clm_0010` supported 0.86\n- `pip install --pre qwen-code-sdk` 证据：`packages/sdk-python/README.md` Claim：`clm_0011` supported 0.86\n- `npm install @qwen-code/sdk` 证据：`packages/sdk-typescript/README.md` Claim：`clm_0012` supported 0.86\n- `npm install -g qwen-code@^0.4.0` 证据：`packages/sdk-typescript/README.md` Claim：`clm_0013` supported 0.86\n- `npm install @qwen-code/webui` 证据：`packages/webui/README.md` Claim：`clm_0014` 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 或项目证据支撑，但仍不等于真实安装效果。 证据：`.qwen/skills/bugfix/SKILL.md`, `.qwen/skills/codegraph/SKILL.md`, `.qwen/skills/docs-audit-and-refresh/SKILL.md`, `.qwen/skills/docs-update-from-diff/SKILL.md` 等 Claim：`clm_0004` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.qwen/skills/bugfix/SKILL.md`, `.qwen/skills/codegraph/SKILL.md`, `.qwen/skills/docs-audit-and-refresh/SKILL.md`, `.qwen/skills/docs-update-from-diff/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`AGENTS.md`, `README.md`, `docs/users/quickstart.md`, `packages/channels/base/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）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.qwen/skills/bugfix/SKILL.md`, `.qwen/skills/codegraph/SKILL.md`, `.qwen/skills/docs-audit-and-refresh/SKILL.md`, `.qwen/skills/docs-update-from-diff/SKILL.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`AGENTS.md`, `README.md`, `docs/users/quickstart.md`, `packages/channels/base/README.md` 等\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.qwen/skills/bugfix/SKILL.md`, `.qwen/skills/codegraph/SKILL.md`, `.qwen/skills/docs-audit-and-refresh/SKILL.md`, `.qwen/skills/docs-update-from-diff/SKILL.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`AGENTS.md`, `README.md`, `docs/users/quickstart.md`, `packages/channels/base/README.md` 等\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`.qwen/skills/qwen-code-claw/SKILL.md`, `README.md`, `docs/users/configuration/auth.md`, `docs/users/configuration/model-providers.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- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\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_0017` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`AGENTS.md`, `README.md`, `docs/users/quickstart.md`, `packages/channels/base/README.md` 等 Claim：`clm_0018` 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 体验。 证据：`.qwen/skills/bugfix/SKILL.md`, `.qwen/skills/codegraph/SKILL.md`, `.qwen/skills/docs-audit-and-refresh/SKILL.md`, `.qwen/skills/docs-update-from-diff/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`AGENTS.md`, `README.md`, `docs/users/quickstart.md`, `packages/channels/base/README.md` 等 Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：2456\n- 重要文件覆盖：40/2456\n- 证据索引条目：80\n- 角色 / Skill 条目：15\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请基于 @qwen-code/qwen-code 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 @qwen-code/qwen-code 当作安装前体验资产，而不是已安装工具或真实运行环境。\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请基于 @qwen-code/qwen-code 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 15 个角色 / Skill / 项目文档条目。\n\n- **bugfix**（skill）：Fix a bug from a GitHub issue, following the reproduce-first 激活提示：当用户任务与“bugfix”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.qwen/skills/bugfix/SKILL.md`\n- **codegraph**（skill）：Analyze indexed codebases via graph database neug and vector index zvec . Covers call graphs, dependencies, dead code, hotspots, module coupling, architecture reports, semantic search, impact analysis, bug root cause from GitHub issues, class diagrams UML , and PR review risk scoring, conflict detection, auto-merge candidates, labeling . Also covers creating, inspecting, and repairing a CodeScope index. Use for: cod… 激活提示：当用户任务与“codegraph”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.qwen/skills/codegraph/SKILL.md`\n- **docs-audit-and-refresh**（skill）：Audit the repository's docs/ content against the current codebase, 激活提示：当用户任务与“docs-audit-and-refresh”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.qwen/skills/docs-audit-and-refresh/SKILL.md`\n- **docs-update-from-diff**（skill）：Review local code changes with git diff and update the official 激活提示：当用户任务与“docs-update-from-diff”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.qwen/skills/docs-update-from-diff/SKILL.md`\n- **e2e-testing**（skill）：Guide for running end-to-end tests of the Qwen Code CLI, including 激活提示：当用户任务与“e2e-testing”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.qwen/skills/e2e-testing/SKILL.md`\n- **feat-dev**（skill）：End-to-end workflow for implementing a non-trivial qwen-code 激活提示：当用户任务与“feat-dev”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.qwen/skills/feat-dev/SKILL.md`\n- **qwen-code-claw**（skill）：Use Qwen Code as a Code Agent for code understanding, project 激活提示：当用户任务与“qwen-code-claw”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.qwen/skills/qwen-code-claw/SKILL.md`\n- **structured-debugging**（skill）：Hypothesis-driven debugging methodology for hard bugs. Use this 激活提示：当用户任务与“structured-debugging”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.qwen/skills/structured-debugging/SKILL.md`\n- **terminal-capture**（skill）：Automates terminal UI screenshot testing for CLI commands. Applies 激活提示：当用户任务与“terminal-capture”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.qwen/skills/terminal-capture/SKILL.md`\n- **tmux-real-user-testing**（skill）：This skill should be used when the user asks to \"用 tmux 做真实测试\", \"保存 tmux 日志\", \"像真实用户一样测试 Qwen\", \"生成可复查的 TUI 测试报告\", \"测试 slash command 交互\", or requests a tmux-based real user E2E run with complete readable logs. It guides real TUI usage with step-by-step capture-pane snapshots rather than ANSI raw pipe logs. 激活提示：当用户任务与“tmux-real-user-testing”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.qwen/skills/tmux-real-user-testing/SKILL.md`\n- **synonyms**（skill）：Generate synonyms for words or phrases. Use this skill when the user needs alternative words with similar meanings, wants to expand vocabulary, or seeks varied expressions for writing. 激活提示：当用户任务与“synonyms”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/cli/src/commands/extensions/examples/skills/skills/synonyms/SKILL.md`\n- **batch**（skill）：Execute batch operations on multiple files in parallel. Automatically discovers files, splits into chunks, and processes with parallel worker agents. Use /batch followed by operation and file pattern. 激活提示：当用户任务与“batch”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/core/src/skills/bundled/batch/SKILL.md`\n- **loop**（skill）：Create a recurring loop that runs a prompt on a schedule. Usage - /loop 5m check the build, /loop check the PR every 30m, /loop run tests defaults to 10m . /loop list to show jobs, /loop clear to cancel all. 激活提示：当用户任务与“loop”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/core/src/skills/bundled/loop/SKILL.md`\n- **qc-helper**（skill）：Answer any question about Qwen Code usage, features, configuration, and troubleshooting by referencing the official user documentation. Also helps users view or modify their settings.json. Invoke with /qc-helper followed by a question, e.g. /qc-helper how do I configure MCP servers? or /qc-helper change approval mode to yolo . 激活提示：当用户任务与“qc-helper”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/core/src/skills/bundled/qc-helper/SKILL.md`\n- **review**（skill）：Review changed code for correctness, security, code quality, and performance. Use when the user asks to review code changes, a PR, or specific files. Invoke with /review , /review , /review , or /review --comment to post inline comments on the PR. 激活提示：当用户任务与“review”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`packages/core/src/skills/bundled/review/SKILL.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **How to Contribute**（documentation）：We would love to accept your patches and contributions to this project. 证据：`docs/developers/contributing.md`\n- **AGENTS.md**（documentation）：This file provides guidance to Qwen Code when working with code in this repository. 证据：`AGENTS.md`\n- **🎉 News**（documentation）：! npm version https://img.shields.io/npm/v/@qwen-code/qwen-code.svg https://www.npmjs.com/package/@qwen-code/qwen-code ! License https://img.shields.io/github/license/QwenLM/qwen-code.svg ./LICENSE ! Node.js Version https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg https://nodejs.org/ ! Downloads https://img.shields.io/npm/dm/@qwen-code/qwen-code.svg https://www.npmjs.com/package/@qwen-code/qwen-code 证据：`README.md`\n- **Qwen Code Docs Site**（documentation）：A documentation website for Qwen Code built with Next.js https://nextjs.org/ and Nextra https://nextra.site/ . 证据：`docs-site/README.md`\n- **Qwen Concurrent Runner**（documentation）：A Python tool for executing multiple Qwen CLI tasks across different models concurrently using isolated git worktrees. 证据：`integration-tests/concurrent-runner/README.md`\n- **@qwen-code/channel-base**（documentation）：Base infrastructure for building Qwen Code channel adapters. Provides the abstract base class, access control, session routing, and the ACP bridge that communicates with the agent. 证据：`packages/channels/base/README.md`\n- **@qwen-code/channel-plugin-example**（documentation）：A reference channel plugin for Qwen Code. It connects to a WebSocket server and routes messages through the full channel pipeline access control, session routing, agent bridge . 证据：`packages/channels/plugin-example/README.md`\n- **Message Rewrite Middleware**（documentation）：⚠️ Temporary Solution — subject to change or removal at any time. This is a stopgap implementation. We are considering a hook-based approach that would be more decoupled and extensible. Ideas and suggestions for a better design are very welcome. 证据：`packages/cli/src/acp-integration/session/rewrite/README.md`\n- **Provider Structure**（documentation）：This folder contains the different provider implementations for the Qwen Code refactor system. 证据：`packages/core/src/core/openaiContentGenerator/provider/README.md`\n- **qwen-code-sdk**（documentation）：Experimental Python SDK for programmatic access to Qwen Code through the stream-json protocol. 证据：`packages/sdk-python/README.md`\n- **@qwen-code/sdk**（documentation）：A minimum experimental TypeScript SDK for programmatic access to Qwen Code. 证据：`packages/sdk-typescript/README.md`\n- **Qwen Code Companion**（documentation）：! Version https://img.shields.io/visual-studio-marketplace/v/qwenlm.qwen-code-vscode-ide-companion https://marketplace.visualstudio.com/items?itemName=qwenlm.qwen-code-vscode-ide-companion ! VS Code Installs https://img.shields.io/visual-studio-marketplace/i/qwenlm.qwen-code-vscode-ide-companion https://marketplace.visualstudio.com/items?itemName=qwenlm.qwen-code-vscode-ide-companion ! Open VSX Downloads https://img.shields.io/open-vsx/dt/qwenlm/qwen-code-vscode-ide-companion https://open-vsx.org/extension/qwenlm/qwen-code-vscode-ide-companion ! Rating https://img.shields.io/visual-studio-marketplace/r/qwenlm.qwen-code-vscode-ide-companion https://marketplace.visualstudio.com/items?itemName… 证据：`packages/vscode-ide-companion/README.md`\n- **@qwen-code/webui**（documentation）：A shared React component library for Qwen Code applications, providing cross-platform UI components with consistent styling and behavior. 证据：`packages/webui/README.md`\n- **Examples**（documentation）：This directory contains example implementations demonstrating various ways to use the @qwen-code/webui library. 证据：`packages/webui/examples/README.md`\n- **Qwen Code Agent Server Extension for Zed**（documentation）：Qwen Code Agent Server Extension for Zed 证据：`packages/zed-extension/README.md`\n- **Package**（package_manifest）：{ \"name\": \"docs-site\", \"version\": \"1.0.0\", \"description\": \"\", \"license\": \"ISC\", \"author\": \"\", \"type\": \"module\", \"main\": \"index.js\", \"scripts\": { \"link\": \"ln -s ../docs content\", \"clean\": \"rm -rf .next\", \"dev\": \"npm run clean && next --turbopack\", \"test\": \"echo \\\"Error: no test specified\\\" && exit 1\" }, \"dependencies\": { \"next\": \"^16.0.8\", \"nextra\": \"^4.6.1\", \"nextra-theme-docs\": \"^4.6.1\", \"react\": \"^19.2.1\", \"react-dom\": \"^19.2.1\" } } 证据：`docs-site/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@qwen-code/qwen-code\", \"version\": \"0.15.11\", \"engines\": { \"node\": \" =22.0.0\" }, \"type\": \"module\", \"workspaces\": \"packages/ \", \"packages/channels/base\", \"packages/channels/telegram\", \"packages/channels/weixin\", \"packages/channels/dingtalk\", \"packages/channels/plugin-example\" , \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/QwenLM/qwen-code.git\" }, \"config\": { \"sandboxImageUri\": \"ghcr.io/qwenlm/qwen-code:0.15.11\" }, \"scripts\": { \"start\": \"cross-env node scripts/start.js\", \"dev\": \"node scripts/dev.js\", \"debug\": \"cross-env DEBUG=1 node --inspect-brk scripts/start.js\", \"generate\": \"node scripts/generate-git-commit-info.js\", \"generate:settings-schema\": \"node --import tsx… 证据：`package.json`\n- **How to Contribute**（documentation）：We would love to accept your patches and contributions to this project. 证据：`CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"name\": \"toy-project\", \"version\": \"1.0.0\", \"description\": \"Minimal toy project for testing\", \"scripts\": { \"build\": \"echo 'Build complete!'\" }, \"keywords\": , \"author\": \"\", \"license\": \"MIT\" } 证据：`integration-tests/concurrent-runner/examples/toy-project/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@qwen-code/terminal-capture\", \"version\": \"0.1.0\", \"private\": true, \"description\": \"Terminal UI screenshot automation for CLI visual testing\", \"type\": \"module\", \"scripts\": { \"capture\": \"npx tsx run.ts scenarios/\", \"capture:about\": \"npx tsx run.ts scenarios/about.ts\", \"capture:all\": \"npx tsx run.ts scenarios/all.ts\", \"capture:markdown-rendering\": \"npx tsx run.ts scenarios/markdown-rendering.ts\" }, \"dependencies\": { \"@lydell/node-pty\": \"1.2.0-beta.10\", \"@xterm/xterm\": \"^5.5.0\", \"playwright\": \"^1.50.0\", \"strip-ansi\": \"^7.1.2\" } } 证据：`integration-tests/terminal-capture/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@qwen-code/channel-base\", \"version\": \"0.15.11\", \"description\": \"Base channel infrastructure for Qwen Code\", \"type\": \"module\", \"main\": \"dist/index.js\", \"types\": \"dist/index.d.ts\", \"exports\": { \".\": { \"types\": \"./dist/index.d.ts\", \"default\": \"./dist/index.js\" } }, \"files\": \"dist\" , \"scripts\": { \"build\": \"tsc --build\" }, \"dependencies\": { \"@agentclientprotocol/sdk\": \"^0.14.1\" }, \"devDependencies\": { \"typescript\": \"^5.0.0\" } } 证据：`packages/channels/base/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@qwen-code/channel-dingtalk\", \"version\": \"0.15.11\", \"description\": \"DingTalk channel adapter for Qwen Code\", \"type\": \"module\", \"main\": \"dist/index.js\", \"types\": \"dist/index.d.ts\", \"exports\": { \".\": { \"types\": \"./dist/index.d.ts\", \"default\": \"./dist/index.js\" } }, \"files\": \"dist\" , \"scripts\": { \"build\": \"tsc --build\" }, \"dependencies\": { \"@qwen-code/channel-base\": \"file:../base\", \"dingtalk-stream-sdk-nodejs\": \"^2.0.4\" }, \"devDependencies\": { \"typescript\": \"^5.0.0\" } } 证据：`packages/channels/dingtalk/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@qwen-code/channel-plugin-example\", \"version\": \"0.15.11\", \"private\": true, \"type\": \"module\", \"main\": \"dist/index.js\", \"types\": \"dist/index.d.ts\", \"exports\": { \".\": { \"types\": \"./dist/index.d.ts\", \"default\": \"./dist/index.js\" } }, \"files\": \"dist\", \"src\", \"qwen-extension.json\" , \"bin\": { \"qwen-channel-plugin-example-server\": \"dist/start-server.js\" }, \"scripts\": { \"build\": \"tsc --build\", \"prepublishOnly\": \"npm run build\" }, \"dependencies\": { \"@qwen-code/channel-base\": \"file:../base\", \"ws\": \"^8.18.0\" }, \"devDependencies\": { \"@types/ws\": \"^8.5.0\" } } 证据：`packages/channels/plugin-example/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@qwen-code/channel-telegram\", \"version\": \"0.15.11\", \"description\": \"Telegram channel adapter for Qwen Code\", \"type\": \"module\", \"main\": \"dist/index.js\", \"types\": \"dist/index.d.ts\", \"exports\": { \".\": { \"types\": \"./dist/index.d.ts\", \"default\": \"./dist/index.js\" } }, \"files\": \"dist\" , \"scripts\": { \"build\": \"tsc --build\" }, \"dependencies\": { \"@qwen-code/channel-base\": \"file:../base\", \"grammy\": \"^1.41.1\", \"https-proxy-agent\": \"^7.0.6\", \"telegram-markdown-formatter\": \"^0.1.2\" }, \"devDependencies\": { \"typescript\": \"^5.0.0\" } } 证据：`packages/channels/telegram/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@qwen-code/channel-weixin\", \"version\": \"0.15.11\", \"description\": \"WeChat Weixin channel adapter for Qwen Code\", \"type\": \"module\", \"main\": \"dist/index.js\", \"types\": \"dist/index.d.ts\", \"exports\": { \".\": { \"types\": \"./dist/index.d.ts\", \"default\": \"./dist/index.js\" }, \"./accounts\": { \"types\": \"./dist/accounts.d.ts\", \"default\": \"./dist/accounts.js\" }, \"./login\": { \"types\": \"./dist/login.d.ts\", \"default\": \"./dist/login.js\" } }, \"files\": \"dist\" , \"scripts\": { \"build\": \"tsc --build\" }, \"dependencies\": { \"@qwen-code/channel-base\": \"file:../base\" }, \"devDependencies\": { \"typescript\": \"^5.0.0\" } } 证据：`packages/channels/weixin/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@qwen-code/qwen-code\", \"version\": \"0.15.11\", \"description\": \"Qwen Code\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/QwenLM/qwen-code.git\" }, \"type\": \"module\", \"main\": \"dist/index.js\", \"types\": \"dist/index.d.ts\", \"bin\": { \"qwen\": \"dist/index.js\" }, \"exports\": { \".\": { \"types\": \"./dist/index.d.ts\", \"import\": \"./dist/index.js\" }, \"./export\": { \"types\": \"./dist/src/export/index.d.ts\", \"import\": \"./dist/src/export/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\": \"vit… 证据：`packages/cli/package.json`\n- **Package**（package_manifest）：{ \"name\": \"mcp-server-example\", \"version\": \"1.0.0\", \"description\": \"Example MCP Server for Qwen Code Extension\", \"type\": \"module\", \"main\": \"example.js\", \"scripts\": { \"build\": \"tsc\" }, \"devDependencies\": { \"typescript\": \"~5.4.5\", \"@types/node\": \"^20.11.25\" }, \"dependencies\": { \"@modelcontextprotocol/sdk\": \"^1.11.0\", \"zod\": \"^3.22.4\" } } 证据：`packages/cli/src/commands/extensions/examples/mcp-server/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@qwen-code/qwen-code-core\", \"version\": \"0.15.11\", \"description\": \"Qwen Code Core\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/QwenLM/qwen-code.git\" }, \"type\": \"module\", \"main\": \"dist/index.js\", \"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\", \"postinstall\": \"node scripts/postinstall.js\" }, \"files\": \"dist\", \"vendor\", \"scripts/postinstall.js\" , \"dependencies\": { \"@anthropic-ai/sdk\": \"^0.36.1\", \"@google/genai\": \"1.30.0\", \"@iarna/toml\": \"^2.2.5\", \"@modelcontextprotocol/sdk\": \"^1.25.1\", \"@opentelemetry/api\": \"^1.9… 证据：`packages/core/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@qwen-code/sdk\", \"version\": \"0.1.7\", \"description\": \"TypeScript SDK for programmatic access to qwen-code CLI\", \"main\": \"./dist/index.cjs\", \"module\": \"./dist/index.mjs\", \"types\": \"./dist/index.d.ts\", \"type\": \"module\", \"exports\": { \".\": { \"types\": \"./dist/index.d.ts\", \"import\": \"./dist/index.mjs\", \"require\": \"./dist/index.cjs\" }, \"./package.json\": \"./package.json\" }, \"files\": \"dist\", \"README.md\" , \"scripts\": { \"build\": \"node scripts/build.js\", \"bundle:cli\": \"node scripts/bundle-cli.js\", \"test\": \"vitest run\", \"test:ci\": \"vitest run\", \"test:watch\": \"vitest\", \"test:coverage\": \"vitest run --coverage\", \"lint\": \"eslint src test\", \"lint:fix\": \"eslint src test --fix\", \"typecheck\": \"tsc --n… 证据：`packages/sdk-typescript/package.json`\n- **Package**（package_manifest）：{ \"name\": \"qwen-code-vscode-ide-companion\", \"displayName\": \"Qwen Code Companion\", \"description\": \"Enable Qwen Code with direct access to your VS Code workspace.\", \"version\": \"0.15.11\", \"publisher\": \"qwenlm\", \"icon\": \"assets/icon.png\", \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/QwenLM/qwen-code.git\", \"directory\": \"packages/vscode-ide-companion\" }, \"engines\": { \"vscode\": \"^1.85.0\" }, \"license\": \"LICENSE\", \"preview\": true, \"categories\": \"AI\" , \"keywords\": \"qwen-code\", \"qwen code\", \"qwen\", \"qwen code\", \"cli\", \"ide integration\", \"ide companion\" , \"activationEvents\": \"onStartupFinished\", \"onView:qwen-code.chatView.sidebar\", \"onView:qwen-code.chatView.secondary\", \"onCommand:qwen-cod… 证据：`packages/vscode-ide-companion/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@qwen-code/web-templates\", \"version\": \"0.15.11\", \"description\": \"Web templates bundled as embeddable JS/CSS strings\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/QwenLM/qwen-code.git\" }, \"type\": \"module\", \"main\": \"dist/index.js\", \"types\": \"dist/index.d.ts\", \"exports\": { \".\": { \"types\": \"./dist/index.d.ts\", \"import\": \"./dist/index.js\" } }, \"scripts\": { \"build\": \"node build.mjs && tsc --build --clean && tsc\", \"build:templates\": \"node build.mjs\" }, \"files\": \"dist\" , \"dependencies\": {}, \"devDependencies\": { \"@types/react\": \"^18.2.0\", \"@types/react-dom\": \"^18.2.0\", \"@vitejs/plugin-react\": \"^4.2.0\", \"autoprefixer\": \"^10.4.22\", \"postcss\": \"^8.5.6\", \"tailwindcss\": \"^3.4… 证据：`packages/web-templates/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@qwen-code/cli-export-html\", \"private\": true, \"type\": \"module\", \"scripts\": { \"build\": \"node build.mjs\" }, \"dependencies\": { \"@qwen-code/webui\": \"latest\" }, \"devDependencies\": { \"esbuild\": \"^0.25.0\" } } 证据：`packages/web-templates/src/export-html/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@qwen-code/cli-insight\", \"private\": true, \"type\": \"module\", \"scripts\": { \"dev\": \"vite\", \"build\": \"node build.mjs\" } } 证据：`packages/web-templates/src/insight/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@qwen-code/webui\", \"version\": \"0.15.11\", \"description\": \"Shared UI components for Qwen Code packages\", \"type\": \"module\", \"main\": \"./dist/index.cjs\", \"module\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\", \"exports\": { \".\": { \"types\": \"./dist/index.d.ts\", \"import\": \"./dist/index.js\", \"require\": \"./dist/index.cjs\" }, \"./icons\": { \"types\": \"./dist/components/icons/index.d.ts\", \"import\": \"./dist/components/icons/index.js\", \"require\": \"./dist/components/icons/index.cjs\" }, \"./tailwind.preset\": \"./tailwind.preset.cjs\", \"./styles.css\": \"./dist/styles.css\" }, \"files\": \"dist\", \"tailwind.preset.cjs\" , \"sideEffects\": \" / .css\" , \"publishConfig\": { \"access\": \"public\" }, \"scripts\": { \"dev\"… 证据：`packages/webui/package.json`\n- **Bugfix Workflow**（skill_instruction）：Follow this workflow for GitHub issue bugfixes. Do not skip reproduction; fixing without first reproducing the bug tends to produce incomplete fixes and regressions. 证据：`.qwen/skills/bugfix/SKILL.md`\n- **CodeScope Q&A**（skill_instruction）：CodeScope indexes source code into a two-layer knowledge graph — structure functions, calls, imports, classes, modules and evolution commits, file changes, function modifications — plus semantic embeddings for every function. Supports Python, JavaScript/TypeScript, C, and Java including Hadoop-scale repositories with 8K+ files . This combination enables analyses that grep, LSP, or pure vector search cannot do alone. It can also fetch GitHub issues and trace bugs to code , and review open PRs — scoring per-PR risk, detecting cross-PR conflicts, identifying auto-merge candidates, and applying GitHub labels. 证据：`.qwen/skills/codegraph/SKILL.md`\n- **Docs Audit And Refresh**（skill_instruction）：Audit docs/ from the repository outward: inspect the current implementation, identify documentation gaps or inaccuracies, and update the relevant pages. Keep the work inside docs/ and treat code, tests, and current configuration surfaces as the authoritative source. 证据：`.qwen/skills/docs-audit-and-refresh/SKILL.md`\n- **Docs Update From Diff**（skill_instruction）：Inspect local diffs, derive the documentation impact, and update only the repository's docs/ pages. Treat the current code as the source of truth and keep changes scoped, specific, and navigable. 证据：`.qwen/skills/docs-update-from-diff/SKILL.md`\n- **E2E Testing Guide**（skill_instruction）：How to run the Qwen Code CLI end-to-end, from building the bundle to inspecting raw API traffic. Use when unit tests are not enough and you need to verify behavior through the full pipeline model API → tool validation → tool execution . 证据：`.qwen/skills/e2e-testing/SKILL.md`\n- **Feature Development Workflow**（skill_instruction）：Use this workflow when implementing a feature in qwen-code that needs design, behavioral validation, or coordinated changes across multiple files. Each phase produces a concrete artifact. Do not combine phases; the output of each phase feeds the next. 证据：`.qwen/skills/feat-dev/SKILL.md`\n- **Qwen Code Claw**（skill_instruction）：- Understand codebases or ask questions about source code - Generate new projects or add new features - Review pull requests in the codebase - Fix bugs or refactor existing code - Execute various programming tasks such as code review, testing, documentation generation, etc. - Collaborate with other tools and agents to complete complex development tasks 证据：`.qwen/skills/qwen-code-claw/SKILL.md`\n- **Structured Debugging**（skill_instruction）：When debugging hard issues, the natural instinct is to form a theory and immediately apply a fix. This fails more often than it works. The fix addresses the wrong cause, adds complexity, creates false confidence, and obscures the real issue. Worse, after several failed attempts you lose track of what's been tried and start guessing randomly. 证据：`.qwen/skills/structured-debugging/SKILL.md`\n- **Terminal Capture — CLI Terminal Screenshot Automation**（skill_instruction）：Terminal Capture — CLI Terminal Screenshot Automation 证据：`.qwen/skills/terminal-capture/SKILL.md`\n- **tmux Real User Testing**（skill_instruction）：Run Qwen Code in a real tmux TUI session as a user would: navigate dialogs, trigger slash commands, exercise workflows, and save a readable log that maintainers can review. Prefer this workflow when the goal is not just a pass/fail assertion, but a narrative artifact showing what happened on screen. 证据：`.qwen/skills/tmux-real-user-testing/SKILL.md`\n- **Synonym Generation Guidelines**（skill_instruction）：This skill helps generate synonyms and alternative expressions for given words or phrases. It provides contextually appropriate alternatives to enhance vocabulary and improve writing variety. 证据：`packages/cli/src/commands/extensions/examples/skills/skills/synonyms/SKILL.md`\n- **/batch - Parallel Batch Operations**（skill_instruction）：You are orchestrating a batch operation across multiple files. Your job is to: 证据：`packages/core/src/skills/bundled/batch/SKILL.md`\n- **/loop — schedule a recurring prompt**（skill_instruction）：/loop — schedule a recurring prompt 证据：`packages/core/src/skills/bundled/loop/SKILL.md`\n- **Qwen Code Helper**（skill_instruction）：You are a helpful assistant for Qwen Code — an AI coding agent for the terminal. Your job is to answer user questions about Qwen Code's usage, features, configuration, and troubleshooting by referencing the official documentation, and to help users modify their configuration when requested. 证据：`packages/core/src/skills/bundled/qc-helper/SKILL.md`\n- **Code Review**（skill_instruction）：You are an expert code reviewer. Your job is to review code changes and provide actionable feedback. 证据：`packages/core/src/skills/bundled/review/SKILL.md`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\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: 证据：`packages/zed-extension/LICENSE`\n- **Qwen Code Documentation**（documentation）：Welcome to the Qwen Code documentation. Qwen Code is an agentic coding tool that lives in your terminal and helps you turn ideas into code faster than ever before. 证据：`docs/index.md`\n- **Adaptive Output Token Escalation Design**（documentation）：Adaptive Output Token Escalation Design 证据：`docs/design/adaptive-output-token-escalation/adaptive-output-token-escalation-design.md`\n- **Auth Provider Registry Motivation**（documentation）：The auth module used to model each setup path as a separate flow: API key, OAuth, subscription plans, and custom providers. In practice, all of these paths produce the same kind of output: updates to the user's provider configuration in ~/.qwen/settings.json . 证据：`docs/design/auth/motivation.md`\n- **Memory 记忆管理系统**（documentation）：本文介绍 Qwen Code 中 Managed Auto-Memory （托管自动记忆）的记忆管理机制、触发时机和实现细节。 证据：`docs/design/auto-memory/memory-system.md`\n- **Channels Design**（documentation）：External messaging integrations for Qwen Code — interact with an agent from Telegram, WeChat, and more. User documentation: Channels Overview ../../users/features/channels/overview.md . 证据：`docs/design/channels/channels-design.md`\n- **Compact Mode Design: Competitive Analysis & Optimization**（documentation）：Compact Mode Design: Competitive Analysis & Optimization 证据：`docs/design/compact-mode/compact-mode-design.md`\n- **Custom API Key Auth Wizard PRD**（documentation）：Improve the /auth - API Key - Custom API Key experience by replacing the current documentation-only screen with an in-terminal setup wizard for custom API providers. 证据：`docs/design/custom-api-key-auth-wizard-prd.md`\n- **Customize Banner Area Design**（documentation）：Allow users to replace the QWEN ASCII art, replace the brand title, and hide the banner entirely — without letting them suppress the operational data version, auth, model, working directory that makes Qwen Code debuggable and trustworthy. 证据：`docs/design/customize-banner-area/customize-banner-area.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/developers/contributing.md`, `AGENTS.md`, `README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/developers/contributing.md`, `AGENTS.md`, `README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概览**：importance `high`\n  - source_paths: README.md, package.json, AGENTS.md\n- **快速入门**：importance `high`\n  - source_paths: docs/users/quickstart.md, docs/users/configuration/settings.md, docs/users/configuration/auth.md, scripts/installation/INSTALLATION_GUIDE.md\n- **系统架构**：importance `high`\n  - source_paths: docs/developers/architecture.md, packages/cli/package.json, packages/core/package.json, packages/core/src/index.ts\n- **包结构详解**：importance `medium`\n  - source_paths: packages/channels/base/src/ChannelBase.ts, packages/sdk-typescript/package.json, packages/sdk-python/pyproject.toml, packages/sdk-java/qwencode/README.md\n- **智能体运行时**：importance `high`\n  - source_paths: packages/core/src/agents/runtime/agent-core.ts, packages/core/src/agents/runtime/agent-interactive.ts, packages/core/src/agents/runtime/agent-headless.ts, packages/core/src/core/coreToolScheduler.ts, packages/core/src/core/permissionFlow.ts\n- **工具系统**：importance `high`\n  - source_paths: packages/core/src/tools/tools.ts, packages/core/src/tools/tool-registry.ts, packages/core/src/tools/shell.ts, packages/core/src/tools/edit.ts, packages/core/src/tools/lsp.ts\n- **模型集成**：importance `high`\n  - source_paths: packages/core/src/core/openaiContentGenerator/openaiContentGenerator.ts, packages/core/src/core/openaiContentGenerator/provider/dashscope.ts, packages/core/src/core/openaiContentGenerator/provider/openrouter.ts, packages/core/src/core/geminiChat.ts, packages/core/src/core/anthropicContentGenerator/anthropicContentGenerator.ts\n- **记忆系统**：importance `medium`\n  - source_paths: packages/core/src/memory/manager.ts, packages/core/src/memory/recall.ts, packages/core/src/memory/extract.ts, packages/core/src/memory/indexer.ts, packages/core/src/memory/dream.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: false\n- repo_inspection_verified: false\n- repo_commit: `unknown`\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: 可能修改宿主 AI 配置\n\n- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Evidence: capability.host_targets | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | host_targets=claude, claude_code, chatgpt\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 存在安全注意事项\n\n- Trigger: No sandbox install has been executed yet; downstream must verify before user use.\n- Host AI rule: 转成明确权限清单和安全审查提示。\n- Why it matters: 用户安装前需要知道权限边界和敏感操作。\n- Evidence: risks.safety_notes | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | No sandbox install has been executed yet; downstream must verify before user use.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | release_recency=unknown\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项目：QwenLM/qwen-code\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 是否匹配：claude, claude_code, chatgpt\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 可能修改宿主 AI 配置（medium）：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在安全注意事项（medium）：用户安装前需要知道权限边界和敏感操作。 建议检查：转成明确权限清单和安全审查提示。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
      "summary": "安装、权限、验证和推荐前风险。",
      "title": "Boundary & Risk Card / 边界与风险卡"
    },
    "human_manual": {
      "asset_id": "human_manual",
      "filename": "HUMAN_MANUAL.md",
      "markdown": "# https://github.com/QwenLM/qwen-code 项目说明书\n\n生成时间：2026-05-14 05:02:28 UTC\n\n## 目录\n\n- [项目概览](#project-overview)\n- [快速入门](#quick-start)\n- [系统架构](#system-architecture)\n- [包结构详解](#packages-structure)\n- [智能体运行时](#agent-runtime)\n- [工具系统](#tool-system)\n- [模型集成](#model-integration)\n- [记忆系统](#memory-system)\n- [会话管理](#session-management)\n- [技能与钩子系统](#skills-hooks)\n\n<a id='project-overview'></a>\n\n## 项目概览\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [快速入门](#quick-start)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/QwenLM/qwen-code/blob/main/README.md)\n- [packages/webui/README.md](https://github.com/QwenLM/qwen-code/blob/main/packages/webui/README.md)\n- [docs-site/README.md](https://github.com/QwenLM/qwen-code/blob/main/docs-site/README.md)\n- [packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx)\n- [packages/cli/src/ui/components/subagents/create/CreationSummary.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/subagents/create/CreationSummary.tsx)\n</details>\n\n# 项目概览\n\n## 简介\n\nQwen Code 是一个基于大语言模型（LLM）的智能编程助手项目，由 Qwen 团队开发维护。该项目旨在为开发者提供高效的代码编写、理解和编辑能力，支持多种模型提供商和本地部署方案。\n\nQwen Code 采用模块化架构设计，核心包含命令行界面（CLI）包和 Web UI 组件库两个主要子系统，能够适应不同的使用场景和部署环境。资料来源：[README.md:1-10]()\n\n## 技术架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n    A[用户界面层] --> B[CLI 终端界面]\n    A --> C[Web UI 组件库]\n    B --> D[核心业务逻辑层]\n    C --> D\n    D --> E[模型交互层]\n    E --> F[多模型提供商]\n    F --> G[OpenAI 兼容 API]\n    F --> H[Ollama 本地模型]\n    F --> I[vLLM 服务]\n    F --> J[阿里云 ModelStudio]\n```\n\n### 核心包结构\n\n| 包名称 | 路径 | 功能描述 |\n|--------|------|----------|\n| `packages/cli` | `packages/cli/` | 命令行工具核心包，提供终端交互界面 |\n| `packages/webui` | `packages/webui/` | Web 界面组件库，包含 UI 基础组件 |\n| `docs-site` | `docs-site/` | 文档网站，基于 Next.js 和 Nextra 构建 |\n\n资料来源：[packages/webui/README.md:1-30]()\n\n## CLI 包架构\n\n### 目录结构\n\n```\npackages/cli/\n├── src/\n│   ├── ui/                    # 终端用户界面\n│   │   ├── components/         # UI 组件\n│   │   │   ├── arena/         # Arena 对比系统\n│   │   │   ├── subagents/     # 子代理管理\n│   │   │   ├── mcp/           # MCP 协议支持\n│   │   │   ├── extensions/    # 扩展系统\n│   │   │   ├── background-view/ # 后台任务视图\n│   │   │   └── views/         # 通用视图组件\n│   │   ├── hooks/             # 自定义 React Hooks\n│   │   └── keyMatchers.ts     # 键盘快捷键匹配\n│   ├── nonInteractiveCli.ts   # 非交互式 CLI\n│   └── ...\n```\n\n### UI 组件系统\n\nCLI 包采用 React 组件化设计，所有 UI 组件基于 `ink` 库构建，支持终端环境下的富文本渲染。\n\n**核心组件分类：**\n\n| 组件类别 | 文件路径 | 功能 |\n|----------|----------|------|\n| Arena 组件 | `ui/components/arena/` | Agent 对比选择、停止对话框、卡片展示 |\n| 子代理组件 | `ui/components/subagents/` | 创建、编辑、管理子代理 |\n| MCP 组件 | `ui/components/mcp/` | MCP 服务器工具列表和交互 |\n| 扩展组件 | `ui/components/extensions/` | 扩展详情展示 |\n| 统计组件 | `ui/components/StatsDisplay.tsx` | 性能统计和模型使用情况 |\n\n资料来源：[packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx:1-50]()\n\n### Arena 对比系统\n\nArena 是 Qwen Code 中的 Agent 对比评估模块，允许用户同时运行多个代理并比较它们的结果。\n\n**Arena 核心功能：**\n\n- **选择对话框** (`ArenaSelectDialog.tsx`)：展示可用代理列表，支持状态筛选\n- **停止对话框** (`ArenaStopDialog.tsx`)：提供清理或保留工作树的选项\n- **卡片展示** (`ArenaCards.tsx`)：显示对比结果和统计数据\n\n```mermaid\ngraph LR\n    A[启动 Arena] --> B[选择代理]\n    B --> C[运行对比]\n    C --> D[结果展示]\n    D --> E[选择获胜者]\n    E --> F{清理策略}\n    F -->|cleanup| G[清理工作树]\n    F -->|preserve| H[保留Artifacts]\n```\n\n资料来源：[packages/cli/src/ui/components/arena/ArenaStopDialog.tsx:1-60]()\n\n### 子代理系统\n\n子代理（Subagents）允许用户创建自定义的 AI 代理，配置专属的系统提示词、工具集和颜色标识。\n\n**子代理创建流程：**\n\n1. 配置基本信息（名称、描述）\n2. 选择可用工具集\n3. 设置系统提示词\n4. 选择存储位置（项目级或用户级）\n5. 保存并激活\n\n```typescript\ninterface SubagentConfig {\n  name: string;\n  description: string;\n  systemPrompt: string;\n  tools: string[];\n  color?: string;\n  location: 'project' | 'user';\n  model?: string;\n}\n```\n\n资料来源：[packages/cli/src/ui/components/subagents/create/CreationSummary.tsx:1-40]()\n\n### MCP 协议支持\n\nQwen Code 集成了 MCP（Model Context Protocol）协议，支持通过 MCP 服务器扩展工具能力。\n\n**MCP 功能特性：**\n\n| 功能 | 命令 | 说明 |\n|------|------|------|\n| 工具列表 | `/mcp` | 显示所有 MCP 工具 |\n| 工具详情 | `/mcp schema` | 显示工具参数模式 |\n| 隐藏描述 | `/mcp nodesc` | 隐藏工具描述信息 |\n| OAuth 认证 | `/mcp auth <server-name>` | MCP 服务器认证 |\n| 快捷开关 | `Ctrl+T` | 切换工具描述显示 |\n\n资料来源：[packages/cli/src/ui/components/views/McpStatus.tsx:1-50]()\n\n### 后台任务系统\n\n后台任务视图（BackgroundTasksDialog）提供了长时间运行任务的监控能力。\n\n**任务状态展示：**\n\n- **运行中**：显示进度文本和会话数量\n- **已完成**：显示执行时长和主题统计\n- **错误状态**：展示错误信息和警告\n- **锁释放警告**：提示可能的锁定问题\n\n```mermaid\nstateDiagram-v2\n    [*] --> Running: 启动任务\n    Running --> Completed: 成功完成\n    Running --> Failed: 发生错误\n    Completed --> [*]: 清理\n    Failed --> [*]: 清理\n    Completed --> LockWarning: 锁释放失败\n```\n\n资料来源：[packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx:1-80]()\n\n## Web UI 组件库\n\n### 组件分类\n\n| 类别 | 组件列表 | 用途 |\n|------|----------|------|\n| 图标组件 | FileIcon, FolderIcon, CheckIcon, ErrorIcon | 基础视觉元素 |\n| 布局组件 | Container, Header, Footer, Sidebar | 页面结构布局 |\n| 消息组件 | Message, MessageList, MessageInput | 对话交互 |\n| 工具调用 | ToolCallCard, ToolCallRow | 工具执行展示 |\n\n资料来源：[packages/webui/README.md:50-100]()\n\n### 平台上下文\n\nWebUI 提供 Platform Context 作为平台抽象层，支持不同运行环境的适配：\n\n```tsx\nimport { PlatformProvider, usePlatform } from '@qwen-code/webui/context';\n```\n\n### 主题系统\n\n组件支持自定义主题配置，包括：\n\n- **颜色系统**：主色、强调色、状态色（成功/错误/警告）\n- **尺寸变体**：`sm` | `md` | `lg`\n- **状态标识**：错误状态、加载状态、空状态\n\n## 文档站点\n\n文档网站采用以下技术栈：\n\n| 技术 | 用途 |\n|------|------|\n| Next.js | React 框架和路由系统 |\n| Nextra | MDX 文档框架 |\n| TypeScript | 类型安全 |\n\n**开发命令：**\n\n```bash\nnpm install    # 安装依赖\nnpm run link   # 链接 docs 目录内容\nnpm run dev    # 启动开发服务器\n```\n\n资料来源：[docs-site/README.md:1-40]()\n\n## 配置系统\n\n### 模型配置\n\nQwen Code 支持配置多个模型提供商，通过 `~/.qwen/settings.json` 文件管理：\n\n```json\n{\n  \"modelProviders\": {\n    \"openai\": [\n      {\n        \"id\": \"qwen3:32b\",\n        \"name\": \"Qwen3 32B (Ollama)\",\n        \"baseUrl\": \"http://localhost:11434/v1\",\n        \"generationConfig\": {\n          \"contextWindowSize\": 131072\n        }\n      }\n    ]\n  },\n  \"model\": {\n    \"name\": \"qwen3:32b\"\n  }\n}\n```\n\n### 键盘快捷键\n\n| 命令 | 快捷键 | 功能 |\n|------|--------|------|\n| 提交输入 | `Enter` | 发送消息 |\n| 取消/返回 | `Escape` | 关闭对话框 |\n| 预览切换 | `p` | 切换预览视图 |\n| 详细差异 | `d` | 切换详细差异视图 |\n| 历史上翻 | `Ctrl+P` | 命令历史向上 |\n| 历史下翻 | `Ctrl+N` | 命令历史向下 |\n| 清屏 | `Ctrl+L` | 清除屏幕 |\n\n资料来源：[packages/cli/src/ui/keyMatchers.test.ts:1-40]()\n\n## 性能统计\n\nStatsDisplay 组件展示任务执行的详细性能数据：\n\n| 统计项 | 说明 |\n|--------|------|\n| Wall Time | 任务总耗时 |\n| Agent Active | Agent 活跃时间 |\n| API Time | LLM API 调用耗时及占比 |\n| Tool Time | 工具执行耗时及占比 |\n| Token 统计 | 输入/输出/缓存 Token 数量 |\n| Cache Efficiency | 缓存命中率 |\n\n资料来源：[packages/cli/src/ui/components/StatsDisplay.tsx:1-60]()\n\n## 扩展系统\n\nQwen Code 支持通过扩展（Extensions）机制增强功能，每个扩展包含：\n\n| 属性 | 说明 |\n|------|------|\n| name | 扩展名称 |\n| version | 版本号 |\n| path | 安装路径 |\n| source | 安装来源（npm/local） |\n| mcpServers | 关联的 MCP 服务器 |\n| commands | 可用命令列表 |\n\n资料来源：[packages/cli/src/ui/components/extensions/steps/ExtensionDetailStep.tsx:1-50]()\n\n## 技术栈总结\n\n| 层级 | 技术选型 |\n|------|----------|\n| CLI 界面 | React + Ink（终端 UI 框架） |\n| Web UI | React + Tailwind CSS |\n| 构建工具 | Vite（WebUI）、pkg（CLI 打包） |\n| 文档框架 | Next.js + Nextra |\n| 包管理 | npm workspace |\n\n## 总结\n\nQwen Code 项目采用现代化 monorepo 架构，通过 `packages/cli` 和 `packages/webui` 两个核心包分别服务终端用户和 Web 应用场景。丰富的组件系统（Arena、Subagents、MCP、Extensions）提供了强大的扩展能力，而统一的配置系统和键盘快捷键设计确保了用户体验的一致性。\n\n---\n\n<a id='quick-start'></a>\n\n## 快速入门\n\n### 相关页面\n\n相关主题：[项目概览](#project-overview)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/QwenLM/qwen-code/blob/main/README.md)\n- [packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx)\n- [packages/cli/src/ui/components/extensions/steps/ExtensionDetailStep.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/extensions/steps/ExtensionDetailStep.tsx)\n- [packages/cli/src/ui/components/subagents/create/CreationSummary.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/subagents/create/CreationSummary.tsx)\n- [packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx)\n- [packages/cli/src/ui/components/StatsDisplay.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/StatsDisplay.tsx)\n- [packages/cli/src/ui/components/views/McpStatus.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/views/McpStatus.tsx)\n- [packages/cli/src/ui/components/mcp/steps/ToolListStep.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/mcp/steps/ToolListStep.tsx)\n- [packages/cli/src/ui/components/mcp/steps/ServerListStep.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/mcp/steps/ServerListStep.tsx)\n- [packages/cli/src/ui/keyMatchers.test.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/keyMatchers.test.ts)\n- [packages/webui/README.md](https://github.com/QwenLM/qwen-code/blob/main/packages/webui/README.md)\n</details>\n\n# 快速入门\n\nQwen Code 是一个基于 AI 的智能编程助手，通过命令行界面（CLI）为开发者提供代码生成、补全、调试和重构等功能。本页将帮助用户快速上手 Qwen Code，掌握从安装到日常使用的完整流程。\n\n## 环境要求\n\n在开始使用 Qwen Code 之前，请确保您的开发环境满足以下要求：\n\n| 要求项 | 最低版本 | 说明 |\n|--------|----------|------|\n| Node.js | 18.0.0 | 运行时环境 |\n| npm/yarn/pnpm | 最新稳定版 | 包管理工具 |\n| 操作系统 | macOS/Linux/Windows | 跨平台支持 |\n| 网络 | 可访问 AI 服务 | 用于 API 调用 |\n\n资料来源：[packages/webui/README.md]()\n\n## 安装步骤\n\n### 方式一：通过 npm 全局安装\n\n```bash\nnpm install -g @qwen-code/cli\n```\n\n安装完成后，运行以下命令验证安装：\n\n```bash\nqwen --version\n```\n\n### 方式二：通过包管理器安装\n\n根据您使用的包管理器选择相应命令：\n\n```bash\n# 使用 npm\nnpm install\n\n# 使用 yarn\nyarn install\n\n# 使用 pnpm\npnpm install\n```\n\n资料来源：[README.md](https://github.com/QwenLM/qwen-code/blob/main/README.md)\n\n## 首次配置\n\n### 配置模型提供商\n\nQwen Code 支持配置多个模型提供商，您需要在配置文件中添加 API 密钥和模型信息：\n\n```json\n{\n  \"modelProviders\": {\n    \"openai\": [\n      {\n        \"id\": \"qwen3.6-plus\",\n        \"name\": \"qwen3.6-plus\",\n        \"baseUrl\": \"https://api.example.com/v1\",\n        \"description\": \"Qwen 3.6 Plus 模型\",\n        \"envKey\": \"YOUR_API_KEY\"\n      }\n    ]\n  }\n}\n```\n\n配置文件的默认位置为 `~/.qwen/config.json`（用户级别）或项目目录下的 `.qwen/config.json`（项目级别）。\n\n资料来源：[README.md](https://github.com/QwenLM/qwen-code/blob/main/README.md)\n\n### 配置环境变量\n\n将您的 API 密钥设置为环境变量：\n\n```bash\nexport YOUR_API_KEY=\"your-api-key-here\"\n```\n\n支持的认证方式包括：\n\n| 认证类型 | 说明 | 配置位置 |\n|----------|------|----------|\n| API Key | 标准 API 密钥认证 | `envKey` 字段 |\n| OAuth | OAuth 2.0 认证 | MCP 服务器配置 |\n| 环境变量 | 通过环境变量传递 | 系统环境 |\n\n资料来源：[packages/cli/src/ui/auth/AuthDialog.tsx]()\n\n## 启动应用\n\n配置完成后，通过以下命令启动 Qwen Code：\n\n```bash\nqwen\n```\n\n启动后将进入交互式命令行界面，您可以直接输入自然语言描述来生成代码。\n\n资料来源：[README.md](https://github.com/QwenLM/qwen-code/blob/main/README.md)\n\n## 基本操作\n\n### 切换模型\n\n使用 `/model` 命令可以在已配置的模型之间切换：\n\n```\n/model\n```\n\n系统将显示可用模型列表，供您选择。\n\n资料来源：[README.md](https://github.com/QwenLM/qwen-code/blob/main/README.md)\n\n### 管理子代理\n\nQwen Code 支持创建和管理子代理（Subagents），用于处理特定任务：\n\n```mermaid\ngraph TD\n    A[创建子代理] --> B[配置工具]\n    B --> C[设置系统提示词]\n    C --> D[生成描述]\n    D --> E[保存到项目或用户级别]\n    \n    F[项目级别] --> E\n    G[用户级别] --> E\n```\n\n子代理配置包括以下选项：\n\n| 配置项 | 说明 | 可选值 |\n|--------|------|--------|\n| location | 存储位置 | project / user |\n| tools | 启用的工具 | Read/Edit/Web/Search 等 |\n| color | 显示颜色 | 预定义颜色值 |\n| description | 代理描述 | 自动生成或手动输入 |\n| systemPrompt | 系统提示词 | 自定义指令 |\n\n资料来源：[packages/cli/src/ui/components/subagents/create/CreationSummary.tsx]()\n\n### MCP 服务器集成\n\nQwen Code 支持 MCP（Model Context Protocol）服务器，可扩展工具能力：\n\n```mermaid\ngraph LR\n    A[MCP 服务器] --> B[工具注册]\n    B --> C[状态监控]\n    C --> D{连接状态}\n    D -->|已连接| E[可用工具列表]\n    D -->|断开连接| F[显示错误日志]\n```\n\n常用 MCP 命令：\n\n| 命令 | 功能 |\n|------|------|\n| `/mcp list` | 列出所有 MCP 服务器 |\n| `/mcp schema` | 显示工具参数模式 |\n| `/mcp nodesc` | 隐藏工具描述 |\n| `/mcp auth <server>` | OAuth 认证 |\n| `Ctrl+T` | 切换工具描述显示 |\n\n资料来源：[packages/cli/src/ui/components/views/McpStatus.tsx]()\n资料来源：[packages/cli/src/ui/components/mcp/steps/ToolListStep.tsx]()\n\n## 交互界面\n\n### 工具调用显示\n\n工具调用结果在界面中以卡片形式展示：\n\n| 状态 | 颜色 | 说明 |\n|------|------|------|\n| success | 绿色 | 执行成功 |\n| error | 红色 | 执行失败 |\n| warning | 黄色 | 警告信息 |\n| loading | 蓝色 | 执行中 |\n| pending | 灰色 | 等待中 |\n\n对于文件操作类工具，系统会显示操作结果和文件列表：\n\n```\nToolCallContainer\n├── 状态标志\n├── 操作描述\n└── 文件位置列表\n```\n\n资料来源：[packages/webui/src/components/toolcalls/GenericToolCall.tsx]()\n\n### 性能统计\n\nQwen Code 提供实时性能统计功能：\n\n| 统计项 | 说明 |\n|--------|------|\n| Wall Time | 总耗时 |\n| Agent Active | 代理活跃时间 |\n| API Time | API 调用耗时及占比 |\n| Tool Time | 工具执行耗时及占比 |\n| Token Usage | Token 使用量 |\n| Cache Efficiency | 缓存效率 |\n\n资料来源：[packages/cli/src/ui/components/StatsDisplay.tsx]()\n\n### 键盘快捷键\n\n| 功能 | 快捷键 |\n|------|--------|\n| 确认建议 | `Tab` 或 `Enter` |\n| 取消操作 | `Escape` |\n| 历史记录上 | `Ctrl+P` |\n| 历史记录下 | `Ctrl+N` |\n| 导航上 | `Up` |\n| 导航下 | `Down` |\n| 删除整行 | `Ctrl+U` |\n| 清屏 | `Ctrl+L` |\n| 提交输入 | `Enter`（无修饰键） |\n\n资料来源：[packages/cli/src/ui/keyMatchers.test.ts]()\n\n## Arena 对战模式\n\nArena 是 Qwen Code 的代码对比评估功能，可比较不同代理的代码生成结果：\n\n```mermaid\ngraph TD\n    A[进入 Arena] --> B[选择代理]\n    B --> C[执行任务]\n    C --> D[生成差异对比]\n    D --> E[选择获胜者]\n    E --> F[查看性能统计]\n```\n\nArena 界面显示：\n\n- **状态信息**：执行状态、耗时、Token 数量、文件数量\n- **差异统计**：代码增删行数（绿色添加/红色删除）\n- **Token 效率**：各代理的 Token 使用量和运行时间对比\n\n资料来源：[packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx]()\n资料来源：[packages/cli/src/ui/components/arena/ArenaCards.tsx]()\n\n## 后台任务管理\n\nQwen Code 支持后台任务执行，适合长时间运行的任务：\n\n```mermaid\ngraph TD\n    A[提交任务] --> B[锁定资源]\n    B --> C{执行状态}\n    C -->|成功| D[释放锁]\n    C -->|失败| E[记录错误]\n    C -->|警告| F[锁释放警告]\n    C -->|警告| G[元数据写入警告]\n```\n\n后台任务显示信息包括：\n\n| 信息类型 | 说明 |\n|----------|------|\n| 会话数量 | 正在审查的会话数 |\n| 进度文本 | 当前任务进度 |\n| 触达主题 | 已处理的主题列表 |\n| 锁定警告 | 锁释放失败提示 |\n| 元数据警告 | 元数据写入失败提示 |\n\n资料来源：[packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx]()\n\n## 扩展管理\n\nQwen Code 支持通过扩展增强功能：\n\n| 扩展属性 | 说明 |\n|----------|------|\n| name | 扩展名称 |\n| version | 版本号 |\n| status | 启用状态 |\n| path | 安装路径 |\n| source | 来源信息 |\n| mcpServers | 关联的 MCP 服务器 |\n| commands | 可用命令列表 |\n\n资料来源：[packages/cli/src/ui/components/extensions/steps/ExtensionDetailStep.tsx]()\n\n## 下一步\n\n完成快速入门后，建议继续阅读以下文档：\n\n- **配置指南**：深入了解配置文件格式和高级选项\n- **认证配置**：学习如何配置各种认证方式\n- **扩展开发**：了解如何开发自定义扩展\n- **API 参考**：查看完整的命令行接口文档\n\n---\n\n<a id='system-architecture'></a>\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目概览](#project-overview), [包结构详解](#packages-structure), [智能体运行时](#agent-runtime)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx)\n- [packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx)\n- [packages/cli/src/ui/components/mcp/steps/ServerListStep.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/mcp/steps/ServerListStep.tsx)\n- [packages/cli/src/ui/components/StatsDisplay.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/StatsDisplay.tsx)\n- [packages/core/src/memory/extractionAgentPlanner.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/memory/extractionAgentPlanner.ts)\n- [README.md](https://github.com/QwenLM/qwen-code/blob/main/README.md)\n</details>\n\n# 系统架构\n\n## 概述\n\nQwen Code 是一个模块化的命令行 AI 编程助手，采用多包架构设计以实现核心逻辑与用户界面的分离。项目主要由 `packages/cli`、`packages/core` 和 `packages/webui` 三个核心包组成，支持扩展机制、后台任务管理、代理（Agent）编排以及 MCP（Model Context Protocol）协议集成。\n\n## 整体架构\n\n```mermaid\ngraph TD\n    User[用户] --> CLI[packages/cli<br/>命令行界面]\n    CLI --> WebUI[packages/webui<br/>Web UI 组件]\n    CLI --> Core[packages/core<br/>核心逻辑]\n    Core --> Memory[记忆管理模块]\n    Core --> Planner[任务规划模块]\n    Core --> Tools[工具系统]\n    CLI --> Mcp[MCP 服务器集成]\n    Mcp --> Servers[外部 MCP 服务]\n```\n\n## 核心包结构\n\n### packages/core — 核心逻辑层\n\n核心包负责 AI 代理的核心功能实现，包括任务规划、记忆管理和工具调用。\n\n| 模块 | 路径 | 功能描述 |\n|------|------|----------|\n| 记忆管理 | `src/memory/` | 管理代理的持久化记忆，包括主题文档自动扫描 |\n| 任务规划 | `src/planner/` | 构建和管理任务执行的提示词 |\n| 工具系统 | `src/tools/` | 代理可调用的内置工具集合 |\n\n**记忆管理模块**\n\n`extractionAgentPlanner.ts` 实现了记忆提取代理，规划器会扫描项目中的自动记忆主题文档并生成摘要块。该模块支持以下功能：\n\n- 扫描 `auto-memory` 主题文档\n- 截断长文本以控制上下文长度\n- 构建 Markdown 格式的记忆摘要\n\n资料来源：[packages/core/src/memory/extractionAgentPlanner.ts:1-30]()\n\n### packages/cli — 命令行界面\n\nCLI 包提供终端用户界面，处理用户输入、命令解析和状态展示。\n\n| 组件目录 | 功能 |\n|----------|------|\n| `ui/components/arena/` | 对战竞技场界面，支持代理选择、对话预览、差异对比 |\n| `ui/components/background-view/` | 后台任务对话框，显示进度、错误、锁定警告 |\n| `ui/components/mcp/` | MCP 服务器和工具列表管理 |\n| `ui/components/extensions/` | 扩展详情展示 |\n| `ui/components/subagents/` | 子代理创建和配置 |\n| `ui/components/views/` | 状态视图组件 |\n\n**Arena 竞技场组件**\n\nArena 模块支持多代理并行对比功能。`ArenaSelectDialog.tsx` 实现了代理选择对话框，提供以下状态信息展示：\n\n- 运行状态及颜色编码\n- 运行时长\n- Token 消耗统计\n- 代码变更（增加/删除行数）\n- 涉及文件数量\n\n资料来源：[packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx:1-40]()\n\n**后台任务管理**\n\n`BackgroundTasksDialog.tsx` 实现了后台任务监控界面，支持以下功能：\n\n- 任务进度文本显示\n- Session 计数展示\n- 主题追踪列表\n- 错误状态展示\n- 锁定释放警告\n- 元数据写入警告\n\n资料来源：[packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx:1-80]()\n\n**MCP 集成**\n\nMCP 模块负责与外部 MCP 服务器的通信：\n\n```mermaid\ngraph LR\n    CLI[CLI] --> ServerList[服务器列表]\n    CLI --> ToolList[工具列表]\n    ServerList --> Status[连接状态]\n    ToolList --> Validation[工具验证]\n    Status -->|disconnected| Debug[调试提示]\n```\n\n- `ServerListStep.tsx`: 显示 MCP 服务器列表及连接状态\n- `ToolListStep.tsx`: 显示可用工具列表，支持滚动和选择\n- 无效工具显示警告信息及原因\n\n资料来源：[packages/cli/src/ui/components/mcp/steps/ServerListStep.tsx:1-50]()\n资料来源：[packages/cli/src/ui/components/mcp/steps/ToolListStep.tsx:1-60]()\n\n### packages/webui — Web UI 组件库\n\nWebUI 包提供可复用的 React 组件，支持 Storybook 文档化。\n\n| 组件类别 | 组件 |\n|----------|------|\n| 图标 | FileIcon, FolderIcon, CheckIcon, ErrorIcon, WarningIcon |\n| 布局 | Container, Header, Footer, Sidebar, Main |\n| 消息 | Message, MessageList, MessageInput, WaitingMessage |\n| 工具调用 | ToolCallCard, ToolCallRow |\n\n**Platform Context**\n\n提供平台特定能力的抽象层：\n\n```tsx\nimport { PlatformProvider, usePlatform } from '@qwen-code/webui/context';\n```\n\n## 统计与性能监控\n\n`StatsDisplay.tsx` 组件负责展示运行统计数据：\n\n| 统计类别 | 指标 |\n|----------|------|\n| 代码变更 | 新增行数、删除行数 |\n| 性能 | 墙钟时间、代理活跃时间 |\n| 时间分析 | API 调用时间及占比、工具调用时间及占比 |\n| 模型使用 | 各模型 Token 消耗、缓存效率 |\n\n资料来源：[packages/cli/src/ui/components/StatsDisplay.tsx:1-60]()\n\n## 扩展机制\n\n扩展系统支持自定义功能和 MCP 服务器集成：\n\n- 扩展版本和路径信息展示\n- 激活状态管理\n- MCP 服务器关联配置\n- 自定义命令注册\n\n资料来源：[packages/cli/src/ui/components/extensions/steps/ExtensionDetailStep.tsx:1-50]()\n\n## 键盘交互系统\n\nCLI 实现了一套完整的键盘快捷键匹配系统：\n\n| 命令 | 快捷键 |\n|------|--------|\n| 接受建议 | Tab / Enter |\n| 清除输入 | Ctrl+C |\n| 历史上一条 | Ctrl+P |\n| 历史下一条 | Ctrl+N |\n| 导航上/下 | 方向键 |\n| 退出 | Escape |\n\n## 子代理创建流程\n\n`CreationSummary.tsx` 组件展示子代理创建的配置摘要：\n\n- 位置选择：项目级（`.qwen/agents/`）或用户级（`~/.qwen/agents/`）\n- 工具配置显示\n- 颜色标识\n- 系统提示词和描述预览\n\n资料来源：[packages/cli/src/ui/components/subagents/create/CreationSummary.tsx:1-50]()\n\n## 数据流架构\n\n```mermaid\ngraph TD\n    Input[用户输入] --> AtCmd[@ 命令处理]\n    AtCmd --> Processor[命令处理器]\n    Processor --> Config[配置系统]\n    Config --> Agent[代理执行]\n    Agent --> Tools[工具调用]\n    Tools --> Mcp[MCP 协议]\n    Mcp --> External[外部服务]\n    Agent --> Memory[记忆更新]\n    Memory --> UI[UI 更新]\n    UI --> Stats[统计展示]\n```\n\n## 配置模型\n\n项目支持灵活的配置模型，支持多个模型提供商：\n\n```json\n{\n  \"modelProviders\": {\n    \"openai\": [\n      {\n        \"id\": \"qwen3.6-plus\",\n        \"name\": \"qwen3.6-plus\",\n        \"baseUrl\": \"https://...\",\n        \"envKey\": \"API_KEY\",\n        \"generationConfig\": {}\n      }\n    ]\n  }\n}\n```\n\n支持的配置项：\n\n- 模型 ID 和名称\n- API Base URL\n- 环境变量密钥\n- 生成配置（温度、最大 token 等）\n- 思考模式启用\n\n资料来源：[README.md:1-50]()\n\n## 技术栈总结\n\n| 层级 | 技术 |\n|------|------|\n| 核心运行时 | TypeScript/Node.js |\n| CLI 界面 | React + Ink（终端 UI 框架） |\n| Web UI | React + Tailwind CSS |\n| 构建工具 | Vite |\n| 文档站点 | Next.js + Nextra |\n| 测试 | Vitest |\n\n---\n\n<a id='packages-structure'></a>\n\n## 包结构详解\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/cli/README.md](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/README.md)\n- [packages/webui/README.md](https://github.com/QwenLM/qwen-code/blob/main/packages/webui/README.md)\n- [docs-site/README.md](https://github.com/QwenLM/qwen-code/blob/main/docs-site/README.md)\n- [packages/core/src/memory/extractionAgentPlanner.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/memory/extractionAgentPlanner.ts)\n- [packages/core/src/utils/toml-to-markdown-converter.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/utils/toml-to-markdown-converter.ts)\n- [README.md](https://github.com/QwenLM/qwen-code/blob/main/README.md)\n</details>\n\n# 包结构详解\n\n## 项目概述\n\nQwen Code 是一个采用 Monorepo（单仓库）结构管理的多语言 SDK 项目。根据项目根目录的 `README.md` 和各子包的文档，该项目包含了 **CLI 命令行工具**、**WebUI 界面**、**Core 核心库**、**文档站点** 等多个子包。\n\n资料来源：[README.md:1-50]()\n\n## 整体架构\n\nQwen Code 采用 monorepo 结构组织代码，所有子包位于 `packages/` 目录下。核心子包包括：\n\n| 子包名称 | 路径 | 技术栈 | 用途 |\n|---------|------|--------|------|\n| cli | `packages/cli/` | TypeScript/Node.js | 命令行交互界面 |\n| webui | `packages/webui/` | React/Vite/TypeScript | Web 图形界面 |\n| core | `packages/core/` | TypeScript | 核心逻辑与 API |\n| docs-site | `docs-site/` | Next.js/MDX | 文档网站 |\n\n资料来源：[packages/webui/README.md:1-30]()\n\n## 子包详细结构\n\n### packages/cli\n\nCLI 子包是用户与 Qwen Code 交互的主要入口，提供终端 UI 界面。\n\n```\npackages/cli/\n├── src/\n│   ├── ui/\n│   │   ├── components/        # UI 组件目录\n│   │   │   ├── arena/         # Arena 对战组件\n│   │   │   ├── background-view/  # 后台任务视图\n│   │   │   ├── extensions/    # 扩展管理组件\n│   │   │   ├── subagents/     # 子代理创建组件\n│   │   │   ├── mcp/           # MCP 服务器管理组件\n│   │   │   ├── messages/      # 消息渲染组件\n│   │   │   ├── hooks/         # Hook 配置组件\n│   │   │   ├── views/         # 状态视图组件\n│   │   │   └── DiffRenderer.tsx  # 差异渲染器\n│   │   ├── commands/          # 命令定义\n│   │   └── App.tsx            # 主应用组件\n│   ├── i18n/                  # 国际化配置\n│   │   ├── locales/           # 语言文件\n│   │   └── mustTranslateKeys.test.ts  # 翻译覆盖测试\n│   └── hooks/                 # 自定义 Hooks\n└── package.json\n```\n\n核心 UI 组件功能说明：\n\n| 组件 | 文件路径 | 功能 |\n|------|----------|------|\n| ArenaSelectDialog | `ui/components/arena/ArenaSelectDialog.tsx` | Agent 对战选择对话框 |\n| BackgroundTasksDialog | `ui/components/background-view/BackgroundTasksDialog.tsx` | 后台任务管理 |\n| ExtensionDetailStep | `ui/components/extensions/steps/ExtensionDetailStep.tsx` | 扩展详情步骤 |\n| ServerListStep | `ui/components/mcp/steps/ServerListStep.tsx` | MCP 服务器列表 |\n| ToolListStep | `ui/components/mcp/steps/ToolListStep.tsx` | 工具列表显示 |\n| McpStatus | `ui/components/views/McpStatus.tsx` | MCP 状态视图 |\n| StatsDisplay | `ui/components/StatsDisplay.tsx` | 统计信息展示 |\n\n资料来源：[packages/cli/README.md](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/README.md)\n\n### packages/webui\n\nWebUI 子包提供基于 React 的图形化界面，支持 Storybook 组件预览。\n\n```\npackages/webui/\n├── src/\n│   ├── components/\n│   │   ├── icons/             # 图标组件\n│   │   ├── layout/            # 布局组件\n│   │   ├── messages/          # 消息组件\n│   │   └── ui/                # UI 基础组件\n│   ├── context/               # 平台上下文\n│   ├── hooks/                 # 自定义 React Hooks\n│   └── types/                 # TypeScript 类型定义\n├── .storybook/                # Storybook 配置\n├── tailwind.preset.cjs        # Tailwind 预设\n└── vite.config.ts             # Vite 构建配置\n```\n\n开发命令：\n\n```bash\n# 启动 Storybook\ncd packages/webui && npm run storybook\n\n# 构建生产版本\nnpm run build\n\n# 类型检查\nnpm run typecheck\n```\n\n资料来源：[packages/webui/README.md:1-60]()\n\n### packages/core\n\nCore 子包包含核心业务逻辑，包括内存管理、内容生成等功能。\n\n```\npackages/core/\n├── src/\n│   ├── memory/\n│   │   ├── prompt.ts              # 内存提示词配置\n│   │   └── extractionAgentPlanner.ts  # 提取代理规划器\n│   ├── core/\n│   │   └── openaiContentGenerator/  # OpenAI 内容生成器\n│   └── utils/\n│       └── toml-to-markdown-converter.ts  # TOML 转 Markdown 工具\n```\n\n核心模块说明：\n\n**内存管理模块 (`memory/`)**\n\n内存管理模块负责管理对话中的持久化记忆，支持外部系统引用、主题文档扫描等功能。\n\n- `prompt.ts` - 定义内存保存的规则和示例，包含 WHAT_NOT_TO_SAVE_SECTION 等常量\n- `extractionAgentPlanner.ts` - 提供 `buildTopicSummaryBlock` 和 `buildTaskPrompt` 等函数用于构建主题摘要\n\n**内容生成模块 (`openaiContentGenerator/`)**\n\n`openaiContentGenerator.ts` 实现内容嵌入和生成功能：\n\n```typescript\nconst embedding = await this.pipeline.client.embeddings.create({\n  model: 'text-embedding-ada-002',\n  input: text,\n});\n```\n\n**工具函数 (`utils/`)**\n\n`toml-to-markdown-converter.ts` 提供 TOML 格式检测和转换功能：\n\n- `isTomlFormat(content: string): boolean` - 检测内容是否为 TOML 格式\n\n资料来源：[packages/core/src/memory/prompt.ts:1-30]()\n\n### docs-site\n\n文档站点基于 Next.js 和 Nextra 构建，提供项目文档的 Web 展示。\n\n```\ndocs-site/\n├── src/\n│   └── app/\n│       ├── [[...mdxPath]]/        # 动态 MDX 路由\n│       │   └── page.jsx\n│       └── layout.jsx             # 根布局\n├── mdx-components.js               # MDX 组件配置\n├── next.config.mjs                # Next.js 配置\n└── package.json\n```\n\n文档内容通过符号链接从 `../docs` 目录挂载：\n\n```bash\nnpm run link  # 创建符号链接\nnpm run dev   # 启动开发服务器\n```\n\n资料来源：[docs-site/README.md:1-40]()\n\n## 依赖关系图\n\n```mermaid\ngraph TD\n    A[docs-site] --> B[docs]\n    C[CLI] --> D[Core]\n    C --> E[WebUI]\n    E --> D\n    F[webui] --> G[Core]\n    \n    style A fill:#e1f5fe\n    style C fill:#fff3e0\n    style E fill:#f3e5f5\n    style G fill:#e8f5e9\n```\n\n## 技术栈总结\n\n| 层级 | 技术选型 |\n|------|----------|\n| 基础语言 | TypeScript |\n| 前端框架 | React 18+ |\n| 构建工具 | Vite (webui) / Next.js (docs) |\n| UI 框架 | Tailwind CSS |\n| 组件测试 | Storybook |\n| 国际化 | 自定义 i18n 方案 |\n| 包管理 | npm |\n\n## 许可证\n\nQwen Code 项目采用 Apache-2.0 许可证发布。\n\n资料来源：[packages/webui/README.md:60]()\n\n---\n\n**注意**：以上包结构基于仓库中实际存在的文件和目录结构整理。部分高级包（如 `channels/`、`sdk-typescript/`、`sdk-python/`、`sdk-java/`）在当前代码快照中未包含详细源码，如需深入了解请查阅对应子包的完整源码。\n\n---\n\n<a id='agent-runtime'></a>\n\n## 智能体运行时\n\n### 相关页面\n\n相关主题：[工具系统](#tool-system), [模型集成](#model-integration), [会话管理](#session-management)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx)\n- [packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx)\n- [packages/cli/src/ui/components/messages/ToolGroupMessage.test.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/messages/ToolGroupMessage.test.tsx)\n- [packages/cli/src/ui/components/StatsDisplay.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/StatsDisplay.tsx)\n- [packages/cli/src/ui/contexts/UIActionsContext.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/contexts/UIActionsContext.tsx)\n- [packages/core/src/memory/prompt.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/memory/prompt.ts)\n</details>\n\n# 智能体运行时\n\n## 概述\n\n智能体运行时（Agent Runtime）是 Qwen Code 系统中负责协调和管理智能体（Agent）生命周期、任务执行、工具调用的核心模块。它提供了智能体的交互式执行环境、后台任务管理、权限控制、以及运行时状态监控等功能。智能体运行时与 UI 层紧密集成，通过事件驱动的架构实现用户与智能体之间的实时交互。\n\n智能体运行时的设计目标是为 AI 编程助手提供一个可扩展、安全且响应迅速的执行环境，支持单智能体任务执行和多智能体协作（如 Arena 对战模式）。\n\n## 核心架构\n\n### 组件层次\n\n```mermaid\ngraph TD\n    subgraph \"UI 层\"\n        ArenaSelectDialog[Arena 选择对话框]\n        BackgroundTasksDialog[后台任务对话框]\n        StatsDisplay[统计信息显示]\n    end\n    \n    subgraph \"状态管理层\"\n        UIActionsContext[UI 操作上下文]\n        AgentViewContext[智能体视图上下文]\n    end\n    \n    subgraph \"运行时核心\"\n        AgentCore[智能体核心]\n        ToolScheduler[工具调度器]\n        PermissionFlow[权限流程]\n    end\n    \n    subgraph \"执行层\"\n        ToolCalls[工具调用]\n        SubAgents[子智能体]\n        Monitors[监控器]\n    end\n    \n    ArenaSelectDialog --> UIActionsContext\n    BackgroundTasksDialog --> UIActionsContext\n    UIActionsContext --> AgentCore\n    AgentCore --> ToolScheduler\n    AgentCore --> PermissionFlow\n    ToolScheduler --> ToolCalls\n    AgentCore --> SubAgents\n    AgentCore --> Monitors\n```\n\n### 智能体状态模型\n\n智能体运行时通过 `AgentResultDisplay` 类型定义智能体的执行状态：\n\n| 状态值 | 含义 | UI 显示 |\n|--------|------|---------|\n| `running` | 任务正在执行中 | 显示进度条和活动指示器 |\n| `completed` | 任务已完成 | 显示成功状态和结果摘要 |\n| `failed` | 任务执行失败 | 显示错误信息 |\n| `cancelled` | 任务被取消 | 显示取消状态 |\n\n资料来源：[packages/cli/src/ui/components/messages/ToolGroupMessage.test.tsx:9-25]()\n\n```typescript\ninterface AgentResultDisplay {\n  type: 'task_execution';\n  subagentName: string;\n  taskDescription: string;\n  taskPrompt: string;\n  status: 'running' | 'completed' | 'failed' | 'cancelled';\n  toolCalls: ToolCall[];\n}\n```\n\n## 任务执行机制\n\n### 工具调用链\n\n智能体运行时通过 `ToolCall` 结构管理所有工具调用操作。每个工具调用包含唯一标识符、调用名称、执行状态和结果描述。\n\n```mermaid\ngraph LR\n    UserInput[用户输入] --> AgentCore\n    AgentCore --> ToolScheduler\n    ToolScheduler --> Tool1[工具: read_file]\n    ToolScheduler --> Tool2[工具: write_file]\n    ToolScheduler --> Tool3[工具: bash]\n    Tool1 --> Result1[成功/失败]\n    Tool2 --> Result2[成功/失败]\n    Tool3 --> Result3[成功/失败]\n    Result1 --> StatsDisplay[统计显示]\n    Result2 --> StatsDisplay\n    Result3 --> StatsDisplay\n```\n\n### 工具调用数据结构\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `callId` | string | 唯一调用标识符 |\n| `name` | string | 工具名称（如 `read_file`、`agent`） |\n| `status` | ToolCallStatus | 执行状态（executing、success、error） |\n| `description` | string | 调用描述信息 |\n| `resultDisplay` | AgentResultDisplay | 子智能体结果展示（可选） |\n\n资料来源：[packages/cli/src/ui/components/messages/ToolGroupMessage.test.tsx:27-34]()\n\n### 子智能体任务\n\n当智能体调用 `agent` 工具时，运行时会创建子智能体任务。子智能体继承父智能体的上下文，可以独立执行特定任务：\n\n```typescript\n// 子智能体任务创建示例\n{\n  type: 'task_execution',\n  subagentName: 'reviewer',\n  taskDescription: 'reviewer task',\n  taskPrompt: 'Run reviewer',\n  status: 'running',\n  toolCalls: [\n    {\n      callId: 'reviewer-read-1',\n      name: 'read_file',\n      status: 'success',\n      description: 'Read file'\n    }\n  ]\n}\n```\n\n子智能体运行时保持了焦点机制，使 Ctrl+E 快捷键可以展开查看详细信息。运行中的子智能体显示为 `focused=true`，而完成的子智能体可以正常折叠。\n\n资料来源：[packages/cli/src/ui/components/messages/ToolGroupMessage.test.tsx:63-68]()\n\n## Arena 模式\n\n### Arena 选择对话框\n\nArena 是 Qwen Code 支持的多智能体对战模式。用户可以通过 Arena 选择对话框选择不同的智能体进行对比测试或对战。\n\n```mermaid\ngraph TD\n    UserOpen[打开 Arena 对话框] --> ArenaSelectDialog\n    ArenaSelectDialog --> FetchAgents[获取智能体列表]\n    FetchAgents --> FilterAgents[筛选成功状态的智能体]\n    FilterAgents --> DisplayList[显示智能体列表]\n    DisplayList --> UserSelect{用户选择}\n    UserSelect -->|选中| RunComparison[运行对比]\n    UserSelect -->|Escape| CloseDialog[关闭对话框]\n    RunComparison --> ShowResults[展示结果]\n```\n\n### 智能体选择状态\n\nArena 对话框中的每个智能体选项显示以下信息：\n\n| 显示字段 | 数据来源 | 说明 |\n|----------|----------|------|\n| 状态图标 | `statusInfo.color` / `statusInfo.text` | 根据状态着色 |\n| 执行时长 | `duration` | 任务耗时 |\n| Token 数量 | `tokens` | 消耗的 Token 数 |\n| 文件数量 | `fileCount` | 涉及的文件数 |\n| 代码变更 | `diffAdditions` / `diffDeletions` | 新增/删除行数 |\n\n资料来源：[packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx:1-22]()\n\n### 快捷键绑定\n\nArena 对话框支持以下键盘交互：\n\n| 快捷键 | 功能 |\n|--------|------|\n| `Escape` | 关闭 Arena 对话框 |\n| `P` | 切换预览视图（Show/Hide Preview） |\n| `D` | 切换详细 Diff 视图 |\n\n资料来源：[packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx:39-50]()\n\n### Arena 操作上下文\n\nArena 相关的操作通过 `UIActionsContext` 统一管理：\n\n| 方法 | 功能 |\n|------|------|\n| `openArenaDialog(type)` | 打开指定类型的 Arena 对话框 |\n| `closeArenaDialog()` | 关闭 Arena 对话框 |\n| `handleArenaModelsSelected(models)` | 处理用户选择的模型列表 |\n\n资料来源：[packages/cli/src/ui/contexts/UIActionsContext.tsx:31-33]()\n\n## 后台任务管理\n\n### 后台任务对话框\n\nBackgroundTasksDialog 组件负责展示和管理后台运行的智能体任务，包括长时间运行的任务、监控事件和会话状态。\n\n```mermaid\ngraph TD\n    Entry[任务条目] --> CheckStatus{状态检查}\n    CheckStatus -->|有错误| ShowError[显示错误信息]\n    CheckStatus -->|有警告| ShowWarning[显示警告信息]\n    CheckStatus -->|正常| CheckTopics{有主题?}\n    CheckTopics -->|是| ShowTopics[显示触及的主题]\n    CheckTopics -->|否| CheckProgress{有进度?}\n    CheckProgress -->|是| ShowProgress[显示进度文本]\n    ShowTopics --> DisplaySummary[显示摘要]\n    ShowProgress --> DisplaySummary\n    ShowWarning --> DisplaySummary\n```\n\n### 任务状态展示\n\n| 组件 | 显示内容 | 样式 |\n|------|----------|------|\n| 状态文本 | 状态描述文字 | 根据状态着色 |\n| Sessions reviewing | 活跃会话数 | 加粗、次要颜色 |\n| Progress | 进度文本 | 单独区块 |\n| Topics touched | 涉及的主题列表 | 缩进列表形式 |\n| Error | 错误信息 | 红色高亮 |\n| Lock release warning | 锁释放警告 | 黄色警告色 |\n\n资料来源：[packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx:1-80]()\n\n### 锁释放错误处理\n\n当任务执行过程中出现锁释放错误时，系统会显示专门的警告信息：\n\n```\nLock release warning: <错误描述>\nSubsequent dreams may be skipped as locked until the next session's staleness sweep cleans the file.\n```\n\n这种设计确保终端状态保持为\"已完成\"，同时通过警告形式解释后续任务可能被跳过的原因。\n\n资料来源：[packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx:37-50]()\n\n## 监控器系统\n\n### 监控通知机制\n\n智能体运行时支持监控器（Monitor）功能，用于追踪长时间运行的任务和事件流。监控通知通过 XML 格式的回调函数传递：\n\n```typescript\ntype MonitorNotificationCallback = (\n  displayText: string,        // 显示给用户的文本\n  modelText: string,          // 模型原始文本\n  meta: {\n    monitorId: string;        // 监控器 ID\n    toolUseId?: string;       // 关联的工具调用 ID\n    status: 'running' | 'completed' | 'failed' | 'cancelled';\n    eventCount: number;       // 事件计数\n  }\n) => void;\n```\n\n### 监控通知 XML 格式\n\n```xml\n<task-notification>\n  <task-id>mon_1</task-id>\n  <kind>monitor</kind>\n  <status>running</status>\n  <summary>Monitor emitted event #1.</summary>\n  <result>ready</result>\n</task-notification>\n```\n\n### 监控器生命周期\n\n| 状态 | 含义 |\n|------|------|\n| `running` | 监控器正在运行，持续接收事件 |\n| `completed` | 监控任务已完成 |\n| `failed` | 监控执行失败 |\n| `cancelled` | 监控被用户取消 |\n\n资料来源：[packages/cli/src/nonInteractiveCli.test.ts:1-50]()\n\n## 性能统计\n\n### 统计信息显示\n\nStatsDisplay 组件展示智能体运行时的性能指标：\n\n| 指标类别 | 具体指标 | 说明 |\n|----------|----------|------|\n| **代码变更** | totalLinesAdded / totalLinesRemoved | 新增和删除的代码行数 |\n| **时间统计** | Wall Time | 墙上时钟时间 |\n| | Agent Active Time | 智能体活跃时间 |\n| | API Time | API 调用耗时及占比 |\n| | Tool Time | 工具执行耗时及占比 |\n| **缓存效率** | totalCachedTokens | 缓存的 Token 总数 |\n| | cacheEfficiency | 缓存命中率 |\n\n资料来源：[packages/cli/src/ui/components/StatsDisplay.tsx:1-50]()\n\n### 百分比计算\n\n性能统计中的百分比通过以下公式计算：\n\n```\napiTimePercent = (totalApiTime / agentActiveTime) × 100\ntoolTimePercent = (totalToolTime / agentActiveTime) × 100\ncacheEfficiency = (cachedTokens / totalTokens) × 100\n```\n\n## 权限与安全\n\n### 权限流程\n\n智能体运行时通过 PermissionFlow 模块管理工具调用的权限请求。当智能体尝试执行受限操作（如文件写入、终端命令）时，系统会弹出权限请求对话框。\n\n| 权限模式 | 说明 |\n|----------|------|\n| 授权所有 | 自动批准所有权限请求 |\n| 逐个确认 | 每个权限请求都需要用户确认 |\n| 拒绝所有 | 拒绝所有权限请求 |\n\n资料来源：[packages/core/src/core/permissionFlow.ts]()\n\n### 设置作用域\n\n权限和其他设置支持两种作用域：\n\n| 作用域 | 说明 |\n|--------|------|\n| `project` | 项目级别设置（`.qwen/` 目录） |\n| `user` | 用户级别设置（`~/.qwen/` 目录） |\n\n## 配置与扩展\n\n### MCP 服务器集成\n\n智能体运行时支持 MCP（Model Context Protocol）服务器扩展。运行时通过 `mcpServers` 配置连接外部工具服务：\n\n| 配置项 | 说明 |\n|--------|------|\n| `path` | MCP 服务器路径 |\n| `source` | 安装来源 |\n| `commands` | 可用命令列表 |\n| `status` | 连接状态（connected/disconnected） |\n\n资料来源：[packages/cli/src/ui/components/extensions/steps/ExtensionDetailStep.tsx:1-40]()\n\n### MCP 服务器状态处理\n\n当存在断开的 MCP 服务器时，系统显示提示信息：\n\n```\n※ Run qwen --debug to see error logs\n```\n\n资料来源：[packages/cli/src/ui/components/mcp/steps/ServerListStep.tsx:1-30]()\n\n## 总结\n\n智能体运行时是 Qwen Code 系统的核心执行引擎，它协调管理智能体的生命周期、任务调度、工具调用、权限控制和状态监控。该系统通过以下特性提供可靠的 AI 编程辅助体验：\n\n- **状态驱动**：清晰的状态模型支持 UI 层实时反映任务执行状态\n- **工具调度**：统一的工具调度器管理所有工具调用和子智能体任务\n- **Arena 模式**：支持多智能体对比和协作\n- **后台任务**：长时间运行任务的后台管理，减少对主界面的干扰\n- **监控通知**：实时事件通知机制，支持长时间任务的追踪\n- **性能统计**：详细的运行时性能指标，帮助用户了解资源消耗\n\n---\n\n<a id='tool-system'></a>\n\n## 工具系统\n\n### 相关页面\n\n相关主题：[智能体运行时](#agent-runtime)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/arena/ArenaSelectDialog.tsx)\n- [packages/cli/src/ui/components/extensions/steps/ExtensionDetailStep.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/extensions/steps/ExtensionDetailStep.tsx)\n- [packages/cli/src/ui/components/mcp/steps/ToolListStep.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/mcp/steps/ToolListStep.tsx)\n- [packages/cli/src/ui/components/views/McpStatus.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/views/McpStatus.tsx)\n- [packages/cli/src/ui/components/arena/ArenaCards.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/arena/ArenaCards.tsx)\n- [packages/cli/src/ui/components/views/ContextUsage.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/views/ContextUsage.tsx)\n- [packages/cli/src/ui/keyMatchers.test.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/keyMatchers.test.ts)\n- [packages/cli/src/ui/components/subagents/create/CreationSummary.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/subagents/create/CreationSummary.tsx)\n</details>\n\n# 工具系统\n\n## 概述\n\nQwen Code 的工具系统是整个代码智能助手的核心能力模块，它为 AI Agent 提供了与代码库、文件系统、外部服务交互的能力。该系统支持多种类型的工具调用，包括内置工具（如 Shell 执行、文件编辑、LSP 通信）、MCP（Model Context Protocol）服务器工具以及子代理（Subagent）自定义工具。\n\n工具系统在 UI 层通过 `ToolListStep` 组件呈现交互式列表界面，支持工具搜索、选择、滚动浏览等功能。同时，工具使用情况会在 `ContextUsage` 组件中单独统计，显示每个工具消耗的 token 数量。资料来源：[packages/cli/src/ui/components/mcp/steps/ToolListStep.tsx:1-80](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/mcp/steps/ToolListStep.tsx)，[packages/cli/src/ui/components/views/ContextUsage.tsx:1-100](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/views/ContextUsage.tsx)\n\n---\n\n## 架构设计\n\n### 系统分层\n\n工具系统采用分层架构设计，从底层到上层依次为：\n\n```mermaid\ngraph TD\n    A[工具定义层] --> B[工具注册层]\n    B --> C[工具执行层]\n    C --> D[UI 展示层]\n    \n    A1[内置工具<br/>Shell/Edit/LSP] --> A\n    A2[MCP 服务器工具] --> A\n    A3[子代理自定义工具] --> A\n```\n\n### 工具分类\n\n根据工具的来源和用途，系统中的工具可分为以下几类：\n\n| 类别 | 说明 | 典型示例 |\n|------|------|----------|\n| 内置工具 | 系统核心能力，硬编码实现 | Shell、Edit、LSP |\n| MCP 工具 | 通过 MCP 协议扩展的工具 | 文件系统、Git、数据库等 |\n| 子代理工具 | 用户自定义子代理暴露的工具 | 用户定义的各类能力 |\n| 技能工具 | 预定义的技能集成 | 代码搜索、测试生成等 |\n\n资料来源：[packages/cli/src/ui/components/subagents/create/CreationSummary.tsx:1-50](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/subagents/create/CreationSummary.tsx)\n\n---\n\n## 工具注册机制\n\n### 工具注册表\n\n工具通过注册表模式进行统一管理，确保工具的可用性、唯一性和可发现性。注册表维护了所有已注册工具的元数据，包括工具名称、描述、参数模式和有效性状态。\n\n### 工具验证\n\n每个工具在注册时都会经过验证流程：\n\n```mermaid\ngraph LR\n    A[工具注册] --> B{参数校验}\n    B -->|通过| C[标记有效]\n    B -->|失败| D[标记无效<br/>记录原因]\n    C --> E[可用]\n    D --> F[禁用显示警告]\n```\n\n工具的有效性状态直接影响其在 UI 中的展示方式：\n\n```tsx\n// 工具列表中无效工具的显示逻辑\n{!tool.isValid && (\n  <Text color={theme.status.warning}>\n    {t('invalid: {{reason}}', {\n      reason: tool.invalidReason || t('unknown'),\n    })}\n  </Text>\n)}\n```\n\n资料来源：[packages/cli/src/ui/components/mcp/steps/ToolListStep.tsx:45-52](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/mcp/steps/ToolListStep.tsx)\n\n---\n\n## 内置工具\n\n### Shell 工具\n\nShell 工具提供了在宿主系统上执行命令的能力，是 AI Agent 与操作系统交互的主要通道。\n\n### Edit 工具\n\nEdit 工具负责文件内容的读取、创建、修改和删除操作，是代码修改的核心能力。\n\n### LSP 工具\n\nLSP（Language Server Protocol）工具集成了语言服务器协议，提供了代码补全、跳转到定义、查找引用等 IDE 级别的功能。\n\n---\n\n## MCP 工具集成\n\n### MCP 协议概述\n\nMCP（Model Context Protocol）是一种标准化的工具扩展协议，允许第三方服务通过标准接口向 Qwen Code 提供工具能力。\n\n### MCP 服务器配置\n\nMCP 服务器在 `ExtensionDetailStep` 组件中展示，包括以下配置项：\n\n| 配置项 | 说明 |\n|--------|------|\n| `name` | 服务器名称 |\n| `version` | 服务器版本 |\n| `path` | 服务器路径 |\n| `source` | 安装来源 |\n| `mcpServers` | 包含的服务器列表 |\n\n```tsx\n{ext.mcpServers && Object.keys(ext.mcpServers).length > 0 && (\n  <Box>\n    <Box width={LABEL_WIDTH} flexShrink={0}>\n      <Text color={theme.text.primary}>{t('MCP Servers:')}</Text>\n    </Box>\n    <Text>{Object.keys(ext.mcpServers).join(', ')}</Text>\n  </Box>\n)}\n```\n\n资料来源：[packages/cli/src/ui/components/extensions/steps/ExtensionDetailStep.tsx:30-45](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/extensions/steps/ExtensionDetailStep.tsx)\n\n### MCP 工具使用\n\n在 Agent Arena 界面中，MCP 工具的使用情况会详细展示：\n\n```tsx\n{agent.toolCalls > 0 && (\n  <Text color={theme.text.secondary}>\n    {agent.toolCalls === 1 ? '1 tool call)' : `${agent.toolCalls} tool calls)`}\n  </Text>\n)}\n```\n\n资料来源：[packages/cli/src/ui/components/arena/ArenaCards.tsx:1-50](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/arena/ArenaCards.tsx)\n\n---\n\n## 子代理工具\n\n### 子代理定义\n\n子代理是用户自定义的 AI Agent，具备独立的系统提示、工具集和描述信息。\n\n### 子代理工具配置\n\n创建子代理时可以为其配置以下工具属性：\n\n```tsx\n<Box>\n  <Text color={theme.text.primary}>{t('Tools: ')}</Text>\n  <Text>{toolsDisplay}</Text>\n</Box>\n```\n\n子代理支持选择性地启用或禁用特定工具，工具配置存储在子代理定义文件中，位于项目级（`.qwen/agents/`）或用户级（`~/.qwen/agents/`）目录。资料来源：[packages/cli/src/ui/components/subagents/create/CreationSummary.tsx:15-25](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/subagents/create/CreationSummary.tsx)\n\n---\n\n## 工具展示界面\n\n### 工具列表视图\n\n`ToolListStep` 组件提供了交互式工具列表界面：\n\n| 功能 | 说明 |\n|------|------|\n| 工具名称显示 | 固定宽度列，支持截断显示 |\n| 选择指示器 | `❯` 符号标识当前选中 |\n| 无效警告 | 显示工具验证失败的原因 |\n| 滚动提示 | 显示当前索引和总数 |\n| 键盘导航 | 支持上下箭头选择 |\n\n```tsx\n// 滚动提示的显示逻辑\n{tools.length > VISIBLE_TOOLS_COUNT && (\n  <Box marginTop={1}>\n    <Text color={theme.text.secondary}>\n      {scrollOffset > 0 ? '↑ ' : '  '}\n      {t('{{current}}/{{total}}', {\n        current: (selectedIndex + 1).toString(),\n        total: tools.length.toString(),\n      })}\n      {scrollOffset + VISIBLE_TOOLS_COUNT < tools.length ? ' ↓' : ''}\n    </Text>\n  </Box>\n)}\n```\n\n资料来源：[packages/cli/src/ui/components/mcp/steps/ToolListStep.tsx:65-78](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/mcp/steps/ToolListStep.tsx)\n\n### MCP 状态视图\n\n`McpStatus` 组件展示了 MCP 工具的详细使用说明：\n\n```tsx\n<Text>- {t('Use')} <Text color={theme.text.accent}>/mcp</Text> {t('to list all available tools')}</Text>\n<Text>- {t('Use')} <Text color={theme.text.accent}>/mcp schema</Text> {t('to show tool parameter schemas')}</Text>\n<Text>- {t('Use')} <Text color={theme.text.accent}>/mcp nodesc</Text> {t('to hide descriptions')}</Text>\n<Text>- {t('Use')} <Text color={theme.text.accent}>/mcp auth &lt;server-name&gt;</Text> {t('to authenticate with OAuth-enabled servers')}</Text>\n```\n\n资料来源：[packages/cli/src/ui/components/views/McpStatus.tsx:1-30](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/views/McpStatus.tsx)\n\n### 上下文使用统计\n\n`ContextUsage` 组件将工具使用情况纳入上下文统计：\n\n```tsx\n{/* MCP Tools detail */}\n{sortedMcpTools.length > 0 && (\n  <Box flexDirection=\"column\" marginTop={1}>\n    <Text bold color={theme.text.primary}>\n      {t('MCP tools')}\n    </Text>\n    {sortedMcpTools.map((tool) => (\n      <DetailRow\n        key={tool.name}\n        name={tool.name}\n        tokens={tool.tokens}\n      />\n    ))}\n  </Box>\n)}\n```\n\n资料来源：[packages/cli/src/ui/components/views/ContextUsage.tsx:40-55](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/views/ContextUsage.tsx)\n\n---\n\n## 键盘快捷键\n\n工具系统支持以下键盘快捷键操作：\n\n| 快捷键 | 功能 |\n|--------|------|\n| `Ctrl+T` | 切换工具描述显示/隐藏 |\n| `Ctrl+G` | 切换 IDE 上下文详情 |\n| `↑/↓` | 导航工具列表 |\n| `Escape` | 关闭工具对话框 |\n| `Tab` 或 `Enter` | 接受工具建议 |\n\n```ts\n[Command.TOGGLE_TOOL_DESCRIPTIONS]: (key: Key) =>\n  key.ctrl && key.name === 't',\n[Command.TOGGLE_IDE_CONTEXT_DETAIL]: (key: Key) =>\n  key.ctrl && key.name === 'g',\n```\n\n资料来源：[packages/cli/src/ui/keyMatchers.test.ts:1-50](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/keyMatchers.test.ts)\n\n---\n\n## Arena 场景中的工具使用\n\n在 Agent Arena 对比场景中，工具使用情况会被详细记录和展示：\n\n```mermaid\ngraph LR\n    A[Agent 执行] --> B[工具调用]\n    B --> C{工具类型}\n    C -->|Shell| D[命令执行]\n    C -->|Edit| E[文件修改]\n    C -->|MCP| F[外部服务]\n    \n    D --> G[统计面板]\n    E --> G\n    F --> G\n```\n\nArena 界面展示每个 Agent 的工具调用统计：\n\n- **工具调用次数**：显示每个 Agent 执行了多少次工具调用\n- **Token 效率**：统计总 token 消耗和运行时长\n- **Diff 统计**：显示代码变更的行数（新增/删除）\n\n```tsx\n<Box flexDirection=\"column\">\n  <Text bold color={theme.text.primary}>\n    Token Efficiency:\n  </Text>\n  {agents.map((agent, index) => (\n    <Box key={agent.label} marginLeft={2}>\n      <Text color={theme.text.secondary}>\n        {index === agents.length - 1 ? '└─' : '├─'} {agent.label}:{' '}\n      </Text>\n      <Text color={theme.text.primary}>\n        {agent.totalTokens.toLocaleString()} tokens · runtime {formatDuration(agent.durationMs)}\n      </Text>\n    </Box>\n  ))}\n</Box>\n```\n\n资料来源：[packages/cli/src/ui/components/arena/ArenaCards.tsx:50-70](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/arena/ArenaCards.tsx)\n\n---\n\n## 扩展性设计\n\n### 工具扩展点\n\n工具系统设计了多个扩展点以支持第三方集成：\n\n1. **MCP 服务器插件**：通过 MCP 协议接入外部工具服务\n2. **子代理自定义**：用户可定义专属工具集\n3. **内置工具扩展**：系统内置工具支持扩展配置\n\n### 错误处理\n\n工具执行过程中的错误会通过统一的错误展示界面呈现：\n\n```tsx\n{hasError && (\n  <Fragment>\n    <Box />\n    <Box>\n      <Text bold color={theme.status.error}>\n        {t('Error')}\n      </Text>\n    </Box>\n    <Box>\n      <Text color={theme.status.error} wrap=\"wrap\">\n        {entry.error}\n      </Text>\n    </Box>\n  </Fragment>\n)}\n```\n\n---\n\n## 配置管理\n\n### 工具配置文件\n\n工具系统的配置通过以下位置管理：\n\n| 配置位置 | 范围 | 说明 |\n|----------|------|------|\n| `.qwen/agents/` | 项目级 | 项目专属工具配置 |\n| `~/.qwen/agents/` | 用户级 | 全局工具配置 |\n\n### 工具描述控制\n\n工具描述的显示可通过命令行参数控制：\n\n- `/mcp` - 列出所有可用工具\n- `/mcp schema` - 显示工具参数模式\n- `/mcp nodesc` - 隐藏工具描述\n- `Ctrl+T` - 切换工具描述显示\n\n---\n\n## 总结\n\nQwen Code 的工具系统采用了模块化、分层式的架构设计，通过统一的注册机制管理内置工具、MCP 工具和子代理工具。系统提供了丰富的 UI 组件用于工具的展示、选择和统计，同时支持通过键盘快捷键进行高效操作。工具系统的扩展性设计使得第三方服务能够方便地通过 MCP 协议接入，为 AI Agent 提供更强大的能力。\n\n---\n\n<a id='model-integration'></a>\n\n## 模型集成\n\n### 相关页面\n\n相关主题：[智能体运行时](#agent-runtime), [快速入门](#quick-start)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/src/core/openaiContentGenerator/openaiContentGenerator.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/core/openaiContentGenerator/openaiContentGenerator.ts)\n- [packages/core/src/core/openaiContentGenerator/provider/dashscope.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/core/openaiContentGenerator/provider/dashscope.ts)\n- [packages/core/src/core/openaiContentGenerator/provider/openrouter.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/core/openaiContentGenerator/provider/openrouter.ts)\n- [packages/core/src/core/geminiChat.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/core/geminiChat.ts)\n- [packages/core/src/core/anthropicContentGenerator/anthropicContentGenerator.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/core/anthropicContentGenerator/anthropicContentGenerator.ts)\n- [README.md](https://github.com/QwenLM/qwen-code/blob/main/README.md)\n- [packages/core/src/memory/extractionAgentPlanner.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/memory/extractionAgentPlanner.ts)\n</details>\n\n# 模型集成\n\n## 概述\n\n模型集成是 Qwen Code 框架的核心子系统，负责与各类大语言模型（LLM）提供商建立通信连接、发送请求并处理响应。该系统通过统一的内容生成器接口抽象不同提供商的实现细节，使上层业务逻辑能够以一致的方式调用各种模型服务。资料来源：[packages/core/src/core/openaiContentGenerator/openaiContentGenerator.ts]()\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n    A[业务层] --> B[ContentGenerator 接口]\n    B --> C[OpenAI ContentGenerator]\n    B --> D[Anthropic ContentGenerator]\n    B --> E[Gemini Chat]\n    C --> F[Provider 层]\n    F --> G[DashScope Provider]\n    F --> H[OpenRouter Provider]\n    F --> I[OpenAI Compatible Provider]\n```\n\n### 核心接口抽象\n\n系统定义了统一的内容生成器接口，所有具体实现必须遵循该契约：\n\n| 接口方法 | 功能描述 | 参数 |\n|---------|---------|------|\n| `generate(prompt, options)` | 生成内容 | 提示词、生成配置 |\n| `stream(prompt, options)` | 流式生成 | 提示词、生成配置 |\n| `getModel()` | 获取当前模型 | 无 |\n| `getName()` | 获取生成器名称 | 无 |\n\n资料来源：[packages/core/src/core/openaiContentGenerator/openaiContentGenerator.ts:30-80]()\n\n## Provider 实现体系\n\n### DashScope Provider（阿里云）\n\nDashScope 是阿里云提供的大模型服务，Qwen Code 通过专门的 Provider 进行集成：\n\n```typescript\n// packages/core/src/core/openaiContentGenerator/provider/dashscope.ts\nexport class DashScopeProvider implements ModelProvider {\n  readonly baseUrl = 'https://dashscope.aliyuncs.com/compatible-mode/v1';\n  \n  async chat(params: ChatParams): Promise<ChatResponse> {\n    // 实现与阿里云 DashScope API 的通信\n  }\n}\n```\n\n**配置示例：**\n\n```json\n{\n  \"modelProviders\": {\n    \"openai\": [\n      {\n        \"id\": \"qwen3.6-plus\",\n        \"name\": \"qwen3.6-plus (Coding Plan)\",\n        \"baseUrl\": \"https://coding.dashscope.aliyuncs.com/v1\",\n        \"description\": \"qwen3.6-plus from ModelStudio Coding Plan\",\n        \"envKey\": \"BAILIAN_CODING_PLAN_API_KEY\"\n      }\n    ]\n  }\n}\n```\n\n资料来源：[packages/core/src/core/openaiContentGenerator/provider/dashscope.ts]()\n\n### OpenRouter Provider\n\nOpenRouter 提供对多种模型的统一访问接口：\n\n```typescript\n// packages/core/src/core/openaiContentGenerator/provider/openrouter.ts\nexport class OpenRouterProvider implements ModelProvider {\n  readonly baseUrl = 'https://openrouter.ai/api/v1';\n  \n  async chat(params: ChatParams): Promise<ChatResponse> {\n    // 实现与 OpenRouter API 的通信\n  }\n}\n```\n\n资料来源：[packages/core/src/core/openaiContentGenerator/provider/openrouter.ts]()\n\n### OpenAI 兼容 Provider\n\n通用的 OpenAI API 兼容实现，可连接任何遵循 OpenAI API 规范的服务：\n\n```mermaid\ngraph LR\n    A[请求] --> B[OpenAI Compatible Provider]\n    B --> C{目标服务}\n    C --> D[本地部署模型]\n    C --> E[vLLM]\n    C --> F[Ollama]\n    C --> G[其他兼容服务]\n```\n\n**vLLM 配置示例：**\n\n```json\n{\n  \"modelProviders\": {\n    \"openai\": [\n      {\n        \"id\": \"Qwen/Qwen3-32B\",\n        \"name\": \"Qwen3 32B (vLLM)\",\n        \"baseUrl\": \"http://localhost:8000/v1\",\n        \"description\": \"Qwen3 32B running locally via vLLM\",\n        \"generationConfig\": {\n          \"contextWindowSize\": 131072\n        }\n      }\n    ]\n  }\n}\n```\n\n**Ollama 配置示例：**\n\n```json\n{\n  \"modelProviders\": {\n    \"openai\": [\n      {\n        \"id\": \"qwen3:32b\",\n        \"name\": \"Qwen3 32B (Ollama)\",\n        \"baseUrl\": \"http://localhost:11434/v1\",\n        \"description\": \"Qwen3 32B running locally via Ollama\",\n        \"generationConfig\": {\n          \"contextWindowSize\": 131072\n        }\n      }\n    ]\n  }\n}\n```\n\n资料来源：[README.md:50-120]()\n\n## Anthropic Claude 集成\n\n### 内容生成器实现\n\nAnthropic Claude 通过专门的内容生成器进行集成：\n\n```typescript\n// packages/core/src/core/anthropicContentGenerator/anthropicContentGenerator.ts\nexport class AnthropicContentGenerator implements ContentGenerator {\n  private readonly client: Anthropic;\n  \n  async generate(\n    prompt: string,\n    options?: GenerationOptions\n  ): Promise<GenerationResult> {\n    const message = await this.client.messages.create({\n      model: this.model,\n      max_tokens: options?.maxTokens ?? 4096,\n      messages: [{ role: 'user', content: prompt }],\n    });\n    \n    return {\n      content: message.content[0].text,\n      usage: {\n        inputTokens: message.usage.input_tokens,\n        outputTokens: message.usage.output_tokens,\n      },\n    };\n  }\n}\n```\n\n### 特性支持\n\n| 特性 | 支持状态 | 说明 |\n|-----|---------|------|\n| 标准生成 | ✅ 支持 | 基础文本生成能力 |\n| 流式输出 | ✅ 支持 | 支持 Server-Sent Events |\n| Thinking Mode | ✅ 支持 | Claude 3.7+ 支持思考模式 |\n| Tool Use | 🔄 计划中 | 工具调用功能 |\n\n资料来源：[packages/core/src/core/anthropicContentGenerator/anthropicContentGenerator.ts]()\n\n## Google Gemini 集成\n\n### 聊天实现\n\nGemini 通过专门的聊天模块进行集成：\n\n```typescript\n// packages/core/src/core/geminiChat.ts\nexport class GeminiChat {\n  private readonly model: GenerativeModel;\n  \n  async generateContent(\n    prompt: string,\n    config?: GenerationConfig\n  ): Promise<GenerateContentResult> {\n    const result = await this.model.generateContent(prompt);\n    return result;\n  }\n  \n  async streamGenerateContent(\n    prompt: string,\n    config?: GenerationConfig\n  ): Promise<AsyncIterable<string>> {\n    const result = await this.model.generateContentStream(prompt);\n    // 返回流式响应\n  }\n}\n```\n\n资料来源：[packages/core/src/core/geminiChat.ts]()\n\n## 配置管理\n\n### 配置文件结构\n\n模型集成通过 `~/.qwen/settings.json` 进行统一配置：\n\n```json\n{\n  \"modelProviders\": {\n    \"openai\": [...],\n    \"anthropic\": {\n      \"apiKey\": \"sk-...\"\n    },\n    \"google\": {\n      \"apiKey\": \"...\"\n    }\n  },\n  \"security\": {\n    \"auth\": {\n      \"selectedType\": \"openai\"\n    }\n  },\n  \"model\": {\n    \"name\": \"qwen3:32b\"\n  }\n}\n```\n\n### 模型切换\n\n用户可以通过 `/model` 命令在运行时切换不同模型：\n\n```bash\nqwen\n> /model qwen3.6-plus\n```\n\n资料来源：[README.md:100-150]()\n\n## 请求处理流程\n\n### 标准生成流程\n\n```mermaid\nsequenceDiagram\n    participant U as 用户\n    participant G as ContentGenerator\n    participant P as Provider\n    participant API as 外部API\n    \n    U->>G: generate(prompt, options)\n    G->>P: chat(params)\n    P->>API: HTTP POST /chat/completions\n    API-->>P: Response\n    P-->>G: ChatResponse\n    G-->>U: GenerationResult\n```\n\n### 错误处理\n\n| 错误类型 | 处理策略 | 重试机制 |\n|---------|---------|---------|\n| 网络超时 | 自动重试 | 3次指数退避 |\n| Rate Limit | 等待后重试 | 尊重 Retry-After |\n| 认证失败 | 提示用户 | 无重试 |\n| 服务不可用 | 切换 Provider | 如配置多 Provider |\n\n资料来源：[packages/core/src/core/openaiContentGenerator/openaiContentGenerator.ts:100-150]()\n\n## 与记忆系统的集成\n\n模型集成与记忆系统深度协作，支持上下文管理和持久化：\n\n```typescript\n// packages/core/src/memory/extractionAgentPlanner.ts\nasync function buildTopicSummaryBlock(projectRoot: string): Promise<string> {\n  const docs = await scanAutoMemoryTopicDocuments(projectRoot);\n  return docs.map((doc) => {\n    return [\n      `- [${doc.title}](${doc.relativePath})`,\n      `  topic=${doc.type}`,\n      `  current=${doc.body}`,\n    ].join('\\n');\n  }).join('\\n\\n');\n}\n```\n\n资料来源：[packages/core/src/memory/extractionAgentPlanner.ts:20-60]()\n\n## 总结\n\n模型集成模块是 Qwen Code 连接各类大语言模型服务的桥梁，通过标准化的 Provider 接口设计，系统能够灵活支持多种模型提供商，包括阿里云 DashScope、OpenRouter、OpenAI 兼容接口、Google Gemini 和 Anthropic Claude 等。该设计遵循开闭原则，便于后续扩展新的模型提供商。\n\n---\n\n<a id='memory-system'></a>\n\n## 记忆系统\n\n### 相关页面\n\n相关主题：[会话管理](#session-management), [技能与钩子系统](#skills-hooks)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/src/memory/manager.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/memory/manager.ts)\n- [packages/core/src/memory/recall.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/memory/recall.ts)\n- [packages/core/src/memory/extract.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/memory/extract.ts)\n- [packages/core/src/memory/indexer.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/memory/indexer.ts)\n- [packages/core/src/memory/dream.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/memory/dream.ts)\n- [packages/core/src/memory/prompt.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/memory/prompt.ts)\n- [packages/core/src/telemetry/metrics.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/telemetry/metrics.ts)\n</details>\n\n# 记忆系统\n\n## 概述\n\n记忆系统是 Qwen Code 的核心组件之一，负责在 AI 与用户的交互过程中自动捕获、存储和检索有用的上下文信息。该系统通过智能记忆提取、定期梦境整理和上下文召回三大机制，帮助 AI 保持对项目、用户偏好、外部系统引用等长期信息的感知能力。\n\n记忆系统的主要目标包括：\n\n- **减少重复信息传递**：用户无需反复告知 AI 相同的背景信息\n- **维护项目上下文**：保存项目相关的架构决策、外部依赖和重要约定\n- **个性化体验**：记住用户的偏好和工作习惯\n- **外部系统追踪**：记录对外部系统（如 Linear、Grafana）的引用关系\n\n资料来源：[packages/core/src/memory/prompt.ts:1-50]()\n\n## 系统架构\n\n记忆系统采用分层架构，包含五个核心模块，各模块职责分明、协同工作。\n\n```mermaid\ngraph TD\n    subgraph 记忆系统架构\n        A[记忆管理器<br/>manager.ts] --> B[提取模块<br/>extract.ts]\n        A --> C[召回模块<br/>recall.ts]\n        A --> D[梦境模块<br/>dream.ts]\n        A --> E[索引模块<br/>indexer.ts]\n    end\n    \n    subgraph 外部交互\n        E --> F[记忆存储<br/>文件系统]\n        F --> C\n        B --> G[对话历史]\n        D --> F\n    end\n    \n    style A fill:#e1f5fe\n    style F fill:#fff3e0\n```\n\n### 组件职责矩阵\n\n| 模块 | 文件 | 主要职责 |\n|------|------|----------|\n| manager.ts | 记忆管理器 | 协调各模块、初始化、配置管理 |\n| extract.ts | 提取模块 | 从对话中识别并提取需要记忆的信息 |\n| recall.ts | 召回模块 | 根据上下文检索相关记忆 |\n| dream.ts | 梦境模块 | 定期整理和强化记忆 |\n| indexer.ts | 索引模块 | 管理记忆文件的索引和元数据 |\n\n资料来源：[packages/core/src/memory/manager.ts](), [packages/core/src/memory/indexer.ts]()\n\n## 核心功能模块\n\n### 1. 记忆提取（Extract）\n\n记忆提取模块负责从对话历史中自动识别有价值的信息片段。该模块通过专门的提示词工程（Prompt Engineering）引导 AI 理解何时应该保存记忆、保存什么类型的信息。\n\n#### 提取的记忆类型\n\n根据 prompt.ts 中的定义，系统将记忆分为以下几类：\n\n```mermaid\ngraph LR\n    subgraph 记忆分类\n        A[user] --> E[用户偏好]\n        B[feedback] --> F[反馈信息]\n        C[project] --> G[项目信息]\n        D[reference] --> H[外部引用]\n    end\n    \n    style E fill:#c8e6c9\n    style F fill:#ffe0b2\n    style G fill:#bbdefb\n    style H fill:#e1bee7\n```\n\n**用户偏好（user/）**：存储用户的个人偏好、工作习惯和配置选择\n\n**反馈信息（feedback/）**：记录用户对 AI 回复的纠正和调整\n\n**项目信息（project/）**：保存项目相关的架构决策、技术选型和重要约定\n\n**外部引用（reference/）**：追踪对外部系统的引用（如缺陷追踪系统、监控系统）\n\n资料来源：[packages/core/src/memory/prompt.ts:1-80]()\n\n#### 提取时机与策略\n\n系统仅在特定情况下触发记忆提取：\n\n- **外部系统引用**：当用户提到 bugs 在 Linear 中跟踪或反馈在某个 Slack 频道时\n- **架构决策**：当用户描述项目的技术选型或设计模式时\n- **配置变更**：当用户修改了项目配置或工具设置时\n\n提取模块遵循以下原则：\n\n- 仅保存非显而易见的长期信息\n- 不保存代码模式、文件路径等可从代码库推导的内容\n- 不保存 Git 历史或调试解决方案（这些可通过 git log 等命令获取）\n- 保持每类记忆的唯一性，避免重复\n\n资料来源：[packages/core/src/memory/prompt.ts:85-100]()\n\n### 2. 记忆召回（Recall）\n\n召回模块是记忆系统的\"读取\"端，负责在需要时检索相关记忆。\n\n#### 召回流程\n\n```mermaid\nsequenceDiagram\n    participant AI as AI 代理\n    participant Recall as 召回模块\n    participant Index as 索引模块\n    participant Storage as 记忆存储\n    \n    AI->>Recall: 请求召回相关记忆\n    Recall->>Index: 查询索引\n    Index-->>Recall: 返回记忆文件列表\n    Recall->>Storage: 读取记忆内容\n    Storage-->>Recall: 返回记忆内容\n    Recall-->>AI: 提供相关上下文\n```\n\n#### 召回触发场景\n\n召回机制在以下场景被激活：\n\n1. **用户消息预处理**：在处理用户输入前，先检索可能相关的记忆\n2. **上下文窗口构建**：将相关记忆注入 AI 的上下文窗口\n3. **决策参考**：当 AI 需要做出影响用户的决策时获取背景信息\n\n资料来源：[packages/core/src/memory/recall.ts](), [packages/core/src/memory/indexer.ts]()\n\n### 3. 梦境模块（Dream）\n\n梦境模块是记忆系统的维护组件，定期对记忆进行整理和强化。\n\n#### 梦境机制\n\n```mermaid\ngraph TD\n    A[定时触发] --> B{锁定记忆文件}\n    B --> C[读取所有记忆]\n    C --> D[分析记忆关联性]\n    D --> E[强化重要记忆]\n    E --> F[清理过时信息]\n    F --> G[更新索引]\n    G --> H[释放文件锁]\n    \n    style A fill:#ffecb3\n    style H fill:#c8e6c9\n```\n\n#### 梦境行为说明\n\n- **文件锁定**：防止在整理过程中被其他进程修改\n- **关联分析**：识别记忆间的关联关系，优化检索效率\n- **强化机制**：对频繁访问的记忆增加访问优先级\n- **清理机制**：移除不再相关或已被覆盖的记忆条目\n\n> 注意：梦境操作可能导致锁释放失败或元数据写入失败。锁释放失败会使后续梦境被静默跳过，元数据写入失败可能导致调度器无法获取最新运行状态。\n\n资料来源：[packages/core/src/memory/dream.ts](), [packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx:50-75]()\n\n### 4. 索引管理（Indexer）\n\n索引模块负责维护记忆文件的元数据索引，支持高效的召回查询。\n\n#### 索引结构\n\n索引文件采用 Markdown 链接格式，每行代表一个记忆条目：\n\n```markdown\n- [记忆标题](relative/path.md) — 一句话描述\n```\n\n索引遵循以下规则：\n\n- 每个记忆文件必须有对应的索引条目\n- 索引条目必须包含标题、相对路径和一句话描述\n- 创建或删除记忆文件时必须同步更新索引\n- 索引本身不是记忆，内容不直接写入\n\n资料来源：[packages/core/src/memory/extractionAgentPlanner.ts:1-30](), [packages/core/src/memory/extractionAgentPlanner.ts:35-60]()\n\n## 记忆存储结构\n\n记忆系统使用文件系统存储记忆，每个记忆类别对应一个子目录：\n\n```\n~/.qwen/memory/\n├── user/           # 用户偏好记忆\n├── feedback/       # 用户反馈记忆\n├── project/        # 项目信息记忆\n├── reference/      # 外部引用记忆\n└── index.md        # 记忆索引文件\n```\n\n### 记忆文件格式\n\n记忆文件采用 Markdown 格式，包含 YAML frontmatter 元数据：\n\n```yaml\n---\ntitle: 记忆标题\ntype: reference\nwhen_to_save: 何时应保存此记忆\nhow_to_use: 如何使用此记忆\n---\n# 记忆正文内容\n```\n\n资料来源：[packages/core/src/memory/prompt.ts:20-55]()\n\n## 遥测指标\n\n记忆系统集成了完整的遥测（Telemetry）支持，便于监控和调试。\n\n### 记忆相关指标\n\n| 指标名称 | 类型 | 描述 |\n|----------|------|------|\n| `memory.extract.count` | 计数器 | 记忆提取次数 |\n| `memory.extract.duration` | 直方图 | 记忆提取耗时 |\n| `memory.dream.count` | 计数器 | 梦境执行次数 |\n| `memory.dream.duration` | 直方图 | 梦境执行耗时 |\n| `memory.recall.count` | 计数器 | 记忆召回次数 |\n| `memory.recall.duration` | 直方图 | 记忆召回耗时 |\n\n资料来源：[packages/core/src/telemetry/metrics.ts:1-25]()\n\n### 指标属性\n\n记忆指标支持以下维度属性：\n\n- **session.id**：当前会话标识\n- **function_name**：函数名称（提取时）\n- **model**：使用的模型名称\n- **status_code**：状态码\n- **error_type**：错误类型\n\n## 配置与扩展\n\n### 记忆系统配置\n\n记忆系统通过 Config 接口集成到主配置体系：\n\n```typescript\ninterface MemoryConfig {\n  getMemoryEnabled: () => boolean;\n  getMemoryRoot: () => string;\n  getSessionId: () => string;\n}\n```\n\n### 扩展点\n\n记忆系统提供以下扩展点：\n\n1. **自定义提取器**：可扩展提取规则以支持特定类型的记忆\n2. **存储后端**：可替换文件系统存储为数据库等后端\n3. **索引策略**：可自定义索引算法以优化召回效率\n4. **调度策略**：可调整梦境执行频率和触发条件\n\n## 使用示例\n\n### 触发记忆保存\n\n```\n用户: bugs are tracked in Linear project \"INGEST\"\n助手: [saves reference memory: pipeline bugs are tracked in Linear project \"INGEST\"]\n```\n\n### 触发记忆召回\n\n```\n用户: where do we track pipeline bugs?\n助手: [recalls reference memory] → 引用之前保存的 Linear 项目信息\n```\n\n### 记忆预览\n\n在 Web UI 的 ToolCallCard 组件中，记忆操作会显示为带有 💭 图标的卡片：\n\n```tsx\nexport const ThinkingCard: Story = {\n  args: {\n    icon: '💭',\n    children: (\n      <ToolCallRow label=\"SaveMemory\">\n        <div className=\"italic opacity-90\">\n          The user wants to refactor the authentication module...\n        </div>\n      </ToolCallRow>\n    ),\n  },\n};\n```\n\n资料来源：[packages/webui/src/components/toolcalls/shared/ToolCallCard.stories.tsx:1-30]()\n\n## 常见问题与排查\n\n### 梦境被跳过（Lock Release Warning）\n\n**症状**：后台任务显示 \"Lock release warning\"，后续梦境被静默跳过\n\n**原因**：文件锁定失败导致\n\n**解决方案**：等待下一个会话的过期清理机制（staleness sweep）清理锁文件\n\n### 调度器无法获取最新状态\n\n**症状**：调度器无法检测到最新的梦境运行状态\n\n**原因**：元数据写入失败\n\n**排查方向**：\n\n- 检查文件系统权限\n- 检查磁盘空间\n- 查看日志中的具体错误信息\n\n资料来源：[packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx:55-70]()\n\n## 相关文档\n\n- [记忆系统架构设计](./architecture/memory-system.md)\n- [上下文管理](./context-management.md)\n- [工具调用扩展](./tool-extensions.md)\n- [遥测系统](./telemetry.md)\n\n---\n\n<a id='session-management'></a>\n\n## 会话管理\n\n### 相关页面\n\n相关主题：[记忆系统](#memory-system), [智能体运行时](#agent-runtime)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/src/services/sessionService.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/services/sessionService.ts)\n- [packages/core/src/services/chatCompressionService.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/services/chatCompressionService.ts)\n- [packages/core/src/services/sessionTitle.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/services/sessionTitle.ts)\n- [packages/cli/src/acp-integration/session/SubAgentTracker.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/acp-integration/session/SubAgentTracker.ts)\n- [packages/vscode-ide-companion/src/services/qwenAgentManager.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/vscode-ide-companion/src/services/qwenAgentManager.ts)\n- [packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx](https://github.com/QwenLM/qwen-code/blob/main/packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx)\n</details>\n\n# 会话管理\n\n## 概述\n\n会话管理（Session Management）是 Qwen Code 核心系统之一，负责管理和维护用户与 AI 助手交互的所有对话历史。系统通过结构化的数据模型存储会话信息，支持会话分叉（Fork）、会话列表检索、后台任务状态跟踪等核心功能。\n\n会话数据以 JSONL（JSON Lines）格式持久化存储在项目目录的 `~/.qwen/chats/` 下，每个会话文件以会话 ID 命名，格式为 `{sessionId}.jsonl`。资料来源：[packages/core/src/services/sessionService.ts:1-50]()\n\n## 核心数据模型\n\n### ChatRecord 会话记录\n\n会话中的每条消息都被封装为 `ChatRecord` 结构，是会话持久化的基本单元：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `uuid` | `string` | 消息唯一标识符 |\n| `sessionId` | `string` | 所属会话 ID |\n| `parentUuid` | `string \\| null` | 父消息 UUID，用于构建消息链 |\n| `forkedFrom` | `ForkedFrom \\| null` | 分叉来源信息 |\n| `cwd` | `string` | 会话工作目录 |\n| `timestamp` | `number` | 消息时间戳 |\n\n资料来源：[packages/core/src/services/sessionService.ts:35-50]()\n\n### 会话元数据结构\n\n会话检索时返回的元数据结构包含以下关键字段：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | `string` | 会话唯一标识 |\n| `sessionId` | `string` | 会话 ID |\n| `title` | `string` | 会话标题 |\n| `name` | `string` | 会话名称 |\n| `startTime` | `number` | 会话开始时间 |\n| `lastUpdated` | `number` | 最后更新时间 |\n| `messageCount` | `number` | 消息总数 |\n| `projectHash` | `string` | 项目哈希值 |\n| `filePath` | `string` | 会话文件路径 |\n| `cwd` | `string` | 工作目录 |\n\n资料来源：[packages/vscode-ide-companion/src/services/qwenAgentManager.ts:30-45]()\n\n## 会话服务架构\n\n### SessionService 核心服务\n\n`SessionService` 是会话管理的核心服务类，负责：\n\n- 会话文件的读写操作\n- 会话 ID 验证与生成\n- 会话分叉（Fork）操作\n- 项目所有权验证\n\n```typescript\nclass SessionService {\n  private getChatsDir(): string;\n  private getSessionFilePath(sessionId: string): string;\n  private validateSessionId(newSessionId: string): void;\n  async forkSession(sourceSessionId: string, newSessionId: string): Promise<void>;\n}\n```\n\n资料来源：[packages/core/src/services/sessionService.ts:1-100]()\n\n### 会话文件模式验证\n\n系统使用正则表达式 `SESSION_FILE_PATTERN` 验证会话 ID 的合法性，确保文件名安全：\n\n```typescript\nSESSION_FILE_PATTERN.test(`${newSessionId}.jsonl`)\n```\n\n不合法的会话 ID 将抛出错误：`Invalid new sessionId: ${newSessionId}`\n\n资料来源：[packages/core/src/services/sessionService.ts:15-20]()\n\n## 会话分叉（Fork）\n\n### 分叉机制概述\n\n会话分叉允许从现有会话创建新会话，同时保持与原会话的消息血缘关系。分叉操作会重建父消息 UUID 链，确保新会话是原会话的线性后裔。\n\n### 分叉流程图\n\n```mermaid\ngraph TD\n    A[源会话] --> B[读取源会话记录]\n    B --> C[验证项目所有权]\n    C --> D{验证通过?}\n    D -->|否| E[抛出错误]\n    D -->|是| F[重建 parentUuid 链]\n    F --> G[设置 forkedFrom 元数据]\n    G --> H[创建新会话文件]\n    H --> I[分叉完成]\n```\n\n### forkedFrom 元数据结构\n\n分叉后的每条消息都记录其来源信息：\n\n```typescript\ninterface ForkedFrom {\n  sessionId: string;    // 来源会话 ID\n  messageUuid: string; // 来源消息 UUID\n}\n```\n\n资料来源：[packages/core/src/services/sessionService.ts:40-55]()\n\n### 分叉实现代码\n\n```typescript\nconst forked: ChatRecord[] = records.map((record) => {\n  const next: ChatRecord = {\n    ...record,\n    sessionId: newSessionId,\n    parentUuid: prevUuid,\n    forkedFrom: {\n      sessionId: sourceSessionId,\n      messageUuid: record.uuid,\n    },\n  };\n  prevUuid = record.uuid;\n  return next;\n});\n```\n\n资料来源：[packages/core/src/services/sessionService.ts:60-75]()\n\n## 会话标题管理\n\n### 标题生成服务\n\n`sessionTitle.ts` 负责为新会话生成有意义的标题。系统通过分析会话内容自动提取标题，便于用户快速识别和检索会话。\n\n### 标题生成策略\n\n- 分析首条用户消息的主题\n- 提取关键主题词作为标题\n- 支持自定义标题覆盖\n\n资料来源：[packages/core/src/services/sessionTitle.ts:1-30]()\n\n## 聊天压缩服务\n\n### 压缩机制\n\n`chatCompressionService.ts` 实现了会话历史压缩功能，当会话长度超过阈值时自动压缩早期消息，减少 token 消耗同时保留关键上下文。\n\n### 压缩触发条件\n\n| 条件 | 说明 |\n|------|------|\n| 消息数量超限 | 会话消息数达到配置阈值 |\n| Token 数量超限 | 累计 token 数超过限制 |\n\n资料来源：[packages/core/src/services/chatCompressionService.ts:1-50]()\n\n## 子代理追踪\n\n### SubAgentTracker\n\n`SubAgentTracker` 负责追踪会话中的子代理（Sub-Agent）活动。当主代理派生子代理完成任务时，跟踪器记录子代理的执行状态和结果。\n\n### 追踪数据结构\n\n```typescript\ninterface SubAgentInfo {\n  agentId: string;\n  parentAgentId: string;\n  status: 'running' | 'completed' | 'failed';\n  startTime: number;\n  endTime?: number;\n  result?: unknown;\n}\n```\n\n资料来源：[packages/cli/src/acp-integration/session/SubAgentTracker.ts:1-40]()\n\n## 后台任务与会话关联\n\n### 状态显示\n\n后台任务对话框显示与会话相关的状态信息：\n\n| 显示项 | 说明 |\n|--------|------|\n| 状态动词 | 如 Running、Completed、Failed |\n| 会话计数 | 当前正在审核的会话数 |\n| 进度文本 | 任务执行进度描述 |\n| 主题列表 | 会话涉及的主题标签 |\n\n资料来源：[packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx:20-60]()\n\n### 错误与警告展示\n\n系统会展示会话相关的错误和警告信息：\n\n- **错误状态**：显示 `entry.error` 内容\n- **锁定释放警告**：当锁定释放失败时提示后续梦境可能被跳过\n- **元数据写入警告**：Scheduler Gate 未获取最新运行的提示\n\n资料来源：[packages/cli/src/ui/components/background-view/BackgroundTasksDialog.tsx:70-100]()\n\n## 会话检索机制\n\n### ACP 会话列表获取\n\n系统通过 ACP（Agent Communication Protocol）接口获取会话列表：\n\n```typescript\n// ACP 方式获取会话\nconst sessions = await acpClient.getSessions();\n\n// 文件系统方式获取（降级方案）\nconst sessions = await this.sessionReader.getAllSessions(undefined, true);\n```\n\n### 获取策略\n\n1. 优先尝试 ACP 接口获取会话列表\n2. ACP 获取失败时降级到文件系统直接读取\n3. 返回统一格式的会话元数据数组\n\n资料来源：[packages/vscode-ide-companion/src/services/qwenAgentManager.ts:20-50]()\n\n## VSCode IDE 集成\n\n### QwenAgentManager\n\nVSCode 扩展通过 `QwenAgentManager` 服务管理会话，集成以下功能：\n\n- 会话列表展示\n- 会话详情查看\n- 新会话创建\n- 会话切换\n\n### 服务初始化\n\n```typescript\nclass QwenAgentManager {\n  private sessionReader: SessionReader;\n  \n  async getAllSessions(): Promise<QwenSession[]>;\n  async getSessionById(sessionId: string): Promise<QwenSession | null>;\n}\n```\n\n资料来源：[packages/vscode-ide-companion/src/services/qwenAgentManager.ts:1-60]()\n\n## 最佳实践\n\n### 会话命名规范\n\n- 使用有意义的会话标题\n- 避免特殊字符在会话 ID 中\n- 定期清理不需要的会话文件\n\n### 会话分叉使用场景\n\n| 场景 | 建议操作 |\n|------|----------|\n| 探索不同解决方案 | 从原会话分叉 |\n| 修复错误方向 | 创建新分叉继续 |\n| A/B 测试方案 | 并行分叉对比 |\n\n### 性能优化\n\n- 及时压缩长会话减少内存占用\n- 使用项目哈希快速定位相关会话\n- 通过 `messageCount` 评估会话复杂度\n\n---\n\n<a id='skills-hooks'></a>\n\n## 技能与钩子系统\n\n### 相关页面\n\n相关主题：[工具系统](#tool-system)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/src/skills/skill-manager.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/skills/skill-manager.ts)\n- [packages/core/src/hooks/hookSystem.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/hooks/hookSystem.ts)\n- [packages/core/src/hooks/hookRegistry.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/hooks/hookRegistry.ts)\n- [packages/core/src/skills/skill-load.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/skills/skill-load.ts)\n- [packages/core/src/skills/skill-activation.ts](https://github.com/QwenLM/qwen-code/blob/main/packages/core/src/skills/skill-activation.ts)\n</details>\n\n# 技能与钩子系统\n\n## 概述\n\n技能（Skills）与钩子（Hooks）系统是 Qwen Code 框架的核心扩展机制，旨在为 AI 编程助手提供高度模块化、可定制的功能扩展能力。技能系统允许开发者定义独立的工具集和功能模块，而钩子系统则在关键执行节点提供拦截、修改和增强行为的能力。\n\n技能与钩子系统的主要职责包括：\n\n- **动态加载**：在运行时从文件系统或远程源加载技能包\n- **生命周期管理**：管理技能的激活、停用和卸载流程\n- **事件拦截**：在工具执行、消息处理等关键节点注入自定义逻辑\n- **上下文注入**：向 AI 模型提供额外的系统提示和上下文信息\n- **错误处理增强**：通过钩子机制提供更细粒度的错误处理和恢复策略\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TB\n    subgraph \"技能层 Skill Layer\"\n        SM[技能管理器<br/>SkillManager]\n        SA[技能激活器<br/>SkillActivator]\n        SL[技能加载器<br/>SkillLoader]\n    end\n    \n    subgraph \"钩子层 Hook Layer\"\n        HS[钩子系统<br/>HookSystem]\n        HR[钩子注册表<br/>HookRegistry]\n        HP[钩子处理器<br/>HookProcessor]\n    end\n    \n    subgraph \"执行层 Execution Layer\"\n        TS[工具调度器<br/>ToolScheduler]\n        MB[消息总线<br/>MessageBus]\n    end\n    \n    subgraph \"工具层 Tool Layer\"\n        BT[内置工具<br/>BuiltinTools]\n        MCPT[MCP工具<br/>MCPTools]\n        SKT[技能工具<br/>SkillTools]\n    end\n    \n    SM --> SA\n    SL --> SM\n    SA --> TS\n    HS --> MB\n    HR --> HP\n    HP --> TS\n    BT --> TS\n    MCPT --> TS\n    SKT --> TS\n```\n\n### 技能系统架构\n\n技能系统采用管理器模式，通过 `SkillManager` 统一管理所有技能的生命周期。每个技能作为一个独立的功能单元，包含工具定义、系统提示和激活逻辑。\n\n```mermaid\ngraph LR\n    A[技能定义文件] --> B[技能加载器<br/>skill-load.ts]\n    B --> C[技能管理器<br/>skill-manager.ts]\n    C --> D[技能激活器<br/>skill-activation.ts]\n    D --> E[工具注册]\n    D --> F[上下文注入]\n    D --> G[系统提示增强]\n```\n\n### 钩子系统架构\n\n钩子系统基于发布-订阅模式，在关键执行节点注册回调函数，实现行为拦截和增强。\n\n```mermaid\ngraph TB\n    A[事件触发点] --> B{钩子类型检查}\n    B -->|预执行钩子| C[Pre-Hook]\n    B -->|后执行钩子| D[Post-Hook]\n    B -->|失败钩子| E[Failure-Hook]\n    \n    C --> F[执行前置逻辑]\n    D --> G[处理返回结果]\n    E --> H[错误处理增强]\n    \n    F --> I[继续执行]\n    G --> J[返回修改结果]\n    H --> K[返回错误上下文]\n```\n\n## 核心组件\n\n### 技能管理器 (SkillManager)\n\n技能管理器是技能系统的中央协调器，负责维护技能注册表、协调加载流程和提供统一的访问接口。\n\n| 方法/属性 | 类型 | 说明 |\n|-----------|------|------|\n| `skills` | `Map<string, Skill>` | 已注册技能集合 |\n| `register()` | `method` | 注册新技能 |\n| `unregister()` | `method` | 注销技能 |\n| `activate()` | `method` | 激活指定技能 |\n| `deactivate()` | `method` | 停用指定技能 |\n| `getActiveSkills()` | `method` | 获取当前活跃技能列表 |\n| `loadFromPath()` | `method` | 从指定路径加载技能 |\n\n资料来源：[packages/core/src/skills/skill-manager.ts]()\n\n### 技能加载器 (SkillLoader)\n\n技能加载器负责从各种来源加载技能定义，包括本地文件系统、远程 URL 和内置技能包。\n\n| 加载方式 | 来源类型 | 说明 |\n|----------|----------|------|\n| `file` | 本地文件系统 | 从 `.qwen/skills/` 目录加载 |\n| `user` | 用户目录 | 从 `~/.qwen/skills/` 目录加载 |\n| `builtin` | 内置技能 | 框架内置的默认技能 |\n| `remote` | 远程源 | 从远程服务器下载技能包 |\n\n资料来源：[packages/core/src/skills/skill-load.ts]()\n\n### 技能激活器 (SkillActivator)\n\n技能激活器负责将技能集成到运行时环境，包括工具注册、提示词注入和状态初始化。\n\n| 激活阶段 | 操作 | 说明 |\n|----------|------|------|\n| 初始化 | 状态重置 | 重置技能内部状态 |\n| 工具注册 | 注册工具函数 | 将技能工具添加到工具调度器 |\n| 提示注入 | 添加系统提示 | 向 AI 注入技能相关指令 |\n| 资源预加载 | 加载资源 | 预加载技能所需的资源文件 |\n\n资料来源：[packages/core/src/skills/skill-activation.ts]()\n\n### 钩子系统 (HookSystem)\n\n钩子系统提供在关键执行节点插入自定义逻辑的能力，支持同步和异步钩子执行。\n\n```typescript\ninterface HookConfig {\n  name: string;           // 钩子名称\n  priority: number;       // 执行优先级，数值越小越先执行\n  enabled: boolean;       // 是否启用\n  handler: HookHandler;   // 钩子处理函数\n}\n```\n\n| 钩子类型 | 触发时机 | 典型用途 |\n|----------|----------|----------|\n| `preToolUse` | 工具执行前 | 参数验证、权限检查 |\n| `postToolUse` | 工具执行后 | 结果转换、日志记录 |\n| `postToolUseFailure` | 工具执行失败 | 错误处理、重试逻辑 |\n| `preMessage` | 消息发送前 | 内容过滤、敏感词处理 |\n| `postMessage` | 消息接收后 | 响应增强、格式转换 |\n\n资料来源：[packages/core/src/hooks/hookSystem.ts]()\n\n### 钩子注册表 (HookRegistry)\n\n钩子注册表维护所有已注册的钩子实例，提供查询、排序和批量操作功能。\n\n| 功能 | 说明 |\n|------|------|\n| `register()` | 注册新钩子 |\n| `unregister()` | 注销钩子 |\n| `getHooks()` | 获取指定类型的钩子列表 |\n| `setEnabled()` | 启用/禁用钩子 |\n| `clear()` | 清空所有钩子 |\n\n资料来源：[packages/core/src/hooks/hookRegistry.ts]()\n\n## 执行流程\n\n### 技能激活流程\n\n```mermaid\nsequenceDiagram\n    participant User as 用户\n    participant SM as 技能管理器\n    participant SL as 技能加载器\n    participant SA as 技能激活器\n    participant TS as 工具调度器\n\n    User->>SM: 加载技能请求\n    SM->>SL: 调用 loadFromPath()\n    SL->>SL: 扫描技能目录\n    SL-->>SM: 返回技能定义列表\n    SM->>SA: 激活技能\n    SA->>SA: 初始化技能状态\n    SA->>TS: 注册技能工具\n    TS-->>SA: 注册成功\n    SA->>SA: 注入系统提示\n    SA-->>SM: 激活完成\n    SM-->>User: 返回激活结果\n```\n\n### 工具执行与钩子调用流程\n\n```mermaid\nsequenceDiagram\n    participant Agent as AI代理\n    participant HS as 钩子系统\n    participant TS as 工具调度器\n    participant Tool as 工具实现\n    participant MB as 消息总线\n\n    Agent->>TS: 请求执行工具\n    TS->>HS: 触发 preToolUse 钩子\n    HS->>HS: 执行前置钩子链\n    HS-->>TS: 钩子执行结果\n    \n    alt 钩子允许执行\n        TS->>Tool: 调用工具\n        Tool-->>TS: 返回结果\n        TS->>HS: 触发 postToolUse 钩子\n        HS->>HS: 执行后置钩子链\n        HS-->>TS: 处理后的结果\n        TS-->>Agent: 返回最终结果\n    else 钩子阻止执行\n        HS-->>TS: 返回阻止信号\n        TS-->>Agent: 返回错误响应\n    end\n    \n    Note over TS,MB: 失败处理流程\n    Tool-->>TS: 抛出异常\n    TS->>MB: 触发 postToolUseFailure 钩子\n    MB->>MB: 执行失败钩子链\n    MB-->>TS: 错误增强结果\n    TS-->>Agent: 返回带上下文的错误\n```\n\n## 数据模型\n\n### 技能定义结构\n\n```typescript\ninterface SkillDefinition {\n  id: string;                    // 唯一标识符\n  name: string;                  // 显示名称\n  version: string;               // 版本号\n  description: string;          // 功能描述\n  author?: string;               // 作者信息\n  tools: SkillTool[];            // 工具定义列表\n  systemPrompt?: string;         // 系统提示词片段\n  activationConfig?: object;     // 激活配置\n  resources?: string[];          // 依赖资源路径\n  dependencies?: string[];       // 依赖的其他技能\n}\n```\n\n### 工具结果结构\n\n技能工具返回的结果遵循统一的结构规范，包含返回内容和显示信息：\n\n```typescript\ninterface SkillToolResult {\n  returnDisplay: string;        // 返回值的文本表示\n  modelOverride?: string;       // 模型覆盖指令\n  error?: {\n    message: string;            // 错误消息\n    type: string;               // 错误类型\n  };\n}\n```\n\n资料来源：[packages/core/src/core/coreToolScheduler.ts:25-35]()\n\n### 钩子结果结构\n\n```typescript\ninterface HookResult {\n  continue: boolean;            // 是否继续执行后续钩子/主流程\n  modifiedContent?: string;     // 修改后的内容\n  additionalContext?: string;   // 附加的上下文信息\n  suppressError?: boolean;      // 是否抑制错误传播\n}\n```\n\n## 钩子类型详解\n\n### 工具执行钩子\n\n工具执行钩子在工具调用的生命周期中提供多个拦截点，支持精细化的行为控制。\n\n| 钩子名称 | 参数 | 返回值 | 说明 |\n|----------|------|--------|------|\n| `preToolUse` | `toolName`, `toolInput` | `HookResult` | 工具执行前调用，可修改参数或阻止执行 |\n| `postToolUse` | `toolName`, `toolInput`, `toolResult` | `HookResult` | 工具执行成功后调用，可修改返回结果 |\n| `postToolUseFailure` | `toolName`, `toolInput`, `error`, `willRetry` | `HookResult` | 工具执行失败后调用，可添加错误上下文 |\n\n### 消息处理钩子\n\n消息处理钩子拦截聊天消息的发送和接收过程，支持内容过滤和增强。\n\n| 钩子名称 | 触发条件 | 用途 |\n|----------|----------|------|\n| `preMessage` | 消息发送前 | 敏感词过滤、内容审核 |\n| `postMessage` | 消息接收后 | 响应格式化、Markdown 处理 |\n\n### 生命周期钩子\n\n生命周期钩子监听会话和系统的重要状态变化。\n\n| 钩子名称 | 触发时机 | 用途 |\n|----------|----------|------|\n| `onSessionStart` | 会话开始 | 初始化会话上下文 |\n| `onSessionEnd` | 会话结束 | 资源清理、状态保存 |\n| `onSkillActivated` | 技能激活 | 依赖技能加载 |\n| `onSkillDeactivated` | 技能停用 | 资源释放 |\n\n## 集成与扩展\n\n### 注册自定义技能\n\n开发者可以通过扩展技能系统来添加自定义功能：\n\n```typescript\nimport { SkillManager } from '@qwen-code/core';\n\nconst skillManager = SkillManager.getInstance();\n\n// 定义技能\nconst customSkill = {\n  id: 'my-custom-skill',\n  name: '自定义技能',\n  version: '1.0.0',\n  description: '演示自定义技能开发',\n  tools: [\n    {\n      name: 'customTool',\n      description: '自定义工具',\n      execute: async (input) => {\n        return { returnDisplay: `处理结果: ${input}` };\n      }\n    }\n  ],\n  systemPrompt: '你可以使用 customTool 工具来处理自定义任务。'\n};\n\n// 注册并激活\nawait skillManager.register(customSkill);\nawait skillManager.activate('my-custom-skill');\n```\n\n### 注册自定义钩子\n\n开发者可以在关键执行点注入自定义逻辑：\n\n```typescript\nimport { HookRegistry } from '@qwen-code/core';\n\nconst registry = HookRegistry.getInstance();\n\n// 注册前置钩子\nregistry.register({\n  name: 'parameter-validator',\n  type: 'preToolUse',\n  priority: 100,\n  enabled: true,\n  handler: async (toolName, toolInput) => {\n    // 参数验证逻辑\n    if (!validateInput(toolInput)) {\n      return {\n        continue: false,\n        additionalContext: '参数验证失败，请检查输入格式。'\n      };\n    }\n    return { continue: true };\n  }\n});\n```\n\n### 失败钩子的高级用法\n\n失败钩子支持在工具执行失败时添加上下文信息或执行重试逻辑：\n\n```typescript\nregistry.register({\n  name: 'error-enhancer',\n  type: 'postToolUseFailure',\n  priority: 50,\n  enabled: true,\n  handler: async (toolName, toolInput, error, willRetry) => {\n    let additionalContext = '';\n\n    // 为网络错误添加重试建议\n    if (error.message.includes('ECONNREFUSED')) {\n      additionalContext = '建议检查网络连接和目标服务状态。';\n    }\n\n    // 为权限错误添加帮助信息\n    if (error.message.includes('permission')) {\n      additionalContext = '请确保具有必要的操作权限。';\n    }\n\n    return {\n      continue: true,\n      additionalContext,\n      suppressError: false\n    };\n  }\n});\n```\n\n资料来源：[packages/core/src/core/coreToolScheduler.ts:45-70]()\n\n## 配置选项\n\n### 技能配置\n\n技能系统支持通过配置文件进行初始化：\n\n```json\n{\n  \"skills\": {\n    \"enabled\": true,\n    \"autoActivate\": true,\n    \"loadPaths\": [\n      \".qwen/skills\",\n      \"~/.qwen/skills\"\n    ],\n    \"excludedSkills\": []\n  }\n}\n```\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `enabled` | `boolean` | `true` | 是否启用技能系统 |\n| `autoActivate` | `boolean` | `true` | 是否自动激活已注册的技能 |\n| `loadPaths` | `string[]` | 系统默认路径 | 技能加载目录列表 |\n| `excludedSkills` | `string[]` | `[]` | 禁用的技能 ID 列表 |\n\n### 钩子配置\n\n钩子系统支持细粒度的启用/禁用控制：\n\n```json\n{\n  \"hooks\": {\n    \"enabled\": true,\n    \"globalTimeout\": 5000,\n    \"hooks\": {\n      \"preToolUse\": {\n        \"enabled\": true,\n        \"timeout\": 1000\n      },\n      \"postToolUse\": {\n        \"enabled\": true,\n        \"timeout\": 2000\n      },\n      \"postToolUseFailure\": {\n        \"enabled\": true,\n        \"timeout\": 3000\n      }\n    }\n  }\n}\n```\n\n## 最佳实践\n\n### 技能开发规范\n\n1. **单一职责**：每个技能应专注于特定功能领域\n2. **版本管理**：遵循语义化版本规范，清晰标注兼容性\n3. **依赖声明**：明确声明技能依赖的其他技能或资源\n4. **错误处理**：为工具实现提供完整的错误处理和用户友好的错误信息\n5. **资源清理**：在技能停用时正确释放资源\n\n### 钩子开发规范\n\n1. **执行效率**：钩子处理应尽可能高效，避免阻塞主流程\n2. **错误安全**：钩子内部应实现异常捕获，防止错误传播影响系统稳定性\n3. **优先级规划**：合理设置钩子优先级，确保执行顺序符合预期\n4. **幂等性**：确保钩子在重复执行时产生一致的结果\n5. **超时控制**：为可能耗时较长的操作设置合理的超时时间\n\n### 安全注意事项\n\n1. **输入验证**：在钩子中始终验证输入参数的安全性\n2. **权限检查**：敏感操作应配合权限钩子进行访问控制\n3. **日志审计**：记录关键钩子的执行情况，便于问题排查\n4. **沙箱隔离**：自定义技能应在受限环境中执行，防止恶意代码\n\n## 总结\n\n技能与钩子系统为 Qwen Code 提供了强大而灵活的扩展机制。技能系统通过模块化的设计允许开发者以插件形式添加新功能，而钩子系统则提供了在关键执行点进行拦截和增强的能力。两者协同工作，使得框架能够在保持核心简洁的同时支持高度定制化的使用场景。\n\n熟练掌握这两个系统的使用，将有助于开发者构建功能丰富、行为可控的 AI 编程辅助工具。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：QwenLM/qwen-code\n\n摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。\n\n## 1. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | host_targets=claude, claude_code, chatgpt\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在安全注意事项\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 | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 6. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | no_demo; severity=medium\n\n## 7. 维护坑 · 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 | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | issue_or_pr_quality=unknown\n\n## 8. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | release_recency=unknown\n\n<!-- canonical_name: QwenLM/qwen-code; human_manual_source: deepwiki_human_wiki -->\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项目：QwenLM/qwen-code\n\n摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。\n\n## 1. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | host_targets=claude, claude_code, chatgpt\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在安全注意事项\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 | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 6. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | no_demo; severity=medium\n\n## 7. 维护坑 · 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 | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | issue_or_pr_quality=unknown\n\n## 8. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | art_875e03abe4cc4cb58b4a8ef8603b8a0b | https://github.com/QwenLM/qwen-code#readme | release_recency=unknown\n",
      "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
      "title": "Pitfall Log / 踩坑日志"
    },
    "prompt_preview": {
      "asset_id": "prompt_preview",
      "filename": "PROMPT_PREVIEW.md",
      "markdown": "# qwen-code - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 qwen-code 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：claude / Claude Code / chatgpt\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. project-overview：项目概览。围绕“项目概览”模拟一次用户任务，不展示安装或运行结果。\n2. quick-start：快速入门。围绕“快速入门”模拟一次用户任务，不展示安装或运行结果。\n3. system-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. agent-runtime：智能体运行时。围绕“智能体运行时”模拟一次用户任务，不展示安装或运行结果。\n5. tool-system：工具系统。围绕“工具系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. project-overview\n输入：用户提供的“项目概览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quick-start\n输入：用户提供的“快速入门”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. system-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. agent-runtime\n输入：用户提供的“智能体运行时”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. tool-system\n输入：用户提供的“工具系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / project-overview：Step 1 必须围绕“项目概览”形成一个小中间产物，并等待用户确认。\n- Step 2 / quick-start：Step 2 必须围绕“快速入门”形成一个小中间产物，并等待用户确认。\n- Step 3 / system-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / agent-runtime：Step 4 必须围绕“智能体运行时”形成一个小中间产物，并等待用户确认。\n- Step 5 / tool-system：Step 5 必须围绕“工具系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/QwenLM/qwen-code#readme\n- .qwen/skills/bugfix/SKILL.md\n- .qwen/skills/codegraph/SKILL.md\n- .qwen/skills/docs-audit-and-refresh/SKILL.md\n- .qwen/skills/docs-update-from-diff/SKILL.md\n- .qwen/skills/e2e-testing/SKILL.md\n- .qwen/skills/feat-dev/SKILL.md\n- .qwen/skills/qwen-code-claw/SKILL.md\n- .qwen/skills/structured-debugging/SKILL.md\n- .qwen/skills/terminal-capture/SKILL.md\n- .qwen/skills/tmux-real-user-testing/SKILL.md\n- packages/cli/src/commands/extensions/examples/skills/skills/synonyms/SKILL.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 qwen-code 的核心服务。\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项目：QwenLM/qwen-code\n\n## 官方安装入口\n\n### Node.js / npm · 官方安装入口\n\n```bash\nnpm install -g @qwen-code/qwen-code@latest\n```\n\n来源：https://github.com/QwenLM/qwen-code#readme\n\n## 来源\n\n- docs: https://github.com/QwenLM/qwen-code#readme\n",
      "summary": "从项目官方 README 或安装文档提取的开工入口。",
      "title": "Quick Start / 官方入口"
    }
  },
  "validation_id": "dval_d750a4261ee247f2afff5933a37f8cf2"
}