236 lines
5.9 KiB
Markdown
236 lines
5.9 KiB
Markdown
#hermes #agent #Configuration
|
||
|
||
> 记录时间：2026-04-27
|
||
> 场景：Vibe Coding 多角色 Agent 配置
|
||
|
||
---
|
||
|
||
## 一、给 Agent 设置预设角色和项目背景
|
||
|
||
### 问题
|
||
|
||
每次对话都要在提示词里重复角色定义和项目背景，效率低。
|
||
|
||
### 解决方案：两个配置文件分工
|
||
|
||
#### `SOUL.md` — 角色人设（全局生效，跟着 Agent 走）
|
||
|
||
**路径：** `~/.hermes/SOUL.md`（默认 profile）或 `~/.hermes/profiles/<名字>/SOUL.md`
|
||
|
||
适合放：
|
||
|
||
- 角色定位、身份定义
|
||
- 思维方式、技术偏好
|
||
- 沟通风格、语言习惯
|
||
|
||
```markdown
|
||
# 角色
|
||
|
||
你是一位资深软件架构师，有 10 年以上分布式系统设计经验。
|
||
|
||
## 核心职责
|
||
在任何 coding 任务开始前，先：
|
||
1. 分析需求，识别潜在的设计问题
|
||
2. 提出 2-3 种技术方案并给出 Trade-off 分析
|
||
3. 明确模块边界和接口设计
|
||
|
||
## 沟通风格
|
||
- 直接说结论，再给理由
|
||
- 用中文回复
|
||
```
|
||
|
||
#### `AGENTS.md` — 项目背景（项目级生效，放在项目根目录）
|
||
|
||
**路径：** `~/your-project/AGENTS.md`
|
||
|
||
适合放：
|
||
|
||
- 技术栈、架构说明
|
||
- 开发约定、命名规范
|
||
- 当前阶段、注意事项
|
||
|
||
```markdown
|
||
# 项目背景
|
||
|
||
## 技术架构
|
||
- Frontend: Next.js 14 (App Router) + Tailwind
|
||
- Backend: Python FastAPI，部署在 Docker
|
||
- 数据库: PostgreSQL，ORM 用 SQLAlchemy
|
||
|
||
## 开发约定
|
||
- API 统一返回 `{data, error, meta}` 结构
|
||
- 不直接修改 migration 文件，用 Alembic 命令
|
||
```
|
||
|
||
#### 优先级总结
|
||
|
||
|内容类型|放哪里|
|
||
|---|---|
|
||
|角色人格、沟通风格|`SOUL.md`|
|
||
|项目架构、技术栈、约定|`AGENTS.md`（项目根目录）|
|
||
|临时切换风格|`/personality teacher` （会话级）|
|
||
|
||
---
|
||
|
||
## 二、创建多个独立 Agent（Profiles）
|
||
|
||
### 问题
|
||
|
||
想用不同角色做 vibe coding，默认只有一个 Agent。
|
||
|
||
### 解决方案：使用 `hermes profile` 创建隔离实例
|
||
|
||
每个 Profile 拥有独立的：SOUL.md、配置、记忆、会话历史、技能。
|
||
|
||
#### 创建 Profile
|
||
|
||
```bash
|
||
# 克隆当前配置（推荐，省去重新配置模型和 API key）
|
||
hermes profile create nova --clone
|
||
hermes profile create werner --clone
|
||
|
||
# 给每个 profile 写专属的 SOUL.md
|
||
vim ~/.hermes/profiles/nova/SOUL.md
|
||
vim ~/.hermes/profiles/werner/SOUL.md
|
||
```
|
||
|
||
#### 启动方式
|
||
|
||
```bash
|
||
nova # 直接用 alias 启动（Hermes 自动创建）
|
||
werner # 同上
|
||
|
||
hermes -p nova chat # 临时使用某个 profile，不切换默认
|
||
```
|
||
|
||
#### 常用管理命令
|
||
|
||
```bash
|
||
hermes profile list # 查看所有 profiles
|
||
hermes profile show nova # 查看某个 profile 详情
|
||
hermes profile rename nova pm # 重命名
|
||
hermes profile delete nova # 删除（含所有记忆和会话，不可恢复）
|
||
hermes profile export nova # 备份
|
||
hermes -p nova doctor # 诊断某个 profile
|
||
```
|
||
|
||
#### 角色命名参考
|
||
|
||
|角色|推荐名字|来源|
|
||
|---|---|---|
|
||
|产品经理|`marty`|Marty Cagan，《Inspired》作者|
|
||
|架构师|`werner`|Werner Vogels，Amazon CTO|
|
||
|产品经理（备选）|`nova`|前瞻、探索感|
|
||
|架构师（备选）|`atlas`|扛起系统架构|
|
||
|
||
---
|
||
|
||
## 三、Telegram Bot 配置后无响应
|
||
|
||
### 问题
|
||
|
||
给新 Profile 配了 Telegram bot token，在 Telegram 上发消息没有任何反应。
|
||
|
||
### 排查顺序
|
||
|
||
**1. Gateway 没有启动（最常见）**
|
||
|
||
配置 token ≠ gateway 在运行，新 profile 需要单独启动。
|
||
|
||
```bash
|
||
hermes -p nova gateway status # 检查状态
|
||
hermes -p nova gateway start # 启动
|
||
hermes -p nova gateway # 前台运行，实时看日志
|
||
hermes -p nova gateway install # gateway service 没有安装的前提下
|
||
```
|
||
|
||
**2. Token 没配在正确的 Profile 下**
|
||
|
||
每个 profile 有独立的 `.env`，默认 profile 的 token 不会共享。
|
||
|
||
```bash
|
||
cat ~/.hermes/profiles/nova/.env | grep TELEGRAM
|
||
# 应看到：TELEGRAM_BOT_TOKEN=xxx
|
||
```
|
||
|
||
**3. 用户 ID 不在白名单**
|
||
|
||
Hermes 默认拒绝所有未授权用户的消息（安全默认值）。
|
||
|
||
```bash
|
||
# 在 .env 里加上自己的 Telegram User ID
|
||
TELEGRAM_ALLOWED_USERS=你的TelegramUserID
|
||
```
|
||
|
||
> 不知道自己 ID？在 Telegram 搜索 `@userinfobot` 发消息获取。
|
||
|
||
**4. 同一个 token 被两个 gateway 同时使用**
|
||
|
||
会导致两个 gateway 互相冲突，都无法正常收消息。每个 Profile 必须使用独立的 Telegram Bot（在 BotFather 分别创建）。
|
||
|
||
---
|
||
|
||
## 四、Gateway 连接 Telegram 超时（国内网络）
|
||
|
||
### 问题
|
||
|
||
Gateway 服务正常运行，但日志反复出现：
|
||
|
||
```
|
||
WARNING: Primary api.telegram.org connection failed
|
||
WARNING: Fallback IP 149.154.167.220 failed
|
||
Connect attempt N/8 failed: Timed out
|
||
```
|
||
|
||
### 原因
|
||
|
||
Telegram 在国内被封，gateway 无法直连。
|
||
|
||
### 解决方案：配置代理
|
||
|
||
编辑对应 profile 的 `.env`：
|
||
|
||
```bash
|
||
vim ~/.hermes/profiles/nova/.env
|
||
```
|
||
|
||
添加代理配置（端口换成本地代理实际端口）：
|
||
|
||
```bash
|
||
# HTTP 代理（Clash 默认 7890）
|
||
HTTPS_PROXY=http://127.0.0.1:7890
|
||
HTTP_PROXY=http://127.0.0.1:7890
|
||
|
||
# SOCKS5 代理（v2rayN 默认 10809）
|
||
HTTPS_PROXY=socks5://127.0.0.1:7890
|
||
HTTP_PROXY=socks5://127.0.0.1:7890
|
||
```
|
||
|
||
重启 gateway：
|
||
|
||
```bash
|
||
hermes -p nova gateway stop
|
||
hermes -p nova gateway start
|
||
hermes -p nova logs --tail # 观察是否连接成功
|
||
```
|
||
|
||
> **注意：** 每个 profile 的 `.env` 需要单独配置，互不共享。
|
||
|
||
---
|
||
|
||
## 快速参考：文件路径总览
|
||
|
||
```
|
||
~/.hermes/
|
||
├── SOUL.md # 默认 profile 的角色人设
|
||
├── profiles/
|
||
│ ├── nova/
|
||
│ │ ├── SOUL.md # nova 的角色人设（产品经理）
|
||
│ │ └── .env # nova 的 token、代理、白名单配置
|
||
│ └── werner/
|
||
│ ├── SOUL.md # werner 的角色人设（架构师）
|
||
│ └── .env # werner 的配置
|
||
|
||
~/your-project/
|
||
└── AGENTS.md # 项目背景（每个项目独立维护）
|
||
``` |