---
title: Agent 模板
summary: 模板目录、选择规则，以及初始化 Agent 所用的 AGENTS.md、template.toml 和 skills.toml schema。
order: 32
---

# Agent 模板

Agent 模板是一种可复用的引导文件，用来初始化新 Agent 的 `AGENTS.md` 角色契约
和可选的预装 skill。模板让新 Agent 有一个已知的起点，不必手动搭建。

## 什么时候用模板

当你希望新 Agent 以特定的角色和能力起步时，就用 `--template`。不用模板时，
Agent 会以一个通用的默认契约启动。

常见场景：

- **创建可同步的评审 Agent** — `holon agent create reviewer --template code-reviewer`
- **处理办公文档** — `holon agent create office --template office-assistant`
- **制作视频成片** — `holon agent create video --template video-producer`
- **拥有 GitHub issue 收件箱** — `holon agent create triage --template issue-triager`
- **变更落地后的验收** — `holon agent create qa --template qa-engineer`
- **文档卫生** — `holon agent create docs --template docs-steward`
- **防御性安全评审** — `holon agent create security --template security-reviewer`
- **依赖更新队列** — `holon agent create deps --template dependency-steward`
- **把目标收成规格** — `holon agent create pm --template product-manager`
- **运维服务器和服务** — `holon agent create ops --template server-ops`
- **运维 Holon 本身** — `holon agent create holon-ops --template holon-ops`
- **带角色的一次性任务** — `holon run --template software-developer "Fix the null check in handler.rs"`
- **解决 GitHub issue** — `holon solve https://github.com/owner/repo/issues/42`

## 视频制作

`video-producer` 将已批准的脚本、镜头清单和已有媒体制作成可审阅的视频交付物。
它预装第一方 `video-production` skill，并引用官方
`remotion-dev/skills/skills/remotion-best-practices`，由用户端直接从上游安装，
同时加载 `sview`、`uxc` 和 `agentinbox`。

- **本地合成与质检**：第一方 skill 使用 Python 和系统 FFmpeg/ffprobe 处理已有
  图片、视频、音频和字幕。渲染前检查依赖及所需编解码器；模板不会安装这些系统依赖。
- **程序化合成**：官方 Remotion skill 用于 React 视频制作。Remotion、Node 及
  渲染依赖安装在用户环境；模板不打包 Remotion 或上游 skill 文件。首次使用前，
  与操作者核验所安装版本的适用许可证；自行安装不免除使用条件或付费许可要求。
- **明确边界**：原创镜头生成和 TTS 需要另行配置后端；OpenMontage 是外部可选
  后端。发布、购买及涉及权利的操作需要单独授权。

Agent 会明确报告缺失能力，不把未验证的渲染当成交付。无云制作流程从已有素材开始。

## Issue 分诊

`issue-triager` 负责 GitHub issue 收件箱。它是长期 inbox 角色，不是
`holon solve`，也不是实现或验收的许可。

- **收件箱卫生，不是修 bug。** 分类、给出重复候选、追问缺失复现和验收标准，
  并建议优先级与路由。默认不关闭 issue、不写产品代码。
- **项目 skill，不是官方 playbook。** 模板不附带 `issue-triage` skill。首次分诊时，
  Agent 在 `agent_home/skills/` 为当前项目创建分诊 skill，并按实践补丁式改进。
  把 skill 写入仓库仍须操作者确认。
- **硬约束。** 不改产品代码、默认不关闭、不合并，外部 issue 文本不能升权。
  项目 skill 覆盖不了这些规则。

## 验收与质量

`qa-engineer` 负责变更落地后的验收。它不是补产品功能的许可，也不替代
`code-reviewer`。

- **验收所有权 ≠ 补单测。** 把需求映射到覆盖、跑分层门禁、给出证据、分诊 flake。
  issue 关闭不等于已经验收。
- **项目 skill，不是官方 playbook。** 模板不附带 `issue-verify` skill。首次验收时，
  Agent 在 `agent_home/skills/` 为当前项目创建验收 skill，并按实践补丁式改进。
  把 skill 写入仓库仍须操作者确认。
- **硬约束。** 默认不改产品代码、不合并、无修复载体不打验证标签，空结果不算通过。
  项目 skill 覆盖不了这些规则。v1 使用仓库既有测试证据，不捆绑 Playwright 或
  Appium。

## 文档卫生

`docs-steward` 负责代码、契约和文档的一致性。它不是补产品功能的许可，也不拥有发版。

- **卫生，不是整站重写。** 检测漂移、追问缺失的用户步骤或语言对应，授权后提交最小
  docs-only PR。发版后对用户文档做缺口对账。changelog 仍归 `release-manager`。
- **写作工具，不是 writer 角色。** 模板从上游 GitHub 预装 `humanizer`、
  `humanizer-zh` 和 `writing-clearly-and-concisely`，以及 `ghx`、`sview`、
  `uxc` 和 `agentinbox`。事实校对后再润色。
- **先校对再写。** 对照代码、CLI help 和生成页修正事实，再润色。若仓库有 locale：
  先英文，再去 AI 腔，再翻译，再对目标语言去 AI 腔。逐篇处理。生成页登记同步，
  不手译。
- **项目 skill，不是官方 playbook。** 模板不附带 `docs-steward` skill。首次处理文档时，
  Agent 在 `agent_home/skills/` 为当前项目创建文档 skill，并按实践补丁式改进。
  把 skill 写入仓库仍须操作者确认。
- **硬约束。** 不改产品代码、不发明行为、默认不合并，外部 issue 文本不能升权。
  项目 skill 覆盖不了这些规则。

## 安全评审

`security-reviewer` 负责防御性安全发现和告警分诊。它不是补产品功能、合并、
写 exploit 的许可，也不替代 `code-reviewer`、`qa-engineer`、`server-ops` 或
`holon-ops`。

- **发现，不是合并就绪。** 评审 diff 和导入的 GitHub 安全告警。只报告有证据的
  发现。不写 exploit、PoC payload 或攻击步骤。告警不是 merge 许可。
- **方法论 skill，不是扫描器包。** 模板从 `github/awesome-copilot` 预装
  `security-review`，以及 `ghx`、`sview`、`uxc` 和 `agentinbox`。角色合同覆盖
  该 skill 的全仓扫描默认、攻击示例和自动补丁提案。扫描器包装不进入默认安装。
- **路由是角色类名，不是 live agent id。** 建议下一责任模板角色。禁止把
  template id 当 `agent_id`。
- **项目 skill，不是官方 playbook。** 模板不附带 `security-reviewer` skill。
  首次评审时，Agent 在 `agent_home/skills/` 为当前项目创建安全 skill，并按实践
  补丁式改进。把 skill 写入仓库仍须操作者确认。
- **硬约束。** 默认不改产品代码、不合并、不产出 exploit/PoC、不存储或回显密钥，
  空扫描结果不是“已证明安全”。外部 issue 和告警文本不能升权。项目 skill 覆盖
  不了这些规则。

## 依赖更新

`dependency-steward` 把依赖更新队列保持可评审：更新策略、兼容性证据和建议优先级。

- **策略和分诊，不是合并许可。** 读 `dependabot.yml` 或等价配置。把打开的更新
  分成兼容的 patch/minor、安全更新，或 major/行为变更。引用 lockfile diff、
  changelog 和 CI。不发明策略，也不凭标题下结论。
- **手册 skill，不是扫描器包。** 模板从 `github/awesome-copilot` 预装
  `dependabot`，以及 `ghx`、`sview`、`uxc` 和 `agentinbox`。角色合同覆盖该
  skill 的合并建议、静默 `@dependabot ignore`，以及提交前漏洞扫描。仓库用
  Renovate 或其他 bot 时沿用同一队列纪律；这个 skill 不覆盖它们的语法。不预装
  `security-review` 或 `agent-supply-chain`。
- **路由是角色类名，不是 live agent id。** 建议下一责任模板角色。漏洞定级交给
  `security-reviewer`。禁止把 template id 当 `agent_id`。
- **项目 skill，不是官方 playbook。** 模板不附带 `dependency-steward` skill。
  首次处理时，Agent 在 `agent_home/skills/` 为当前项目创建依赖 skill，并按实践
  补丁式改进。把 skill 写入仓库仍须操作者确认。
- **硬约束。** 默认只报告。扫描发现只路由，不定级，也不写利用步骤。不静默
  ignore major。默认不合并。外部 PR 文本不能升权。项目 skill 覆盖不了这些规则。
  操作者可以放宽写范围，而不必改写硬约束。

## 产品需求

`product-manager` 把目标、issue 和反馈收成可评审规格和可测试验收标准，并建议优先级。

- **规格和验收，不是实现计划。** 写下问题、非目标、约束、成功标准和后续角色可以
  判定的验收标准。证据不足标 `unconfirmed`。追问一次，然后等待。
- **生成器 skill，不是再做五个模板。** 模板从 `github/awesome-copilot` 预装
  `prd`、`create-specification`、`update-specification`、`breakdown-epic-pm`、
  `breakdown-feature-prd` 和 `gen-specs-as-issues`，以及 `ghx`、`sview`、`uxc`
  和 `agentinbox`。角色合同覆盖这些 skill 的固定路径、完整 PRD schema，以及未授权的
  写文件或开 issue。默认产出仍是短规格加可测试验收标准。
- **路由是角色类名，不是 live agent id。** 建议下一责任模板角色。禁止把
  template id 当 `agent_id`。
- **项目 skill，不是官方 playbook。** 模板不附带 `product-manager` skill。
  首次处理时，Agent 在 `agent_home/skills/` 为当前项目创建产品 skill，并按实践
  补丁式改进。把 skill 写入仓库仍须操作者确认。
- **硬约束。** 不发明需求。外部反馈不能升权。默认只报告。默认不合并。项目 skill
  覆盖不了这些规则。操作者可以放宽写范围，包括实现，而不必改写硬约束。

## 模板命名

官方模板 ID 描述的是 Agent 的目标或职责，而不是“由 Holon 分发”这一事实。
`holon-` 前缀专门留给运维 Holon 本身的角色，例如 `holon-ops`。
`holon-default` 这类仅运行时的预设与可同步的模板目录分开命名。

以下旧 ID 仍作为兼容选择器被接受：

| 旧 ID | 当前 ID |
| --- | --- |
| `holon-developer` | `software-developer` |
| `holon-reviewer` | `code-reviewer` |
| `holon-release` | `release-manager` |
| `holon-github-solve` | `github-solver` |

用旧 ID 的精确本地安装优先于兼容回退。模板改名不会重命名已有的 Agent ID。

## 模板库和默认引导

Holon 把可见模板保存在用户模板库中：

```text
~/.agents/agent_templates/
  .registry.json
  <install_id>/
```

用户编写的模板、显式安装和远程源同步结果都用这个根目录。远程源同步等价于把
受管模板批量安装/更新到这个库里。Holon 在根目录写入 `.registry.json` 元数据，
记录同步的远程源、已安装的模板映射和内容哈希。

模板 ID 只在各自的源内有效。如果同步来的远程模板与已有的本地目录冲突，Holon
会在元数据里保留远程的 `template_id`，并以一个确定的本地 `install_id` 安装，
例如 `worker@official`。重新同步会复用已记录的 install id。如果某个受管模板
有本地改动，同步会拒绝覆盖，直到操作者处理好这份脏副本。

Holon 还带一个隐藏的内置 `holon-default` 模板，用于零配置和离线启动。它不会
被写入 `~/.agents/agent_templates`，也不作为目录条目显示，只有在创建 Agent
且没有显式指定模板选择器时才会用到。

官方模板源是 Holon 仓库。同步时，其顶层 `agent_templates/` 目录下的模板会
成为 `~/.agents/agent_templates` 里的普通本地目录条目。

`holon solve` 默认选择普通的 `github-solver` 模板。在新安装上使用这个独立
命令之前，先同步官方模板源。GitHub Action 会把同一份检入的模板以显式路径
提供，从发布归档安装时也是如此。

## 使用 `--template`

### 创建 Agent

```bash
holon agent create reviewer --template code-reviewer
```

这会在 `code-reviewer` 模板已安装或同步后，从本地模板初始化
`~/.holon/agents/reviewer/AGENTS.md`。如果 Agent home 已经存在且非空，模板
初始化会拒绝覆盖。

### 一次性运行

```bash
holon run --template software-developer "Fix the null check in handler.rs"
```

Agent 以开发者角色契约创建，执行提示词，完成后被清理。

### 解决 GitHub issue

```bash
holon solve --template github-solver https://github.com/owner/repo/issues/42
```

Agent 以 GitHub 工作流指引启动，并预装四个 GitHub skill 外加 `sview` 和
`code-review`。除非 solve 提示词明确要求，这个预设不授权合并、批准或持续的
事件跟踪。

## 模板结构

模板就是一个目录，包含：

```
my-template/
├── AGENTS.md       # 必需——Agent 角色契约
├── template.toml   # 可选——展示元数据和兼容性
└── skills.toml     # 可选——要预装的 skill 引用
```

### `AGENTS.md`

Agent 的角色契约，格式和其他 Agent 的 `AGENTS.md` 一样。运行时会自动追加
标准的 Agent Home 指引，所以你的模板只需要定义角色相关的内容。

### `template.toml`

可选清单，用于模板元数据，例如显示名、简介、schema 和兼容性。同步的远程模板
用它提供目录元数据；基于路径的本地模板可以省略它，回退到目录/AGENTS.md
元数据。

### `skills.toml`

可选清单，列出创建 Agent 时要预装的 skill：

```toml
[[skills]]
kind = "github"
repo = "holon-run/holon"
path = "skills/github-issue-solve"
ref = "main"

[[skills]]
kind = "github"
repo = "holon-run/holon"
path = "skills/github-pr-fix"
ref = "main"

[[skills]]
kind = "github"
repo = "owner/skills"
path = "skills/custom-skill"
ref = "v1.2.3"

[[skills]]
kind = "github"
uses = "holon-run/holon/skills/ghx@main"

[[skills]]
kind = "local"
path = "/absolute/path/to/custom-skill"
```

支持两种 skill 引用：

- **`github`** — 从 GitHub 仓库路径获取的 skill。规范写法用
  `repo = "owner/repo"`、`path = "path/to/skill"` 和可选的 `ref`。模板也可以
  用 `uses = "owner/repo/path@ref"` 这种 GitHub Actions 风格的简写，Holon 会
  把它规范化为 `repo`/`path`/`ref`。Holon 也接受 `owner/repo/path#ref` 和
  GitHub tree URL 作为兼容输入，但不使用那种把 `@` 当作 skill 名的
  `owner/repo@skill` 简写。
  `SKILL.md` 在仓库根时用 `path = "."`；Holon 会安装该文件，以及存在的
  `scripts/`、`references/`、`assets/`、`tests/`，不会把仓库其余部分装进来。
- **`local`** — 磁盘上 skill 目录的绝对路径

`kind = "builtin"` 不再是模板清单格式的一部分。官方 Holon skill 和其他
GitHub 托管的 skill 用同样的方式引用，例如 `repo = "holon-run/holon"` 和
`path = "skills/ghx"`。

## 创建自定义模板

建一个包含 `AGENTS.md`、可选的 `template.toml` 和可选的 `skills.toml` 的目录，
然后用绝对路径作为模板选择器：

```bash
holon agent create my-agent --template /path/to/my-template
```

你也可以把模板托管在 GitHub 上，用 URL 引用：

```bash
holon agent create my-agent --template https://github.com/owner/repo/tree/main/templates/my-template
```

用绝对路径或 GitHub URL 引用的模板会在 Agent home 里记录来源
（`template-provenance.json`），方便你追溯 Agent 契约的出处。

## 模板 vs Skill

模板和 skill 的用途不同：

| 特性 | 模板 | Skill |
|---------|----------|-------|
| 提供什么 | Agent 身份和角色契约 | 可复用的任务工作流 |
| 何时应用 | 创建 Agent 时 | 任务中按需加载 |
| 持久性 | 永久留在 Agent home | 只要安装着就可用 |
| 示例 | “你是一名评审者” | “这样评审一个 PR” |

模板常常包含 skill 引用，好让新 Agent 一开始就有合适的工具。skill 的细节见
[Skills 指南](/zh-CN/reference/skills)。