Tài liệu này mô tả hướng đi ban đầu để xây dựng hệ thống Agent AI - SecondBrain cho y khoa dựa trên dự án LLM-Wiki-DUY / SecondBrain-YKhoa. Trọng tâm là mô hình local-first, dùng Git để kiểm soát phiên bản, Ollama để chạy mô hình ngôn ngữ cục bộ, Cursor để thao tác với mã nguồn và tài liệu, sau đó từng bước mở rộng thành một hệ thống wiki có kiểm soát bằng chứng.
Mục tiêu của dự án không phải chỉ là lưu tài liệu, mà là xây dựng một hệ thống tri thức y khoa có thể:
Nguyên tắc cốt lõi:
Không để AI tự do viết kiến thức y khoa không nguồn.
AI chỉ được biên tập, tổ chức, tổng hợp và kiểm định trên nền nguồn đã ingest.Git được chọn vì hệ thống SecondBrain-YKhoa là một dự án tri thức dài hạn, không phải một bộ ghi chú ngắn hạn. Khi dùng Git, mọi thay đổi trong wiki, skill, script, schema và log đều có thể được theo dõi.
Vai trò của Git:
Ví dụ workflow Git cơ bản:
git status --short
python3 scripts/validate.py
git add .
git commit -m "ingest 2025 ACC AHA ACS guideline source note"
git pushTrong dự án này, Git không chỉ là công cụ lập trình. Git là cơ chế bảo vệ tri thức.
Ollama được chọn để chạy mô hình ngôn ngữ trên máy cá nhân. Với hướng local-first, tài liệu raw, source note và wiki có thể được xử lý cục bộ trước khi cân nhắc tích hợp với dịch vụ online.
Vai trò của Ollama:
Ví dụ định hướng sử dụng:
ollama run llama3.2 "Tóm tắt tài liệu này theo cấu trúc source note"Hoặc trong script:
local-ai/scripts/ingest-lecture-and-audit.sh audit wiki/source-notes/example.mdTrong giai đoạn đầu, Ollama không nhất thiết phải đạt chất lượng cao nhất. Giá trị chính là tạo được workflow local, có thể lặp lại và có thể kiểm soát.
Cursor được chọn vì nó nằm giữa IDE và AI Agent. Dự án SecondBrain-YKhoa cần chỉnh sửa nhiều loại file: markdown, Python, shell script, JSON, AGENTS.md, SKILL.md, schema và log. Cursor phù hợp vì có thể làm việc trực tiếp trên repository.
Vai trò của Cursor:
Cursor nên được dùng như một Agent editor, không phải như nơi để hỏi đáp tự do.
Cách dùng đúng:
Giao nhiệm vụ cụ thể cho Cursor:
- File đầu vào ở đâu?
- File đầu ra ở đâu?
- Không được sửa thư mục nào?
- Có được cập nhật index/log không?
- Sau khi sửa phải chạy lệnh audit/validate nào?Ví dụ prompt:
@raw/lectures/vi/endocrinology/Viemgiapthoangqua_baisoanDuy.pptx
@wiki/source-notes/lecture-endocrinology-viemgiapthoangqua-baisoanduy.md
Ingest lecture source note. Tiếng Việt học thuật.
1. Chỉ dùng file đính kèm.
2. Không sửa raw/.
3. Không cập nhật wiki/index.md và logs/log.md ở bước này.
4. Điền learning objectives, teaching points, references trên slide.
5. Không dùng lecture như guideline nếu không có nguồn gốc rõ.
6. Claims index + Claim cards.
7. Không placeholder: Citation needed, TODO, Pending, Chờ Agent.
Sau đó chạy:
local-ai/scripts/ingest-lecture-and-audit.sh audit wiki/source-notes/lecture-endocrinology-viemgiapthoangqua-baisoanduy.mdCác hướng online như liên kết Obsidian với plugin AI, dùng Claude Code trực tiếp, hoặc dùng các nền tảng cloud-based AI có thể mạnh và tiện lợi. Tuy nhiên, với một hệ thống y khoa cần kiểm soát nguồn, hướng local-first có nhiều lợi thế trong giai đoạn nền móng.
Obsidian rất tốt để đọc và liên kết ghi chú, nhưng không nên là lõi kỹ thuật ban đầu của dự án này.
Lý do:
Cách dùng Obsidian phù hợp hơn:
Obsidian nên là lớp đọc, duyệt, tra cứu và liên kết trực quan.
Không nên là lõi kiểm soát chất lượng của SecondBrain-YKhoa trong giai đoạn đầu.Tức là có thể mở thư mục wiki/ bằng Obsidian sau này,
nhưng nền vẫn nên là markdown chuẩn + Git + validator.
Claude Code hoặc các Agent online có thể mạnh trong viết code và xử lý repo. Tuy nhiên, nếu dùng làm nền chính ngay từ đầu, dự án có thể gặp một số vấn đề:
Vì vậy, hướng tốt hơn là:
Xây nền local-first trước.
Sau đó mới dùng Claude Code hoặc Agent online như một lớp tăng tốc, không phải lớp kiểm soát chính.| Hướng | Vai trò phù hợp | Ưu điểm | Hạn chế nếu dùng làm lõi ban đầu |
|---|---|---|---|
| Git + Markdown | Nền lưu trữ và version control | Bền vững, minh bạch, dễ kiểm tra | Cần kỷ luật đặt cấu trúc |
| Ollama | LLM local | Riêng tư hơn, chạy được script, ít phụ thuộc cloud | Chất lượng tùy model và phần cứng |
| Cursor | IDE + Agent thao tác repo | Mạnh khi sửa code, markdown, script | Cần prompt chặt để tránh sửa lan |
| Obsidian | Giao diện đọc và liên kết note | Trực quan, dễ duyệt wiki | Không đủ làm validator/audit engine |
| Claude Code / Agent online | Tăng tốc code và refactor | Mạnh, thông minh, nhanh | Phụ thuộc online, cần kiểm soát bằng Git và validator |
Kết luận thực hành:
Giai đoạn đầu: Git + Markdown + Cursor + Ollama + validator.
Giai đoạn sau: có thể thêm Obsidian để đọc và Claude Code để tăng tốc, nhưng không thay lõi kiểm soát.Cấu trúc tổng quát:
SecondBrain-YKhoa/
├── AGENTS.md
├── README.md
├── raw/
├── wiki/
├── skills/
├── schema/
├── scripts/
├── local-ai/
└── logs/raw/Lưu tài liệu gốc chưa chỉnh sửa.
Ví dụ:
raw/guidelines/cardiology/2025_ACC_AHA_ACS_Guideline.pdf
raw/lectures/vi/endocrinology/Viemgiapthoangqua_baisoanDuy.pptx
raw/trials/cardiology/EMPEROR_Preserved.pdf
raw/textbooks/cardiology/Braunwald_chapter_hf.pdfNguyên tắc:
Không sửa raw/.
Không viết ghi chú trực tiếp vào raw/.
Mọi xử lý phải sinh ra file mới trong wiki/source-notes/ hoặc wiki/.wiki/Đây là kho tri thức đã tổ chức lại.
Cấu trúc hiện tại:
wiki/
├── claim-registry/
├── concepts/
├── contradiction-notes/
├── dataset-notes/
├── diseases/
├── drugs/
├── evidence-maps/
├── guidelines/
├── source-notes/
├── synthesis/
├── teaching-notes/
├── trials/
└── index.mdVai trò từng phần:
| Thư mục | Mục đích |
|---|---|
source-notes/ |
Ghi chú trung thành với từng nguồn riêng lẻ |
claim-registry/ |
Danh mục claim đã kiểm định hoặc đang cần kiểm định |
contradiction-notes/ |
Ghi nhận mâu thuẫn giữa guideline, trial, textbook, lecture |
concepts/ |
Khái niệm nền như HFpEF, PICO, NT-proBNP, ASCVD risk |
diseases/ |
Trang bệnh học tổng hợp |
drugs/ |
Hồ sơ thuốc |
guidelines/ |
Trang tổng hợp guideline và khuyến cáo |
trials/ |
Hồ sơ trial lâm sàng |
evidence-maps/ |
Bản đồ bằng chứng theo câu hỏi, can thiệp, outcome |
synthesis/ |
Bài tổng hợp để trả lời câu hỏi cụ thể |
teaching-notes/ |
Slide outline, script, MCQ, CLO, bài giảng |
dataset-notes/ |
Ghi chú dataset nghiên cứu |
index.md |
Mục lục và registry toàn wiki |
skills/Mỗi skill là một quy trình thao tác chuẩn cho Agent.
Ví dụ:
skills/write-source-note/SKILL.md
skills/citation-audit/SKILL.md
skills/ingest-source/SKILL.md
skills/write-synthesis/SKILL.md
skills/lint-wiki/SKILL.md
skills/guideline-update/SKILL.mdMỗi SKILL.md nên có contract:
---
name: write-source-note
version: 0.1.0
status: active
triggers:
- ingest guideline
- write source note
dependencies:
- citation-audit
owner: LLM-Wiki-DUY
updated: 2026-05-13
---
# write-source-note
## What
## When
## How
## Examples
## Pitfalls
## ChangelogMục tiêu của skills/ là giúp Agent không hành động tùy
tiện. Khi có nhiệm vụ, Agent phải đi theo skill phù hợp.
schema/Chứa quy ước về cấu trúc, loại trang, citation policy, taxonomy và style guide.
Ví dụ:
schema/citation-policy.md
schema/page-types.md
schema/taxonomy.md
schema/style-guide.mdVai trò:
scripts/Chứa các script kiểm định và tự động hóa.
Ví dụ:
scripts/validate.py
scripts/audit-source-notes.py
scripts/auto-ingest.py
scripts/ingest-registry.jsonVai trò:
Lệnh quan trọng nhất:
python3 scripts/validate.pylocal-ai/Chứa prompt, script và RAG local.
Ví dụ:
local-ai/prompts/secondbrain-system.md
local-ai/scripts/ingest-and-audit.sh
local-ai/scripts/ingest-lecture-and-audit.sh
local-ai/scripts/rag-audit.sh
local-ai/rag/simple_rag.pyVai trò:
logs/Chứa lịch sử thao tác.
Ví dụ:
logs/log.md
logs/llm-output/Vai trò:
AGENTS.mdĐây là file định tuyến hành vi cho Agent.
Mục tiêu:
Ví dụ routing:
| User intent | Route |
|---|---|
| Ingest guideline PDF | ingest-source → write-source-note → citation-audit |
| Ingest lecture PPTX | ingest-source → write-source-note → lecture audit |
| Update disease page | write-synthesis → citation-audit → lint-wiki |
| Compare two guidelines | guideline-update → contradiction-notes → synthesis |
| Create MCQ from wiki | teaching-notes → citation-audit |mkdir SecondBrain-YKhoa
cd SecondBrain-YKhoa
git initTạo cấu trúc thư mục:
mkdir -p raw wiki/source-notes wiki/diseases wiki/drugs wiki/trials wiki/guidelines
mkdir -p wiki/concepts wiki/synthesis wiki/claim-registry wiki/contradiction-notes
mkdir -p wiki/evidence-maps wiki/teaching-notes wiki/dataset-notes
mkdir -p skills schema scripts local-ai/prompts local-ai/scripts local-ai/rag logsTạo file nền:
touch README.md AGENTS.md wiki/index.md logs/log.mdCác file nên có:
schema/citation-policy.md
schema/page-types.md
schema/taxonomy.md
schema/style-guide.mdMục tiêu của bước này là định nghĩa trước luật chơi. Không nên ingest hàng loạt khi chưa có schema, vì wiki sẽ dễ bị loạn cấu trúc.
Tạo các skill lõi:
skills/ingest-source/SKILL.md
skills/write-source-note/SKILL.md
skills/citation-audit/SKILL.md
skills/write-synthesis/SKILL.md
skills/guideline-update/SKILL.md
skills/lint-wiki/SKILL.md
skills/execute/SKILL.md
skills/guide/SKILL.mdMỗi skill phải có đủ section:
## What
## When
## How
## Examples
## Pitfalls
## ChangelogFile chính:
scripts/validate.pyValidator nên kiểm tra:
wiki/index.md và logs/log.md có tồn tại
không..DS_Store, .tmp/,
__pycache__/ không.TODO, Citation needed,
Pending, Chờ Agent không.original_file không.Chạy kiểm tra:
python3 scripts/validate.pyMục tiêu không phải thay thế hoàn toàn ChatGPT hay Claude, mà là có một LLM local để chạy pipeline cơ bản.
Ví dụ:
ollama list
ollama run llama3.2Sau đó tạo prompt hệ thống:
local-ai/prompts/secondbrain-system.mdNội dung prompt nên nhấn mạnh:
- Chỉ dùng nguồn được cung cấp.
- Không tự tạo citation.
- Không dùng lecture như guideline nếu không rõ nguồn.
- Mọi claim lâm sàng phải có citation anchor.
- Nếu thiếu bằng chứng, ghi rõ thiếu bằng chứng.
- Không để placeholder.Ví dụ:
local-ai/scripts/ingest-and-audit.sh
local-ai/scripts/ingest-lecture-and-audit.sh
local-ai/scripts/rag-audit.shMột script nên có các mode rõ ràng:
local-ai/scripts/ingest-lecture-and-audit.sh prepare <raw_file> <source_note> "<title>"
local-ai/scripts/ingest-lecture-and-audit.sh audit <source_note>
local-ai/scripts/ingest-lecture-and-audit.sh final <source_note>Không nên viết script mơ hồ kiểu chỉ nhận một đường dẫn rồi tự đoán tất cả.
Không nên ingest hàng loạt ngay. Nên bắt đầu với một guideline chuẩn.
Ví dụ:
raw/guidelines/cardiology/2024_ESC_Hypertension_Guideline.pdfSinh source note:
wiki/source-notes/2024-esc-hypertension-guideline.mdSau đó audit:
python3 scripts/validate.py
git status --shortNếu pass mới commit:
git add .
git commit -m "ingest 2024 ESC hypertension guideline source note"Sau khi pipeline chạy ổn với một guideline, có thể mở rộng theo cụm chuyên ngành:
Cardiology first batch:
- 2024 ESC Hypertension
- 2024 ESC Atrial Fibrillation
- 2023 ACC/AHA/HRS Atrial Fibrillation
- 2025 ACC/AHA ACS
- ESC Heart Failure
- ESC Pulmonary EmbolismNguyên tắc:
Mỗi lần thêm nguồn mới → tạo source note → audit → validate → commit.
Không ingest hàng loạt nếu validator chưa ổn.Sau khi có vài source note, bắt đầu tách claim quan trọng.
Ví dụ:
wiki/claim-registry/hfpef-claims.md
wiki/claim-registry/acs-claims.md
wiki/claim-registry/af-anticoagulation-claims.mdMẫu claim:
# HFPEF-THER-001
## Claim
SGLT2 inhibitors reduce the risk of heart failure hospitalization in patients with HFpEF.
## Source support
- EMPEROR-Preserved source note
- DELIVER source note
- ESC heart failure guideline source note
- AHA/ACC/HFSA heart failure guideline source note
## Certainty
High
## Clinical use
Treatment recommendation for symptomatic HFpEF unless contraindicated.
## Audit status
AuditedSau khi claim đã có nguồn, mới tạo các trang tổng hợp.
Ví dụ:
wiki/diseases/heart-failure-preserved-ef.md
wiki/drugs/empagliflozin.md
wiki/trials/emperor-preserved.md
wiki/guidelines/esc-heart-failure.mdNguyên tắc:
Disease/drug/guideline/trial page không được là bản chép tự do của AI.
Mỗi claim quan trọng phải truy ngược được về source note hoặc claim registry.Synthesis nên trả lời một câu hỏi rõ, không nên quá rộng.
Ví dụ tốt:
wiki/synthesis/sglt2i-in-hfpef-after-decompensation.md
wiki/synthesis/doac-in-mitral-stenosis.md
wiki/synthesis/oxygen-therapy-when-spo2-above-90.md
wiki/synthesis/diagnosis-of-acute-heart-failure.mdVí dụ không nên:
wiki/synthesis/heart-failure.md
wiki/synthesis/cardiology.md1. Đưa file vào raw/
2. Chạy prepare để tạo source note skeleton
3. Dùng Cursor/Agent để điền source note
4. Không sửa raw/
5. Không cập nhật index/log ở bước nháp nếu chưa audit
6. Chạy audit source note
7. Sửa lỗi citation, placeholder, metadata
8. Chạy validate toàn repo
9. Cập nhật wiki/index.md và logs/log.md
10. Commit bằng GitVí dụ:
local-ai/scripts/ingest-lecture-and-audit.sh prepare \
raw/lectures/vi/endocrinology/Viemgiapthoangqua_baisoanDuy.pptx \
wiki/source-notes/lecture-endocrinology-viemgiapthoangqua-baisoanduy.md \
"Viêm giáp thoáng qua - bài soạn Duy"
local-ai/scripts/ingest-lecture-and-audit.sh audit \
wiki/source-notes/lecture-endocrinology-viemgiapthoangqua-baisoanduy.md
python3 scripts/validate.py
git status --short@raw/lectures/vi/endocrinology/example.pptx
@wiki/source-notes/lecture-endocrinology-example.md
Ingest lecture source note. Tiếng Việt học thuật.
Yêu cầu:
1. Chỉ dùng file đính kèm.
2. Không sửa raw/.
3. Không cập nhật wiki/index.md và logs/log.md ở bước này.
4. Điền learning objectives, teaching points, references nếu có trên slide.
5. Không dùng lecture như guideline nếu không có nguồn gốc rõ.
6. Tạo Claims index và Claim cards.
7. Không để placeholder: Citation needed, TODO, Pending, Chờ Agent.
8. Ghi rõ slide/page anchor nếu có thể.
Sau đó chạy:
local-ai/scripts/ingest-lecture-and-audit.sh audit wiki/source-notes/lecture-endocrinology-example.md@raw/guidelines/cardiology/example_guideline.pdf
@wiki/source-notes/example-guideline.md
Ingest guideline source note. Tiếng Việt học thuật.
Yêu cầu:
1. Chỉ dùng guideline được cung cấp.
2. Không dùng kiến thức ngoài tài liệu.
3. Giữ rõ metadata: official title, society/authors, year, DOI/URL nếu có, original_file.
4. Tạo các phần: Scope, Key recommendations, Diagnostic criteria, Treatment recommendations, Follow-up, Evidence gaps.
5. Mỗi claim quan trọng phải có page/table/section anchor.
6. Không tạo recommendation nếu guideline không nói.
7. Không để placeholder.
Sau đó chạy:
python3 scripts/validate.pyTạo synthesis tại:
wiki/synthesis/sglt2i-in-hfpef-after-decompensation.md
Câu hỏi:
Bệnh nhân HFpEF vừa nhập viện vì suy tim mất bù, eGFR 38 mL/phút/1,73m², có nên khởi trị SGLT2 inhibitor sau ổn định không?
Chỉ dùng:
- wiki/source-notes/
- wiki/trials/
- wiki/guidelines/
- wiki/claim-registry/
Yêu cầu:
1. Trả lời theo PICO.
2. Tách guideline, trial, chống chỉ định, điểm cần kiểm tra trước dùng.
3. Nếu có mâu thuẫn giữa nguồn, ghi rõ.
4. Mọi claim điều trị phải có citation anchor.
5. Không tạo nguồn giả.
6. Không để placeholder.Ghi chú thông thường:
Đọc tài liệu → tóm tắt → lưu vào note → tìm lại khi cầnSecondBrain-YKhoa:
Raw source → source note → claim card → audit → registry → synthesis → teaching/clinical outputĐiểm mạnh của SecondBrain-YKhoa là khả năng truy vết:
Câu trả lời cuối cùng → claim → source note → guideline/trial/textbook gốcĐây là điểm khác biệt quan trọng với workflow hỏi đáp AI thông thường.
Việc cần làm:
scripts/validate.py.scripts/audit-source-notes.py.Mục tiêu:
Mọi file mới sinh ra đều có thể được kiểm tra tự động.Ưu tiên:
- ACS
- Heart failure
- Atrial fibrillation
- Hypertension
- Pulmonary embolism
- Valvular heart disease
- DyslipidemiaMục tiêu:
Có 20-30 source notes chất lượng cao, không placeholder, có claim cards và citation anchors.Tạo các trang:
wiki/diseases/acute-coronary-syndrome.md
wiki/diseases/heart-failure-preserved-ef.md
wiki/diseases/atrial-fibrillation.md
wiki/drugs/warfarin.md
wiki/drugs/alteplase.md
wiki/drugs/empagliflozin.md
wiki/trials/emperor-preserved.md
wiki/trials/deliver.mdMục tiêu:
Không chỉ có source note, mà có tri thức đã tổng hợp để dùng lại.Bắt đầu từ RAG đơn giản:
local-ai/rag/simple_rag.pyChức năng tối thiểu:
python3 local-ai/rag/simple_rag.py index wiki/
python3 local-ai/rag/simple_rag.py answer "Chẩn đoán suy tim cấp theo ESC?"Sau đó nâng cấp:
Sau khi wiki đã ổn, có thể mở folder bằng Obsidian.
Vai trò Obsidian lúc này:
Nhưng lõi kiểm soát vẫn là:
Git + markdown + schema + validator + source-note auditCó thể dùng Claude Code hoặc các Agent online khi:
Nhưng mọi output của Agent online phải qua:
python3 scripts/validate.py
git diff
git status --shortKhông nên cho Agent online toàn quyền sửa repo mà không có bước kiểm tra.
Trước khi cho Agent làm:
[ ] Đã chỉ rõ file đầu vào.
[ ] Đã chỉ rõ file đầu ra.
[ ] Đã nói rõ không được sửa raw/.
[ ] Đã nói rõ có được cập nhật index/log không.
[ ] Đã yêu cầu không placeholder.
[ ] Đã yêu cầu citation anchor cho claim quan trọng.
[ ] Đã yêu cầu chạy audit/validate sau khi sửa.Sau khi Agent làm:
[ ] Chạy git diff.
[ ] Chạy python3 scripts/validate.py.
[ ] Kiểm tra có file rác không.
[ ] Kiểm tra source note có original_file không.
[ ] Kiểm tra claim có nguồn không.
[ ] Kiểm tra không có citation giả.
[ ] Commit nếu ổn.Hướng đi ban đầu nên là:
Git làm nền kiểm soát phiên bản.
Markdown làm định dạng tri thức bền vững.
Cursor làm môi trường Agent thao tác repo.
Ollama làm lớp LLM local và thử nghiệm pipeline.
Validator làm hàng rào chất lượng.
Source note và claim registry làm cơ chế chống hallucination.Obsidian và Claude Code không bị loại bỏ. Chúng nên được thêm sau khi lõi đã vững:
Obsidian = lớp đọc và duyệt tri thức.
Claude Code / Agent online = lớp tăng tốc thao tác.
Git + validator + source audit = lõi kiểm soát.Đây là kiến trúc phù hợp với một hệ thống y khoa cần độ tin cậy cao, có khả năng truy vết, có thể mở rộng theo chuyên ngành và không bị phụ thuộc hoàn toàn vào một nền tảng AI online.