Hermes Agent · setup guide · deepseek direct

Guidebook — Hermes Agent with DeepSeek (Direct API)

สำหรับผู้ใช้ที่เรียก DeepSeek ตรง (api.deepseek.com) ไม่ผ่าน gateway/aggregator เขียนจากของที่วัดจริงบนเครื่อง Hermes อีกตัว (แต่ตัดส่วนที่ผูกกับ Cloudflare ออกทั้งหมด)

0. TL;DR — 10 บรรทัด

  1. Hermes มี provider deepseek ในตัว — ใส่แค่ DEEPSEEK_API_KEY
  2. model.provider: deepseek · model: deepseek-chat (ตัวหลัก)
  3. deepseek-reasoner ใช้เฉพาะงานวิเคราะห์ อย่าตั้งเป็น default (ช้า + แพงกว่า)
  4. context 128k แต่ ตั้ง compression.threshold ~0.4 เพราะคุณภาพตกก่อนเต็ม
  5. ความจำขั้นต่ำ = USER.md + MEMORY.md + transcript ที่ runtime เก็บ + ไฟล์ state-of-record ต่อโปรเจกต์
  6. อย่าให้ AI สรุปความจำ — ให้ marker/ไฟล์เป็นตัวตัดสิน (deterministic)
  7. ถ้าทำโค้ด: บังคับผ่าน kanban + gate ที่รันเอง + reviewer แยก
  8. hook 4 ตัวพอ และต้อง fail-open + log ERROR
  9. วัด 4 ตัว: context tokens, recall accuracy, latency, silent failures
  10. ของที่ "ไม่ต้องมี" อยู่ใน §10 — อ่านก่อนติดตั้งอะไรเพิ่ม

1. ติดตั้งและตั้งโมเดล

# 1) คีย์
echo 'DEEPSEEK_API_KEY=sk-xxxxxxxx' >> ~/.hermes/.env

# 2) provider + model
hermes config set model.provider deepseek
hermes config set model deepseek-chat

# 3) ตรวจว่ามองเห็นโมเดล
hermes models            # หรือในแชท: /model

เลือกโมเดล | งาน | โมเดล | เหตุผล | |---|---|---| | แชท/งานทั่วไป/เขียนโค้ด | deepseek-chat | เร็ว ถูก context 128k | | วิเคราะห์ยาว/วางแผนซับซ้อน | deepseek-reasoner | คิดเป็นขั้น แต่ช้ากว่า 2–5 เท่า | | สรุป/จัดรูปแบบ | deepseek-chat | อย่าเปลือง reasoner |

ข้อควรระวังกับ reasoner: มันคืน reasoning_content แยกจาก content — ถ้า max_tokens น้อยจะได้ content ว่าง ตั้ง ≥4000 และ ห้ามให้ระบบ fallback ไปใช้ reasoning_content แทนคำตอบ

fallback provider (ถ้าอยากมีกันล่ม): ตั้ง fallback_providers ให้ชี้ provider อื่นที่มีคีย์ — Hermes รองรับ (fallback-providers.md)

2. Context — ตั้งให้พอดี ไม่ใช่ให้เต็ม

hermes config set compression.threshold 0.4      # compact ที่ ~40% ของ window
hermes config set compression.model deepseek-chat

เหตุผล: 128k คือเพดานที่รับได้ ไม่ใช่จุดที่ยังฉลาด — งานจริงคุณภาพเริ่มตกที่ 40–60% ของ window ตัวเลขที่ควรจำ: context 300k+ ทำให้ compaction ล้ม (result_tokens=0) และ stream หลุด — เราเคยเจอจริง

DeepSeek context caching: prompt ที่มี prefix ซ้ำจะถูก cache → ถูกกว่า ~10 เท่า ⇒ ออกแบบ system prompt ให้ นิ่ง และวางของที่เปลี่ยนทุกเทิร์น (ผล tool, context ที่ฉีด) ไว้ ท้าย prompt

3. Memory ขั้นต่ำ (พอสำหรับคนเดียว)

~/.hermes/memories/USER.md     ← ตัวเจ้าของ: preference, วิธีพูด, ข้อห้าม (เพดาน ~3,000 ตัวอักษร)
~/.hermes/memories/MEMORY.md   ← convention ของเครื่อง/โปรเจกต์ (เพดาน ~6,000)
$HERMES_HOME/state.db          ← transcript ทั้งหมด (runtime เก็บเอง) + FTS5
<repo>/docs/project-history/   ← current-state.md (snapshot ≤80 บรรทัด) + changelog.md (append-only)

กติกา 3 ข้อ 1. USER.md เขียนเป็น ข้อเท็จจริง ไม่ใช่คำสั่ง: ผู้ใช้ชอบรายงานสั้น ≤5 บรรทัด ✅ / ต้องตอบสั้น ❌ 2. current-state.md = snapshot (เขียนทับ) · changelog.md = append-only — อย่าสลับกัน 3. เมื่อ USER.md ใกล้เต็ม ให้ แทนที่ บรรทัดที่ล้าสมัย ไม่ใช่เพิ่มต่อ

ค้นย้อนหลัง: ทำ CLI เล็ก ๆ อ่าน state.db แบบ read-only (FTS5) — เร็วกว่าและไม่กิน context ของโมเดล

SELECT session_id, role, content FROM messages_fts f JOIN messages m ON m.id=f.rowid
WHERE messages_fts MATCH ? ORDER BY bm25(messages_fts) LIMIT 20;

4. Context injection (ถ้าต้องการให้ "จำเอง")

hook ของ Hermes รับ JSON ทาง stdin คืน JSON ทาง stdout — pre_llm_call คืน {"context": "..."} = ถูกฉีดเข้า user message

ค่าที่แนะนำ | hook | ทำอะไร | ค่า | |---|---|---| | pre_llm_call | ฉีดความรู้ เฉพาะเทิร์นแรก | timeout 8s · budget ≤1,500 tokens · cache 30 นาที | | pre_tool_call | บล็อกการแก้ไฟล์นอก allowlist | fail_closed: true | | post_tool_call | บันทึก event (PROBE) | ไม่บล็อก | | pre_api_request | คุม rate/concurrency | concurrency 1 |

กฎเหล็ก: hook ต้อง fail-open (exception → คืน {} + log ERROR) เพราะ hook ที่ทำให้เทิร์นพังแย่กว่าไม่มี hook และห้ามฉีดทุกเทิร์น — วัดแล้วเทิร์นแรก +5.5s, เทิร์นถัดไปต้อง +0s

5. ให้มันเรียนรู้ "คนใช้"

สัมภาษณ์รอบเดียว 20 นาที แล้วเขียน USER.md 5–10 บรรทัด: งานประจำ · เครื่องมือที่ใช้ · ภาษาและน้ำเสียง · สิ่งที่ห้ามทำ · เวลาทำงาน/ความเร่งด่วน

วงจรเรียนรู้ 1. ทุกครั้งที่ผู้ใช้แก้คำตอบ → เพิ่ม preference 1 บรรทัด (ไม่เล่าเรื่อง) 2. ทุกครั้งที่ต้องเตือนซ้ำเรื่องเดิม → นั่นคือช่องว่างของ memory ให้เก็บทันที 3. ทบทวนสัปดาห์ละครั้ง: บรรทัดไหนไม่เคยถูกใช้ = ลบทิ้ง

ห้าม: ให้โมเดล "สรุปว่าผู้ใช้เป็นคนแบบไหน" แล้วเก็บเป็นความจริง — ให้เก็บจากคำพูดจริงของผู้ใช้เท่านั้น

6. ถ้าทำโค้ดด้วย — governance ย่อ

เจ้าของ → Lead (Hermes) เขียน brief + gate
        → coder (agent อีกตัว/subprocess) เขียนโค้ดเท่านั้น
        → Lead รันเทสต์เอง (ไม่เชื่อรายงาน)
        → reviewer แยก เห็นเฉพาะ diff + ผลเทสต์ + brief
        → ปิดงาน: changelog + commit

บังคับที่ระดับเครื่องมือ ไม่ใช่ที่วินัย: hook pre_tool_call ที่บล็อก Lead ไม่ให้เขียนไฟล์ source (fail_closed) บทเรียนจริง: gate ที่ใช้ fixture ประดิษฐ์จะ "เขียวหลอก" — ต้องทดสอบด้วยข้อมูลจริง + holdout ที่คนเขียนไม่เห็นล่วงหน้า

7. ค่าใช้จ่าย

8. ปัญหาที่พบบ่อย

อาการ สาเหตุ แก้
ตอบว่าง reasoner + max_tokens เล็ก ตั้ง ≥4000, ห้ามใช้ reasoning_content แทน content
ช้าผิดปกติ ใช้ reasoner เป็น default เปลี่ยน default เป็น deepseek-chat, เรียก reasoner เฉพาะงาน
ตอบช้าแล้วหลุดกลางทาง context ใหญ่ + compaction ล้ม ลด compression.threshold, ตรวจ log ว่า compaction สำเร็จ
429 ยิงพร้อมกันหลาย request concurrency 1 + breaker
"จำไม่ได้" ความรู้อยู่แต่ไม่ถูกค้น ทำ recall CLI + ฉีดเทิร์นแรก + เขียน current-state.md
script รายงานสำเร็จแต่ไม่มีอะไรเกิดขึ้น silent failure บังคับ exit ≠ 0 + log ERROR + watchdog

9. Checklist 30 นาทีแรก

วัดผลสัปดาห์แรก: context tokens/เทิร์น · session ใหม่ตอบเรื่องเดิมได้กี่ข้อจาก 5 · latency เทิร์นแรก · จำนวนครั้งที่ต้องอธิบายซ้ำ

10. สิ่งที่ ไม่ต้อง ติดตั้ง (อ่านก่อน)

หลักคิด: ยิ่งทำงานนาน ต้องยิ่งมีความรู้ ไม่ใช่ยิ่งมี context บวม