1.1 Hermes 完整安装与验证

Step 1：系统要求

• Linux / macOS / WSL2（Windows 用户必须安装 WSL2）
• 推荐内存 ≥8GB，磁盘空间 ≥5GB
• 已安装 Git、curl、Node.js 18+（Hermes 依赖）

Step 2：执行安装脚本

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安装后重启终端，或执行 source ~/.bashrc（或 ~/.zshrc）。

Step 3：验证安装

hermes --version

正常输出版本号即成功。

Step 4：快速初始化（推荐最小配置）

hermes setup --quick

该命令会交互式询问：

• 默认模型 Provider（选 kimi-coding）
• API Key（粘贴你的 sk-kimi-xxx）
• 默认工具集（建议全选：filesystem, shell, web）

Step 5：运行健康检查

hermes doctor

检查结果应全部为 ✅，如有 ❌ 则按提示修复。

---

1.2 Kimi K2.6 API 配置详解

获取 API Key

• 访问 Kimi 开放平台
• 注册/登录 → 控制台 → API Key 管理 → 创建新 Key
• 记录 Key（格式：sk-kimi-xxxxxxxxxxxxxx）

在 Hermes 中配置模型

hermes model add kimi-coding \
  --api-key sk-kimi-xxxxx \
  --base-url https://api.kimi.com/coding/v1 \
  --model moonshot-v1-8k  # 或 moonshot-v1-32k / moonshot-v1-128k

注意：Kimi K2.6 编码专用模型在 API 中可能名为 moonshot-v1-128k 或 kimi-coding，请以官方文档为准。

测试模型连通性

hermes -p default chat --message "你好，请输出 JSON 格式的自我介绍"

若正常返回 JSON 结构，说明配置成功。

---

1.3 多 Agent Profile 的完整生命周期管理

创建专用 Agent

# 创建 planner Agent
hermes profile create planner --clone-from default

# 创建 coder Agent
hermes profile create coder --clone-from default

# 创建 reviewer Agent
hermes profile create reviewer --clone-from default

为每个 Agent 编写 SOUL.md

# 编辑 planner 的人设
hermes -p planner config edit soul

在打开的编辑器中粘贴以下内容（示例）：

planner 的 SOUL.md

# 角色
你是一个资深技术架构师，职责是将用户的复杂需求拆解成可执行的子任务。

# 工作方式
1. 先理解用户目标的最终产物（代码、文档、配置等）
2. 拆解为 3-7 个独立子任务，每个子任务有明确的输入、输出、验收标准
3. 指定子任务之间的依赖关系和执行顺序
4. 输出格式必须为 JSON，包含 tasks 数组，每个 task 有 id, name, description, input_files, output_files, depends_on

# 约束
- 不直接编写代码
- 不执行任何系统命令
- 每个子任务的复杂度控制在 20 行代码以内

# 交付物
最终的 JSON 计划文件保存为 `plan.json`

coder 的 SOUL.md

# 角色
你是一个专注执行的编码工程师，根据 planner 输出的 plan.json 逐个实现代码。

# 工作方式
1. 读取 plan.json，按顺序执行每个 task
2. 每个 task 完成后，更新 `progress.md` 标记完成
3. 遇到错误立即停止，并在 `error.log` 中记录

# 约束
- 只修改与当前 task 相关的文件
- 不擅自增加额外功能
- 代码必须包含注释

# 交付物
完整的代码文件 + progress.md

reviewer 的 SOUL.md

# 角色
你是一个代码审查专家，负责验收 coder 的输出。

# 工作方式
1. 检查所有预期文件是否存在
2. 运行测试用例（如果有）
3. 检查代码风格、注释、错误处理
4. 输出验收报告 `review.md`，包含 PASS/FAIL 状态和改进建议

# 约束
- 不修改代码，只评估
- 必须明确指出问题所在行号

---

1.4 多 Agent 协作实战命令

启动一个完整的开发流水线

假设用户需求：“用 HTML/CSS/JS 生成一个带深色模式的个人卡片，包含头像、姓名、简介、社交链接。”

# 1. 让 planner 拆解任务
hermes -p planner chat --checkpoints --max-turns 30
> 请将"生成个人卡片"拆解为子任务，输出 plan.json

# planner 输出 plan.json（示例内容）：
# [
#   {"id":1, "name":"创建HTML结构", "output":"index.html"},
#   {"id":2, "name":"编写CSS样式（含深色模式）", "output":"style.css"},
#   {"id":3, "name":"添加JS交互（切换主题）", "output":"script.js"},
#   {"id":4, "name":"生成测试截图", "output":"screenshot.png"}
# ]

# 2. 切换到 coder 执行
hermes -p coder chat --max-turns 100
> 请根据 plan.json 实现所有任务

# 3. 切换到 reviewer 验收
hermes -p reviewer chat
> 请验收当前目录下的所有输出文件，生成 review.md

---

1.5 高级技巧：跨 Agent 调度与总控 Agent

让一个 Agent 启动另一个 Agent

在 SOUL.md 中允许 Agent 使用 hermes -p 命令调用其他 Agent。例如，总控 Agent 可以这样写：

# 角色
你是总调度官。当用户提出需求时，你先用自己的能力判断是否需要拆解。
如果需要拆解，你执行 `hermes -p planner chat --message "请拆解：{用户需求}"` 获取 plan.json。
然后你执行 `hermes -p coder chat --message "请实现 plan.json"`。
最后执行 `hermes -p reviewer chat --message "请验收"`。
你汇总结果返回给用户。

实际调用命令（在总控 Agent 对话中）：

> 用户：帮我做一个待办事项网页

总控 Agent 内部会自动执行：
hermes -p planner chat --message "请拆解待办事项网页"
hermes -p coder chat --message "请实现 plan.json"
hermes -p reviewer chat --message "请验收"

---

1.6 常见问题与解决方案

问题	可能原因	解决方法
hermes: command not found	安装脚本未加入 PATH	执行 export PATH="$HOME/.hermes/bin:$PATH" 并写入 shell 配置
Kimi API 返回 401	API Key 无效或过期	重新生成 Key，执行 hermes model update kimi-coding --api-key 新key
Agent 执行到一半卡住	--max-turns 设置过小或模型陷入循环	增大 --max-turns（如 200），或按 Ctrl+C 中断后输入“继续”
多个 Agent 互相覆盖文件	没有使用独立工作目录	每个 Agent 启动前 cd 到不同目录，或在 SOUL.md 中约束文件路径
记忆丢失，Agent 忘记之前的对话	Hermes 默认记忆字符数太小	执行 hermes config set memory.memory_char_limit 8000
想删除一个 Agent Profile	不再需要	hermes profile delete planner

---

1.7 推荐工作目录结构

~/my_ai_workspace/
├── project_a/
│   ├── plan.json
│   ├── progress.md
│   ├── review.md
│   └── src/
├── project_b/
└── .hermes/
    └── profiles/
        ├── planner/
        │   └── SOUL.md
        ├── coder/
        │   └── SOUL.md
        └── reviewer/
            └── SOUL.md

建议不同项目使用不同目录，并在每个项目中启动 Agent，避免文件混淆。

---

1.8 性能优化建议

1. 模型选择：Kimi K2.6 编码任务性价比最高；若需纯文本推理，可选用 DeepSeek-V3 或 GPT-4o-mini。
2. 并行执行：如果子任务之间无依赖，可以同时启动多个 coder Agent（不同目录），最后合并结果。
3. 缓存计划：对相似需求，可以复用之前的 plan.json，只需修改部分参数。
4. 定期清理记忆：长期运行的 Agent 记忆会膨胀，使用 hermes -p <name> memory clear 定期重置。