abs-zalo-bot 0.8.0 → 0.8.2

package/README.md

@@ -188,6 +188,28 @@ For profile-aware quality, select `gateway_skill = "your-owner-authored-hermes-s
 
 ---
 
+## 🎭 5-Layer Agent Scaffolding (`templates/zalo-agent-scaffolding/`)
+
+Turn raw command-line AI into a warm, reliable, enterprise-grade Zalo AI Assistant in 60 seconds across 5 structured knowledge layers:
+
+| Layer | File | Purpose |
+| :--- | :--- | :--- |
+| **1. Soul** | `template_soul.md` | Core service philosophy, patience, empathy & outcome-driven mindset |
+| **2. Persona** | `template_persona.md` | Natural Vietnamese mobile chat tone, anti-AI-slop & F-shape reading layout |
+| **3. Identity** | `template_identity.md` | Role definition, RBAC boundaries, autonomous actions vs owner approval |
+| **4. Memory** | `template_memory.md` | Durable facts storage for recurring customers without context bloat |
+| **5. Context** | `template_context.md` | Business catalog, pricing packages, sales policies & intake workflows |
+
+### ⚡ 1-Command Setup
+To scaffold a complete 5-layer profile for your Hermes Agent, simply run:
+```bash
+bash templates/zalo-agent-scaffolding/setup.sh my-zalo-assistant
+hermes --profile my-zalo-assistant
+```
+*Read full documentation at [`docs/5-layer-agent-framework.md`](docs/5-layer-agent-framework.md).*
+
+---
+
 ## 🧠 Hermes Agent Starter Kit (`hermes-plugin/starter-kit/`)
 
 Ready-to-use "Digital Brain" template for Hermes Agent:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abs-zalo-bot",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "type": "module",
   "description": "ABS Zalo Agent Engine — Free, Transparent & Autonomous Zalo AI Agent Engine for Hermes, Claude Code & Codex. Dual Personal QR + Official OA, Group Administration, Lead Intel, Polls, Reactions & MCP Server.",
   "author": "teddiesloco",

package/src/message_debounce.js

@@ -0,0 +1,42 @@
+/**
+ * Message Debounce — gom bọt chat liên tiếp từ cùng 1 người trong cùng 1 luồng.
+ *
+ * Người Việt thường nhắn 3–4 câu ngắn liên tục trong 1–2 giây:
+ *   "anh ơi" → "giá tour Phú Quý" → "cho 3 người cuối tuần"
+ * Nếu không gom lại, Agent sẽ chạy 3 LLM call song song, trả lời đè nhau.
+ *
+ * YAGNI: Không cần queue phức tạp. Map<key, {timer, texts[]}> là đủ.
+ */
+
+const DEFAULT_WINDOW_MS = 1_800; // 1.8s — đủ để người gõ thêm câu, không làm khách đợi lâu
+
+/**
+ * @param {Map} pending   - Shared state: Map<key, {timer, parts, resolve}>
+ * @param {string} key    - "<accountId>:<sourceId>:<senderId>"
+ * @param {string} text   - Nội dung tin nhắn vừa tới
+ * @param {Function} flush - Callback khi cửa sổ đóng: flush(key, combinedText)
+ * @param {number} [windowMs]
+ */
+export function debounceMessage(pending, key, text, flush, windowMs = DEFAULT_WINDOW_MS) {
+  const entry = pending.get(key);
+  if (entry) {
+    clearTimeout(entry.timer);
+    entry.parts.push(text);
+  } else {
+    pending.set(key, { parts: [text], timer: null });
+  }
+  const slot = pending.get(key);
+  slot.timer = setTimeout(() => {
+    pending.delete(key);
+    flush(key, slot.parts.join("\n"));
+  }, windowMs);
+}
+
+/**
+ * Xây debounce key từ normalized event.
+ */
+export function debounceKey(event) {
+  return `${event.account_id}:${event.source_id}:${event.sender_id}`;
+}
+
+export { DEFAULT_WINDOW_MS };

package/src/quote_resolver.js

@@ -0,0 +1,65 @@
+/**
+ * Quote Resolution — giải mã tin nhắn trích dẫn (reply/quote) trong nhóm Zalo.
+ *
+ * Khi khách quote một ảnh cũ rồi gõ "Cái này còn hàng không?", Zalo gửi:
+ *   { quote: { msgId, content: { ... } } }
+ * Nếu Agent chỉ đọc text hiện tại, nó sẽ hỏi ngược "Cái nào ạ?" — trải nghiệm tệ.
+ *
+ * Module này extract nội dung quoted và dán vào context prompt dưới dạng:
+ *   [Trích dẫn] <nội dung tin gốc>
+ */
+
+import { extractText } from "./schema.js";
+
+/**
+ * Giải mã payload quote từ Zalo message data.
+ * @param {object|undefined} quote   - data.quote từ raw Zalo message
+ * @returns {string}                 - "" nếu không có / không đọc được
+ */
+export function resolveQuoteText(quote) {
+  if (!quote) return "";
+
+  // Zalo quote payload có thể chứa content.title hoặc content trực tiếp
+  const content = quote.content ?? quote.msg ?? quote;
+
+  // Text thẳng
+  if (typeof content === "string" && content.trim()) {
+    return content.trim().slice(0, 500);
+  }
+
+  // Content là object (ảnh, file, tin nhắn có cấu trúc)
+  if (typeof content === "object" && content !== null) {
+    // Ưu tiên title (sticker name, file name, album title)
+    const title = content.title || content.name || "";
+    const body = extractText(content);
+    // extractText thường trả về title khi không có body thật — loại trùng
+    const combined = (body && body !== title)
+      ? [title, body].filter(Boolean).join(" — ").trim()
+      : title.trim();
+    if (combined) return combined.slice(0, 500);
+
+    // Fallback: loại media
+    const mediaType =
+      content.type === 2 ? "[Ảnh]"
+      : content.type === 3 ? "[Video]"
+      : content.type === 5 ? "[File]"
+      : content.type === 6 ? "[Nhãn dán]"
+      : content.type === 8 ? "[Audio]"
+      : "[Nội dung đa phương tiện]";
+    return mediaType;
+  }
+
+  return "";
+}
+
+/**
+ * Nếu event có quoted content, gắn thêm prefix [Trích dẫn] vào text để Agent hiểu ngữ cảnh.
+ * @param {object} event - Normalized event từ schema.js
+ * @param {object|undefined} rawQuote - data.quote từ raw Zalo message
+ * @returns {string}     - text đã kèm ngữ cảnh trích dẫn
+ */
+export function enrichTextWithQuote(event, rawQuote) {
+  const quoteText = resolveQuoteText(rawQuote);
+  if (!quoteText) return event.text;
+  return `[Trích dẫn] ${quoteText}\n${event.text}`;
+}