AI Copilot (HITL)
LumiBase Studio đi kèm một AI Copilot có thể nhận lệnh ngôn ngữ tự nhiên từ admin và thực thi các skill đã được khai báo trên CMS. Đây là bước seed của Agent Harness Layer: agent nhận goal/context/quyền hạn qua harness, gọi tool theo registry, bị đánh giá rủi ro và để lại audit trail. Mọi hành động nguy hiểm (đụng schema hoặc xoá dữ liệu) đều phải qua Human-in-the-Loop (HITL): AI tạo ai_approvals row chờ admin duyệt thay vì execute trực tiếp.
Tài liệu lịch sử của giai đoạn triển khai (chia 4 module cho AI agent) nằm ở
ai-first-specification.md. Blueprint chiến lược để mở rộng Copilot thành control plane cho agent nằm ởagent-harness-layer.md. File này tập trung vào hành vi end-user và contract API.
Kiến trúc 4 module
| Module | File chính | Trách nhiệm |
|---|---|---|
| A. Schema | packages/database/src/schema/ai.ts (ai_approvals) | Lưu trạng thái phê duyệt |
| B. Harness | apps/cms/src/services/ai-harness.ts (AISecureHarness) | Validate skill, check capability, evaluate risk, execute hoặc gate qua HITL |
| C. Routes | apps/cms/src/routes/ai.ts (aiRouter) | /api/v1/ai/chat, /api/v1/ai/approvals, /api/v1/ai/approvals/:id/decide |
| D. Studio UI | apps/studio/src/components/ai-assistant.tsx, apps/studio/src/modules/settings/ai-approvals.tsx | Floating chat panel + Approvals dashboard |
Quan hệ với Agent Harness Layer
AI Copilot hiện tại xử lý một vòng lặp ngắn: chat → chọn skill → risk/capability check → execute hoặc tạo approval. Agent Harness Layer mở rộng cùng nguyên tắc này cho vòng lặp dài hơn:
Goal → Run → Plan → Tool calls → Evaluation → Approval → Artifact commit → Memory update
Vì vậy các bảng hiện có được xem như seed:
ai_approvals→ tiền thân của approval gate tổng quát cho plan/tool/artifact.ai_conversations+ai_messages→ context memory ngắn hạn.ai_embeddings→ dành cho RAG knowledge base theo site/collection/item. Hiện chưa có code nào đọc hoặc ghi bảng này (#581).CORE_SKILLS→ tiền thân của tool registry có input schema, capability, rate limit và risk policy.
CORE_SKILLS registry
Skills được khai báo tập trung trong packages/ai-skills/src/skills.ts. Mỗi skill chứa:
name,description(description dùng cho LLM tool calling).parameters— JSON Schema OpenAI-compatible.requiredCapabilities— phải thỏa mãn so với capability của session.
Skills hiện có: listCollections, createCollection, deleteCollection, createField, deleteField, listItems, createItem, updateItem, deleteItem.
Helper getAISkillsAsTools() trả về dạng OpenAI function-calling tool list — dùng khi tích hợp LLM thật.
Risk evaluation rules
Một skill được phân loại dangerous (cần HITL) nếu:
- Yêu cầu capability
'schema:write', hoặc - Tên skill bắt đầu bằng
'delete'.
Ngược lại là safe → execute trực tiếp.
Wildcard '*' trong user capabilities thoả mãn mọi yêu cầu.
Luồng end-to-end
┌──────────────┐ POST /api/v1/ai/chat
│ AI Assistant │ ─────────► [Hono router]
│ (Studio UI) │ │
└──────┬───────┘ ▼
│ [AISecureHarness.execute]
│ │
│ ┌──────────┼──────────┐
│ ▼ ▼ ▼
│ validate capability risk
│ skill check eval
│ │ │ │
│ └──────────┴──────────┘
│ │
│ ┌────────┴────────┐
│ ▼ ▼
│ safe → run dangerous →
│ skill direct INSERT ai_approvals
│ │
│ status=pending
│ ▼
│ respond { status:
│ 'pending_approval',
│ approvalId }
│ │
│ ┌──────────────────┘
│ │
▼ ▼
┌──────────────┐ GET /api/v1/ai/approvals
│ Approvals │ ─────────► [list pending for siteId]
│ Dashboard │
│ │ POST /api/v1/ai/approvals/:id/decide
│ │ ─────────► executeApproved | rejectApproval
└──────────────┘
API contract
POST /api/v1/ai/chat
Request: { "message": string } (1-2000 chars sau trim).
Response 200: { "data": { "status": "executed" | "pending_approval" | "denied", "data"?, "approvalId"?, "message"? } }.
Response 400: validation error.
GET /api/v1/ai/approvals
Trả về tối đa 100 approval có status='pending' trong site hiện tại, sắp xếp createdAt DESC.
POST /api/v1/ai/approvals/:id/decide
Body: { "decision": "approved" | "rejected" }.
"approved"→ harness execute skill với arguments đã lưu, cập nhật status thànhapproved(nếu execute thành công). Nếu skill thất bại, giữ statuspendingđể admin retry."rejected"→ cập nhật statusrejected.
Mọi truy vấn đều scope siteId — request từ site B không bao giờ thấy bản ghi của site A (HTTP 403, không tiết lộ existence).
Studio UI
AI Assistant panel
- Floating button 48×48px ở
bottom: 24px, right: 24px. - Click mở panel 320×480px, glassmorphism (backdrop-blur).
- Phân biệt vai trò
uservsassistant. - Hiển thị badge
pending_approvalkhi áp dụng. - History tối đa 50 messages, reset khi reload trang.
Approvals Dashboard
apps/studio/src/modules/settings/ai-approvals.tsx.- Card view, mỗi card:
skillName,arguments(JSON pretty 2 spaces),context. - Hai nút Approve / Reject với loading state — disable cả 2 khi đang xử lý.
- Empty state khi không có pending.
Multi-tenancy
- Mọi insert/select/update bảng
ai_approvalsđềuWHERE siteId = currentSiteId. - Cross-site access → 403, không cho biết bản ghi có tồn tại ở site khác hay không.
- Tenant middleware (
withTenant) bắt buộc resolvesiteIdtrước khi router AI hoạt động.
Tích hợp LLM thật & Context Memory (RAG)
LumiBase Copilot đã tích hợp hoàn chỉnh với các mô hình ngôn ngữ lớn (LLM) và hệ thống lưu trữ vector/lịch sử trò chuyện:
1. LLM Providers
Hệ thống hỗ trợ nhiều LLM providers (cấu hình qua LLM_PROVIDER env, model qua LLM_MODEL):
- OpenAI: Sử dụng Chat Completions tool calling (ví dụ
gpt-4.1-nano, mặc địnhgpt-4o-mini). - Anthropic / Claude: Sử dụng dòng mô hình Claude thông qua native
tool_use. - Gemini: Sử dụng Gemini REST
generateContentvới function declarations. - Workers AI: Chạy trực tiếp tại edge trên hạ tầng Cloudflare Workers AI (mặc định sử dụng
@cf/meta/llama-3.1-8b-instruct). - Echo: Bộ khớp từ khóa (fallback mock) dùng cho môi trường test hoặc khi thiếu API credentials.
2. Context Memory (Lịch sử hội thoại)
Bảng ai_conversations và ai_messages được dùng để lưu trữ trạng thái các luồng trò chuyện:
- Mỗi khi gửi message lên
/api/v1/ai/chat, hệ thống sẽ load tối đa 20 messages gần nhất để làm ngữ cảnh (context window) truyền vào LLM. Từ #582 cả route đồng bộ lẫn workerPrefer: respond-asyncđều dùng chungloadCopilotHistory(apps/cms/src/services/copilot-history.ts); trước đó cả hai đọc 20 message cũ nhất, nên từ message thứ 21 trở đi lượt user vừa gửi không có trong request. - Cửa sổ luôn mở đầu bằng một lượt user (nếu cắt rơi vào message assistant thì bỏ message đó) và kết thúc bằng lượt user vừa gửi. System prompt của Copilot gửi riêng nên không bao giờ bị cắt.
- Mỗi tin nhắn chat tối đa 2.000 ký tự. Đầu vào và đầu ra mô hình tuân theo chính sách ngữ cảnh bên dưới.
- Model trả nhiều tool call thì chỉ call đầu tiên được thực thi. Arguments không phải JSON hợp lệ trả
500một lần, không retry và không ghi gì. - Hỗ trợ đầy đủ các API quản lý:
GET /conversations,GET /conversations/:id/messages,DELETE /conversations/:id. - Một hội thoại thuộc về user đã tạo nó (#579). Thành viên khác của site nhận
404khi đọc messages,DELETEkhông xoá gì, vàPOST /chatvớiconversationIdđó sẽ mở một hội thoại mới cho người gọi. Caller dùng API key chỉ sở hữu các hội thoại được ghi với chính key đó (api_key_id, migration0023), nên key này không list, đọc, xoá hay nối vào hội thoại của key khác được. Hội thoại không có user id tạo trước0023không ghi key nào nên không API key nào sở hữu chúng.
Ranh giới tin cậy (#579)
- Chỉ dẫn và dữ liệu. Chỉ Copilot chat dùng system prompt của Copilot và danh sách tool. Mọi lời gọi model khác (skill sinh nội dung, constitution compiler và judge, intent compiler, decisions) gửi chỉ dẫn riêng vào system slot của provider và tắt tool (
completeWithInstructions). Constitution judge gửi nội dung cần chấm làm user turn duy nhất, trong một khối<untrusted>. Một test source-scan sẽ fail khi có lời gọi mới bỏ qua quy tắc này. - Mỗi lượt một tool call, output của tool không vào prompt.
POST /chatchỉ thực thi tool call đầu tiên mà model trả về, và kết quả tool trả cho client chứ không quay lại model. Một tấn công nhiều bước vì vậy cần một lượt user cho mỗi bước, và mỗi lượt được phân quyền riêng. - Model không cấp quyền. Harness kiểm capability, input schema chuẩn, và quyền theo row và field của người gọi ở mọi tool call, bất kể model yêu cầu gì.
apps/cms/eval/prompt-injection/dataset.v1.jsonliệt kê các tấn công và benign control, được chạy lại như thể model làm theo kẻ tấn công. - Redaction.
listSettingsche các field chứa secret theo cùng quy tắc vớiGET /api/v1/settings.
3. Skill sinh nội dung có context (aiSuggestField và aiContentAssist)
Hiện cả hai skill đều không chạy vector search (#581). embedding-service.ts (OpenAI text-embedding-3-small, Workers AI @cf/baai/bge-base-en-v1.5) và bảng ai_embeddings có tồn tại, nhưng chưa có đường code nào gọi hoặc ghi vào chúng.
aiSuggestField: gửi cho model tên các field hiện có của collection và mô tả của admin.aiContentAssist: gửi tối đa 3 item mẫu của collection, là các item cập nhật gần nhất mà caller được đọc.ItemServiceáp quy tắc tenant, row và field, nên field bị ẩn, item của site khác hay item ngoài row rule không bao giờ tới model. Một lần cập nhật, xoá hay thu hồi quyền có hiệu lực ngay ở lần gọi kế tiếp. Chỉstatusvàdatacủa từng mẫu được gửi, không gửi metadata của row. Các mẫu không phụ thuộc vào instruction.apps/cms/eval/retrieval/dataset.v1.jsonghi baseline trên dataset đó (Recall@3 0.5, MRR@3 0.46).- Các primitive embedding throw
EMBEDDING_DIMENSION_MISMATCHhoặcEMBEDDING_RESPONSE_INVALIDkhi so sánh vector khác kích thước hoặc khi provider trả sai số lượng hay kích thước vector.
Property-based testing
Hệ thống có 15 property tests (fast-check, ≥100 iterations) được liệt kê đầy đủ trong .kiro/specs/ai-first-cms-engine/design.md mục "Correctness Properties". Các test ở:
apps/cms/src/services/__tests__/ai-harness-*.property.test.ts— Properties 1-8 (Module B).apps/cms/src/routes/__tests__/ai-*.property.test.ts— Properties 9-12 (Module C).apps/studio/src/modules/settings/__tests__/— Properties 13-14 (Module D).packages/database/src/__tests__/— Property 15 (round-trip).
Ngân sách ngữ cảnh và trích dẫn nguồn
Đặt LLM_CONTEXT_WINDOW_TOKENS theo cửa sổ mà mô hình triển khai hỗ trợ.
Nếu chưa đặt, mô hình đã biết dùng mức trần ứng dụng 32.768. Tên mô hình tùy
chỉnh cần khai báo cửa sổ. Thiếu cửa sổ hoặc giá trị không hợp lệ thì mỗi lần
gọi mô hình trả LLM_CONTEXT_LIMIT trước khi gọi mạng; route không gọi mô hình
(ví dụ MCP tools/list) vẫn chạy bình thường. Trước khi gọi mạng, provider tính byte UTF-8 sau
serialize làm cận trên thận trọng cho token văn bản, chừa đầu ra (thường 1.024
token) và tính cả công cụ, phần đóng gói message. Hệ thống bỏ lịch sử cũ trước,
giữ chính sách hệ thống, định nghĩa công cụ và yêu cầu mới nhất. Yêu cầu quá dài
trả HTTP 413 với LLM_CONTEXT_LIMIT. Giới hạn tần suất, phản hồi không hợp lệ và
mất kết nối đều có mã lỗi để xử lý; không tự ghi hoặc tự sửa bằng lần gọi mới.
Để yêu cầu trích dẫn, truyền grounded: true cho aiContentAssist. Chỉ trường
mẫu hiện tại được phép đọc mới đi vào tập bằng chứng. Nội dung chấp nhận được
gồm toàn bộ các đoạn trích đúng nguyên văn; trích dẫn chỉ ra trường và mã item.
Khi thiếu bằng chứng, trả nội dung rỗng và abstained: true; nội dung bịa, cũ
hoặc thiếu nguồn bị từ chối. Trích dẫn nguyên văn xác định xuất xứ; độ đúng của
nguồn và mức phù hợp vẫn cần đánh giá. Nên từ chối trả lời khi nguồn mâu thuẫn
hoặc không liên quan. Mặc định vẫn cho phép viết tự do.
Chạy pnpm -F @lumibase/cms eval:grounding để tái lập baseline tổng hợp cho
hợp đồng thực thi. v1 cần đạt 12/12 trường hợp, bao gồm trích đoạn Anh/Việt,
số liệu bị sửa, nguồn cũ hoặc khác tenant, nguồn mâu thuẫn và từ chối trả lời.
Kết quả đo bộ xác thực; độ chính xác trên công việc biên tập cần dữ liệu riêng.