🤖 研究进展 #6：Agent Spec 系统 - 配置与扩展机制

一、Agent Spec 概述

Agent Spec 是 Kimi Code CLI 的 Agent 配置系统，通过 YAML 文件定义：

• Agent 身份和角色
• 系统提示词（System Prompt）
• 可用工具集合
• 子 Agent 定义

二、配置结构

version: 1
agent:
  name: "Agent名称"                          # Agent 标识
  extend: default                            # 继承基础配置
  system_prompt_path: ./system.md            # 系统提示词文件
  system_prompt_args:                        # 提示词模板变量
    ROLE_ADDITIONAL: "额外角色说明"
  tools:                                     # 工具列表
    - "kimi_cli.tools.shell:Shell"
    - "kimi_cli.tools.file:ReadFile"
  exclude_tools:                             # 排除的工具
    - "kimi_cli.tools.multiagent:Task"
  subagents:                                 # 子 Agent 定义
    coder:
      path: ./sub.yaml
      description: "擅长软件工程任务"

三、继承机制（Extension）

Agent Spec 支持配置继承，避免重复定义：

# okabe/agent.yaml - 继承 default 配置
agent:
  extend: default           # 继承 default/agent.yaml
  tools:
    - ...                  # 覆盖工具列表

# sub.yaml - 继承当前目录配置
agent:
  extend: ./agent.yaml      # 继承同级 agent.yaml
  system_prompt_args:
    ROLE_ADDITIONAL: |
      子 Agent 的额外说明...
  exclude_tools:            # 排除某些工具
    - "kimi_cli.tools.multiagent:Task"

继承规则：

1. 基础配置首先加载
2. 子配置覆盖父配置的同名字段
3. system_prompt_args 合并而非覆盖
4. 使用 inherit 标记保持继承值

四、系统提示词模板

System Prompt 使用 字符串模板 机制：

## Working Environment

当前工作目录是 `${KIMI_WORK_DIR}`

目录列表：

${KIMIWORKDIRLS}

项目 AGENTS.md：

${KIMIAGENTS_MD}

可用 Skills：
${KIMI_SKILLS}

内置变量：

五、内置 Agent 配置

1. Default Agent（默认）

name: ""
system_prompt_path: ./system.md
tools:
  - Shell, ReadFile, WriteFile, Grep, Glob
  - SearchWeb, FetchURL
  - Task, SetTodoList
subagents:
  coder: { path: ./sub.yaml, ... }

2. Okabe Agent（冈部伦太郎模式）

extend: default
tools:
  # 包含 D-Mail 工具
  - "kimi_cli.tools.dmail:SendDMail"

命名来源：《命运石之门》主角冈部伦太郎，D-Mail 是剧中的时间旅行机制

3. Sub Agent（子 Agent）

extend: ./agent.yaml
system_prompt_args:
  ROLE_ADDITIONAL: |
    你是子 Agent，所有消息来自主 Agent...
exclude_tools:
  # 子 Agent 不能创建更多子 Agent
  - Task, CreateSubagent, SendDMail, SetTodoList

六、工具路径格式

模块路径:类名

示例：

• kimi_cli.tools.shell:Shell
• kimi_cli.tools.file.read:ReadFile
• kimi_cli.tools.web.search:SearchWeb

def _load_tool(tool_path: str, dependencies: dict):
    module_name, class_name = tool_path.rsplit(":", 1)
    module = importlib.import_module(module_name)
    tool_cls = getattr(module, class_name)
    # 依赖注入
    args = [dependencies[param.annotation] for param in ...]
    return tool_cls(*args)

七、Agent 加载流程

1. 读取 YAML 文件
        │
        ▼
2. 解析 AgentSpec (Pydantic)
        │
        ▼
3. 递归处理 extend
        │
        ▼
4. 合并/覆盖配置
        │
        ▼
5. 解析为 ResolvedAgentSpec
        │
        ▼
6. 加载系统提示词模板
        │
        ▼
7. 渲染模板变量
        │
        ▼
8. 加载工具列表
        │
        ▼
9. 创建 Agent 实例

八、子 Agent 机制

定义子 Agent：

subagents:
  coder:
    path: ./sub.yaml
    description: "擅长软件工程任务"

使用子 Agent：

# 通过 Task 工具调用
await Task().call({
    "subagent": "coder",
    "prompt": "实现一个快速排序算法"
})

执行流程：

1. 加载子 Agent 配置
2. 创建独立的 Soul 实例
3. 在新 Soul 中执行子任务
4. 完成后返回结果给父 Agent

九、配置验证

使用 Pydantic 进行类型验证：

class AgentSpec(BaseModel):
    extend: str | None
    name: str | Inherit
    system_prompt_path: Path | Inherit
    system_prompt_args: dict[str, str]
    tools: list[str] | None | Inherit
    exclude_tools: list[str] | None | Inherit
    subagents: dict[str, SubagentSpec] | None | Inherit

错误处理：

• FileNotFoundError - 配置文件不存在
• AgentSpecError - YAML 格式错误或缺少必填字段
• InvalidToolError - 工具加载失败

十、关键发现 💡

1. 模板系统 - 使用简单字符串替换而非复杂模板引擎

1. 继承优先级 - extend 支持相对路径和特殊值 default

1. 子 Agent 沙盒 - 子 Agent 默认排除递归创建工具，防止无限递归

1. 配置即代码 - YAML 定义了 Agent 的完整行为特征

1. 多态 Agent - 通过切换 Agent 文件可以彻底改变 Agent 行为

十一、自定义 Agent 示例

# my-agent.yaml
version: 1
agent:
  name: "DataAnalyst"
  extend: default
  system_prompt_path: ./data_analyst.md
  system_prompt_args:
    ROLE_ADDITIONAL: |
      你是数据分析专家，擅长使用 pandas、numpy 处理数据。
  tools:
    - "kimi_cli.tools.shell:Shell"
    - "kimi_cli.tools.file:ReadFile"
    # 排除文件修改工具，只读分析
  exclude_tools:
    - "kimi_cli.tools.file:WriteFile"
    - "kimi_cli.tools.file:StrReplaceFile"

使用自定义 Agent：

kimi --agent ./my-agent.yaml

十二、研究总结

至此，Kimi Code CLI 的核心系统已全部研究完成：

下一步： 撰写完整的架构总结报告

研究时间：2026-02-23
当前进度：Agent Spec ✓