spec-probe

LLM functional-requirement coverage scanner (C/C++, Python, TS/JS, Java). Spec (.docx / .pdf / .md) → parse FR → search evidence → verify → coverage report.

→ Dùng ngay: QUICKSTART.md (chat-first; terminal chỉ cài + codegraph).

Cài từ PyPI / publish: docs/PYPI.md

---

Phần dưới: tài liệu chi tiết (codegraph, RAG, LLM, domain pack, …).

---

codegraph (tùy chọn — tăng độ chính xác search)

spec-probe hoạt động tốt chỉ với grep có sẵn, không bắt buộc cài thêm gì. Nhưng nếu cài codegraph (AST-accurate code index, hỗ trợ C/C++/Python/TS/JS/Java...) cho module đang verify, spec-probe sẽ tự động dùng nó để:

• Tìm đúng hàm dù LLM đoán sai tên định danh (vd đoán ClassifyToolRisk trong khi hàm thật là classify).
• Lấy chính xác danh sách caller/callee bằng AST thay vì đoán bằng regex.

Cài 1 lần, tự động phát hiện — không cần cấu hình gì thêm:

./setup/setup_codegraph.sh /path/to/your/module

Script sẽ: kiểm tra Node.js → cài codegraph CLI qua npm nếu chưa có → chạy codegraph init để build index cho module. Sau đó spec-probe tự nhận ra .codegraph/ và dùng ngay, không cần sửa config.yaml/config.json. Chạy lại an toàn (idempotent) — nếu module đã có index rồi thì chỉ báo vậy, không init lại.

Cách gọi	Kết quả
./setup/setup_codegraph.sh	Chỉ cài CLIcodegraph qua npm (nếu chưa có), không build index cho module nào
./setup/setup_codegraph.sh /path/to/module	Cài CLI (nếu chưa có)+ build index (.codegraph/) cho đúng module đó
codegraph sync /path/to/module	Cập nhật index sau khi code đổi nhiều (gọi thẳng CLI, không qua script) — không bắt buộc, index cũ vẫn dùng được, chỉ kém chính xác hơn với code mới
codegraph status /path/to/module	Xem index hiện có bao nhiêu file/node/edge, có đang lỗi gì không

Hoặc gộp cài codegraph vào ngay lúc install.sh (chạy setup_codegraph.sh như một bước con):

./install.sh --cursor --init --codegraph --module /path/to/your/module

Nếu không cài / không có Node.js: spec-probe tự fallback về grep như trước — không lỗi, không cần tắt gì.

Có related_modules (module chính + service liên quan)? Index thư mục cha chung, không phải từng module riêng

Nếu config.yaml có input.related_modules (vd module chính + 1-2 service khác nằm cạnh nhau), đừng chạy setup_codegraph.sh riêng cho từng module — mỗi lần chạy tạo 1 .codegraph/ độc lập, và codegraph không tự nối cạnh gọi hàm giữa 2 index riêng biệt (mỗi module chỉ biết code trong chính nó). Ví dụ:

input:
  module_path: /path/to/monorepo-root/apps/myapp
  related_modules:
    paths:
      - /path/to/monorepo-root/libs/core-service
      - /path/to/monorepo-root/libs/shared-runtime

→ Index đúng 1 lần ở thư mục cha chung (monorepo-root), không phải từng app riêng — dùng setup_codegraph.sh (tự cài CLI nếu chưa có), không gọi thẳng codegraph init:

./setup/setup_codegraph.sh /path/to/monorepo-root

(hoặc nếu CLI đã cài rồi, gọi thẳng codegraph init -y /path/to/monorepo-root cũng được — chỉ là setup_codegraph.sh an toàn hơn vì tự lo phần cài đặt.)

spec-probe tự nhận ra — module_path/related_modules trong config.yaml không cần đổi gì, vì lúc query, spec-probe tự đi ngược từ mỗi path lên tìm .codegraph/ gần nhất, và với cách index này các module con trỏ về cùng một index → cạnh gọi hàm chéo module được resolve đúng.

Sau này code đổi, cập nhật lại (nhanh, chỉ re-parse phần thay đổi):

codegraph sync /path/to/monorepo-root

Quy mô tham khảo: repo test thật (~1600 file, đa ngôn ngữ) mất 1.9 giây để index (đo trực tiếp, không phải ước lượng). Với ~1000 file C++ thuần (~800K dòng), dự kiến cũng ở mức giây tới dưới 1 phút — chưa đo trực tiếp ở quy mô/ngôn ngữ này, nhưng không có lý do để lo về hiệu năng.

---

Quick start (Cursor)

Xem QUICKSTART.md.

VS Code Copilot

./install.sh --vscode --init

Cả hai IDE

./install.sh --init

Dev mode (symlink skill → repo)

./install.sh --cursor --symlink --init

Gắn module + spec lúc install

./install.sh --cursor --init \
  --module /path/to/your/cpp-module \
  --spec /path/to/spec.docx

---

install.sh --init làm gì?

Bước	Kết quả
Skills	spec-cover + spec-pack + spec-audit → ~/.cursor/skills/ (hoặc ~/.copilot/skills/)
Venv	.venv/ trong repo
Package	pip install -e '.[dev]' — skip nếu venv đã import được spec-probe
Config	Tạo~/.config/spec-probe/ (.env, config.yaml, config.json)
RAG	Không mặc định. ./install.sh --init --rag nếu cần FAISS/embeddings

./install.sh --cursor (không --init) chỉ copy skill — vài giây.

Sửa code trong repo spec-probe → không cần chạy lại gì cả. pip install -e '.[dev]' là editable install — venv chỉ trỏ thẳng về source code trong repo (không copy), nên sửa bất kỳ file .py nào có hiệu lực ngay, không cần reinstall.

Chạy lại ./install.sh --init khi code đã sửa thì sao? Tự động bỏ qua bước pip install nếu venv đã có sẵn spec-probe (in ra venv already has spec-probe — skip pip) — không làm gì thêm, không lỗi.

Khi nào thực sự cần reinstall: chỉ khi đổi dependency trong pyproject.toml (thêm package mới, đổi version) — không phải vì sửa logic code. install.sh hiện chưa có cờ --force truyền xuống, nên gọi thẳng:

python3 skills/spec-cover/scripts/spec_cover.py install --force

(hoặc đơn giản: xoá .venv/ rồi chạy lại ./install.sh --init)

---

Kiến trúc RAG trong spec-probe (Spec RAG vs Code RAG)

Hệ thống phân tách rõ ràng vai trò của RAG thành 3 tầng độc lập:

Thành phần	Cơ chế	Mặc định	Vai trò & Đặc điểm
Spec RAG*(Semantic Requirement Search)*	FAISS Vector Search + Multilingual Embedding (paraphrase-multilingual-MiniLM-L12-v2)	Tự động BẬT khi môi trường có gói RAG	• Phục vụ tìm kiếm yêu cầu (parse --query): tự động liên kết các khái niệm tương đồng ngữ nghĩa (vd: retry $\leftrightarrow$ redial / retransmission; voice $\leftrightarrow$ audio / call).• Cực nhẹ, vector hóa theo từng FR đã bóc tách (vài chục đến vài trăm vector).
KB Hybrid RAG & Reranker*(Verification Knowledge)*	Lexical + Semantic + Cross-Encoder Reranker (mmarco-mMiniLMv2-L12-H384-v1)	BẬT (rag.enabled: true)	• Truy xuất các ca nghiệm thu tương tự từ Knowledge Base.• Dùng cross-encoder chấm điểm và re-rank độ khớp trước khi đưa ngữ cảnh vào prompt cho LLM.
Code RAG*(Vectorized Code Chunks)*	Chunking toàn bộ source code C/C++ + FAISS embeddings	TẮT (code_rag_enabled: false)	• Phục vụ tìm kiếm bằng chứng code thô bằng vector.• Vì sao mặc định tắt? Spec-probe ưu tiên Knowledge Wiki Layer (AST, Subsystem, State Machine, Call Hierarchy) + Iterative Targeted Grep. Cách tiếp cận có cấu trúc này chạy nhanh hơn và chính xác hơn nhiều so với việc chia chunk vector thô trên code C/C++ lớn. User có thể bật trong config.json ("code_rag_enabled": true) khi muốn bổ sung thêm bằng chứng ngữ nghĩa cho các module trừu tượng.

💡 Lưu ý cài đặt:

• Máy cá nhân / Workstation cố định: nên chạy ./install.sh --both --init --rag một lần để có đầy đủ mô hình embedding và reranker.
• CI/CD / Container tạm thời: chỉ cần ./install.sh --both --init (không --rag) để tiết kiệm băng thông và hoàn thành setup trong vài giây.

---

Config

User chỉ sửa: ~/.config/spec-probe/

File	Bắt buộc?	Mục đích
.env	Có	EXACODE_API_KEY; thêm DEEPSEEK_API_KEY / COPILOT_GITHUB_TOKEN theo job
config.yaml	Có	Chỉ path dự án: module_path, spec_path, related_modules, domain_pack_paths (absolute)
config.json	Hiếm khi	Pipeline, LLM jobs, RAG, KB, report, collab — mặc định từ config.json.example khi --init

Coverage reports (Confluence / markdown) are English only: short rationale and key evidence links (no raw LLM audit dump). Gap bullets stay in English from verify (no report translation step).

OpenGrok / xref links: output.code_browser_base_url — chỉ trong file .md/.html và Collab; chat verify dùng link IDE.

Report: Mặc định verify/check chỉ trả kết quả trong chat (gồm phần thiếu/sai so spec). Ghi file .md/.html: chat tạo report → spec_cover report, hoặc verify --write-report, hoặc config.json → report.write_files: true. report.llm: true (mặc định) khi có file report.

Skill plumbing trong ~/.cursor/skills/spec-cover/config.yaml — không sửa (auto-generated).

Ví dụ config.yaml:

pipeline:
  mode: quality          # bật multi-module, bundle verify, RAG, verification KB

input:
  module_path: /path/to/my-module
  spec_path: /path/to/spec.md
  related_modules:
    paths:
      - /path/to/related-service

verification_kb:
  enabled: true
  append_on_verify: true

rag:
  enabled: true
  mode: hybrid           # lexical + semantic + rerank

---

Chuyển đổi LLM (backend + model slug)

Hai khái niệm tách bạch:

Khái niệm	Config	Ý nghĩa
Backend	provider	Cổng API:exacode, deepseek, copilot — không phải tên model
Model	model	Slug API của backend đó (bắt buộc hiểu đúng từng backend)

Backend	Ví dụmodel	Credentials
exacode	Chat-EXACODE-A (mặc định nếu bỏ trống)	EXACODE_API_KEY trong .env
deepseek	deepseek-v4-flash, deepseek-v4-pro, …	DEEPSEEK_API_KEY
copilot	Slug API — xemĐặt tên model Copilot	COPILOT_GITHUB_TOKEN — Login Copilot

Đặt tên model Copilot (slug API)

Danh sách tên hiển thị (cột Model name) nằm ở tài liệu GitHub — đó là nguồn đúng, không đoán slug:

Supported AI models in GitHub Copilot

Model khả dụng phụ thuộc gói Copilot và policy org (Enterprise/Business có thể phải bật model trong Copilot settings). Danh sách trên có thể thay đổi theo thời gian.

Cách đổi tên hiển thị → giá trị model trong config.json

1. Chọn model trong bảng Supported AI models (hoặc cùng tên trong model picker VS Code/Cursor).
2. Viết slug API: chữ thường, mỗi khoảng trắng → -, giữ nguyên số phiên bản và dấu chấm (.) trong tên.
3. Gán vào job: "provider": "copilot", "model": "<slug>".

spec-probe cũng chuẩn hoá tự động nếu bạn dán đúng Model name (vd "GPT-5.6 Luna" → gpt-5.6-luna) — xem spec_probe/llm/copilot_models.py.

Ví dụ (theo tài liệu GitHub, 2026)

Model name (GitHub / picker)	model trong config
GPT-5 mini	gpt-5-mini
GPT-5.3-Codex	gpt-5.3-codex
GPT-5.6 Luna	gpt-5.6-luna
GPT-5.6 Sol	gpt-5.6-sol
GPT-5.6 Terra	gpt-5.6-terra
Gemini 3.8 Flash	gemini-3.8-flash
Claude Sonnet 4.6	claude-sonnet-4.6
Grok 4.6	grok-4.6

Sai thường gặp: rút gọn bỏ phiên bản — vd GPT-5.6 Luna không phải gpt-5-luna (API: model not supported).

Ví dụ config (verify = Luna):

"verify": { "provider": "copilot", "model": "gpt-5.6-luna" }

Kiểm tra token + slug trước khi chạy pipeline:

spec-probe-copilot-test
spec-probe-copilot-test --job verify --model gpt-5.6-luna

Login Copilot (lấy token)

Dùng khi bất kỳ llm.jobs.* có provider: copilot (vd final_review + Gemini).

Yêu cầu: đã cài spec-probe (pip install -e . hoặc ./install.sh --init) để có lệnh spec-probe-copilot-login.

spec-probe-copilot-login

Hoặc trong repo:

python -m spec_probe.llm.copilot_login

Các bước:

1. Terminal hiện URL GitHub (device flow) và mã (vd ABCD-1234).

2. Mở URL trong browser, đăng nhập GitHub, nhập mã, Authorize.

3. Chờ vài giây — khi thành công, token được ghi vào ~/.config/spec-probe/.env:

   COPILOT_GITHUB_TOKEN=ghu_...
   

4. Trong config.json, bật Copilot cho job cần dùng, ví dụ:

   "final_review": { "provider": "copilot", "model": "gemini-3.8-flash" }
   

5. Chạy lại verify / spec-cover (reload Cursor nếu chạy qua skill).

Ghi token sang file khác (hiếm khi cần):

spec-probe-copilot-login --env-file /path/to/.env

Một token COPILOT_GITHUB_TOKEN cho một user/máy (từ spec-probe-copilot-login, thường prefix ghu_). Không dùng gh auth token (gho_) — exchange Copilot sẽ lỗi 401. Slug model: mục Đặt tên model Copilot.

Cấu hình LLM: llm.jobs (tùy từng bước pipeline)

Quy tắc: Mỗi job = một lần gọi LLM trong pipeline. Mặc định trong code là Exacode (Chat-EXACODE-A) nếu bạn xóa hẳn key job đó. Template đầy đủ 7 key trong config.json.example — copy rồi sửa provider / model từng dòng.

Job	Giai đoạn pipeline	Mặc định (không config)	Thứ tự khi thiếu config riêng
enrich	Làm rõ FR, tạo rubric / từ khóa tìm kiếm	Exacode	—
search	Grep lặp, đọc file, search agent	Exacode	—
rescue	NOT_FOUND rescue (grep/đọc bổ sung)	Exacode	dùngsearch nếu có → còn không thì Exacode
verify	Bundle evidence, per-candidate, synthesize verdict	Exacode	—
final_review	Kiểm tra lại verdict (quality mode)	Exacode	dùngverify nếu có → còn không thì Exacode
wiki	Build / index wiki kiến trúc (skill, CLI)	Exacode	—
translate	Dịch spec tiếng Nhật → Anh khi parse	Exacode	—
report	Tổng hợp báo cáo coverage sau verify	Exacode	—

Tùy chọn jobs.default: đổi backend cho mọi job chưa khai báo (thay Exacode built-in).

Ví dụ llm.jobs (7 slot — cùng config.json.example):

"jobs": {
  "enrich": { "provider": "exacode", "model": "Chat-EXACODE-A" },
  "search": { "provider": "exacode", "model": "Chat-EXACODE-A" },
  "rescue": { "provider": "exacode", "model": "Chat-EXACODE-A" },
  "verify": { "provider": "deepseek", "model": "deepseek-v4-flash" },
  "final_review": { "provider": "copilot", "model": "gemini-3.8-flash" },
  "wiki": { "provider": "exacode", "model": "Chat-EXACODE-A" },
  "translate": { "provider": "exacode", "model": "Chat-EXACODE-A" },
  "report": { "provider": "exacode", "model": "Chat-EXACODE-A" }
}

Chỉ muốn đổi một bước: giữ template trên, sửa một key; hoặc xóa các key Exacode — runtime vẫn fallback Exacode cho key thiếu. final_review không khai báo → dùng verify nếu có, rồi Exacode.

Copilot: jobs.<job>.provider = copilot, model = slug API — token qua Login Copilot.

Không cần restart IDE ngoài reload Cursor/VS Code (hoặc chạy lại CLI).

pipeline.mode: quality: preset mặc định (iterative Luna search, search_agent_enabled: false để tiết kiệm token; bật agent khi FR khó), verify_bundle_top_k: 16, not_found_rescue_enabled: true, final_review_full_file_enabled: true, parallel_workers: 1, …). Giá trị trong config.json / config.yaml → pipeline: không bị preset ghi đè. FR quan trọng: spec_cover verify --force <fr_id>.

Đổi tạm thời cho 1 lần chạy CLI (không sửa config.yaml) — set biến môi trường trước khi chạy:

export DEEPSEEK_API_KEY=sk-...
spec-probe verify --module /path/to/module --spec /path/to/spec.md --config /path/to/a-deepseek-config.yaml

(dùng --config trỏ tới file config khác với llm.jobs khác, tiện khi so sánh nhanh provider).

Lưu ý về DeepSeek: provider tùy chọn khi không có Exacode — cô lập trong spec_probe/llm/factory.py (comment "DeepSeek: test-only"). Muốn gỡ bỏ: xoá khối đó + field DEEPSEEK_API_KEY trong spec_probe/settings.py.

---

Usage (Hoàn toàn qua Chat)

Người dùng chỉ cần chat bằng ngôn ngữ tự nhiên trong Cursor hoặc VS Code Copilot. Không cần gõ bất kỳ lệnh CLI phức tạp nào.

---

1. Khởi tạo & Cập nhật Tri thức Kiến trúc (Knowledge Wiki)

Trước khi verify, bạn có thể yêu cầu AI quét và lập chỉ mục kiến trúc codebase và spec để tăng tối đa độ chính xác:

• Build / Cập nhật Wiki:

  "Build knowledge wiki cho module" "Index lại tri thức kiến trúc từ source code và file spec"

• Liệt kê & Xem danh sách Concept:

  "Liệt kê các subsystem và state machine đã được index trong wiki" "Hiển thị các concept kiến trúc trong wiki"

• Xem chi tiết một Subsystem / State Machine cụ thể:

  "Xem chi tiết kiến trúc concept variant" "Giải thích luồng hoạt động của state machine source_statemachine"

• Tra cứu nhanh tri thức kiến trúc theo từ khóa:

  "Tra cứu trong wiki về retry policy và state processing" "Query wiki xem module nào xử lý outbound messaging"

---

2. Khám phá, Tóm tắt & Nghiên cứu Spec (Optional Study Flow)

💡 Lưu ý về Luồng thực thi:

• Luồng chính (Verification): Không bắt buộc chạy bước này. Khi bạn gọi Build knowledge wiki ở Mục 1, hệ thống đã tự động bóc tách và liên kết toàn bộ requirement với mã nguồn.
• Khi nào dùng mục này? Khi kỹ sư muốn nghiên cứu tài liệu spec trước (human study/exploration): nắm cấu trúc tài liệu, xem có bao nhiêu section, lọc ra các FR ID liên quan đến tính năng mình quan tâm, hoặc đọc bản dịch tiếng Anh của spec tiếng Nhật.

• Xem tổng quan cấu trúc spec (Tóm tắt số lượng req theo section):

  "Spec này gồm những section và bao nhiêu requirement?" "Tóm tắt các phần chính trong spec"

• Liệt kê danh sách requirement để chọn lựa:

  "Liệt kê các requirement trong section Voice Connection" "Danh sách FR của section Authentication"

• Tìm kiếm requirement theo từ khóa / chủ đề:

  "Tìm các spec liên quan đến voice connection" "Có requirement nào nói về session timeout hoặc retry?"

• Sinh file Requirement Catalog Markdown để đọc trực tiếp:

  "Tạo catalog tổng hợp các requirement trong spec ra file markdown" (File catalog dịch ngữ tiếng Anh sẽ được lưu tại reports/specs/<tên_spec>_requirements.md để kỹ sư tiện tra cứu)

---

3. Kiểm tra Thực thi (Verify FR)

Yêu cầu AI đối soát trực tiếp mã nguồn C/C++ với yêu cầu trong spec:

• Kiểm tra một FR cụ thể:

  "Kiểm tra FR AUTH-001" "Verify REQ-042"

• Kiểm tra nhiều FR cùng lúc:

  "Kiểm tra các FR AUTH-001, NET-002, UI-003"

• Kiểm tra toàn bộ một section:

  "Verify toàn bộ section Network connectivity"

---

4. Kiểm tra Nhanh một Yêu cầu Bất kỳ (Ad-hoc Text Check)

Không cần file spec, bạn có thể dán trực tiếp một câu yêu cầu để AI quét code:

"Kiểm tra xem code đã implement yêu cầu này chưa: The module shall reject invalid credentials within 500ms" "Module có logic này không: The service shall retry the connection up to three times"

---

5. Xuất bản báo cáo lên Confluence

Đẩy kết quả lên wiki Confluence (cấu hình collab trong config.yaml + token trong .env):

"Publish báo cáo vừa chạy lên Confluence" "Verify FR AUTH-001 và publish kết quả"

---

6. Cách Đọc Kết quả Trả lời

AI sẽ trả lời trực tiếp trong khung chat với cấu trúc rõ ràng:

1. Bảng tóm tắt:
   • Trạng thái: IMPLEMENTED (Đạt đầy đủ), PARTIAL (Thiếu một phần tiêu chí), NOT_FOUND (Chưa tìm thấy triển khai).
2. Bằng chứng Code (Evidence):
   • Đường dẫn chính xác file:line đến vị trí cài đặt state machine, hàm xử lý event hoặc logic kiểm tra.
3. Chi tiết gap (PARTIAL / NOT_FOUND):
   • Implemented/evidenced — tiêu chí đã thấy trong code (bullet).
   • Not implemented/missing — tiêu chí chưa có hoặc chưa chứng minh (bullet đầy đủ).
   • Suggested fix — gợi ý sửa cụ thể (hàm, timer, SIP…).
   • Analysis — giải thích ngắn; kèm link file:line cho phần đã có.
   • IMPLEMENTED chỉ hiển thị tóm tắt ngắn + bằng chứng.
4. File báo cáo:
   • Đường dẫn file markdown tổng hợp đã được lưu tự động trong thư mục reports/.

---

Pipeline (quality mode)

load_spec
  → retrieve_context (verification KB + hybrid RAG)
  → enrich (clarify + section context)
  → search (structural + targeted grep + call-chain + code RAG + LLM agent)
  → caller_context
  → bundle_verify (top evidence chain)
  → cache + verification KB
  → coverage report

---

Verdicts

Verdict	Meaning
IMPLEMENTED	Acceptance criteria visible in source
PARTIAL	Some criteria met; incomplete chain
NOT_FOUND	No relevant evidence after search
NEEDS_REVIEW	Ambiguous — human review

---