Qwen Code Agent 工具完全指南子代理委派、Fork 并行执行与后台延续实战【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-codeagent是 Qwen Code开源终端 AI 编码代理中用于自主委派复杂多步任务的核心工具它把任务交给独立的专用子代理subagent子代理拥有各自的工具集可以并行运行、共享提示缓存prompt cache并在后台完成后通过通知汇报结果。读完本文你将掌握agent全部参数的正确用法、内置子代理的构成、Fork 与 fork profile 的上下文继承机制以及用list_agentssend_message对后台代理进行续工continuation的完整实战流程。本文技术事实以仓库源码为准工具实现位于 packages/core/src/tools/agent/agent.tsFork 机制在 packages/core/src/tools/agent/fork-subagent.ts内置子代理注册表在 packages/core/src/subagents/builtin-agents.ts。Agent Tool 是什么Agent Tool 允许主代理primary agent把复杂、多步骤的任务委派给专用子代理自主处理。子代理以独立进程运行拥有自己的一套工具从而支持并行任务执行与专业能力复用。从源码结构看AgentTool是一个声明式工具继承自BaseDeclarativeToolAgentParams, ToolResult见 agent.ts它通过SubagentManager动态加载当前配置中可用的子代理列表并在构造与配置变更时刷新自身描述与参数模式refreshSubagents()见 agent.ts。也就是说模型每次发起agent调用时工具描述里会实时列出当前可用的子代理类型及其说明引导模型选择正确的subagent_type。当你调用 Agent Tool 时子代理会经历以下生命周期源自 task.md 与源码执行路径接收任务提示词如果是 Fork还接收选定的父会话上下文使用其可用工具自主执行任务默认上报一条完成通知后台运行或在前台运行时直接返回最终结果消息若保留状态支持续工后台运行结束后仍可被寻址并继续接收后续任务。参数详解agent工具的参数模式JSON Schema定义在 agent.ts必填参数仅description与prompt。完整参数如下参数类型必填说明descriptionstring是任务简短描述3-5 个词用于用户可见性与任务跟踪promptstring是交给子代理执行的详细任务提示词应包含自主执行所需的完整指令subagent_typestring否使用的专用代理类型省略时默认为general-purpose传fork则继承父会话上下文fork_turnsstring否仅对subagent_typefork有效。省略或传all继承完整父会话传正整数数字字符串如3只继承最近三轮真实用户轮次。工具响应与纯系统提醒不计入轮次fork_toolsarray of strings否仅对 fork 有效。将 fork 可执行的工具限制为精确的规范工具名或 MCP 服务器模式同时保持模型可见的工具声明不变以共享提示缓存fork_profilestring否仅对 fork 有效。从项目根目录加载 frontmatter-only 的.qwen/fork-profiles/name.md配置文件并应用其tools与可选promptHintrun_in_backgroundboolean否顶层常规代理默认为true设为false则前台运行并内联返回结果isolationstring否设为worktree时在 Qwen Code 创建并管理的隔离 git worktree 中运行显式命名的非 fork 代理working_dirstring否将显式命名的非 fork 代理钉到当前仓库内一个已注册的 git worktreemodel源码扩展string否为本次子代理调用指定用户自定义模型等级model grade不可与 fork 组合todo_id源码扩展string否本顶层代理执行所对应的 todo 项 ID在存在可见计划时使用name/plan_mode_required/read_only源码扩展各异否团队功能启用时将代理作为命名队友teammate生成 / 要求计划模式审批 / 限制为只读参数校验逻辑集中在validateToolParams()见 agent.ts任何非法组合都会在调度前被明确拒绝。下面逐项深入。description 与 promptdescription必须是非空字符串校验见 agent.ts。它是用户在界面上识别多个并行任务的关键标识。prompt必须是非空字符串agent.ts。由于常规子代理看不到父会话你的初始提示词必须自带完成自主执行所需的全部上下文与指令。subagent_type省略时解析为默认内置类型general-purpose常量DEFAULT_BUILTIN_SUBAGENT_TYPE见 builtin-agents.ts。传fork是显式选择继承父会话上下文的伪类型常量FORK_SUBAGENT_TYPE见 fork-subagent.ts它不在已注册子代理列表中由调度逻辑专门处理。传入其他名称时校验会先查缓存列表若不在缓存中可能是刚创建的代理文件校验不直接拒绝而是触发一次异步刷新执行阶段通过loadSubagent()从磁盘解析若确实不存在会以清晰的Subagent name not found错误失败agent.ts。run_in_background 的精细语义这是最容易被误用的参数其规则源码 schema 描述与校验双重印证如下顶层常规子代理默认后台运行schema 中default: true完成后通过完成通知汇报设run_in_background: false则前台运行、内联返回结果适用于当前轮次必须先用子代理结果才能继续的场景。无头headlessfork 始终后台运行。嵌套代理默认前台运行显式传run_in_background: true会被拒绝因为嵌套代理无法接收后台完成通知。未命名的 caller-ownedworking_dir启动前台运行显式run_in_background: true被拒绝子代理定义中配置的后台默认background: true在顶层被拒绝、嵌套时降级为前台——因为调用方拥有 worktree 生命周期后台代理运行期间 worktree 可能被移除。命名队友始终并发并通过团队消息汇报生成队友时应省略run_in_background显式false会被拒绝需要内联阻塞结果时应省略name、使用run_in_background: false的常规代理。fork_turns有界上下文继承fork_turns的合法取值只有all或正整数数字字符串校验见 agent.ts。其底层实现selectForkHistory()见 fork-subagent.ts按真实用户轮次切窗只统计用户发起的真实 prompt工具响应、纯系统提醒、压缩摘要前缀均不计入然后从最近的 N 个真实用户轮次开始截取历史。fork_tools执行白名单fork_tools把 fork 可执行的工具限制为精确的规范工具名或MCP 服务器模式schema 见 agent.ts规则如下条目不能有环绕空白通配符仅限mcp__*或尾部MCP 工具前缀模式如mcp__github__read_*fork 永远不会执行ask_user_question省略fork_tools允许所有其他继承工具传空数组则拒绝所有工具调用。校验函数validateForkToolList()fork-subagent.ts会拒绝*通配与非法通配形式。关键设计在于模型可见的工具声明保持不变以便提示缓存前缀逐字节共享仅在执行层收窄能力被禁止的工具调用会在调度/审批前直接报错。这是调用方按调用选择的执行限制而非管理员强制的沙箱。fork_profile项目级执行配置fork_profile从当前项目根目录加载.qwen/fork-profiles/name.md实现见 fork-profile.ts约束如下frontmatter-only文件必须包含 YAML frontmattername字段必须与文件名完全一致tools为必填数组可选的promptHint最多 200 字符文件大小上限64 KiB路径通过realpath解析后必须位于项目 profile 目录内防目录穿越不能与fork_tools或命名队友组合校验见 agent.tssafe mode 与 bare mode 下不可用项目 profile 被视为本地自定义配置见 agent.ts。profile 在启动前解析一次解析出的工具列表会持久化以便代理复活revival时复用promptHint只追加进任务指令directive中且被标记为仅供参考、不可覆盖指令。执行门控与fork_tools复用同一套机制buildChildMessage中的 TOOL EXECUTION RESTRICTION 段落见 fork-subagent.ts。isolation: worktree 与 working_dirisolation: worktree在projectRoot/.qwen/worktrees/agent-7hex创建临时 git worktree要求显式的非 forksubagent_typefork 复用父会话的上下文与工作树无法隔离。完成后若无改动则自动移除 worktree若有改动则保留并在结果中返回 worktree 路径与分支供审查或合并见 agent.ts 的参数注释与buildWorktreeNotice在 fork-subagent.ts。working_dir将子代理钉到仓库内已存在、由调用方拥有生命周期的已注册 git worktree。与isolation不同Qwen Code 不会创建或清理该目录。这是cwd 钉扎而非文件系统沙箱——显式绝对路径仍可访问外部。若同时提供working_dir与isolationworking_dir优先isolation被忽略。子代理的 cwd 相关文件/shell 操作与搜索工具都将在 worktree 内解析buildPinnedWorktreeNotice见 fork-subagent.ts。基本用法agent(descriptionBrief task description, promptDetailed task instructions for the subagent, subagent_typeagent_name) agent(descriptionBrief task description, promptDetailed task instructions for the fork, subagent_typefork, fork_turns3) agent(descriptionRead-only investigation, promptInspect the implementation, subagent_typefork, fork_tools[read_file, grep_search, mcp__github]) agent(descriptionProfiled investigation, promptInspect the implementation, subagent_typefork, fork_profilero-research)当当前轮次必须先用子代理结果再继续时设置run_in_backgroundfalse。委派给通用代理agent( descriptionCode refactoring, promptPlease refactor the authentication module in src/auth/ to use modern async/await patterns instead of callbacks. Ensure all tests still pass and update any related documentation., subagent_typegeneral-purpose )并行任务# Launch code review and test execution in parallel agent( descriptionCode review, promptReview the recent changes in the user management module for code quality, security issues, and best practices compliance., subagent_typegeneral-purpose ) agent( descriptionRun tests, promptExecute the full test suite and analyze any failures. Provide a summary of test coverage and recommendations for improvement., subagent_typetest-engineer )并行能力来自在单条消息中多次调用 Agent Tool 即可并发启动多个子代理对应源码描述中的 Run agents concurrently only when their tasks are independent 指引。注意并发执行代码修改任务时应给各代理划分互不重叠的写入范围避免冲突。文档生成agent( descriptionUpdate docs, promptGenerate comprehensive API documentation for the newly implemented REST endpoints in the orders module. Include request/response examples and error codes., subagent_typegeneral-purpose )可用子代理类型文档指出可用的子代理取决于你的配置常见类型包括general-purpose、code-reviewer、test-runner、documentation-writer等这些是可能包含的示例。以当前仓库源码为准BuiltinAgentRegistry内置了以下始终可用的类型builtin-agents.ts名称定位工具面general-purpose通用代理研究复杂问题、搜索代码、执行多步任务未声明tools走继承全部工具的路径Explore快速代码库探索代理glob 模式、关键词搜索、代码库问答只读工具集read_file、grep、glob、只读shell、web_fetch、skill、lsp刻意不含ask_user_questionstatusline-setup配置用户的状态栏statusLine设置read_file、write_file、editreview-agent捆绑reviewskill 启动的代码审查环节之一非通用用途封闭列表read_file、grep、glob、shell、write_file、editclaude-code通过 claude-agent-acp 适配器委派给已安装的 Claude Code外部执行器ACP默认前台codex委派自包含任务给已安装的 Codex CLI外部执行器Codex默认前台这些内置类型是代码内嵌、不可修改或删除的用户自定义的子代理会按 session project user extension builtin 的优先级解析并可以覆盖内置同名条目。在 Qwen Code 中运行/agents命令可查看当前可用的全部子代理。Agent Tool 能力特性实时进度更新Agent 工具提供实时动态子代理执行状态、子代理正在发起的单个工具调用、工具调用结果与错误、整体任务进度与完成状态。实现上工具声明了canUpdateOutput: true以启用实时输出更新agent.ts事件通过AgentEventEmitter广播工具调用、工具结果、完成、错误、审批请求、用量等事件类型定义见 agent.ts 的导入。并行执行在单条消息中多次调用 Agent Tool 即可并发启动多个子代理。AgentTool的 schema 与描述会明确引导模型If the user asks for agents in parallel, group independent launches in a single message with multiple Agent tool use content blocks. Do not parallelize overlapping code changes.专业化能力每个子代理可通过配置获得特定工具访问权限、专用系统提示词与指令、自定义模型配置、领域知识。对应SubagentConfig的字段详见 packages/core/src/subagents/types.tstools白名单、disallowedTools黑名单支持mcp__server级模式、systemPrompt支持${variable}模板、modelinherit/fast/ 模型 ID /authType:model-id、runConfigmax_time_minutes、max_turns、color、background、maxTurns、mcpServers、hooks、executorACP/Codex 外部执行器等。此外每个子代理还有独立的approvalModedefault、plan、auto-edit、yolo以及子代理专有的bubble模式——后台交互运行时把需要确认的调用冒泡到父会话 UI而不是自动拒绝见 types.ts 与 types.ts。resolveSubagentApprovalMode()agent.ts概括了权限模式的继承规则宽容的父模式yolo、auto-edit总是胜出否则采用代理定义的模式默认回退到 auto-edit 以保证子代理的自主性。后台代理续工Continuation后台代理在首次完成后仍可接收后续工作调用list_agents发现当前会话可寻址的后台代理及其task_id包含父会话恢复后重建的兼容代理。实现见 packages/core/src/tools/list-agents.ts它返回每个后台条目的task_id、subagent_type、description、status、can_message以及不可续工时的resume_blocked_reason。调用send_message传入task_id与后续指令运行中的代理在下一个工具轮次边界接收消息暂停的代理以此作为首个续工指令恢复已完成的代理在可用时于常驻运行时上继续否则从其保留的 transcript 中复活。等待下一条完成通知后再使用续工结果。重要约束源自 task.md 的 Background Agent Continuation 一节若代理无法续工list_agents会返回resume_blocked_reason对恢复或续工的代理输出应视为证据在整合变更前务必验证。相应地不要在通知到达前臆造或预测后台代理的结果——通知是稍后轮次中以用户角色消息到达的。Fork 深入何时使用Forksubagent_type: fork是显式选择省略subagent_type永远不会变成 fork见 fork-subagent.ts 的注释。选择 Fork 的场景任务需要大量父会话上下文时选 fork新鲜提示词足够时用常规子代理Fork 因共享提示缓存而开销更低——不要在 fork 上设置model不同模型无法复用父缓存传一个简短的小写name一两个词方便用户跟踪 fork。Fork 默认继承完整父会话fork_turns省略或all只有有界近期窗口足够时才设正整数。后台 fork 通过完成通知汇报结果交互式会话中如需该结果可设run_in_background: true无头 fork 始终走后台路径。编写 fork prompt 的要点默认完整历史下prompt 是一份指令要做什么而非介绍现状当fork_turns限制了历史时要包含 fork 仍需的旧上下文明确界定范围——什么在内、什么在外、什么由别的代理处理。从实现看fork 的指令注入通过buildChildMessage()完成fork-subagent.ts内含硬性规则fork 不得再派生子代理、不得对话或提问ask_user_question不可执行、按指定格式Scope:/Result:/Key files:/Files changed:/Verification:/Issues:结构化汇报。递归 fork 通过AsyncLocalStorage标记isInForkExecution()在调度时拒绝。Fork 轮次上限为FORK_DEFAULT_MAX_TURNS 200fork-subagent.ts。编写有效 prompt 的实践把子代理当作聪明的同事来交代任务明确委派任务、边界与期望输出说明你在达成什么目标、为什么描述你已知的信息或已排除的方向提供足够的问题背景让代理能做判断而非机械执行需要简短回答就明确说出来查证类任务给出精确目标调研类任务给出真实问题而非过度规定步骤序列。永远不要委派理解不要写基于你的发现修复 bug或基于调研实现它这类把综合工作推给代理的 prompt。应写出证明你已理解任务的 prompt包含相关文件路径、约束、需要学习或变更的具体内容、以及范围之外的内容。发布后在代理返回前不要臆造或预测它的发现。何时使用 / 不使用 Agent Tool应当使用源自 task.md复杂多步任务——需要多次自主操作的任务专业化需求——受益于领域知识或专用工具的任务并行执行——有多个可同时运行的独立任务委派需求——想整体移交任务而非逐步微观管理资源密集操作——可能消耗大量时间或计算资源的任务。不应使用简单单步操作——直接用 Read、Edit 等工具交互式任务——需要来回沟通的任务特定文件读取——直接用 Read 工具性能更好简单搜索——直接用 Grep 或 Glob 工具。源码工具描述中还明确读特定文件用read_file/glob、搜类定义用grep都比启动代理更快。同时遵循三个不要后台代理运行期间不要偷看不要 tail 其输出文件、不要竞速不要在通知到达前编造结果、不要重开通知未到不代表任务丢失不要为同一任务启动替代代理用list_agents查看名册、用send_message重定向运行中的代理。子代理配置子代理通过 Qwen Code 的代理配置系统管理。使用/agents命令可以查看可用子代理创建新的子代理配置修改现有子代理设置设置工具权限与能力。配置文件的存储层级SubagentLevel见 types.ts为session运行时提供只读优先级最高project项目.qwen/agents/user用户目录~/.qwen/agents/extension扩展提供builtin代码内嵌优先级最低。子代理定义使用 Markdown YAML frontmatter 格式frontmatter 字段对应上文SubagentConfig的各项能力。AgentTool会监听配置变更并自动刷新可用列表agent.ts因此新建子代理后无需重启即可被模型看到。小结agent工具是 Qwen Code 实现自主委派 并行 后台续工的枢纽常规子代理提供专业化隔离执行fork 以提示缓存共享为代价换取父上下文继承fork_tools/fork_profile提供调用级或项目级的执行收窄isolation/working_dir提供 git worktree 级的隔离与钉扎list_agentssend_message则让后台代理可被寻址与续工。正确组合这些参数即可把大型任务拆解为可独立验证、可并行推进、可延续迭代的工作流——这正是把终端里的 AI 编码代理从单线程助手升级为可编排的多代理团队的关键能力。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考