Skip to content

README_VI.md

Latest commit

 

History

History
174 lines (113 loc) · 12.8 KB

README_VI.md

File metadata and controls

174 lines (113 loc) · 12.8 KB

Tích hợp OpenSpace × OpenViking

Trí tuệ xuyên phiên cho các AI agent tự tiến hóa. Mỗi task làm mọi agent thông minh hơn — và giờ đây, tri thức đó tồn tại bền vững qua các phiên, người dùng, và máy tính khác nhau.

Ngôn ngữ: English · Tiếng Việt · 中文

Mục lục

  1. Triết lý — Tại sao chúng tôi xây dựng thứ này (trang này)
  2. Kiến trúc — User flows, data flows, component breakdown
  3. Kinh tế học Token — Thực sự tiết kiệm được bao nhiêu?
  4. Cấu hình — Env vars, identity resolution, multi-tenancy
  5. Vận hành — Business rules, triển khai, testing, troubleshooting

Triết lý

Vấn đề: thông minh trong từng task, ngu đần giữa các task

OpenSpace đã làm các agent thông minh trong phạm vi một task đơn lẻ. Skills hướng dẫn execution, evolution tự sửa workflows bị lỗi, quality monitoring lọc bỏ tools bị degradation. Trên các benchmark công bố, điều này cho ra hiệu suất tốt hơn 4.2× với 46% token ít hơn.

Nhưng giữa các task, OpenSpace quay về cold start. Agent vừa bỏ 8 iterations để khám phá "chromedriver 124 cần Chrome 124+" không có ký ức gì về bài học đó khi task mới bắt đầu. User đã nói rõ ràng "tôi prefer bar charts" hôm thứ Ba phải nói lại lần nữa vào thứ Tư. Tool knowledge mà một agent vất vả đúc kết lại mắc kẹt trong local database của agent đó, trừ khi có ai đó thủ công upload lên cloud.

Chúng tôi gọi đây là khoảng trống học lại (relearn gap) — khoảng cách giữa "skill DB của tôi tốt hơn rồi" và "task tương tự kế tiếp nhanh hơn rõ rệt".

Insight: OpenViking đã giải quyết phần khó

OpenViking là Context Database for AI Agents do đội Volcano Engine xây dựng. Nó coi context của agent — memories, resources, skills — như một filesystem với L0/L1/L2 tiered loading. Memory extraction chạy tự động khi một session được commit. Retrieval semantic với directory-prefix filters. Mọi thứ queryable qua HTTP API nhỏ gọn ở localhost:1933.

Những gì OpenViking cho chúng ta out-of-the-box:

  • Extraction tự động — drop session messages vào, memories có cấu trúc (tool knowledge, user preferences, patterns, past cases) đi ra bên kia. Không cần curation thủ công.
  • L0 abstracts — ~100 tokens per retrieval result. Rẻ để inject, rẻ để dedupe.
  • Directory semantics — viking://tenants/acme/agent/memories/tools/ là một path thật. Multi-tenant isolation chỉ là prefix matching đơn giản.
  • Local-first — chạy như một HTTP server đơn lẻ trên máy bạn hoặc team LAN. Không SaaS lock-in, không data egress.

OpenSpace cần cross-session memory. OpenViking chính là thứ đó. Integration tự viết ra.

Nguyên tắc thiết kế: compound, không replace

Chúng tôi không xây dựng lại bất kỳ cơ chế tiết kiệm token hiện có nào của OpenSpace. Two-phase skill-first execution, progressive disclosure skill selection, BM25 + embedding pre-filter, iter-2 skill context stripping, tool auto-search, message truncation — toàn bộ giữ nguyên chính xác như cũ.

OpenViking là một layer bổ sung:

OpenSpace (giữ nguyên) OpenViking (thêm vào)
Trí tuệ trong-task Trí tuệ xuyên-task
Skills là thủ tục thực thi Memories là tri thức kinh nghiệm
Evolution tạo skills mới Extraction tạo memories mới
Quality metrics lọc skills tệ Past cases surface solutions tốt
Execution local workspace Namespace-scoped across team

Mọi lời gọi enrichment đều là best-effort. Nếu OpenViking down, OpenSpace chạy đúng như nó chạy trước khi có integration này. Rủi ro regression là zero, trần chi phí nghiêm ngặt.

Năm access paths

Tri thức Viking chảy vào OpenSpace qua năm đường riêng biệt, mỗi đường được chọn vì đó là nơi một hint xuyên phiên tạo ra đòn bẩy lớn nhất ở giai đoạn đó:

  1. Skill selector prompt (trước skill selection) Đòn bẩy: User preferences và past similar cases giúp selector chọn skills đã biết là thành công với phong cách của user này — tránh Phase 2 fallback hoàn toàn trong nhiều trường hợp.

  2. Grounding agent system prompt (chỉ iter 1, sau đó strip) Đòn bẩy: Known tool pitfalls, pattern hints, và anti-patterns (known failure modes) short-circuit 2–4 iterations khám phá. Strip ở iter 2 để tiết kiệm prompt tokens y hệt như skill context.

  3. Analyzer prompt (post-execution analysis) Đòn bẩy: Lịch sử tool issues xuyên phiên giúp evolution decisions hội tụ nhanh hơn, biến suggestions CAPTURED suy đoán thành suggestions FIX chính xác — chỉ edit skills hiện có thay vì viết skill mới từ đầu.

  4. Mid-iteration retrieve_memory tool (any iteration, on-demand) Đòn bẩy: Khi grounding agent phát hiện giữa execution rằng nó cần knowledge khác — tool fail bất ngờ, approach không work — nó gọi retrieve_memory(query, category) như bất kỳ tool nào khác. Categories bao gồm antipatterns cho câu hỏi "failure này đã thấy trước chưa?"

  5. Direct MCP tools cho host agent (bất kỳ lúc nào, ngoài OpenSpace execution) Đòn bẩy: Host agents (OpenClaw, Claude Code, Codex, nanobot, …) có 5 MCP tools — openviking_retrieve_memory, openviking_remember, openviking_forget_memory, openviking_report_stale_memory, openviking_memory_status — để chat surface của host có thể access cross-session memories mà không cần delegate task cho OpenSpace execution engine.

Năm access points, năm chiến thắng có thể đo lường — và paths 4, 5 đóng hai gap lớn nhất của thiết kế 3-point ban đầu.

Feedback loop hai chiều

Khi evolver của OpenSpace sinh ra một evolved skill, chúng tôi ghi ngược về OpenViking qua hai kênh:

  1. Session phong phú — task description, final response, tool sequence, metadata evolution của từng skill, environment fingerprint (OS/Python/tool versions để detect staleness trong tương lai). Extraction pipeline của OpenViking tự động biến thứ này thành memories bền vững.

  2. Structured skill resource — nội dung SKILL.md đã evolve được push tới /api/v1/skills để Viking index nó như một resource queryable first-class. Một instance OpenSpace khác đâu đó trên team LAN giờ có thể retrieve skill này qua find_skill_knowledge().

Không cần upload cloud thủ công. Không có nút "share this skill" tường minh. Hành động giải quyết task tự động contribute lại vào collective intelligence.

Negative feedback cũng quan trọng. Failures không bị vứt đi — chúng trở thành anti-pattern memories routed vào viking://agent/memories/antipatterns/. Khi execution status là error hoặc incomplete, OpenSpace tự động record failure reason, tool sequence bị fail, và environment context. Tasks tương lai query Viking sẽ thấy chúng như warnings "AVOID" trong enrichment block. Host agents và user trực tiếp cũng có thể provide feedback tường minh qua OpenSpace.provide_feedback(task_id, "negative", comment) hoặc openviking_remember MCP tool.

Kết quả là một learning loop capture cả những gì work và không work — cùng architecture như skill evolution của chính OpenSpace, giờ extend qua sessions qua Viking.

Lập trường privacy

Shared intelligence là mạnh mẽ — và là nguy cơ privacy nếu làm cẩu thả. Chúng tôi vẽ biên giới isolation có chủ đích và enforce nó bằng nhiều lớp phòng thủ:

  • Agent memories (tools, patterns, skills, cases, antipatterns) là shared trong team theo quy ước. Tool knowledge là toàn bộ điểm của collective intelligence; duplicate nó per user là phá bỏ mục đích.
  • User memories (preferences, profile) là isolated per user qua URI segment user_id. "Alice prefer bar charts" không bao giờ được leak vào sessions của Bob.
  • PII / secret scrubbing xảy ra trước khi bất kỳ content nào rời process. Một scrubber regex-based (openspace/viking/scrubber.py) redact API keys (Anthropic, OpenAI, GitHub, AWS, GCP, Slack, OpenRouter), JWTs, private keys, basic-auth URLs, emails, phone numbers, credit cards (Luhn-validated), SSNs, và IP addresses. Default BẬT. Opt out qua OPENVIKING_SCRUB_PII=false chỉ khi bạn hoàn toàn tin tưởng Viking endpoint.
  • Skill content push là opt-out qua env var. Teams làm việc với data khách hàng nhạy cảm về privacy set OPENVIKING_PUSH_SKILLS=false và session feedback vẫn commit nhưng không skill bodies nào rời máy.
  • Namespace không bao giờ auto-derive. Trộn memory cross-team vô tình quá nguy hiểm để giải quyết bằng heuristics. Teams set OPENVIKING_NAMESPACE=<team> tường minh hoặc có hành vi single-tenant.
  • Quality threshold (OPENVIKING_MIN_SCORE) cho phép teams reject low-confidence retrievals để wrong memories không đến được prompt.

Xem Configuration và Operations cho privacy model đầy đủ.

Lời hứa observability

Nếu không đo được, không tin được. Mỗi lời gọi OpenSpace.execute() trả về một key viking trong result dict:

{
    "viking": {
        "enabled": True,
        "available": True,
        "query": "build dashboard\nPrior user turns: prefer bar charts",
        "enrichment_chars": 1243,
        "hit_counts": {"tool_hints": 3, "user_preferences": 1, ...},
        "feedback_status": "committed",
        "pushed_skills": 1,
    }
}

Cộng với một dòng log summary cho mỗi task:

Viking telemetry: available=True hits=9 enrich_chars=1243 feedback=committed pushed=1

Benchmark pipelines, MCP host agents, và team dashboards có thể đo impact thực tế mà không cần parse execution logs.

Xem Token Economics để phân tích định lượng về savings.

Nội dung của các trang khác

Kiến trúc — Bức tranh end-to-end. Bốn user flows (cold start, warm cache, cross-agent propagation, analysis enrichment). Data flow sequences cụ thể với latency budgets. Component breakdown với file-level entry points.

Kinh tế học Token — Baseline assumptions, per-mechanism savings breakdown, realistic scenarios (cold / warm / cross-agent), cách điều này compound với 46% reduction hiện có của OpenSpace. Phân tích chi phí failure modes.

Cấu hình — Mọi env var được document với precedence rules. OpenSpaceConfig fields. Identity resolution fallback chain. Multi-tenant deployment patterns. Privacy toggles.

Vận hành — Business rule decisions (deployment model, retention, ownership). Test matrix (30 tests, all passing). Troubleshooting playbook. Rollout checklist. Phải làm gì khi Viking down.

Status

  • Audit findings đã xử lý: 10/10
  • Unresolved questions đã giải quyết: 4/4
  • Business rules đã quyết định: 5/5
  • Architectural gaps post-audit đã đóng: 5/5 (host MCP access, mid-iter retrieval, negative feedback, staleness signals, quality threshold)
  • Privacy layer: regex-based PII/secret scrubber, default BẬT
  • Access paths: 5 (selector, grounding, analyzer, mid-iter tool, host MCP tools)
  • MCP tools cho host agent: 5 (retrieve_memory, remember, forget_memory, report_stale_memory, memory_status)
  • Tests: 63 passing (client, scrubber, MCP tools, negative feedback, mid-iter tool, identity, stats)
  • Production readiness: graceful degradation đã verify cho mọi failure mode

Tác giả & Credits

Nguyễn Ngọc Tuấn Founder & CEO — Transform Group Lark Platinum Partner facebook.com/khongphaituan

Xây dựng trên:

  • OpenSpace — Self-evolving engine cho AI agents bởi HKU-DS
  • OpenViking — Context Database for AI Agents bởi Volcano Engine

Integration được cấp phép MIT cùng với OpenSpace. Chào đón đóng góp và phản hồi.