Hybrid Knowledge Ingestion Workflow (Google Docs/Sheets + Local Documents)

Hybrid Knowledge Ingestion Workflow (Google Docs/Sheets Private)

Operational reference only. Knowledge Base content remains under docs/Shared/Knowledge Base/.

Nếu bạn chỉ cần dùng repo docs hoặc sửa docs canonical bình thường, không cần đọc file này.

Ở file này:

• ingest = kéo nội dung từ nguồn private vào repo theo pipeline đồng bộ
• mirror = bản copy markdown bám theo nguồn gốc, chưa phải lúc nào cũng là bản canonical cuối
• staging = vùng trung gian để review trước khi promote
• promote = đưa phần đã review vào docs canonical

Mục tiêu

Xây cơ chế thu thập tài liệu private từ Google Docs/Sheets, chuẩn hóa nội dung, phát hiện liên kết chéo và đưa về Knowledge Base dưới dạng cấu trúc logic hơn.

Nguyên tắc bảo mật

• File nguồn giữ private/local, không cần public.
• Cấp quyền tối thiểu:
  • documents.readonly
  • spreadsheets.readonly
  • drive.metadata.readonly
• Không commit token/key vào git.
• Mọi output đều giữ traceability về nguồn (source_id, source_url, auth_mode, fetched_at).

Mô hình Hybrid

• oauth_access_token:
  • Dùng cho cá nhân biên tập (đọc đúng quyền user).
  • Token đọc từ env GOOGLE_OAUTH_ACCESS_TOKEN.
• oauth_refresh_token (khuyến nghị):
  • Dùng quyền account thật của bạn, không cần share từng file.
  • Token có thể tự refresh để chạy sync lâu dài.
  • Đọc từ oauthCredentialsFile (ví dụ .secrets/google-oauth-refresh-token.json).
• service_account:
  • Dùng cho job automation ổn định.
  • Share file/folder cho email service account.
  • Key đọc từ GOOGLE_SERVICE_ACCOUNT_KEY_FILE hoặc GOOGLE_SERVICE_ACCOUNT_JSON.

Lấy OAuth access token nhanh (local, ngắn hạn)

export GOOGLE_OAUTH_ACCESS_TOKEN=\"$(gcloud auth print-access-token)\"

Lưu ý: token này ngắn hạn, phù hợp để chạy local/manual ingest.

Cách 2: OAuth refresh token (khuyến nghị)

Bước 1: tạo OAuth client (1 lần)

• Google Cloud Console -> APIs & Services -> Credentials -> Create Credentials -> OAuth client ID.
• Loại client: Desktop app.
• Tải file JSON client và lưu vào:
  • .secrets/google-oauth-client.json

Bước 2: bootstrap refresh token (1 lần)

npm run kb:oauth:setup

• Lệnh in URL xác thực.
• Mở URL, approve, rồi copy redirect URL cuối cùng.
• Exchange code:

node scripts/kb-oauth-setup.mjs --redirect-url "<PASTE_REDIRECT_URL>"

• Kết quả:
  • .secrets/google-oauth-refresh-token.json

Bước 3: cấu hình ingest

• authMode: oauth_refresh_token
• oauthCredentialsFile: .secrets/google-oauth-refresh-token.json

Cấu hình nguồn

1. Copy file mẫu:
   • config/knowledge-ingest/sources.example.json
2. Tạo local config:
   • config/knowledge-ingest/sources.local.json
3. Khai báo từng nguồn:
   • kind: gdoc hoặc gsheet
   • id: Google file ID hoặc full Google URL
   • authMode: oauth_refresh_token, oauth_access_token, hoặc service_account
   • outputMode: dùng clone để mirror thuần nội dung
   • targetPath: file đích cố định trong repo (để sync ghi đè cùng 1 file)

Lệnh ingest

# thêm nhanh 1 source từ Google URL (auto gdoc/gsheet + clone targetPath)
node scripts/kb-add-source.mjs --url "<GOOGLE_URL>"

# thêm hàng loạt từ 1 Drive folder (auto Docs/Sheets), target vào subfolder theo area
node scripts/kb-add-folder-sources.mjs --folder "<DRIVE_FOLDER_URL>" --target-subdir "Teaching tool"

# dry run
node scripts/kb-ingest.mjs --config config/knowledge-ingest/sources.local.json --dry-run

# ingest toàn bộ source
node scripts/kb-ingest.mjs --config config/knowledge-ingest/sources.local.json

# guard naming/layout cho Imported staging
npm run kb:guard:imported

# ingest theo source key/id
node scripts/kb-ingest.mjs --config config/knowledge-ingest/sources.local.json --only product-discovery-master-doc

Local Office/PDF convert

Lane này dùng cho file đã nằm trong repo/local Drive, ví dụ .pptx, .pdf, .docx, .xlsx, .xls.

# scan local documents without writing markdown
npm run kb:local:scan

# convert all detected local documents
npm run kb:local:convert

# convert a focused folder/file
npm run kb:local:convert -- --root "docs/Command/Resources/Documents/Exercise with AI 2026/Speaking" --only "Brief - Speaking LMS New.pptx"

Contract:

• Source files stay in docs/Command/Resources/Documents/**.
• Converted Markdown is written beside each source file under a sibling _converted/ folder.
• Filename preserves the source filename and appends .convert.md (example: Brief - Speaking LMS New.pptx.convert.md).
• Path/content hashes stay in frontmatter as source_path_hash and source_sha256.
• For .pptx, --keep-data-uris is enabled by config so slide images remain self-contained.

Output

• Markdown staging:
  • docs/Shared/Knowledge Base/Imported/NB_IMP_*.md
• Local converted Markdown:
  • docs/Command/Resources/Documents/**/_converted/*.convert.md
• Index tổng hợp:
  • docs/Shared/Knowledge Base/Imported/NB_IMP_INDEX.md
• Raw normalized cache:
  • .cache/kb-ingest/raw/<source-id>.json
• Run summary:
  • .cache/kb-ingest/last-run.json

Chu trình review đề xuất

1. Ingest vào Imported/ (staging).
2. Reviewer kiểm tra:
   • category đúng chưa
   • missing context
   • link chéo có hợp lệ
3. Promote nội dung đã duyệt sang khu vực chính trong docs/Shared/Knowledge Base/.

Mirror 1-1 (khuyến nghị cho nhu cầu đồng bộ)

• Mỗi source gán targetPath cố định.
• Chạy lại ingest sẽ ghi đè file đó, tạo hiệu ứng đồng bộ 2 chiều theo thời gian (Google -> repo).
• Với Google Docs private, nội dung mirror là markdown đã convert từ cấu trúc Doc, không thêm phần tóm tắt nếu outputMode=clone.
• Naming chuẩn cho imported mirror:
  • NB_IMP_<TitleToken>_<ShortId>.md
  • ví dụ: NB_IMP_Linearthinking_17ab81FwfH.md
• Folder import behavior:
  • kb-add-folder-sources quét đệ quy toàn bộ subfolder.
  • Chỉ add các file Google Docs/Sheets (hoặc shortcut trỏ đến Docs/Sheets).
  • Nếu báo Cannot access folder ..., cần cấp quyền folder cho đúng account đã cấp OAuth refresh token.

Rủi ro hiện tại (PoC)

• Heuristic phân loại nội dung vẫn đơn giản.
• Chưa có dedup semantic giữa các source trùng nội dung.

Nâng cấp nên làm tiếp

• Thêm resolver tự follow link Google để crawl depth=1..2.
• Thêm semantic merge + confidence score trước khi ghi markdown cuối.
• Bổ sung CI check cho schema config ingest.