📄 user-guide/features/built-in-plugins.md

sidebar_position: 12 sidebar_label: "ปลั๊กอินในตัว" title: "ปลั๊กอินในตัว" description: "Plugins ที่มาพร้อมกับ Hermes Agent ซึ่งทำงานโดยอัตโนมัติผ่าน lifecycle hooks - เช่น disk-cleanup และอื่น ๆ"

ปลั๊กอินในตัว (Built-in Plugins)

Hermes มีชุดปลั๊กอินขนาดเล็กที่มาพร้อมกับ repository เหล่านี้ ปลั๊กอินเหล่านี้จะอยู่ใน <repo>/plugins/<name>/ และจะโหลดโดยอัตโนมัติพร้อมกับปลั๊กอินที่ผู้ใช้ติดตั้งใน ~/.hermes/plugins/ พวกมันใช้ plugin surface เดียวกันกับปลั๊กอินภายนอก ไม่ว่าจะเป็น hooks, tools, หรือ slash commands เพียงแต่ถูกดูแลรักษาแบบ in-tree

ดูที่หน้า Plugins สำหรับระบบปลั๊กอินโดยรวม และ Build a Hermes Plugin เพื่อเรียนรู้วิธีสร้างปลั๊กอินของคุณเอง

การค้นพบ (Discovery) ทำงานอย่างไร

PluginManager จะสแกนแหล่งที่มาสี่แห่งตามลำดับ:

1. Bundled - <repo>/plugins/<name>/ (ส่วนที่หน้านี้อธิบาย)
2. User - ~/.hermes/plugins/<name>/
3. Project - ./.hermes/plugins/<name>/ (ต้องตั้งค่า HERMES_ENABLE_PROJECT_PLUGINS=1)
4. Pip entry points - hermes_agent.plugins

หากเกิดการชนกันของชื่อ (name collision) แหล่งที่มาที่อยู่ภายหลังจะชนะเสมอ - ตัวอย่างเช่น ปลั๊กอินของผู้ใช้ชื่อ disk-cleanup จะมาแทนที่ปลั๊กอินที่ติดตั้งมาให้

plugins/memory/ และ plugins/context_engine/ ถูกยกเว้นจากการสแกนแบบ bundled โดยเจตนา เนื่องจาก memory providers และ context engines เป็น providers ที่เลือกได้เพียงตัวเดียวและถูกกำหนดค่าผ่าน hermes memory setup / context.engine ในไฟล์ config

ปลั๊กอินในตัวต้องเปิดใช้งาน (Opt-in)

ปลั๊กอินในตัวจะถูกติดตั้งมาในสถานะปิดใช้งาน (disabled) การค้นพบจะพบพวกมัน (จะปรากฏใน hermes plugins list และ UI แบบโต้ตอบ hermes plugins) แต่จะไม่มีปลั๊กอินใดโหลดขึ้นมาจนกว่าคุณจะเปิดใช้งานมันอย่างชัดเจน:

hermes plugins enable disk-cleanup

หรือผ่าน ~/.hermes/config.yaml:

plugins:
  enabled:
    - disk-cleanup

นี่คือกลไกเดียวกับที่ปลั๊กอินที่ผู้ใช้ติดตั้งใช้ ปลั๊กอินในตัวจะไม่ถูกเปิดใช้งานโดยอัตโนมัติเลย ไม่ว่าจะติดตั้งใหม่หรือสำหรับผู้ใช้เดิมที่อัปเกรดเป็น Hermes เวอร์ชันใหม่ คุณต้องเปิดใช้งานมันด้วยตนเองเสมอ

หากต้องการปิดปลั๊กอินในตัวอีกครั้ง:

hermes plugins disable disk-cleanup
# หรือ: ลบออกจาก plugins.enabled ใน config.yaml

ปลั๊กอินที่ติดตั้งมาให้ในปัจจุบัน

disk-cleanup

ติดตามและลบไฟล์ชั่วคราว (ephemeral files) ที่ถูกสร้างขึ้นระหว่างเซสชันโดยอัตโนมัติ - เช่น test scripts, temp outputs, cron logs, stale chrome profiles - โดยไม่จำเป็นต้องให้ agent จำได้ว่าต้องเรียกใช้ tool นี้

วิธีการทำงาน:

กฎการลบ:

Slash command - /disk-cleanup สามารถใช้ได้ทั้งใน CLI และ gateway sessions:

/disk-cleanup status                     # สรุป + 10 รายการที่ใหญ่ที่สุด
/disk-cleanup dry-run                    # ดูตัวอย่างโดยไม่ลบ
/disk-cleanup quick                      # ทำการล้างข้อมูลแบบปลอดภัยทันที
/disk-cleanup deep                       # quick + แสดงรายการที่ต้องยืนยัน
/disk-cleanup track <path> <category>    # ติดตามด้วยตนเอง
/disk-cleanup forget <path>              # หยุดติดตาม (ไม่ลบ)

State - ทุกอย่างอยู่ใน $HERMES_HOME/disk-cleanup/:

ความปลอดภัย - การล้างข้อมูลจะแตะเฉพาะ paths ที่อยู่ภายใต้ HERMES_HOME หรือ /tmp/hermes-* เท่านั้น Windows mounts (/mnt/c/...) จะถูกปฏิเสธ โฟลเดอร์ state ระดับบนที่ทราบกันดี (logs/, memories/, sessions/, cron/, cache/, skills/, plugins/, disk-cleanup/ เอง) จะไม่ถูกลบแม้ว่าจะว่างเปล่าก็ตาม - การติดตั้งใหม่จะไม่ถูกล้างข้อมูลทั้งหมดตั้งแต่เซสชันแรกที่จบลง

การเปิดใช้งาน: hermes plugins enable disk-cleanup (หรือทำเครื่องหมายใน hermes plugins)

การปิดใช้งานอีกครั้ง: hermes plugins disable disk-cleanup

การเพิ่มปลั๊กอินในตัว

ปลั๊กอินในตัวถูกเขียนขึ้นเหมือนกับปลั๊กอิน Hermes อื่น ๆ ทั้งหมด - ดูที่ Build a Hermes Plugin ความแตกต่างเพียงอย่างเดียวคือ:

• Directory อยู่ที่ <repo>/plugins/<name>/ แทนที่จะเป็น ~/.hermes/plugins/<name>/
• Manifest source จะรายงานเป็น bundled ใน hermes plugins list
• ปลั๊กอินของผู้ใช้ที่มีชื่อเดียวกันจะเขียนทับเวอร์ชันที่ติดตั้งมาให้

ปลั๊กอินจะเหมาะสมสำหรับการรวมเป็น bundled เมื่อ:

• ไม่มี optional dependencies (หรือเป็น deps ที่ติดตั้งด้วย pip install .[all])
• พฤติกรรมนั้นเป็นประโยชน์ต่อผู้ใช้ส่วนใหญ่และเป็นแบบ opt-out มากกว่า opt-in
• ตรรกะมีการเชื่อมโยงกับ lifecycle hooks ที่โดยปกติแล้ว agent จะต้องจำได้ว่าจะต้องเรียกใช้
• มันเสริมความสามารถหลักโดยไม่ขยาย tool surface ที่ model มองเห็น

ตัวอย่างที่ควรเป็นปลั๊กอินที่ติดตั้งได้โดยผู้ใช้ ไม่ใช่ bundled: การรวมระบบภายนอกที่ใช้ API keys, workflow เฉพาะทาง, dependency trees ขนาดใหญ่, หรืออะไรก็ตามที่เปลี่ยนแปลงพฤติกรรมของ agent อย่างมีนัยสำคัญโดยค่าเริ่มต้น

📄 user-guide/features/code-execution.md

sidebar_position: 8 title: "Code Execution" description: "Programmatic Python execution with RPC tool access - collapse multi-step workflows into a single turn"

Code Execution (Programmatic Tool Calling)

เครื่องมือ execute_code ช่วยให้ agent สามารถเขียนสคริปต์ Python ที่เรียกใช้เครื่องมือของ Hermes ในรูปแบบ programmatic ซึ่งเป็นการรวมเวิร์กโฟลว์หลายขั้นตอนให้เหลือเพียงรอบเดียวของ LLM สคริปต์จะทำงานใน child process บน host ของ agent และสื่อสารกับ Hermes ผ่าน RPC บน Unix domain socket

วิธีการทำงาน

1. agent เขียนสคริปต์ Python โดยใช้ from hermes_tools import ...
2. Hermes สร้างโมดูล stub ชื่อ hermes_tools.py พร้อมฟังก์ชัน RPC
3. Hermes เปิด Unix domain socket และเริ่ม thread สำหรับการรับฟัง RPC
4. สคริปต์ทำงานใน child process - การเรียกใช้เครื่องมือจะเดินทางผ่าน socket กลับไปยัง Hermes
5. มีเพียงผลลัพธ์จาก print() ของสคริปต์เท่านั้นที่จะถูกส่งกลับไปยัง LLM; ผลลัพธ์ของเครื่องมือระหว่างทางจะไม่เข้าสู่ context window

# The agent can write scripts like:
from hermes_tools import web_search, web_extract

results = web_search("Python 3.13 features", limit=5)
for r in results["data"]["web"]:
    content = web_extract([r["url"]])
    # ... filter and process ...
print(summary)

เครื่องมือที่พร้อมใช้งานภายในสคริปต์: web_search, web_extract, read_file, write_file, search_files, patch, terminal (foreground เท่านั้น).

เมื่อ agent ใช้สิ่งนี้

agent จะใช้ execute_code เมื่อมี:

• การเรียกใช้เครื่องมือ 3+ ครั้ง พร้อมตรรกะในการประมวลผลระหว่างกัน
• การกรองข้อมูลจำนวนมาก หรือการแตกกิ่งแบบมีเงื่อนไข
• ลูป (Loops) เหนือผลลัพธ์

ประโยชน์หลัก: ผลลัพธ์ของเครื่องมือระหว่างทางจะไม่เข้าสู่ context window - มีเพียงผลลัพธ์ print() สุดท้ายเท่านั้นที่ส่งกลับมา ซึ่งช่วยลดการใช้ token ได้อย่างมาก

ตัวอย่างการใช้งานจริง

Data Processing Pipeline

from hermes_tools import search_files, read_file
import json

# ค้นหาไฟล์ config ทั้งหมดและดึงการตั้งค่าฐานข้อมูล
matches = search_files("database", path=".", file_glob="*.yaml", limit=20)
configs = []
for match in matches.get("matches", []):
    content = read_file(match["path"])
    configs.append({"file": match["path"], "preview": content["content"][:200]})

print(json.dumps(configs, indent=2))

Multi-Step Web Research

from hermes_tools import web_search, web_extract
import json

# ค้นหา, ดึงข้อมูล, และสรุปในรอบเดียว
results = web_search("Rust async runtime comparison 2025", limit=5)
summaries = []
for r in results["data"]["web"]:
    page = web_extract([r["url"]])
    for p in page.get("results", []):
        if p.get("content"):
            summaries.append({
                "title": r["title"],
                "url": r["url"],
                "excerpt": p["content"][:500]
            })

print(json.dumps(summaries, indent=2))

Bulk File Refactoring

from hermes_tools import search_files, read_file, patch

# ค้นหาไฟล์ Python ทั้งหมดที่ใช้ API ที่เลิกใช้แล้วและแก้ไขให้ถูกต้อง
matches = search_files("old_api_call", path="src/", file_glob="*.py")
fixed = 0
for match in matches.get("matches", []):
    result = patch(
        path=match["path"],
        old_string="old_api_call(",
        new_string="new_api_call(",
        replace_all=True
    )
    if "error" not in str(result):
        fixed += 1

print(f"Fixed {fixed} files out of {len(matches.get('matches', []))} matches")

Build and Test Pipeline

from hermes_tools import terminal, read_file
import json

# รัน tests, parse ผลลัพธ์, และรายงาน
result = terminal("cd /project && python -m pytest --tb=short -q 2>&1", timeout=120)
output = result.get("output", "")

# Parse ผลลัพธ์การทดสอบ
passed = output.count(" passed")
failed = output.count(" failed")
errors = output.count(" error")

report = {
    "passed": passed,
    "failed": failed,
    "errors": errors,
    "exit_code": result.get("exit_code", -1),
    "summary": output[-500:] if len(output) > 500 else output
}

print(json.dumps(report, indent=2))

Execution Mode

execute_code มีโหมดการทำงานสองโหมดที่ควบคุมโดย code_execution.mode ในไฟล์ ~/.hermes/config.yaml:

เมื่อใดที่ควรใช้ project: เมื่อคุณต้องการให้ import pandas, from my_project import foo, หรือ relative paths เช่น open(".env") ทำงานได้เหมือนกับที่ทำใน terminal(). นี่คือสิ่งที่คุณต้องการเกือบทุกครั้ง

เมื่อใดที่ควรเปลี่ยนเป็น strict: เมื่อคุณต้องการความสามารถในการทำซ้ำสูงสุด (maximum reproducibility) - คุณต้องการ interpreter ตัวเดิมทุก session ไม่ว่าผู้ใช้จะ activate venv ใด และคุณต้องการให้สคริปต์ถูกกักกันจาก project tree (ไม่มีความเสี่ยงที่จะอ่านไฟล์ project ผ่าน relative path โดยไม่ได้ตั้งใจ)

# ~/.hermes/config.yaml
code_execution:
  mode: project   # หรือ "strict"

พฤติกรรม fallback ในโหมด project: หาก VIRTUAL_ENV / CONDA_PREFIX ไม่ได้ถูกตั้งค่า, เสียหาย, หรือชี้ไปยัง Python ที่เก่ากว่า 3.8, resolver จะ fallback ไปยัง sys.executable อย่างราบรื่น - มันจะไม่ทิ้ง agent โดยไม่มี interpreter ที่ใช้งานได้

Invariant ที่สำคัญด้านความปลอดภัยเหมือนกันทั้งสองโหมด:

• environment scrubbing (ลบ API keys, tokens, credentials)
• tool whitelist (สคริปต์ไม่สามารถเรียกใช้ execute_code ซ้ำ, delegate_task, หรือเครื่องมือ MCP)
• resource limits (timeout, stdout cap, tool-call cap)

การเปลี่ยนโหมดจะเปลี่ยนว่าสคริปต์ทำงานที่ไหนและ interpreter ตัวใดที่รันมัน ไม่ใช่ว่า credentials ใดที่มันมองเห็นหรือเครื่องมือใดที่มันเรียกใช้ได้

Resource Limits

ขีดจำกัดทั้งหมดสามารถกำหนดค่าได้ผ่าน config.yaml:

# In ~/.hermes/config.yaml
code_execution:
  mode: project      # project (default) | strict
  timeout: 300       # Max seconds per script (default: 300)
  max_tool_calls: 50 # Max tool calls per execution (default: 50)

How Tool Calls Work Inside Scripts

เมื่อสคริปต์ของคุณเรียกใช้ฟังก์ชันเช่น web_search("query"):

1. การเรียกใช้จะถูก serialize เป็น JSON และส่งผ่าน Unix domain socket ไปยัง parent process
2. parent จะ dispatch ผ่าน handler มาตรฐาน handle_function_call
3. ผลลัพธ์จะถูกส่งกลับผ่าน socket
4. ฟังก์ชันจะส่งคืนผลลัพธ์ที่ถูก parse แล้ว

นั่นหมายความว่าการเรียกใช้เครื่องมือภายในสคริปต์มีพฤติกรรมเหมือนกับการเรียกใช้เครื่องมือปกติ - มี rate limits เดียวกัน, การจัดการ error เดียวกัน, และความสามารถเดียวกัน ข้อจำกัดเดียวคือ terminal() เป็นแบบ foreground-only (ไม่มีพารามิเตอร์ background หรือ pty)

Error Handling

เมื่อสคริปต์ล้มเหลว, agent จะได้รับข้อมูล error ที่มีโครงสร้าง:

• Non-zero exit code: stderr จะถูกรวมอยู่ใน output เพื่อให้ agent เห็น traceback ทั้งหมด
• Timeout: สคริปต์จะถูก kill และ agent จะเห็นข้อความ "Script timed out after 300s and was killed."
• Interruption: หากผู้ใช้ส่งข้อความใหม่ระหว่างการทำงาน, สคริปต์จะถูกยุติ และ agent จะเห็น [execution interrupted - user sent a new message]
• Tool call limit: เมื่อถึงขีดจำกัด 50 ครั้ง, การเรียกใช้เครื่องมือครั้งถัดไปจะส่ง error message กลับมา

การตอบกลับจะรวม status (success/error/timeout/interrupted), output, tool_calls_made, และ duration_seconds เสมอ

Security

:::danger Security Model child process ทำงานด้วย minimal environment API keys, tokens, และ credentials จะถูกลบออกโดยค่าเริ่มต้น สคริปต์จะเข้าถึงเครื่องมือผ่านช่องทาง RPC เท่านั้น - มันไม่สามารถอ่าน secrets จาก environment variables ได้ เว้นแต่จะได้รับอนุญาตอย่างชัดเจน :::

Environment variables ที่มี KEY, TOKEN, SECRET, PASSWORD, CREDENTIAL, PASSWD, หรือ AUTH ในชื่อ จะถูกยกเว้น มีเพียง system variables ที่ปลอดภัยเท่านั้น (PATH, HOME, LANG, SHELL, PYTHONPATH, VIRTUAL_ENV, ฯลฯ) เท่านั้นที่จะถูกส่งผ่าน

Skill Environment Variable Passthrough

เมื่อ skill ประกาศ required_environment_variables ใน frontmatter ของมัน, ตัวแปรเหล่านั้นจะถูก ส่งผ่านโดยอัตโนมัติ ไปยัง child processes ทั้ง execute_code และ terminal หลังจากที่ skill ถูกโหลด สิ่งนี้ช่วยให้ skill สามารถใช้ API keys ที่ประกาศได้โดยไม่ลดความปลอดภัยสำหรับโค้ดทั่วไป

สำหรับกรณีที่ไม่ใช่ skill, คุณสามารถอนุญาตให้ variables ได้อย่างชัดเจนใน config.yaml:

terminal:
  env_passthrough:
    - MY_CUSTOM_KEY
    - ANOTHER_TOKEN

ดู Security guide สำหรับรายละเอียดทั้งหมด

Hermes จะเขียนสคริปต์และ stub RPC hermes_tools.py ที่สร้างขึ้นโดยอัตโนมัติไปยัง temp staging directory ซึ่งจะถูกล้างออกหลังจากการทำงาน ในโหมด strict สคริปต์จะ รัน ที่นั่นด้วย; ในโหมด project มันจะรันใน working directory ของ session (staging directory ยังคงอยู่ใน PYTHONPATH ดังนั้นการ import จึงยังคง resolve ได้) child process ทำงานใน process group ของตัวเองเพื่อให้สามารถถูก kill ได้อย่างสะอาดเมื่อหมดเวลาหรือถูกขัดจังหวะ

execute_code vs terminal

หลักการง่ายๆ: ใช้ execute_code เมื่อคุณต้องการเรียกใช้เครื่องมือของ Hermes ในรูปแบบ programmatic พร้อมตรรกะระหว่างการเรียกใช้ ใช้ terminal สำหรับการรัน shell commands, builds, และ processes

Platform Support

Code execution ต้องการ Unix domain sockets และใช้งานได้เฉพาะบน Linux และ macOS เท่านั้น โดยจะถูกปิดใช้งานโดยอัตโนมัติบน Windows - agent จะ fallback ไปใช้การเรียกใช้เครื่องมือแบบ sequential ปกติ

📄 user-guide/features/context-files.md

sidebar_position: 8 title: "Context Files" description: "ไฟล์ context ของโปรเจกต์ - .hermes.md, AGENTS.md, CLAUDE.md, SOUL.md ทั่วโลก, และ .cursorrules - จะถูกฉีด (injected) เข้าไปในทุก conversation โดยอัตโนมัติ"

Context Files

Hermes Agent จะค้นหาและโหลด context files ที่กำหนดพฤติกรรมของมันโดยอัตโนมัติ ไฟล์บางส่วนเป็นแบบ local ของโปรเจกต์และจะถูกค้นพบจาก working directory ของคุณ ส่วน SOUL.md ถูกกำหนดให้เป็น global สำหรับ instance ของ Hermes และจะถูกโหลดจาก HERMES_HOME เท่านั้น

Supported Context Files

:::info ระบบลำดับความสำคัญ จะมีการโหลด context type ของโปรเจกต์ได้เพียง หนึ่ง อย่างต่อ session (ใช้แบบที่เจอเป็นอันแรก): .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules ส่วน SOUL.md จะถูกโหลดอย่างอิสระเสมอในฐานะ identity ของ agent (slot #1). :::

AGENTS.md

AGENTS.md คือไฟล์ context หลักของโปรเจกต์ มันจะบอก agent ว่าโปรเจกต์ของคุณมีโครงสร้างอย่างไร, ต้องปฏิบัติตาม convention อะไร, และคำสั่งพิเศษใดๆ

Progressive Subdirectory Discovery

เมื่อเริ่ม session, Hermes จะโหลด AGENTS.md จาก working directory ของคุณเข้าสู่ system prompt ขณะที่ agent เดินทางเข้าไปใน subdirectories ระหว่าง session (ผ่าน read_file, terminal, search_files, ฯลฯ), มันจะ ค้นพบอย่างต่อเนื่อง (progressively discovers) context files ในไดเรกทอรีเหล่านั้นและฉีดมันเข้าสู่ conversation ในขณะที่มันมีความเกี่ยวข้อง

my-project/
├── AGENTS.md              ← โหลดเมื่อเริ่มต้น (system prompt)
├── frontend/
│   └── AGENTS.md          ← ค้นพบเมื่อ agent อ่านไฟล์ใน frontend/
├── backend/
│   └── AGENTS.md          ← ค้นพบเมื่อ agent อ่านไฟล์ใน backend/
└── shared/
    └── AGENTS.md          ← ค้นพบเมื่อ agent อ่านไฟล์ใน shared/

แนวทางนี้มีข้อดีสองอย่างเมื่อเทียบกับการโหลดทุกอย่างตั้งแต่เริ่มต้น:

• ไม่มี system prompt bloat - คำแนะนำของ subdirectory จะปรากฏเมื่อจำเป็นเท่านั้น
• Prompt cache preservation - system prompt จะคงที่ตลอดการสนทนา

แต่ละ subdirectory จะถูกตรวจสอบได้สูงสุดครั้งละหนึ่งครั้งต่อ session นอกจากนี้ การค้นหายังจะเดินขึ้นไปยัง parent directories ด้วย ดังนั้นการอ่าน backend/src/main.py จะค้นพบ backend/AGENTS.md แม้ว่า backend/src/ จะไม่มี context file ของตัวเองก็ตาม

:::info context files ของ subdirectory จะผ่าน security scan เช่นเดียวกับ context files ตอนเริ่มต้น ไฟล์ที่เป็นอันตรายจะถูกบล็อก :::

Example AGENTS.md

# Project Context

This is a Next.js 14 web application with a Python FastAPI backend.

## Architecture
- Frontend: Next.js 14 with App Router in `/frontend`
- Backend: FastAPI in `/backend`, uses SQLAlchemy ORM
- Database: PostgreSQL 16
- Deployment: Docker Compose on a Hetzner VPS

## Conventions
- Use TypeScript strict mode for all frontend code
- Python code follows PEP 8, use type hints everywhere
- All API endpoints return JSON with `{data, error, meta}` shape
- Tests go in `__tests__/` directories (frontend) or `tests/` (backend)

## Important Notes
- Never modify migration files directly - use Alembic commands
- The `.env.local` file has real API keys, don't commit it
- Frontend port is 3000, backend is 8000, DB is 5432

SOUL.md

SOUL.md ควบคุมบุคลิกภาพ, โทนเสียง, และรูปแบบการสื่อสารของ agent ดูรายละเอียดทั้งหมดได้ที่หน้า Personality

Location:

• ~/.hermes/SOUL.md
• หรือ $HERMES_HOME/SOUL.md หากคุณรัน Hermes ด้วย custom home directory

รายละเอียดที่สำคัญ:

• Hermes จะสร้างค่าเริ่มต้นของ SOUL.md โดยอัตโนมัติหากยังไม่มี
• Hermes จะโหลด SOUL.md จาก HERMES_HOME เท่านั้น
• Hermes จะไม่ตรวจสอบ working directory สำหรับ SOUL.md
• หากไฟล์ว่างเปล่า จะไม่มีอะไรจาก SOUL.md ถูกเพิ่มเข้าไปใน prompt
• หากไฟล์มีเนื้อหา เนื้อหานั้นจะถูกฉีดเข้าไปตามตัวอักษรหลังจากสแกนและตัดทอน

.cursorrules

Hermes รองรับไฟล์ .cursorrules และโมดูลกฎ .cursor/rules/*.mdc ของ Cursor IDE หากไฟล์เหล่านี้มีอยู่ใน root ของโปรเจกต์ของคุณและไม่พบ context file ที่มีลำดับความสำคัญสูงกว่า (เช่น .hermes.md, AGENTS.md, หรือ CLAUDE.md) พวกมันจะถูกโหลดเป็น project context

นั่นหมายความว่า convention ของ Cursor ที่คุณมีอยู่จะถูกนำมาใช้โดยอัตโนมัติเมื่อใช้ Hermes

How Context Files Are Loaded

At startup (system prompt)

Context files ถูกโหลดโดย build_context_files_prompt() ใน agent/prompt_builder.py:

1. Scan working directory - ตรวจสอบ .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules (ใช้แบบที่เจอเป็นอันแรก)
2. Content is read - แต่ละไฟล์จะถูกอ่านเป็นข้อความ UTF-8
3. Security scan - เนื้อหาจะถูกตรวจสอบหา pattern ของ prompt injection
4. Truncation - ไฟล์ที่เกิน 20,000 characters จะถูกตัดทอนแบบ head/tail (70% head, 20% tail, พร้อม marker ตรงกลาง)
5. Assembly - ส่วนทั้งหมดจะถูกรวมภายใต้ header # Project Context
6. Injection - เนื้อหาที่ประกอบเสร็จแล้วจะถูกเพิ่มเข้าไปใน system prompt

During the session (progressive discovery)

SubdirectoryHintTracker ใน agent/subdirectory_hints.py จะเฝ้าดู tool call arguments สำหรับ file paths:

1. Path extraction - หลังจากการเรียกใช้ tool แต่ละครั้ง จะมีการดึง file paths ออกมาจาก arguments (path, workdir, shell commands)
2. Ancestor walk - จะมีการตรวจสอบไดเรกทอรีและ parent directories สูงสุด 5 ระดับ (หยุดที่ไดเรกทอรีที่เคยเข้าชมแล้ว)
3. Hint loading - หากพบ AGENTS.md, CLAUDE.md, หรือ .cursorrules จะถูกโหลด (ใช้แบบที่เจอเป็นอันแรกต่อไดเรกทอรี)
4. Security scan - การสแกน prompt injection แบบเดียวกับไฟล์ตอนเริ่มต้น
5. Truncation - จำกัดที่ 8,000 characters ต่อไฟล์
6. Injection - ถูกเพิ่มต่อท้าย tool result เพื่อให้ model เห็นใน context อย่างเป็นธรรมชาติ

ส่วน prompt สุดท้ายจะมีลักษณะประมาณนี้:

# Project Context

The following project context files have been loaded and should be followed:

## AGENTS.md

[Your AGENTS.md content here]

## .cursorrules

[Your .cursorrules content here]

[Your SOUL.md content here]

สังเกตว่าเนื้อหา SOUL ถูกแทรกโดยตรง โดยไม่มีข้อความ wrapper เพิ่มเติม

Security: Prompt Injection Protection

context files ทั้งหมดจะถูกสแกนหา potential prompt injection ก่อนที่จะถูกรวมเข้ามา Scanner จะตรวจสอบหา:

• Instruction override attempts: "ignore previous instructions", "disregard your rules"
• Deception patterns: "do not tell the user"
• System prompt overrides: "system prompt override"
• Hidden HTML comments: <!-- ignore instructions -->
• Hidden div elements: <div style="display:none">
• Credential exfiltration: curl ... $API_KEY
• Secret file access: cat .env, cat credentials
• Invisible characters: zero-width spaces, bidirectional overrides, word joiners

หากตรวจพบ threat pattern ใดๆ ไฟล์นั้นจะถูกบล็อก:

[BLOCKED: AGENTS.md contained potential prompt injection (prompt_injection). Content not loaded.]

:::warning Scanner นี้ป้องกัน against common injection patterns แต่ไม่สามารถแทนที่การตรวจสอบ context files ใน shared repositories ได้ ควรตรวจสอบเนื้อหาของ AGENTS.md ในโปรเจกต์ที่คุณไม่ได้เป็นผู้สร้างเสมอ :::

Size Limits

เมื่อไฟล์เกิน 20,000 characters ข้อความ truncation จะแสดงว่า:

[...truncated AGENTS.md: kept 14000+4000 of 25000 chars. Use file tools to read the full file.]

Tips for Effective Context Files

:::tip แนวทางปฏิบัติที่ดีที่สุดสำหรับ AGENTS.md

1. Keep it concise - ควรอยู่ต่ำกว่า 20K chars มากๆ เพราะ agent อ่านมันทุก turn
2. Structure with headers - ใช้ส่วน ## สำหรับ architecture, conventions, important notes
3. Include concrete examples - แสดง preferred code patterns, API shapes, naming conventions
4. Mention what NOT to do - เช่น "never modify migration files directly"
5. List key paths and ports - agent ใช้สิ่งเหล่านี้สำหรับ terminal commands
6. Update as the project evolves - context ที่ล้าสมัยแย่กว่าไม่มี context :::

Per-Subdirectory Context

สำหรับ monorepos ให้ใส่คำแนะนำเฉพาะ subdirectory ในไฟล์ AGENTS.md ที่ซ้อนกัน:

<!-- frontend/AGENTS.md -->
# Frontend Context

- Use `pnpm` not `npm` for package management
- Components go in `src/components/`, pages in `src/app/`
- Use Tailwind CSS, never inline styles
- Run tests with `pnpm test`

<!-- backend/AGENTS.md -->
# Backend Context

- Use `poetry` for dependency management
- Run the dev server with `poetry run uvicorn main:app --reload`
- All endpoints need OpenAPI docstrings
- Database models are in `models/`, schemas in `schemas/`

📄 user-guide/features/context-references.md

sidebar_position: 9 sidebar_label: "Context References" title: "Context References" description: "Inline @-syntax for attaching files, folders, git diffs, and URLs directly into your messages"

Context References

ให้พิมพ์ @ ตามด้วยการอ้างอิงเพื่อแทรกเนื้อหาลงในข้อความของคุณโดยตรง Hermes จะขยายการอ้างอิงนั้นในรูปแบบ inline และแนบเนื้อหาไว้ภายใต้ส่วน --- Attached Context ---

การอ้างอิงที่รองรับ (Supported References)

ตัวอย่างการใช้งาน (Usage Examples)

Review @file:src/main.py and suggest improvements

What changed? @diff

Compare @file:old_config.yaml and @file:new_config.yaml

What's in @folder:src/components?

Summarize this article @url:https://arxiv.org/abs/2301.00001

การอ้างอิงหลายรายการสามารถใช้งานได้ในข้อความเดียว:

Check @file:main.py, and also @file:test.py.

เครื่องหมายวรรคตอนที่อยู่ท้าย (เช่น ,, ., ;, !, ?) จะถูกลบออกโดยอัตโนมัติจากค่าการอ้างอิง

การเติมคำอัตโนมัติใน CLI (CLI Tab Completion)

ใน CLI แบบโต้ตอบ การพิมพ์ @ จะกระตุ้นการเติมคำอัตโนมัติ:

• @ แสดงประเภทการอ้างอิงทั้งหมด (@diff, @staged, @file:, @folder:, @git:, @url:)
• @file: และ @folder: จะกระตุ้นการเติมคำอัตโนมัติของ path ระบบไฟล์พร้อมเมตาดาต้าขนาดไฟล์
• การใช้ @ อย่างเดียวตามด้วยข้อความบางส่วน จะแสดงไฟล์และโฟลเดอร์ที่ตรงกันจากไดเรกทอรีปัจจุบัน

ช่วงบรรทัด (Line Ranges)

การอ้างอิง @file: รองรับช่วงบรรทัดสำหรับการแทรกเนื้อหาที่แม่นยำ:

@file:src/main.py:42        # บรรทัดเดียวที่ 42
@file:src/main.py:10-25     # บรรทัดที่ 10 ถึง 25 (รวม)

บรรทัดจะนับแบบ 1-indexed ช่วงที่ไม่ถูกต้องจะถูกละเลยโดยเงียบ (จะส่งคืนไฟล์ทั้งหมด)

ข้อจำกัดขนาด (Size Limits)

การอ้างอิงบริบทถูกจำกัดเพื่อป้องกันไม่ให้เกินขีดจำกัด context window ของ model:

ความปลอดภัย (Security)

การบล็อก Path ที่ละเอียดอ่อน (Sensitive Path Blocking)

Path เหล่านี้จะถูกบล็อกเสมอจากการอ้างอิง @file: เพื่อป้องกันการเปิดเผย credential:

• SSH keys and config: ~/.ssh/id_rsa, ~/.ssh/id_ed25519, ~/.ssh/authorized_keys, ~/.ssh/config
• Shell profiles: ~/.bashrc, ~/.zshrc, ~/.profile, ~/.bash_profile, ~/.zprofile
• Credential files: ~/.netrc, ~/.pgpass, ~/.npmrc, ~/.pypirc
• Hermes env: $HERMES_HOME/.env

ไดเรกทอรีเหล่านี้ถูกบล็อกโดยสมบูรณ์ (ไฟล์ใดๆ ที่อยู่ภายใน):

• ~/.ssh/, ~/.aws/, ~/.gnupg/, ~/.kube/, $HERMES_HOME/skills/.hub/

การป้องกัน Path Traversal (Path Traversal Protection)

Path ทั้งหมดจะถูกแก้ไขโดยอ้างอิงจาก working directory การอ้างอิงที่แก้ไขอยู่นอก root ของ workspace ที่อนุญาตจะถูกปฏิเสธ

การตรวจจับไฟล์ไบนารี (Binary File Detection)

ไฟล์ไบนารีจะถูกตรวจจับผ่าน MIME type และการสแกน null-byte ส่วนขยายข้อความที่ทราบ (.py, .md, .json, .yaml, .toml, .js, .ts, ฯลฯ) จะข้ามการตรวจจับที่อิงจาก MIME ไฟล์ไบนารีจะถูกปฏิเสธพร้อมคำเตือน

ความพร้อมใช้งานของแพลตฟอร์ม (Platform Availability)

Context references เป็นฟีเจอร์หลักของ CLI โดยเฉพาะ มันทำงานใน CLI แบบโต้ตอบที่ @ กระตุ้นการเติมคำอัตโนมัติ และการอ้างอิงจะถูกขยายก่อนที่ข้อความจะถูกส่งไปยัง agent

ใน messaging platforms (เช่น Telegram, Discord) ไวยากรณ์ @ จะไม่ถูกขยายโดย gateway - ข้อความจะถูกส่งผ่านไปตามเดิม ตัว agent เองยังสามารถอ้างอิงไฟล์ได้ผ่านเครื่องมือ read_file, search_files, และ web_extract

การทำงานร่วมกับการบีบอัดบริบท (Interaction with Context Compression)

เมื่อบริบทการสนทนาถูกบีบอัด เนื้อหาการอ้างอิงที่ขยายแล้วจะถูกรวมอยู่ในสรุปการบีบอัด ซึ่งหมายความว่า:

• เนื้อหาไฟล์ขนาดใหญ่ที่แทรกผ่าน @file: จะนับเป็นส่วนหนึ่งของการใช้ context
• หากมีการบีบอัดการสนทนาในภายหลัง เนื้อหาไฟล์จะถูกสรุป (ไม่ได้เก็บรักษาแบบ verbatim)
• สำหรับไฟล์ขนาดใหญ่มาก ให้พิจารณาใช้ช่วงบรรทัด (@file:main.py:100-200) เพื่อแทรกเฉพาะส่วนที่เกี่ยวข้อง

รูปแบบทั่วไป (Common Patterns)

# Code review workflow
Review @diff and check for security issues

# Debug with context
This test is failing. Here's the test @file:tests/test_auth.py
and the implementation @file:src/auth.py:50-80

# Project exploration
What does this project do? @folder:src @file:README.md

# Research
Compare the approaches in @url:https://arxiv.org/abs/2301.00001
and @url:https://arxiv.org/abs/2301.00002

การจัดการข้อผิดพลาด (Error Handling)

การอ้างอิงที่ไม่ถูกต้องจะสร้างคำเตือนแบบ inline แทนที่จะเกิดความล้มเหลว:

📄 user-guide/features/credential-pools.md

title: Credential Pools description: Pool multiple API keys or OAuth tokens per provider for automatic rotation and rate limit recovery. sidebar_label: Credential Pools sidebar_position: 9

Credential Pools

Credential pools ช่วยให้คุณสามารถลงทะเบียน API keys หรือ OAuth tokens หลายรายการสำหรับ Provider เดียวกัน เมื่อคีย์ใดคีย์หนึ่งถึง rate limit หรือ billing quota, Hermes จะทำการ rotate ไปยังคีย์ที่ใช้งานได้รายการถัดไปโดยอัตโนมัติ ซึ่งช่วยให้เซสชันของคุณยังคงอยู่ได้โดยไม่ต้องสลับ Provider

สิ่งนี้แตกต่างจาก fallback providers ซึ่งจะสลับไปใช้ Provider อื่น โดยสิ้นเชิง Credential pools คือการหมุนเวียนภายใน Provider เดียวกัน ส่วน fallback providers คือการ failover ข้าม Provider Pools จะถูกลองใช้ก่อน - หากคีย์ทั้งหมดใน pool ถูกใช้จนหมด, จึง fallback provider จะทำงาน

How It Works

Your request
  → Pick key from pool (round_robin / least_used / fill_first / random)
  → Send to provider
  → 429 rate limit?
      → Retry same key once (transient blip)
      → Second 429 → rotate to next pool key
      → All keys exhausted → fallback_model (different provider)
  → 402 billing error?
      → Immediately rotate to next pool key (24h cooldown)
  → 401 auth expired?
      → Try refreshing the token (OAuth)
      → Refresh failed → rotate to next pool key
  → Success → continue normally

Quick Start

หากคุณมี API key ที่ตั้งค่าไว้ใน .env อยู่แล้ว, Hermes จะค้นพบโดยอัตโนมัติว่าเป็น pool ที่มี 1 key หากต้องการใช้ประโยชน์จากการ pooling, ให้เพิ่มคีย์เพิ่มเติม:

# Add a second OpenRouter key
hermes auth add openrouter --api-key sk-or-v1-your-second-key

# Add a second Anthropic key
hermes auth add anthropic --type api-key --api-key sk-ant-api03-your-second-key

# Add an Anthropic OAuth credential (Claude Code subscription)
hermes auth add anthropic --type oauth
# Opens browser for OAuth login

ตรวจสอบ pools ของคุณ:

hermes auth list

Output:

openrouter (2 credentials):
  #1  OPENROUTER_API_KEY   api_key env:OPENROUTER_API_KEY ←
  #2  backup-key           api_key manual

anthropic (3 credentials):
  #1  hermes_pkce          oauth   hermes_pkce ←
  #2  claude_code          oauth   claude_code
  #3  ANTHROPIC_API_KEY    api_key env:ANTHROPIC_API_KEY

← แสดงถึง credential ที่ถูกเลือกใช้งานอยู่ในปัจจุบัน

Interactive Management

เรียกใช้ hermes auth โดยไม่มี subcommand เพื่อเข้าสู่ interactive wizard:

hermes auth

สิ่งนี้จะแสดงสถานะ pool ทั้งหมดของคุณและเสนอเมนู:

What would you like to do?
  1. Add a credential
  2. Remove a credential
  3. Reset cooldowns for a provider
  4. Set rotation strategy for a provider
  5. Exit

สำหรับ Provider ที่รองรับทั้ง API keys และ OAuth (Anthropic, Nous, Codex), ขั้นตอนการเพิ่มจะถามว่าต้องการประเภทใด:

anthropic supports both API keys and OAuth login.
  1. API key (paste a key from the provider dashboard)
  2. OAuth login (authenticate via browser)
Type [1/2]:

CLI Commands

Rotation Strategies

ตั้งค่าผ่าน hermes auth → "Set rotation strategy" หรือใน config.yaml:

credential_pool_strategies:
  openrouter: round_robin
  anthropic: least_used

Error Recovery

Pool จะจัดการข้อผิดพลาดที่แตกต่างกันด้วยวิธีที่แตกต่างกัน:

flag has_retried_429 จะถูกรีเซ็ตในการเรียก API ที่สำเร็จทุกครั้ง ดังนั้น 429 ชั่วคราวเพียงครั้งเดียวจึงไม่กระตุ้นการ rotate

Custom Endpoint Pools

Custom OpenAI-compatible endpoints (เช่น Together.ai, RunPod, local servers) จะมี pool ของตัวเอง โดยใช้ชื่อ endpoint เป็น key จาก custom_providers ใน config.yaml

เมื่อคุณตั้งค่า custom endpoint ผ่าน hermes model, ระบบจะสร้างชื่อให้โดยอัตโนมัติ เช่น "Together.ai" หรือ "Local (localhost:8080)". ชื่อนี้จะกลายเป็น pool key

# After setting up a custom endpoint via hermes model:
hermes auth list
# Shows:
#   Together.ai (1 credential):
#     #1  config key    api_key config:Together.ai ←

# Add a second key for the same endpoint:
hermes auth add Together.ai --api-key sk-together-second-key

Custom endpoint pools จะถูกจัดเก็บใน auth.json ภายใต้ credential_pool โดยมี prefix custom::

{
  "credential_pool": {
    "openrouter": [...],
    "custom:together.ai": [...]
  }
}

Auto-Discovery

Hermes จะค้นพบ credentials จากหลายแหล่งโดยอัตโนมัติและใส่ข้อมูลลงใน pool เมื่อเริ่มต้น:

รายการที่ auto-seed จะถูกอัปเดตทุกครั้งที่โหลด pool - หากคุณลบ env var ออก, รายการ pool ของมันจะถูกลบออกโดยอัตโนมัติ ส่วนรายการที่เพิ่มด้วยตนเอง (เพิ่มผ่าน hermes auth add) จะไม่มีการลบออกโดยอัตโนมัติ

Delegation & Subagent Sharing

เมื่อ agent สร้าง subagents ผ่าน delegate_task, credential pool ของ parent จะถูกแชร์ให้ child โดยอัตโนมัติ:

• Same provider - child จะได้รับ pool ทั้งหมดของ parent ซึ่งช่วยให้สามารถ rotate key เมื่อเกิด rate limits
• Different provider - child จะโหลด pool ของ Provider นั้นเอง (หากมีการตั้งค่า)
• No pool configured - child จะใช้ API key เดียวที่สืบทอดมา

นั่นหมายความว่า subagents จะได้รับประโยชน์จากความยืดหยุ่นในการรับมือ rate-limit เช่นเดียวกับ parent โดยไม่จำเป็นต้องมีการตั้งค่าเพิ่มเติม การเช่า credential ต่อ task (Per-task credential leasing) ช่วยให้มั่นใจว่า child จะไม่ขัดแย้งกันเมื่อมีการ rotate keys พร้อมกัน

Thread Safety

Credential pool ใช้ threading lock สำหรับการเปลี่ยนแปลง state ทั้งหมด (select(), mark_exhausted_and_rotate(), try_refresh_current(), mark_used()) สิ่งนี้ช่วยให้มั่นใจได้ว่าการเข้าถึงพร้อมกัน (concurrent access) จะปลอดภัยเมื่อ gateway จัดการเซสชัน chat หลายรายการพร้อมกัน

Architecture

สำหรับแผนภาพ data flow แบบเต็ม, ดูที่ docs/credential-pool-flow.excalidraw ใน repository

Credential pool จะถูกรวมเข้าที่ชั้น Provider resolution:

1. agent/credential_pool.py - Pool manager: storage, selection, rotation, cooldowns
2. hermes_cli/auth_commands.py - CLI commands and interactive wizard
3. hermes_cli/runtime_provider.py - Pool-aware credential resolution
4. run_agent.py - Error recovery: 429/402/401 → pool rotation → fallback

Storage

Pool state จะถูกจัดเก็บใน ~/.hermes/auth.json ภายใต้ key credential_pool:

{
  "version": 1,
  "credential_pool": {
    "openrouter": [
      {
        "id": "abc123",
        "label": "OPENROUTER_API_KEY",
        "auth_type": "api_key",
        "priority": 0,
        "source": "env:OPENROUTER_API_KEY",
        "access_token": "sk-or-v1-...",
        "last_status": "ok",
        "request_count": 142
      }
    ]
  },
}

Strategies จะถูกจัดเก็บใน config.yaml (ไม่ใช่ auth.json):

credential_pool_strategies:
  openrouter: round_robin
  anthropic: least_used

📄 user-guide/features/cron.md

sidebar_position: 5 title: "งานที่กำหนดเวลา (Cron)" description: "กำหนดเวลาทำงานอัตโนมัติด้วยภาษาธรรมชาติ จัดการด้วยเครื่องมือ cron เพียงตัวเดียว และแนบทักษะ (skills) หนึ่งตัวหรือมากกว่า"

งานที่กำหนดเวลา (Cron)

กำหนดเวลาให้งานทำงานโดยอัตโนมัติด้วยภาษาธรรมชาติหรือ cron expressions Hermes เปิดเผยการจัดการ cron ผ่านเครื่องมือ cronjob ตัวเดียว โดยใช้การดำเนินการแบบ action-style แทนการใช้เครื่องมือแยกสำหรับ schedule/list/remove

สิ่งที่ cron ทำได้ในปัจจุบัน

งาน cron สามารถ:

• กำหนดเวลางานแบบครั้งเดียว (one-shot) หรืองานที่เกิดขึ้นซ้ำ (recurring)
• หยุดชั่วคราว (pause), กลับมาทำงานต่อ (resume), แก้ไข (edit), ทริกเกอร์ (trigger), และลบงาน (remove)
• แนบทักษะ (skills) ศูนย์ ตัวเดียว หรือหลายตัวกับงาน
• ส่งผลลัพธ์กลับไปยัง chat ต้นทาง, local files, หรือปลายทางของแพลตฟอร์มที่กำหนดค่าไว้
• ทำงานใน agent sessions ใหม่ด้วยรายการเครื่องมือ (tool list) แบบ static ปกติ

:::warning เซสชันที่รัน cron ไม่สามารถสร้าง cron jobs เพิ่มเติมแบบวนซ้ำได้ Hermes จะปิดใช้งานเครื่องมือจัดการ cron ภายใน cron executions เพื่อป้องกันวงจรการกำหนดเวลาที่ทำงานผิดปกติ :::

การสร้างงานที่กำหนดเวลา

ใน chat ด้วย /cron

/cron add 30m "Remind me to check the build"
/cron add "every 2h" "Check server status"
/cron add "every 1h" "Summarize new feed items" --skill blogwatcher
/cron add "every 1h" "Use both skills and combine the result" --skill blogwatcher --skill maps

จาก CLI แบบ standalone

hermes cron create "every 2h" "Check server status"
hermes cron create "every 1h" "Summarize new feed items" --skill blogwatcher
hermes cron create "every 1h" "Use both skills and combine the result" \
  --skill blogwatcher \
  --skill maps \
  --name "Skill combo"

ผ่านการสนทนาแบบธรรมชาติ

ถาม Hermes ตามปกติ:

Every morning at 9am, check Hacker News for AI news and send me a summary on Telegram.

Hermes จะใช้เครื่องมือ cronjob แบบรวมภายใน

งาน cron ที่ผูกกับทักษะ (Skill-backed cron jobs)

งาน cron สามารถโหลดทักษะหนึ่งตัวหรือมากกว่าก่อนที่จะรัน prompt

ทักษะเดียว

cronjob(
    action="create",
    skill="blogwatcher",
    prompt="Check the configured feeds and summarize anything new.",
    schedule="0 9 * * *",
    name="Morning feeds",
)

หลายทักษะ

ทักษะจะถูกโหลดตามลำดับ prompt จะกลายเป็นคำสั่งงานที่ซ้อนทับอยู่บนทักษะเหล่านั้น

cronjob(
    action="create",
    skills=["blogwatcher", "maps"],
    prompt="Look for new local events and interesting nearby places, then combine them into one short brief.",
    schedule="every 6h",
    name="Local brief",
)

สิ่งนี้มีประโยชน์เมื่อคุณต้องการให้ agent ที่กำหนดเวลาสามารถสืบทอด workflow ที่นำกลับมาใช้ใหม่ได้ โดยไม่ต้องใส่ข้อความทักษะทั้งหมดลงใน cron prompt เอง

การแก้ไขงาน

คุณไม่จำเป็นต้องลบและสร้างงานใหม่เพียงเพื่อเปลี่ยนแปลงมัน

Chat

/cron edit <job_id> --schedule "every 4h"
/cron edit <job_id> --prompt "Use the revised task"
/cron edit <job_id> --skill blogwatcher --skill maps
/cron edit <job_id> --remove-skill blogwatcher
/cron edit <job_id> --clear-skills

CLI แบบ standalone

hermes cron edit <job_id> --schedule "every 4h"
hermes cron edit <job_id> --prompt "Use the revised task"
hermes cron edit <job_id> --skill blogwatcher --skill maps
hermes cron edit <job_id> --add-skill maps
hermes cron edit <job_id> --remove-skill blogwatcher
hermes cron edit <job_id> --clear-skills

หมายเหตุ:

• --skill ที่ทำซ้ำจะแทนที่รายการทักษะที่แนบกับงาน
• --add-skill จะเพิ่มต่อท้ายรายการที่มีอยู่โดยไม่แทนที่
• --remove-skill ลบทักษะที่แนบเฉพาะตัว
• --clear-skills ลบทักษะที่แนบทั้งหมด

การดำเนินการวงจรชีวิต (Lifecycle actions)

งาน cron มีวงจรชีวิตที่สมบูรณ์กว่าแค่ create/remove แล้ว

Chat

/cron list
/cron pause <job_id>
/cron resume <job_id>
/cron run <job_id>
/cron remove <job_id>

CLI แบบ standalone

hermes cron list
hermes cron pause <job_id>
hermes cron resume <job_id>
hermes cron run <job_id>
hermes cron remove <job_id>
hermes cron status
hermes cron tick

สิ่งที่แต่ละคำสั่งทำ:

• pause - เก็บงานไว้แต่หยุดการกำหนดเวลา
• resume - เปิดใช้งานงานอีกครั้งและคำนวณการทำงานในอนาคตครั้งถัดไป
• run - ทริกเกอร์งานในการ tick ของ scheduler ครั้งถัดไป
• remove - ลบงานออกไปทั้งหมด

วิธีการทำงาน

การรัน cron ถูกจัดการโดย gateway daemon gateway จะทำการ tick scheduler ทุก 60 วินาที และรันงานที่ถึงกำหนดใน isolated agent sessions

hermes gateway install     # ติดตั้งเป็น user service
sudo hermes gateway install --system   # Linux: boot-time system service สำหรับเซิร์ฟเวอร์
hermes gateway             # หรือรันใน foreground

hermes cron list
hermes cron status

พฤติกรรมของ gateway scheduler

ในการ tick แต่ละครั้ง Hermes:

1. โหลดงานจาก ~/.hermes/cron/jobs.json
2. ตรวจสอบ next_run_at เทียบกับเวลาปัจจุบัน
3. เริ่มต้น AIAgent session ใหม่สำหรับงานที่ถึงกำหนดแต่ละงาน
4. ฉีดทักษะที่แนบมาหนึ่งตัวหรือมากกว่าเข้าสู่ session ใหม่นั้นตามความจำเป็น
5. รัน prompt จนเสร็จสมบูรณ์
6. ส่งมอบผลลัพธ์สุดท้าย
7. อัปเดต metadata การรันและเวลาที่กำหนดการถัดไป

การล็อกไฟล์ที่ ~/.hermes/cron/.tick.lock ป้องกันไม่ให้การ tick ของ scheduler ที่ซ้อนทับกันรันงานชุดเดียวกันซ้ำ

ตัวเลือกการส่งมอบ (Delivery options)

เมื่อกำหนดเวลางาน คุณต้องระบุว่าผลลัพธ์จะถูกส่งไปที่ใด:

ผลลัพธ์สุดท้ายของ agent จะถูกส่งมอบโดยอัตโนมัติ คุณไม่จำเป็นต้องเรียกใช้ send_message ใน cron prompt

การห่อหุ้มผลลัพธ์ (Response wrapping)

โดยค่าเริ่มต้น ผลลัพธ์ cron ที่ส่งมอบจะถูกห่อหุ้มด้วย header และ footer เพื่อให้ผู้รับทราบว่ามาจากงานที่กำหนดเวลา:

Cronjob Response: Morning feeds
-------------

<agent output here>

Note: The agent cannot see this message, and therefore cannot respond to it.

หากต้องการส่งมอบผลลัพธ์ agent ดิบโดยไม่มี wrapper ให้ตั้งค่า cron.wrap_response เป็น false:

# ~/.hermes/config.yaml
cron:
  wrap_response: false

การระงับแบบเงียบ (Silent suppression)

หากผลลัพธ์สุดท้ายของ agent ขึ้นต้นด้วย [SILENT], การส่งมอบจะถูกระงับทั้งหมด ผลลัพธ์ยังคงถูกบันทึกไว้ในเครื่องสำหรับการตรวจสอบ (ใน ~/.hermes/cron/output/) แต่จะไม่มีการส่งข้อความไปยังปลายทางที่กำหนด

สิ่งนี้มีประโยชน์สำหรับการตรวจสอบงานที่ควรรายงานเมื่อมีบางอย่างผิดปกติเท่านั้น:

Check if nginx is running. If everything is healthy, respond with only [SILENT].
Otherwise, report the issue.

งานที่ล้มเหลวจะส่งมอบเสมอไม่ว่าจะมี marker [SILENT] หรือไม่ - มีเพียงการรันที่สำเร็จเท่านั้นที่สามารถถูกระงับได้

การหมดเวลาของสคริปต์ (Script timeout)

สคริปต์ก่อนรัน (แนบผ่านพารามิเตอร์ script) มีการหมดเวลาเริ่มต้นที่ 120 วินาที หากสคริปต์ของคุณต้องการเวลานานกว่านั้น - ตัวอย่างเช่น เพื่อรวมการหน่วงเวลาแบบสุ่มที่หลีกเลี่ยงรูปแบบการจับเวลาแบบบอท - คุณสามารถเพิ่มค่านี้ได้:

# ~/.hermes/config.yaml
cron:
  script_timeout_seconds: 300   # 5 minutes

หรือตั้งค่า environment variable HERMES_CRON_SCRIPT_TIMEOUT ลำดับการแก้ไขคือ: env var → config.yaml → ค่าเริ่มต้น 120 วินาที

การกู้คืนผู้ให้บริการ (Provider recovery)

งาน cron จะสืบทอด fallback providers และ credential pool rotation ที่คุณกำหนดค่าไว้ หาก API key หลักถูกจำกัดอัตรา (rate-limited) หรือผู้ให้บริการส่งข้อผิดพลาด agent cron สามารถ:

• Fall back ไปยังผู้ให้บริการทางเลือก หากคุณได้กำหนดค่า fallback_providers (หรือ fallback_model แบบเก่า) ใน config.yaml
• หมุนเวียนไปยัง credential ถัดไป ใน credential pool สำหรับผู้ให้บริการรายเดียวกัน

ซึ่งหมายความว่างาน cron ที่ทำงานด้วยความถี่สูงหรือในช่วงเวลาเร่งด่วนจะมีความยืดหยุ่นมากขึ้น - การที่ key เดียวถูกจำกัดอัตราจะไม่ทำให้การรันทั้งหมดล้มเหลว

รูปแบบการกำหนดเวลา (Schedule formats)

ผลลัพธ์สุดท้ายของ agent จะถูกส่งมอบโดยอัตโนมัติ - คุณไม่จำเป็นต้องรวม send_message ใน cron prompt สำหรับปลายทางเดียวกันนั้น หากการรัน cron เรียกใช้ send_message ไปยังเป้าหมายที่ scheduler จะส่งมอบอยู่แล้ว Hermes จะข้ามการส่งซ้ำนั้น และบอกให้ model ใส่เนื้อหาที่ผู้ใช้เห็นใน final response แทน ให้ใช้ send_message สำหรับเป้าหมายเพิ่มเติมหรือที่แตกต่างกันเท่านั้น

การหน่วงเวลาแบบสัมพัทธ์ (one-shot)

30m     → รันครั้งเดียวใน 30 นาที
2h      → รันครั้งเดียวใน 2 ชั่วโมง
1d      → รันครั้งเดียวใน 1 วัน

ช่วงเวลา (recurring)

every 30m    → ทุก 30 นาที
every 2h     → ทุก 2 ชั่วโมง
every 1d     → ทุกวัน

Cron expressions

0 9 * * *       → ทุกวันเวลา 9:00 น.
0 9 * * 1-5     → วันธรรมดาเวลา 9:00 น.
0 */6 * * *     → ทุก 6 ชั่วโมง
30 8 1 * *      → วันที่ 1 ของทุกเดือนเวลา 8:30 น.
0 0 * * 0       → ทุกวันอาทิตย์เวลาเที่ยงคืน

ISO timestamps

2026-03-15T09:00:00    → ครั้งเดียวในวันที่ 15 มีนาคม 2026 เวลา 9:00 น.

พฤติกรรมการทำซ้ำ (Repeat behavior)

คุณสามารถเขียนทับได้:

cronjob(
    action="create",
    prompt="...",
    schedule="every 2h",
    repeat=5,
)

การจัดการงานในรูปแบบโปรแกรม (Programmatically)

API ที่ใช้สำหรับ agent คือเครื่องมือเดียว:

cronjob(action="create", ...)
cronjob(action="list")
cronjob(action="update", job_id="...")
cronjob(action="pause", job_id="...")
cronjob(action="resume", job_id="...")
cronjob(action="run", job_id="...")
cronjob(action="remove", job_id="...")

สำหรับ update ให้ส่ง skills=[] เพื่อลบทักษะที่แนบทั้งหมด

การจัดเก็บงาน (Job storage)

งานจะถูกจัดเก็บใน ~/.hermes/cron/jobs.json ผลลัพธ์จากการรันงานจะถูกบันทึกที่ ~/.hermes/cron/output/{job_id}/{timestamp}.md

การจัดเก็บใช้ atomic file writes เพื่อให้แน่ใจว่าการเขียนที่ถูกขัดจังหวะจะไม่ทิ้งไฟล์งานที่เขียนไม่สมบูรณ์ไว้

งานที่กำหนดเวลาต้องมี prompt ที่สมบูรณ์

:::warning สำคัญ งาน cron ทำงานใน agent session ที่สดใหม่โดยสมบูรณ์ prompt จะต้องมีทุกสิ่งที่ agent ต้องการซึ่งไม่ได้ถูกให้โดย attached skills อยู่แล้ว :::

ไม่ดี: "ตรวจสอบปัญหาเซิร์ฟเวอร์นั้น"

ดี: "SSH เข้าไปยังเซิร์ฟเวอร์ 192.168.1.100 ในฐานะผู้ใช้ 'deploy', ตรวจสอบว่า nginx กำลังทำงานอยู่ด้วย 'systemctl status nginx', และยืนยันว่า https://example.com ส่งคืน HTTP 200"

ความปลอดภัย (Security)

prompt ของงานที่กำหนดเวลาจะถูกสแกนหารูปแบบ prompt-injection และ credential-exfiltration ทั้งในขณะสร้างและอัปเดต prompt ที่มี Unicode tricks ที่มองไม่เห็น, การพยายาม SSH backdoor, หรือ payload การขโมยความลับที่ชัดเจน จะถูกบล็อก

📄 user-guide/features/dashboard-plugins.md

sidebar_position: 16 title: "Dashboard Plugins" description: "Build custom tabs and extensions for the Hermes web dashboard"

Dashboard Plugins

Dashboard plugins ช่วยให้คุณเพิ่มแท็บที่กำหนดเอง (custom tabs) เข้าไปใน web dashboard ได้ Plugin หนึ่งสามารถแสดง UI ของตัวเอง เรียกใช้ Hermes API และทางเลือกคือลงทะเบียน backend endpoints ได้ทั้งหมดนี้โดยที่ไม่ต้องแก้ไข source code ของ dashboard เลย

Quick Start

ให้สร้าง plugin directory พร้อมกับ manifest และไฟล์ JS:

mkdir -p ~/.hermes/plugins/my-plugin/dashboard/dist

manifest.json:

{
  "name": "my-plugin",
  "label": "My Plugin",
  "icon": "Sparkles",
  "version": "1.0.0",
  "tab": {
    "path": "/my-plugin",
    "position": "after:skills"
  },
  "entry": "dist/index.js"
}

dist/index.js:

(function () {
  var SDK = window.__HERMES_PLUGIN_SDK__;
  var React = SDK.React;
  var Card = SDK.components.Card;
  var CardHeader = SDK.components.CardHeader;
  var CardTitle = SDK.components.CardTitle;
  var CardContent = SDK.components.CardContent;

  function MyPage() {
    return React.createElement(Card, null,
      React.createElement(CardHeader, null,
        React.createElement(CardTitle, null, "My Plugin")
      ),
      React.createElement(CardContent, null,
        React.createElement("p", { className: "text-sm text-muted-foreground" },
          "Hello from my custom dashboard tab!"
        )
      )
    );
  }

  window.__HERMES_PLUGINS__.register("my-plugin", MyPage);
})();

เมื่อ refresh dashboard - แท็บของคุณจะปรากฏใน navigation bar

Plugin Structure

Plugins จะอยู่ใน directory มาตรฐาน ~/.hermes/plugins/ ส่วนส่วนขยาย dashboard คือ subfolder ชื่อ dashboard/:

~/.hermes/plugins/my-plugin/
  plugin.yaml              # optional - manifest สำหรับ plugin CLI/gateway ที่มีอยู่
  __init__.py              # optional - hooks สำหรับ plugin CLI/gateway ที่มีอยู่
  dashboard/               # ส่วนขยาย dashboard
    manifest.json          # required - config ของแท็บ, icon, entry point
    dist/
      index.js             # required - JS bundle ที่ build ไว้ล่วงหน้า
      style.css            # optional - CSS ที่กำหนดเอง
    plugin_api.py          # optional - เส้นทาง API backend

Plugin เดียวสามารถขยายได้ทั้ง CLI/gateway (ผ่าน plugin.yaml + __init__.py) และ dashboard (ผ่าน dashboard/) จาก directory เดียวกัน

Manifest Reference

ไฟล์ manifest.json ใช้เพื่ออธิบาย plugin ของคุณให้กับ dashboard:

{
  "name": "my-plugin",
  "label": "My Plugin",
  "description": "What this plugin does",
  "icon": "Sparkles",
  "version": "1.0.0",
  "tab": {
    "path": "/my-plugin",
    "position": "after:skills"
  },
  "entry": "dist/index.js",
  "css": "dist/style.css",
  "api": "plugin_api.py"
}

Tab Position

field position ควบคุมว่าแท็บของคุณจะปรากฏที่ใดใน navigation:

• "end" - หลังแท็บ built-in ทั้งหมด (ค่าเริ่มต้น)
• "after:skills" - หลังแท็บ Skills
• "before:config" - ก่อนแท็บ Config
• "after:cron" - หลังแท็บ Cron

ค่าที่อยู่หลังเครื่องหมาย colon คือ path segment ของแท็บเป้าหมาย (โดยไม่มีเครื่องหมาย slash นำหน้า)

Available Icons

Plugins สามารถใช้ชื่อ icon ของ Lucide เหล่านี้ได้:

Activity, BarChart3, Clock, Code, Database, Eye, FileText, Globe, Heart, KeyRound, MessageSquare, Package, Puzzle, Settings, Shield, Sparkles, Star, Terminal, Wrench, Zap

หากชื่อ icon ไม่เป็นที่รู้จัก จะ fallback ไปที่ Puzzle

Plugin SDK

Plugins ไม่ได้ bundle React หรือ UI components แต่ใช้ SDK ที่เปิดเผยบน window.__HERMES_PLUGIN_SDK__ วิธีนี้ช่วยหลีกเลี่ยงปัญหา version conflicts และทำให้ plugin bundles มีขนาดเล็ก

SDK Contents

var SDK = window.__HERMES_PLUGIN_SDK__;

// React
SDK.React              // React instance
SDK.hooks.useState     // React hooks
SDK.hooks.useEffect
SDK.hooks.useCallback
SDK.hooks.useMemo
SDK.hooks.useRef
SDK.hooks.useContext
SDK.hooks.createContext

// API
SDK.api                // Hermes API client (getStatus, getSessions, etc.)
SDK.fetchJSON          // Raw fetch สำหรับ custom endpoints - จัดการเรื่อง auth โดยอัตโนมัติ

// UI Components (shadcn/ui style)
SDK.components.Card
SDK.components.CardHeader
SDK.components.CardTitle
SDK.components.CardContent
SDK.components.Badge
SDK.components.Button
SDK.components.Input
SDK.components.Label
SDK.components.Select
SDK.components.SelectOption
SDK.components.Separator
SDK.components.Tabs
SDK.components.TabsList
SDK.components.TabsTrigger

// Utilities
SDK.utils.cn           // Tailwind class merger (clsx + twMerge)
SDK.utils.timeAgo      // "5m ago" จาก unix timestamp
SDK.utils.isoTimeAgo   // "5m ago" จาก ISO string

// Hooks
SDK.useI18n            // i18n translations
SDK.useTheme           // ข้อมูล theme ปัจจุบัน

Using SDK.fetchJSON

สำหรับการเรียกใช้ backend API endpoints ของ plugin:

SDK.fetchJSON("/api/plugins/my-plugin/data")
  .then(function (result) {
    console.log(result);
  })
  .catch(function (err) {
    console.error("API call failed:", err);
  });

fetchJSON จะทำการ inject session auth token, จัดการข้อผิดพลาด, และ parse JSON โดยอัตโนมัติ

Using Existing API Methods

object SDK.api มี methods สำหรับ endpoint ของ Hermes ทั้งหมดที่ built-in:

// Fetch agent status
SDK.api.getStatus().then(function (status) {
  console.log("Version:", status.version);
});

// List sessions
SDK.api.getSessions(10).then(function (resp) {
  console.log("Sessions:", resp.sessions.length);
});

Backend API Routes

Plugins สามารถลงทะเบียน FastAPI routes ได้โดยการตั้งค่า field api ใน manifest ให้สร้างไฟล์ Python ที่ export router:

# plugin_api.py
from fastapi import APIRouter

router = APIRouter()

@router.get("/data")
async def get_data():
    return {"items": ["one", "two", "three"]}

@router.post("/action")
async def do_action(body: dict):
    return {"ok": True, "received": body}