# @routerhub/agent-rules 中文说明

`@routerhub/agent-rules` 用来把通用规则和项目私有规则合并成项目中可直接使用的规则文件。

它主要提供两类能力：

1. 生成项目可用的 `AGENTS.md` 和 `.github/copilot-instructions.md`
2. 监听 `AGENTS.private.md` 变更并自动同步

## 安装

在目标项目中安装：

```bash
pnpm add -D concurrently @routerhub/agent-rules
```

## 初始化

如果项目里还没有 `AGENTS.private.md`，可以执行：

```bash
pnpm exec agent-rules init
```

执行后会在项目根目录生成一份可编辑的私有规则模板。

## 同步规则

将基础规则与项目私有规则合并为 `AGENTS.md` 和 `.github/copilot-instructions.md`：

```bash
pnpm exec agent-rules sync
```

适合以下场景：

- 首次接入后生成规则文件
- 修改了 `AGENTS.private.md` 后手动重建
- CI 或脚本中显式同步规则

## 监听模式

开发时建议通过监听模式自动保持规则文件最新：

```json
{
  "scripts": {
    "dev": "concurrently \"next dev\" \"agent-rules watch\""
  }
}
```

监听模式会：

- 先执行一次同步，生成最新的 `AGENTS.md` 和 `.github/copilot-instructions.md`
- 持续监听项目根目录下的 `AGENTS.private.md`
- 在文件变更后自动重新同步

## 规则来源

- `AGENTS.base.md`：规则包内置的通用基础规则
- `AGENTS.private.md`：项目自己的私有规则
- `AGENTS.md`：最终合并结果，供项目中的 Agent 使用
- `.github/copilot-instructions.md`：最终合并结果，供 GitHub Copilot 强制规则使用

## 推荐用法

项目接入时推荐保持以下流程：

1. 安装 `@routerhub/agent-rules`
2. 执行 `pnpm exec agent-rules init`
3. 根据项目情况编辑 `AGENTS.private.md`
4. 使用 `pnpm exec agent-rules sync` 或 `agent-rules watch` 生成最终的 `AGENTS.md`

## 更新

当 `@routerhub/agent-rules` 有新版本时，锁文件不会自动追最新，需要手动更新：

```bash
pnpm update @routerhub/agent-rules --latest
```

更新后 `postinstall` 脚本会自动运行，重新同步规则文件。

> 直接 `pnpm i` 会按 `pnpm-lock.yaml` 中的锁定版本安装，必须加 `--latest` 才能拿到最新版本。

## 注意事项

- 私有规则应只写项目特有的限制、接口地址、组件路径和业务规范
- 通用规范应维护在规则包的 `AGENTS.base.md` 中
- 若私有规则与基础规则冲突，以项目私有规则为准