Qwen Code Subagent Prompt Guardrails 深入解析：父代理委派纪律、通用提示重构与 Explore/Fork 安全边界

Qwen Code Subagent Prompt Guardrails 深入解析父代理委派纪律、通用提示重构与 Explore/Fork 安全边界【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code导读本文基于 Qwen Codeqwen-code开源仓库的设计文档 2026-07-16-subagent-prompt-guardrails.md系统讲解该项目对Agent子代理委派体系做的一次提示词安全加固它一方面约束父代理的委派行为有界委派、本地保留关键路径、避免重复工作、并行写范围隔离、整合前必须审查另一方面重构了通用子代理、Explore 与 fork 三类内置代理的提示与工具边界缩小 Explore 有状态工具面、废除 fork 的强制提交要求。读完本文你将掌握 Qwen Code 子代理委派的安全规则、内置代理的完整提示设计、工具 allowlist 机制以及对应单元测试的验证方式可直接用于理解或二次开发该仓库的代理编排逻辑。背景为什么需要给子代理提示词加“护栏”设计文档开篇指出了三个促使本次加固的动机Agent 工具既往引导过于宽松旧版的委派引导鼓励“广泛并行委派”并默认子代理输出“大体可信”缺少对结果质量的把关要求内置提示缺失执行与验证预期通用子代理提示没有明确要求保留无关改动、验证事实、报告不确定性导致子代理产出质量参差Explore 与 fork 提示存在不安全或自相矛盾的引导Explore 提示中包含写操作的矛盾表述fork 提示则强制要求提交代码与实际工作流不符。对应的源码事实可以从 agent.ts 中看到AgentTool 的动态描述在 Usage notes 一节直接写入了新的委派纪律后文详述这正是设计文档落地为真实提示词的证据。设计文档同时声明本次改动不涉及上下文继承与默认后台执行行为边界清晰。父代理委派纪律五条核心约束设计文档要求父代理在委派时遵守以下规则这些规则已经逐条落进 AgentTool 的提示描述中见 agent.ts纪律提示原文要点转述源码位置有界委派Delegate only concrete, bounded tasks that can run independentlyagent.ts关键路径本地化Keep immediate critical-path work local when your next action depends on itagent.ts避免重复工作Do not duplicate work between the parent and subagentsagent.ts并行写范围隔离For code changes, give concurrent agents disjoint write scopesagent.ts整合前审查Treat the agents output as evidence, not as automatically correct. Verify factual claims, review code changes, and run relevant checks before integrating or relaying the resultagent.ts有界委派与关键路径本地化“只委派有界的、可独立完成的具象任务”意味着父代理不能把模糊的“帮我看看这个项目”丢给子代理而“当下一步动作依赖某结果时把即时关键路径工作留在本地”则防止父代理把串行依赖环节交给后台代理后空等。二者共同防止委派链失去控制。并行写范围隔离当父代理决定并行启动多个代码编写代理时必须在单个消息中以多个 Agent 工具调用同时发起且给每个代理不相交的写范围disjoint write scopes避免多个代理同时编辑同一文件导致冲突。提示中还明确“If the user asks for agents in parallel, group independent launches in a single message … Do not parallelize overlapping code changes”可见隔离是并行委派的前提条件。审查义务输出只是“证据”而非结论这是本次护栏最核心的一条父代理必须把子代理输出视为evidence证据在整合或转发前验证事实性声明、审查代码改动、运行相关检查。这条规则同时呼应了提示中“Agent results are not visible to the user, so relay the relevant outcome”的职责——父代理是中转者必须为子代理的结果质量负责。通用子代理提示重构范围、保留、验证、不确定性与结构化报告设计文档要求“简化通用提示并加入范围、保留、验证、不确定性、结构化报告的预期”。落地后的general-purpose代理系统提示位于 builtin-agents.ts核心结构如下You are a general-purpose subagent working for a parent agent. Complete only the assigned task ... Do not expand the scope ... Guidelines: - Inspect the relevant code and existing state before making changes. - Preserve unrelated user changes. // 保留无关改动 - Prefer editing existing files. Do not create files unless necessary... - Verify factual claims before reporting. When making changes, run the smallest relevant checks. // 最小化验证 - Do not guess when evidence is unavailable. Report uncertainty or blockers. // 不确定性如实上报 Notes: - Return a concise report ... containing: the result and key evidence, files changed, verification performed and its outcome, and remaining issues or blockers. // 结构化报告对应设计文档的五个维度范围scope“Complete only the assigned task…Do not expand the scope or perform adjacent work”禁止擅自扩大任务范围保留preservation“Preserve unrelated user changes”改动前先检查现状不碰与任务无关的用户修改验证verification“Verify factual claims before reporting” “run the smallest relevant checks”事实先验证、改动跑最小相关检查不确定性uncertainty“Do not guess when evidence is unavailable. Report uncertainty or blockers”证据缺失时不得猜测必须上报阻塞结构化报告structured reporting报告须包含“结果与关键证据、改动的文件、执行过的验证及结果、遗留问题或阻塞”并约定只在“精确文本是关键信息如 bug 原文、函数签名”时才贴代码片段避免无意义地复述读过的代码。Explore 代理收窄去掉有状态工具、保留只读管道设计文档要求从 Explore 的 allowlist 中移除 task、memory、user question 工具允许 shell 管道但继续禁止一切写入。工具 allowlist 的实际构成Explore 内置代理的tools白名单定义在 builtin-agents.tstools: [ ToolNames.READ_FILE, ToolNames.GREP, ToolNames.GLOB, ToolNames.SHELL, ToolNames.WEB_FETCH, ToolNames.SKILL, ToolNames.LSP, // ASK_USER_QUESTION is deliberately absent: Explore is a read-only // search worker that typically runs as a subagent with no human in // the loop — an interactive question would block forever (#7126). ],注意ASK_USER_QUESTION被有意缺席Explore 是典型的无人值守子代理若允许它发起交互式提问整个管线会永久阻塞对应 issue #7126。这与general-purpose一致——后者同样不接收ask_user_question工具见 agent.ts 的说明。提示中的只读约束与管道许可Explore 的系统提示builtin-agents.ts用“CRITICAL: READ-ONLY MODE”段落逐条列出禁止项创建文件、修改文件、删除、移动/复制、创建临时文件、输出重定向、、heredoc。关键设计点是管道被明确允许但附加条件“pipelines are allowed when every command is read-only and no command sends data to a network endpoint (no curl, wget, nc, or similar)”也就是说grep foo | sort | head这类只读管道可以正常使用但任何向网络端点发送数据的命令curl/wget/nc被禁止。相比旧提示中笼统地禁掉(, , |)新表述消除了“管道是否被允许”的自相矛盾。允许的 SHELL 用途也列得很具体ls, git status, git log, git diff, find, cat, head, tail明确禁止mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install等一切创建/修改操作。fork 代理废除强制提交、强化结构化报告设计文档最后一条是“除非指令明确要求提交否则不再要求 fork 代理提交变更”。fork 代理的 boilerplate 提示位于 fork-subagent.ts其中 RULES 第 5 条原文为5. If you modify files, report the files changed and verification performed. Do NOT create a commit unless the directive explicitly asks you to.这意味着 fork 的默认行为是改动后汇报改了什么文件、做了什么验证把是否提交的决策权交还给父代理/用户而不是自作主张产生提交记录。同时该提示要求输出必须以Scope:开头并按固定标签结构汇报Scope: echo back your assigned scope in one sentence Result: the answer or key findings, limited to the scope above Key files: relevant file paths — include for research tasks Files changed: list — include only if you modified files Verification: checks performed and their outcome — include only if you modified files Issues: list — include only if there are issues to flag其余规则还包括fork 不得再派生子代理“You ARE the fork. Do NOT spawn sub-agents”、不得对话提问ask_user_question不可执行缺输入时在 Issues 中上报阻塞并停止、不在工具调用之间输出文本、报告控制在 500 词以内除非指令另有要求。这份 boilerplate 正是设计文档“fork 报告规则”的完整实现。验证方式单元测试与编译期检查设计文档的 Verification 部分描述了四类断言全部有对应的测试代码印证1. 父代理指导断言AgentTool 动态描述中的“Usage notes”包含上述委派纪律有界委派、并行写隔离、输出作为证据等由 agent.ts 的模板字符串直接承载属于每次请求都会注入的静态提示内容无需专门 mock 即可断言。2. 内置提示内容断言builtin-agents.test.ts 对general-purpose的系统提示逐条断言包含 “Preserve unrelated user changes”保留无关改动包含 “Verify factual claims before reporting”上报前验证事实包含 “run the smallest relevant checks”最小相关检查包含 “Report uncertainty or blockers”上报不确定性/阻塞3. Explore 工具 allowlist 断言builtin-agents.test.ts 提供三组关键断言exploreAgent.tools不包含TODO_WRITE、MEMORY、ASK_USER_QUESTION对应设计文档的“移除 task、memory、user question 工具”系统提示包含 “pipelines are allowed when every command is read-only”且不包含旧的笼统禁令(, , |)印证“允许管道同时禁止写入”的矛盾消除回归测试 #7126Explore 不得拥有ask_user_question工具防止无人值守子代理阻塞管线。4. fork 报告规则断言fork 的 boilerplate 与报告模板由 fork-subagent.test.ts 覆盖同目录下与实现 fork-subagent.ts 配对验证“非显式要求不提交、结构化标签输出”等规则。除此之外核心包packages/core的构建与类型检查build typecheck作为更广泛的编译期检查保证提示模板中的工具名引用如ToolNames.READ_FILE不会漂移失效。设计边界与相关机制设计文档明确划出本次改动的边界上下文继承fork 继承父会话上下文与默认后台执行行为不在本次范围内。从 agent.ts 可见顶层常规子代理默认run_in_background: true、通过完成通知回报结果而 fork 在交互会话中可显式设置run_in_background: true获取通知——这些行为由其他设计文档与实现承担本文所述的护栏只负责“提示与工具面”的约束。与本设计配套的可继续深入阅读的源码入口packages/core/src/tools/agent/agent.tsAgentTool 的完整参数 schemafork_turns、fork_tools、fork_profile、isolation、working_dir等与父代理提示模板packages/core/src/subagents/builtin-agents.tsgeneral-purpose、Explore、statusline-setup、review-agent等全部内置代理定义packages/core/src/tools/agent/fork-subagent.tsfork boilerplate、报告格式与执行限制packages/core/src/subagents/builtin-agents.test.ts上述护栏的单元测试断言packages/core/src/subagents/subagent-manager.ts子代理的加载与解析session project user extension builtin 优先级。小结Subagent Prompt Guardrails 是一次典型的“提示词即安全边界”改造通过收紧父代理的委派纪律、为通用子代理补全执行与验证预期、收窄 Explore 的有状态工具面、取消 fork 的强制提交Qwen Code 在不改变子代理执行引擎的前提下显著提高了多代理协作的质量下限与安全性。对于希望理解或扩展 Qwen Code 代理编排能力的开发者这份设计文档与其在 builtin-agents.ts 和 agent.ts 中的实现是最直接的参照。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考