996 lines
60 KiB
Markdown
996 lines
60 KiB
Markdown
# ADR-031: Hermes Agent — Autonomous Dev Orchestrator & Telegram DevOps Bridge (v2.0)
|
||
|
||
## Status
|
||
|
||
- **Status:** Draft
|
||
- **Date:** 2026-05-28
|
||
- **Version:** 2.0 (2026-05-29 — grill-with-docs: Orchestration as primary concern)
|
||
- **Deciders:** NAP-DMS Architecture Team
|
||
- **Supersedes:** ADR-031 v1.1 (DevOps Bridge only)
|
||
|
||
### Locked Decisions (v1.x — DevOps Bridge Foundation)
|
||
|
||
ข้อตกลงด้านล่างถูกล็อคตั้งแต่ v1.x และยังคงบังคับใช้ใน v2.0:
|
||
|
||
* **Hermes role:** Hermes เป็น Developer Operations Agent / Autonomous Dev Orchestrator ไม่ใช่ production DMS service และไม่ใช่ AI inference boundary ของ DMS
|
||
* **Database access:** Hermes เชื่อม MariaDB ได้เฉพาะ read-only account สำหรับ schema inspection, metadata diagnostics เท่านั้น
|
||
* **Document storage:** Hermes ห้าม mount, browse, หรืออ่าน permanent document storage ของ production โดยตรง
|
||
* **Telegram scope:** Hermes Telegram ใช้สำหรับ DevOps commands เท่านั้น ไม่ใช่ production DMS command channel
|
||
* **DMS Telegram:** Telegram command สำหรับ query/mutate เอกสารจริงเป็น future separate ADR/spec
|
||
* **Hermes proxy:** `hermes proxy` เป็น Developer AI Proxy only ไม่ใช่ DMS AI runtime
|
||
* **Telegram writes:** ต้องมี explicit confirmation; push `main`/`master`, production deploy, schema migration, direct DB writes, storage delete ห้ามทุกกรณี
|
||
* **Schema rollout:** ADR-031 ไม่เพิ่มหรือแก้ production DMS schema
|
||
|
||
### Locked Decisions (v2.0 — Orchestration Layer)
|
||
|
||
ข้อตกลงใหม่จาก grill session 2026-05-29:
|
||
|
||
* **Cloud AI Exception:** Hermes Orchestrator layer อนุญาต Cloud AI API (Claude/GPT-4o) ได้ — เป็น exception จาก ADR-023A ที่ใช้เฉพาะ DevOps/Dev Orchestration layer เท่านั้น ไม่ใช่ DMS document processing
|
||
* **Data Classification (Dev-Out Policy):** Code, Config, ADR, Stack trace ส่ง Cloud AI ได้ — Production runtime data จาก DB query (document content, user info, project business data) ห้ามส่งออกทุกกรณี
|
||
* **Dev Qdrant:** Separate Qdrant instance บน ASUSTOR สำหรับ codebase embedding โดยเฉพาะ — ห้ามใช้ Qdrant instance เดียวกับ DMS document RAG (ADR-023A)
|
||
* **SOUL.md:** Hermes working journal อยู่ใน container เท่านั้น (`/volume1/docker/hermes/SOUL.md`) ไม่ sync กลับ repo
|
||
* **Context Source:** Hermes ดึง project context จาก `specs/06-Decision-Records/CONTEXT-ADR-031.md` + `AGENTS.md` โดยตรง ไม่ใช้ Obsidian หรือ external knowledge base
|
||
* **Sub-agent Delegation:** Hermes orchestrate โดย (1) Cloud sub-agents ใช้ model เล็กกว่า (Claude Haiku/GPT-4o-mini) สำหรับ code generation tasks และ (2) MCP invocations ไปยัง Devin/agy ที่มีอยู่แล้ว
|
||
* **Git Identity:** Hermes ใช้ Gitea service account (`hermes-bot`) push เฉพาะ `hermes/*` branches — ห้าม push ตรง `main`/`develop` ทุกกรณี — ทุก change ต้องผ่าน PR ที่ human approve
|
||
|
||
## Context
|
||
|
||
การตั้งค่าระบบ **Hermes Agent** ในโปรเจกต์ **NAP-DMS (LCBP3)** เพื่อทำหน้าที่เป็น **Autonomous Development Loop Orchestrator** — ควบคุมงาน AI Coding ทั้งหมด วาง Roadmap จ่ายงานให้ sub-agents ตรวจสอบผลลัพธ์ และสร้าง PR สำหรับ human review
|
||
|
||
ใน v2.0 Hermes มี 2 primary roles:
|
||
1. **Autonomous Dev Orchestrator** (primary) — คุม development loop ตั้งแต่ requirement จนถึง PR
|
||
2. **Telegram DevOps Bridge** (subsystem) — DevOps commands, CI status, Gitea notifications
|
||
|
||
Hermes ไม่ใช่ production DMS service และไม่ใช่ DMS AI inference boundary (ADR-023/ADR-023A) แต่ได้รับ **Cloud AI exception** สำหรับ dev orchestration layer โดยเฉพาะ พร้อม Data Classification Policy ที่ชัดเจน
|
||
|
||
## Decision
|
||
|
||
ใช้ Approach B (Local Development Network) พร้อมควบคุมทรัพยากร (CPU/RAM) และใช้ API Key Authentication สำหรับ CLI Tools
|
||
|
||
## Consequences
|
||
|
||
### Infrastructure Setup (Approach B - Local Development)
|
||
|
||
* **Hermes Agent:** รันบน ASUSTOR NAS ภายใน Docker Network `lcbp3` โดยมีการจำกัดทรัพยากร (Resource Limits) เพื่อป้องกันผลกระทบต่อระบบหลักของ NAS และทำหน้าที่เป็น Developer Operations Agent / Integration Assistant เท่านั้น
|
||
* **Resource Allocation:**
|
||
* CPU Limit: 2.0 Cores
|
||
* RAM Memory: 2GB (Reservation) / 4GB (Limit)
|
||
|
||
* **Environment:** เน้นการพัฒนาในรูปแบบ Local Development โดยให้ Agent สื่อสารกับ Gitea และแหล่งข้อมูลตรวจสอบแบบ read-only ภายในเครือข่ายเท่านั้น
|
||
* **Database Access Boundary:** Hermes สามารถเชื่อมต่อ MariaDB เพื่อการตรวจสอบแบบ read-only ได้เฉพาะผ่าน read-only replica หรือ read-only DB account ที่ฐานข้อมูลบังคับสิทธิ์เอง ใช้สำหรับ schema inspection, metadata diagnostics, และ query verification เท่านั้น ห้ามเขียน production DB ทุกกรณี
|
||
* **Data Minimization Boundary:** read-only DB account ของ Hermes ต้องเห็นเฉพาะ schema metadata และข้อมูล operational/devops ที่จำเป็น หากต้อง query ตาราง DMS จริงต้องใช้ masked read-only replica หรือ database view ที่ redact PII/document-sensitive fields เช่น เนื้อหาเอกสาร, storage path, token, password hash, และข้อมูลผู้ใช้ละเอียด
|
||
* **Storage Access Boundary:** Hermes ห้าม mount, browse, หรืออ่าน permanent document storage ของ production โดยตรง หากต้องตรวจสอบเอกสารจริงต้องเรียกผ่าน DMS Backend API ที่ผ่าน RBAC, audit, และ project isolation controls เท่านั้น
|
||
|
||
### Security & Access Control Strategy
|
||
|
||
* **Authentication:** ใช้ระบบ **API Key** ในการเข้าถึง Hermes Agent จาก CLI Tools (Antigravity/Codex) บน Local Desktop
|
||
* **Hermes Proxy Boundary:** `hermes proxy` เป็น Developer AI Proxy สำหรับ coding/devops assistance เท่านั้น ไม่ใช่ DMS AI runtime, ไม่ใช่ document intelligence path, และห้ามใช้กับ production document payload, secrets, หรือข้อมูลเอกสารจริง
|
||
* **Network Exposure Boundary:** Hermes services (`:8080`, `:8766`, `/mcp`, และ internal tool endpoints) ต้อง expose เฉพาะ LAN/VPN ที่จำเป็น ห้ามเปิด public internet โดยตรง หาก Telegram webhook ต้องรับ traffic จาก internet ให้ terminate ผ่าน reverse proxy ที่มี TLS, Telegram secret token verification, IP/rate limit, และ request logging
|
||
* **Secret Management Boundary:** `HERMES_PROXY_API_KEY`, Telegram bot token, webhook secret, Gitea token, และ read-only DB credential ห้ามอยู่ใน repo/spec/plain `.env` ที่ commit ได้ ต้องเก็บใน ASUSTOR secret store หรือไฟล์ environment นอก repo ที่จำกัด permission และมี rotation plan
|
||
* **Gitea Token Boundary:** Hermes ต้องใช้ Gitea token แบบ least privilege โดย default เป็น read-only สำหรับ repo/issue/PR status และใช้ write token แยกเฉพาะ action ที่ผ่าน confirmation แล้ว ห้ามใช้ admin token หรือ token ที่ push ไป `main`/`master` ได้
|
||
* **Operations Log Boundary:** `hermes_operations_log` เป็น log store ของ Hermes เอง เช่น SQLite/Postgres volume ภายใน Hermes stack หรือ structured log file ที่ ship ไป log collector ไม่ใช่ `audit_logs` ของ DMS และต้องมี retention/redaction policy
|
||
* **Failure Isolation Boundary:** Hermes เป็น optional DevOps assistant เท่านั้น หาก Hermes, Telegram Bridge, MCP, หรือ hermes proxy ล่ม ต้องไม่กระทบ DMS production, Workflow Engine, AI pipeline, หรือ user-facing app
|
||
* **Validation Boundary:** ข้อมูลทั้งหมดที่ส่งผ่าน CLI, MCP หรือ AI จะต้องอ้างอิงผ่าน `publicId` (UUIDv7) เท่านั้น ห้ามเปิดเผยหรือใช้งาน `INT AUTO_INCREMENT` ภายนอกเด็ดขาด (ADR-019)
|
||
* **Repository Gate Compliance:** Hermes ต้องเคารพ repo gates เดิมทั้งหมดตาม `AGENTS.md`, lint, tests, CI, และ branch protection; ADR-031 ไม่เป็นเจ้าของ Git Hooks policy และไม่เพิ่ม hook ใหม่
|
||
* **Telegram Access Check:** Hermes Telegram ต้องใช้ allowlist/admin mapping สำหรับ DevOps commands เท่านั้น หากมี DMS Telegram module ในอนาคต ต้องแยก implementation และตรวจสอบสิทธิ์ผ่าน CASL Guard ของ DMS API เสมอ
|
||
|
||
---
|
||
|
||
## Orchestration Architecture (v2.0 — Primary Concern)
|
||
|
||
### Overview: Autonomous Development Loop
|
||
|
||
Hermes ทำหน้าที่เป็น "Lead Developer" / "Conductor" ที่คุม development loop ทั้งหมด โดยไม่ลงไปเขียนโค้ดทุกบรรทัดเอง แต่วางแผน จ่ายงาน ตรวจสอบผลลัพธ์ และสร้าง PR:
|
||
|
||
```
|
||
[Developer / Telegram Command]
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────┐
|
||
│ Hermes Orchestrator (Flagship Cloud AI) │
|
||
│ Claude / GPT-4o │
|
||
│ Context: CONTEXT-ADR-031.md + AGENTS.md │
|
||
│ Memory: SOUL.md (container-local) │
|
||
│ Search: Dev Qdrant (ASUSTOR) │
|
||
└──────────┬──────────────────────────────┘
|
||
│
|
||
┌───────┴────────┐
|
||
▼ ▼
|
||
[Cloud Sub-agents] [MCP Tool Invocations]
|
||
Claude Haiku / Devin / agy / Codex
|
||
GPT-4o-mini (existing tools, no new models)
|
||
│ ▼
|
||
└────────┬───────
|
||
▼
|
||
[Self-Correction Loop]
|
||
npm run lint / jest / tsc
|
||
→ Error? Re-delegate to sub-agent
|
||
→ Pass? Continue
|
||
│
|
||
▼
|
||
[Git: hermes/* branch]
|
||
hermes-bot commits
|
||
Creates PR → Human Review & Approve
|
||
```
|
||
|
||
### Step 1: Requirement & Context Assembly
|
||
|
||
Hermes โหลด context แบบ **selective** ตาม task type เพื่อลด token ที่ส่งไป Cloud AI:
|
||
|
||
| Task Type | Context ที่โหลด |
|
||
|-----------|----------------|
|
||
| DevOps / CI / Git | `CONTEXT-ADR-031.md` + `AGENTS.md` |
|
||
| DMS feature coding | `CONTEXT-ADR-031.md` + `AGENTS.md` + `CONTEXT.md` |
|
||
| Schema / DB work | `CONTEXT-ADR-031.md` + `AGENTS.md` + `CONTEXT.md` + schema SQL (read-only) |
|
||
| Bug fix / refactor | `CONTEXT-ADR-031.md` + `AGENTS.md` + Dev Qdrant (code patterns) |
|
||
|
||
**Sources:**
|
||
- `specs/06-Decision-Records/CONTEXT-ADR-031.md` — agent rules, project identity, tooling, infra paths
|
||
- `CONTEXT.md` (root) — domain terminology (Correspondence, RFA, Workflow Engine, AI concepts) — โหลดเฉพาะ DMS feature tasks
|
||
- `AGENTS.md` — TypeScript rules, forbidden patterns (no `any`, no `parseInt` on UUID), ADR references
|
||
- Dev Qdrant (ASUSTOR) — semantic code search หา reference patterns จาก codebase embeddings
|
||
|
||
**ห้ามดึง** production runtime data (DB query results, document content, user data) เข้า cloud AI context
|
||
|
||
### Step 2: Semantic Code Search (Dev Qdrant)
|
||
|
||
Hermes ใช้ Qdrant instance แยก (บน ASUSTOR, ไม่ใช่ DMS Qdrant) ทำ semantic search หา reference patterns ใน codebase:
|
||
|
||
```yaml
|
||
# docker-compose.hermes-qdrant.yml (ASUSTOR — แยกจาก DMS)
|
||
services:
|
||
hermes-qdrant:
|
||
image: qdrant/qdrant:latest
|
||
container_name: hermes-qdrant
|
||
volumes:
|
||
- hermes_qdrant_data:/qdrant/storage
|
||
ports:
|
||
- "6334:6333" # port แยกจาก DMS Qdrant (:6333)
|
||
deploy:
|
||
resources:
|
||
limits:
|
||
memory: 2G
|
||
```
|
||
|
||
Collection: `lcbp3_code_chunks` — indexed by `repoName` + `moduleName` (ไม่ใช่ `projectPublicId` ซึ่งเป็น DMS document isolation)
|
||
|
||
### Step 3: Sub-agent Delegation
|
||
|
||
Hermes แตกงานเป็น tasks แล้ว delegate ผ่าน 2 channels:
|
||
|
||
**Channel A — Cloud Sub-agents (Code Generation):**
|
||
```
|
||
Orchestrator (Claude/GPT-4o)
|
||
→ "เขียน NestJS service สำหรับ X"
|
||
→ Sub-agent (Claude Haiku / GPT-4o-mini)
|
||
→ Returns code diff
|
||
→ Orchestrator validates against AGENTS.md rules
|
||
```
|
||
|
||
**Channel B — MCP Tool Invocations (File Execution):**
|
||
```
|
||
Orchestrator
|
||
→ MCP hermes-tools: bash/git operations บน ASUSTOR
|
||
→ MCP mariadb: schema lookup (read-only)
|
||
→ MCP gitea: PR/issue management
|
||
→ Triggers Devin/agy ถ้า complex scaffolding needed
|
||
```
|
||
|
||
**Data Classification Enforcement:**
|
||
| ส่งได้ | ห้ามส่ง |
|
||
|--------|---------|
|
||
| Code snippets, patterns | Production DB query results |
|
||
| ADR/spec content | Document content (title, body) |
|
||
| Stack traces, error output | User data, project names from DB |
|
||
| Config files, tsconfig | API keys, tokens, passwords |
|
||
| Schema structure (column names) | Storage paths ที่มี PII |
|
||
|
||
### Step 4: Self-Correction Loop
|
||
|
||
โค้ดที่ sub-agent ส่งกลับมาต้องผ่าน validation ก่อนใช้:
|
||
|
||
```bash
|
||
# Hermes runs via MCP hermes-tools
|
||
npm run lint # ESLint — ต้องผ่านทุก rule
|
||
npx tsc --noEmit # TypeScript strict mode
|
||
npm test -- --passWithNoTests # Jest tests ที่เกี่ยวข้อง
|
||
```
|
||
|
||
ถ้าพบ error → Hermes วิเคราะห์ output → ส่งกลับให้ sub-agent แก้ไข (max 3 iterations)
|
||
ถ้า iteration > 3 → หยุดและแจ้ง developer ผ่าน Telegram
|
||
|
||
### Step 5: Git Identity & PR Flow
|
||
|
||
```
|
||
hermes-bot commits → hermes/feat-{task-id} branch
|
||
├─ git config user.name "Hermes Bot"
|
||
├─ git config user.email "hermes-bot@np-dms.work"
|
||
├─ commit message: "feat(hermes): {task description}\n\nOrchestrated by Hermes ADR-031 v2.0"
|
||
└─ push → Gitea → Create PR → assign to developer
|
||
```
|
||
|
||
**Git Identity Rules:**
|
||
- Service account: `hermes-bot` (Gitea, least privilege, write token เฉพาะ feature branches)
|
||
- Branch pattern: `hermes/feat-*`, `hermes/fix-*`, `hermes/refactor-*`
|
||
- ห้าม push ตรง `main`, `develop`, `release/*` ทุกกรณี
|
||
- PR ต้องผ่าน CI (lint + test) ก่อน merge
|
||
- Human ต้อง review และ approve ก่อน merge เสมอ — ห้าม auto-merge
|
||
|
||
### SOUL.md — Hermes Working Journal
|
||
|
||
`/volume1/docker/hermes/SOUL.md` เก็บ per-session working memory ของ Hermes:
|
||
|
||
```markdown
|
||
## Session 2026-05-29T10:30
|
||
Task: scaffold correspondence search feature
|
||
Context loaded: CONTEXT-ADR-031.md, backend/src/modules/correspondence/
|
||
Sub-agents delegated: 2 code generation calls
|
||
Iterations: 1 (lint pass first try)
|
||
PR created: hermes/feat-correspondence-search → #142
|
||
Status: DONE
|
||
```
|
||
|
||
- ไม่ commit ลง repo — อยู่ใน container volume เท่านั้น
|
||
- Hermes อ่าน SOUL.md ต้น session เพื่อ resume context
|
||
- Rotate ทุก 30 วัน หรือ manual clear
|
||
|
||
---
|
||
|
||
## Implementation Details
|
||
|
||
### 1. Infrastructure Configuration
|
||
|
||
#### Redis Persistence for BullMQ (Durability)
|
||
|
||
เพื่อให้ BullMQ queue ของ Hermes ทนทานต่อการ restart ของ ASUSTOR NAS ต้องกำหนดค่า Redis persistence โดยแยกจาก DMS production Redis เป็นค่า default:
|
||
|
||
```yaml
|
||
# docker-compose.hermes-redis.yml
|
||
services:
|
||
hermes-redis:
|
||
image: redis:7-alpine
|
||
container_name: hermes_redis_lcbp3
|
||
networks:
|
||
- lcbp3_net
|
||
volumes:
|
||
- hermes_redis_data:/data
|
||
- ./hermes.redis.conf:/usr/local/etc/redis/redis.conf
|
||
command: redis-server /usr/local/etc/redis/redis.conf
|
||
restart: unless-stopped
|
||
|
||
volumes:
|
||
hermes_redis_data:
|
||
driver: local
|
||
```
|
||
|
||
```conf
|
||
# hermes.redis.conf - บันทึกข้อมูลทุก 60 วินาที หากมีการเปลี่ยนแปลงอย่างน้อย 1 key
|
||
save 60 1
|
||
save 300 10
|
||
save 900 10000
|
||
|
||
# เปิดใช้งาน AOF (Append-Only File) เพื่อ durability สูงสุด
|
||
appendonly yes
|
||
appendfsync everysec
|
||
|
||
# ชื่อไฟล์ AOF
|
||
appendfilename "appendonly.aof"
|
||
|
||
# จำกัด memory ใช้งานสูงสุด (ปรับตามสเปก NAS)
|
||
maxmemory 512mb
|
||
maxmemory-policy allkeys-lru
|
||
```
|
||
|
||
**ข้อดี:**
|
||
- หาก ASUSTOR restart ข้อมูลใน Hermes queue จะไม่สูญหาย
|
||
- AOF บันทึกทุก operation ทำให้สามารถ recovery ได้เกือบ 100%
|
||
- ไม่ปะปนกับ DMS production BullMQ/lock/cache keys
|
||
|
||
**Redis Isolation Policy:**
|
||
|
||
* Default คือ Hermes ใช้ Redis instance/volume แยกจาก DMS production Redis
|
||
* หาก resource จำกัดจนต้องใช้ Redis instance เดียวกับ DMS production ต้องกำหนด `keyPrefix`, DB index แยก, ACL user แยก, monitoring แยก, และ maxmemory policy ที่ไม่ evict DMS keys
|
||
* ห้ามใช้ `allkeys-lru` บน shared Redis ที่มี DMS locks/cache/queues เพราะอาจ evict key สำคัญของ DMS
|
||
* Hermes queue names ต้องขึ้นต้นด้วย `hermes-` เช่น `hermes-notification-queue`
|
||
|
||
#### Docker Compose (Hermes Agent with Resource Limits)
|
||
|
||
```yaml
|
||
version: '3.8'
|
||
|
||
networks:
|
||
lcbp3_net:
|
||
name: lcbp3
|
||
external: true
|
||
|
||
services:
|
||
hermes-agent:
|
||
image: np-dms.work/hermes/agent:latest
|
||
container_name: hermes_agent_lcbp3
|
||
networks:
|
||
- lcbp3_net
|
||
environment:
|
||
- DATABASE_HOST=mariadb_container_name
|
||
- DATABASE_PORT=3306
|
||
- GITEA_URL=http://gitea_container_name:3000
|
||
- HERMES_ENV=local_dev
|
||
# Non-Swarm Docker Compose fallback. ตรวจสอบว่า ASUSTOR runtime enforce จริงด้วย docker inspect/stats
|
||
cpus: '2.0'
|
||
mem_reservation: 2048M
|
||
mem_limit: 4096M
|
||
deploy:
|
||
resources:
|
||
limits:
|
||
cpus: '2.0'
|
||
memory: 4096M
|
||
reservations:
|
||
memory: 2048M
|
||
restart: unless-stopped
|
||
```
|
||
|
||
> **Resource Limit Note:** `deploy.resources` อาจถูก ignore ใน Docker Compose แบบ non-Swarm บน ASUSTOR ได้ จึงต้องกำหนด fallback (`cpus`, `mem_reservation`, `mem_limit`) และ verify จาก runtime ด้วย `docker inspect`/`docker stats` ทุกครั้ง
|
||
|
||
#### API Key Configuration
|
||
|
||
ตัวอย่างบนเครื่องพัฒนา Windows PowerShell:
|
||
|
||
```powershell
|
||
# คอนฟิกค่า API Key ลงในตัวแปรระบบของเครื่องพัฒนา
|
||
$env:ANTIGRAVITY_API_KEY = "hermes_secure_api_key_v1_9_0"
|
||
$env:CODEX_API_KEY = "hermes_secure_api_key_v1_9_0"
|
||
|
||
# ตัวอย่างการเรียกใช้งาน CLI
|
||
antigravity-cli sync --target hermes_agent_lcbp3:8080 --key $env:ANTIGRAVITY_API_KEY
|
||
```
|
||
|
||
#### MCP Server Configuration
|
||
|
||
ตัวอย่างด้านล่างเป็น template เท่านั้น ต้อง verify package/command ของ MCP server จริงตอน implementation และห้าม commit credential จริงลง config:
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"lcbp3-mariadb-mcp": {
|
||
"command": "npx",
|
||
"args": [
|
||
"-y",
|
||
"@modelcontextprotocol/server-postgres-mariadb",
|
||
"--host", "${HERMES_MARIADB_READONLY_HOST}",
|
||
"--port", "${HERMES_MARIADB_READONLY_PORT}",
|
||
"--db", "${HERMES_MARIADB_READONLY_DATABASE}",
|
||
"--user", "${HERMES_MARIADB_READONLY_USER}",
|
||
"--password", "${HERMES_MARIADB_READONLY_PASSWORD}"
|
||
],
|
||
"description": "Read-only schema/metadata diagnostics only. Verify MCP package and CLI before rollout."
|
||
},
|
||
"lcbp3-gitea-mcp": {
|
||
"command": "node",
|
||
"args": ["./scripts/gitea-mcp-bridge.js"],
|
||
"env": {
|
||
"GITEA_TOKEN": "${HERMES_GITEA_TOKEN}",
|
||
"GITEA_BASE_URL": "${HERMES_GITEA_BASE_URL}"
|
||
},
|
||
"description": "Least-privilege Gitea token for DevOps diagnostics and approved actions."
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
> **Security Boundary:** MCP database access สำหรับ Hermes ต้องเป็น read-only account หรือ read-only replica เท่านั้น และใช้เพื่อ developer diagnostics ไม่ใช่ production DMS write path การอ่านไฟล์เอกสาร production ต้องผ่าน DMS Backend API ห้าม mount storage เข้า Hermes container โดยตรง
|
||
|
||
> **Data Minimization:** read-only account นี้ต้องถูกจำกัดที่ระดับ DB grant/view/replica ไม่ใช่พึ่ง policy ใน agent เท่านั้น โดย default ให้เห็น schema metadata และ operational diagnostics เท่านั้น หากจำเป็นต้อง query ตาราง DMS จริงให้ใช้ masked views หรือ read-only replica ที่ redact sensitive fields
|
||
|
||
> **Implementation Verification:** MCP package name, CLI arguments, remote-server field names, and environment interpolation behavior must be verified against the actual installed MCP client/server before rollout.
|
||
|
||
---
|
||
|
||
### 2. Telegram Integration Architecture
|
||
|
||
#### System Overview
|
||
|
||
Telegram Bridge ใน ADR-031 เป็น interface ของ Hermes สำหรับ **DevOps commands เท่านั้น** ไม่ใช่ production DMS command channel และไม่ใช่ช่องทาง query/แก้ไขเอกสารจริง
|
||
|
||
* **Inbound Commands (Inbound):** รับคำสั่งผ่าน Webhook ของ Telegram Bot สำหรับ DevOps tasks เช่น CI status, Gitea issue/PR summary, scheduled audit, repository diagnostics, และสถานะ Hermes Agent
|
||
* **System Commands:** เช่น `/status`, `/ci_status`, `/repo_summary`, `/schedule_audit` จะถูกประมวลผลทันทีใน Hermes command service โดยไม่แตะ production DMS workflow
|
||
* **Document Queries:** ไม่อยู่ใน scope ของ Hermes Telegram หากต้อง query หรือ mutate เอกสารจริง ต้องทำเป็น DMS Backend Telegram module แยกต่างหาก และต้อง enforce RBAC, audit, project isolation, และ Idempotency-Key ตาม ADR-016/019/023A
|
||
|
||
* **Notification Dispatcher (Outbound):** ใช้ **BullMQ** เป็นตัวจัดการคิวการส่งข้อความ
|
||
* ทุกการส่งงาน (Job) จะต้องระบุ `Transaction ID` (UUIDv7) เพื่อใช้ในการติดตามผล
|
||
* ทุก Transaction จะถูกบันทึกใน `hermes_operations_log` หรือ log store ของ Hermes เพื่อ trace DevOps operation โดยไม่ปะปนกับ `audit_logs` ของ DMS
|
||
|
||
* **Error Handling:** ตาม ADR-007 ระบบต้องทำ Retry 3 ครั้งพร้อม Exponential Backoff หากการเชื่อมต่อ Telegram API ล้มเหลว
|
||
|
||
#### Hermes DevOps Telegram Gateway (Pseudocode)
|
||
|
||
```typescript
|
||
// hermes/src/integrations/telegram/hermes-telegram-gateway.ts
|
||
type HermesTelegramMessage = {
|
||
message?: {
|
||
from?: { id?: number; username?: string };
|
||
text?: string;
|
||
chat?: { id?: number };
|
||
};
|
||
};
|
||
|
||
class HermesTelegramGateway {
|
||
constructor(private readonly commandRouter: HermesDevOpsCommandRouter) {}
|
||
|
||
async handleWebhook(payload: HermesTelegramMessage): Promise<HermesCommandResult> {
|
||
const transactionId = uuidv7();
|
||
const telegramUserId = payload.message?.from?.id?.toString();
|
||
const text = payload.message?.text?.trim();
|
||
|
||
if (!telegramUserId || !text) {
|
||
return this.reject(transactionId, 'INVALID_TELEGRAM_PAYLOAD');
|
||
}
|
||
|
||
await hermesOperationsLog.recordInbound({
|
||
transactionId,
|
||
telegramUserId,
|
||
commandText: text,
|
||
});
|
||
|
||
return this.commandRouter.execute({
|
||
transactionId,
|
||
telegramUserId,
|
||
commandText: text,
|
||
scope: 'DEVOPS_ONLY',
|
||
});
|
||
}
|
||
}
|
||
```
|
||
|
||
#### Hermes Outbound Dispatcher
|
||
|
||
```typescript
|
||
// hermes/src/integrations/telegram/hermes-telegram-dispatcher.ts
|
||
@Processor('hermes-notification-queue')
|
||
class HermesTelegramDispatcher extends WorkerHost {
|
||
@Process('telegram-devops-outbound')
|
||
async handleOutbound(job: Job<HermesTelegramOutboundJob>): Promise<TelegramSendResult> {
|
||
const { chatId, message, transactionId } = job.data;
|
||
const sent = await this.bot.sendMessage(chatId, `${message}\n\n[Ref: ${transactionId}]`);
|
||
|
||
await hermesOperationsLog.recordOutbound({ transactionId, chatId });
|
||
return sent;
|
||
}
|
||
}
|
||
```
|
||
|
||
> **Out of Scope:** Production DMS Telegram commands, document queries, Workflow Engine actions, and AI document interactions are not implemented in Hermes. If the project needs those capabilities, create a separate DMS Backend ADR/spec and enforce DMS Backend API, CASL/RBAC, `Idempotency-Key`, `audit_logs`, and `publicId` rules there.
|
||
|
||
#### System Commands
|
||
|
||
* `/status`: เช็คสถานะ Agent (Bypass AI)
|
||
* `/ci_status`: เช็คสถานะ CI ล่าสุดจาก Gitea
|
||
* `/repo_summary`: สรุป issue/PR หรือ repository diagnostics
|
||
* `/schedule_audit`: ตั้ง scheduled DevOps audit ผ่าน Hermes
|
||
* `/help`: แสดงรายการคำสั่งทั้งหมด
|
||
|
||
#### Telegram Command Permission Policy
|
||
|
||
Hermes Telegram commands ต้องแบ่งสิทธิ์ตามผลกระทบของคำสั่ง:
|
||
|
||
| ระดับ | คำสั่งที่อนุญาต | เงื่อนไข |
|
||
|---|---|---|
|
||
| **Read-only** | `/status`, `/ci_status`, `/repo_summary`, `/audit_summary` | ทำได้ทันทีสำหรับผู้ใช้ใน allowlist |
|
||
| **Write with confirmation** | สร้าง branch, เปิด issue/PR, trigger CI, schedule audit | ต้องมี explicit confirmation ใน Telegram และบันทึก `transactionId` ใน `hermes_operations_log` |
|
||
| **Forbidden from Telegram** | push ไป `main`/`master`, production deploy, schema migration execution, destructive git/file commands, direct DB writes, storage delete | ห้ามทำผ่าน Telegram ทุกกรณี ต้องใช้ workflow ที่มี human review และ approval แยกต่างหาก |
|
||
|
||
ตัวอย่างคำสั่งที่ปลอดภัยควรเป็น “เตรียม branch/PR proposal สำหรับ fix/ci-pnpm-cache” ไม่ใช่ “สร้าง branch แล้ว push ให้เลย”
|
||
|
||
#### Future DMS Telegram Module (Out of Scope)
|
||
|
||
หากต้องการ Telegram command ที่ query หรือ mutate เอกสารจริง ต้องสร้าง ADR/spec แยกสำหรับ DMS Backend Telegram module เท่านั้น และ rollout นั้นต้องผ่าน ADR-009/016/019/023A เต็มรูปแบบ
|
||
|
||
ตาราง `user_telegram_mapping` ด้านล่างเป็นตัวอย่าง requirement สำหรับ future module เท่านั้น **ห้าม create table นี้เป็นส่วนหนึ่งของ ADR-031 rollout**
|
||
|
||
```sql
|
||
CREATE TABLE user_telegram_mapping (
|
||
id BINARY(16) PRIMARY KEY,
|
||
user_id BINARY(16) NOT NULL,
|
||
telegram_id VARCHAR(255) NOT NULL UNIQUE,
|
||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||
INDEX (telegram_id),
|
||
CONSTRAINT fk_user_telegram FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
### 3. Security & Audit Requirements
|
||
|
||
#### Tier 1 Security Checklist
|
||
|
||
1. **Auth Check:** Hermes Telegram ต้องตรวจสอบ allowlist/admin mapping สำหรับ DevOps commands เท่านั้น หากเป็น DMS Backend Telegram module ในอนาคต ต้องตรวจสอบ `telegram_id` กับ `user_id` และสิทธิ์ผ่าน CASL Guard ของ DMS API
|
||
2. **Hermes Operations Log:** ทุก Transaction ID ต้องถูกบันทึกใน `hermes_operations_log` หรือ log store ของ Hermes ทันทีทั้งตอนได้รับ (Inbound) และส่งออก (Outbound) ไม่ใช้ `audit_logs` ของ DMS เว้นแต่มี DMS Backend module แยกต่างหาก
|
||
3. **Error Handling:** ตาม `ADR-007` หากการส่งข้อความผ่าน BullMQ ล้มเหลว (เช่น Telegram API ล่ม) ระบบต้องมีการทำ Retry 3 ครั้งโดยใช้ Exponential Backoff
|
||
|
||
#### Webhook Security & Verification
|
||
|
||
Telegram ส่ง Webhook พร้อม Header `X-Telegram-Bot-Api-Secret-Token` เพื่อ verify ว่า request มาจาก Telegram จริง:
|
||
|
||
```typescript
|
||
// hermes/src/integrations/telegram/hermes-telegram-webhook.ts
|
||
class HermesTelegramWebhook {
|
||
async handleWebhook(headers: WebhookHeaders, payload: HermesTelegramMessage) {
|
||
if (headers['x-telegram-bot-api-secret-token'] !== process.env.HERMES_TELEGRAM_WEBHOOK_SECRET) {
|
||
throw new Error('INVALID_TELEGRAM_WEBHOOK_SECRET');
|
||
}
|
||
return this.hermesTelegramGateway.handleWebhook(payload);
|
||
}
|
||
}
|
||
```
|
||
|
||
**ข้อควรระวัง:**
|
||
- หากไม่ verify secret ใครก็ตามที่คาดเดา URL ได้จะสามารถส่งข้อความปลอมในนามระบบได้
|
||
- ต้องตั้งค่า `secret_token` เมื่อ register webhook กับ Telegram Bot API
|
||
|
||
#### Rate Limiting (ป้องกัน Spam)
|
||
|
||
ใช้ Redis-based rate limiting เพื่อจำกัดจำนวน request ต่อ `telegram_id` และไม่เก็บ state ใน memory ของ container:
|
||
|
||
```typescript
|
||
const rateLimitKey = `hermes:telegram:${telegramUserId}`;
|
||
const requestCount = await redis.incr(rateLimitKey);
|
||
await redis.expire(rateLimitKey, 60);
|
||
|
||
if (requestCount > HERMES_TELEGRAM_RATE_LIMIT_MAX) {
|
||
throw new Error('HERMES_TELEGRAM_RATE_LIMIT_EXCEEDED');
|
||
}
|
||
```
|
||
|
||
#### Hermes Transaction Status (Tracking)
|
||
|
||
ให้ผู้ใช้ติดตามสถานะของ Transaction ID ได้ผ่าน Telegram command `/status <transactionId>` เฉพาะ Hermes DevOps transaction:
|
||
|
||
```typescript
|
||
// hermes/src/commands/status-command.ts
|
||
async function getHermesTransactionStatus(transactionId: string): Promise<HermesTransactionStatus> {
|
||
const operation = await hermesOperationsLog.findByTransactionId(transactionId);
|
||
const job = await hermesNotificationQueue.getJob(transactionId);
|
||
|
||
return {
|
||
transactionId,
|
||
status: job?.state ?? operation?.status ?? 'unknown',
|
||
createdAt: operation?.createdAt,
|
||
completedAt: job?.finishedOn,
|
||
attempts: job?.attemptsMade,
|
||
error: job?.failedReason,
|
||
};
|
||
}
|
||
```
|
||
|
||
**การใช้งาน:**
|
||
- ผู้ใช้สามารถ query ด้วย `/status <transactionId>` ใน Telegram สำหรับ DevOps/Hermes transaction เท่านั้น
|
||
- ไม่ expose DMS-style `/api/v1/telegram` endpoint จาก Hermes
|
||
|
||
#### Environment Variables
|
||
|
||
```env
|
||
HERMES_TELEGRAM_BOT_TOKEN=your_token_here
|
||
HERMES_TELEGRAM_WEBHOOK_SECRET=a_very_secret_string_for_security
|
||
HERMES_TELEGRAM_ALLOWED_USER_IDS=123456789,987654321
|
||
HERMES_TELEGRAM_RATE_LIMIT_MAX=10
|
||
HERMES_TELEGRAM_RATE_LIMIT_WINDOW_MS=60000
|
||
```
|
||
|
||
---
|
||
|
||
### 4. Hermes Interface Modes
|
||
|
||
Hermes รันได้ 3 mode หลักที่ share config/data เดียวกันใน `~/.hermes`:
|
||
- **CLI/TUI** — `hermes --tui` interactive session
|
||
- **Messaging Gateway** — รองรับ 22 platform (Telegram, Discord, Slack, WhatsApp, Signal, LINE, Mattermost, Matrix, Teams, Google Chat ฯลฯ)
|
||
- **IDE Integration** — เชื่อมกับ Devin / Codex ผ่าน MCP
|
||
|
||
#### CLI Commands
|
||
|
||
ตัวอย่าง command ด้านล่างรันบน ASUSTOR shell หลัง SSH เข้า NAS:
|
||
|
||
```sh
|
||
hermes # interactive TUI session
|
||
hermes -q "สรุป open issues" # single query แบบ non-interactive
|
||
hermes --continue # resume session ล่าสุด
|
||
hermes -z "task" < file.txt # pipe input → capture output (scriptable)
|
||
hermes -s dms-context -q "..." # preload skill แล้วถาม
|
||
hermes -w -q "fix issue #42" # isolated git worktree (safe parallel run)
|
||
```
|
||
|
||
#### เหตุผลที่ Telegram เป็น interface หลักบน ASUSTOR
|
||
|
||
Hermes รันบน ASUSTOR ตลอด 24/7 การ SSH เข้าไปแค่เพื่อถามคำถามไม่ practical — สามารถ chat จาก **ทุก device** ขณะที่มันทำงานบน NAS ได้เลย
|
||
|
||
```
|
||
[มือถือ / Laptop ที่ไหนก็ได้]
|
||
↕ Telegram
|
||
[Hermes บน ASUSTOR Docker]
|
||
↕ SSH terminal backend
|
||
[ASUSTOR filesystem / Gitea / MariaDB]
|
||
```
|
||
|
||
#### Updated Stack ภาพรวม
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ Laptop / Desktop │
|
||
│ │
|
||
│ Windsurf IDE agy (Antigravity CLI) │
|
||
│ └─ Cascade └─ same engine as desktop │
|
||
│ └─ MCP (MariaDB, └─ parallel subagents │
|
||
│ Gitea) └─ /schedule tasks │
|
||
│ │
|
||
│ Codex CLI │
|
||
│ └─ → hermes proxy (Developer AI Proxy only) │
|
||
└────────────────────┬────────────────────────────────┘
|
||
│ SSH / Telegram
|
||
┌────────────────────▼────────────────────────────────┐
|
||
│ ASUSTOR NAS (ADM + Docker) │
|
||
│ │
|
||
│ ┌─────────────────────────────────────────────┐ │
|
||
│ │ Hermes Agent (Docker container) │ │
|
||
│ │ │ │
|
||
│ │ Memory: DMS schema, conventions, ADRs │ │
|
||
│ │ Skills: dms-context, gitea-watch, rag-ops │ │
|
||
│ │ Channels: Telegram + hermes proxy │ │
|
||
│ │ Terminal backend: SSH → Gitea Actions │ │
|
||
│ └─────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ Gitea Actions Runners (existing) │
|
||
└─────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
#### Interface Selection Guide
|
||
|
||
| สถานการณ์ | Interface | ทำไม |
|
||
|---|---|---|
|
||
| นั่งทำงานที่โต๊ะ coding | Devin Cascade | IDE context + MCP |
|
||
| สั่ง task ซับซ้อน / multi-agent | `agy` CLI หรือ Desktop | parallel subagents |
|
||
| batch ops / scaffolding | Codex CLI | bash execution |
|
||
| อยู่นอกบ้าน / มือถือ | Telegram → Hermes | always-on บน ASUSTOR สำหรับ DevOps commands เท่านั้น |
|
||
| CI watch / scheduled audit | Hermes `/schedule` | 24/7 background |
|
||
| Codex ต้องการ assistance สำหรับ coding/devops | `hermes proxy` → Codex | Developer AI Proxy เท่านั้น ห้ามใช้กับ production document payload |
|
||
|
||
#### 3 วิธีที่คุยกับ Hermes
|
||
|
||
**1. Telegram (แนะนำสำหรับ DevOps commands)** — ส่งข้อความจากที่ไหนก็ได้
|
||
|
||
ตัวอย่างที่ส่งได้:
|
||
```
|
||
"CI run ล่าสุดผ่านไหม?"
|
||
"สรุป TODO ใน correspondence module ให้หน่อย"
|
||
"เตรียม branch/PR proposal สำหรับ fix/ci-pnpm-cache"
|
||
```
|
||
|
||
**2. SSH เข้า ASUSTOR → `hermes --tui`** — ใช้เมื่อทำงานหนัก (multi-step coding task)
|
||
|
||
```bash
|
||
ssh admin@<ASUSTOR_IP>
|
||
hermes --continue # resume session ล่าสุด
|
||
```
|
||
|
||
**3. Codex CLI บน laptop → hermes proxy** — Codex รันบน laptop และใช้ Hermes เป็น Developer AI Proxy สำหรับ coding/devops assistance เท่านั้น
|
||
|
||
ตัวอย่างบน Windows PowerShell:
|
||
|
||
```powershell
|
||
$env:OPENAI_BASE_URL = "http://<ASUSTOR_IP>:8766/v1"
|
||
$env:OPENAI_API_KEY = "<HERMES_PROXY_API_KEY>"
|
||
|
||
# ใช้กับ coding/devops task ที่ไม่มี production document payload หรือ secrets
|
||
codex "scaffold NestJS module for repository diagnostics"
|
||
```
|
||
|
||
> **Secret Handling:** ตัวอย่างค่า key/token ในเอกสารนี้เป็น placeholder เท่านั้น ห้าม commit secret จริงลง repo หรือ spec file
|
||
|
||
> **หมายเหตุ Port และ Boundary:** hermes proxy ใช้ port `:8766` — ห้ามใช้ `:8765` ซึ่ง PaddleOCR sidecar ใช้อยู่แล้ว (ADR-023A) และห้ามนำ proxy นี้ไปใช้แทน DMS AI runtime ที่ต้องผ่าน DMS Backend/BullMQ/Ollama boundary ตาม ADR-023A
|
||
|
||
---
|
||
|
||
### 5. Antigravity CLI (agy) + Hermes MCP Integration
|
||
|
||
#### Antigravity CLI (`agy`) คืออะไร
|
||
|
||
`agy` เป็น Go binary — single self-contained executable ที่ bidirectional sync กับ desktop app ได้ ใช้ Gemini 3.5 Flash by default รองรับ parallel subagents, slash commands อย่าง `/goal` และ `/schedule`
|
||
|
||
```bash
|
||
agy # TUI interactive
|
||
agy "scaffold NestJS module for docs" # single task
|
||
agy /goal "implement RAG pipeline" # set persistent goal
|
||
agy /schedule "run audit daily 02:00" # background scheduled task
|
||
```
|
||
|
||
#### agy ใช้ Hermes เป็น model backend ตรงๆ ไม่ได้
|
||
|
||
`agy` ผูกกับ Google Antigravity backend — ไม่รองรับ custom OpenAI-compatible endpoint โดยตรง
|
||
|
||
**วิธีที่ถูกต้อง:** เชื่อม agy กับ Hermes **ผ่าน MCP** — agy ยังใช้ Gemini ในการ orchestrate แต่ดึง DMS memory + tools จาก Hermes มาด้วย
|
||
|
||
```
|
||
agy (Gemini 3.5 Flash)
|
||
└── MCP: hermes-memory ← ดึง DMS context จาก Hermes
|
||
└── MCP: hermes-tools ← สั่ง Hermes รัน bash/git บน ASUSTOR
|
||
└── MCP: mariadb ← DB schema (เดิม)
|
||
└── MCP: gitea ← Gitea API (เดิม)
|
||
```
|
||
|
||
#### Config Files สำหรับ agy
|
||
|
||
**`~/.gemini/config/mcp_config.json`**
|
||
|
||
```json
|
||
{
|
||
"hermes-memory": {
|
||
"serverUrl": "http://<ASUSTOR_IP>:8766/mcp",
|
||
"headers": {
|
||
"Authorization": "Bearer <HERMES_PROXY_API_KEY>"
|
||
},
|
||
"description": "LCBP3 DMS persistent memory and context from Hermes"
|
||
},
|
||
"mariadb": {
|
||
"command": "docker",
|
||
"args": [
|
||
"run", "--rm", "-i",
|
||
"-e", "MARIADB_HOST=<QNAP_IP>",
|
||
"-e", "MARIADB_PORT=3306",
|
||
"-e", "MARIADB_USER=dms_user",
|
||
"-e", "MARIADB_PASSWORD=<password>",
|
||
"mcp/mariadb"
|
||
]
|
||
},
|
||
"gitea": {
|
||
"command": "docker",
|
||
"args": [
|
||
"run", "--rm", "-i",
|
||
"-e", "GITEA_URL=http://<QNAP_IP>:3000",
|
||
"-e", "GITEA_TOKEN=<token>",
|
||
"mcp/gitea"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
> **สำคัญ:** field name สำหรับ remote MCP server ใช้ `serverUrl` (ไม่ใช่ `url`) ใน agy — ถ้าผิดตรงนี้ server จะ fail แบบ silent
|
||
|
||
**`~/.gemini/antigravity-cli/settings.json`**
|
||
|
||
```json
|
||
{
|
||
"model": "gemini-3.5-flash-high",
|
||
"theme": "Default",
|
||
"autoAccept": false,
|
||
"contextFiles": [
|
||
"~/.gemini/antigravity-cli/DMS_CONTEXT.md"
|
||
],
|
||
"permissions": {
|
||
"defaultMode": "suggest",
|
||
"autoApprove": [
|
||
"read_file",
|
||
"list_directory",
|
||
"mcp_hermes-memory_recall",
|
||
"mcp_mariadb_query"
|
||
]
|
||
},
|
||
"subagents": {
|
||
"maxParallel": 3
|
||
}
|
||
}
|
||
```
|
||
|
||
**`~/.gemini/antigravity-cli/DMS_CONTEXT.md`**
|
||
|
||
```markdown
|
||
# LCBP3 DMS — agy context
|
||
|
||
## Stack
|
||
- NestJS + Next.js 14, pnpm monorepo, MariaDB + TypeORM
|
||
- Gitea (QNAP) → CI via ASUSTOR runners
|
||
- Hermes Agent (ASUSTOR): DMS memory + bash execution
|
||
|
||
## When starting any task
|
||
1. Call mcp_hermes-memory_recall("dms-context") ก่อนเสมอ
|
||
2. อ่าน schema ผ่าน mcp_mariadb ก่อน scaffold
|
||
3. งานที่ต้องรัน bash → delegate ให้ Hermes ผ่าน MCP
|
||
|
||
## Hard rules (🔴)
|
||
- ห้าม commit ตรง main/develop
|
||
- ห้ามรัน migration โดยไม่ได้รับ human approval
|
||
```
|
||
|
||
#### Flow เมื่อใช้ agy + Hermes ร่วมกัน
|
||
|
||
```
|
||
คุณพิมพ์ใน agy:
|
||
"implement document revision API"
|
||
│
|
||
▼
|
||
agy (Gemini 3.5 Flash)
|
||
1. เรียก MCP hermes-memory → ดึง DMS context
|
||
2. เรียก MCP mariadb → อ่าน schema
|
||
3. วางแผน → spawn 2 subagents parallel:
|
||
├── subagent A: NestJS service + controller
|
||
└── subagent B: unit tests
|
||
4. subagents เรียก MCP hermes-tools
|
||
→ Hermes รัน git/pnpm บน ASUSTOR
|
||
5. รายงานผลกลับมาที่ agy
|
||
```
|
||
|
||
| | agy | Hermes |
|
||
|---|---|---|
|
||
| Model | Gemini 3.5 Flash (orchestration) | Claude Sonnet (memory/tools) |
|
||
| Role | สั่งงาน, parallel subagents | จำ context, รัน bash บน ASUSTOR |
|
||
| เชื่อมกันผ่าน | MCP client | MCP server (`/mcp` endpoint) |
|
||
|
||
---
|
||
|
||
### 6. Deploy Prerequisites
|
||
|
||
#### VLAN Requirements
|
||
|
||
ต้องเปิด path นี้ได้ก่อน deploy:
|
||
```
|
||
ASUSTOR (VLAN ใดก็ตาม) → QNAP VLAN 10 (MariaDB :3306, Gitea :3000)
|
||
```
|
||
หาก inter-VLAN routing ยังติด firewall อยู่ ต้อง allow subnet ของ ASUSTOR เข้า VLAN 10 ด้วย
|
||
|
||
#### Network Exposure Requirements
|
||
|
||
* Hermes API (`:8080`), Hermes proxy (`:8766`), และ MCP endpoint (`/mcp`) ต้อง bind หรือ firewall ให้อยู่เฉพาะ LAN/VPN ที่กำหนดเท่านั้น
|
||
* ห้ามเปิด Hermes API/proxy/MCP ตรงสู่ public internet
|
||
* Telegram webhook เป็น endpoint เดียวที่อาจต้องรับ traffic จาก internet และต้องอยู่หลัง reverse proxy ที่เปิด TLS, verify `X-Telegram-Bot-Api-Secret-Token`, ทำ IP/rate limit, และบันทึก request log
|
||
* หากใช้ Cloudflare Tunnel, Tailscale Funnel, หรือ reverse proxy ใด ๆ ต้องกำหนด allowlist และ audit config ก่อนเปิดใช้งานจริง
|
||
|
||
#### Secret Management Requirements
|
||
|
||
* Secret ทั้งหมด (`HERMES_PROXY_API_KEY`, `HERMES_TELEGRAM_BOT_TOKEN`, `HERMES_TELEGRAM_WEBHOOK_SECRET`, Gitea token, read-only DB credential) ต้องเก็บนอก repo
|
||
* ห้าม commit secret จริงใน `.env`, compose file, MCP config, ADR/spec, README, หรือ screenshot
|
||
* บน ASUSTOR ให้ใช้ secret store ที่มีอยู่ หรือไฟล์ environment นอก repo ที่จำกัด permission เฉพาะ admin/service account
|
||
* ต้องมี rotation plan สำหรับ API key/token และ revoke token ทันทีเมื่อเครื่อง client หายหรือ operator ออกจากทีม
|
||
* Verification ต้องรวม secret scan ก่อน rollout และหลังแก้ config
|
||
|
||
#### Gitea Token Requirements
|
||
|
||
* Default token ต้องเป็น read-only สำหรับอ่าน repo, issue, PR, CI status และ release metadata
|
||
* Write action เช่น create branch, create issue, create PR, หรือ trigger CI ต้องใช้ token แยกที่ scope แคบกว่า admin และต้องผ่าน Telegram explicit confirmation ก่อน
|
||
* ห้ามใช้ admin token กับ Hermes
|
||
* ห้ามใช้ token ที่สามารถ push ไป `main`/`master` หรือ bypass branch protection ได้
|
||
* Token ต้องมี expiry/rotation schedule และสามารถ revoke แยกตาม operator/service ได้
|
||
* ทุก write action ต้องบันทึก `transactionId`, token identity หรือ service identity, target repo, target branch, และผลลัพธ์ใน `hermes_operations_log`
|
||
|
||
#### Hermes Operations Log Requirements
|
||
|
||
* `hermes_operations_log` ต้องอยู่ใน Hermes-owned storage เท่านั้น เช่น SQLite/Postgres volume ภายใน Hermes stack หรือ structured log file ที่ส่งต่อไป log collector
|
||
* ห้ามเขียน Hermes DevOps operations ลง `audit_logs` ของ DMS ยกเว้น future DMS Telegram module ที่แยก ADR/spec และผ่าน DMS Backend API
|
||
* ต้องบันทึกอย่างน้อย `transactionId`, operator identity, command type, target system, status, createdAt, completedAt, และ error classification
|
||
* ต้อง redact command payload ที่อาจมี secret, token, file path sensitive, หรือ production document content
|
||
* Retention เริ่มต้น 90 วัน แล้ว archive/delete ตาม policy ของ DevOps logs
|
||
* Log storage ต้องจำกัดสิทธิ์อ่านเฉพาะ admin/operator ที่จำเป็น
|
||
|
||
#### Failure & Degradation Requirements
|
||
|
||
* Hermes, Telegram Bridge, MCP, และ hermes proxy ต้องเป็น optional DevOps tooling ไม่ใช่ dependency ของ DMS production runtime
|
||
* หาก Hermes stack ล่ม ผู้ใช้ DMS ต้องยังใช้งาน frontend/backend, Workflow Engine, notification, และ AI pipeline ตาม ADR-023A ได้ตามปกติ
|
||
* Degraded mode คือกลับไปใช้ IDE, Gitea UI, CI UI, SSH/manual ops, และ Codex/Devin local workflow ตามปกติ
|
||
* ห้ามให้ production deploy, Workflow Engine transition, AI inference, หรือ document ingestion รอ Hermes availability
|
||
* Monitoring ต้องแจ้งเตือนเฉพาะ operator/devops team ไม่ alert เป็น production DMS outage เว้นแต่มีผลกระทบจริงกับ DMS service
|
||
|
||
#### Monitoring & Alerting Requirements
|
||
|
||
* Hermes down, Telegram Bridge down, MCP unavailable, หรือ hermes proxy down ให้แจ้งเป็น DevOps warning ไม่ใช่ production DMS outage
|
||
* Repeated API key failure, webhook secret failure, Telegram allowlist rejection spike, หรือ rate limit spike ต้องแจ้งเป็น security alert
|
||
* Failed write-with-confirmation command เช่น create branch/issue/PR/trigger CI ต้องแจ้ง DevOps alert พร้อม `transactionId`
|
||
* หาก hermes proxy ได้รับ payload ที่คล้าย production document content, secret, token, password, หรือ storage path ต้องถือเป็น security incident และต้อง redact log ทันที
|
||
* Monitoring ต้องแยก dashboard/status ของ Hermes ออกจาก DMS production service health เพื่อไม่ให้ incident severity ปะปนกัน
|
||
* Alert ทุกประเภทต้อง link กลับไปยัง `hermes_operations_log` ด้วย `transactionId` เมื่อมี
|
||
|
||
#### ASUSTOR-Specific Notes
|
||
|
||
ASUSTOR ADM Docker บางรุ่นใช้ path `/share/` แทน `/volume1/` — รัน `df -h` บน ASUSTOR shell หลัง SSH เข้า NAS เพื่อดู shared folder mount แล้วแก้ path ใน `docker-compose.yml` ให้ตรง
|
||
|
||
#### ลำดับ Deploy ที่แนะนำ
|
||
|
||
```
|
||
1. สร้าง Telegram bot (@BotFather) → copy token
|
||
2. สร้าง SSH keypair บน ASUSTOR
|
||
3. copy files ขึ้น ASUSTOR → แก้ .env (ระวัง HERMES_PROXY_PORT=8766)
|
||
4. บน ASUSTOR shell: `docker compose up -d` → ทดสอบ Telegram
|
||
5. ทดสอบ hermes proxy จาก laptop
|
||
6. บน Windows PowerShell: ตั้ง `$env:OPENAI_BASE_URL = "http://<ASUSTOR_IP>:8766/v1"` → ทดสอบ Codex CLI สำหรับ coding/devops task เท่านั้น
|
||
7. ส่ง /schedule tasks ผ่าน Telegram
|
||
```
|
||
|
||
---
|
||
|
||
## Implementation Roadmap
|
||
|
||
### Rollout Stages
|
||
|
||
ADR-031 ต้อง rollout แบบเป็น stage เพื่อลดความเสี่ยง และห้ามข้ามไป stage ที่สูงกว่าโดยยังไม่ผ่าน verification gate ของ stage ก่อนหน้า:
|
||
|
||
1. **Stage 0 - Documentation Only:** สรุป boundary และ rollout plan ให้ stable ก่อน ยังไม่ deploy, ไม่เปิด network, ไม่เพิ่ม schema
|
||
2. **Stage 1 - Hermes Container LAN-only:** deploy Hermes container บน ASUSTOR แบบ LAN/VPN-only, ใช้ Redis/log store แยก, ยังไม่เปิด Telegram public webhook
|
||
3. **Stage 2 - Read-only Diagnostics:** เปิด Gitea read-only และ MariaDB masked/read-only diagnostics ตาม least privilege และ data minimization policy
|
||
4. **Stage 3 - Telegram Read-only DevOps:** เปิด Telegram DevOps commands เฉพาะ read-only เช่น `/status`, `/ci_status`, `/repo_summary`, `/audit_summary`
|
||
5. **Stage 4 - Write-with-confirmation DevOps:** เปิด action ที่เขียน Gitea/CI ได้เฉพาะ create branch/issue/PR/trigger CI/schedule audit พร้อม explicit confirmation และ `hermes_operations_log`
|
||
6. **Stage 5 - Developer AI Proxy:** เปิด `hermes proxy` สำหรับ coding/devops assistance เท่านั้น โดยห้าม production document payload, secrets, และ DMS AI runtime usage
|
||
|
||
### Stage Acceptance Gates
|
||
|
||
| Stage | Go/No-Go Gate |
|
||
|---|---|
|
||
| **Stage 0** | ADR boundary reviewed, locked decisions captured, no schema delta, no deploy files applied |
|
||
| **Stage 1** | LAN/VPN-only exposure confirmed, ASUSTOR runtime resource limits enforced, Hermes Redis/log store separated from DMS production |
|
||
| **Stage 2** | read-only DB grant verified, masked/redacted fields verified, Gitea read-only token verified, no direct storage mount |
|
||
| **Stage 3** | Telegram allowlist verified, webhook secret verified, rate limit verified, `hermes_operations_log` captures inbound/outbound transaction |
|
||
| **Stage 4** | explicit confirmation flow verified, forbidden action blocklist verified, branch protection and Gitea token scope verified |
|
||
| **Stage 5** | proxy LAN/VPN-only verified, no secrets/document payload test passed, proxy not wired into DMS AI runtime or document intelligence path |
|
||
|
||
### Stage Owner & Approval Matrix
|
||
|
||
| Stage | Required Owner/Approval |
|
||
|---|---|
|
||
| **Stage 0** | Architecture Team |
|
||
| **Stage 1** | DevOps/Admin |
|
||
| **Stage 2** | DBA/Security + DevOps |
|
||
| **Stage 3** | DevOps/Security |
|
||
| **Stage 4** | Architecture + Security + Repo Owner |
|
||
| **Stage 5** | Architecture + Security |
|
||
|
||
### Stage Rollback Matrix
|
||
|
||
| Stage | Rollback Action |
|
||
|---|---|
|
||
| **Stage 1** | Stop/remove Hermes container, keep `hermes_operations_log` for review, verify DMS production remains unaffected |
|
||
| **Stage 2** | Revoke DB/Gitea read-only credentials, disable MCP servers, confirm no direct storage mount exists |
|
||
| **Stage 3** | Unregister Telegram webhook, revoke Telegram bot token if needed, stop `HermesTelegramDispatcher` |
|
||
| **Stage 4** | Revoke Gitea write token, disable write commands, preserve operations log for audit/review |
|
||
| **Stage 5** | Unset `OPENAI_BASE_URL` on clients, stop hermes proxy, revoke proxy API key |
|
||
|
||
### Roadmap Items
|
||
|
||
1. **Hermes Telegram Scope:** จำกัด Telegram Bridge ของ Hermes ให้รองรับ DevOps commands เท่านั้น
|
||
2. **Notification Queue:** ปรับใช้โครงสร้าง `HermesTelegramDispatcher` เพื่อดึงงาน DevOps notification ออกจากคิว `hermes-notification-queue`
|
||
3. **Command Handling:** สร้าง Telegram Gateway Controller เพื่อรองรับ Webhook และส่งต่อไปยัง DevOps Command Router
|
||
4. **Logging:** เพิ่ม Hermes operations logging เพื่อบันทึกการทำงานของ Telegram ในทุกจุดที่เปลี่ยนผ่าน Transaction
|
||
5. **No DMS Schema Rollout:** ADR-031 ไม่เพิ่มหรือแก้ production DMS tables ใด ๆ รวมถึงไม่สร้าง `user_telegram_mapping`
|
||
|
||
---
|
||
|
||
## Verification Plan
|
||
|
||
1. **Resource Limit Test:** บน ASUSTOR shell รัน `docker inspect hermes_agent_lcbp3` และ `docker stats hermes_agent_lcbp3` เพื่อยืนยันว่า runtime enforce RAM ไม่เกิน 4GB และ CPU ไม่เกิน 2 Cores จริง ไม่ใช่แค่มีค่าใน compose file
|
||
2. **API Key Auth Test:** บน Windows PowerShell รัน `Invoke-WebRequest -Headers @{ "X-API-Key" = "wrong_key" } -Uri "http://<ASUSTOR_IP>:8080/api/v1/sync"` ต้องโดนบล็อกด้วยสิทธิ์ 401 Unauthorized
|
||
3. **Git Hooks Test:** ลองจงใจพิมพ์ `: any` หรือ `console.log` ลงในไฟล์ `.ts` แล้วกด `git commit` ระบบต้องทำการ `exit 1`
|
||
4. **Unit Test:** ทดสอบ `handleInboundCommand` ว่าสามารถแยกคำสั่ง `/` ออกจากข้อความปกติได้ถูกต้อง
|
||
5. **Queue Test:** ตรวจสอบว่า `BullMQ` ดึงงาน `telegram-devops-outbound` จาก `hermes-notification-queue` ไปประมวลผลและตอบกลับ Telegram ได้สำเร็จ
|
||
6. **Security Test:** ทดสอบว่า Telegram user ที่ไม่อยู่ใน `HERMES_TELEGRAM_ALLOWED_USER_IDS` ไม่สามารถใช้ DevOps commands ได้
|
||
7. **Schema Safety Test:** ตรวจสอบว่า ADR-031 rollout ไม่มี SQL delta หรือ migration ที่สร้าง `user_telegram_mapping`
|
||
8. **Secret Scan Test:** ตรวจสอบว่าไม่มี secret จริงใน repo/spec/compose/MCP config และ environment file ที่ใช้ deploy อยู่นอก repo พร้อม permission จำกัด
|
||
9. **Operations Log Test:** ตรวจสอบว่า Hermes operation ถูกบันทึกใน Hermes-owned log store, payload ถูก redact, และไม่มี write ไปยัง DMS `audit_logs`
|
||
10. **Failure Isolation Test:** ปิด Hermes container แล้วตรวจว่า DMS frontend/backend, Workflow Engine, AI pipeline, และ user-facing app ยังทำงานตามปกติ
|
||
11. **Monitoring Test:** จำลอง Hermes down, webhook auth failure, failed write command, และ proxy secret-like payload เพื่อยืนยัน alert severity/channel ถูกต้องและ log ถูก redact
|
||
|
||
---
|
||
|
||
## Related ADRs
|
||
|
||
- ADR-007: Error Handling Strategy
|
||
- ADR-008: Email Notification Strategy (BullMQ)
|
||
- ADR-016: Security & Authentication
|
||
- ADR-019: Hybrid Identifier Strategy (UUIDv7)
|
||
- ADR-023/ADR-023A: Unified AI Architecture และ AI isolation boundary
|
||
- ADR-031 v2.0: Cloud AI exception สำหรับ Hermes dev orchestration layer (ดู Locked Decisions v2.0)
|
||
|
||
---
|
||
|
||
## Change Log
|
||
|
||
| Date | Version | Changes |
|
||
|------|---------|---------|
|
||
| 2026-05-28 | 1.0.0 | Initial ADR creation - Merged from CONTEXT-ADR-031 and CONTEXT-ADR-031-Added |
|
||
| 2026-05-28 | 1.1.0 | Added sections 4–6 from CONTEXT-ADR-031-Added-2: Hermes Interface Modes, agy+Hermes MCP Integration, Deploy Prerequisites; fixed port conflict (hermes proxy :8766, not :8765) |
|
||
| 2026-05-29 | 1.1.1 | Aligned with CONTEXT-ADR-031.md grill-with-docs: fixed monorepo structure (flat layout), corrected file paths, updated repo URL to git.np-dms.work, added AGENTS.md v1.9.7 reference |
|
||
| 2026-05-29 | 1.1.2 | Linked root CONTEXT.md with specs/CONTEXT-ADR-031.md; fixed setup-context.sh paths; updated Devin/agy/Hermes symlink targets |
|
||
| 2026-05-29 | 2.0.0 | **v2.0 Rewrite** — grill-with-docs: Orchestration as primary concern; Added Autonomous Dev Loop architecture; Cloud AI exception (Data Classification Policy C); Separate Dev Qdrant on ASUSTOR; SOUL.md container-local journal; Sub-agent delegation (Cloud+MCP); Git identity hermes-bot + hermes/* branches + PR-only flow |
|
||
| 2026-05-29 | 2.0.1 | Step 1 context assembly: เพิ่ม `CONTEXT.md` (root domain terminology) เป็น selective context source สำหรับ DMS feature coding และ Schema/DB work tasks |
|