lint 檢查完成後產出的報告...可以幹嘛？ #4

New Issue

yellowadmin · 2026-07-23T08:14:36Z

yellowadmin commented

2026-07-23 08:14:36 +00:00

應該是有在，但是不知道為啥比對不出來？？

# Lint 報告 — 2026-07-23 16:06

- 檢查頁面數：19
- 發現項目：15（Schema 完整性 12、重複頁（LLM 判定） 3）
- LLM 比對：model=gemma4:12b，上限 15 對

> lint 絕不修改或刪除任何檔案；以下所有項目皆**待人工核准**後才處置。

## Schema 完整性

- [ ] `wiki/summaries/pluspay-faq.md` — source_ref 不在 manifest：raw/converted/www-pluspay-com-tw-faq-06b02fd9.md#752feda9
- [ ] `wiki/summaries/pluspay-personal-data-privacy-policy.md` — source_ref 不在 manifest：raw/converted/www-pluspay-com-tw-terms-personaldata-30d3e3fa.md#226b4839
- [ ] `wiki/summaries/pluspay-registration-instructions.md` — source_ref 不在 manifest：raw/converted/www-pluspay-com-tw-instructions-registered-29bda491.md#af710425
- [ ] `wiki/summaries/pluspay-terms-user.md` — source_ref 不在 manifest：raw/converted/www-pluspay-com-tw-terms-user-81d64467.md#85b9d650
- [ ] `wiki/entities/pluspay-account-security.md` — source_ref 不在 manifest：raw/converted/www-pluspay-com-tw-faq-06b02fd9.md#752feda9
- [ ] `wiki/entities/pluspay-account-types.md` — source_ref 不在 manifest：raw/converted/www-pluspay-com-tw-terms-user-81d64467.md#85b9d650
- [ ] `wiki/entities/pluspay-payment-tools.md` — source_ref 不在 manifest：raw/converted/www-pluspay-com-tw-faq-06b02fd9.md#752feda9
- [ ] `wiki/entities/pluspay-privacy-policy.md` — source_ref 不在 manifest：raw/converted/www-pluspay-com-tw-terms-personaldata-30d3e3fa.md#226b4839
- [ ] `wiki/entities/pluspay-registration-flow.md` — source_ref 不在 manifest：raw/converted/www-pluspay-com-tw-instructions-registered-29bda491.md#af710425
- [ ] `wiki/entities/pluspay-registration-process.md` — source_ref 不在 manifest：raw/converted/www-pluspay-com-tw-faq-06b02fd9.md#752feda9
- [ ] `wiki/concepts/e-payment-dispute-handling.md` — source_ref 不在 manifest：raw/converted/www-pluspay-com-tw-terms-user-81d64467.md#85b9d650
- [ ] `wiki/concepts/pluspay-error-codes.md` — source_ref 不在 manifest：raw/converted/www-pluspay-com-tw-faq-06b02fd9.md#752feda9

## 重複頁（LLM 判定）

- [ ] `wiki/summaries/pluspay-main-scan-online-trading.md ↔ wiki/summaries/pluspay-passive-scan-spec.md` — 疑似重複：兩者皆描述全盈支付的技術串接規範，包含相同的核心要素：SHA256 校驗、取消與退款的區分、以及透過 SFTP 進行對帳。
- [ ] `wiki/summaries/pluspay-personal-data-privacy-policy.md ↔ wiki/entities/pluspay-privacy-policy.md` — 疑似重複：兩頁皆在描述全盈支付根據個資法第 8 條第 1 項提供相同內容的法定告知事項，包含蒐集目的代碼、類別及保存期限。
- [ ] `wiki/entities/pluspay-settlement-files.md ↔ wiki/entities/pluspay-settlement.md` — 疑似重複：兩頁皆描述相同的文件類型（D與R）及相同的傳輸方式（SFTP）。

應該是有在，但是不知道為啥比對不出來？？ ``` # Lint 報告 — 2026-07-23 16:06 - 檢查頁面數：19 - 發現項目：15（Schema 完整性 12、重複頁（LLM 判定） 3） - LLM 比對：model=gemma4:12b，上限 15 對 > lint 絕不修改或刪除任何檔案；以下所有項目皆**待人工核准**後才處置。 ## Schema 完整性 - [ ] `wiki/summaries/pluspay-faq.md` — source_ref 不在 manifest：raw/converted/www-pluspay-com-tw-faq-06b02fd9.md#752feda9 - [ ] `wiki/summaries/pluspay-personal-data-privacy-policy.md` — source_ref 不在 manifest：raw/converted/www-pluspay-com-tw-terms-personaldata-30d3e3fa.md#226b4839 - [ ] `wiki/summaries/pluspay-registration-instructions.md` — source_ref 不在 manifest：raw/converted/www-pluspay-com-tw-instructions-registered-29bda491.md#af710425 - [ ] `wiki/summaries/pluspay-terms-user.md` — source_ref 不在 manifest：raw/converted/www-pluspay-com-tw-terms-user-81d64467.md#85b9d650 - [ ] `wiki/entities/pluspay-account-security.md` — source_ref 不在 manifest：raw/converted/www-pluspay-com-tw-faq-06b02fd9.md#752feda9 - [ ] `wiki/entities/pluspay-account-types.md` — source_ref 不在 manifest：raw/converted/www-pluspay-com-tw-terms-user-81d64467.md#85b9d650 - [ ] `wiki/entities/pluspay-payment-tools.md` — source_ref 不在 manifest：raw/converted/www-pluspay-com-tw-faq-06b02fd9.md#752feda9 - [ ] `wiki/entities/pluspay-privacy-policy.md` — source_ref 不在 manifest：raw/converted/www-pluspay-com-tw-terms-personaldata-30d3e3fa.md#226b4839 - [ ] `wiki/entities/pluspay-registration-flow.md` — source_ref 不在 manifest：raw/converted/www-pluspay-com-tw-instructions-registered-29bda491.md#af710425 - [ ] `wiki/entities/pluspay-registration-process.md` — source_ref 不在 manifest：raw/converted/www-pluspay-com-tw-faq-06b02fd9.md#752feda9 - [ ] `wiki/concepts/e-payment-dispute-handling.md` — source_ref 不在 manifest：raw/converted/www-pluspay-com-tw-terms-user-81d64467.md#85b9d650 - [ ] `wiki/concepts/pluspay-error-codes.md` — source_ref 不在 manifest：raw/converted/www-pluspay-com-tw-faq-06b02fd9.md#752feda9 ## 重複頁（LLM 判定） - [ ] `wiki/summaries/pluspay-main-scan-online-trading.md ↔ wiki/summaries/pluspay-passive-scan-spec.md` — 疑似重複：兩者皆描述全盈支付的技術串接規範，包含相同的核心要素：SHA256 校驗、取消與退款的區分、以及透過 SFTP 進行對帳。 - [ ] `wiki/summaries/pluspay-personal-data-privacy-policy.md ↔ wiki/entities/pluspay-privacy-policy.md` — 疑似重複：兩頁皆在描述全盈支付根據個資法第 8 條第 1 項提供相同內容的法定告知事項，包含蒐集目的代碼、類別及保存期限。 - [ ] `wiki/entities/pluspay-settlement-files.md ↔ wiki/entities/pluspay-settlement.md` — 疑似重複：兩頁皆描述相同的文件類型（D與R）及相同的傳輸方式（SFTP）。 ``` ![image.png](/attachments/ec44ce6c-bbaf-46bc-8baa-66f4007ce70b)

image.png

223 KiB

yellowadmin commented

2026-07-23 16:11:47 +00:00

報告能幹嘛

lint 報告是待人工核准的待辦清單 + CI 閘門,不是修復工具(AGENTS.md §7、§1.5):它只健檢、把發現列成 - [ ]、用結束碼 0/1 給排程當紅燈,絕不改檔。所以處置一律走 branch + PR,由人裁決。

這份只有 Schema + 重複兩節,代表過期/覆蓋缺口/孤兒頁三項都 0 發現——是好訊號。

「應該有在,為啥比對不出來?」

因為 lint 的 schema 檢查是精確字串比對:把每個 wiki 頁 source_ref 的路徑部分,拿去 manifest["files"] 找 key,對不上就報「不在 manifest」。檔案存在但比對不出來 → 不是掉檔,是 key 字串對不起來,差一個斜線、./ 前綴、大小寫、或檔名 hash 後綴就 miss。

正常情況下 ingest 寫 source_ref 時 path 直接取自 manifest key(source_ref = f"{t}#{sha8}"),天生一致、不會岔開。會岔開通常是攝入之後 manifest 被動過(重生/被 git restore 回舊版,掉了那幾筆 converted 條目,但 raw/converted/*.md 檔還在)——這跟近期在處理 CRLF/manifest hash 的那批改動吻合。

怎麼一次問到底

新增了 tools/diag_refs.py,專門把「對不上」分成五類、各附修法(已 commit 在分支 feat/convert-verify-reconcile,見 PR):

.venv\Scripts\python tools\diag_refs.py

型別	意思	修法
Hash 不符	帳本有此路徑、sha256 不同	raw 被就地改動/重轉,還原或連 source_ref 走 PR(§14.2)
路徑字串岔開	反斜線/`./`/大小寫,正規化後其實同一 key	修產生岔開字串的那一環,別逐頁改(§12)
檔名 hash 後綴岔開	帳本有同檔名幹、後綴不同的 key	核對正確檔名,別改帳本遷就(§14.2)
檔在磁碟、帳本無條目	檔還在、manifest 掉了條目	branch+PR 補登 manifest,別動 wiki 頁(§14.3)
完全無對應	帳本、磁碟、檔名幹全無	source_ref 攝入時寫歪或檔真的遺失,上報 HITL(§14.2)

先跑 python tools/convert/convert.py --verify 分類磁碟 vs 帳本,再看 diag_refs 的型別。你這 12 條(其實只牽涉 4 個來源檔)最可能落在檔在磁碟、帳本無條目(→ 補帳本)或路徑字串岔開(→ 修規則)——兩者修法相反,先分類再動手,別猜。

重複頁那 3 對

是 LLM 建議、待人工裁決的合併候選(§4「猶豫時傾向就地編輯、避免碎片化」):主掃 vs 被掃很可能是誤判(不同收單流程,只共用 SHA256/SFTP),保留並互相 cross-link;settlement-files ↔ settlement 最像真的該合併;summary ↔ entity 對同一來源本來就會像,若 entity 只是重講 summary 就合併。逐對判完勾掉,合併的走 PR。

## 報告能幹嘛 lint 報告是**待人工核准的待辦清單 + CI 閘門**,不是修復工具(AGENTS.md §7、§1.5):它只健檢、把發現列成 `- [ ]`、用結束碼 `0/1` 給排程當紅燈,**絕不改檔**。所以處置一律走 branch + PR,由人裁決。這份只有 Schema + 重複兩節,代表過期/覆蓋缺口/孤兒頁三項都 0 發現——是好訊號。 ## 「應該有在,為啥比對不出來?」因為 lint 的 schema 檢查是**精確字串比對**:把每個 wiki 頁 `source_ref` 的路徑部分,拿去 `manifest["files"]` 找 key,對不上就報「不在 manifest」。**檔案存在但比對不出來 → 不是掉檔,是 key 字串對不起來**,差一個斜線、`./` 前綴、大小寫、或檔名 hash 後綴就 miss。正常情況下 ingest 寫 `source_ref` 時 path 直接取自 manifest key(`source_ref = f"{t}#{sha8}"`),天生一致、不會岔開。會岔開通常是攝入之後 **manifest 被動過**(重生/被 `git restore` 回舊版,掉了那幾筆 converted 條目,但 `raw/converted/*.md` 檔還在)——這跟近期在處理 CRLF/manifest hash 的那批改動吻合。 ## 怎麼一次問到底新增了 `tools/diag_refs.py`,專門把「對不上」分成五類、各附修法(已 commit 在分支 `feat/convert-verify-reconcile`,見 PR): ```powershell .venv\Scripts\python tools\diag_refs.py ``` | 型別 | 意思 | 修法 | |---|---|---| | Hash 不符 | 帳本有此路徑、sha256 不同 | raw 被就地改動/重轉,還原或連 source_ref 走 PR(§14.2) | | 路徑字串岔開 | 反斜線/`./`/大小寫,正規化後其實同一 key | 修產生岔開字串的那一環,別逐頁改(§12) | | 檔名 hash 後綴岔開 | 帳本有同檔名幹、後綴不同的 key | 核對正確檔名,別改帳本遷就(§14.2) | | 檔在磁碟、帳本無條目 | 檔還在、manifest 掉了條目 | branch+PR 補登 manifest,別動 wiki 頁(§14.3) | | 完全無對應 | 帳本、磁碟、檔名幹全無 | source_ref 攝入時寫歪或檔真的遺失,上報 HITL(§14.2) | 先跑 `python tools/convert/convert.py --verify` 分類磁碟 vs 帳本,再看 diag_refs 的型別。你這 12 條(其實只牽涉 4 個來源檔)最可能落在**檔在磁碟、帳本無條目**(→ 補帳本)或**路徑字串岔開**(→ 修規則)——兩者修法相反,**先分類再動手,別猜**。 ## 重複頁那 3 對是 LLM 建議、**待人工裁決**的合併候選(§4「猶豫時傾向就地編輯、避免碎片化」):主掃 vs 被掃很可能是誤判(不同收單流程,只共用 SHA256/SFTP),保留並互相 cross-link;settlement-files ↔ settlement 最像真的該合併;summary ↔ entity 對同一來源本來就會像,若 entity 只是重講 summary 就合併。逐對判完勾掉,合併的走 PR。

yellowadmin referenced this issue

2026-07-23 16:14:00 +00:00

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

yellowadmin referenced this issue from a commit

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

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

yellowadmin commented

2026-07-24 10:06:40 +00:00