<!-- locale: zh-CN -->

# create-agent 技能

## L0：一句话摘要

通过自然语言对话收集需求，调用 ManageAgent 内置工具创建专业化的数字智能体。

## L1：概述

元技能：多轮对话收集需求 → 生成 persona/principles → `ManageAgent(action='create')` 落地。用于为用户培养专业领域数字助手（法律顾问、财务分析师）、企业快速部署定制业务 Agent、或基于模板快速创建原型。创建的仓库符合 AgentFS v2 规范、由 git 管理版本（可治理、可追溯）。价值在工具给不了的部分：领域化的人格/原则生成 + 创建前的预览确认。

## L2：详细规范

流程：意图识别 → 需求收集 → 内容生成 → 用户确认 → 创建 → 回执。

### 阶段 1：意图识别

触发（任一）：用户明说"创建 Agent / 帮我做个助手"；描述某领域专业需求而当前 Agent 不具备；问"能不能培养一个…"。确认意图后进入需求收集。

### 阶段 2：需求收集

- 必填（括号内为引导问题示例）：`name`（"起什么名字？"）、`role`（"主要负责什么工作？"）、`target_users`（"谁会使用它？"）、`domain`（"需要哪些专业知识？"）。
- 选填：`style`（沟通风格）、`boundaries`（禁区/红线）、`language`（默认中文）——缺省由领域模板决定。
- 策略：优先从用户自然描述推断，只追问未提及的必填项；追问的数量与节奏由你自主把握。

### 阶段 3：内容生成

按结构化字段组织 persona 与 principles（不要输出 raw markdown，按字段整理后再展示）。未收集到的字段留空，由系统补全默认：

- **persona**：L0 一句话核心身份；L1 `role`（角色定位）/ `personality`（特征标签数组）/ `communication_style`（沟通风格）；L2 专业领域、价值观、决策偏好（free-form）。
- **principles**：L0 一句话最高原则；L1 `must_do` / `must_not`（安全红线）/ `priority`（优先级排序）；L2 治理原则、升级规则（free-form）。

**领域匹配参考**（据 domain 推荐人格与红线）：

| 领域 | 推荐 personality | 默认 must_not |
| --- | --- | --- |
| 法律 / 合同 / 法务 | 专业、严谨、审慎 | 不提供诉讼代理、不替代正式法律意见 |
| 财务 / 会计 / 投资 | 精确、分析性、保守 | 不提供投资建议、不处理真实交易 |
| 代码 / 开发 / 架构 | 逻辑、务实、直接 | 不直接访问生产环境、不存储凭证 |
| 通用 / 其他 | 友好、有帮助 | 通用安全规范 |

### 阶段 4：用户确认

以自然语言/表格向用户展示预览（名称、描述、人格设定、行为原则；**不展示 raw markdown 源码**），例如：

> 即将创建「法律顾问小助手」——专注合同审查与法律风险评估。
> **人格**：数字法律顾问；专业、严谨、审慎；准确用法律术语并给通俗解释。
> **原则**：以用户利益优先、不替代正式法律意见；必做——引用法条 / 标注不确定性 / 建议咨询律师；不做——诉讼代理 / 泄露咨询内容；优先级 用户安全 > 准确性 > 效率。
> 确认创建？（确认 / 修改 / 取消）

用户选"修改"：问改哪个字段 → 重新收集该字段 → 更新预览 → 再次展示并确认。

### 阶段 5：调用 ManageAgent 创建

结构化调用（persona/principles 也接受 markdown 字符串；未提供的字段系统自动补全）：

```
ManageAgent({
  "action": "create",
  "name": "法律顾问小助手",
  "description": "专注于合同审查和法律风险评估的数字智能体",
  "persona": { "L0": "…", "L1": { "role": "…", "personality": ["专业","严谨","审慎"], "communication_style": "…" } },
  "principles": { "L0": "…", "L1": { "must_do": ["…"], "must_not": ["…"], "priority": "用户安全 > 准确性 > 效率" } }
})
```

- 最简创建只需 `{ "action": "create", "name": "我的助手" }`（其余全自动生成）。
- 基础创建 `{ "action": "create", "name": "法律顾问", "description": "专注合同审查" }`——只给 name + description，description 会自动填充 persona 的 L0。
- 可选 `id`（kebab-case slug；`core` / `desirecore` 为核心保留标识不可用，含 name 自动生成命中的情况）、`config`、`smartRouting` 与 `avatarImage`。详细契约见下方；`mcp_servers`、`tool_permissions` 等敏感字段会被拒，需创建后经界面调整。
- 创建后智能体立即在线可用，返回 ID 可直接用于 ManageTeam / Delegate。若工具报错（已存在 / 命中保留标识 / config 非白名单字段等），向用户说明原因并按提示调整后重试。

#### 创建参数说明

**智能路由**：新建 Agent 默认使用 Smart 旗舰量级。需要按职责控制量级时传 `smartRouting`：

```json
{
  "tier": "balanced",
  "requiredCapabilities": ["vision", "tool_use"],
  "reasoning": "high"
}
```

- `tier` 可选 `lightweight`、`balanced`、`flagship`；`reasoning` 可选 `auto`、`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`。
- `tier` 未传时默认 `flagship`；只表达任务量级和能力需求，不绑定具体 Provider 或模型。
- 固定模型、Provider、Smart/fixed 模式由人类模型选择器管理，不能通过 ManageAgent 修改。
- 用户说“最深/最高/拉满”通常对应 `xhigh`；只有用户明确点名 `max` 且模型支持时才使用 `max`。

**配置增量**：`config` 只支持 `llm` 与声明头像 `avatar`。创建时通常无需传；确需调整默认推理行为时可用：

```json
{
  "llm": {
    "reasoning": "high",
    "maxRetryDelayMs": 30000
  },
  "avatar": {
    "char": "法",
    "color": "purple"
  }
}
```

`config.llm` 当前只开放 `reasoning`、`thinkingBudgets`、`maxRetryDelayMs`。不要传 `model`、`provider`、`providerId` 或 `routingMode`。

**图片头像**：使用独立的 `avatarImage`，不要把图片写进 `config`：

```json
{ "source": "dc-media://<mediaId>" }
```

`source` 可以是本轮媒体 ID 或工作目录内的 PNG/JPEG/WebP 文件；不接受 URL 或 base64。服务端会自动裁成 512×512 WebP 并移除 EXIF。头像失败不会回滚已经成功创建的 Agent，需根据工具回执单独重试头像设置。

### 阶段 6：回执

以用户友好方式呈现（不暴露内部路径/技术细节）：告知创建成功，并提示下一步——直接对话、添加技能、调整人格或规则。

### 背景与约束

- AgentFS 结构、排查要点与受保护路径详见 `_agentfs-background.md` 与 `_protected-paths.yaml`。
- 一律经 `ManageAgent` 创建，禁止 curl / HTTP 或直接写 AgentFS 目录；需客户端 ≥ 10.0.90。
