yellowadmin/pp-qa-km
1
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases Wiki Activity

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

Merged
yellowadmin merged 4 commits from feat/convert-verify-reconcile into main 2026-07-24 05:42:35 +00:00
Conversation 0 Commits 4 Files Changed 9 +492 -14
yellowadmin commented 2026-07-23 16:14:00 +00:00
Owner
Copy Link

摘要

本 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

## 摘要 本 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)
yellowadmin added 4 commits 2026-07-23 16:14:01 +00:00
feat: convert 新增 --verify 對帳模式 + 修復 Windows CRLF 使 hash 失準 f9a0cd2369 
- convert.py --verify：純唯讀 re-hash 全部登記檔並掃未登記檔，
  報 missing/mismatch/unregistered，不一致退出碼 1（供刪除/竄改後稽核）
- 修 write_text 在 Windows 轉 \n→\r\n 使磁碟 bytes 與登記 SHA-256 不符
  （converted md 與 web 快照原始檔），改 write_bytes 寫入所登記的那份 bytes
- selfcheck 補 clean/missing/mismatch/unregistered 四情境（全程唯讀斷言）
- AGENTS.md §14 raw 完整性與修復流程 + §1.4 hash==磁碟 bytes 不變式

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
fix: 加 .gitattributes 對 raw/** 關閉換行正規化 d41cb49a45 
core.autocrlf=true 下，已 commit 的 raw/converted/*.md 於 Windows checkout
會被 git 轉成 CRLF，使磁碟 bytes 與 manifest 登記的 LF-hash 不符、--verify
誤報 mismatch——在 git 層抵銷了轉換器的 write_bytes 修復。以 `raw/** -text`
把「登記 hash == 磁碟 bytes」的不變式延伸到 git 的 checkin/checkout。
AGENTS.md §1.4 補記此機制。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
feat: 新增 diag_refs — source_ref↔manifest 對帳診斷 04f4fd5ead 
lint 的「source_ref 不在 manifest」只報對不上、不辨成因。diag_refs 把每個
對不上的 source_ref 分成五類（hash 不符／路徑字串岔開／檔名 hash 後綴岔開／
檔在磁碟未登記／完全無對應），各附修法，讓「補帳本（§14.3）」與「修規則
（§12）」的相反處置不再混為一談。純唯讀、結束碼 0/1，可當搬機或改 manifest
後的閘門。附 selfcheck 驗五型別分類、結束碼與零寫檔。README §3.3/§6/§7/§8 同步。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
feat: ingest 進度可見性 + Ctrl-C 安全回復 (Closes #2) 4add7fa9d9 
issue #2：--all-pending 長時間本地 Ollama 攝入全程靜默，使用者不確定有沒有在
跑、又不敢中斷。三處補強：

- 進度可見：每份來源印 [i/N] 起始行、長文件逐分段印「分段 k/n」、每個
  knowledge-item 印「↳ 新增/更新」、完成印「✓」，全部 flush=True 即時顯示。
  最會靜默的分段迴圈正是重點回報處。
- Ctrl-C 安全：KeyboardInterrupt 不是 Exception 子類，原本會略過善後、把使用者
  留在 ingest 分支且無指引。改為獨立攔截——commit 在迴圈之後，故 main 必然未受
  影響——印出可照做的回復指令（git checkout main && git stash -u &&
  git branch -D <branch>），以結束碼 130 收場。

selfcheck_ingest 新增：驗進度標記出現；驗中斷後 main HEAD 未動、停在 ingest
分支、且照文件回復指令實測能回到乾淨 main（驗結果可用，非字串存在，§13.4）。
README §7 補一列。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
yellowadmin merged commit b90727fc11 into main 2026-07-24 05:42:35 +00:00
yellowadmin deleted branch feat/convert-verify-reconcile 2026-07-24 05:42:35 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
CLAUDE_AI yellowadmin
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: yellowadmin/pp-qa-km#5
Delete Branch "feat/convert-verify-reconcile"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?