Môi trường và đóng góp CXK
Phiên bản 0.4 · 26/09/2026 · Hướng dẫn kỹ thuật ngoại tuyến; không chứng nhận môi trường triển khai.
1. Nguồn phụ thuộc
pyproject.toml là nguồn khai báo chính. backend/requirements.txt tham chiếu nhóm backend và dev từ thư mục gốc.
Nhóm mặc định chỉ có PyYAML để đọc schema. Không cài SDK nhà cung cấp như phụ thuộc bắt buộc.
| Nhóm | Mục đích | Điều kiện |
|---|---|---|
| Mặc định | Công cụ đọc YAML | Không gọi dịch vụ |
backend |
FastAPI, Pydantic, Uvicorn ngoại tuyến | Không mở Internet; không dữ liệu người dùng |
dev |
pytest, httpx và công cụ phát triển | Test trong tiến trình; dữ liệu tổng hợp |
docs |
Markdown cho công cụ tài liệu cũ | Cài gói không cho phép build hoặc công bố |
legacy_providers, retrieval, database |
Tách phụ thuộc thiết kế cũ | Chưa kiểm chứng tương thích, chưa được phép gọi dịch vụ |
voice, telegram |
Nhánh mở rộng | Không cài hoặc kích hoạt trong đợt này |
Các khoảng phiên bản trong khai báo không phải bản khóa toàn bộ môi trường.
Đợt 1 không cài thêm hoặc gỡ gói. Đợt 2 cài npm trong bản sao frontend trên ổ cục bộ.
Đợt 3 đã cài sạch Python từ .[backend,dev] trong môi trường tạm trên ổ cục bộ.
pip check đạt; 313 test đạt, một ca liên kết tượng trưng bị bỏ qua.
Đợt 4 kiểm lại: 381 test đạt, một ca bỏ qua trên môi trường đang chọn và môi trường cài sạch mới.
Đây là cài bản nguồn sao chép, chưa chứng minh tái lập mọi phiên bản hoặc bộ cài phân phối đầy đủ.
glossary_data mà công cụ cũ import vẫn thiếu; không cài package trùng tên ngẫu nhiên để che lỗi nguồn.
2. Môi trường đã quan sát
| Thành phần | Phiên bản quan sát |
|---|---|
| Python của VS Code | 3.14.3 trong .venv |
| FastAPI / Pydantic | 0.141.1 / 2.13.5 |
| Uvicorn / httpx | 0.54.0 / 0.28.1 |
| PyYAML / pytest | 6.0.3 / 9.1.1 |
| Markdown | Chưa có trong môi trường này |
Python tối thiểu khai báo là 3.11. Không suy kết quả 3.14.3 chứng minh tương thích mọi phiên bản hoặc Windows Server.
Đợt 2 kiểm Node 22.22.2, npm 10.9.7; 21 test Vue đạt, Vite 8.3.1 dựng thành công.
frontend/package-lock.json khóa phụ thuộc frontend. Chưa kiểm ODBC, IIS, SQL hoặc GPU.
3. Kiểm tra trên Windows
Dùng đúng Python đã chọn trong VS Code. Không dựa vào lệnh python bất kỳ trên PATH.
Đặt PYTHONIOENCODING=utf-8, PYTHONDONTWRITEBYTECODE=1 cho phiên chạy công cụ.
| Mục đích | Lệnh tính từ gốc dự án | Cách đọc kết quả |
|---|---|---|
| Test mã | python -m pytest -q -p no:cacheprovider |
Không thay thẩm định y khoa |
| Chạy qua PowerShell | tools/KIEM_TRA_CXK.ps1 -TestsOnly |
Mặc định tìm .venv/Scripts/python.exe; có -PythonPath |
| Cài sạch Python và test | tools/KIEM_TRA_MOI_TRUONG_SACH.ps1 |
Bản sao nguồn chọn lọc và venv mới ở TEMP; cần PyPI; không thay .venv hiện có |
| Test/build Vue | tools/KIEM_TRA_FRONTEND.ps1 |
Bản sao TEMP riêng; npm ci; xóa bản sao khi kết thúc, trừ -KeepBuild sau đạt |
| Kiểm dữ liệu thực | tools/KIEM_TRA_CXK.ps1 |
Tiếp tục thu kết quả các công cụ, exit khác 0 nếu có lỗi |
| Kiểm byte văn bản | python tools/KIEM_TRA_TEP_VAN_BAN.py --json |
Chỉ đọc .md/.py; --path giới hạn một file hoặc thư mục |
| Quét thêm HTML hiện có | tools/KIEM_TRA_CXK.ps1 -IncludeHtml |
Chỉ đọc; không build; có thể chậm trên ổ chia sẻ |
| Kho tri thức JSON | python tools/validate_schema.py --json |
Số file/mục, loại trừ, lỗi, trạng thái chưa thẩm định |
| Thuật ngữ một file | python tools/check_glossary.py --path README.md --json |
Giữ số dòng; tách ví dụ sai/đúng khỏi vi phạm |
| Link HTML JSON | python tools/link_audit.py --json |
Stdout; có thể kiểm một site khác bằng --path |
| Kiểm hồ sơ và số học lịch | python tools/AUDIT_RESEARCH_PACK.py |
Chỉ đọc; PLAN_ARITHMETIC tách khỏi PACK_CHECK; không thay quyết định lịch |
Các lệnh trong bảng là cách dùng, không xác nhận đã cài mới hoặc chạy máy chủ.
Không chạy --fix trên dữ liệu thật khi chưa review từng hành động. Xung đột thư mục tuần phải được đối chiếu thủ công.
Không xóa môi trường hoặc sửa nguồn y khoa để làm kiểm tra xanh.
Lệnh PowerShell mặc định chạy kiểm byte, cấu trúc, thuật ngữ rồi kho tri thức, kể cả khi công cụ trước phát hiện lỗi.
Kết quả test mã đạt không thay kết quả kiểm dữ liệu. Lệnh test tắt tự nạp phần mở rộng pytest ngoài cấu hình.
Kiểm Python trong môi trường mới
Task VS Code CXK: verify clean Python environment kiểm cú pháp PowerShell rồi chạy script cài sạch.
Script phải chạy bình thường, không nạp bằng dấu chấm vào phiên PowerShell hiện tại.
-PythonPathchọn trình thông dịch tạo môi trường; mặc định dùng.venv/Scripts/python.exe.- Chỉ sao chép mã, test, cấu hình, README và bốn file schema cần cho test; kiểm SHA-256 trước thực thi.
- Không sao chép nguồn y khoa, thẻ tri thức, bộ safety, website HTML hoặc dữ liệu người dùng.
- Tạo venv mới; cài
.[backend,dev]từ PyPI, chạypip check, liệt kê phiên bản và chạy hai thư mục test. - Tạm loại cấu hình pip/Python/pytest kế thừa được liệt kê trong script, rồi khôi phục trong
finally. - Mặc định xóa đúng thư mục TEMP do script tạo.
-KeepEnvironmentchỉ giữ sau khi mọi phép kiểm đạt. - Không gọi bộ sinh trang, mô hình hoặc cơ sở dữ liệu. Cài gói có dùng mạng; đây không phải vùng cách ly hệ điều hành.
Biên bản đợt 3 ghi phiên bản, kết quả và xác nhận dọn TEMP.
Python 3.14.3 đã được kiểm; chưa kiểm 3.11–3.13, nhóm tùy chọn, bộ cài phân phối hoặc máy chủ triển khai.
Starlette 1.7.0 cảnh báo TestClient dùng httpx sẽ thay đổi trong tương lai; test hiện tại vẫn đạt.
Chưa đổi sang httpx2, chưa có bản khóa Python và chưa kiểm lỗ hổng phụ thuộc.
Đọc kết quả kiểm byte
UTF8_BOM: có dấu nhận biết BOM đầu file; quy ước dự án không cho phép.INVALID_UTF8: không giải mã UTF-8 nghiêm ngặt được; không tự đoán bảng mã thay thế.EMPTY_FILE,MISSING_FINAL_NEWLINE: file rỗng hoặc thiếu ký tự xuống dòng cuối.EXCESS_EOF_BLANK_LINES: Markdown có dòng trắng sau dòng nội dung cuối; không kiểm toàn bộ định dạng Markdown.- Mã thoát 0: đã đọc ít nhất một file, không phát hiện lỗi trong phạm vi; 1: có lỗi byte/quy ước.
- Mã thoát 2: phạm vi không hợp lệ, rỗng, bị loại trừ trực tiếp hoặc có lỗi truy cập. Mã 2 ưu tiên hơn mã 1.
Công cụ ghi số byte, dòng và vị trí lỗi, không in đoạn nội dung. JSON đầy đủ xuất ra stdout, không ghi file báo cáo.
Thư mục môi trường chỉ bị loại khi có pyvenv.cfg; cache dùng danh sách tên chính xác. Mỗi loại trừ có lý do.
Không đi theo liên kết tượng trưng hoặc điểm chuyển hướng Windows. Kiểm trước khi đọc vẫn có giới hạn khi file bị thay đồng thời.
Nguồn y khoa cũng được đọc kiểm byte, nhưng không được tự sửa khi thấy lỗi. Không đánh giá chất lượng nội dung hoặc lỗi hiển thị chữ.
fix_encoding.py cũ không phải công cụ này; không chạy chế độ sửa hàng loạt để đóng các phát hiện mới.
4. Phạm vi từng bộ kiểm
| Công cụ | Đã kiểm | Không kiểm |
|---|---|---|
KIEM_TRA_TEP_VAN_BAN.py |
UTF-8 nghiêm ngặt, BOM, rỗng, kết thúc file; loại trừ có lý do | Không sửa byte, đoán bảng mã, kiểm ngữ nghĩa hoặc toàn bộ định dạng Markdown |
validate_schema.py và audit vault |
Quét KC/FAQ/EC/case đệ quy; dạng đã quan sát; trùng ID; lỗi parse và khung rỗng | Quyền nguồn, ký duyệt, độ đúng y khoa; không tự hợp nhất schema |
check_structure.py |
Vị trí file; môi trường có dấu nhận biết; xung đột không tự xóa | Chất lượng hoặc quyền của nội dung |
check_glossary.py |
Thuật ngữ văn xuôi; ví dụ sửa sai báo riêng; lỗi đọc/rỗng | Hiểu nghĩa câu hoặc kiểm phần mã đã che |
link_audit.py |
File HTML thật, href/src, đích và anchor | URL ngoài, JavaScript/CSS sinh động, công bố hợp pháp |
AUDIT_RESEARCH_PACK.py |
ID T/CAM-Y, bảng tuần đơn/khoảng, tổng giờ và tải; đối chiếu tuần với roadmap | Trạng thái T, phê duyệt, phụ thuộc theo nghĩa, mọi dòng tổng gõ tay hoặc lịch nhận việc |
KIEM_TRA_TRUOC_XUAT_BAN.py |
Cấu trúc bản kê giả, hash và phụ thuộc thuộc cú pháp hạn chế | Không xác thực phê duyệt hoặc điều khiển bộ sinh thật; các cờ cho phép luôn false |
Không chạy lại AUDIT_RESEARCH_PACK.py --inventory để ghi đè ảnh chụp trước nâng cấp.
Từ đợt 4, chế độ này từ chối đích đã tồn tại bằng mã 2 trước quét; tạo độc quyền còn chặn xung đột đến muộn.
Bộ kiểm từ chối tập kiểm kê rỗng trước khi tạo file. Không có tùy chọn ghi đè.
Bằng chứng phiên mới phải lưu riêng, có ngày và chỉ rõ những thay đổi ngoài phạm vi.
Đọc kết quả kiểm lịch và hồ sơ
audit_plan_hours(plan, roadmap=None) kiểm chuỗi Markdown theo bố cục bảng hiện có, không phân tích Markdown tổng quát.
Tổng nhiệm vụ được cộng từ T01–T20 và CAM-Y01–04; giờ người khác của CAM-Y thiếu cột thì bằng 0.
Kiểm tuần W1–W42 đúng một lần, số không âm hữu hạn và tải bốn vai trò theo giới hạn giả định.
Cho phép sai số làm tròn tổng mỗi vai trò tối đa 0,03h; đối chiếu roadmap chính xác từng tuần sau chuẩn hóa số.
Không kiểm ý nghĩa phụ thuộc, thời gian chờ, dòng tổng gõ tay hoặc người nhận việc thật.
Đợt 4: số học đạt, nhưng kiểm hồ sơ tổng thể trả 1 vì nguồn task_list.txt thiếu.
Bản sao HTML khớp hash cũ không tự thay nguồn; không xóa mục manifest để báo đạt.
Đã cài sạch lại 36 file nguồn/schema chọn lọc; pip check đạt, 381 test đạt, một ca bỏ qua và một cảnh báo TestClient.
Vùng TEMP đã dọn. Không dùng kết quả này làm kiểm nội dung kế hoạch, vì test số học dùng dữ liệu giả.
5. Đóng góp và kiểm tra lại
- Đọc AGENTS, GLOSSARY và sổ theo dõi. Kiểm file có bị phiên khác sửa không trước khi ghi.
- Phân quyền từng file khi dùng nhiều agent. Không tự mở dịch vụ hoặc thay trạng thái APPROVED.
- Viết test lỗi trước hoặc cùng bản sửa; dùng dữ liệu tổng hợp và thư mục tạm do test quản lý.
- Không đưa bí mật vào log. Phản hồi API không được lặp đầu vào, kể cả khi lỗi kiểm tra dữ liệu.
- So diff hoặc hash nếu không có Git. Kiểm encoding UTF-8 không BOM, liên kết và chẩn đoán mã.
- Ghi kết quả đạt, không đạt và chưa chạy. Lưu bằng chứng theo phiên bản, cập nhật sổ theo dõi và diary.
NCS phải đọc hiểu mã AI trước khi nhận dùng. Test đạt không hoàn tất T05/T09 hoặc mở bất kỳ cổng kiểm soát nào.