# config.yaml — Kanban 設定範例
kanban:
  enabled: true
  multi_project: true
  max_retries: 3
  heartbeat_interval: 30  # 秒
  zombie_timeout: 300     # 秒
  hallucination_gate: true

# 使用 /goal 設定持久目標
> /goal 重構所有 API endpoints 為 RESTful 風格，並撰寫完整測試

# Agent 會持續追蹤進度，跨回合記錄
# 即使中途切換話題，/goal 會在每次對話開始時提醒目標進度

# 啟動 hermes proxy
hermes proxy --port 4141

# 其他工具指向本地 proxy
export OPENAI_API_BASE=http://localhost:4141/v1
aider --model grok-4.3  # 使用 Hermes 的 xAI 授權

pip install hermes-agent
# 或使用 uv
uv tool install hermes-agent

# 將當前 session 轉移到新 Profile
> /handoff team-ops
# 或轉移到不同模型
> /handoff --model gpt-5.5

# config.yaml — Bitwarden Secrets Manager 設定
secrets:
  backend: bitwarden
  bitwarden:
    machine_account_token: ${BWS_ACCESS_TOKEN}

# 語法範例
delegate_task(
    task="分析所有 PR 的安全風險",
    background=True  # 背景執行，完成後結果自動回注對話
)

# 範例：每日早上 9 點檢查安全漏洞
name: daily-security-scan
schedule: "每天早上 9 點"
task: "掃描所有專案的已知漏洞，彙整報告到 Slack #security 頻道"
profile: security-ops

{
  "operations": [
    {"action": "add", "key": "user_preference_theme", "value": "dark"},
    {"action": "replace", "key": "project_status", "value": "phase-2"},
    {"action": "remove", "key": "deprecated_config"}
  ]
}

使用者：幫我分析這個 Spring Boot 專案的安全漏洞

Agent 執行過程：
1. 讀取 pom.xml（了解依賴）
2. 搜尋已知 CVE
3. 掃描程式碼（SQL Injection / XSS 等）
4. 生成報告

Agent 自動回顧：
→ 這個任務涉及多步驟安全分析
→ 封裝為 Skill: "spring-security-audit"
→ 下次呼叫 /spring-security-audit 即可直接使用

~/.hermes/skills/
├── bundled/                    # 官方內建技能
│   ├── claude-code/
│   │   └── skill.md
│   ├── popular-web-designs/
│   │   └── skill.md
│   ├── gitnexus-explorer/
│   │   └── skill.md
│   ├── humanizer/              # v0.12.0: 去除 AI 文風
│   │   └── skill.md
│   └── spotify/                # v0.12.0: Spotify 整合技能
│       └── skill.md
├── user/                       # 使用者自建技能
│   ├── spring-security-audit/
│   │   └── skill.md
│   └── bank-api-generator/
│       └── skill.md
└── community/                  # 社群下載技能
    └── research-paper-writing/
        └── skill.md

# spring-security-audit

## Description
掃描 Spring Boot 專案的常見安全漏洞，包括依賴 CVE、程式碼注入風險、認證配置問題。

## Steps
1. 讀取 pom.xml 或 build.gradle，列出所有依賴版本
2. 使用 web_search 查詢各依賴的已知 CVE
3. 掃描 src/ 目錄中的以下模式：
   - SQL String Concatenation（SQL Injection 風險）
   - @CrossOrigin 無限制（CORS 風險）
   - 硬編碼密碼或 API Key
4. 檢查 Spring Security 配置（SecurityFilterChain）
5. 生成安全報告（表格格式 + 嚴重度 + 修復建議）

## Config
- scan_depth: 3  # 掃描目錄深度
- severity_threshold: medium  # 最低報告嚴重度

# ~/.hermes/config.yaml
memory:
  provider: supermemory  # 或 mem0, honcho, builtin
  auto_save: true
  nudge_interval: 5      # 每 5 輪對話提醒一次持久化
  
  supermemory:
    containers:
      - name: project-knowledge
        description: "專案技術知識"
      - name: user-preferences  
        description: "使用者偏好與習慣"
    search_mode: hybrid    # keyword + semantic

# Agent 內部 tool call 格式
memory(operations=[
    {"action": "add", "key": "new_learning", "value": "React 19 uses compiler..."},
    {"action": "replace", "key": "project_phase", "value": "production"},
    {"action": "remove", "key": "outdated_note_xyz"}
])

hermes tools                    # 列出所有工具集與狀態
hermes tools enable browser     # 啟用瀏覽器工具集
hermes tools disable delegation # 停用委派工具集

# ~/.hermes/config.yaml
mcp:
  servers:
    - name: github
      command: npx
      args: ["@modelcontextprotocol/server-github"]
      env:
        GITHUB_TOKEN: "${GITHUB_TOKEN}"
    - name: postgres
      command: npx
      args: ["@modelcontextprotocol/server-postgres"]
      env:
        DATABASE_URL: "${DATABASE_URL}"

# ~/.hermes/config.yaml
terminal:
  backend: docker
  docker:
    image: "python:3.11-slim"
    docker_env:
      PYTHONPATH: "/workspace"
    volumes:
      - "./project:/workspace"

# CLI 切換
/model anthropic:claude-sonnet-4-20250514
/model openrouter:deepseek/deepseek-r1
/model nous:hermes-3-405b
/model google:gemini-2.5-pro
/model qwen:qwen-max
/model xai:grok-3
/model xai:grok-composer-2.5-fast   # v0.17.0: Cursor Composer 模型, 200k context

# 查看當前模型
/model

# 切換 Provider（v0.16.0+ Fuzzy Model Picker：所有介面統一模糊搜尋）
hermes model   # 互動式選擇

# ~/.hermes/config.yaml
providers:
  primary: anthropic
  fallback:
    - openrouter
    - nous
  
  anthropic:
    api_key: "${ANTHROPIC_API_KEY}"
    model: claude-sonnet-4-20250514
  
  openrouter:
    api_key: "${OPENROUTER_API_KEY}"
    model: anthropic/claude-sonnet-4-20250514
  
  nous:
    # OAuth 自動管理
    model: hermes-3-405b

# 輔助模型（壓縮 / Vision / 摘要）
auxiliary:
  provider: nous
  model: mimo-v2-pro  # 免費模型

# 手動觸發 Curator
hermes curator

# 查看 Curator 狀態（依使用頻率排名）
hermes curator status

# 查看最近一次 Curator 報告
cat logs/curator/REPORT.md

# ~/.hermes/config.yaml
auxiliary:
  curator:
    enabled: true           # 啟用 / 停用
    interval_days: 7        # 執行間隔（天）
    min_quality_score: 0.3  # 品質閾值
    max_skills: 500         # 技能庫上限
    protect_pinned: true    # 保護 pinned skills
    consolidate: false      # v0.17.0: LLM consolidation 改為 opt-in（預設 deterministic sweep 免費）

# 設定一個跨回合持久目標
> /goal 將整個後端 API 從 REST 遷移到 GraphQL，包括 schema 設計、resolver 實作、測試覆蓋

# Agent 會自動拆解為多個子任務，持續追蹤
# 即使切換話題或重啟 Gateway，目標仍然有效

# 查看當前目標狀態
> /goal status

# 清除目標
> /goal clear

# 一鍵安裝（處理所有依賴：Python、Node.js、套件、hermes 指令）
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# 重新載入 Shell 環境
source ~/.bashrc    # Bash 使用者
source ~/.zshrc     # Zsh 使用者

# 驗證安裝
hermes --version

# 1. Clone 專案
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# 2. 安裝 uv（Python 套件管理器）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 3. 建立虛擬環境
uv venv venv --python 3.11
source venv/bin/activate

# 4. 安裝所有依賴
uv pip install -e ".[all]"

# 5. 驗證
python cli.py --version

# v0.6.0+ 支援 Homebrew
brew install hermes-agent

# 升級
brew upgrade hermes-agent

# 以系統管理員身份開啟 PowerShell
# 一鍵安裝（處理所有依賴）
irm https://hermes-agent.nousresearch.com/install.ps1 | iex

# 驗證安裝
hermes --version

# 拉取映像
docker pull ghcr.io/nousresearch/hermes-agent:latest

# 啟動（互動模式）
docker run -it \
  --name hermes \
  -v ~/.hermes:/root/.hermes \
  -e ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY}" \
  ghcr.io/nousresearch/hermes-agent:latest

# 啟動（Gateway 模式，背景執行）
docker run -d \
  --name hermes-gateway \
  --restart unless-stopped \
  -v ~/.hermes:/root/.hermes \
  -e ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY}" \
  -e TELEGRAM_BOT_TOKEN="${TELEGRAM_BOT_TOKEN}" \
  ghcr.io/nousresearch/hermes-agent:latest \
  hermes gateway start

# Dockerfile（專案根目錄已提供）
FROM python:3.11-slim

WORKDIR /app

# 安裝系統依賴
RUN apt-get update && apt-get install -y \
    git curl nodejs npm \
    && rm -rf /var/lib/apt/lists/*

# 複製應用程式
COPY . .

# 安裝 Python 依賴
RUN pip install -e ".[all]"

# 安裝 Playwright（瀏覽器工具）
RUN playwright install chromium

ENTRYPOINT ["hermes"]

# docker-compose.yml
version: '3.8'

services:
  hermes-agent:
    build: .
    container_name: hermes-agent
    restart: unless-stopped
    volumes:
      - hermes-data:/root/.hermes
      - ./projects:/workspace
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
    ports:
      - "8080:8080"  # API Server
    networks:
      - hermes-net
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: '2.0'

  hermes-gateway:
    build: .
    container_name: hermes-gateway
    restart: unless-stopped
    command: hermes gateway start
    volumes:
      - hermes-data:/root/.hermes
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
      - DISCORD_BOT_TOKEN=${DISCORD_BOT_TOKEN}
      - SLACK_BOT_TOKEN=${SLACK_BOT_TOKEN}
    networks:
      - hermes-net

volumes:
  hermes-data:

networks:
  hermes-net:
    driver: bridge

# Nix Flake 安裝（v0.5.0+ 支援）
nix profile install github:NousResearch/hermes-agent

# 或在 NixOS 配置中
{
  inputs.hermes-agent.url = "github:NousResearch/hermes-agent";
  
  # 加入系統套件
  environment.systemPackages = [ inputs.hermes-agent.packages.${system}.default ];
}

# 執行完整設定精靈（推薦首次使用）
hermes setup

# 精靈將引導完成：
# 1. 選擇 LLM Provider
# 2. 輸入 API Key
# 3. 選擇模型
# 4. 設定工具
# 5. 設定記憶系統
# 6. （可選）設定訊息平台

# ~/.hermes/.env
# === 主要 Provider（至少需要一個）===

# Anthropic（推薦）
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx

# OpenAI
OPENAI_API_KEY=sk-xxxxxxxxxxxxx

# OpenRouter（200+ 模型）
OPENROUTER_API_KEY=sk-or-xxxxxxxxxxxxx

# Nous Portal（免費模型可用）
# 使用 OAuth 登入：hermes auth login nous

# Google AI Studio（Gemini）
GOOGLE_AI_API_KEY=AIzaSyxxxxxxxxxxxx

# Qwen（通義千問）— OAuth 登入
# 使用 OAuth 登入：hermes auth login qwen

# xAI（Grok）
XAI_API_KEY=xai-xxxxxxxxxxxxx

# === 訊息平台 ===
TELEGRAM_BOT_TOKEN=1234567890:ABCDefghIJKLmnoPQRSTuvwxyz
DISCORD_BOT_TOKEN=your-discord-bot-token
SLACK_BOT_TOKEN=xoxb-your-slack-token

# === MCP 伺服器 ===
GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb

# OAuth 登入（瀏覽器會自動開啟）
hermes auth login nous

# 登入後可使用免費模型（如 MiMo v2 Pro）
# 無需 API Key，適合預算有限的團隊

# ~/.hermes/config.yaml

# === 模型設定 ===
model:
  provider: anthropic
  model: claude-sonnet-4-20250514
  reasoning_effort: medium   # low / medium / high

# === 輔助模型（壓縮/Vision/摘要）===
auxiliary:
  provider: nous
  model: mimo-v2-pro         # 免費

# === 記憶設定 ===
memory:
  provider: builtin           # builtin / mem0 / supermemory / honcho
  auto_save: true
  nudge_interval: 5

# === 安全設定 ===
security:
  command_approval: smart      # always / smart / never / yolo
  allowed_commands:
    - "git status"
    - "git diff"
    - "npm test"
    - "mvn test"
    - "python -m pytest"

# === 終端後端 ===
terminal:
  backend: local               # local / docker / ssh / daytona / modal
  
# === 工具集 ===
toolsets:
  enabled:
    - core
    - web
    - delegation
    - cron
    - code
  disabled:
    - browser

# === MCP ===
mcp:
  servers: []

# === Gateway ===
gateway:
  platforms:
    telegram:
      enabled: true
      allowed_users: ["your_telegram_id"]
    discord:
      enabled: false
    slack:
      enabled: false

# === 日誌 ===
logging:
  level: INFO                  # DEBUG / INFO / WARNING / ERROR
  file: ~/.hermes/logs/agent.log

# 手動驗證設定
hermes doctor

# 診斷內容：
# ✅ Config YAML syntax valid
# ✅ Provider credentials found
# ✅ Model accessible
# ✅ Memory provider configured
# ✅ No WAL corruption detected
# ⚠️ Browser toolset disabled (optional)

# 啟動 Hermes（互動式 CLI）
hermes

# 進入 TUI 界面後，直接輸入問題：
> 你好！請自我介紹一下你的能力

# Agent 會回應其工具、記憶、技能能力
# 使用 Ctrl+C 暫停當前操作
# 使用 /new 開啟新對話
# 使用 /exit 或 Ctrl+D 離開

# 使用 -z 旗標執行單次任務（不進入互動式 TUI）
hermes -z "列出當前目錄下所有 Python 檔案"

# 指定模型與 Provider
hermes -z --model anthropic:claude-sonnet-4-20250514 "審查 main.py 的安全性"
hermes -z --provider openrouter "產生項目摘要"

# 適合 CI/CD 或腳本自動化使用

# 將當前任務移至背景運行
/background

# 允許平行執行多個任務，主線程可繼續對話
# 背景任務完成後會自動通知

# 自訂快速指令（直接執行 Shell，不經過 LLM）
# ~/.hermes/config.yaml
quick_commands:
  test: "mvn test"
  lint: "npm run lint"
  deploy: "./scripts/deploy.sh"

# 在 TUI 中使用
/test    # 直接執行 mvn test
/lint    # 直接執行 npm run lint

# config.yaml
session:
  auto_resume: true    # 啟動時自動復原上次對話記錄

# 啟動 Hermes 並指定工作目錄
cd /path/to/your/project
hermes

# 開始互動
> 請幫我建立一個 Spring Boot REST API 專案，包含：
> 1. 使用者 CRUD API（/api/users）
> 2. JWT 認證
> 3. PostgreSQL 資料庫
> 4. Swagger 文件
> 5. 完整的單元測試

Agent 會自動：
1. [execute_command] 使用 Spring Initializr 建立專案骨架
2. [write_file] 建立 Entity、Repository、Service、Controller
3. [write_file] 建立 Security 配置（JWT Filter）
4. [write_file] 建立 application.yml（DB 連線）
5. [write_file] 建立 Swagger 配置
6. [write_file] 建立 JUnit 測試
7. [execute_command] 執行 mvn test 驗證
8. [自動學習] 封裝為 "spring-boot-rest-api" Skill

# 設定 Memory Provider
hermes setup  # 在 Memory 區段選擇 provider

# 或直接編輯 config.yaml
hermes config set memory.provider supermemory
hermes config set memory.auto_save true

# 告訴 Agent 你的偏好
> 我使用 Java 21，偏好 Clean Architecture，測試框架用 JUnit 5 + Mockito

# Agent 會自動記錄到 MEMORY.md：
# - User prefers Java 21
# - Uses Clean Architecture
# - Testing: JUnit 5 + Mockito

# 下次對話時，Agent 會自動載入這些偏好

# 查看所有工具集
hermes tools

# 啟用瀏覽器工具（如需要網頁操作）
hermes tools enable browser

# 設定 MCP 伺服器（擴展工具能力）
hermes config set mcp.servers '[{"name":"github","command":"npx","args":["@modelcontextprotocol/server-github"]}]'

> 請審查 src/main/java/com/example/UserService.java，
> 檢查安全性、效能和程式碼品質問題

# Agent 會：
# 1. 讀取檔案
# 2. 分析 SQL Injection / XSS 風險
# 3. 檢查效能瓶頸（N+1 Query 等）
# 4. 檢查 Code Style
# 5. 產出報告 + 修改建議

> 幫我寫一個 GitHub Actions CI/CD pipeline，需求：
> - Java 21 + Maven
> - 執行 unit test 和 integration test
> - 建構 Docker image
> - 推送到 GitHub Container Registry
> - 部署到 Kubernetes

# Agent 會產出完整的 .github/workflows/deploy.yml

> 每天早上 9 點幫我：
> 1. 執行 git pull 更新專案
> 2. 執行 mvn test
> 3. 將測試結果傳到 Telegram

# Agent 會使用 cron_add 建立排程任務
# 結果自動透過 Gateway 投遞到指定平台

# config.yaml — Cron 進階設定
cron:
  jobs:
    daily-test:
      schedule: "0 8 * * *"
      task: "執行完整測試套件並產出報告"
      workdir: "/home/dev/my-project"       # v0.12.0: 指定工作目錄
      deliver_to: telegram
    
    weekly-report:
      schedule: "0 9 * * 1"
      task: "根據上次測試結果產出週報"
      context_from: "daily-test"             # v0.12.0: 從前一任務繼承上下文
      deliver_to: slack

mkdir -p ~/.hermes/skills/user/bank-api-security-check

# bank-api-security-check

## Description
銀行 API 安全性檢查技能。依據 OWASP Top 10 和金融法規要求，
對 RESTful API 進行全面安全掃描。

## Triggers
- 使用者提到「安全檢查」、「弱掃」、「安全掃描」

## Steps
1. **掃描 API Controller**
   - 讀取所有 @RestController 類別
   - 檢查是否有 @PreAuthorize 或 @Secured 註解
   - 確認 CSRF 保護狀態

2. **檢查認證機制**
   - 確認 JWT 配置（Token 過期時間、簽發者驗證）
   - 檢查 OAuth2 Scope 設定
   - 確認 CORS 配置是否過於寬鬆

3. **掃描注入風險**
   - SQL Injection：搜尋字串拼接 SQL
   - XSS：檢查輸入是否有 sanitize
   - Command Injection：檢查 Runtime.exec() 使用
   - SSRF：檢查外部 URL 呼叫是否有白名單

4. **檢查敏感資料處理**
   - 確認密碼使用 BCrypt/Argon2 加密
   - 確認 PII 資料是否有遮蔽（Masking）
   - 確認日誌中不包含敏感資訊

5. **產出報告**
   - 格式：Markdown 表格
   - 欄位：風險項目 / 嚴重度 / 檔案位置 / 修復建議
   - 依嚴重度排序（Critical > High > Medium > Low）

## Config
- severity_threshold: medium
- include_owasp_references: true
- output_format: markdown

# skill.md 中加入 Config Block

## Config
- api_scan_depth: 5
  description: "API 掃描深度（目錄層級）"
  required: true
- custom_rules_path: null
  description: "自訂規則檔案路徑"
  required: false

# 瀏覽社群技能
/skills

# 安裝特定技能
/skills install popular-web-designs
/skills install gitnexus-explorer
/skills install research-paper-writing

# 自動同步到所有 Profiles
hermes update  # 會自動將 bundled skills 同步到所有 profile

> 請用以下分工完成這個功能：
> 1. 先研究 Spring Boot 3 的 Virtual Threads 最佳實踐
> 2. 根據研究結果開發 API
> 3. 對開發結果進行安全審查
> 
> 使用 subagent 平行處理第 1 和第 2 步

# Agent 會自動使用 delegate_task 工具委派子代理

# 同步委派（既有行為，等待完成）
delegate_task(task="分析 API 安全性")

# 背景委派（v0.17.0 新增，不阻塞主對話）
delegate_task(
    task="掃描所有 1,200 個 REST endpoint 的安全合規性",
    background=True
)
# 主 Agent 可繼續回應使用者
# 背景子代理完成後，結果自動注入對話上下文

# Agent 可以生成並執行這樣的腳本
import json

# 透過 RPC 呼叫多個工具
results = []
files = tool_call("search_files", {"pattern": "*.java", "path": "src/"})
for f in files:
    content = tool_call("read_file", {"path": f})
    if "SQL" in content and "PreparedStatement" not in content:
        results.append({"file": f, "risk": "SQL Injection"})

# 一次性回傳結果，零額外上下文成本
print(json.dumps(results))

# config.yaml — Multi-agent Kanban 完整設定
kanban:
  enabled: true
  multi_project: true         # 支援多專案看板
  max_retries: 3              # 每任務最大重試次數
  heartbeat_interval: 30      # Worker 心跳間隔（秒）
  zombie_timeout: 300         # 殭屍 Worker 判定超時（秒）
  hallucination_gate: true    # 啟用幻覺閘門
  
  # 跨 Profile 共享設定
  sharing:
    board: true               # 共享看板
    workspaces: true           # 共享工作區
    worker_logs: true          # 共享 Worker 日誌

# Kanban 操作指令
/kanban                        # 查看當前看板狀態
/kanban create "重構 API"       # 建立新任務
/kanban assign task-1 backend  # 指派任務到 Profile
/kanban status                 # 查看所有任務進度

# Worker 生命週期管理
hermes kanban workers          # 列出所有 Worker 狀態
hermes kanban diagnostics      # 執行任務診斷引擎

# ~/.hermes/config.yaml
memory:
  provider: supermemory
  
  supermemory:
    # 多容器設計
    containers:
      - name: technical-knowledge
        description: "技術知識庫（架構/設計模式/最佳實踐）"
      - name: project-context
        description: "專案上下文（需求/決策/變更記錄）"
      - name: team-preferences
        description: "團隊偏好（程式風格/工具設定/流程）"
    
    search_mode: hybrid     # keyword + semantic
    identity_template: "enterprise-developer"

# ~/.hermes/config.yaml
memory:
  provider: mem0
  
  mem0:
    api_key: "${MEM0_API_KEY}"     # Cloud 版
    # 或使用 mem0.json 進行本地配置
    prefetch_context: true          # LLM 呼叫前預取
    secret_redaction: true          # 自動遮蔽敏感資訊

> 我要重構整個訂單系統，請先分析後提出分階段執行計畫：
> 
> 系統現況：
> - Monolithic Spring Boot 2.7
> - 16 個 REST API
> - PostgreSQL 資料庫
> - 無單元測試
> 
> 目標：
> - 升級到 Spring Boot 3.2
> - 導入 Clean Architecture
> - 補齊單元測試（>80% 覆蓋率）
> - 保持向後相容

# Agent 會產出分階段計畫：
# Phase 1: 架構分析 & 依賴盤點
# Phase 2: Spring Boot 3.2 升級
# Phase 3: Clean Architecture 重構
# Phase 4: 測試補齊
# Phase 5: 效能測試 & 上線

> 建立以下自動化流程：
> 
> 1. 每天 08:00 - 檢查 GitHub 上的新 Issue，摘要傳到 Slack
> 2. 每天 18:00 - 執行程式碼品質掃描，結果傳到 Telegram
> 3. 每週一 09:00 - 生成週報（本週 commits / issues / PRs 摘要）

# ~/.hermes/blueprints/weekly-report.yaml
name: weekly-report
schedule: "每週一早上 9 點"
task: |
  彙整本週的 Git commits、PR 合併數、Issue 解決數，
  生成 Markdown 週報傳送到 Slack #engineering 頻道
profile: devops
channel: slack
conditions:
  - type: day_of_week
    value: monday

# AGENTS.md - 專案上下文

## 專案說明
這是一個銀行核心系統的 REST API，使用 Spring Boot 3.2 + Java 21。

## 開發規範
- 所有 API 必須有輸入驗證
- 所有 Service 必須有 JUnit 測試
- 所有 Repository 方法必須使用 Parameterized Query
- 程式碼風格遵循 Google Java Style

## 部署流程
1. 通過 CI（mvn verify）
2. SonarQube 掃描通過
3. Docker build & push
4. K8s rolling update

## 安全要求
- 所有 API 需 JWT 認證
- 敏感資料需加密存儲
- 日誌不得包含 PII

# 建立不同團隊的 Profile
hermes --profile team-backend     # 後端團隊
hermes --profile team-frontend    # 前端團隊
hermes --profile team-devops      # DevOps 團隊

# 每個 Profile 有獨立的：
# - Skills（技能）
# - Memory（記憶）
# - Config（設定）
# - SOUL.md（人格）

# SOUL.md
你是「Hermes」，一個專業的 AI 開發助理。

## 性格特質
- 精確、專業、注重細節
- 主動提供替代方案
- 遇到不確定的問題時，會明確告知並提供最佳猜測

## 專業領域
- Java / Spring Boot 開發
- DevOps / CI/CD 流程
- 系統架構設計

## 語言偏好
- 使用繁體中文回應
- 程式碼註解使用英文
- 專有名詞保留原文

## 限制
- 不得修改生產環境設定
- 不得刪除 Git 分支
- 敏感資訊必須遮蔽

## 輸出格式
- 程式碼使用 Markdown Code Block
- 表格使用 Markdown 表格
- 重要警告使用 ⚠️ 標記

# 設定人格
/personality professional    # 專業模式
/personality friendly        # 友善模式
/personality concise         # 精簡模式

# 自訂人格（寫入 SOUL.md）
> 請調整你的人格為：專業但友善的金融科技顧問

# 每個 Profile 有獨立 SOUL.md
~/.hermes/profiles/
├── default/
│   └── SOUL.md          # 預設人格
├── team-backend/
│   └── SOUL.md          # 後端團隊：專注 Java / Spring Boot
├── team-devops/
│   └── SOUL.md          # DevOps：專注部署 / 監控
└── customer-service/
    └── SOUL.md          # 客服：親切有禮、遵守合規

# AGENTS.md

## 專案概述
[簡短描述專案目標和技術棧]

## 技術規範
[列出程式語言版本、框架、套件管理器等]

## 程式碼風格
[定義 coding standard、命名慣例、註解要求]

## 安全要求
[列出安全合規要求、禁止的操作]

## Git 工作流
[定義分支策略、commit 格式、PR 規範]

## 測試要求
[定義測試框架、覆蓋率目標]

## 部署流程
[定義 CI/CD 流程、環境配置]

# .hermesignore — 排除 Agent 不應讀取的檔案
*.env
**/secrets/**
**/node_modules/**
**/.git/**
**/target/**
**/build/**
*.log
credentials.yaml

# plugins/my-output-filter/__init__.py — 使用 transform_llm_output hook
from hermes.plugins import PluginBase, hook

class OutputFilterPlugin(PluginBase):
    name = "my-output-filter"
    version = "1.0.0"
    
    @hook("transform_llm_output")
    async def filter_output(self, output: str) -> str:
        """在 LLM 輸出送入對話前進行過濾/變形"""
        # 例如：移除敏感資訊、壓縮上下文
        return output.replace("INTERNAL_SECRET", "[REDACTED]")

# 安裝 Spotify Plugin（v0.12.0 預設已內建）
hermes plugins enable spotify

# 首次使用會啟動 PKCE OAuth 流程
# 瀏覽器自動開啟 Spotify 授權頁面

# 之後可直接對 Agent 下達音樂指令：
> 播放一些適合寫程式的 Lo-fi 音樂
> 暫停播放
> 建立一個名為「Coding Vibes」的播放清單

# config.yaml
plugins:
  google_meet:
    enabled: true
    credentials: "${GOOGLE_MEET_CREDENTIALS}"  # OAuth 或 Service Account

# plugins/my-custom-tool/__init__.py
from hermes.plugins import PluginBase, tool

class MyCustomPlugin(PluginBase):
    name = "my-custom-tool"
    version = "1.0.0"
    
    @tool(description="執行自訂業務邏輯")
    async def my_action(self, param: str) -> str:
        # 實作你的工具邏輯
        return f"執行完成: {param}"

# 啟用語音模式
hermes --voice

# 或在對話中切換
/voice on     # 開啟語音
/voice off    # 關閉語音

# 設定 STT/TTS Provider
hermes config set voice.stt_provider openai
hermes config set voice.tts_provider elevenlabs

# ~/.hermes/config.yaml
voice:
  enabled: false                # 預設關閉
  stt_provider: openai          # openai / voxtral / deepgram / local
  tts_provider: openai          # openai / elevenlabs / minimax / piper / xai
  
  openai:
    stt_model: whisper-1
    tts_model: tts-1
    tts_voice: alloy             # alloy / echo / fable / onyx / nova / shimmer
  
  elevenlabs:
    api_key: "${ELEVENLABS_API_KEY}"
    voice_id: "your-voice-id"
  
  # xAI Custom Voices（v0.13.0 新增）
  xai:
    api_key: "${XAI_API_KEY}"
    voice_id: "your-cloned-voice-id"  # 語音克隆 ID
  
  voxtral:
    api_key: "${MISTRAL_API_KEY}"   # Mistral AI API Key
  
  # v0.12.0: Piper 本地 TTS
  piper:
    model: "zh_CN-huayan-medium"  # 本地模型名稱
    speaker_id: 0                 # 說話者 ID
    # 模型存放於 ~/.hermes/tts/piper/models/
    # 首次使用自動下載

# 自訂 TTS Provider
tts:
  providers:
    my_custom_tts:
      plugin: "plugins/tts-my-engine"
      endpoint: "http://localhost:5500/api/tts"
      voice: "default"

使用者：[傳送語音備忘錄]
Agent：
  1. 自動用 STT 轉錄語音為文字
  2. 處理轉錄後的文字指令
  3. 以文字或語音回應（依設定）

# config.yaml
gateway:
  platforms:
    telegram:
      enabled: true
      voice_transcription: true    # 自動轉錄語音備忘錄
      voice_response: false        # 是否以語音回應

# Discord Voice Channel 設定
gateway:
  platforms:
    discord:
      enabled: true
      voice_channel:
        enabled: true
        auto_join: false          # 是否自動加入語音頻道
        wake_word: "hermes"       # 喚醒詞

# agent_service.py
from fastapi import FastAPI, HTTPException
from fastapi.responses import StreamingResponse
from pydantic import BaseModel
import subprocess
import asyncio
import json

app = FastAPI(title="Hermes Agent Service", version="1.0.0")

class AgentRequest(BaseModel):
    """Agent 請求模型"""
    message: str
    session_id: str | None = None
    profile: str = "default"
    model: str | None = None

class AgentResponse(BaseModel):
    """Agent 回應模型"""
    response: str
    session_id: str
    tokens_used: int
    tools_called: list[str]

@app.post("/api/agent/chat", response_model=AgentResponse)
async def chat(request: AgentRequest):
    """
    與 Hermes Agent 進行對話
    
    - **message**: 使用者訊息
    - **session_id**: 對話 Session ID（可選，用於延續對話）
    - **profile**: Agent Profile（預設 default）
    - **model**: 指定模型（可選）
    """
    cmd = ["hermes", "chat", "--message", request.message]
    
    if request.session_id:
        cmd.extend(["--session", request.session_id])
    if request.profile != "default":
        cmd.extend(["--profile", request.profile])
    if request.model:
        cmd.extend(["--model", request.model])
    
    try:
        result = await asyncio.create_subprocess_exec(
            *cmd,
            stdout=asyncio.subprocess.PIPE,
            stderr=asyncio.subprocess.PIPE
        )
        stdout, stderr = await result.communicate()
        
        if result.returncode != 0:
            raise HTTPException(status_code=500, detail=stderr.decode())
        
        output = json.loads(stdout.decode())
        return AgentResponse(
            response=output["response"],
            session_id=output["session_id"],
            tokens_used=output.get("tokens_used", 0),
            tools_called=output.get("tools_called", [])
        )
    except json.JSONDecodeError:
        return AgentResponse(
            response=stdout.decode(),
            session_id=request.session_id or "new",
            tokens_used=0,
            tools_called=[]
        )

@app.post("/api/agent/stream")
async def stream_chat(request: AgentRequest):
    """SSE 串流模式 - 即時回傳 Agent 回應"""
    async def generate():
        cmd = ["hermes", "chat", "--message", request.message, "--stream"]
        process = await asyncio.create_subprocess_exec(
            *cmd,
            stdout=asyncio.subprocess.PIPE,
            stderr=asyncio.subprocess.PIPE
        )
        
        async for line in process.stdout:
            text = line.decode().strip()
            if text:
                yield f"data: {json.dumps({'content': text})}\n\n"
        
        yield f"data: {json.dumps({'done': True})}\n\n"
    
    return StreamingResponse(generate(), media_type="text/event-stream")

@app.get("/api/agent/skills")
async def list_skills():
    """列出所有可用技能"""
    result = subprocess.run(
        ["hermes", "skills", "--json"],
        capture_output=True, text=True
    )
    return json.loads(result.stdout)

@app.post("/api/agent/skill/{skill_name}")
async def execute_skill(skill_name: str, request: AgentRequest):
    """執行指定技能"""
    message = f"/{skill_name} {request.message}"
    request.message = message
    return await chat(request)

# 安裝依賴
pip install fastapi uvicorn pydantic

# 啟動服務
uvicorn agent_service:app --host 0.0.0.0 --port 8000 --reload

# API 文件：http://localhost:8000/docs

/**
 * Hermes Agent 客戶端
 * 透過 HTTP 呼叫 Agent Service 或直接呼叫 CLI
 */
@Service
@Slf4j
public class HermesAgentClient {

    private final WebClient webClient;
    
    @Value("${hermes.agent.url:http://localhost:8000}")
    private String agentUrl;

    public HermesAgentClient(WebClient.Builder builder) {
        this.webClient = builder.baseUrl(agentUrl).build();
    }

    /**
     * 與 Agent 對話
     * @param message 使用者訊息
     * @param sessionId Session ID（可選）
     * @return Agent 回應
     */
    public Mono<AgentResponse> chat(String message, String sessionId) {
        AgentRequest request = new AgentRequest();
        request.setMessage(message);
        request.setSessionId(sessionId);
        
        return webClient.post()
            .uri("/api/agent/chat")
            .bodyValue(request)
            .retrieve()
            .bodyToMono(AgentResponse.class)
            .doOnError(e -> log.error("Agent 呼叫失敗", e))
            .onErrorResume(e -> Mono.just(
                AgentResponse.error("Agent 暫時無法回應，請稍後再試")
            ));
    }

    /**
     * SSE 串流對話
     */
    public Flux<String> streamChat(String message) {
        AgentRequest request = new AgentRequest();
        request.setMessage(message);
        
        return webClient.post()
            .uri("/api/agent/stream")
            .bodyValue(request)
            .retrieve()
            .bodyToFlux(String.class);
    }

    /**
     * 執行指定技能
     */
    public Mono<AgentResponse> executeSkill(String skillName, String message) {
        AgentRequest request = new AgentRequest();
        request.setMessage(message);
        
        return webClient.post()
            .uri("/api/agent/skill/{skill}", skillName)
            .bodyValue(request)
            .retrieve()
            .bodyToMono(AgentResponse.class);
    }
}

/**
 * 智能助手 API Controller
 */
@RestController
@RequestMapping("/api/assistant")
@RequiredArgsConstructor
public class AssistantController {

    private final HermesAgentClient agentClient;

    @PostMapping("/chat")
    public Mono<ResponseEntity<AgentResponse>> chat(
            @RequestBody @Valid ChatRequest request) {
        return agentClient.chat(request.getMessage(), request.getSessionId())
            .map(ResponseEntity::ok);
    }

    @PostMapping("/stream")
    public Flux<ServerSentEvent<String>> streamChat(
            @RequestBody @Valid ChatRequest request) {
        return agentClient.streamChat(request.getMessage())
            .map(content -> ServerSentEvent.<String>builder()
                .data(content)
                .build());
    }

    @PostMapping("/code-review")
    public Mono<ResponseEntity<AgentResponse>> codeReview(
            @RequestBody @Valid CodeReviewRequest request) {
        String prompt = String.format(
            "請審查以下程式碼的安全性和品質：\n```java\n%s\n```",
            request.getCode()
        );
        return agentClient.executeSkill("code-review", prompt)
            .map(ResponseEntity::ok);
    }
}

<template>
  <div class="agent-chat">
    <div class="messages" ref="messagesRef">
      <div v-for="msg in messages" :key="msg.id"
           :class="['message', msg.role]">
        <div class="content" v-html="renderMarkdown(msg.content)"></div>
        <div class="meta">
          <span v-if="msg.tokens">{{ msg.tokens }} tokens</span>
          <span v-if="msg.tools?.length">
            工具：{{ msg.tools.join(', ') }}
          </span>
        </div>
      </div>
      <div v-if="isStreaming" class="message assistant streaming">
        <div class="content">{{ streamContent }}</div>
        <span class="typing-indicator">▋</span>
      </div>
    </div>
    
    <div class="input-area">
      <textarea v-model="input" 
                @keydown.enter.ctrl="sendMessage"
                placeholder="輸入訊息（Ctrl+Enter 發送）"
                rows="3"></textarea>
      <button @click="sendMessage" :disabled="isStreaming">
        {{ isStreaming ? '回應中...' : '發送' }}
      </button>
    </div>
  </div>
</template>

<script setup>
import { ref, nextTick } from 'vue'
import { marked } from 'marked'

const messages = ref([])
const input = ref('')
const isStreaming = ref(false)
const streamContent = ref('')
const sessionId = ref(null)
const messagesRef = ref(null)

const AGENT_API = '/api/agent'

async function sendMessage() {
  if (!input.value.trim() || isStreaming.value) return
  
  const userMsg = input.value.trim()
  input.value = ''
  
  messages.value.push({
    id: Date.now(),
    role: 'user',
    content: userMsg
  })
  
  isStreaming.value = true
  streamContent.value = ''
  
  try {
    const response = await fetch(`${AGENT_API}/stream`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        message: userMsg,
        session_id: sessionId.value
      })
    })
    
    const reader = response.body.getReader()
    const decoder = new TextDecoder()
    
    while (true) {
      const { done, value } = await reader.read()
      if (done) break
      
      const text = decoder.decode(value)
      const lines = text.split('\n')
      
      for (const line of lines) {
        if (line.startsWith('data: ')) {
          const data = JSON.parse(line.slice(6))
          if (data.done) break
          streamContent.value += data.content
        }
      }
      
      await nextTick()
      scrollToBottom()
    }
    
    messages.value.push({
      id: Date.now(),
      role: 'assistant',
      content: streamContent.value
    })
  } catch (error) {
    messages.value.push({
      id: Date.now(),
      role: 'error',
      content: `錯誤：${error.message}`
    })
  } finally {
    isStreaming.value = false
    streamContent.value = ''
  }
}

function renderMarkdown(text) {
  return marked.parse(text || '')
}

function scrollToBottom() {
  if (messagesRef.value) {
    messagesRef.value.scrollTop = messagesRef.value.scrollHeight
  }
}
</script>

# 不要這樣做 ❌
export ANTHROPIC_API_KEY=sk-ant-real-key-here

# 應該這樣做 ✅
# .env 檔案（不入版控）
ANTHROPIC_API_KEY=${vault:secret/hermes/anthropic-key}

# ~/.hermes/config.yaml
security:
  command_approval: smart      # 推薦企業使用

  # 永久白名單（無需審批）
  allowed_commands:
    - "git status"
    - "git diff"
    - "git log"
    - "mvn test"
    - "mvn verify"
    - "npm test"
    - "python -m pytest"
    - "ls"
    - "cat"
    - "grep"
  
  # 永久黑名單（永遠需要審批）
  # rm -rf, git push --force, DROP TABLE 等自動觸發

# config.yaml
model:
  provider: anthropic
  model: claude-sonnet-4-20250514

# 使用免費模型做輔助任務
auxiliary:
  provider: nous
  model: mimo-v2-pro     # 免費！

# Context 壓縮策略
context:
  auto_compress: true
  compress_threshold: 0.8  # 上下文使用 80% 時觸發壓縮

# 查看使用量
/usage

# 查看 N 天內的使用洞察
/insights --days 7

# 範例輸出：
# 過去 7 天：
# - 總 Token：125,430
# - 估計成本：$2.35
# - 對話數：45
# - 技能使用：12 次
# - 最常用工具：execute_command(38%), write_file(25%)

# 手動壓縮
/compress

# 自動壓縮（config.yaml）
context:
  auto_compress: true
  compress_threshold: 0.8

# v0.11.0: ~2.1s 冷啟動
# v0.12.0: ~0.9s 冷啟動（-57%）
# v0.14.0: 再快 ~19 秒（Cold-start 效能浪潮）
# v0.15.0: 47% fewer per-turn function calls
#          `hermes --version` 快 63%
#          Termux: 2.9s → 0.8s
hermes  # 幾乎即時啟動

# config.yaml
prompt_caching:
  cache_ttl: 300          # 預設 5 分鐘（秒）
  # cache_ttl: 3600       # 可設為 1 小時（opt-in）
  # 減少重複 System Prompt 的 Token 消耗

# 傳統方式（多次推理，高 Token 消耗）
Agent → read_file(a.java) → read_file(b.java) → read_file(c.java) → 分析
# 4 次推理 = 4x Token 成本

# Programmatic 方式（單次推理，低 Token 消耗）
Agent → execute_code("讀取所有 .java 並分析") → 結果
# 1 次推理 + 本地執行 = 1x Token 成本

# 背景任務 + 自動通知（v0.8.0 新增 notify_on_complete）
> 在背景執行完整測試套件，完成後通知我

# Agent 使用 execute_command 的 background + notify_on_complete
# 測試完成後自動通知到 CLI / Telegram / Discord

# 委派子代理平行處理，減少總等待時間
> 請同時做以下三件事：
> 1. 搜尋最新的 Spring Boot 安全修補
> 2. 掃描 src/ 中的程式碼品質問題
> 3. 檢查 Docker Compose 配置是否正確

# 三個 subagent 平行執行
# 總時間 ≈ max(task1, task2, task3) 而非 sum(task1+task2+task3)

# Hermes 自動寫入日誌
~/.hermes/logs/agent.log    # INFO+ 級別
~/.hermes/logs/errors.log   # WARNING+ 級別

# 即時查看日誌
hermes logs                  # tail -f agent.log
hermes logs --errors         # 只看錯誤
hermes logs --filter "tool"  # 過濾特定關鍵字

# filebeat.yml
filebeat.inputs:
  - type: log
    paths:
      - /root/.hermes/logs/agent.log
    json.keys_under_root: true
    fields:
      service: hermes-agent
      environment: production

output.elasticsearch:
  hosts: ["elasticsearch:9200"]
  index: "hermes-agent-%{+yyyy.MM.dd}"

# 自訂 Prometheus metrics exporter
from prometheus_client import Counter, Histogram, start_http_server

agent_requests = Counter(
    'hermes_agent_requests_total',
    'Total agent requests',
    ['status', 'model']
)

token_usage = Histogram(
    'hermes_agent_tokens_used',
    'Tokens used per request',
    buckets=[100, 500, 1000, 5000, 10000, 50000]
)

tool_calls = Counter(
    'hermes_agent_tool_calls_total',
    'Total tool calls',
    ['tool_name']
)

# 啟動 metrics endpoint
start_http_server(9090)

# config.yaml
plugins:
  langfuse:
    enabled: true
    public_key: "${LANGFUSE_PUBLIC_KEY}"
    secret_key: "${LANGFUSE_SECRET_KEY}"
    host: "https://cloud.langfuse.com"  # 或自託管

重試間隔 = min(base_delay * 2^attempt + random_jitter, max_delay)

第 1 次重試: ~1s + jitter
第 2 次重試: ~2s + jitter
第 3 次重試: ~4s + jitter
第 4 次重試: ~8s + jitter
最大間隔: 30s

# 自動 failover 配置
providers:
  primary: anthropic
  fallback:
    - openrouter
    - nous
  
  # 402 付費失敗 → 切換下一個
  # 429 限流 → 指數退避
  # 500 伺服器錯誤 → 切換下一個
  # OAuth 過期 → 自動刷新

# Dockerfile.production
FROM python:3.11-slim AS builder

WORKDIR /app

# 安裝系統依賴
RUN apt-get update && apt-get install -y --no-install-recommends \
    git curl ca-certificates \
    && rm -rf /var/lib/apt/lists/*

# 安裝 Node.js
RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
    && apt-get install -y nodejs \
    && rm -rf /var/lib/apt/lists/*

# 安裝 uv
RUN curl -LsSf https://astral.sh/uv/install.sh | sh

# 複製依賴檔案
COPY pyproject.toml uv.lock ./

# 安裝依賴
RUN /root/.cargo/bin/uv pip install --system -e ".[all]"

# --- Production Stage ---
FROM python:3.11-slim

WORKDIR /app

# 複製已安裝的套件
COPY --from=builder /usr/local/lib/python3.11 /usr/local/lib/python3.11
COPY --from=builder /usr/local/bin /usr/local/bin
COPY --from=builder /usr/bin/node /usr/bin/node

# 複製應用程式
COPY . .

# 非 root 使用者
RUN useradd -m hermes && \
    mkdir -p /home/hermes/.hermes && \
    chown -R hermes:hermes /home/hermes

USER hermes

HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
    CMD hermes doctor --quick || exit 1

ENTRYPOINT ["hermes"]

# docker-compose.production.yml
version: '3.8'

services:
  hermes-agent:
    build:
      context: .
      dockerfile: Dockerfile.production
    container_name: hermes-agent
    restart: unless-stopped
    volumes:
      - hermes-data:/home/hermes/.hermes
      - ./workspace:/workspace
    env_file:
      - .env.production
    ports:
      - "127.0.0.1:8080:8080"
    networks:
      - hermes-net
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: '2.0'
        reservations:
          memory: 1G
          cpus: '0.5'
    logging:
      driver: "json-file"
      options:
        max-size: "50m"
        max-file: "3"
    healthcheck:
      test: ["CMD", "hermes", "doctor", "--quick"]
      interval: 60s
      timeout: 10s
      retries: 3

  hermes-gateway:
    build:
      context: .
      dockerfile: Dockerfile.production
    container_name: hermes-gateway
    restart: unless-stopped
    command: ["gateway", "start"]
    volumes:
      - hermes-data:/home/hermes/.hermes
    env_file:
      - .env.production
    networks:
      - hermes-net
    depends_on:
      hermes-agent:
        condition: service_healthy

volumes:
  hermes-data:
    driver: local

networks:
  hermes-net:
    driver: bridge

# k8s/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hermes-agent
  labels:
    app: hermes-agent
spec:
  replicas: 2
  selector:
    matchLabels:
      app: hermes-agent
  template:
    metadata:
      labels:
        app: hermes-agent
    spec:
      containers:
        - name: hermes-agent
          image: ghcr.io/your-org/hermes-agent:v0.11.0
          resources:
            requests:
              memory: "1Gi"
              cpu: "500m"
            limits:
              memory: "4Gi"
              cpu: "2000m"
          envFrom:
            - secretRef:
                name: hermes-secrets
          volumeMounts:
            - name: hermes-data
              mountPath: /home/hermes/.hermes
            - name: workspace
              mountPath: /workspace
          livenessProbe:
            exec:
              command: ["hermes", "doctor", "--quick"]
            initialDelaySeconds: 30
            periodSeconds: 60
          readinessProbe:
            exec:
              command: ["hermes", "doctor", "--quick"]
            initialDelaySeconds: 10
            periodSeconds: 30
      volumes:
        - name: hermes-data
          persistentVolumeClaim:
            claimName: hermes-data-pvc
        - name: workspace
          persistentVolumeClaim:
            claimName: workspace-pvc

---
apiVersion: v1
kind: Service
metadata:
  name: hermes-agent-svc
spec:
  selector:
    app: hermes-agent
  ports:
    - port: 8080
      targetPort: 8080
  type: ClusterIP

---
apiVersion: v1
kind: Secret
metadata:
  name: hermes-secrets
type: Opaque
stringData:
  ANTHROPIC_API_KEY: "sk-ant-xxxxx"
  OPENROUTER_API_KEY: "sk-or-xxxxx"
  TELEGRAM_BOT_TOKEN: "12345:ABCdef"

# k8s/pvc.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: hermes-data-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: standard

# .github/workflows/hermes-deploy.yml
name: Hermes Agent Deploy

on:
  push:
    branches: [main]
    paths:
      - 'hermes/**'
      - 'Dockerfile*'
      - 'docker-compose*.yml'

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}/hermes-agent

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      
      - name: Install dependencies
        run: |
          pip install -e ".[all,dev]"
      
      - name: Run tests
        run: |
          python -m pytest tests/ -q
      
      - name: Security scan
        run: |
          pip install safety
          safety check

  build-image:
    needs: build-and-test
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      
      - name: Log in to Container Registry
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      
      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          file: Dockerfile.production
          push: true
          tags: |
            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}

  deploy:
    needs: build-image
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to Kubernetes
        uses: azure/k8s-deploy@v4
        with:
          manifests: k8s/
          images: |
            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}

# k8s/deployment.yaml 的 spec.strategy
spec:
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 0      # 升級期間不停機
      maxSurge: 1             # 最多多 1 個 Pod

# 使用內建升級指令
hermes update

# 注意事項（v0.8.0 修正）：
# - 升級不會 kill 正在運行的 gateway service
# - 升級後 bundled skills 會自動同步到所有 profiles
# - 升級後建議執行 hermes doctor 驗證

#!/bin/bash
# backup-hermes.sh

BACKUP_DIR="/backup/hermes/$(date +%Y%m%d)"
HERMES_HOME="$HOME/.hermes"

mkdir -p "$BACKUP_DIR"

# 備份設定
cp "$HERMES_HOME/config.yaml" "$BACKUP_DIR/"
cp "$HERMES_HOME/SOUL.md" "$BACKUP_DIR/" 2>/dev/null

# 備份 Skills
tar czf "$BACKUP_DIR/skills.tar.gz" -C "$HERMES_HOME" skills/

# 備份 Memories
tar czf "$BACKUP_DIR/memories.tar.gz" -C "$HERMES_HOME" memories/ 2>/dev/null

# 備份 Session DB（SQLite）
sqlite3 "$HERMES_HOME/sessions.db" ".backup '$BACKUP_DIR/sessions.db'"

# 上傳到 S3（可選）
# aws s3 sync "$BACKUP_DIR" "s3://your-bucket/hermes-backup/$(date +%Y%m%d)/"

echo "Backup completed: $BACKUP_DIR"

v0.8.0 (v2026.4.8)
│ │ │    │    │ │
│ │ │    │    │ └── 日（Day）
│ │ │    │    └──── 月（Month）
│ │ │    └───────── 年（Year）
│ │ └────────────── Patch（修復版本）
│ └──────────────── Minor（功能版本）
└────────────────── Major（大版本）

# 方式 1：使用內建升級指令（推薦）
hermes update

# 方式 1a：免確認升級（v0.13.0，適合 CI/CD）
hermes update --yes     # 或 -y

# 方式 1b：升級前預檢（v0.12.0）
hermes update --check   # 預覽可升級版本與破壞性變更

# 方式 2：手動升級（pip）
pip install --upgrade hermes-agent

# 方式 3：從原始碼升級
cd ~/hermes-agent
git pull origin main
uv pip install -e ".[all]"

# 方式 4：Docker 映像升級
docker pull ghcr.io/nousresearch/hermes-agent:latest
docker-compose up -d --force-recreate

# 升級後驗證
hermes --version
hermes doctor

# 互動式移轉（推薦）
hermes claw migrate

# 預覽移轉內容（不執行）
hermes claw migrate --dry-run

# 僅移轉使用者資料（不含 Secrets）
hermes claw migrate --preset user-data

# 覆寫已存在的衝突
hermes claw migrate --overwrite

# 移轉 workspace 指令
hermes claw migrate --workspace-target

# Config migration 由 hermes doctor 自動偵測
hermes doctor

# 如果有 config 結構變更，會自動建議修改
# 例如：
# ⚠️ Config migration needed:
#   - memory_mode → recall_mode (Honcho)
#   - reasoning_effort 統一到 config.yaml

# AGENTS.md（放在專案根目錄）
# AI Coding Agent 上下文

## 技術棧
- Java 21 / Spring Boot 3.2
- Maven
- JUnit 5 + Mockito
- PostgreSQL 16
- Clean Architecture

## 程式碼規範
- Google Java Style
- 每個 public 方法必須有 JavaDoc
- 測試覆蓋率 > 80%
- 不得使用 System.out.println

## Git 工作流
- feature/* → develop → main
- Conventional Commits
- PR 需要 2 人 review

# config.yaml
model:
  provider: anthropic
  model: claude-sonnet-4-20250514

security:
  command_approval: smart
  allowed_commands:
    - "mvn *"
    - "git status"
    - "git diff"
    - "git log"

toolsets:
  enabled: [core, web, delegation, code]

mcp:
  servers:
    - name: github
      command: npx
      args: ["@modelcontextprotocol/server-github"]

# 1. 開發新功能
> 幫我開發使用者 CRUD API，遵循 AGENTS.md 中的規範

# 2. 程式碼審查
> 請審查 git diff 中的變更，檢查安全性和效能

# 3. 測試補齊
> 幫 UserService 補齊單元測試，目標覆蓋率 90%

# 4. 自動化 PR
> 幫我建立 PR，標題遵循 Conventional Commits

# 5. 排程（每日定時）
> 每天早上 9 點執行 mvn verify，結果傳到 Slack

# SOUL.md
你是「小安」，XX 銀行的智慧客服助理。

## 性格特質
- 親切有禮、專業可靠
- 說話簡潔明瞭
- 遇到無法處理的問題，主動告知並轉接真人客服

## 限制
- 不能提供投資建議
- 不能洩漏其他客戶的資料
- 不能修改客戶帳戶（只能查詢）
- 敏感資訊必須遮蔽（帳號僅顯示末 4 碼）

## 語言
- 使用繁體中文
- 稱呼客戶為「您」

# bank-customer-service

## Description
銀行客服知識庫，處理客戶常見問題。

## FAQ Categories
1. **帳戶查詢**：餘額、交易記錄、對帳單
2. **信用卡**：帳單、繳費、掛失、額度
3. **匯款**：國內匯款、國際匯款、轉帳限額
4. **貸款**：房貸、信貸、車貸進度查詢
5. **其他**：營業時間、ATM 據點、網銀問題

## Escalation Rules
- 客戶連續 3 次表示不滿意 → 轉接真人
- 涉及交易爭議 → 轉接真人
- 涉及帳戶異常 → 轉接真人 + 通知風控

# 1. 每日報表（每天 08:00）
> 每天早上 8 點：
> - 查詢 PostgreSQL 取得昨日交易統計
> - 產生摘要報表（表格格式）
> - 傳送到 Telegram 群組和 Email

# 2. 系統監控（每小時）
> 每小時：
> - 檢查所有 K8s Pod 狀態
> - 檢查 DB connection pool
> - 檢查 API 回應時間
> - 如有異常，立即通知 Telegram

# 3. 部署前檢查（觸發式）
> 當收到 "部署檢查 [環境]" 訊息時：
> - 執行 mvn verify
> - 執行安全掃描（/bank-api-security-check）
> - 檢查 Jira 是否有未關閉的相關 Bug
> - 產出部署檢查報告

# XX銀行系統日報 - 2026/04/09

## 交易統計
| 類型 | 筆數 | 金額（萬元）|
|------|------|------------|
| 轉帳 | 12,345 | 45,678 |
| 匯款 | 1,234 | 23,456 |
| 刷卡 | 34,567 | 12,345 |

## 系統健康度
- API 可用率：99.97%
- 平均回應時間：45ms（P99: 200ms）
- 錯誤率：0.03%
- DB Connection Pool：65/100

## 安全事件
- ⚠️ 偵測到 3 次異常登入嘗試（已鎖定）
- ✅ CVE 掃描：無新漏洞

## 待處理項目
- JIRA-1234：修復對帳差異問題（High，已指派）
- JIRA-1235：優化查詢效能（Medium，待指派）

# config.yaml
model:
  provider: anthropic
  model: claude-sonnet-4-20250514

plugins:
  spotify:
    enabled: true
  comfyui:
    enabled: true
    endpoint: "http://localhost:8188"   # 本地 ComfyUI 伺服器
  touchdesigner:
    enabled: true

toolsets:
  enabled: [core, web, code, browser]

# 1. 生成行銷素材
> 幫我用 ComfyUI 生成一張企業年度報告的封面圖，
> 風格：科技感、藍色調、包含數據視覺化元素

# 2. 音樂配合
> 搜尋一首適合產品發布會的背景音樂，加到播放清單

# 3. 互動視覺
> 用 TouchDesigner 設計一個即時數據看板的原型

# 確認記憶設定
hermes config get memory.provider

# 手動觸發技能建立
> 請將剛才的操作流程封裝為一個技能

# 查看已有技能
/skills

# 查看記憶大小
du -sh ~/.hermes/memories/

# 壓縮 Session 資料庫
sqlite3 ~/.hermes/sessions.db "VACUUM;"

# 清理舊 Session
> 幫我清理 30 天前的 session 資料

# 如果使用 Vector DB，定期清理低相關性記憶
# mem0 / Supermemory 都有自動清理機制

# 錯誤：Stale OAuth credentials
hermes auth login nous   # 重新登入

# 錯誤：Model not found
/model                   # 查看可用模型清單

# 錯誤：402 Payment Required
# → 自動切換到 fallback provider
# → 或充值 API 額度

# 錯誤：Non-agentic model warning
# → 切換到支援 tool-use 的模型（如 Claude Sonnet / GPT-4o）

# 診斷工具
hermes doctor

# 1. 檢查 gateway 狀態
hermes gateway status

# 2. 查看日誌
hermes logs --filter "gateway"

# 3. 重啟 gateway
hermes gateway restart

# 4. 診斷
hermes doctor

# 5. 常見修復
# Telegram：檢查 BOT_TOKEN 是否正確
# Discord：確認 Bot 權限（不需要 members intent）
# Slack：確認 Event Subscription URL

# 方式 1：WSL2（企業推薦）
wsl --install
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# 方式 2：Native Windows（v0.16.0+ 正式支援）
irm https://hermes-agent.nousresearch.com/install.ps1 | iex
# 或安裝 Desktop App（官網下載 NSIS installer）
# 企業環境可選擇 WSL2 以獲得完整 Linux 工具鏈

# Hermes 支援 ACP（Agent Communication Protocol）
# 可與 VS Code / JetBrains / Zed 整合

# 在 VS Code 中使用 Hermes 作為 AI Agent：
# 1. 安裝 Hermes VS Code 擴展
# 2. 設定 ACP adapter
# 3. 即可在 IDE 中直接呼叫 Hermes

# 或者直接在 VS Code Terminal 中使用 hermes CLI

# 1. 確認 MCP 伺服器可用
npx @modelcontextprotocol/server-github --version

# 2. 確認環境變數已設定
echo $GITHUB_TOKEN

# 3. 檢查 OAuth 認證（v0.8.0）
# MCP OAuth 2.1 PKCE 需要瀏覽器互動

# 4. 檢查 OSV 掃描結果
# 如果套件有已知漏洞，Hermes 會阻擋安裝

# 1. 確認已啟用語音工具集
hermes tools enable voice

# 2. 確認 STT/TTS Provider 設定
hermes config get voice.stt_provider
hermes config get voice.tts_provider

# 3. 確認 API Key 已配置
# OpenAI Whisper → 需要 OPENAI_API_KEY
# Voxtral → 需要 MISTRAL_API_KEY
# ElevenLabs → 需要 ELEVENLABS_API_KEY

# 4. 確認麥克風權限（CLI Voice Mode）
# macOS: 系統偏好設定 → 隱私權 → 麥克風
# Linux: 確認 PulseAudio / PipeWire 正常

# 5. 診斷
hermes doctor

# 即時查看日誌
hermes logs

# 只看錯誤
hermes logs --errors

# 過濾特定關鍵字
hermes logs --filter "tool_call"
hermes logs --filter "memory"

# 日誌位置
~/.hermes/logs/agent.log     # INFO+ 級別
~/.hermes/logs/errors.log    # WARNING+ 級別

# 方式 1：使用不同 Profile
hermes --profile project-a
hermes --profile project-b

# 方式 2：在不同工作目錄啟動（會自動載入當前目錄的 AGENTS.md）
cd /path/to/project-a && hermes
cd /path/to/project-b && hermes

# 方式 3：使用 /new 重置對話但保留記憶
/new

# 保護重要技能
hermes skills pin my-important-skill

# 關閉 Curator
hermes config set auxiliary.curator.enabled false

# 檢查 Curator 最近的操作報告
cat ~/.hermes/logs/curator/REPORT.md

# -z 模式（非互動式，適合腳本與 CI/CD）
hermes -z "列出所有待修 bug"
# → 直接執行一次任務後退出，不進入 TUI
# → 不會記錄 session history
# → 可用 --model / --provider 指定模型

# 普通模式（互動式 TUI）
hermes
# → 進入持久對話，支援多輪互動
# → 記錄 session history
# → 支援所有 slash 指令

# 在對話中，將耗時任務移至背景
> 幫我對整個 src/ 目錄做安全掃描
/background    # 將此任務移至背景

# 繼續在主對話中工作
> 幫我修改 README.md

# 背景任務完成後會自動通知
# [Background] 安全掃描完成，發現 2 個中風險問題

# config.yaml
prompt_caching:
  cache_ttl: 300         # 預設 5 分鐘
  # cache_ttl: 3600      # 高頻使用場景可設為 1 小時
  # 適用於 System Prompt 不常變更的場景
  # 可有效降低重複 Token 消耗

# config.yaml
kanban:
  enabled: true
  max_concurrent: 4      # 同時運行的子代理數量
  auto_spawn: true        # 自動依任務生成子代理

# 使用 /kanban 查看看板狀態
/kanban

# 使用 /goal 設定持久化目標（Ralph Loop）
/goal 完成 API 重構並通過所有測試

# config.yaml
display:
  language: zh    # 繁體中文
  # 支援: zh, ja, de, es, fr, uk, tr

# 在對話中直接分析影片
> 請分析這段影片的內容：/path/to/video.mp4

# 支援格式：MP4、WebM 等常見格式
# 需要 LLM Provider 支援 Vision（如 Claude Sonnet、GPT-4o）

# Desktop App 設定
remote_gateway:
  url: "https://hermes-gateway.company.internal"
  auth: oauth2        # 或 password
  auto_reconnect: true