Qoder 自定义子智能体（Subagent）学习笔记

[Qoder 自定义子智能体（Subagent）学习笔记](#Qoder 自定义子智能体（Subagent）学习笔记)
- [1. 子智能体解决什么问题](#1. 子智能体解决什么问题)
- [2. 文件位置与优先级](#2. 文件位置与优先级)
- [3. frontmatter 字段全表](#3. frontmatter 字段全表)
- - [3.1 tools 只有 8 个官方名字](#3.1 tools 只有 8 个官方名字)
  - [3.2 model 字段：能写，但别指望靠它验证](#3.2 model 字段：能写，但别指望靠它验证)
  - [3.3 skills 是「预加载」，不是「授权」](#3.3 skills 是「预加载」，不是「授权」)
- [4. 系统提示词怎么写](#4. 系统提示词怎么写)
- [5. 本仓库的三角色协作实践](#5. 本仓库的三角色协作实践)
- [6. 验收清单](#6. 验收清单)
- [7. 常见坑速查](#7. 常见坑速查)
- [8. 维护建议](#8. 维护建议)

Qoder 自定义子智能体（Subagent）学习笔记

本文记录在本仓库落地 .qoder/agents/ 三只子智能体的完整认知：字段规范、权限设计、验证方法与踩过的坑。面向后续维护者，也用于给团队新人讲清「为什么要拆 agent，以及怎么拆不踩坑」。

参考来源：官方文档 docs.qoder.com/zh/extensions/subagent（以文档为准，本文只补实测经验）；本仓库实例 .qoder/agents/、docs/07-agents/project-checks.md、AGENTS.md 快速导航表。

1. 子智能体解决什么问题

一句话：用隔离的上下文 + 受限的工具 + 固定的产出格式，把一类任务做稳。

问题	主会话直接做	拆成子智能体
上下文污染	查十几个文件后，噪声留在对话里	子智能体查完只回结论
职责漂移	同一个助手既设计又实现又自评	一个 agent 只做一件事，边界写进 prompt
权限失控	审查者也能改文件	用 `tools` 从工具层限制，而非口头约束
产出不稳定	每次格式随心情	固定输出模板 + 分级标准

不适合拆的场景：一次性小改动、简单问答、需要与用户多轮澄清的任务（子智能体默认不交互）。方案推演类任务也可以直接用 IDE 的 Plan 模式，不必为每个环节都造 agent。

2. 文件位置与优先级

位置	路径	作用域	优先级
用户级	`~/.qoder/agents/<name>.md`	所有项目	低
项目级	`<repo>/.qoder/agents/<name>.md`	当前项目	高

同名时项目级覆盖用户级。项目级适合绑定本仓库规范，可随版本库共享；用户级适合跨项目的个人工作流。

命名要求：小写字母与连字符。避免与内置智能体重名 （Browser、CodeReview、ComputerUse），否则容易误触发或被遮蔽------本仓库审查 agent 命名为 code-auditor 而非 code-reviewer，就是这个原因。

3. frontmatter 字段全表

markdown 复制代码

---
name: implementer
description: 实现工程师，负责按需求直接修改代码文件......
tools: Bash, Read, Write, Edit, Glob, Grep
---

# 角色定义
（这里是系统提示词，也就是给这个 agent 的长期指令）

字段	必填	说明
`name`	是	唯一标识，小写 + 连字符
`description`	是	自动调度的唯一依据，要写清「做什么 / 何时用 / 不做什么」
`tools`	否	逗号分隔，不给则按默认权限
`model`	否	`"[模型名](modelId)"`，不写跟随会话模型
`skills`	否	预加载到该子智能体上下文的技能名
`mcpServers`	否	限定或追加 MCP server

易错点：内置的 /create-agent 技能文档只列了 name / description / tools 三项。不能据此判断 model / skills / mcpServers 无效------这三项在官方扩展文档的字段表里是明确支持的。

3.1 tools 只有 8 个官方名字

Bash、Edit、Write、Glob、Grep、Read、WebFetch、WebSearch。

编辑用 Edit，不要写 SearchReplace 之类主会话工具名，写了会被忽略（功能不坏，但属无效配置）。
权限设计按最小必要：只读审查 agent 不给 Edit / Write；需要跑测试才给 Bash。
注意 Bash 是双刃剑：审查 agent 拿到 Bash 就能跑 eslint --fix、prettier --write，会把「只读」变成「能改」。所以必须在 prompt 里写死命令黑名单（本仓库见 docs/07-agents/project-checks.md §1）。

3.2 model 字段：能写，但别指望靠它验证

格式：model: "[Qwen3.8-Max](qmodel_38max)"，括号里是内部 id，外面是显示名。
id 真伪可在 %APPDATA%\Qoder\User\dynamic-text-cache.json 的 modelSelector.item.<id> 词条核对（已核实：dfmodel=DeepSeek-Flash、qfmodel=Qwen3.8-Flash、qmodel_38max=Qwen3.8-Max）。
写错 id 通常静默回退到会话模型，不报错，所以「没报错」不等于「生效」。
实测结论：%APPDATA%\Qoder\SharedClientCache\cache\ai_tracker\**\*.jsonl 里的 modelName 不能用来判断子智能体模型 ------它把子智能体的编辑归到父会话（两次子会话调用的 userQueryBusinessId 完全相同），改 frontmatter 前后都报父会话模型。
因此本仓库的取舍：不写 model，跟随会话模型。歧义最小，行为最可预测；确需固定，只能靠输出风格/耗时对比或官方渠道确认。

3.3 skills 是「预加载」，不是「授权」

skills 会把技能内容注入该子智能体的上下文。含义有两点：

名称必须解析得到：~/.qoder/skills/<目录名> 或插件限定名 plugin:skill。
会持续占用上下文预算，挂不相关技能等于每次调用都白烧 token。

选择标准只有一条：技能必须直接服务于该 agent 的核心动作 。反例（本仓库曾经踩过）：给只读审查 agent 挂 frontend-design（视觉设计指导）、给方案设计 agent 挂 canvas-design（海报生成）------都属无效预加载，已清空。

4. 系统提示词怎么写

一个可复用的骨架，本仓库三只 agent 均按此结构：

markdown 复制代码

# 角色定义
你是谁、只做什么、不做什么（一句话讲清边界）

## 工作流程
1. 先做什么（通常是读规范 / 看差异）
2. 再做什么（核实现状，禁止凭印象）
3. 怎么产出行结论

## 输出格式
固定分段，例如「必须修复 / 建议修复 / 待核实 / 总体结论」

## 约束
**必须做：** ......（带判据，不写口号）
**禁止做：** ......（写清红线与例外）

写作要点：

描述动作，不写工具名。写「查看工作区差异」而不是「调用 Bash 执行 git diff」，工具改名时不至于失效。
约束要有判据 。「注意金额精度」是口号；「聚合结果进 DTO 前过 round2；前端金额不得裸渲染」才可执行。
写清不做什么 。description 里明确「不负责需求澄清、不做审查结论」，能明显减少误调度。
不设计交互。子智能体默认自主运行，需要澄清的环节交给主会话。

5. 本仓库的三角色协作实践

环节	agent	权限	输入 → 输出
方案设计	`solution-designer`	只读	待评估需求 → 七段式方案 + 待决策问题
代码实现	`implementer`	读写 + 命令	已明确方案 → 代码改动 + 验证结果
代码审查	`code-auditor`	只读	已完成改动 → 分级问题清单

三条落地原则：

入口可发现 ：AGENTS.md 快速导航表登记三个入口，按「方案设计 → 代码实现 → 代码审查」排列，读规范时顺手知道该找谁。
规范单一来源 ：三只 agent 共用的检查项抽取到 docs/07-agents/project-checks.md，prompt 里只写「读哪一节」。禁止在三份 prompt 里各抄一份------下次改规范要改三处，必然漂移。
职责不重叠：设计不写代码，实现不做审查结论，审查不落修复。想要「改完顺手审」时，宁可多一次调度，也不要让实现者自评。

6. 验收清单

新建或改动 agent 后，按此清单确认真的生效，而不是「文件写对了」：

手动触发 /agent-name 做一个只读小任务，确认能被找到。
用自然语言描述任务，确认 description 能命中自动调度。
权限边界实测：让只读 agent 尝试写文件，应无法调用写工具；让实现 agent 改一个文件，应能成功。
输出格式符合模板分段，没有退回成自由发挥的长段落。
只读 agent 未执行改文件的命令（如 lint --fix、format）。
若配置了 skills / mcpServers，确认名称解析成功、内容与职责相关。
不要用 ai_tracker 的 modelName 判断模型是否生效（见 §3.2）。

7. 常见坑速查

现象	根因	处理
以为 `skills` / `model` 不支持	只看了内置 create-agent 文档的三字段列表	以官方扩展文档字段表为准
配了 `SearchReplace` 但没生效	非官方工具名	用 `Edit`
模型像没变，但也没报错	modelId 写错会静默回退	用 i18n 缓存核对 id；或干脆不写
上下文莫名变长、回答变慢	`skills` 挂了不相关技能	只挂直接服务于核心动作的技能
审查 agent 实际改了文件	给了 `Bash` 却没禁 `--fix` 命令	prompt 写死命令黑名单 + 只读清单
三个 agent 的清单越改越不一致	规范被复制到三份 prompt	抽到共享文档，prompt 只引用章节
子智能体与内置能力抢触发	命名冲突	换名，如 `code-auditor` 而非 `code-reviewer`

8. 维护建议

新增 agent 前先回答三个问题：它负责哪一段？它的产出谁来消费？它不能做什么？答不全说明还不该拆。
规范变更只改两处：AGENTS.md（业务/工程规则）与 docs/07-agents/project-checks.md（agent 执行口径）。prompt 里只维护「读哪一节」的引用。
.qoder/agents/ 与共享清单都应进版本库，让团队用同一套口径；个人偏好放用户级目录，不要混进项目级。
改动 agent 后按 §6 验一遍，别只检查 YAML 语法------格式正确但边界失效，比写错字段更难发现。