Directus Operating Rules — SSOT
Version: 1.2
Date: 2026-03-08 S107
Status: Active
Enforcement: Bắt buộc cho mọi Agent thao tác trên Directus
Lưu ý S107: 50+ Directus Flows (21 registry sync + 13 auto-ID), 135+ collections. Tạo collection MỚI → PHẢI tạo table_registry record (Registry Wiring Rule).
⚠️ CẢNH BÁO QUAN TRỌNG — ĐỌC TRƯỚC KHI LÀM BẤT CỨ GÌ:
- Schema changes (tạo collection, thêm field) → CHỈ DOT tools (
dot-schema-*). MCP CRUD tools sẽ BỊ 403.
- Data CRUD (items) → MCP tools OK.
- Quy trình DOT:
ls dot/bin/dot-schema-* → cat đọc pattern mẫu → tạo tool mới nếu cần → chmod +x → chạy.
- Đã xảy ra lỗi: Agent thử MCP
directus_create_item(collection: "directus_collections") → 403 → fallback curl → cũng sai. DOT là con đường DUY NHẤT.
I. NGUYÊN TẮC CỐT LÕI
Luật 1: 100% DÙNG DOT — KHÔNG CODE MỚI
Mọi thao tác Directus PHẢI qua DOT tools hoặc Directus Admin UI.
- Schema changes →
dot-schema-* tools hoặc Directus UI
- Content CRUD →
dot-content-* tools hoặc Directus API
- Flow setup →
dot-flow-* tools hoặc Directus UI
- Permissions →
dot-fix-permissions hoặc dot-permission-ensure
- Seed data →
dot-seed-* tools
KHÔNG BAO GIỜ:
- Viết custom API endpoint cho Directus
- Viết Cloud Function thay cho Directus Flow
- Viết middleware xử lý auth thay cho Directus built-in
- Viết script SQL trực tiếp vào MySQL (trừ emergency)
Luật 2: ASSEMBLY FIRST
Trước khi làm gì, kiểm tra Directus đã có sẵn chưa:
- Flows — Automation, webhooks, scheduled tasks
- Permissions — Role-based access control
- API — REST/GraphQL endpoints cho mọi collection
- Webhooks — Event notifications
- Extensions — Chỉ khi built-in không đủ, VÀ phải xin phép User
Luật 3: DIRECTUS LÀ SSOT CHO STRUCTURED DATA
- Directus sở hữu: tasks, task_comments, ai_tasks, contacts, organizations, pages, posts, blocks...
- Agent Data sở hữu: knowledge documents, session reports, architecture docs
- KHÔNG trùng lặp data giữa 2 hệ thống
- Sync 1 chiều duy nhất cho mỗi collection
Luật 4: AI AGENT TRUY CẬP QUA ĐƯỜNG CHUẨN
- Claude family (Desktop, Code, AI): Directus STDIO MCP (10 tools, toàn bộ collections)
- Codex + GPT: OPS Proxy HTTP (
ops.incomexsaigoncorp.vn) — 23 collections
- Auth: X-API-Key → Nginx inject Directus AI Agent token
- KHÔNG cho AI agent truy cập trực tiếp Directus admin
- Chi tiết đường kết nối:
search_knowledge("directus connections tools")
Luật 5: THÊM COLLECTION/FIELD PHẢI CẬP NHẬT SSOT
Khi thêm collection hoặc field mới:
- Cập nhật
directus-collections.md
- Cập nhật permissions nếu cần
- Nếu cần sync → tạo/update Flow → cập nhật
directus-flows.md
- Nếu expose cho AI → cập nhật OPS proxy config + OpenAPI spec
| Tool |
Mô tả |
| dot-schema-apply |
Apply schema changes |
| dot-schema-blog-ensure |
Ensure blog schema exists |
| dot-schema-ensure |
General schema ensure |
| dot-schema-feedback-ensure |
Ensure feedback schema |
| dot-schema-knowledge-ensure |
Ensure knowledge schema |
| dot-schema-navigation-ensure |
Ensure navigation schema |
| dot-schema-redirects-ensure |
Ensure redirects schema |
| dot-schema-tasks-ensure |
Ensure tasks schema |
| dot-schema-workflows-ensure |
Ensure workflows schema (Sprint 1) |
| dot-schema-checkpoints-ensure |
Ensure task_checkpoints schema (Sprint 1) |
| dot-schema-comments-extend |
Extend task_comments with workflow fields (Sprint 1) |
Content CRUD (5 tools)
| Tool |
Mô tả |
| dot-content-approve |
Approve content item: dot-content-approve <id> [collection] [status] |
| dot-content-create |
Create content: dot-content-create <collection> --title "Title" |
| dot-content-delete |
Delete content: dot-content-delete <collection> <id> [--soft|--force] |
| dot-content-list |
List content: dot-content-list [status] [collection] |
| dot-content-update |
Update content: dot-content-update <collection> <id> --field value |
| Tool |
Mô tả |
| dot-knowledge-ingest |
Ingest single document |
| dot-knowledge-ingest-batch |
Batch ingest documents |
| dot-knowledge-info |
Show knowledge stats |
| dot-knowledge-search |
Search knowledge base |
| dot-knowledge-sync |
Sync knowledge |
| dot-knowledge-sync-agentdata |
Sync Agent Data ↔ Directus |
| Tool |
Mô tả |
| dot-flow-setup-sync |
Setup Knowledge sync flows |
| dot-flow-setup-tasks-sync |
Setup Tasks + Comments sync flows |
| dot-rollback |
Delete all [DOT] flows |
| Tool |
Mô tả |
| dot-ai-bridge-check |
Check AI bridge connectivity |
| dot-ai-connect-all |
Verify all AI platform connections |
| dot-ai-gateway-setup |
Setup AI gateway |
| dot-ai-manifest |
Show AI agent manifest |
| dot-ai-start |
Start AI infrastructure |
| dot-ai-status |
Check AI services status |
| dot-ai-user-setup |
Setup AI user in Directus |
| dot-mcp-config-claude |
Configure Claude Desktop MCP |
| dot-mcp-status |
Check MCP status |
| dot-mcp-stdio-restart |
Restart MCP stdio server |
| dot-mcp-verify |
Verify MCP connectivity |
| Tool |
Mô tả |
| dot-local-up |
Start local dev environment |
| dot-local-down |
Stop local dev environment |
| dot-local-restart |
Restart local services |
| dot-local-status |
Check local container status |
| dot-local-logs |
View local container logs |
| Tool |
Mô tả |
| dot-agent-up |
Start agent services |
| dot-agent-down |
Stop agent services |
| dot-agent-status |
Check agent status |
| Tool |
Mô tả |
| dot-fix-gap3 |
Fix gap3 permissions |
| dot-fix-knowledge-permissions |
Fix knowledge collection permissions |
| dot-fix-permissions |
Fix general permissions |
| dot-permission-ensure |
Ensure permissions are correct |
| Tool |
Mô tả |
| dot-auth |
Authenticate with Directus |
| dot-backup |
Backup Directus data |
| dot-clean-data |
Clean stale data |
| dot-cost-audit |
Audit cloud costs |
| dot-health-check |
Comprehensive health check |
| dot-sync-check |
Verify local/cloud sync |
| dot-test-login |
Test Directus login |
| dot-token |
Get Directus access token |
| dot-ops-status |
Check OPS proxy status |
| Tool |
Mô tả |
| dot-seed-agency-os |
Seed Agency OS data |
| dot-seed-knowledge-test |
Seed test knowledge data |
| Tool |
Mô tả |
| dot-verify |
General verification |
| dot-verify-ai-connections |
Verify AI connections |
| dot-e2e-test |
End-to-end test |
| dot-arch-check |
Architecture compliance check |
| Tool |
Mô tả |
| dot-vector-audit |
Audit vector consistency |
| dot-vector-audit-schedule |
Schedule vector audits |
| Tool |
Mô tả |
| dot-gpt-setup |
Setup GPT Actions |
| dot-gpt-copy-spec |
Copy OpenAPI spec for GPT |
| Tool |
Mô tả |
| dot-apply |
Apply configurations |
| dot-claude-restart |
Restart Claude Desktop |
| dot-env-backup |
Backup .env files |
| dot-env-restore |
Restore .env files |
| dot-gemini-setup |
Setup Gemini connection |
| dot-nav-remove-item |
Remove navigation item |
| dot-spider |
Content spider/crawler |
| dot-start-all |
Start all services |
| dot-web28-complete |
Legacy completion tool |
VPS đã có 75 tools (TD-041 RESOLVED, CONN-FINAL 2026-02-28). Đường dẫn: /opt/incomex/dot/bin/.
IV. OPS PROXY RULES
Whitelist
| Scope |
Collections |
Methods |
| Core (3) |
tasks, task_comments, ai_tasks |
GET, POST, PATCH, DELETE |
| Extended (20) |
posts, pages, contacts, organizations, help_articles, globals, navigation, + 13 khác |
GET, POST, PATCH (18 RW + 2 RO) |
| Tổng: 23 collections |
Chi tiết: search_knowledge("directus connections tools") |
|
Khi thêm collection mới (VD: workflows, task_checkpoints) → cần thêm vào nginx whitelist + OpenAPI spec. Xem mục "Thêm collection vào OPS Proxy" bên dưới.
Security
- Auth: X-API-Key header (Nginx validate)
- Backend: Directus AI Agent token inject via /etc/nginx/secrets/directus_ai_token.conf
- Rate limit: 10 req/s, burst 20
- CORS: ai.incomexsaigoncorp.vn, vps.incomexsaigoncorp.vn, ops.incomexsaigoncorp.vn
- Catch-all: 404 (non-whitelisted paths)
- Legacy /ops/ path: 410 DEPRECATED
Thêm collection vào OPS Proxy
- Thêm location block trong nginx config
- Cập nhật OpenAPI spec (openapi-ops.json)
- Cập nhật document này
- Push qua Git → CI/CD deploy
- GPT: refresh Actions schema
V. CHANGELOG
| Date |
Version |
Change |
| 2026-02-28 |
1.0 |
Initial creation từ audit data |
| 2026-03-03 |
1.1 |
Thêm cảnh báo DOT schema, fix OPS Proxy 3→23 cols, fix VPS 50→75 tools, fix Luật 4 đường kết nối |