# 智能体配置注册规范

智能体 agent.json 配置文件的注册规范，确保提示词文件被正确加载。

## 1. agent.json 配置文件字段说明

| 字段名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| name | string | 是 | 智能体唯一标识（英文名，小写蛇形命名） |
| title | string | 是 | 智能体中文标题/名称 |
| description | string | 是 | 智能体职责描述，50字以内 |
| group | string | 是 | 所属分组，如 master/develop/design/media/agent |
| tags | string[] | 是 | 标签数组，用于技能匹配和知识关联 |
| main | string | 否 | 主入口文件路径 |
| scope | string | 否 | 作用域：sys（系统级）/ proj（项目级）/ user（用户级） |
| sort | number | 否 | 排序权重，数值越小越靠前 |
| state | number | 否 | 状态：1-启用，0-禁用 |
| show | number | 否 | 是否展示：1-展示，0-隐藏 |
| end | boolean | 否 | 是否终态：true/false |

## 2. 提示词文件加载机制

智能体启动时，系统会自动加载 agent.md 提示词文件（位于智能体目录下）：

| 文件名 | 说明 |
|-------|------|
| agent.md | 智能体提示词文件，包含角色定位、职责权限等所有提示词内容 |

### 2.1 加载规则

- 系统自动读取 agent.md 文件内容，作为智能体的固定提示词
- 干系人协作关系从 agent.json 的 stakeholders 字段读取
- 文件不存在时不影响系统启动，但智能体将缺少提示词内容
- 文件编码使用 UTF-8

### 2.2 注意事项

- agent.md 与 agent.json 必须放在同一目录下
- 文件名必须为 agent.md（大小写敏感）

## 3. agent.md 提示词格式规范

智能体提示词统一使用 `agent.md` 单文件，包含以下内容：

### 3.1 章节结构

| 章节 | 标题 | 必填 | 说明 |
|:----|:-----|:----:|:------|
| 职业定位 | `## 职业定位` | ✅ | 一句话定义智能体角色，如 `**UI设计师** - 根据项目需求设计用户界面` |
| 核心职责 | `## 核心职责` | 推荐 | 用 `1. **职责名**：说明` 的编号格式，列出核心职责 |
| 职责权限 | `## 职责权限` | ✅ | 包含以下权限子章节，定义智能体的行为边界 |

### 3.2 职责权限子章节

| 子章节 | 标题 | 必填 | 说明 |
|:------|:-----|:----:|:------|
| 应该做的事 | `### ✅ 应该做的事` | ✅ | 用 `-` 列表列出该智能体应执行的具体任务 |
| 不该做的事 | `### ❌ 不该做的事` | ✅ | 用 `-` 列表明确禁止的具体行为 |
| 能自己决定的事 | `### 🟢 能自己决定的事` | 推荐 | 用 `-` 列表列出可自主决策的事项 |
| 绝对不能碰的事 | `### 🔴 绝对不能碰的事` | 可选 | 用 `-` 列表列出绝对禁区（如系统权限、安全配置等） |
| 要先问过用户的事 | `### 🟡 要先问过用户的事` | 推荐 | 用 `-` 列表列出需要上报确认的事项 |
| 要先问过 master 的事 | `### 🟡 要先问过 master 的事` | 推荐 | 替代上方，用于 master 以外的智能体 |

### 3.3 格式规范

- 使用 `##` 二级标题分章节，`###` 三级标题分权限子章节
- 所有列表使用 `-` 无序列表
- 描述使用大白话，一句话说清楚
- **禁止出现**"我"、"我的"等代名词
- 禁止混入技能级的执行步骤（如工具调用、文件操作等）

### 3.4 示例

```markdown
## 职业定位

**UI设计师** - 根据项目需求制定UI设计规范、组件库说明，并生成界面代码文件

## 核心职责

1. **定规范**：制定UI设计规范和视觉标准，设计可复用的组件库
2. **做界面**：设计用户界面布局和视觉元素，制作交互原型
3. **出代码**：生成.html、.css、.js、.svg等界面代码文件

## 职责权限

### ✅ 应该做的事
- 制定UI设计规范和视觉标准
- 设计UI组件库和设计系统
- 设计用户界面和交互方案

### ❌ 不该做的事
- 直接修改前端代码或技术实现
- 处理业务数据或数据库操作

### 🟢 能自己决定的事
- 常规UI界面设计和交互方案制定
- 标准设计规范和组件库设计

### 🟡 要先问过 master 的事
- 需大幅调整已确认的设计方案
- 设计方案可能引发重大用户体验问题
```

## 4. 多环境配置注意事项

| 环境类型 | 配置要点 | 说明 |
|---------|---------|------|
| 开发环境 | debug模式 | 开启详细日志，方便排查问题 |
| 测试环境 | 模拟数据 | 使用测试数据验证配置正确性 |
| 生产环境 | 性能优化 | 关闭调试日志，开启缓存机制 |

### 4.1 环境变量配置

- 通过环境变量区分不同环境（DEV/TEST/PROD）
- 敏感信息（API Key、Token等）通过环境变量注入
- 文件路径根据环境自动适配

### 4.2 配置继承与覆盖

- 基础配置在 agent.json 中定义
- 环境特定配置在对应环境的配置文件中定义
- 环境配置优先级高于基础配置

## 5. 配置验证和错误排查指南

### 5.1 配置验证清单

| 检查项 | 检查内容 | 验证方法 |
|-------|---------|---------|
| 名称唯一性 | name 是否与其他智能体重复 | 全局搜索检查 |
| 文件存在性 | 引用的提示词文件是否存在 | 检查文件路径 |
| 格式正确性 | JSON 格式是否合法 | JSON 语法校验 |
| 字段完整性 | 必填字段是否填写完整 | 对照字段说明表 |
| 编码一致性 | 文件编码是否为 UTF-8 | 查看文件编码 |

### 5.2 常见错误及解决方案

| 错误现象 | 可能原因 | 解决方案 |
|---------|---------|---------|
| 智能体未加载 | agent.json 格式错误 | 检查 JSON 语法，确保无多余逗号 |
| 提示词未生效 | 文件名或路径错误 | 确认文件名与加载规则一致 |
| 技能调用失败 | 技能名称不匹配 | 检查技能名称大小写和拼写 |
| 标签匹配异常 | 标签不一致 | 确认知识标签与智能体标签一致 |
| 环境配置不生效 | 环境变量未设置 | 检查环境变量是否正确注入 |

### 5.3 调试建议

- 首次配置时，先添加最少的必要字段，逐步扩展
- 修改配置后重启智能体使配置生效
- 使用日志输出确认各阶段提示词加载情况
- 配置变更后验证核心功能是否正常