pp-qa-km

yellowadmin/pp-qa-km

Fork 0

Commit Graph

Author	SHA1	Message	Date
yellowadmin	b90727fc11	feat: diag_refs 對帳診斷 + ingest 進度可見性/Ctrl-C 安全 (Closes #2 ) (#5 ) ## 摘要本 PR 含兩個獨立關注點,各一 commit。 ### 1. `diag_refs` — source_ref↔manifest 對帳診斷 (`04f4fd5`) — 回應 #4 lint 的「source_ref 不在 manifest」只報對不上、不辨成因。新增 `tools/diag_refs.py`,把每個對不上的 source_ref 分成五類(hash 不符／路徑字串岔開／檔名 hash 後綴岔開／檔在磁碟未登記／完全無對應),各附修法,讓「補帳本(§14.3)」與「修規則(§12)」的相反處置不再混為一談。純唯讀、結束碼 `0/1`,可當搬機或改 manifest 後的閘門。附 selfcheck 驗五型別分類、結束碼與零寫檔。README §3.3/§6/§7/§8 同步。 ### 2. ingest 進度可見性 + Ctrl-C 安全回復 (`4add7fa`) — Closes #2 `--all-pending` 長時間本地 Ollama 攝入全程靜默,使用者不確定有沒有在跑、又不敢中斷: - 進度可見:每份來源 `[i/N]`、長文件逐段 `分段 k/n`、每個 item `↳ 新增/更新`、完成 `✓`,全 `flush=True` 即時顯示。 - Ctrl-C 安全:獨立攔 `KeyboardInterrupt`(它不是 `Exception` 子類,原本會略過善後)。因 commit 在迴圈之後,main 必然未受影響;中斷時印可照做的回復指令並以結束碼 130 收場。 ## 測試 - `python tools/selfcheck_diag_refs.py` — ALL PASS - `python tools/selfcheck_ingest.py` — ALL PASS(含進度標記、中斷後 main 未動、回復指令實測可回乾淨 main) - README markdownlint 0 issues Closes #2 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: LittleYellow <crazytea@gmail.com> Reviewed-on: #5	2026-07-24 05:42:35 +00:00
LittleYellow	0b4c2bbb15	修復中文路徑 preflight 與 BM25 核心詞落空，測資改照現實建兩個 bug 同源於自檢測資「照能過建、不照現實建」： - ingest preflight：git status --porcelain 預設會把含中文或空格的路徑加引號轉義，raw/ 白名單比對因此失效，中文檔名的 convert 產出被誤判為 raw/ 以外的未提交變更而中止攝入。舊測資用 ASCII 檔名，整條路徑從未被走過。 - search：BM25Okapi 的 idf 在 df >= N/2 時 <= 0（rank_bm25 對負 idf 的替代值 epsilon x average_idf 在 average_idf 為負時同樣為負），與 search() 的 s > 0 過濾相乘，會讓「每頁都提到的核心詞」查詢全數落空——知識庫愈小、詞愈核心愈嚴重，MCP 的 search_wiki 一併受害。改用 Lucene 式恆正 idf。舊測資每個查詢詞都只出現在一頁（df=1），恰好避開此配置。變更： - tools/ingest.py：preflight 比對前剝除 git 的轉義引號 - tools/search.py：_BM25 子類覆寫 _calc_idf 為 log(1 + (N-df+0.5)/(df+0.5)) - tools/selfcheck_ingest.py：新增 preflight 中文檔名放行 / 非 raw 擋下的檢查 - tools/selfcheck_search.py：新增與既有頁共用核心詞的測資，鎖住 idf 退化 - tools/convert/selfcheck.py、tools/selfcheck_lint.py：測資檔名改中文＋空格 - AGENTS.md §13.4：新增「測資照現實建，不是照能過建」規則 - README.md §3.2：補 convert 產出應保持未提交、由 ingest 一併 commit 的流程驗證：四個自檢全數通過；分別移除兩個修法後對應檢查會失敗。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-22 07:21:45 +08:00
LittleYellow	f9a863e271	Phase 3: 攝入管線 — kb.py 共用模組 + ingest.py（重試/fallback/branch+PR）+ selfcheck Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-07-14 20:58:30 +08:00

Author

SHA1

Message

Date

yellowadmin

b90727fc11

feat: diag_refs 對帳診斷 + ingest 進度可見性/Ctrl-C 安全 (Closes #2 ) (#5 )

## 摘要

本 PR 含兩個獨立關注點,各一 commit。

### 1. `diag_refs` — source_ref↔manifest 對帳診斷 (`04f4fd5`) — 回應 #4

lint 的「source_ref 不在 manifest」只報對不上、不辨成因。新增 `tools/diag_refs.py`,把每個對不上的 source_ref 分成五類(hash 不符／路徑字串岔開／檔名 hash 後綴岔開／檔在磁碟未登記／完全無對應),各附修法,讓「補帳本(§14.3)」與「修規則(§12)」的相反處置不再混為一談。純唯讀、結束碼 `0/1`,可當搬機或改 manifest 後的閘門。附 selfcheck 驗五型別分類、結束碼與零寫檔。README §3.3/§6/§7/§8 同步。

### 2. ingest 進度可見性 + Ctrl-C 安全回復 (`4add7fa`) — Closes #2

`--all-pending` 長時間本地 Ollama 攝入全程靜默,使用者不確定有沒有在跑、又不敢中斷:

- **進度可見**:每份來源 `[i/N]`、長文件逐段 `分段 k/n`、每個 item `↳ 新增/更新`、完成 `✓`,全 `flush=True` 即時顯示。
- **Ctrl-C 安全**:獨立攔 `KeyboardInterrupt`(它不是 `Exception` 子類,原本會略過善後)。因 commit 在迴圈之後,**main 必然未受影響**;中斷時印可照做的回復指令並以結束碼 130 收場。

## 測試

- `python tools/selfcheck_diag_refs.py` — ALL PASS
- `python tools/selfcheck_ingest.py` — ALL PASS(含進度標記、中斷後 main 未動、回復指令實測可回乾淨 main)
- README markdownlint 0 issues

Closes #2

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: LittleYellow <crazytea@gmail.com>
Reviewed-on: #5

2026-07-24 05:42:35 +00:00

LittleYellow

0b4c2bbb15

修復中文路徑 preflight 與 BM25 核心詞落空，測資改照現實建

兩個 bug 同源於自檢測資「照能過建、不照現實建」：

- ingest preflight：git status --porcelain 預設會把含中文或空格的路徑加引號
  轉義，raw/ 白名單比對因此失效，中文檔名的 convert 產出被誤判為 raw/ 以外的
  未提交變更而中止攝入。舊測資用 ASCII 檔名，整條路徑從未被走過。

- search：BM25Okapi 的 idf 在 df >= N/2 時 <= 0（rank_bm25 對負 idf 的替代值
  epsilon x average_idf 在 average_idf 為負時同樣為負），與 search() 的 s > 0
  過濾相乘，會讓「每頁都提到的核心詞」查詢全數落空——知識庫愈小、詞愈核心
  愈嚴重，MCP 的 search_wiki 一併受害。改用 Lucene 式恆正 idf。
  舊測資每個查詢詞都只出現在一頁（df=1），恰好避開此配置。

變更：
- tools/ingest.py：preflight 比對前剝除 git 的轉義引號
- tools/search.py：_BM25 子類覆寫 _calc_idf 為 log(1 + (N-df+0.5)/(df+0.5))
- tools/selfcheck_ingest.py：新增 preflight 中文檔名放行 / 非 raw 擋下的檢查
- tools/selfcheck_search.py：新增與既有頁共用核心詞的測資，鎖住 idf 退化
- tools/convert/selfcheck.py、tools/selfcheck_lint.py：測資檔名改中文＋空格
- AGENTS.md §13.4：新增「測資照現實建，不是照能過建」規則
- README.md §3.2：補 convert 產出應保持未提交、由 ingest 一併 commit 的流程

驗證：四個自檢全數通過；分別移除兩個修法後對應檢查會失敗。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-07-22 07:21:45 +08:00

LittleYellow

f9a863e271

Phase 3: 攝入管線 — kb.py 共用模組 + ingest.py（重試/fallback/branch+PR）+ selfcheck

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

2026-07-14 20:58:30 +08:00

3 Commits