野生码农
Kimi Code 自定义 agent 机制复盘:四轮问答摸清工具闸门,顺手实测满血岗技能链路
背景与目标
我在研究 Kimi Code CLI 的自定义 agent 机制——就是 .agents 目录下用 Markdown 文件定义数字员工的那套东西。本项目走"军师+数字员工"架构:军师负责架构治理不亲手执行,满血岗(manxue-coder/manxue-ceshi)负责落地,技能按需注入不占上下文。
目标很直接:让军师查官方文档(https://www.kimi.com/code/docs/en/kimi-code-cli/customization/agents.html),把这套机制的能力边界问清楚,特别是工具控制和技能调度两块——这决定了我能给数字员工开多大权限、怎么派单才最可靠。
过程回顾
问答 1:自定义智能体能否明确哪些工具能调、哪些不能?
结论:能,而且是白名单+黑名单双闸门。
每个 agent 是一个 Markdown 文件,frontmatter 里声明:
tools:白名单。省略或写*= 全部工具;tools: []= 全禁;disallowedTools:黑名单,在白名单之后生效。
匹配规则有两个易错点:内置工具按精确大小写敏感名称匹配;MCP 工具必须用完整 glob,如 mcp__github__*——写成 mcp__github 这种不完整形式匹配不到任何东西。
限制是双保险:既决定模型能看到哪些工具,执行前还会再校验一次。另有 subagents 字段控制可派单给哪些子代理,默认继承 coder/explore/plan,防无限递归。项目级目录是 .kimi-code/agents/ 或 .agents/agents/——注意是 agents 子目录,不是 .agents/ 根。
问答 2:自定义 agent 和"满血模式"什么区别?
结论:满血岗本身就是这套机制的实例,不是另一套体系。
满血 = 不写 tools 白名单(工具全开) + 正文写入岗位铁律(实测重放留证据、文件写入互斥等)。也就是说,满血岗的"满血"不是特权,只是配置上的一个特例。
内置子代理工具集是固定的:explore 只读,plan 连 shell 都没有。
军师还给了一条安全警告:项目级 agent 文件是 system prompt 本体(不像 AGENTS.md 只是参考数据)。陌生仓库里放一个 agent.md + override: true 就能整体替换主 Agent 提示词——所以跑不可信仓库前,要先审 .agents/agents/。
问答 3:内置子代理能否加载自定义技能?
结论:coder 能,explore/plan 不能。
coder 有 Skill 工具,既能按技能的 description/whenToUse 自动触发,也能派单时点名。explore/plan 工具集被刻意收窄,没有 Skill 工具。想改可以用同名文件 + override: true 覆盖内置 agent。
问答 4:manxue-coder/manxue-ceshi 能否自由调度自己写的技能?
结论:能,而且有文件级实测证据。
这一问我没停留在文档层面,要求军师实测核实 .agents/agents/coder.md 和 .agents/agents/ceshi.md——两者 frontmatter 均未写 tools 字段,按规则保留全部工具,含 Skill。
技能调度有三种方式:
- 自动触发(按 description/whenToUse);
- 派单点名(推荐)——硬指令比模型自觉可靠;
- agent 正文写死。
两个例外:技能设 disableModelInvocation: true 或 type: flow 的,子代理用不了;技能嵌套最多 3 层。
收尾:把答疑变成实测
我指示"派 manxue-coder 用博客技能复盘本次会话"——也就是本篇的产出任务。这不是顺手,是有意为之:答疑问清了机制,但机制活不活,得跑一次"满血岗 + 自定义技能"的真实链路才算数。
关键踩坑(本场是认知纠偏,非报错)
本场没有程序报错,踩的是认知坑,三个:
- MCP 工具 glob 不完整写法匹配不到任何东西(
mcp__github≠mcp__github__*)——配置时极易写错,且错了是静默不生效; - 项目级目录是
.agents/agents/子目录,不是.agents/根——路径放错等于没配; - 误以为满血岗是另一套体系——被军师纠正:它只是"不写 tools 白名单"的自定义 agent 实例,机制是同一套。
最终方案(机制结论汇总)
- 工具控制:
tools白名单 +disallowedTools黑名单,双保险(可见性 + 执行前校验); - 满血岗定位:机制实例,工具全开靠省略
tools,纪律靠正文铁律; - 技能调度:三种方式里派单点名最可靠,本次任务卡即按此执行(硬指令"先用 Skill 工具加载 ai-dev-blog");
- 安全基线:跑陌生仓库前先审
.agents/agents/,防override: true偷换 system prompt。
做得好的地方
- 问题链是递进的:机制(能不能控)→ 定位(满血是什么)→ 边界(内置子代理行不行)→ 实测(满血岗行不行),四轮问完全貌;
- 第四问没有停在"文档说能",而是要求实测核实两个 agent 文件的 frontmatter,拿到文件级证据;
- 收尾直接把答疑会话变成链路实测,一鱼两吃。
复盘与改进
不足:本场止步于"问清机制",结论目前只落到文档与配置层,尚未在真实开发任务里复用(比如给某个岗位实际收窄工具白名单)。
改进一条:把机制结论转成治理动作——陌生仓库派单前置检查项加"先审 .agents/agents/",别让安全警告只停留在复盘文里。
成长评估(10 分制,只对事)
| 维度 | 分 | 证据 |
|---|---|---|
| 指令与提示词质量 | 9 | 四轮问题逐层聚焦;第四问带"实测核实 coder.md/ceshi.md"的验证要求,不接受口头结论;本任务卡硬指令明确技能名与路径 |
| 判断与结论 | 8 | 采纳"派单点名"为推荐调度方式,理由是"硬指令比模型自觉可靠",且当场写进任务卡硬指令,判断落到了执行结构 |
| 思维方式 | 8 | 机制→实例→边界→实测的闭环;"本任务同时也是链路实测"把答疑变成验证实验 |
| 最终结果与产出 | 8 | 机制全貌到手、文件级证据到手、链路实测落地(本稿);未满分:结论尚未在真实开发任务中复用 |
| AI 协作能力 | 9 | 任务卡带事实红线("只允许使用上面给出的素材")、文件写入互斥、链路实测报告要求,从制度上堵死虚构空间 |
低分项改进(判断 8 / 思维 8 / 结果 8):问答类会话收尾强制一问"这些结论哪条要落成机制条款",答不出就把结论挂进待办,不停在聊天层。
AI 自评(同场失分点):素材中无军师被本人抓错的记录,如实登记为零。本稿由满血岗(manxue-coder)代笔,自承两点风险:①成长评估是 AI 给本人打分,尺度可能偏松,以本人终审为准;②会话具体时分素材未给,frontmatter 时间以占位符处理,未编造。
素材点(可抄走的东西)
Kimi Code 自定义 agent 工具控制速查清单:
frontmatter 字段:
tools: 白名单(省略或 * = 全开;[] = 全禁)
disallowedTools: 黑名单(白名单后生效)
subagents: 可派单的子代理(默认 coder/explore/plan)
匹配规则:
内置工具 → 精确大小写敏感名称
MCP 工具 → 必须完整 glob:mcp__github__*(mcp__github 匹配不到)
项目级目录: .kimi-code/agents/ 或 .agents/agents/(注意 agents 子目录)
安全: agent 文件 = system prompt 本体,陌生仓库先审 .agents/agents/
技能调度: 自动触发 / 派单点名(推荐) / 正文写死
例外: disableModelInvocation: true、type: flow 子代理用不了;嵌套最多 3 层
本篇由 manxue-coder 按 ai-dev-blog 技能流程产出,本身即"满血岗+自定义技能"链路实测的交付物。