@cornhsu/polymigrate-darwin-x64 2.3.1 → 3.0.0

package/bin/PolyMigrate.Core.xml

@@ -109,8 +109,67 @@
         <member name="T:PolyMigrate.Core.Configuration.SiteConfigLoader">
             <summary>
             YAML site config 載入器(§3.9):underscored 命名、未知欄位報錯(不默默忽略)、載入後驗證。
+            <para>3.0 起「寫壞的 config 不該等到某個指令才炸」:每個欄位逐一看過,寫壞了會到使用時才擲例外、或安靜地產出錯東西的
+            (regex、URL、路徑形狀、列舉值、數值範圍、重複的 key、YAML 寫了 key 卻沒給值),都在這裡驗,一次列出全部、點名欄位。
+            不是每一種錯都驗得出來(selector 在真實頁面上選不選得到東西、頁型有沒有拼錯…),沒驗的列在 docs/contracts.md。用到時的檢查保留為第二道防線
+            (函式庫呼叫端可以不經 loader、直接在程式裡組 <see cref="T:PolyMigrate.Core.Configuration.SiteConfig"/>)。</para>
             </summary>
         </member>
+        <member name="F:PolyMigrate.Core.Configuration.SiteConfigLoader.MaxDelayMs">
+            <summary>
+            <c>site.polite.delay_ms</c> 的上限:probe 遇到 409 的重試等兩倍(<c>DelayMs * 2</c>),
+            超過 int 一半時乘出負數,<c>Task.Delay</c> 要到探測當下才擲例外。
+            </summary>
+        </member>
+        <member name="F:PolyMigrate.Core.Configuration.SiteConfigLoader.Bcp47">
+            <summary>BCP-47 的語法形狀(RFC 5646:主語言 2～8 字母或 x / i 開頭的私用與舊式標記,之後每段 1～8 個英數字)。</summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Configuration.SiteConfigLoader.LoadFile(System.String,System.Collections.Generic.List{System.String})">
+            <summary>
+            同上,另把載入時的 warning(用不到、但不是寫壞的設定,例如 lang_map 裡沒有的 pdf_labels)收進
+            <paramref name="warnings"/>。CLI 用這個,照既有慣例印在 stderr、不影響 exit code。
+            </summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Configuration.SiteConfigLoader.Load(System.String,System.String,System.Collections.Generic.List{System.String})">
+            <summary>同上,另收集載入時的 warning(見 <see cref="M:PolyMigrate.Core.Configuration.SiteConfigLoader.LoadFile(System.String,System.Collections.Generic.List{System.String})"/>)。</summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Configuration.SiteConfigLoader.DuplicateKeys(System.String)">
+            <summary>
+            同一個對照表裡重複的 key。YamlDotNet 預設安靜接受、後者覆蓋前者(<c>section_types: { news: article, news: event }</c>
+            載入後只剩 event,沒有任何提示;審查建議 4)。逐一走解析事件,記下每個對照表的路徑,訊息點名欄位與行號;
+            與其餘的驗證錯誤一起列出(後者照樣驗——用的是覆蓋後的值)。
+            </summary>
+        </member>
+        <member name="T:PolyMigrate.Core.Configuration.SiteConfigLoader.YamlLevel">
+            <summary><see cref="M:PolyMigrate.Core.Configuration.SiteConfigLoader.DuplicateKeys(System.String)"/> 走到的一層對照表或清單。</summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Configuration.SiteConfigLoader.YamlLevel.#ctor(System.Boolean,System.String)">
+            <summary><see cref="M:PolyMigrate.Core.Configuration.SiteConfigLoader.DuplicateKeys(System.String)"/> 走到的一層對照表或清單。</summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Configuration.SiteConfigLoader.YamlLevel.ChildPath">
+            <summary>下一個子節點(對照表的值、清單的項目)的路徑,並把這一層推進到下一格。</summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Configuration.SiteConfigLoader.YamlLevel.Consume(System.String)">
+            <summary>這一層讀到一個純量(對照表的 key 或值、清單的項目)。</summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Configuration.SiteConfigLoader.Present``1(System.Collections.Generic.List{System.String},``0,System.String)">
+            <summary>區段或純量寫了 key 卻沒給值 → 報一條、回 null(呼叫端就不再往下驗)。</summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Configuration.SiteConfigLoader.List(System.Collections.Generic.List{System.String},System.Collections.Generic.List{System.String},System.String)">
+            <summary>清單寫了 key 卻沒給值、或其中有沒給值的項目(<c>[~]</c>、<c>- </c>)時報錯;回傳可用的清單(null 時回 null)。</summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Configuration.SiteConfigLoader.IsWebPrefix(System.String)">
+            <summary>根相對路徑(<c>/media/</c>)或絕對 http(s) 網址,而且沒有會弄壞網址或內嵌 HTML 的字元。</summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Configuration.SiteConfigLoader.IsPrintableAscii(System.Char)">
+            <summary>可列印的 ASCII(0x20 空白～0x7E <c>~</c>):HTTP 標頭值唯一安全的範圍。</summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Configuration.SiteConfigLoader.IsSectionKey(System.String)">
+            <summary>section_types / section_flags 的 key:"" 或單一路徑段(與 lang_map 的 key 同一條規則)。</summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Configuration.SiteConfigLoader.IsPathSegment(System.String)">
+            <summary>單一路徑段:非空、不含 / \ :、不是 . 或 ..(與 slugs 的 --section / --lang 同一條規則)。</summary>
+        </member>
         <member name="T:PolyMigrate.Core.Configuration.TextEncodings">
             <summary>編碼解析(§3.1)。註冊 CodePages 讓 Big5/GB2312 等舊站編碼可用。</summary>
         </member>
@@ -132,6 +191,37 @@
         <member name="M:PolyMigrate.Core.Diagnostics.PathIssue.#ctor(PolyMigrate.Core.Diagnostics.Severity,System.String,System.String)">
             <summary>路徑安全問題(§3.4):輸出於 path_issues.csv 的一列。取代原本的裸 value-tuple。</summary>
         </member>
+        <member name="T:PolyMigrate.Core.Extraction.CssSelectors">
+             <summary>
+             config 裡的 CSS selector 語法檢查。
+            
+             <para>兩道防線。第一道在<b>載入 config 時</b>(<see cref="T:PolyMigrate.Core.Configuration.SiteConfigLoader"/>,3.0 起):所有 selector 欄位都驗,
+             包括這次沒有頁屬於那個頁型的 <c>type_rules</c>,以及根本不用 selector 的指令(<c>thumbs</c>、<c>probe-orphans</c>)
+             讀到的 config——寫壞的 config 不該等到某個指令、某個頁型才炸。2.x 刻意不在載入時驗,只是為了不讓原本能跑的
+             config 在 patch 版開始失敗。第二道在「真的要用」之前(<see cref="M:PolyMigrate.Core.Extraction.CssSelectors.Ensure(System.String,System.String)"/>、<see cref="M:PolyMigrate.Core.Extraction.CssSelectors.QueryAll(AngleSharp.Dom.IParentNode,System.String,System.String)"/>):
+             函式庫呼叫端可以不經 loader、直接在程式裡組 <see cref="T:PolyMigrate.Core.Configuration.SiteConfig"/>,這一層保證那種 config 寫壞時
+             也是 <see cref="T:PolyMigrate.Core.Configuration.ConfigException"/>,而不是 AngleSharp 的 <see cref="T:AngleSharp.Dom.DomException"/> 半途崩潰。</para>
+             </summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Extraction.CssSelectors.Problem(System.String,System.String)">
+            <summary>
+            <paramref name="selector"/> 合語法回 null,否則回點名欄位與 selector 的訊息(與 <see cref="M:PolyMigrate.Core.Extraction.CssSelectors.Ensure(System.String,System.String)"/> 擲出的相同)。
+            給載入 config 時一次收集所有錯誤用。
+            </summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Extraction.CssSelectors.Ensure(System.String,System.String)">
+            <summary>
+            <paramref name="selector"/> 不合語法時擲 <see cref="T:PolyMigrate.Core.Configuration.ConfigException"/>,訊息點名欄位
+            (CLI 原樣印出、exit 2)。拿空文件跑一次 QuerySelector:語法錯誤與文件內容無關,
+            而且這樣走的就是真正用到它時的同一條解析路徑,不會出現「檢查過了、用的時候還是爆」。
+            </summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Extraction.CssSelectors.QueryAll(AngleSharp.Dom.IParentNode,System.String,System.String)">
+            <summary>
+            等同 <c>root.QuerySelectorAll(selector)</c>,但語法錯誤時擲 <see cref="T:PolyMigrate.Core.Configuration.ConfigException"/>
+            (給沒辦法事先知道會不會用到、只能在用的當下檢查的呼叫端)。
+            </summary>
+        </member>
         <member name="T:PolyMigrate.Core.Extraction.ImageRef">
             <summary>frontmatter images 相簿的一筆(web 路徑 + alt)。</summary>
         </member>
@@ -251,6 +341,21 @@
             <param name="paths">輸入/輸出位置。</param>
             <param name="dryRun">true = 完整跑抽取與統計但不寫任何檔案(§3.8)。</param>
         </member>
+        <member name="P:PolyMigrate.Core.Extraction.ExtractionPipeline.OnCheckpoint">
+            <summary>
+            測試用:每個取消檢查點之前呼叫一次,參數是檢查點標籤(<c>page:&lt;raw 相對路徑&gt;</c>、<c>write</c>)。
+            讓測試能在「半途」取消——只用預先取消的 token,測不出逐頁的檢查到底有沒有作用。
+            </summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Extraction.ExtractionPipeline.Run(PolyMigrate.Core.Extraction.ExtractionPaths,System.Boolean,System.Threading.CancellationToken)">
+            <summary>
+            同上,可取消(取消時擲 <see cref="T:System.OperationCanceledException"/>;CLI 接 Ctrl-C 後回 130)。
+            逐頁檢查一次、媒體檔算 sha1 前逐檔檢查、寫清單之前再檢查一次:已寫出的 .md 保留(只寫不刪,重跑會覆寫),
+            清單檔要嘛整組寫出、要嘛一份都不寫。3.0 起 public:以新增 overload 的方式加,不替既有方法加選用參數
+            (那是二進位不相容)。
+            <para>方法開頭刻意不另外檢查:第一頁之前就是一個檢查點,0 頁時則由寫清單前那一個接住。</para>
+            </summary>
+        </member>
         <member name="M:PolyMigrate.Core.Extraction.ExtractionPipeline.FindStaleOutputs(System.String,System.Collections.Generic.HashSet{System.String})">
             <summary>
             content/ 裡有、但這次沒被寫到的 .md(見 <see cref="P:PolyMigrate.Core.Extraction.ExtractionReport.StaleOutputs"/>)。
@@ -260,6 +365,12 @@
         <member name="M:PolyMigrate.Core.Extraction.ExtractionPipeline.SuggestPairs(System.Collections.Generic.SortedDictionary{System.String,PolyMigrate.Core.Inventory.InventoryRecord},System.Collections.Generic.List{System.String},PolyMigrate.Core.Pairing.HreflangIndex)">
             <summary>對「只有單語」的 key 產生啟發式配對建議(§1.4);回傳 key → 建議,兩端各一筆。</summary>
         </member>
+        <member name="T:PolyMigrate.Core.Extraction.ExtractionPipeline.MediaManifest">
+            <summary>算好的 media_manifest.csv 列與更新過的雜湊快取(寫檔留給呼叫端,見 Run)。</summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Extraction.ExtractionPipeline.MediaManifest.#ctor(System.Collections.Generic.List{System.Collections.Generic.IReadOnlyList{System.String}},PolyMigrate.Core.Inventory.MediaHashCache)">
+            <summary>算好的 media_manifest.csv 列與更新過的雜湊快取(寫檔留給呼叫端,見 Run)。</summary>
+        </member>
         <member name="M:PolyMigrate.Core.Extraction.ExtractionPipeline.WriteHreflangMap(System.String,PolyMigrate.Core.Pairing.HreflangIndex)">
             <summary>
             原站宣告的 hreflang 全紀錄(§1.4)。**含不可用的**——這份檔案的用途是回答
@@ -277,6 +388,13 @@
             外部、錨點、mailto 等保留原樣。
             </summary>
         </member>
+        <member name="M:PolyMigrate.Core.Extraction.LinkRewriter.#ctor(PolyMigrate.Core.Configuration.SiteSection,PolyMigrate.Core.Configuration.UrlPatternSection,System.Collections.Generic.IReadOnlySet{System.String})">
+            <param name="pageRoutes">
+            鏡像裡每一頁的路由(<see cref="M:PolyMigrate.Core.Extraction.LinkRewriter.RouteForPath(System.String)"/> 算出來的)。連結目標是鏡像頁時一律照頁的規則改寫;
+            只有目標不是鏡像頁,才考慮「它其實是個檔案」(見 <see cref="M:PolyMigrate.Core.Extraction.LinkRewriter.Rewrite(System.String,System.String)"/>)。null = 不知道鏡像有哪些頁:
+            一律照頁的規則,與 9d17071 逐位元相同——日後新的呼叫端忘了傳時,至少不會把指向鏡像頁的連結改壞(最終驗證 I5)。
+            </param>
+        </member>
         <member name="M:PolyMigrate.Core.Extraction.LinkRewriter.RouteForUrl(System.String)">
              <summary>
              絕對 URL → 站內路由;**不同 host 一律回 null**。
@@ -289,8 +407,20 @@
         </member>
         <member name="M:PolyMigrate.Core.Extraction.LinkRewriter.RouteForPath(System.String)">
             <summary>
-            站內路徑 → 新路由:去動態副檔名、收攏 index。
-            內文連結改寫與 redirect_map 的 new_path 共用同一套規則(兩者不同步 = 301 打到破頁)。
+            站內路徑 → 頁的路由:去動態副檔名、收攏 index。
+            內文連結改寫與 redirect_map 的 new_path、hreflang 的目標共用同一套規則(兩者不同步 = 301 打到破頁)。
+            <para><b>這是頁的路由,不做任何「檔案」判斷</b>:redirect_map 的每一列都來自真的頁,在這裡猜「像不像檔案」
+            只會誤判(9254591 曾讓 /jane.doe.php、/CONTACT.PHP、/calendar.html 的路由與 301 改變,第三輪審查)。
+            必須與 9d17071 逐位元相同,PageRouteStabilityTests 釘住。</para>
+            </summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Extraction.LinkRewriter.FileRoute(System.String)">
+            <summary>
+            不是鏡像頁的連結目標,是不是「檔案」:是的話回傳不加尾斜線的路由,否則 null(照頁的規則)。
+            只有單段路徑會因此不同(多段本來就不加尾斜線)。下列一律當頁,不做判斷:剝掉了 strip_extensions、
+            原本以 / 結尾、或那一段是語言前綴(<c>/index</c> 沒有副檔名,本來就不會被當成檔案)。剩下的才看名字:點檔案(.htaccess),或副檔名是
+            1～16 個 ASCII 英數字、至少一個字母(.swf、.pdf、.mp4、.webmanifest)——
+            <c>v1.2-rc</c> 的 <c>.2-rc</c>、<c>2019.05.01</c> 的 <c>.01</c> 不算。
             </summary>
         </member>
         <member name="T:PolyMigrate.Core.Extraction.MediaPaths">
@@ -327,11 +457,32 @@
             圖片 → 根絕對網路路徑 + 壞圖偵測,最後 HTML → Markdown。
             </summary>
         </member>
+        <member name="M:PolyMigrate.Core.Extraction.PageExtractor.#ctor(PolyMigrate.Core.Configuration.SiteConfig,System.Collections.Generic.IReadOnlySet{System.String})">
+            <param name="pageRoutes">鏡像裡每一頁的路由,見 <see cref="T:PolyMigrate.Core.Extraction.LinkRewriter"/>;null = 不知道,連結一律照頁的規則。</param>
+        </member>
+        <member name="M:PolyMigrate.Core.Extraction.PageExtractor.EnsureSelectorsValid(System.Collections.Generic.IReadOnlyCollection{PolyMigrate.Core.Extraction.RawPage})">
+             <summary>
+             這一批頁會用到的 config selector,先各檢查一次語法(壞了擲 <see cref="T:PolyMigrate.Core.Configuration.ConfigException"/>)。
+            
+             <para>放在寫任何檔之前:<c>type_rules</c> 的 selector 只在碰到該頁型時才用到,
+             原本會在半途崩潰——前面的頁已經寫進 content/,清單檔卻一份都沒寫。
+             這是第二道防線:經 <see cref="T:PolyMigrate.Core.Configuration.SiteConfigLoader"/> 載入的 config 在載入時就驗過全部 selector(3.0 起);
+             這裡擋的是函式庫呼叫端直接在程式裡組、沒經過 loader 的 config,只檢查「這次真的會用到的」
+             (<c>extract.content</c> 每頁都用;<c>type_rules</c> 只看這批頁出現過的頁型),見 <see cref="T:PolyMigrate.Core.Extraction.CssSelectors"/>。
+             頁型只靠路徑判定,不必先解析 HTML。</para>
+             </summary>
+        </member>
         <member name="M:PolyMigrate.Core.Extraction.PageExtractor.ReadAlternates(AngleSharp.Dom.IDocument,System.String)">
              <summary>
-             &lt;head&gt; 裡的 <c>&lt;link rel="alternate" hreflang&gt;</c>——全站唯一由作者「宣告」的
+             頁面上的 <c>&lt;link rel="alternate" hreflang&gt;</c>——全站唯一由作者「宣告」的
              語言版本對應,其餘配對線索(路徑、相簿、日期、標題)都是推測出來的。
             
+             <para>讀的是<b>整份文件</b>,不只 <c>&lt;head&gt;</c>(這段註解原本寫「&lt;head&gt; 裡的」,與實作不符)。
+             規範上 <c>rel=alternate</c> 的 link 只該出現在 head,但舊站常因 include 檔帶 BOM 或 head 裡夾了文字,
+             讓 HTML5 解析器提早開 body,之後的 link 全落進 body——只讀 <c>doc.Head</c> 的話這類站的宣告會整批
+             安靜地消失。代價是正文裡亂放的 link 也會被當成宣告(仍須過 <see cref="T:PolyMigrate.Core.Pairing.HreflangIndex"/> 的門檻,
+             而且只是建議)。要不要改成只讀 head 是待裁定的取捨,見 HreflangPipelineTests。</para>
+            
              <para>刻意<b>不</b>認 <c>&lt;a hreflang&gt;</c>:那是「這個連結指向的東西是什麼語言」的標註,
              不是「本頁的某語言版本在這裡」的宣告。內文裡一句「另見 &lt;a hreflang="en"&gt;英文說明&lt;/a&gt;」
              會被當成本頁的英文版,而那通常是另一篇文章。</para>
@@ -464,6 +615,15 @@
         <member name="T:PolyMigrate.Core.Extraction.RawPageParser">
             <summary>鏡像檔路徑 → 頁面身分。鏡像檔名規則:原始 URL 路徑 + ".html"(如 ch/news/a.php → ch/news/a.php.html)。</summary>
         </member>
+        <member name="M:PolyMigrate.Core.Extraction.RawPageParser.MirrorSuffixes(System.Collections.Generic.IEnumerable{System.String})">
+            <summary>鏡像檔名要剝的尾綴,長的先比:<c>.php.html</c> 再 <c>.html</c>。</summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Extraction.RawPageParser.SlugOfFileName(System.String,System.Collections.Generic.IEnumerable{System.String})">
+            <summary>
+            鏡像檔名 → slug 的唯一規則(extract 用的就是這一條;空字串由呼叫端決定怎麼處理)。
+            給手上有 config、要與 extract 一致的呼叫端(例如 probe-orphans 的已知 slug 集)。
+            </summary>
+        </member>
         <member name="T:PolyMigrate.Core.Extraction.TitleCleaner">
             <summary>
             標題清理(規格 clean_title / _strip_date_prefix):去「YYYY/MM/DD 新聞:」類日期前綴;
@@ -471,6 +631,13 @@
             「新聞/News」類標記字由 config extract.title_markers 提供(i18n-first:不硬編任何語言的字)。
             </summary>
         </member>
+        <member name="F:PolyMigrate.Core.Extraction.TitleCleaner.PrefixOptions">
+            <summary>
+            標題前綴 regex 的選項(內建三式與 config 的 <c>strip_title_prefix</c> 共用)。IgnoreCase 一律搭 CultureInvariant:
+            否則 tr-TR 上的 Turkish-I 會讓 "News" 之類標記字在不同機器 locale 下清出不同結果。
+            載入 config 時也用同一組選項驗 <c>strip_title_prefix</c>,驗過的就一定編得起來。
+            </summary>
+        </member>
         <member name="T:PolyMigrate.Core.Inventory.Csv">
             <summary>
             極簡 CSV 輸出:RFC 4180 跳脫、\r\n 行尾、UTF-8 含 BOM(人工覆核走 Excel,無 BOM 中文會亂碼)。
@@ -541,6 +708,12 @@
         <member name="M:PolyMigrate.Core.Inventory.MediaHashCache.GetOrCompute(System.String,System.String)">
             <summary>檔案不存在回傳空值;快取命中免重讀,未命中計算並記入。</summary>
         </member>
+        <member name="M:PolyMigrate.Core.Inventory.MediaHashCache.TrySave">
+            <summary>
+            盡量存:失敗(目錄被佔住、唯讀、磁碟滿)就算了,回傳 false。這是內部加速檔,存不了只會讓下次變慢,
+            不可以影響交付的清單與 exit code(第三輪審查)。失敗時順手清掉寫到一半的暫存檔。
+            </summary>
+        </member>
         <member name="T:PolyMigrate.Core.Inventory.MirrorSlugs">
              <summary>
              鏡像裡已經有的 slug(<c>raw/{lang}/{section}/</c> 的檔名去尾綴)。
@@ -552,14 +725,35 @@
              那一半本來就是十幾行的一次性腳本,留給使用者;這一半只有 PolyMigrate 答得出來。
              </summary>
         </member>
-        <member name="M:PolyMigrate.Core.Inventory.MirrorSlugs.InDirectory(System.String)">
+        <member name="M:PolyMigrate.Core.Inventory.MirrorSlugs.InDirectory(System.String,System.Collections.Generic.IReadOnlyList{System.String})">
             <summary>
-            檔名 → slug:<c>20260101.php.html</c> → <c>20260101</c>。
+            目錄裡的 slug(檔名 → slug 見 <see cref="M:PolyMigrate.Core.Inventory.MirrorSlugs.SlugOf(System.String)"/>):<c>20260101.php.html</c> → <c>20260101</c>。
             只認 <c>*.html</c>——這正是 ExtractionPipeline 對「一個鏡像頁」的定義,同一把尺。
             逐檔取名的話,鏡像目錄被 Finder / 檔案總管開過長出來的 .DS_Store 會變成空字串 slug
             (輸出第一行就是空行),Thumbs.db 會變成一個叫「Thumbs」的假文章——
             而這個指令的賣點就是 stdout 乾淨到可以直接導成檔案再餵給 fetch-orphans。
             </summary>
+            <param name="stripExtensions">config 的 <c>url_pattern.strip_extensions</c>;null = 沒有 config,改用 <see cref="M:PolyMigrate.Core.Inventory.MirrorSlugs.SlugOf(System.String)"/> 的啟發式。</param>
+        </member>
+        <member name="M:PolyMigrate.Core.Inventory.MirrorSlugs.SlugOf(System.String)">
+             <summary>
+             沒有 config 時的鏡像檔名 → slug:先去掉結尾的 <c>.html</c>,再去掉一個動態副檔名。
+            
+             <para>原本取「第一個點之前」,含點的 slug 會被截斷(<c>v1.2-release.php.html</c> → <c>v1</c>、
+             <c>2019.05.01.php.html</c> → <c>2019</c>),餵給 <c>fetch-orphans --slugs</c> 就去抓不存在的網址。</para>
+            
+             <para><c>slugs</c> 與函式庫的 <c>MirrorSlugs</c> 不帶 config、不知道 <c>strip_extensions</c>,
+             所以「動態副檔名」認的是:點之後 1～8 個 ASCII 英數字、至少一個字母(<c>.php</c>、<c>.php5</c>、<c>.php3</c>、
+             <c>.asp</c>、<c>.aspx</c>、<c>.jsp</c>…;e0a8e6f 一度只認全是字母的,老 PHP 站的 <c>.php5</c> 因此退化,第三輪審查)。
+             沒有動態副檔名的乾淨網址站(<c>2019.05.01.html</c>、<c>v1.2-release.html</c>)不會被多剝一段。</para>
+            
+             <para><b>它仍是啟發式</b>,下列情況與 extract(<see cref="T:PolyMigrate.Core.Extraction.RawPageParser"/>,依 config 剝尾綴、分大小寫)
+             不一致:乾淨網址站的 <c>jane.doe.html</c>(這裡得到 <c>jane</c>,extract 是 <c>jane.doe</c>);
+             <c>strip_extensions: []</c> 的 <c>foo.php.html</c>(<c>foo</c> 對 <c>foo.php</c>);副檔名不在 <c>strip_extensions</c>
+             裡的,例如只列 <c>.php</c> 時的 <c>a.asp.html</c>、<c>a.php5.html</c>(<c>a</c> 對 <c>a.asp</c>、<c>a.php5</c>);
+             大小寫不符的,例如 <c>A.PHP.html</c>(<c>A</c> 對 <c>A.PHP</c>)。手上有 config 的呼叫端改傳
+             <c>stripExtensions</c>,走與 extract 完全相同的規則。</para>
+             </summary>
         </member>
         <member name="M:PolyMigrate.Core.Inventory.MirrorSlugs.EnsurePathSegment(System.String,System.String)">
              <summary>
@@ -575,8 +769,9 @@
              空字串合法(無語言前綴的站)。</para>
              </summary>
         </member>
-        <member name="M:PolyMigrate.Core.Inventory.MirrorSlugs.ForLanguage(System.String,System.String,System.String)">
+        <member name="M:PolyMigrate.Core.Inventory.MirrorSlugs.ForLanguage(System.String,System.String,System.String,System.Collections.Generic.IReadOnlyList{System.String})">
             <summary>單一語言的 slug 集(探測時用來跳過已抓過的)。</summary>
+            <param name="stripExtensions">有 config 時傳 <c>url_pattern.strip_extensions</c>,與 extract 用同一條規則;null = 啟發式。</param>
         </member>
         <member name="M:PolyMigrate.Core.Inventory.MirrorSlugs.List(System.String,System.String,System.String)">
             <summary>
@@ -699,11 +894,20 @@
         <member name="P:PolyMigrate.Core.Media.ThumbnailReport.Failures">
             <summary>(相對路徑, 錯誤訊息);縮圖失敗不阻斷(原圖可能截斷/損壞)。</summary>
         </member>
+        <member name="P:PolyMigrate.Core.Media.ThumbnailReport.AnimationsKept">
+            <summary>保留動畫(逐格縮放)的多格 GIF / WebP 數。這些也算在 <see cref="P:PolyMigrate.Core.Media.ThumbnailReport.Created"/> 裡。</summary>
+        </member>
+        <member name="P:PolyMigrate.Core.Media.ThumbnailReport.AnimationsAsFirstFrame">
+            <summary>
+            多格的 GIF / WebP 改用第一格的縮圖(與 2.3.1 的結果相同):(相對路徑, 原因)。原因是超過像素預算,
+            或保留動畫的縮圖會比原檔大。這些也算在 <see cref="P:PolyMigrate.Core.Media.ThumbnailReport.Created"/> 裡,不是失敗,不影響 exit code。
+            </summary>
+        </member>
         <member name="T:PolyMigrate.Core.Media.ThumbnailGenerator">
             <summary>
             縮圖產生(規格 make_thumbs.py):media/ 圖片 → 縮圖目錄(同結構、同檔名)。
             §2.6 坑:手機直拍照片 EXIF 方向顛倒 → 先依 EXIF 轉正(AutoOrient)再縮,
-            否則縮圖會顛倒/側躺。已存在的縮圖跳過(可重跑、增量)。
+            否則縮圖會顛倒/側躺。動畫 GIF / WebP 逐格縮放、保留動畫(3.0 起;2.3.1 以前只剩第一格)。已存在的縮圖跳過(可重跑、增量)。
             影像庫用 Magick.NET(Apache 2.0)——ImageSharp 4.x 建置即要求授權金鑰,已棄用(§3.7)。
             </summary>
         </member>
@@ -711,10 +915,78 @@
             <summary>
             縮圖產生(規格 make_thumbs.py):media/ 圖片 → 縮圖目錄(同結構、同檔名)。
             §2.6 坑:手機直拍照片 EXIF 方向顛倒 → 先依 EXIF 轉正(AutoOrient)再縮,
-            否則縮圖會顛倒/側躺。已存在的縮圖跳過(可重跑、增量)。
+            否則縮圖會顛倒/側躺。動畫 GIF / WebP 逐格縮放、保留動畫(3.0 起;2.3.1 以前只剩第一格)。已存在的縮圖跳過(可重跑、增量)。
             影像庫用 Magick.NET(Apache 2.0)——ImageSharp 4.x 建置即要求授權金鑰,已棄用(§3.7)。
             </summary>
         </member>
+        <member name="F:PolyMigrate.Core.Media.ThumbnailGenerator.DefaultAnimationPixelBudget">
+            <summary>
+            動畫縮圖的像素預算預設值:格數 × 畫布寬 × 畫布高 = 5,000 萬像素。
+            <para>逐格縮放要先把每一格補成完整畫面(Coalesce),記憶體與時間都跟「格數 × 畫布」成正比。審查實測:
+            400 格 1300x900(4.68 億像素)要 39 秒、峰值 3.2 GB,約每百萬像素 7 MB、0.08～0.2 秒;298 格 800x408 的真實錄影
+            (9,700 萬像素)要 21 秒,縮圖 4.18 MB 比原檔 1.8 MB 還大。5,000 萬像素讓最壞情況停在 10 秒以內、記憶體峰值約 250～400 MB(視內容而定;兩個 100 格 1000x500 的 GIF 實測約 250 MB 與 384 MB),
+            而一般的小動畫(480x270 × 100 格約 1,300 萬)照樣保留。超過的退回第一格(與 2.3.1 相同),摘要會列出。</para>
+            </summary>
+        </member>
+        <member name="P:PolyMigrate.Core.Media.ThumbnailGenerator.AnimationPixelBudget">
+            <summary>超過就退回第一格的像素預算;測試用小值才不必真的產生 5,000 萬像素的動畫。</summary>
+        </member>
+        <member name="F:PolyMigrate.Core.Media.ThumbnailGenerator.DefaultStillPixelLimit">
+            <summary>
+            靜態圖(與改用第一格的動畫)的像素上限預設值:2 × 89,478,485 = 178,956,970(約 179 MP),
+            Pillow 擲 DecompressionBombError 的門檻。
+            <para>小檔、巨大尺寸的圖(解壓縮炸彈)不經過動畫預算:一格 20000x20000 的 GIF 只有 270 KB,2.3.1 起照樣整張解碼,
+            實測 14.8 秒、峰值 1.6 GB(約每像素 4 位元組);65535x65535 這種宣告可以把機器拖垮。179 MP 以同樣的比例約 720 MB,
+            而 100 MP 級的相機原圖(11648x8736 約 101.8 MP)照常處理。超過的在解碼前就擋下(只 Ping 標頭),記成縮圖失敗。</para>
+            </summary>
+        </member>
+        <member name="P:PolyMigrate.Core.Media.ThumbnailGenerator.StillPixelLimit">
+            <summary>靜態圖的像素上限;測試用小值才不必真的產生巨大的圖。</summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Media.ThumbnailGenerator.Megapixels(System.Int64)">
+            <summary>以百萬像素(MP)表示,動畫預算與靜態圖上限的訊息共用:<c>400 MP</c>、<c>1.5 MP</c>、<c>4294.8 MP</c>。</summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Media.ThumbnailGenerator.StillImageTooLarge(System.String)">
+            <summary>
+            解碼前只讀標頭(Ping)拿尺寸;超過 <see cref="P:PolyMigrate.Core.Media.ThumbnailGenerator.StillPixelLimit"/> 回傳失敗訊息(例如
+            <c>20000x20000 (400 MP) exceeds the 179 MP still-image limit</c>),否則 null。
+            標頭讀不起來時也回 null,照舊交給解碼(壞檔照舊是一般的 failed)。
+            </summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Media.ThumbnailGenerator.Run(System.String,System.String,System.Action{System.String},System.Threading.CancellationToken)">
+            <summary>
+            同上,可取消(取消時擲 <see cref="T:System.OperationCanceledException"/>;CLI 接 Ctrl-C 後回 130)。
+            逐張檢查;每張縮圖本來就是原子寫入,中斷不會留下半截檔。3.0 起 public(2.x 只有 CLI 用得到)。
+            </summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Media.ThumbnailGenerator.ReadFrames(System.String)">
+            <summary>
+            多格讀取;讀不起來回 null(呼叫端改走單張路徑)。截斷的檔(舊站鏡像裡下載到一半的 GIF 很常見)多格讀取
+            直接擲例外,單張讀取卻讀得到第一格——退回單張,結果與 2.3.1 相同(第一格縮圖、不算 failed);
+            單張也讀不起來的才是 failed(審查必修 1)。
+            </summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Media.ThumbnailGenerator.PingFrames(System.String)">
+            <summary>
+            多格讀取但只讀中繼資料(Ping:格數與畫布大小,不解碼像素),先決定要不要保留動畫——
+            不先 Ping 的話,超過預算的大動畫光是讀進來就要好幾 GB。讀不起來回 null(改走單張路徑)。
+            </summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Media.ThumbnailGenerator.TryWriteAnimated(System.String,System.String,PolyMigrate.Core.Configuration.ThumbnailSection,System.String@)">
+            <summary>
+            多格的 GIF / WebP:逐格縮放、保留動畫(格數、每格的延遲與循環次數),寫到 <paramref name="tmp"/>。
+            單格(或其他格式、讀不起來的)回 false、<paramref name="firstFrameReason"/> 為 null,由呼叫端走一般的單張路徑。
+            確定是多格、但決定不保留動畫時也回 false,並在 <paramref name="firstFrameReason"/> 寫明原因(呼叫端改用第一格):
+            格數 × 畫布超過 <see cref="P:PolyMigrate.Core.Media.ThumbnailGenerator.AnimationPixelBudget"/>(審查實測 400 格要 39 秒、3.2 GB),
+            或保留動畫的縮圖比原檔大(縮圖的意義是更小;審查實測 298 格的錄影 1.8 MB → 4.18 MB)——
+            但動畫本來就不需要縮放、也不必轉正時,原檔本身就是最小的縮圖,直接複製(回 true,算保留動畫)。
+            <para>2.3.1 以前一律 <c>new MagickImage(file)</c>,只讀第一格:動畫縮圖變成靜止的第一格,而且沒有任何提示
+            (決策檔 L4 選項 A)。先 <c>Coalesce</c>:GIF 的後續格常只存「跟上一格不同的那一塊」,不補成完整畫面就縮,
+            各格的位置與大小會對不上(Coalesce 之後每格的畫布都從 (0,0) 起,AutoOrient 與 Resize 會跟著轉、跟著縮,
+            所以不必再 ResetPage——實測加不加輸出逐位元相同)。GIF 寫出前再 <c>Optimize</c> 回格間差異,檔案才不會因為每格都是全畫面而暴增;
+            WebP 的編碼器自己處理格間差異,不另外做。</para>
+            </summary>
+        </member>
         <member name="T:PolyMigrate.Core.Orphans.OrphanFetcher">
             <summary>
             抓回孤兒頁(規格 fetch_orphans.py):每個 slug 抓所有語言版進 raw/,
@@ -731,12 +1003,52 @@
             之後抽取統一依 config site.encoding 解碼(§3.1)。
             </summary>
         </member>
+        <member name="M:PolyMigrate.Core.Orphans.OrphanFetcher.AssetSources(System.Byte[])">
+            <summary>正文(<c>extract.content</c> 命中的節點)裡 img/source 的 src,字典序去重。</summary>
+        </member>
         <member name="M:PolyMigrate.Core.Orphans.OrphanFetcher.IsTransient(System.Exception,System.Threading.CancellationToken)">
             <summary>HTTP 層錯誤或請求逾時(非呼叫端主動取消)才算可略過的暫時性失敗。</summary>
         </member>
         <member name="M:PolyMigrate.Core.Orphans.OrphanFetcher.WriteAtomicAsync(System.String,System.Byte[],System.Threading.CancellationToken)">
             <summary>先寫暫存檔再原子改名:寫到一半被中斷不會在最終路徑留下半截檔(重跑會當它已完成)。</summary>
         </member>
+        <member name="T:PolyMigrate.Core.Orphans.ProbeReport">
+            <summary>
+            探測孤兒頁的結果(<see cref="M:PolyMigrate.Core.Orphans.OrphanProber.ProbeDetailedAsync(System.String,System.String,System.Int32,System.Int32,System.Collections.Generic.IReadOnlySet{System.String},System.Action{System.String},System.Threading.CancellationToken)"/>、<see cref="M:PolyMigrate.Core.PolyMigrator.ProbeOrphansAsync(System.String,System.String,System.Int32,System.Int32,System.String,System.Action{System.String},System.Threading.CancellationToken)"/>)。
+            分開統計「確定沒有」與「沒拿到回答」:伺服器掛了、被 WAF 擋、<c>base_url</c> 打錯時,<see cref="P:PolyMigrate.Core.Orphans.ProbeReport.Found"/> 一樣是空的,
+            但那不代表沒有孤兒頁——看 <see cref="P:PolyMigrate.Core.Orphans.ProbeReport.NoUsableAnswers"/>。3.0 起 public(2.x 是 internal 的 ProbeResult)。
+            <para>建構子是 internal:結果只由探測產生。取得方式有兩種——
+            用 facade:<c>await PolyMigrator.FromConfigFile("site.yaml").ProbeOrphansAsync(root, "news", 2021, 2023)</c>
+            (自己建 HttpClient、自己算已鏡像的 slug,規則與 CLI 的 <c>probe-orphans</c> 相同);或用底層型別、自己提供
+            HttpClient 與已知 slug 集:<c>await new OrphanProber(config, httpClient).ProbeDetailedAsync(langPrefix, section, yearFrom, yearTo, known)</c>
+            (<c>known</c> 通常是 <see cref="M:PolyMigrate.Core.Orphans.OrphanProber.KnownSlugs(System.String,System.String,System.String,System.Collections.Generic.IReadOnlyList{System.String})"/>,
+            HttpClient 用 <see cref="M:PolyMigrate.Core.Orphans.OrphanProber.CreateHttpClient(PolyMigrate.Core.Configuration.SiteConfig,System.Boolean)"/> 建才會帶 User-Agent、cookie,而且不跟轉址)。</para>
+            </summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Orphans.ProbeReport.#ctor">
+            <summary>只由探測產生;呼叫端拿到的都是填好的結果。</summary>
+        </member>
+        <member name="P:PolyMigrate.Core.Orphans.ProbeReport.Found">
+            <summary>命中的 slug,依探測順序(= <see cref="M:PolyMigrate.Core.Orphans.OrphanProber.ProbeAsync(System.String,System.String,System.Int32,System.Int32,System.Collections.Generic.IReadOnlySet{System.String},System.Action{System.String},System.Threading.CancellationToken)"/> 的回傳值)。</summary>
+        </member>
+        <member name="P:PolyMigrate.Core.Orphans.ProbeReport.Checks">
+            <summary>探過的候選數(含後綴變體;每個候選最多兩次 HTTP 請求,這裡只算一次)。</summary>
+        </member>
+        <member name="P:PolyMigrate.Core.Orphans.ProbeReport.Unanswered">
+            <summary>
+            沒拿到「有/沒有」回答的候選,依原因計數(<c>HTTP 503</c>、<c>connection error</c>、<c>timeout</c>…),鍵依 ordinal 排序。
+            「確定沒有」的回答是 404、410、其他 2xx 與 3xx(不跟轉址);401/403/429/5xx、重試後仍 409、連線錯誤與逾時算沒拿到回答。
+            </summary>
+        </member>
+        <member name="P:PolyMigrate.Core.Orphans.ProbeReport.UnansweredCount">
+            <summary><see cref="P:PolyMigrate.Core.Orphans.ProbeReport.Unanswered"/> 的總數。</summary>
+        </member>
+        <member name="P:PolyMigrate.Core.Orphans.ProbeReport.NoUsableAnswers">
+            <summary>
+            一個回答都沒拿到(探了至少一個候選,而且全部沒拿到回答)。這時 <see cref="P:PolyMigrate.Core.Orphans.ProbeReport.Found"/> 是空的,但不可讀成
+            「沒有孤兒頁」:CLI 的 <c>probe-orphans</c> 在這個情況 exit 2、不覆寫既有清單。
+            </summary>
+        </member>
         <member name="T:PolyMigrate.Core.Orphans.OrphanProber">
             <summary>
             孤兒頁探測(規格 probe_orphans.py;§2.6:索引移除但頁面還在)。
@@ -757,7 +1069,40 @@
             <summary>逐日期候選 slug:每一天先 MMDDYYYY 再 YYYYMMDD(與規格同序)。</summary>
         </member>
         <member name="M:PolyMigrate.Core.Orphans.OrphanProber.KnownSlugs(System.String,System.String,System.String)">
-            <summary>已抓到的 slug(raw/{lang}/{section}/ 檔名),探測時跳過。</summary>
+            <summary>
+            已抓到的 slug(<c>raw/{lang}/{section}/</c> 的檔名),探測時跳過。
+            <para>這個多載不帶 config,所以檔名 → slug 用的是啟發式:去掉結尾的 <c>.html</c>,再去掉一段 1～8 個 ASCII 英數字、
+            至少一個字母的副檔名(<c>.php</c>、<c>.php5</c>、<c>.asp</c>…;2.3.1 以前是取第一個點之前)。它與 <c>extract</c>
+            的 slug 在這些情況不一致:乾淨網址站的 <c>jane.doe.html</c>(這裡得到 <c>jane</c>);<c>strip_extensions: []</c> 的
+            <c>foo.php.html</c>(這裡得到 <c>foo</c>);副檔名不在 <c>strip_extensions</c> 裡的(只列 <c>.php</c> 時的
+            <c>a.php5.html</c>、<c>a.asp.html</c>,這裡得到 <c>a</c>);大小寫不符的(<c>A.PHP.html</c>,這裡得到 <c>A</c>)。
+            手上有 config 時用帶 <c>stripExtensions</c> 的多載,結果與 <c>extract</c> 及 CLI 的 <c>probe-orphans</c> 一致。</para>
+            </summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Orphans.OrphanProber.KnownSlugs(System.String,System.String,System.String,System.Collections.Generic.IReadOnlyList{System.String})">
+            <summary>
+            同上,但依 config 的 <c>url_pattern.strip_extensions</c> 剝檔名尾綴(傳 <c>config.UrlPattern.StripExtensions</c>):
+            與 <c>extract</c> 寫出的 slug 完全相同的規則,CLI 的 <c>probe-orphans</c> 用的就是這個(3.0 起 public)。
+            </summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Orphans.OrphanProber.ProbeDetailedAsync(System.String,System.String,System.Int32,System.Int32,System.Collections.Generic.IReadOnlySet{System.String},System.Action{System.String},System.Threading.CancellationToken)">
+            <summary>
+            同 <see cref="M:PolyMigrate.Core.Orphans.OrphanProber.ProbeAsync(System.String,System.String,System.Int32,System.Int32,System.Collections.Generic.IReadOnlySet{System.String},System.Action{System.String},System.Threading.CancellationToken)"/>,另外分開統計「確定沒有」與「沒拿到回答」。
+            兩者原本一律當成「不存在」:伺服器掛了、被 WAF 擋、base_url 打錯時,探測照樣「跑完、0 筆」,
+            而空清單會被讀成「沒有孤兒頁」。CLI 靠這份統計決定清單能不能信、要不要寫(3.0 起 public)。
+            </summary>
+        </member>
+        <member name="F:PolyMigrate.Core.Orphans.OrphanProber.Answer.Exists">
+            <summary>200。</summary>
+        </member>
+        <member name="F:PolyMigrate.Core.Orphans.OrphanProber.Answer.Absent">
+            <summary>確定沒有:404、410、其他 2xx,以及 3xx(不跟轉址,轉址頁不算命中,見 <see cref="M:PolyMigrate.Core.Orphans.OrphanProber.CreateHttpClient(PolyMigrate.Core.Configuration.SiteConfig,System.Boolean)"/>)。</summary>
+        </member>
+        <member name="F:PolyMigrate.Core.Orphans.OrphanProber.Answer.None">
+            <summary>沒拿到「有沒有」的回答:連線錯誤、逾時、重試後仍 409,以及 401/403/429/5xx 等其餘狀態。</summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Orphans.OrphanProber.ProbeOneAsync(System.String,System.String,System.String,System.Threading.CancellationToken)">
+            <returns>回答;<see cref="F:PolyMigrate.Core.Orphans.OrphanProber.Answer.None"/> 時附上原因(<c>HTTP 503</c>、<c>connection error</c>、<c>timeout</c>)。</returns>
         </member>
         <member name="M:PolyMigrate.Core.Orphans.OrphanProber.CreateHttpClient(PolyMigrate.Core.Configuration.SiteConfig,System.Boolean)">
             <summary>
@@ -765,6 +1110,19 @@
             probe 不跟轉址(轉址頁不算命中);fetch 要跟(頁面可能在 301 之後)。
             </summary>
         </member>
+        <member name="T:PolyMigrate.Core.Orphans.SitePaths">
+             <summary>
+             舊站上的「語言前綴/section/slug」路徑。
+            
+             <para>語言前綴可以是空字串(<c>lang_map</c> 的 key 是 <c>""</c> = 沒有語言前綴的站,
+             見 <see cref="T:PolyMigrate.Core.Inventory.MirrorSlugs"/>)。直接 <c>$"{base}/{lang}/{section}/…"</c> 會組出
+             <c>//news/…</c>:nginx 預設合併斜線所以看不出來,但不合併斜線的伺服器或框架路由會讓
+             probe 全部落空、fetch 全部 404。所以只接非空的段。</para>
+             </summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Orphans.SitePaths.Join(System.String[])">
+            <summary>非空的段以 <c>/</c> 連接(不加開頭斜線):<c>("", "news", "a")</c> → <c>news/a</c>。</summary>
+        </member>
         <member name="T:PolyMigrate.Core.Pairing.HreflangRow">
             <summary>
             <c>hreflang_map.csv</c> 的一列:一則宣告,加上它經不經得起查證。
@@ -886,7 +1244,11 @@
             <summary>title_similarity 低於此值不當證據(跨語言標題相似度本就偏弱)。</summary>
         </member>
         <member name="M:PolyMigrate.Core.Pairing.PairingSuggester.Evaluate(PolyMigrate.Core.Pairing.UnpairedGroup,PolyMigrate.Core.Pairing.UnpairedGroup)">
-            <summary>回傳命中的證據(依 fallback 順序);空 = 無任何依據,不建議。</summary>
+            <summary>
+            回傳命中的證據(依 fallback 順序);空 = 無任何依據,不建議。
+            數值一律以 invariant 文化格式化(§3.10 決定性輸出):原本跟著執行機器的文化,
+            th-TH 寫出佛曆 <c>date=2567-01-21</c>、de-DE 寫出 <c>title_similarity=0,50</c>。
+            </summary>
         </member>
         <member name="M:PolyMigrate.Core.Pairing.PairingSuggester.HreflangToken(PolyMigrate.Core.Pairing.UnpairedGroup,PolyMigrate.Core.Pairing.UnpairedGroup)">
             <summary>
@@ -937,8 +1299,10 @@
         <member name="T:PolyMigrate.Core.PolyMigrator">
             <summary>
             PolyMigrate 函式庫的進入點(<c>Cornhsu.PolyMigrate.Core</c>)。
-            polymigrate CLI 是這層之上的殼;要在自己的 .NET 程式裡驅動搬遷,用這個型別即可,
-            不必碰內部的 ExtractionPipeline / OutputVerifier 等實作型別。
+            polymigrate CLI 是這層之上的殼;要在自己的 .NET 程式裡驅動抽取、縮圖、巡檢、列出已鏡像的 slug、
+            探測與抓回孤兒頁,用這個型別即可(probe / fetch 入口與各方法的可取消 overload 自 3.0 起)。
+            <para>其餘 public 型別(ExtractionPipeline、OutputVerifier、ThumbnailGenerator、OrphanProber、
+            OrphanFetcher 等)是較底層的進階用途:它們同樣屬於公開面、受 semver 約束,只是沒有這一層的便利。</para>
             </summary>
             <example>
             <code>
@@ -952,8 +1316,10 @@
         <member name="M:PolyMigrate.Core.PolyMigrator.#ctor(PolyMigrate.Core.Configuration.SiteConfig)">
             <summary>
             PolyMigrate 函式庫的進入點(<c>Cornhsu.PolyMigrate.Core</c>)。
-            polymigrate CLI 是這層之上的殼;要在自己的 .NET 程式裡驅動搬遷,用這個型別即可,
-            不必碰內部的 ExtractionPipeline / OutputVerifier 等實作型別。
+            polymigrate CLI 是這層之上的殼;要在自己的 .NET 程式裡驅動抽取、縮圖、巡檢、列出已鏡像的 slug、
+            探測與抓回孤兒頁,用這個型別即可(probe / fetch 入口與各方法的可取消 overload 自 3.0 起)。
+            <para>其餘 public 型別(ExtractionPipeline、OutputVerifier、ThumbnailGenerator、OrphanProber、
+            OrphanFetcher 等)是較底層的進階用途:它們同樣屬於公開面、受 semver 約束,只是沒有這一層的便利。</para>
             </summary>
             <example>
             <code>
@@ -972,11 +1338,26 @@
             <param name="paths">raw / media / 輸出位置。</param>
             <param name="dryRun">true = 完整跑抽取與統計但不寫任何檔案。</param>
         </member>
+        <member name="M:PolyMigrate.Core.PolyMigrator.Extract(PolyMigrate.Core.Extraction.ExtractionPaths,System.Boolean,System.Threading.CancellationToken)">
+            <summary>
+            同上,可取消:逐頁、逐個媒體檔(算 sha1 前)、開始寫清單前各檢查一次,取消時擲
+            <see cref="T:System.OperationCanceledException"/>。已寫出的 <c>.md</c> 保留(只寫不刪);清單檔要嘛整組寫出、要嘛一份都不寫。
+            </summary>
+        </member>
         <member name="M:PolyMigrate.Core.PolyMigrator.Extract(System.String,System.Boolean)">
             <summary>Phase 2 抽取,採預設佈局:<c>root/raw</c>、<c>root/media</c>,輸出至 <c>root</c>。</summary>
         </member>
+        <member name="M:PolyMigrate.Core.PolyMigrator.Extract(System.String,System.Boolean,System.Threading.CancellationToken)">
+            <summary>同上,可取消(檢查點見 <see cref="M:PolyMigrate.Core.PolyMigrator.Extract(PolyMigrate.Core.Extraction.ExtractionPaths,System.Boolean,System.Threading.CancellationToken)"/>)。</summary>
+        </member>
         <member name="M:PolyMigrate.Core.PolyMigrator.GenerateThumbnails(System.String,System.String)">
-            <summary>縮圖:media 目錄 → 縮圖目錄(同結構、EXIF 轉正、寬度上限依 config)。</summary>
+            <summary>縮圖:media 目錄 → 縮圖目錄(同結構、EXIF 轉正、寬度上限依 config;動畫 GIF / WebP 逐格縮放)。</summary>
+        </member>
+        <member name="M:PolyMigrate.Core.PolyMigrator.GenerateThumbnails(System.String,System.String,System.Threading.CancellationToken)">
+            <summary>
+            同上,可取消:每張圖之前檢查一次,取消時擲 <see cref="T:System.OperationCanceledException"/>。
+            已建立的縮圖保留(每張都是原子寫入,不會留半截檔)。
+            </summary>
         </member>
         <member name="M:PolyMigrate.Core.PolyMigrator.Verify(System.String,System.String,System.String,System.Collections.Generic.IReadOnlyCollection{System.String})">
             <summary>
@@ -987,6 +1368,12 @@
             <param name="mediaPrefix">內文中媒體引用的根前綴。</param>
             <param name="allowUnlinked">豁免孤島偵測的頁(content 相對路徑或路由)。</param>
         </member>
+        <member name="M:PolyMigrate.Core.PolyMigrator.Verify(System.String,System.String,System.String,System.Collections.Generic.IReadOnlyCollection{System.String},System.Threading.CancellationToken)">
+            <summary>
+            同上,可取消:逐頁、寫報告前各檢查一次,取消時擲 <see cref="T:System.OperationCanceledException"/>,
+            不會寫出半份 <c>verify_report.csv</c>。參數意義與上面相同(這裡沒有預設值,避免與上一個多載互相模糊)。
+            </summary>
+        </member>
         <member name="M:PolyMigrate.Core.PolyMigrator.MirrorSlugs(System.String,System.String,System.String)">
             <summary>
             鏡像裡已有的 slug(<c>raw/{lang}/{section}/</c> 檔名),字典序、跨語言去重;
@@ -998,6 +1385,45 @@
             <param name="langPrefix">語言前綴;null = 涵蓋所有語言目錄。</param>
             <returns>找不到任何對應目錄時為 null(通常是 section 名打錯)——與「有目錄但沒有頁」不同。</returns>
         </member>
+        <member name="M:PolyMigrate.Core.PolyMigrator.ProbeOrphansAsync(System.String,System.String,System.Int32,System.Int32,System.String,System.Action{System.String},System.Threading.CancellationToken)">
+            <summary>
+            探測孤兒頁(CLI 的 <c>probe-orphans</c>;索引移除但頁面還在的舊文章):逐日期候選 slug(YYYYMMDD 與 MMDDYYYY),
+            命中再探 A～D 後綴。與 CLI 同一套規則:已鏡像的 slug 取自 <c>root/raw/{lang}/{section}/</c>、依
+            <c>url_pattern.strip_extensions</c> 判定(與 extract 一致;本身不探、後綴照探),禮貌延遲 <c>site.polite.delay_ms</c>,
+            送 <c>site.auth_workaround</c> 的 cookie,不跟轉址(轉址頁不算命中)。
+            <para><b>不寫任何檔案</b>:清單在 <see cref="P:PolyMigrate.Core.Orphans.ProbeReport.Found"/>,要不要寫成 <c>orphan_slugs.&lt;section&gt;.txt</c>
+            由呼叫端決定。<see cref="P:PolyMigrate.Core.Orphans.ProbeReport.NoUsableAnswers"/> 為 true 時不要把空清單當成「沒有孤兒頁」
+            (CLI 在這個情況 exit 2、不覆寫既有清單)。</para>
+            </summary>
+            <param name="root">站的工作根目錄(讀 <c>root/raw</c> 判斷哪些 slug 已鏡像)。</param>
+            <param name="section">section 目錄名(如 news)。</param>
+            <param name="yearFrom">起始年(含)。</param>
+            <param name="yearTo">結束年(含)。</param>
+            <param name="langPrefix">探哪個語言的網址;null = <c>url_pattern.lang_map</c> 的第一個 key(同 CLI 的 <c>--lang</c> 預設)。</param>
+            <param name="progress">進度訊息(命中、每 100 個候選一次)。</param>
+            <param name="ct">取消時擲 <see cref="T:System.OperationCanceledException"/>(等待中的延遲與進行中的請求都會被打斷)。</param>
+            <exception cref="T:System.ArgumentOutOfRangeException">年份不在 1～9999,或 <paramref name="yearFrom"/> 大於 <paramref name="yearTo"/>。</exception>
+        </member>
+        <member name="M:PolyMigrate.Core.PolyMigrator.ProbeOrphansAsync(System.Net.Http.HttpClient,System.String,System.String,System.Int32,System.Int32,System.String,System.Action{System.String},System.Threading.CancellationToken)">
+            <summary>同上,HttpClient 由呼叫端提供(測試注入用;public 版自己建、自己釋放)。</summary>
+        </member>
+        <member name="M:PolyMigrate.Core.PolyMigrator.FetchOrphansAsync(System.String,System.String,System.Collections.Generic.IReadOnlyList{System.String},System.Action{System.String},System.Threading.CancellationToken)">
+            <summary>
+            抓回孤兒頁(CLI 的 <c>fetch-orphans</c>):每個 slug 抓 <c>url_pattern.lang_map</c> 的每一種語言版,
+            頁面存進 <c>root/raw/</c>(原始 bytes)、正文引用的圖片與資產存進 <c>root/media/</c>(路徑鏡像、解碼檔名)。
+            已鏡像的頁跳過(只寫不刪);跟轉址(頁面可能在 301 之後),存檔名仍是要求的 slug。
+            單頁失敗(非 200、非 HTML、連線失敗、逾時)記進 <see cref="P:PolyMigrate.Core.Orphans.FetchReport.Errors"/>、不中止整批(CLI 在這個情況 exit 1)。
+            </summary>
+            <param name="root">站的工作根目錄(寫進 <c>root/raw</c> 與 <c>root/media</c>)。</param>
+            <param name="section">section 目錄名(如 news)。</param>
+            <param name="slugs">要抓的 slug(通常是 <see cref="M:PolyMigrate.Core.PolyMigrator.ProbeOrphansAsync(System.String,System.String,System.Int32,System.Int32,System.String,System.Action{System.String},System.Threading.CancellationToken)"/> 的 <see cref="P:PolyMigrate.Core.Orphans.ProbeReport.Found"/>)。</param>
+            <param name="progress">進度訊息(每抓到一頁一則)。</param>
+            <param name="ct">取消時擲 <see cref="T:System.OperationCanceledException"/>;已寫出的頁與資產保留(原子寫入,不會留半截檔)。</param>
+            <exception cref="T:PolyMigrate.Core.Configuration.ConfigException"><c>extract.content</c> 不是合法的 CSS selector(在寫入抓到的頁之前就擲)。</exception>
+        </member>
+        <member name="M:PolyMigrate.Core.PolyMigrator.FetchOrphansAsync(System.Net.Http.HttpClient,System.String,System.String,System.Collections.Generic.IReadOnlyList{System.String},System.Action{System.String},System.Threading.CancellationToken)">
+            <summary>同上,HttpClient 由呼叫端提供(測試注入用;public 版自己建、自己釋放)。</summary>
+        </member>
         <member name="T:PolyMigrate.Core.Redirects.IRedirectExporter">
             <summary>
             把 (舊路徑 → 新路徑) 301 對映輸出成某種可直接部署的設定檔格式。
@@ -1014,7 +1440,23 @@
             <summary>目前支援的 301 輸出格式。</summary>
         </member>
         <member name="T:PolyMigrate.Core.Redirects.NginxRedirectExporter">
-            <summary>nginx:<c>location = {old} { return 301 {new}; }</c>。</summary>
+             <summary>
+             nginx:<c>location = {old} { return 301 {new}; }</c>。
+            
+             <para><b>{old} 寫解碼後的路徑。</b>nginx 的 location 比對的是正規化後的 URI——先把 <c>%XX</c> 解碼、
+             解析 <c>.</c> 與 <c>..</c>、合併斜線(ngx_http_core_module 文件「location」段);設定檔裡的
+             location 字串則照字面。寫成 <c>/ch/news/%E7%A6%AA%E4%BF%AE.php</c> 的話,只有解碼後字面就是
+             <c>%E7…</c> 的請求才對得上——中日韓或含空白的舊網址永遠不會 301,直接 404。</para>
+            
+             <para><b>{new} 維持編碼</b>(來自 <c>Uri.AbsolutePath</c>):它是 Location 標頭的值,應為 ASCII。
+             <c>return</c> 的值會展開 <c>$變數</c>(加引號也一樣),所以 <c>$</c> 一律編碼成 <c>%24</c>。</para>
+            
+             <para>兩邊都只在必要時加雙引號(空白、<c>; { } " ' \ #</c>、控制字元),其餘維持原樣——
+             純 ASCII 的一般路徑與舊版逐位元組相同。排序依寫出來的(解碼後的)路徑。</para>
+             </summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Redirects.NginxRedirectExporter.Token(System.String)">
+            <summary>nginx 設定檔的一個參數:會被 nginx 斷開或誤讀的字元出現時才加雙引號並跳脫。</summary>
         </member>
         <member name="T:PolyMigrate.Core.Redirects.NetlifyRedirectExporter">
             <summary>Netlify <c>_redirects</c>:<c>{old} {new} 301</c>。</summary>
@@ -1032,12 +1474,26 @@
             missing_images.csv 已記錄的原站壞圖降為 warning(已知、非搬遷回歸)。
             </summary>
         </member>
+        <member name="P:PolyMigrate.Core.Verify.OutputVerifier.OnCheckpoint">
+            <summary>
+            測試用:每個取消檢查點之前呼叫一次,參數是檢查點標籤(<c>page:&lt;content 相對路徑&gt;</c>、<c>write</c>)。
+            讓測試能在「半途」取消——只用預先取消的 token,測不出逐頁的檢查到底有沒有作用。
+            </summary>
+        </member>
         <member name="M:PolyMigrate.Core.Verify.OutputVerifier.Run(System.String,System.String,System.String,System.Collections.Generic.IReadOnlyCollection{System.String})">
             <param name="allowUnlinked">
             豁免孤島偵測的頁(content 相對路徑或路由皆可)。刻意不從 config 讀:
             verify 的「只讀輸出、不需 config」是它的設計前提,不為了一份清單破例。
             </param>
         </member>
+        <member name="M:PolyMigrate.Core.Verify.OutputVerifier.Run(System.String,System.String,System.String,System.Collections.Generic.IReadOnlyCollection{System.String},System.Threading.CancellationToken)">
+            <summary>
+            同上,可取消(取消時擲 <see cref="T:System.OperationCanceledException"/>;CLI 接 Ctrl-C 後回 130)。
+            逐頁檢查、寫報告前再檢查一次:被中斷時不寫半份 verify_report.csv。3.0 起 public,以新增 overload 的方式加
+            (2.2.0 替上一個方法加選用參數就已經是一次二進位破壞,見盤點 §7.6)。
+            <para>方法開頭刻意不另外檢查:第一頁之前就是一個檢查點(<c>content/</c> 不存在時什麼都不做、立刻結束)。</para>
+            </summary>
+        </member>
         <member name="M:PolyMigrate.Core.Verify.OutputVerifier.BuildRoutes(System.String,System.Collections.Generic.List{System.String})">
             <summary>content 樹 → 路由集:{prefix}/{section}/{slug};index 檔代表其目錄路由。</summary>
         </member>
@@ -1090,8 +1546,21 @@
         <member name="M:PolyMigrate.Core.Verify.OutputVerifier.NormalizeRoute(System.String)">
             <summary>連結正規化:去 #fragment/?query、去尾斜線(根除外)。</summary>
         </member>
-        <member name="M:PolyMigrate.Core.Verify.OutputVerifier.ExtractInternalRefs(System.String)">
-            <summary>抽正文裡的站內引用:markdown 連結/圖片 與內嵌 HTML 的 href/src,只留 "/" 開頭者。</summary>
+        <member name="M:PolyMigrate.Core.Verify.OutputVerifier.MarkdownRefs(System.String)">
+            <summary>正文裡 Markdown 連結/圖片的站內引用(只留 "/" 開頭者)。</summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Verify.OutputVerifier.HtmlRefs(System.String)">
+            <summary>
+            內嵌 HTML 的站內引用(只留 "/" 開頭者),依出現順序;集合恰好是 9d17071 看得到的那一份。
+            <list type="bullet">
+            <item><b>LinkCheck = true</b>:真正的 <c>href</c> / <c>src</c> 屬性——檢查壞連結與缺圖,也算入口。</item>
+            <item><b>LinkCheck = false</b>:屬性名只是以 href / src 結尾(<c>data-src</c>、<c>data-href</c>、<c>xsrc</c>)——
+            算入口、媒體照樣檢查缺檔,只有站內頁不檢查壞連結(見 Run)。</item>
+            </list>
+            一律以 9d17071 那條沒有邊界的比對(<see cref="M:PolyMigrate.Core.Verify.OutputVerifier.AnyHrefOrSrcAttribute"/>)為準,只用有邊界的比對
+            (<see cref="M:PolyMigrate.Core.Verify.OutputVerifier.HtmlTarget"/>)判斷「這個起點是不是真正的屬性」。有邊界的比對若單獨跑,會在 <c>data-src</c>
+            的值中間找到 <c>src='…'</c>——9d17071 從來不會看到那裡,檢查集合就比 9d 大(最終驗證 I3:r4-d 由 0 變 2)。
+            </summary>
         </member>
         <member name="M:PolyMigrate.Core.Verify.OutputVerifier.MarkdownTarget">
             <remarks>
@@ -1107,6 +1576,43 @@
             </remarks>
         </member>
         <member name="M:PolyMigrate.Core.Verify.OutputVerifier.HtmlTarget">
+            <remarks>
+            Pattern:<br/>
+            <code>(?&lt;![\\w-])(?:href|src)\\s*=\\s*(?:"([^"]*)"|'([^']*)')</code><br/>
+            Options:<br/>
+            <code>RegexOptions.IgnoreCase</code><br/>
+            Explanation:<br/>
+            <code>
+            ○ Zero-width negative lookbehind.<br/>
+                ○ Match a character in the set [\-\w] right-to-left.<br/>
+            ○ Match with 2 alternative expressions.<br/>
+                ○ Match a sequence of expressions.<br/>
+                    ○ Match a character in the set [Hh].<br/>
+                    ○ Match a character in the set [Rr].<br/>
+                    ○ Match a character in the set [Ee].<br/>
+                    ○ Match a character in the set [Ff].<br/>
+                ○ Match a sequence of expressions.<br/>
+                    ○ Match a character in the set [Ss].<br/>
+                    ○ Match a character in the set [Rr].<br/>
+                    ○ Match a character in the set [Cc].<br/>
+            ○ Match a whitespace character atomically any number of times.<br/>
+            ○ Match '='.<br/>
+            ○ Match a whitespace character atomically any number of times.<br/>
+            ○ Match with 2 alternative expressions, atomically.<br/>
+                ○ Match a sequence of expressions.<br/>
+                    ○ Match '"'.<br/>
+                    ○ 1st capture group.<br/>
+                        ○ Match a character other than '"' atomically any number of times.<br/>
+                    ○ Match '"'.<br/>
+                ○ Match a sequence of expressions.<br/>
+                    ○ Match '\''.<br/>
+                    ○ 2nd capture group.<br/>
+                        ○ Match a character other than '\'' atomically any number of times.<br/>
+                    ○ Match '\''.<br/>
+            </code>
+            </remarks>
+        </member>
+        <member name="M:PolyMigrate.Core.Verify.OutputVerifier.AnyHrefOrSrcAttribute">
             <remarks>
             Pattern:<br/>
             <code>(?:href|src)\\s*=\\s*(?:"([^"]*)"|'([^']*)')</code><br/>
@@ -1493,6 +1999,38 @@
             <param name="inputSpan">The text being scanned by the regular expression.</param>
             <returns>true if the regular expression matches at the current position; otherwise, false.</returns>
         </member>
+        <member name="T:System.Text.RegularExpressions.Generated.AnyHrefOrSrcAttribute_11">
+            <summary>Custom <see cref="T:System.Text.RegularExpressions.Regex"/>-derived type for the AnyHrefOrSrcAttribute method.</summary>
+        </member>
+        <member name="F:System.Text.RegularExpressions.Generated.AnyHrefOrSrcAttribute_11.Instance">
+            <summary>Cached, thread-safe singleton instance.</summary>
+        </member>
+        <member name="M:System.Text.RegularExpressions.Generated.AnyHrefOrSrcAttribute_11.#ctor">
+            <summary>Initializes the instance.</summary>
+        </member>
+        <member name="T:System.Text.RegularExpressions.Generated.AnyHrefOrSrcAttribute_11.RunnerFactory">
+            <summary>Provides a factory for creating <see cref="T:System.Text.RegularExpressions.RegexRunner"/> instances to be used by methods on <see cref="T:System.Text.RegularExpressions.Regex"/>.</summary>
+        </member>
+        <member name="M:System.Text.RegularExpressions.Generated.AnyHrefOrSrcAttribute_11.RunnerFactory.CreateInstance">
+            <summary>Creates an instance of a <see cref="T:System.Text.RegularExpressions.RegexRunner"/> used by methods on <see cref="T:System.Text.RegularExpressions.Regex"/>.</summary>
+        </member>
+        <member name="T:System.Text.RegularExpressions.Generated.AnyHrefOrSrcAttribute_11.RunnerFactory.Runner">
+            <summary>Provides the runner that contains the custom logic implementing the specified regular expression.</summary>
+        </member>
+        <member name="M:System.Text.RegularExpressions.Generated.AnyHrefOrSrcAttribute_11.RunnerFactory.Runner.Scan(System.ReadOnlySpan{System.Char})">
+            <summary>Scan the <paramref name="inputSpan"/> starting from base.runtextstart for the next match.</summary>
+            <param name="inputSpan">The text being scanned by the regular expression.</param>
+        </member>
+        <member name="M:System.Text.RegularExpressions.Generated.AnyHrefOrSrcAttribute_11.RunnerFactory.Runner.TryFindNextPossibleStartingPosition(System.ReadOnlySpan{System.Char})">
+            <summary>Search <paramref name="inputSpan"/> starting from base.runtextpos for the next location a match could possibly start.</summary>
+            <param name="inputSpan">The text being scanned by the regular expression.</param>
+            <returns>true if a possible match was found; false if no more matches are possible.</returns>
+        </member>
+        <member name="M:System.Text.RegularExpressions.Generated.AnyHrefOrSrcAttribute_11.RunnerFactory.Runner.TryMatchAtCurrentPosition(System.ReadOnlySpan{System.Char})">
+            <summary>Determine whether <paramref name="inputSpan"/> at base.runtextpos is a match for the regular expression.</summary>
+            <param name="inputSpan">The text being scanned by the regular expression.</param>
+            <returns>true if the regular expression matches at the current position; otherwise, false.</returns>
+        </member>
         <member name="T:System.Text.RegularExpressions.Generated.Utilities">
             <summary>Helper methods used by generated <see cref="T:System.Text.RegularExpressions.Regex"/>-derived implementations.</summary>
         </member>
@@ -1514,6 +2052,9 @@
         <member name="M:System.Text.RegularExpressions.Generated.Utilities.StackPush(System.Int32[]@,System.Int32@,System.Int32,System.Int32,System.Int32)">
             <summary>Pushes 3 values onto the backtracking stack.</summary>
         </member>
+        <member name="F:System.Text.RegularExpressions.Generated.Utilities.s_ascii_1080000010800">
+            <summary>Supports searching for characters in or not in "HShs".</summary>
+        </member>
         <member name="F:System.Text.RegularExpressions.Generated.Utilities.s_ascii_FF000000008000000000">
             <summary>Supports searching for characters in or not in "01234567_".</summary>
         </member>