Tổng quan

Trang Admin (/admin) chỉ accessible với role admin. Đây là nơi cấu hình toàn bộ hệ thống AOKP: user management, RBAC, workspace config, và system health telemetry.

User Management

Các role trong AOKP

AOKP dùng 5-tier authority level:

Tạo và quản lý user

1. 1
   Users

   Admin panel → tab → click New User
2. 2
   (không tiêu đề)

   Nhập email, tên hiển thị, chọn role
3. 3
   (không tiêu đề)

   User nhận email với link đăng ký WebAuthn (passkey)
4. 4
   (không tiêu đề)

   Sau khi user setup passkey, account active

Để thay đổi role: click user → Edit Role → chọn role mới → Save. Thay đổi có hiệu lực ngay lập tức.

Để vô hiệu hóa user: click user → Deactivate → user không còn đăng nhập được nhưng records vẫn giữ nguyên.

Cấu hình hệ thống

Thay đổi qua Admin panel → tab Config → chỉnh sửa → Apply. Một số config cần restart server (có ghi chú requires-restart).

Workspace Configuration

Admin có thể cấu hình Workspace settings qua API /api/workspace-config:

• Default filter khi mở Workspace
• Columns hiển thị trong list view
• Sort order mặc định
• Số items per page

Telemetry và Health

Tab Telemetry trong Admin hiển thị:

• Request rates — số request/phút cho mỗi API endpoint
• p95 latency — so với baseline (fail nếu regress > 25%)
• Error rates — lỗi theo loại và endpoint
• Agent session metrics — số session, tỷ lệ approval, timeout rate
• Storage usage — theo Evidence Store và Index

Câu hỏi thường gặp

Tổng quan

Connector là module nhận dữ liệu từ nguồn ngoài (file system, URL, external API) và emit intake records chuẩn hóa. Intake records đi qua pipeline: register → normalize → chunk → index — không bao giờ write thẳng vào Evidence Store.

Connector Pack 01 (Accepted & Frozen)

Pack 01 gồm 4 connectors đã qua governance review và được frozen — không thay đổi implementation:

Luồng intake chuẩn

Mọi connector đều theo luồng này:

1. 1
   Detect

   — Connector phát hiện data mới (file change, API call, schedule)
2. 2
   Emit intake record

   — Tạo record với: sourceId, sourceType, rawContent, capturedAt, connectorId
3. 3
   Register

   — Pipeline nhận intake record, assign artifactId, ghi vào register
4. 4
   Normalize

   — Extract metadata, validate schema, gắn classificationPath
5. 5
   Chunk

   — Chia content thành chunks theo strategy (token-based, section-based)
6. 6
   Index

   — Ghi vào Evidence Store, tạo embedding, cập nhật search index

Theo dõi trạng thái connector

Admin panel → tab Connectors, hoặc API /api/kb-health:

File Watcher — live monitoring

File Watcher (connector-fs-watch) theo dõi thư mục được cấu hình và tự động ingest khi có file mới hoặc thay đổi:

• Thư mục được watch: data/01_knowledge/ (mặc định)
• File types: .md, .txt, .yaml, .json, .pdf
• Debounce: 2 giây (tránh ingest nhiều lần khi file đang được ghi)
• Recursive: watch toàn bộ subdirectory

Xem watcher status: GET /api/kb-health → field watcherActive.

Reset connector bị stuck

Nếu connector ở trạng thái running quá timeout (mặc định 5 phút):

# Reset tất cả connector jobs
pnpm reingest:queries --force-reset

# Reset connector cụ thể
pnpm reingest:queries --connector connector-fs-watch --force-reset

Hoặc qua Admin panel → Connectors → click connector → Force Reset.

Connector Pack 02 — Pending Governance Review

Pack 02 đã được đề xuất nhưng chưa qua governance review:

Câu hỏi thường gặp

Tổng quan

Governance không phải một module riêng — nó là lớp kiểm soát xuyên suốt mọi thao tác trong AOKP. Mọi artifact đều có lifecycle, mọi write action đều đi qua policy gate, mọi thay đổi quan trọng đều cần approval có ghi log.

Lifecycle State Machine

draft → pendingApproval → active → superseded → archived
         ↑_________________↓ (reject)

Policy Gates

Policy gate chạy trước mọi state transition và write action:

Nếu gate fail: action bị block, error message ghi rõ gate nào fail và lý do.

Approval Routing

Khi action cần approval, AOKP tạo Approval Request và route đến đúng người:

SLA mặc định: 30 phút cho operator approval, 4 giờ cho admin approval. Quá SLA → escalate lên tier cao hơn.

Retention Engine

Retention policy xác định bao lâu artifact ở mỗi state trước khi tự động transition:

Config tại data/04_governance/retention-policy.yaml. Thay đổi cần Superadmin và ghi governance record.

Governance Records

Mọi action governance đều tạo immutable record tại data/04_governance/:

data/04_governance/
├── approvals/          # Approval records (approve/reject)
├── lifecycle/          # Lifecycle transition history
├── policy-changes/     # Config/policy change log
└── force-actions/      # Force-transition log (superadmin)

Record không thể xóa qua UI. Xem qua API /api/kb-lifecycle?artifactId=<id>.

Audit Trail

Tab Audit trong Admin hiển thị toàn bộ governance events theo thời gian:

• Ai đã làm gì, lúc nào, với artifact nào
• Approval/reject với reason và approver
• Policy gate failures
• Force actions

Có thể filter theo: user, artifact, action type, time range. Export ra CSV (button góc trên phải).

Câu hỏi thường gặp

Luồng cơ bản

AOKP hoạt động theo vòng: đưa dữ liệu vào → tìm kiếm → hỏi AI. Ba bước sau đây đủ để bạn thấy kết quả thực.

1. 1
   Ingest file đầu tiên

   Ingest file đầu tiên

   Vào trang chủ, kéo thả file .md, .txt, hoặc .pdf vào vùng upload. AOKP tự chạy pipeline: register → normalize → chunk → index. Trạng thái hiển thị trong Health → Indexer, cột pendingDocs.

2. 2
   Tìm kiếm để xác nhận

   Tìm kiếm để xác nhận

   Sau khi pendingDocs = 0, vào trang Tìm kiếm (hoặc gõ vào ô search ở trang chủ). Gõ một từ khóa có trong file vừa upload. Kết quả là evidence chunks với snippet, source path, và lifecycle state.

3. 3
   Hỏi Trợ lý AI

   Hỏi Trợ lý AI

   Vào Trợ lý → nhập câu hỏi liên quan đến nội dung file. Copilot trả lời và kèm citations — mỗi trích dẫn có link về chunk gốc trong kho.

4. 4
   Kiểm tra Health

   Kiểm tra Health

   Vào Health (trang chủ) hoặc API /api/health. 12 subsystem đều xanh = hệ thống sẵn sàng.

Sẵn sàng khám phá sâu hơn?

Câu hỏi thường gặp

Trong 1 phút

AOKP làm 3 việc chính cho người vận hành:

Khi nào dùng AOKP trực tiếp?

Nếu bạn đang dùng AIOS-OC Console, đa phần các tác vụ tra cứu Knowledge sẽ đi qua tab Knowledge ở đó. Tới AOKP trực tiếp khi cần:

• Quan sát health của 12 subsystem (Storage, Indexer, Retriever, Reasoner, ...)
• Bulk ingest hàng trăm file qua CLI
• Inspect raw query / chunk / embedding cho debug

Cần làm gì lần đầu?

1. 1
   Mở aokp.local

   Mở aokp.local — Vào URL trong trình duyệt. Trang chủ là Search interface.

2. 2
   Thử search keyword

   Thử search keyword — Gõ ví dụ "authentication" rồi Enter. Kết quả là evidence chunks với title + snippet + source.

3. 3
   Mở Health tab

   Mở Health tab — Click vào Health ở topbar để xem trạng thái 12 subsystem. Tất cả xanh = ok.

Câu hỏi thường gặp

Tổng quan

Trang Trợ lý (/copilot) kết nối trực tiếp với retrieval pipeline của AOKP. Mỗi câu hỏi bạn gửi được xử lý qua CRAG (Corrective RAG): truy xuất chunks liên quan, đánh giá độ liên quan, tổng hợp câu trả lời, rồi gắn citations về nguồn gốc.

Cách đặt câu hỏi hiệu quả

Citations và nguồn gốc

Mỗi câu trả lời từ Copilot kèm theo danh sách citations ở cuối. Mỗi citation có:

• Title và kind của artifact nguồn
• Snippet — đoạn văn bản được trích xuất
• classificationPath — phân loại của nguồn
• Link — mở trực tiếp artifact trong Workspace

Giới hạn của Copilot

Câu hỏi thường gặp

Tổng quan

Trang Đồ thị (/graph) hiển thị Knowledge Graph được xây dựng từ toàn bộ evidence trong kho. Entities là các khái niệm, hệ thống, sự kiện; Relations là mối liên kết giữa chúng (phụ thuộc, gây ra, kế thừa, ...).

Các loại entity

Các loại quan hệ nhân quả (Temporal Causal)

AOKP có engine riêng để trace 7 loại quan hệ nhân quả:

Cách điều hướng đồ thị

1. 1
   Zoom và pan

   — dùng scroll wheel để zoom, kéo để pan. Click node để select.
2. 2
   Filter theo type

   — sidebar trái có checkbox cho từng entity type và relation type.
3. 3
   Search node

   — ô tìm kiếm phía trên tìm theo tên entity.
4. 4
   Expand neighbors

   — click node → "Expand" để xem tất cả relation của node đó.
5. 5
   Trace causal chain

   — click node → tab "Causal" → xem chain nguyên nhân-kết quả đầy đủ.

GraphRAG — hỏi về đồ thị

Ngoài visualization, AOKP có endpoint /api/graph-rag cho phép hỏi câu hỏi về cấu trúc graph:

• "Những entity nào phụ thuộc vào FDP?"
• "Có bao nhiêu relation giữa cluster A và cluster B?"
• "Trace nguyên nhân của incident Z"

Từ trang Đồ thị, click Query Graph (góc trên phải) để mở GraphRAG panel.

Câu hỏi thường gặp

Tổng quan

Trang Agent thử nghiệm (/pilot) là giao diện để khởi tạo và tương tác với bounded AI agents của AOKP. Agent hoạt động trong ranh giới được xác định trước (bounded posture) — không thể vượt qua approval gate mà không có sự phê duyệt của người vận hành.

Ba persona agent

Vòng đời một agent session

1. 1
   Khởi tạo

   — Chọn persona, nhập task description. Session ID được tạo tự động.
2. 2
   Agent planning

   — Agent phân rã task thành steps, hiển thị plan để bạn review trước khi execute.
3. 3
   Execution với checkpoints

   — Mỗi step có checkpoint. Nếu bước nào thất bại, agent dừng và báo cáo — không tự ý tiếp tục.
4. 4
   Approval gates

   — Step nào có write action sẽ pause và chờ bạn approve/reject.
5. 5
   Completion

   — Agent tổng kết kết quả, ghi session trace vào data/08_agent_sessions/.

Approval boundary

Agent không thể tự mình thực hiện các hành động sau mà không có approval:

• Ingest file mới vào Evidence Store
• Transition lifecycle state của artifact
• Trigger connector re-ingest
• Ghi governance record
• Modify config

Khi agent cần approval, giao diện Pilot sẽ hiện Approval Request với:

• Mô tả action dự định
• Impact assessment
• Nút Approve / Reject / Modify and Approve

Checkpoint và rollback

Sau mỗi step thực hiện thành công, agent tạo checkpoint. Nếu bạn muốn rollback:

1. 1
   Session History

   Vào tab → click session ID
2. 2
   (không tiêu đề)

   Chọn checkpoint muốn rollback về
3. 3
   Rollback to checkpoint

   Click → confirm
4. 4
   (không tiêu đề)

   Agent state và mọi artifact thay đổi được restore về thời điểm đó

Câu hỏi thường gặp

Tổng quan

Trang Suy luận (/reason) khác với Copilot ở chỗ: thay vì trả lời thẳng từ retrieval, nó phân rã câu hỏi thành các sub-query, chạy song song, rồi tổng hợp kết quả. Phù hợp với câu hỏi có nhiều vế hoặc cần so sánh nhiều nguồn.

Hai chế độ suy luận

Chọn chế độ bằng dropdown phía trên ô nhập câu hỏi. Mặc định là ReAct.

Câu hỏi phù hợp với Suy luận

Suy luận tốt nhất với câu hỏi:

• Có nhiều vế: "So sánh X và Y theo các tiêu chí A, B, C"
• Cần truy tìm nguyên nhân: "Vì sao hệ thống Z có hành vi như vậy?"
• Yêu cầu tổng hợp từ nhiều artifact: "Tóm tắt tất cả thay đổi liên quan đến authentication từ tháng 3 đến nay"
• Cần verify chéo: "Thông tin trong runbook có khớp với spec không?"

Xem quá trình suy luận

Kết quả trả về gồm:

1. 1
   Câu hỏi gốc

   + cách phân rã thành sub-queries
2. 2
   Trace từng bước

   — xem agent đã làm gì, query nào, tìm được gì
3. 3
   Câu trả lời tổng hợp

   — kèm citations từ evidence
4. 4
   Confidence score

   — mức độ tin cậy của tổng hợp (0–1)
5. 5
   Thời gian xử lý

   — p95 latency cho từng phase

Cấu hình nâng cao

Cấu hình qua data/config.yaml → reasoning.*.

Câu hỏi thường gặp

Cú pháp tìm kiếm

Có thể combine: kind:runbook scope:operations/atcc since:2026-04 ssh.

Mẹo viết query

Khắc phục

Tổng quan

Trang Giám sát (/supervision) là control center cho tất cả bounded AI agents. Người vận hành (Operator trở lên) có thể xem toàn bộ agent sessions, trạng thái từng step, và phê duyệt các action đang chờ.

Các tab chính

Theo dõi session real-time

Click vào bất kỳ session trong Active Sessions → view live:

Xử lý approval requests

1. 1
   Pending Approvals

   Vào tab — danh sách hiển thị theo thứ tự thời gian, cũ nhất trước.
2. 2
   (không tiêu đề)

   Click approval item → xem chi tiết: action type, target artifact, expected impact.
3. 3
   Approve

   Chọn một trong ba:

   • Approve — agent tiếp tục thực hiện action
   • Reject — agent bỏ qua action, tiếp tục step tiếp theo nếu có
   • Modify — chỉnh sửa parameters rồi approve (ví dụ: thay đổi target file)
4. 4
   (không tiêu đề)

   Thêm ghi chú (tùy chọn) — được ghi vào session trace.

Can thiệp vào session đang chạy

Từ Active Sessions → click session → toolbar phía trên có:

Câu hỏi thường gặp

Tổng quan

Trang Kho tri thức (/workspace) liệt kê mọi evidence artifact trong Evidence Store. Mỗi item hiển thị: title, kind, scope, classificationPath, ngày ingest, và lifecycle state hiện tại.

Lifecycle states

Mỗi artifact đi qua vòng đời có kiểm soát:

Lọc và tìm trong workspace

Workspace hỗ trợ filter theo:

• Kind — doc, runbook, log, spec, policy, ...
• Scope — path phân cấp, ví dụ operations/atcc, design/network
• Classification — theo classificationPath (plane × dimension × tier)
• Lifecycle state — chọn một hoặc nhiều state
• Ngày ingest — từ/đến

Kết hợp filter để khoanh vùng: ví dụ kind:runbook scope:operations/atcc state:active → chỉ hiện runbook ATCC đang active.

Xem provenance chain

Click vào bất kỳ artifact → panel bên phải mở ra. Tab Provenance hiển thị:

1. 1
   Source

   — file gốc (path, hash, capturedAt)
2. 2
   Ingestion record

   — timestamp, connector ID, normalize version
3. 3
   Chunk list

   — danh sách chunk được tạo, số token mỗi chunk
4. 4
   Embedding status

   — vectorized hay chưa, model dùng để embed
5. 5
   Superseded by / Supersedes

   — link về các version liên quan (nếu có)

Xem và thay đổi lifecycle state

Từ panel artifact → tab Lifecycle → click nút transition. Các transition hợp lệ:

• draft → active (sau review)
• active → superseded (khi upload version mới)
• active → archived (khi artifact hết hiệu lực)
• archived → active (restore, cần Admin approval)

Câu hỏi thường gặp