5 Feature Flags
| Flag Key | Mặc định | Khi bật |
|---|---|---|
| v3_pipeline_enabled | false | Dùng Pipeline 8 stage thay vì runLoop() cũ |
| v3_memory_enabled | false | Bật episodic memory flush khi compact — lưu tóm tắt phiên vào L1 |
| v3_retrieval_enabled | false | Auto-inject L0 memory từ L2 (pgvector) vào system prompt |
| self_evolution_metrics | false | Thu thập metrics hiệu suất sau mỗi run — latency, tool usage, token cost |
| self_evolution_suggestions | false | Tạo đề xuất cải tiến từ metrics tích lũy — hiển thị trên Evolution tab |
Tất cả flags lưu trong agents.other_config JSONB. Whitelist validation qua IsV3FlagKey().
Luồng quyết định Runtime
from other_config JSONB"] S --> F1{"v3_pipeline_enabled?"} F1 -->|"false"| V2["runLoop
v2 path — không thay đổi"] F1 -->|"true"| V3["runViaPipeline
v3 path — 8 stages"] V3 --> F2{"v3_memory_enabled?"} F2 -->|"true"| MEM["MemoryFlush ON
Flush episodic sau compact"] F2 -->|"false"| NOMEM["MemoryFlush OFF"] V3 --> F3{"v3_retrieval_enabled?"} F3 -->|"true"| RET["AutoInject ON
L0 inject vào ContextStage"] F3 -->|"false"| NORET["AutoInject OFF"] V3 --> F4{"self_evolution_metrics?"} F4 -->|"true"| EVO["Metrics ON
Ghi metrics async sau run"] F4 -->|"false"| NOEVO["Metrics OFF"]
Chiến lược Migration — 5 bước
Bật Pipeline cho 1 agent test
Chọn 1 agent ít quan trọng. Bật v3_pipeline_enabled. Kiểm tra agent vẫn hoạt động bình thường — response đúng, tool calls thành công. Monitor logs 1–2 giờ.
Bật Memory cho agent test
Bật v3_memory_enabled và v3_retrieval_enabled. Kiểm tra L0 inject hoạt động — sau 1 session, session tiếp theo có nhớ ngữ cảnh không.
Bật Metrics
Bật self_evolution_metrics. Theo dõi Evolution tab — kiểm tra metrics latency, token count, tool call frequency được ghi đúng. Chạy ít nhất 10 requests để có dữ liệu.
Roll out cho nhiều agent hơn
Sau khi xác nhận agent test hoạt động ổn định (≥24h), bật v3 cho từng agent production. Bật từng flag riêng biệt — không bật tất cả cùng lúc. Theo dõi metrics sau mỗi batch.
Bật Self-Evolution Suggestions
Sau khi có đủ metrics (≥50 runs), bật self_evolution_suggestions. Duyệt đề xuất trên Evolution tab — approve thủ công, không có auto-apply.
Rollback
- Tắt flag → agent quay về v2 ngay lập tức, không cần restart
- Dữ liệu v3 (episodic summaries, metrics, vault) không bị mất — chỉ không sử dụng
- Khi bật lại flag, dữ liệu cũ vẫn còn và được dùng tiếp
- Không cần migration down — tất cả changes là additive
Pre-flight Checklist
API Quản lý Flags
Đọc tất cả v3 flags hiện tại của agent. Trả về object key-value với trạng thái từng flag.
Cập nhật một hoặc nhiều flags. Chỉ chấp nhận keys trong whitelist — validation qua IsV3FlagKey(). Keys không hợp lệ bị từ chối với lỗi 400.
v2 vs v3 — Workspace Resolution
Logic rải rác
- Logic nằm trong loop_context.go dòng 107–212
- Dual-key gây nhầm lẫn giữa agent_id và user_id
- Khó test — không có unit test độc lập
- Bảo trì khó — mỗi thay đổi có thể break nhiều nơi
Package riêng, cấu trúc rõ ràng
- Package internal/workspace/ có trách nhiệm rõ ràng
- Resolver có cấu trúc — 1 hàm duy nhất xử lý tất cả kịch bản
- 6 kịch bản test đầy đủ — mỗi case được verify độc lập
- Bất biến sau ContextStage — không thể thay đổi giữa chừng pipeline
6 Kịch bản Workspace Resolution
| # | Kịch bản | Đường dẫn Workspace | Mô tả |
|---|---|---|---|
| 1 | Team | workspace/teams/{team_id} | Workspace chung, tất cả thành viên chia sẻ |
| 2 | Open Agent | workspace/agents/{agent_id}/users/{user_id} | Mỗi user có không gian riêng với agent |
| 3 | Predefined + User | workspace/agents/{agent_id} + USER.md | Workspace chung + file cấu hình per-user |
| 4 | Predefined | workspace/agents/{agent_id} | Workspace chung cho agent predefined |
| 5 | Tenant Root | workspace/tenants/{tenant_id} | Workspace gốc của tenant (admin) |
| 6 | Fallback | workspace/default | Mặc định — read-only, không có agent context |
Enforcement vs Suggestion
System prompt chỉ "đề nghị" agent làm việc trong workspace:
"Bạn nên làm việc trong workspace.
Đây là thư mục được khuyến nghị."
→ Agent có thể bỏ qua, truy cập file tùy ý.
System prompt đưa ra chỉ thị bắt buộc với ngữ cảnh rõ ràng:
"BẮT BUỘC làm việc trong:
{workspace_path}
Truy cập ngoài phạm vi bị chặn."
→ Agent phải tuân thủ, path được inject chính xác.
PromptBuilder — Template System
Nối chuỗi cứng nhắc
- Dùng fmt.Sprintf nối trực tiếp
- Thứ tự sections cứng — không toggle
- Không có biến thể theo provider
- Test khó — output là string thuần
Template engine linh hoạt
- Dùng text/template chuẩn Go
- PromptConfig toggle từng section riêng
- Biến thể theo provider (Anthropic / OpenAI)
- Mỗi section test độc lập
Sections có thể bật/tắt độc lập: Identity, Persona, Instructions, Tools, Skills, Memory, Workspace, Orchestration. Mỗi section được cấu hình per-agent qua PromptConfig — không cần sửa code.
3 Migrations mới
Migration lớn nhất — tạo nền tảng cho Memory Layer và Self-Evolution System.
episodic_summaries
Lưu tóm tắt phiên của agent. Cols chính: agent_id, user_id, session_key, summary, embedding. Embedding dùng pgvector cho similarity search.
agent_evolution_metrics
Metrics hiệu suất per run. Cols: agent_id, metric_type, value, metadata, recorded_at. Partitioned by time cho query nhanh.
agent_evolution_suggestions
Đề xuất cải tiến được generate. Cols: agent_id, type, priority, description, status. Status: pending / approved / rejected.
KG Temporal Columns
Thêm valid_from, valid_until vào kg_entities và kg_relations — cho phép Knowledge Graph time-travel queries.
Tạo Vault — hệ thống quản lý tài liệu kiểu Obsidian với wikilinks hai chiều và version control.
vault_documents
Metadata tài liệu trong vault. Cols: tenant_id, agent_id, scope, title, path, content_hash, embedding. Scope: agent / team / global.
vault_links
Wikilinks hai chiều giữa tài liệu. Cols: source_doc_id, target_doc_id, link_text. Auto-maintained khi parse [[link]] syntax.
vault_versions
Lịch sử phiên bản tài liệu. Cols: document_id, version, content_hash, changed_by. Cho phép rollback nội dung về bất kỳ phiên bản nào.
Migration nhỏ — dọn dẹp agent_links legacy và tinh chỉnh index trên episodic_summaries. Migration này đảm bảo RequiredSchemaVersion = 39 được đặt đúng.
Chạy đơn giản: ./goclaw migrate up — tự động áp dụng tất cả 3 migrations theo thứ tự. Idempotent — an toàn khi chạy lại.
SQLite (Desktop Edition): Migration riêng — cập nhật internal/store/sqlitestore/schema.sql (fresh DB) và thêm incremental patch trong schema.go migrations map, đồng thời bump SchemaVersion constant. v3 features trên SQLite hiện ở mức stub — không có pgvector nên retrieval không hoạt động.
Tóm tắt bảng mới
| Bảng | Migration | Cột chính | Mục đích |
|---|---|---|---|
| episodic_summaries | 037 | agent_id, user_id, session_key, summary, embedding | Tóm tắt phiên — L1 Memory |
| agent_evolution_metrics | 037 | agent_id, metric_type, value, metadata, recorded_at | Metrics hiệu suất per run |
| agent_evolution_suggestions | 037 | agent_id, type, priority, description, status | Đề xuất cải tiến từ metrics |
| kg_entities (thêm cột) | 037 | + valid_from, valid_until | KG Temporal — time-travel queries |
| kg_relations (thêm cột) | 037 | + valid_from, valid_until | KG Temporal — time-travel queries |
| vault_documents | 038 | tenant_id, agent_id, scope, title, path, content_hash, embedding | Metadata tài liệu Vault |
| vault_links | 038 | source_doc_id, target_doc_id, link_text | Wikilinks hai chiều |
| vault_versions | 038 | document_id, version, content_hash, changed_by | Lịch sử phiên bản tài liệu |
Tất cả thay đổi là additive — không sửa hoặc xóa bảng/cột cũ. RequiredSchemaVersion = 39 trong internal/upgrade/version.go.