Files

LittleYellow 59c16ea393 Phase 1: 骨架與 schema — 目錄結構、AGENTS.md 正本、指標檔、models.yaml、index/log 模板、manifest 結構

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-14 07:42:45 +08:00

12 KiB

Raw Blame History

QA 部門知識庫（LLM Wiki 模式）— 專案啟動 Prompt v2

使用方式：在空白專案資料夾中啟動 Claude Code（或 GitHub Copilot Chat agent mode），將本文件全文貼入作為第一則訊息。

你的角色與任務

你是本專案的首席架構師與實作者。任務：為一個金融業（電子支付）QA 測試部門，建置一套基於 Karpathy LLM Wiki 模式（https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f）的部門知識庫系統，最終透過一層薄的 MCP server 供團隊成員與內部 AI agents 查詢。

本專案的核心哲學：知識編譯一次、持續維護，而非每次查詢重新推導。 這不是 RAG 專案——不建向量庫、不做 chunk 檢索（至少第一版不做）。LLM 在文件攝入時就完成萃取、綜合與交叉引用，查詢時只讀已編譯的 wiki 頁面。

硬性約束（不可協商，違反即為缺陷）

資料落地：受 FSC 法遵限制，所有文件內容的 LLM 處理一律走本地 Ollama，任何情況下不得將文件內容送往雲端 API。格式轉換一律使用本地程式庫，禁止任何雲端轉換服務。
模型設定外部化：所有 Ollama 連線資訊與 model tags 不得寫死在程式碼中，一律讀取 config/models.yaml（規格見下方）。
供應鏈限制：禁止引入任何中國團隊開發或有中國關聯的模型與框架（含 bge、Qwen、Jina 系列）。未來若需 embedding，預設候選為 EmbeddingGemma（Google）或 snowflake-arctic-embed（Snowflake）。
raw 層不可變：raw/ 內的文件只讀不改。原始檔（含 Office/PDF 原檔）與轉換後的 Markdown 皆登記 SHA-256 至 raw/manifest.json，轉換檔的 manifest 條目必須回指原始檔 hash。wiki 頁面引用來源時必須帶 source_ref（檔案路徑 + hash 前 8 碼）。
HITL 閘門：所有 wiki 層的變更以 git branch + PR 形式提交，經人工審核後才合併至 main。攝入腳本永遠不直接 commit 到 main。
雙棧支援，單一事實來源：專案設定必須同時支援 Claude Code 與 GitHub Copilot。schema 正本唯一存在於 AGENTS.md；CLAUDE.md 與 .github/copilot-instructions.md 只是薄指標檔（一行說明 + 引用 AGENTS.md），禁止在指標檔中複製 schema 內容。
Copilot 成本紀律：Copilot 於 2026/6/1 起按 token 計費（AI Credits）。所有 Copilot agent 設計為薄編排層——文件內容的 LLM 處理一律委派給本地 Ollama 腳本（shell out 至 tools/），Copilot 本身不直接讀取大量文件內容。
最小詮釋原則：遇到模糊需求時採取最小合理詮釋，並將所有假設以  註解形式標註在產出物內，不要擅自擴大範圍。
語言：wiki 內容與註解以繁體中文為主，程式碼、識別字、專有名詞用英文。

目標架構

pp-qa-knowledge/
├── AGENTS.md                      # schema 正本：本專案最重要的檔案（見下方要求）
├── CLAUDE.md                      # 指標檔 → AGENTS.md
├── .github/
│   ├── copilot-instructions.md    # 指標檔 → AGENTS.md
│   └── agents/
│       ├── kb-ingest.agent.md     # Copilot Custom Agent：攝入編排
│       ├── kb-lint.agent.md       # Copilot Custom Agent：健檢編排
│       └── kb-query.agent.md      # Copilot Custom Agent：查詢
├── config/
│   └── models.yaml                # Ollama 端點與 model tags 設定（見下方規格）
├── raw/
│   ├── originals/                 # 原始檔（docx/xlsx/pdf/pptx/html 快照）
│   ├── converted/                 # 轉換後 Markdown（攝入管線的實際輸入）
│   └── manifest.json              # SHA-256 登記 + 原始檔↔轉換檔對應
├── wiki/
│   ├── summaries/                 # 每份來源一頁摘要
│   ├── entities/                  # 實體頁：系統、模組、API、法規條目、專案
│   └── concepts/                  # 概念頁：跨來源綜合（缺陷模式、測試策略、法遵準則）
├── index.md                       # 目錄式導航：每頁一行（連結 + 一句摘要 + 分類）
├── log.md                         # append-only 操作日誌，格式 `## [YYYY-MM-DD] <op> | <title>`
├── tools/
│   ├── convert/
│   │   ├── convert.py             # 統一入口：依副檔名分派
│   │   ├── from_docx.py           # Word → Markdown
│   │   ├── from_xlsx.py           # Excel → Markdown（表格）
│   │   ├── from_pdf.py            # PDF → Markdown（掃描件標記待 OCR，不擅自處理）
│   │   ├── from_pptx.py           # PowerPoint → Markdown（含講者備註）
│   │   └── from_web.py            # 網頁 URL → 本地 HTML 快照 + Markdown 正文萃取
│   ├── ingest.py                  # 攝入管線（讀 config/models.yaml，呼叫本地 Ollama）
│   ├── lint.py                    # wiki 健檢（同上）
│   └── search.py                  # 第一版：BM25 / 全文檢索，不用向量庫
├── mcp/
│   └── server.py                  # FastMCP 薄殼：search_wiki 與 read_page 兩個 tool
└── .gitea/workflows/              # lint 定時排程（Gitea Actions，之後部署用）

config/models.yaml 規格

ollama:
  base_url: "http://localhost:11434"
  timeout_seconds: 300
tasks:                    # 依任務指定模型，全部可調
  ingest:
    model: "CHANGE_ME"    # 例：gemma3:27b — Phase 0 與我確認實際 tag
    temperature: 0.2
    max_retries: 3
  lint:
    model: "CHANGE_ME"
    temperature: 0.1
    max_retries: 3
  fallback:
    model: "CHANGE_ME"    # 例：devstral — 主模型格式驗證連續失敗時切換
limits:
  mcp_response_max_tokens: 2000
  ingest_chunk_max_chars: 12000   # 超長文件的分段攝入門檻

所有 tools/ 與 mcp/ 下的程式讀取此檔，不接受環境變數以外的其他覆寫來源；缺欄位時報錯而非使用隱含預設值。

格式轉換規範（tools/convert/）

只用本地程式庫：docx 用 mammoth 或 python-docx、xlsx 用 openpyxl、pdf 用 pymupdf 或 pdfplumber、pptx 用 python-pptx、網頁用 trafilatura 或 readability-lxml
流程：原始檔存入 raw/originals/ 並登記 hash → 轉換 → Markdown 存入 raw/converted/ 並登記 hash 與對應關係 → 之後攝入管線只讀 converted 層
轉換品質規則：保留標題層級與表格結構；圖片抽出存為附檔並在 Markdown 留佔位引用；PDF 偵測到無文字層（掃描件）時登記為 needs_ocr 狀態並跳過，不擅自呼叫 OCR
網頁轉換：抓取當下同時保存完整 HTML 快照（來源可能消失），Markdown 只萃取正文；URL 與抓取時間寫入 manifest
每個轉換器可獨立執行也可被 convert.py 統一調度，皆有 --dry-run

Copilot Custom Agents（.github/agents/）

參照 Copilot Custom Agent 慣例撰寫三個 .agent.md，共同原則：agent 是編排者不是處理者——透過終端呼叫 tools/ 下的腳本完成實際工作，Copilot 只讀取腳本回傳的精簡結果（狀態、統計、報告路徑），不將文件全文拉進 context。

kb-ingest.agent.md：接收檔案路徑或 URL → 呼叫 convert.py → 呼叫 ingest.py → 回報攝入結果與 PR 連結
kb-lint.agent.md：呼叫 lint.py → 摘要報告重點 → 列出需人工核准的項目
kb-query.agent.md：呼叫 search.py 取得候選頁 → 只讀取命中的少數頁面 → 綜合回答並附 source_ref

內容邊界（wiki 化的判斷準則）

該 wiki 化（綜合壓縮散落多來源的事實才有價值）：跨專案缺陷模式、需求與測項的追溯關係、法遵測試準則綜合（FSC/AML/KYC 相關測試要求）、歷次結案報告的教訓、部門 SOP 的決策脈絡。
不該 wiki 化（單檔可 grep 的內容做鏡像是負價值）：測試案例的逐步驟內容、單一 API 的規格細節。這些留在 raw 層，wiki 只放指向它們的索引條目與跨案例綜合。

AGENTS.md（schema 正本）必須涵蓋

頁面類型定義（summary / entity / concept）及各自的 YAML frontmatter 欄位：type、title、description、tags、timestamp、sources（source_ref 列表）、status（draft / reviewed / stale）
「新頁 vs. 就地編輯」的判斷準則：獨立實體且會被他頁連結 → 新頁；既有實體的屬性更新 → 就地編輯
Ingest 工作流：轉換 → 讀來源 → 寫 summary → 更新相關 entity/concept 頁（單一來源可能觸及多頁）→ 更新 index.md → 追加 log.md → 開 PR
Lint 工作流：schema 完整性、過期主張（staleness）、覆蓋缺口、孤兒頁、重複頁偵測；產出 markdown 報告；絕不擅自刪檔，一律標記待人工核准
Query 工作流：先讀 index.md 定位候選頁（最多 10 頁）再讀內文，禁止全庫掃描
雙棧規則：本檔為唯一正本；Claude Code 與 Copilot 的行為差異（若有）以附註標明，禁止另立分叉檔
Meta-loop 紀律：審核者發現系統性問題時，修改的是本 schema 或 lint 規則，而非逐筆修正輸出（change the ruler, not the output）

分階段交付（每階段結束停下來等我驗收，不要一次做完）

Phase 0 — 對齊：閱讀本文件後，列出你的理解摘要、所有假設清單、以及需要我確認的問題（至少包含：本機實際的 Ollama model tags、部門文件的格式分佈比例、Copilot Custom Agent 在我環境的實際支援格式）。不寫任何程式碼。
Phase 1 — 骨架與 schema：建立目錄結構、撰寫 AGENTS.md 第一版與兩個指標檔、config/models.yaml、index.md 與 log.md 模板、raw/manifest.json 結構。
Phase 2 — 轉換管線：實作 tools/convert/ 全部轉換器與統一入口，附各格式的最小測試檔與轉換驗證。
Phase 3 — 攝入管線：實作 tools/ingest.py。含 SHA-256 登記、讀取 models.yaml、Ollama 呼叫、頁面產出、git branch + PR 準備。錯誤處理要完整——本地模型輸出不穩定是預期情況，需有格式驗證、重試、以及 fallback model 切換機制。
Phase 4 — Lint agent：實作 tools/lint.py 與報告格式，並準備 Gitea Actions workflow 草稿（cron 觸發）。
Phase 5 — MCP 薄殼與 Copilot Agents：FastMCP 實作 search_wiki（BM25，回傳 index 條目 + 相關度）與 read_page（回傳單頁全文 + frontmatter，依 models.yaml 的 token 上限截斷並附 source_ref）；撰寫三個 .agent.md。
Phase 6 — Pilot 驗收：我會提供 10–20 份真實部門文件（去敏後，含 Word/Excel/PDF/PPT 混合格式）。跑完整轉換 + 攝入，產出品質報告：各格式轉換成功率、攝入成功率、frontmatter 合規率、交叉引用正確性、人工抽驗結果。以此決定是否擴大。

成功標準

四種 Office 格式 + 網頁皆能一鍵轉換入庫，manifest 可完整追溯原始檔
Pilot 文件攝入後，任一團隊成員透過 MCP 或 kb-query agent 問「某功能的歷史缺陷模式」，能得到有 source_ref 的綜合答案
換一個 Ollama model tag 只需改 config/models.yaml，不動任何程式碼
lint 報告能抓出人為植入的矛盾頁（Phase 6 我會故意放）
Copilot agents 全程只經手精簡結果，credit 消耗趨近於零
全程無任何文件內容離開本機
每個階段的產出，模糊處都有 ASSUMPTION 註解

現在從 Phase 0 開始。

12 KiB Raw Blame History Unescape Escape