智能体

智能体（Agent）是面向多样化开发场景的编程助手。码道CLI内置了多款开箱即用的智能体，这些智能体无需手动创建，即拿即用，旨在为多种开发场景提供高效的编程辅助。除了内置智能体，还支持自定义智能体功能。

内置智能体

内置智能体分为主智能体和子智能体。主智能体是您直接交互的主要助手，可以使用Tab键来循环切换，这些主智能体处理您的主要对话。子代理是主代理可以调用来执行特定任务的专业助手，可以通过在消息中@子智能体来手动调用。

表1 内置智能体列表
分类	创建者	说明
主智能体	系统内置	码道CLI内置了两个核心主智能体Build和Plan，分别承担开发与规划职责。 Build主智能体默认的开发执行智能体，拥有完整工具访问权限，适用于需要实际修改代码、执行命令或创建文件等真实开发操作场景。典型使用场景：编写、修改或删除代码文件执行构建、测试、部署等终端命令创建新功能模块或修复Bug 对项目进行任何需落地变更的实际操作 Plan主智能体受约束的只读型智能体，专注于分析代码结构、设计解决方案与制定实施计划，不会对代码库做任何实质性修改。典型使用场景：分析代码结构和逻辑设计功能方案或重构策略 Bug定位和修复方案规划架构评审和可行性分析任何需要“先想清楚再做”的场景
子智能体	系统内置	子智能体是主智能体可以调用来执行特定任务的专业助手，您可以通过在消息中@子智能体来手动调用。说明：您可以通过如下命令，查看系统内置的子智能体：在CLI环境中：codearts run "自然语言描述"，自然语言描述中必须要带subagent关键词。在TUI环境中：在输入框中，直接输入@即可查看。 developer-test-agent：专门用于单元测试生成、修复、覆盖率优化，审查真实代码库。 explore：代码库探索智能体，专门用于快速查找文件、搜索代码关键词、回答代码库相关问题。 general：通用智能体，用于研究复杂问题和执行多步骤任务。 rule-generator：规则生成器。 spec-design-agent：生成综合技术设计，将需求（做什么）转化为架构（如何做）。 spec-requirement-agent：基于项目描述和上下文生成EARS格式需求。 spec-task-agent：根据需求和设计生成实现任务。

自定义智能体

除了系统内置的智能体外，码道CLI还支持自定义智能体功能。存在同名的项目级和个人级智能体时，项目级智能体优先级高于个人级智能体。

表2 自定义智能体分类
分类	作用域	说明
自定义主智能体自定义子智能体	项目级	仅针对当前项目的智能体，随代码库分发，存于本地。存储位置：项目根目录/.codeartsdoer/agents
自定义主智能体自定义子智能体	个人级	个人习惯或特定偏好的智能体，仅对本用户下的所有项目生效。存储位置：~/.codeartsdoer/agents “~”表示当前用户的主目录，Windows下等同于“C:\Users\用户名\”，macOS下等同于“/Users/用户名/”，Linux下等同于/home/用户名/

通过Markdown文件创建智能体

码道CLI支持通过新建Markdown文件，配置本地项目级或本地个人级智能体。存在同名的项目级和个人级智能体时，项目级智能体优先级高于个人级智能体。

自定义智能体文件格式

自定义智能体采用Markdown文件格式编写，文件头部配置YAML Frontmatter元信息，主体承载提示词角色指令。

---
description: Agent desc  # 智能体功能描述
mode: subagent           # 智能体描述信息
model: provider/model     #如果参照此格式配置模型，将覆盖默认模型
tools:                   # 工具权限配置
  tool1: true           # 允许使用tool1
  tool2: false            # 禁止使用tool2
---

# 提示词
这里是智能体的系统提示词内容

上述自定义智能体各参数填写规范如下表所示：

表3 Markdown文件参数说明
参数	是否必选	参数类型	默认值	描述
description	是	字符串	不涉及	自定义智能体的描述。
mode	是	字符串	subagent	设置智能体的角色。 subagent：只能当作子智能体被调用。 primary：只能当主智能体，不能被调用。 all：既能当主智能体，也能当子智能体被调用。
model	否	字符串	不涉及	格式为：provider/model
tools	否	对象	不涉及	控制智能体可使用的工具权限，码道CLI支持的工具如表5，您也可以使用“”匹配所有工具。示例： tools： "":false #表示禁止所有工具
hidden	否	布尔值	不涉及	可见性控制。设为“true”时，从@自动补全菜单中隐藏。适用于仅供编程调用的内部代理。
disable	否	布尔值	不涉及	开关控制。 true：禁用该智能体 false：启用该智能体
提示词	是	字符串	不涉及	自定义智能体的系统提示词。

表4 tools对象取值说明
参数	说明
true	允许使用该工具
false	禁止使用该工具

表5 码道CLI支持的工具
工具	说明
read	读取文件
write	写入文件
edit	编辑文件
bash	执行命令
glob	文件模式匹配
grep	内容搜索
task	子任务
webfetch	获取网页
question	询问用户

自定义智能体示例

本示例以Windows系统下配置个人级子智能体为例。

进入“~/.codeartsdoer/agents”目录下，创建“test.md”文件，写入如下内容。

“~”表示当前用户的主目录，Windows下等同于“C:\Users\用户名\”，macOS下等同于“/Users/用户名/”，Linux下等同于/home/用户名/

---
# ========== 必填项 ==========
description: 智能体的功能及使用场景描述（必填，主智能体据此判断调用时机）
mode: subagent            # 枚举值：subagent子智能体 / primary主智能体 / all两者通用

# ========== 模型配置 ==========
model: provider/model-id  # 自定义模型，格式规范：provider/model-id，执行“/models”可查看支持的模型

# ========== 行为控制 ==========
hidden: false              # true：隐藏@联想菜单，仅程序内部调用
disable: false             # true：停用当前代理

# ========== 工具权限 ==========
tools:
  write: false              # 文件写入权限
  edit: false               # 文件编辑权限
  bash: false               # 系统命令执行权限
  read: false               # 文件读取权限

# 系统提示词（支持多行Markdown格式）
你是一名资深代码审查专家。请重点关注：

-代码质量与最佳实践
-潜在Bug和边界情况
-性能影响
-安全隐患

提供建设性反馈，不要直接修改代码。