内容
# dotagents
您的AI代理的配置文件。
一个私有的 `~/.agents` Git仓库存储您的技能、MCP服务器、钩子和代理角色。`dotagents`命令行工具将这些内容同步到您使用的每个代码代理的原生格式中 — Claude Code、Codex、Factory Droid、Hermes、OpenCode、Pi — 并像配置文件一样在不同机器之间跟踪您。外部技能在加载到任何代理之前，会被提交固定并审计。
**[概述和比较 →](https://yourconscience.github.io/dotagents/)** · [发布版本](https://github.com/yourconscience/dotagents/releases)
<p align="center"><img src="docs/status-preview.png" alt="dotagents 状态截图，显示技能、MCP服务器、钩子和代理角色已同步到Claude Code、Codex、Hermes和Droid" width="720"></p>
## 为什么使用dotagents
如果您使用多个代码代理，您需要在每个环境中维护相同的四项内容 — 技能、MCP服务器、钩子和子代理角色 — 但格式各不相同。手动复制这些内容很容易出错。Shell配置文件解决了这个问题，使用配置文件管理所有内容。dotagents 将这种模式应用于代理配置。
两个值得注意的设计选择：
- **用户级，非项目级。** 您的设置存储在 `~/.agents` 中，适用于您工作中的所有项目。诸如rulesync和ruler之类的工具生成每个项目的配置；参见[它与众不同之处](#它与众不同之处)。
- **工具和配置是分开的。** 安装dotagents不会安装任何其他人的提示。您的 `~/.agents` 是私有的，由您自己管理。
## 快速开始
在macOS或Linux上安装命令行工具：
```bash
# 预编译的发布二进制文件
curl -fsSL https://raw.githubusercontent.com/yourconscience/dotagents/main/scripts/install.sh | sh
# 或者通过mise安装
mise use -g github:yourconscience/dotagents
# 或者使用Go安装
go install github.com/yourconscience/dotagents/cmd/dotagents@latest
```
然后运行：
```bash
dotagents setup
```
`setup`会执行首次运行所需的所有操作，交互式地：
1. 如果 `~/.agents` 不存在，则创建它，并复制启动内容（两个技能、五个角色、内存钩子、一个最小的 `dotagents.yaml`）。
2. 检测已安装的代理并记录它们的原生路径。
3. 扫描每个代理中您已经拥有的技能、角色和MCP服务器，并提供将它们导入 `~/.agents` 的选项 — 仅复制，原始文件不受影响，名称冲突时会提示您一一处理。
4. 在第一次同步触摸具有内容的代理之前，显示可能会被删除或覆盖的内容，并询问每个代理。拒绝会保留该代理的文件。
5. 提供初始化 `git` 仓库的选项，并运行第一次同步。
要将相同的设置移植到其他机器，请添加一个私有的远程仓库：
```bash
cd ~/.agents
git remote add origin <您的私有仓库地址>
git push -u origin main
# 在下一台机器上：克隆到 ~/.agents，安装 dotagents，运行 dotagents setup
```
在任何时候都可以验证状态：
```bash
dotagents status # 每个代理的同步状态
dotagents doctor # 健康检查：前置信息、锁定固定、审计、钩子
```
## 同步内容
dotagents同步四个部分，每个部分都渲染成代理的原生格式 — dotagents不会创建代理无法使用的兼容性文件：
1. **技能** — `SKILL.md` 目录，符号链接或复制到每个代理的技能根目录。
2. **MCP服务器** — 一个YAML条目，渲染成每个支持的原生配置（JSON、TOML或YAML，根据代理的要求）。
3. **钩子** — 生命周期钩子，仅在代理公开验证的钩子接口时注册。
4. **代理角色** — Markdown角色定义，渲染成原生格式（Claude Markdown、Codex TOML、Droid）。
| 代理 | 技能 | 角色 | MCP | 钩子 |
|---|---|---|---|---|
| Claude Code | 是 | 是 | 是 | 是 |
| Codex | 是 | 是 | 是 | 是 |
| Factory Droid | 是 | 是 | 是 | 是 |
| Hermes | 是 | 否 | 是 | 是 |
| OpenCode | 是† | 是 | 是 | 否 |
| Pi* | 是 | 否* | 否* | 否 |
\* 普通的 [pi](https://github.com/earendil-works/pi) 设计上仅支持技能。如果您使用OMP分支，dotagents会将其检测为单独的分支，并额外管理角色和MCP服务器 — 两个分支永远不会冲突。
† OpenCode原生读取 `~/.agents/skills/`，因此当配置根目录为 `~/.agents` 时，dotagents直接提供技能；自定义配置根目录会将技能镜像到 `~/.config/opencode/skills/`，就像其他代理一样。OpenCode唯一的钩子接口是JS插件API，因此不支持钩子。
Amp和OpenClaw可以通过标准约定读取仓库的技能，但不受管理；只有在验证了原生行为后，表面才会获得上表中的“是”。
## 使用技能
技能是 `~/.agents/skills/` 下的目录，包含带有名称和描述前置信息的 `SKILL.md` 文件（遵循 [agentskills.io](https://agentskills.io) 约定）。创建一个技能，它就会出现在每个已配置的代理中：
```bash
dotagents skill new review-checklist --description "预合并审查清单"
dotagents sync
```
已经在某个代理中编写了技能？将其提升为规范技能，以便所有代理都可以使用：
```bash
dotagents skill promote my-skill # 查找原生技能根目录中的技能，复制到 ~/.agents 下
```
### 外部技能：固定、审计
从他人仓库拉取技能就像安装来自陌生人的提示代码一样 — dotagents将其视为依赖项，而不是下载。 在 `dotagents.yaml` 中声明源：
```yaml
external_skills:
- url: https://github.com/mattpocock/skills
branch: main
skill_dirs: [skills/productivity/grilling]
materialize: true
```
- `dotagents.lock` 将源代码固定到确切的提交；代理只能看到固定的树。
- `materialize: true` 将选定的目录复制到 `~/.agents/skills/<name>`，以便内容在您的仓库中版本化，并在更新时可差异化。
- `dotagents skill update [name ...]` 是唯一可以更新固定点的操作；更新是故意的，而不是隐含的。
- `dotagents doctor` 扫描外部源代码中的风险模式（例如数据提取、shell滥用），并检测锁定和具体化副本之间的差异。
## MCP服务器
声明一次，针对您想要的代理：
```yaml
mcp_servers:
- name: tavily
enabled: true
command: npx
args: [-y, mcp-remote@0.1.38, "https://mcp.tavily.com/mcp"]
agents: [claude-code, codex, hermes, droid]
```
`dotagents mcp list|add|import|remove` 从命令行管理条目；`import` 将您已经在某个代理中配置的服务器拉入规范配置。秘密应作为环境变量引用 — 导入拒绝在命令参数中出现字面秘密。
## 代理角色
角色是 `~/.agents/agents/` 中的Markdown文件，具有前置信息（`name`、`description`、`model`、`effort`、`tools`，以及可选的特定于代理的覆盖）和系统提示作为正文。dotagents将其渲染成每个代理的原生格式 — 例如Codex的TOML。五个通用启动角色随工具一起提供：`architect` `builder` `researcher` `reviewer` `tester`。如果您的 `~/.agents/agents/` 中有同名文件，它将始终优先于启动角色。
## 钩子和内存
钩子是生命周期命令（会话开始/结束、停止），在 `dotagents.yaml` 中按代理注册。dotagents附带一个基于它们的内存集成 — 在设置期间选择一个层级：
```bash
dotagents setup --memory basic # 默认
dotagents setup --memory off
dotagents setup --memory memsearch
```
| 层级 | 行为 | 依赖项 |
|---|---|---|
| `off` | 无托管内存钩子 | 无 |
| `basic` | 将每个会话的有限摘要追加到 `$KNOWLEDGE_DIR/sessions/YYYY-MM-DD.md`，并在会话开始时注入最近的摘要作为上下文 | Python 3 |
| `memsearch` | 知识库的全文本索引搜索 | `memsearch` 在PATH上（`uv tool install memsearch`） |
内存数据存储在您的知识目录中（默认为 `~/Workspace/knowledge`，可通过 `KNOWLEDGE_DIR` 配置），永远不会存储在工具仓库中。
## 命令参考
```bash
dotagents setup [--memory off|basic|memsearch] [--agents ...] # 首次运行、导入、内存层级、首次同步
dotagents status [--agents ...] # 每个代理的同步状态
dotagents sync [--pull] [--agents ...] # 协调所有代理（--pull：先进行git pull）
dotagents doctor [--e2e] [--agents ...] # 健康检查和审计
dotagents skill new|update|promote # 创建、更新固定点、规范化
dotagents mcp list|add|import|remove # 管理MCP条目
```
`dotagents help --all` 列出维护命令和兼容性别名。
## 配置
`~/.agents/dotagents.yaml` 是唯一的真相来源。附带的模板故意很小 — `setup` 会填充检测到的代理：
```yaml
version: 1
agents: [] # 由 dotagents setup 填充
external_skills:
- url: https://github.com/mattpocock/skills
branch: main
skill_dirs: [skills/productivity/grilling]
materialize: true
```
- 配置解析顺序：`--config <path>` → `$DOTAGENTS_HOME/dotagents.yaml` → `~/.agents/dotagents.yaml`。dotagents 永远不会遍历当前项目目录寻找配置。
- `dotagents.local.yaml` 紧邻主配置，覆盖机器本地条目（不进入git）到共享条目上。
- 已管理的条目在原生配置中被标记为已管理；dotagents 未创建的任何内容都保持不变。
## 公共启动内容
<!-- BEGIN GENERATED SKILLS -->
此仓库中附带2个技能：
`dotagents` `grilling`
<!-- END GENERATED SKILLS -->
`dotagents` 是自我管理技能（代理可以为您运行状态/同步/医生）。`grilling` 是来自 [`mattpocock/skills`](https://github.com/mattpocock/skills) 的实时外部技能示例。首次设置会复制启动文件，仅在您没有它们时。
## 故障排除
- **`dotagents doctor`** 是第一步：它验证技能前置信息、角色定义、锁定固定点、具体化副本、钩子注册，并审计外部源代码。
- **从旧配置升级** 以 `pi` 代理为目标，带有MCP：普通Pi没有MCP表面，因此目标被忽略并带有警告 — 如果您使用的是OMP分支，请在 `dotagents.yaml` 中将 `pi` 重命名为 `omp`。
- **同步建议您不期望的删除：** 设置驱动的同步始终会预览每个代理的删除，并默认为保留您的文件；回答 `n` 并使用 `dotagents status` 检查。
## 它与众不同
[rulesync](https://github.com/dyoshikawa/rulesync) 和 [ruler](https://github.com/intellectronica/ruler) 是项目级的：它们在仓库内为每个工具生成配置，并在工具广度上胜出。dotagents 是用户级的：一个私有的配置在项目和机器之间跟踪，并更深入地针对每个代理 — 原生角色渲染、钩子注册和固定审计的外部技能。 [openskills](https://github.com/numman-ali/openskills) 安装技能；dotagents 一起管理四个用户级表面。
## 许可证
[MIT](./LICENSE)
