np-dms/lcbp3

Fork 0

Files

T

admin f33487f511

CI / CD Pipeline / build (push) Successful in 4m53s

Details

CI / CD Pipeline / deploy (push) Failing after 2m16s

Details

690529:1702 ADR-030-230 context aware #09

2026-05-29 17:02:12 +07:00

7.4 KiB

Raw Blame History

// File: specs/200-fullstacks/231-hermes-agent/research.md // Change Log: // - 2026-05-29: Phase 0 research — all unknowns resolved from ADR-031 v2.0

Research: Hermes Agent

Feature: 231-hermes-agent | Date: 2026-05-29

R-001: Hermes Stack / Runtime

Decision: NestJS (TypeScript) บน Node.js 22 — เช่นเดียวกับ DMS backend เพื่อ reuse tooling, tsconfig, ESLint, Jest Rationale: ทีมรู้จัก NestJS ดีแล้ว; BullMQ ใช้ร่วม npm package ได้; TypeScript strict mode enforce ตาม AGENTS.md Alternatives considered:

Python FastAPI — reuse Ollama/ML code แต่ทีมหลักเป็น TypeScript/NestJS
Go — performance ดีกว่าแต่ไม่มี BullMQ native และทีมไม่คุ้นเคย

R-002: Cloud AI Provider & Model Selection

Decision: Claude Sonnet (orchestration) / Claude Haiku (sub-agents) เป็น primary; GPT-4o / GPT-4o-mini เป็น fallback Rationale: ADR-031 v2.0 Locked Decision — Cloud AI Exception สำหรับ dev orchestration layer โดยเฉพาะ; ใช้ model ขนาดเล็กกว่าสำหรับ sub-agents เพื่อลด cost Alternatives considered:

Ollama only (Gemma4/gemma2) — ไม่ได้รับ exception จาก ADR-023A สำหรับ dev orchestration; context window จำกัด; ไม่เหมาะกับ orchestration workload ขนาดใหญ่
GPT-4o only — ราคาสูงกว่าถ้าใช้ทุก request

R-003: Dev Qdrant Isolation

Decision: Separate Qdrant instance บน ASUSTOR port 6334 (container: hermes-qdrant); collection lcbp3_code_chunks indexed by repoName + moduleName Rationale: ADR-031 v2.0 Locked — ห้ามใช้ Qdrant instance เดียวกับ DMS document RAG (port 6333 บน QNAP ADR-023A); separation ป้องกัน cross-contamination Alternatives considered:

Shared DMS Qdrant — ปฏิเสธ: ADR-031 v2.0 explicit lock; DMS Qdrant ใช้ projectPublicId filter สำหรับ document isolation ซึ่งไม่เหมาะกับ code chunks

R-004: BullMQ Queue Architecture

Decision: hermes-notification-queue เป็น queue หลักสำหรับ outbound Telegram; hermes-orchestration-queue สำหรับ async dev tasks; ใช้ Redis instance แยก (hermes-redis container) Rationale: ADR-031 Redis Isolation Policy — ห้ามใช้ DMS production Redis (อาจ evict DMS BullMQ/lock/cache keys ถ้าใช้ allkeys-lru); queue names ขึ้นต้น hermes- Alternatives considered:

Shared DMS Redis — ปฏิเสธ: ADR-031 explicit policy; ถ้าจำเป็นต้องแชร์ต้องมี keyPrefix แยก, DB index แยก, ACL user แยก

R-005: hermes_operations_log Storage

Decision: SQLite database ภายใน Hermes container volume (/volume1/docker/hermes/data/ops.db) — เริ่มต้นง่าย, ไม่ต้อง external service, เพียงพอสำหรับ DevOps audit trail Rationale: ADR-031 — ต้องอยู่ใน Hermes-owned storage เท่านั้น; ไม่ใช่ DMS audit_logs; single-operator DevOps tool ไม่ต้องการ high-concurrency DB Alternatives considered:

Postgres volume ภายใน Hermes stack — option ถ้า ops volume เติบโต แต่ SQLite เพียงพอสำหรับ Stage 1-4
Structured log files + ship to log collector — viable แต่ SQLite ง่ายกว่าสำหรับ query ด้วย /status <transactionId>

R-006: SOUL.md เป็น Session Memory

Decision: Plain Markdown file ภายใน container volume /volume1/docker/hermes/SOUL.md; Hermes อ่านต้น session และ append per-session entry; rotate ทุก 30 วัน Rationale: ADR-031 v2.0 Locked — ไม่ sync ลง repo ทุกกรณี; container-local เท่านั้น; ไม่ใช้ Obsidian หรือ external knowledge base Alternatives considered:

Redis-based session memory — volatile และ restart ทำให้ข้อมูลหาย
Gitea wiki/issue — sync ลง repo ซึ่งขัดกับ ADR-031 locked decision

R-007: Telegram Webhook Security

Decision: Verify X-Telegram-Bot-Api-Secret-Token header ทุก request; enforce allowlist (HERMES_TELEGRAM_ALLOWED_USER_IDS); Redis-based rate limit 10 req/min/user; expose webhook เฉพาะ LAN หรือผ่าน reverse proxy ที่มี TLS + Telegram secret verification Rationale: ป้องกัน spoofed requests; ป้องกัน unauthorized DevOps access; ป้องกัน spam/DoS ตาม ADR-031 security requirements Alternatives considered:

IP allowlist only — ไม่เพียงพอถ้า Telegram ใช้ dynamic IPs
No rate limiting — risk ของ spam/DoS จาก compromised Telegram account

R-008: Git Identity & PR Flow

Decision: hermes-bot Gitea service account (least privilege); write token scope: create branch/issue/PR/trigger CI เท่านั้น (ไม่ใช่ admin token); branch pattern hermes/{feat,fix,refactor}-*; ห้าม push main/develop; ต้องผ่าน CI ก่อน merge; human approve required Rationale: ADR-031 v2.0 Locked — ทุก change ผ่าน PR ที่ human review เท่านั้น; ป้องกัน accidental direct push to protected branches Alternatives considered:

Hermes push ตรง develop — ปฏิเสธ: ADR-031 explicit lock; repo gate compliance
Admin token — ปฏิเสธ: ADR-031 explicit prohibition; least privilege principle

R-009: Resource Limits บน ASUSTOR (non-Swarm Docker)

Decision: กำหนด fallback resource limits ทั้งใน deploy.resources (Swarm syntax) และ top-level cpus/mem_limit (non-Swarm syntax) เพื่อให้ enforce บน ASUSTOR ADM Docker; verify ด้วย docker inspect และ docker stats Rationale: ADR-031 note — deploy.resources อาจถูก ignore ใน non-Swarm Docker บน ASUSTOR; ต้อง verify จาก runtime ไม่ใช่ compose file เท่านั้น Alternatives considered:

Swarm mode บน ASUSTOR — ไม่จำเป็นสำหรับ single-node DevOps tool; เพิ่ม complexity โดยไม่จำเป็น

R-010: Context Loading Strategy (Selective Context)

Decision: Hermes โหลด context แบบ selective ตาม task type เพื่อลด token ที่ส่งไป Cloud AI: DevOps task → CONTEXT-ADR-031+AGENTS.md; DMS feature coding → +CONTEXT.md; Schema/DB → +schema SQL (read-only); Bug fix → +Dev Qdrant search results Rationale: ADR-031 v2.0 — ลด cost ของ Cloud AI; ป้องกันส่ง production DB query results เข้า Cloud AI context (Data Classification Policy) Alternatives considered:

โหลด CONTEXT.md ทุก request — เพิ่ม token cost; ไม่จำเป็นสำหรับ pure DevOps queries

7.4 KiB Raw Blame History