CodeBuddy的Agent角色功能，本质上就是为AI设定一个“专业身份”。比如，当您需要处理数据库迁移时，每次都要反复叮嘱“检查SQL语法、生成回滚脚本、校验目标库兼容性”这些步骤——不如直接创建一个“MySQL迁移守门人”角色，一次配置，永久复用。该角色可以绑定sql-linter、rollback-generator等技能，打通MCP通道，配置manual权限和Plan模式，实现全流程自动化执行。

明确角色定位与能力边界

首先打开CodeBuddy IDE右下角的「Agent管理」面板，点击「+新建角色」。先不要急于填写名称，停顿三秒，自问：这个角色要替我承担哪类具体职责？是“前端组件审核员”还是“遗留系统重构顾问”？如果起一个模糊的“Java专家”，AI的行为就会变得不稳定——必须绑定具体的职责域。

输入角色名时，建议采用动宾结构命名。例如，“MySQL迁移守门人”比“数据库助手”更有效——CodeBuddy会将动词“守门”自动映射为校验、拦截、预警等动作倾向。名称中必须包含领域关键词，如“Spring Boot”“Figma转码”“TAPD同步”，否则Skills将无法按需加载。

注入核心约束与知识锚点

在「系统指令」文本框中，粘贴三条硬性规则：第一行写明角色身份（例如：“你是一名专注金融级数据迁移的DBA，已通过Oracle ACE认证”）；第二行写明不可妥协的底线（例如：“所有生成的SQL必须通过EXPLAIN验证执行计划，未验证则拒绝输出”）；第三行挂载知识源（例如：“严格遵循@knowledge:bank-migration-rules中的12条合规条款”）。

这三行缺一不可。缺少第一行，AI会降级为通用模型；缺少第二行，它可能跳过安全检查；缺少第三行，私有规范将失效。粘贴后立即点击右侧「测试指令」按钮，输入“生成ALTER TABLE添加非空字段语句”，观察是否触发合规条款引用——如果没有引用，说明知识锚点未生效。

绑定技能包与工具链

方法一：拖拽式绑定
在「可用Skills」列表中，找到已预装的「sql-linter」和「rollback-generator」技能包，直接拖拽到角色卡片的「已启用」区域。拖拽完成后图标变为蓝色，表示技能已成功注入该角色上下文。

方法二：命令行强制关联
在终端执行：codebuddy agent update "MySQL迁移守门人" --add-skill sql-linter --add-skill rollback-generator。这一步可以绕过UI缓存，确保技能版本与本地仓库完全一致。

注意：如果列表里找不到目标Skill，请先确认该Skill文件夹内存在有效的SKILL.md文件，且YAML元数据中的name字段与列表显示名完全一致——大小写或空格差异都会导致识别失败。

配置权限与执行模式

第一步：选择权限模式
勾选「manual」手动模式。这是关键的安全阀，尤其当角色涉及DROP TABLE或生产环境部署时，每一步操作都必须手动敲击回车确认，避免误触发不可逆操作。

第二步：设定工作流起点
在「默认模式」下拉菜单中，选择「Plan」而非「Craft」。因为迁移类任务必须先输出执行路径图、风险评估矩阵、回滚预案这三项内容，您签字确认后才允许生成SQL——这比直接执行更可靠。

第三步：绑定MCP通道
展开「外部连接」设置，勾选「本地MySQL实例」和「TAPD需求看板」。此时角色才能读取真实表结构并同步更新工单状态，脱离这两项，它就成了纸上谈兵的理论派。

验证与快速迭代

① 在对话框输入：“用‘MySQL迁移守门人’角色，对user_profile表添加phone_hash字段，要求支持在线加字段且不锁表”。
② 观察返回内容是否包含三部分：a) 执行方案（推荐ALGORITHM=INSTANT）、b) 风险提示（提醒旧版本MySQL不支持）、c) 回滚语句（DROP COLUMN）。
③ 若缺少任意一项，立即点击角色卡片右上角「调试」按钮，查看日志中报错的Skill加载路径——通常问题出在scripts目录下Python脚本缺少shebang头或权限未设为可执行。