Tools Index
AI Agent Instructions
Vai trò của thư mục này: /tools/ chứa toàn bộ automation scripts của RAC. Các script viết bằng Python standard library (zero-dependency) để có thể chạy trong bất kỳ CI runner container nào.
Kiến trúc shared library:
/tools/lib/frontmatter.py— Shared parser cho YAML frontmatter và simple YAML. Tất cả tools đều import module này.- Mỗi tool nằm trong sub-directory riêng với một
index.mdmô tả chi tiết usage.
Mapping tool → CI stage:
| Tool | CI Stage | Trigger | Mô tả |
|---|---|---|---|
validate.py | validate | Mọi branch push và MR event | Pass 1: schema/field validation. Pass 2: broken link check. |
generate_pir.py | report-generation | incident/* branch (manual trigger) | Đọc scratchpad.json → sinh PIR draft qua self-hosted LLM. |
drift_analyzer.py | review-automation | Nightly schedule trên main | Scan expired docs, phân tích git drift, output review report. |
schema_migrate.py | (manual) | Chạy thủ công khi bump schema version | Bulk-update frontmatter khi profile.yaml thay đổi major version. |
Environment variables quan trọng:
OKF_LLM_BASE_URL — URL endpoint của self-hosted LLM (OpenAI-compatible API)
OKF_LLM_MODEL — Model ID để generate PIR content
Sub-directories
| Tool Directory | Script | Mô tả |
|---|---|---|
| /tools/validate/index.md | validate.py | Schema + semantic link validator |
| /tools/report/index.md | generate_pir.py | AI PIR generator với LLM integration |
| /tools/review/index.md | drift_analyzer.py | Expired document drift analyzer |
| /tools/migrate/index.md | schema_migrate.py | Schema version migration tool |
| /tools/docusaurus/index.md | (website/) | Docusaurus v3 static site — plugins, CI/CD, Cloudflare Pages |