141 lines
12 KiB
Markdown
141 lines
12 KiB
Markdown
# 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 頁面。
|
||
|
||
## 硬性約束（不可協商，違反即為缺陷）
|
||
|
||
1. **資料落地**：受 FSC 法遵限制，所有文件內容的 LLM 處理一律走本地 Ollama，任何情況下不得將文件內容送往雲端 API。**格式轉換一律使用本地程式庫，禁止任何雲端轉換服務。**
|
||
2. **模型設定外部化**：所有 Ollama 連線資訊與 model tags 不得寫死在程式碼中，一律讀取 `config/models.yaml`（規格見下方）。
|
||
3. **供應鏈限制**：禁止引入任何中國團隊開發或有中國關聯的模型與框架（含 bge、Qwen、Jina 系列）。未來若需 embedding，預設候選為 EmbeddingGemma（Google）或 snowflake-arctic-embed（Snowflake）。
|
||
4. **raw 層不可變**：`raw/` 內的文件只讀不改。原始檔（含 Office/PDF 原檔）與轉換後的 Markdown 皆登記 SHA-256 至 `raw/manifest.json`，轉換檔的 manifest 條目必須回指原始檔 hash。wiki 頁面引用來源時必須帶 `source_ref`（檔案路徑 + hash 前 8 碼）。
|
||
5. **HITL 閘門**：所有 wiki 層的變更以 git branch + PR 形式提交，經人工審核後才合併至 main。攝入腳本永遠不直接 commit 到 main。
|
||
6. **雙棧支援，單一事實來源**：專案設定必須同時支援 Claude Code 與 GitHub Copilot。schema 正本唯一存在於 `AGENTS.md`；`CLAUDE.md` 與 `.github/copilot-instructions.md` 只是薄指標檔（一行說明 + 引用 AGENTS.md），禁止在指標檔中複製 schema 內容。
|
||
7. **Copilot 成本紀律**：Copilot 於 2026/6/1 起按 token 計費（AI Credits）。所有 Copilot agent 設計為薄編排層——文件內容的 LLM 處理一律委派給本地 Ollama 腳本（shell out 至 `tools/`），Copilot 本身不直接讀取大量文件內容。
|
||
8. **最小詮釋原則**：遇到模糊需求時採取最小合理詮釋，並將所有假設以 `<!-- ASSUMPTION: ... -->` 註解形式標註在產出物內，不要擅自擴大範圍。
|
||
9. **語言**：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 規格
|
||
|
||
```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 正本）必須涵蓋
|
||
|
||
1. 頁面類型定義（summary / entity / concept）及各自的 YAML frontmatter 欄位：`type`、`title`、`description`、`tags`、`timestamp`、`sources`（source_ref 列表）、`status`（draft / reviewed / stale）
|
||
2. 「新頁 vs. 就地編輯」的判斷準則：獨立實體且會被他頁連結 → 新頁；既有實體的屬性更新 → 就地編輯
|
||
3. Ingest 工作流：轉換 → 讀來源 → 寫 summary → 更新相關 entity/concept 頁（單一來源可能觸及多頁）→ 更新 index.md → 追加 log.md → 開 PR
|
||
4. Lint 工作流：schema 完整性、過期主張（staleness）、覆蓋缺口、孤兒頁、重複頁偵測；產出 markdown 報告；**絕不擅自刪檔**，一律標記待人工核准
|
||
5. Query 工作流：先讀 index.md 定位候選頁（最多 10 頁）再讀內文，禁止全庫掃描
|
||
6. 雙棧規則：本檔為唯一正本；Claude Code 與 Copilot 的行為差異（若有）以附註標明，禁止另立分叉檔
|
||
7. 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 開始。
|