robot-notes /關於/整理計畫與進度

robot-notes 整理計畫(PLAN)

把機器人知識「從軟體到硬體」完整整理成一套可在 GitHub 上隨時閱讀的筆記。以送餐機器人(室內 AMR)為主軸,逐步擴展到調度軟體、主板模擬與 Physical AI。

每個主題一個 markdown,README.md 當索引入口。每完成一輪就更新 GitHub,並請「專家」與「學生」兩個角色的 agent 讀過新文件,確認清楚到能讓人快速理解。

目錄結構

robot-notes/
├── README.md                 # 索引入口(GitHub 首頁)
├── PLAN.md                   # 本檔:整理計畫與進度
├── CONTEXT.md                # 術語表(ubiquitous language)
├── img/                      # 概念圖與示意圖(SVG 為主)
└── docs/
    ├── 00-overview/       # 系統全貌
    │   └── system-architecture.md
    ├── 10-core/           # 共通核心 —— 換了形態也還在
    │   ├── README.md
    │   ├── 10-hardware/   # 硬體:電怎麼變成力矩、感測器怎麼把物理量變成數字
    │   │   ├── README.md
    │   │   ├── communication-buses.md
    │   │   ├── digital-circuits.md
    │   │   ├── encoders.md
    │   │   ├── lidar-landscape.md
    │   │   ├── motors-and-foc.md
    │   │   ├── power-and-safety.md
    │   │   └── sensors.md
    │   ├── 20-firmware/   # 韌體:意圖怎麼變成馬達實際在轉
    │   │   ├── README.md
    │   │   ├── board-simulation-renode.md
    │   │   ├── host-mcu-protocol.md
    │   │   ├── low-level-control.md
    │   │   └── stm32-rest-tls.md
    │   └── 30-navigation/ # 導航:我在哪、地圖長什麼樣、怎麼從 A 到 B
    │       ├── README.md
    │       ├── kinematics-and-coordinate-transforms.md
    │       ├── nav2-plugin-algorithms.md
    │       ├── localization.md
    │       ├── path-planning.md
    │       ├── path-smoothing-and-trajectory.md
    │       ├── slam-3d-lidar.md
    │       └── slam-mapping.md
    ├── 20-forms/          # 形態分支 —— 換了形態就得換
    │   ├── README.md
    │   ├── legged/        # 四足
    │   │   ├── README.md
    │   │   ├── gait-and-actuation.md
    │   │   └── legged-fundamentals.md
    │   ├── mobile-manipulator/ # 搬運車 + 機械手臂
    │   │   ├── README.md
    │   │   ├── arm-kinematics.md
    │   │   └── mobile-manipulation.md
    │   └── wheeled-amr/   # 輪式 AMR
    │       ├── README.md
    │       └── chassis-and-drivetrain.md
    ├── 40-fleet/          # 多機調度
    │   ├── README.md
    │   ├── indoor-amr-roadnet-selection.md
    │   ├── mqtt-tls-emqx.md
    │   ├── open-rmf.md
    │   ├── proprietary-vs-ros2-arbitrary-start.md
    │   ├── rmf-adapter-cookbook.md
    │   ├── rmf-maps-and-traffic.md
    │   ├── rmf-multi-container-deploy.md
    │   ├── roadnet-and-traffic-control.md
    │   ├── robot-wan-5g-satellite.md
    │   ├── ros2-dds-intro.md
    │   ├── slot-reservation-dispatch-strategies.md
    │   └── vda5050.md
    ├── 50-physical-ai/    # Physical AI:模擬與 sim-to-real
    │   ├── README.md
    │   ├── claude-physical-ai-workflow.md
    │   ├── gazebo-slam-warehouse.md
    │   ├── gpu-lidar-how-it-works.md
    │   ├── isaac-sim-isaac-lab-amr.md
    │   ├── physical-ai-overview.md
    │   ├── project-forklift-rmf-gazebo.md
    │   ├── sdf-3d-models.md
    │   ├── sensor-data-and-3d-reconstruction.md
    │   ├── sim-to-real.md
    │   ├── simulation-asset-sources.md
    │   └── simulation-gazebo-ros2.md
    ├── 55-vlm-llm/        # VLM 與 LLM
    │   ├── README.md
    │   ├── llm-vlm-for-robots.md
    │   └── local-llm-on-nvidia-gb10.md
    ├── 60-compliance/     # 法規與認證
    │   ├── README.md
    │   ├── battery-certification.md
    │   ├── pwc-semi-iso3691-certification.md
    │   └── semiconductor-amr-standards.md
    ├── 70-security/       # 資安
    │   ├── README.md
    │   ├── ota-firmware-signing.md
    │   ├── secure-boot.md
    │   └── sros2-dds-security.md
    ├── 90-foundations/    # 數學與力學基礎
    │   ├── feedback-control-pid-lqr.md
    │   ├── gaussian-from-first-principles.md
    │   └── robot-dynamics.md
    ├── _meta/             # 工作方法與教訓
    │   ├── github-actions-gz-sim-playbook.md
    │   └── lessons-learned.md
    ├── _refs/             # 參考論文導讀
    │   └── nav2-survey.md
    └── _legacy/           # 舊版單檔整理(已被取代,保留對照)
        ├── README.md
        ├── delivery-robot-architecture.md
        └── delivery-robot-fundamentals.md

兩層骨幹:10-core/ 是換了形態也還在的部分(硬體 / 韌體 / 導航),20-forms/ 是換了形態就得換的部分。判準是「把形態換掉,這篇還成不成立?」

數字前綴是為了讓 GitHub 的字母排序剛好等於閱讀順序(沒有前綴的話 core/ 會排到 90-foundations 後面)。每個 doc 開頭一段「一句話定位 + 延伸閱讀連結」;每一區都有 README.md 當入口。

分輪計畫與進度

輪次可調整;新需求隨時插入。已寫好的檔不重做,只增修。

每輪收尾固定流程

1. 更新受影響的 README.md 索引與本檔進度表。
2. git add → commit(繁中 message)→ push 到 origin/main。
3. 啟動兩個 review agent 讀新增/修改的文件:
   • 專家角色:檢查技術正確性、有無過度簡化或錯誤、領域用詞是否精準。
   • 學生角色(硬體不熟的讀者):檢查是否讀得懂、哪裡卡住、需要補什麼前置知識或圖。
4. 把兩方意見整理成下一輪的修訂清單。

審查待辦 backlog(R1 專家/學生審查產出)

來自 R1 收尾的兩個 review agent,尚未處理的高優先項,排進後續輪次:

• 上下位機通訊協議專篇(20-firmware/host-mcu-protocol.md) ✅ 完成:三痛點→framing/CRC16/心跳逾時/序號,第一性原理 + 4 張 SVG(幀格式/接收狀態機/逾時看門狗/編碼範例)。
• Nav2 規劃/控制層(30-navigation/path-planning.md,R4):costmap、global planner、controller(MPPI/DWB)、behavior tree/recovery。對應 CLAUDE.md「路徑計算/軌跡計算」。
• 座標系與 TF 專篇(30-navigation/coordinate-frames-tf.md,R4):map→odom→base_link→sensor、各 frame 語意、外參標定。對應「座標轉換公式」。
• Physical AI 收緊 Cosmos=WFM 措辭、區分 Jetson Thor(robot)/ DRIVE AGX(automotive) ✅(R9 總體檢);Isaac ROS 一列可選補。
• 電池續航/功耗預算一節(中優先)。
• 較深的跨檔 §N 引用,長期改為帶連結的引用(目前先用 section-map.md 兜底)。

• 第一性原理回顧(全專案):既有硬體/韌體/導航文件逐篇補「為什麼是這個設計/公式」的第一性原理視角(高斯那篇是範本)。專家審查結論:硬體層(FOC/數位電路/電源)已近範本水準;缺口集中在「會動到數學公式」的地方——先給公式再解釋符號,而非把式子逼出來。

  第一性原理補強 Top 8 — ✅ 全數完成(R7),各配 SVG:

  1. ICC 推導差速運動學 + ICC 幾何 SVG — chassis-and-drivetrain.md §1.1(目前標「必背」=反第一性原理訊號)
  2. odometry 積分推導(車體位移經 θ 旋轉到世界系、中點朝向 Δθ/2 少一階誤差)+ 一步積分 SVG — low-level-control.md §4.1
  3. FOC「τ ∝ sin(夾角)」一條式子 + 夾角/扭矩曲線 SVG — motors-and-foc.md §2.2

  4. **AMCL 權重=似然 P(z

     x)、z_hit/z_rand/z_short=量測模型分解、為何用粒子不用高斯(多峰)** + 多峰 SVG — localization.md §22

  5. IMU bias 二次積分發散(t² 爆炸 → 距離信 encoder、角度信 IMU)+ 發散 SVG — sensors.md §3.3
  6. scan matching=最小化點到牆殘差平方和、pose graph=加權最小二乘 + 代價函數 SVG — slam-mapping.md §21.2/§21.3
  7. PID 的 I 項第一性原理(純 P 對常值負載必留穩態誤差 → 需 I 保住輸出;windup 由此推) — low-level-control.md §7.3
  8. wired-AND 跨章節 SVG 錨點(供 CAN 仲裁、I²C、共享中斷線共同回指) — digital-circuits.md §13.4 → communication-buses.md §6.2

  SVG 補強優先給 ASCII 畫不好的數學概念(ICC 幾何、sinθ 曲線、bias 發散、多峰分布、scan 殘差),結構剖面圖維持 ASCII。

教訓:改寫既有內容時,不要「順手補完」自己沒查證的細節

R15.2 那個假宣稱值得記住。原本的圖說是誠實的「Keenon 官網首頁」,我在做「裸 ![]() → 置中寫法」這個純格式的改動時,覺得 alt 文字寫得太籠統,就順手改成「Keenon DINERBOT T10 官網頁面」——內容我沒開圖看過。格式改動裡夾帶未查證的內容改動,而且因為 commit 訊息寫的是「改排版」,審查時也不會有人特別去看它。

規則:格式改動就只改格式。 覺得原本的描述不夠好,那是另一件事,要另外查證再改。

量測方法備忘(下次要再掃時直接用)

SVG 的「內容到底畫到哪」不能用抓 y=/x= 屬性的座標估法——量不到 <path> 與文字實際渲染出來的墨水範圍,估出來的數字是錯的。正確作法是用 chrome 跑 getBoundingClientRect() 再換算回 viewBox 座標(腳本邏輯見 R15.1 的 commit 訊息)。

getBBox() 也不行:它回傳套用 transform 之前的框,有 rotate 的標籤會被誤報成溢出(pai-isaac-stack、meta-ci-verification-ladder 都被這樣誤標過)。

這一輪查證抓到的兩件事

• 安全標準之間有一道空隙,而且移動操作正好掉進去。 ISO 10218:2025(第 3 版)的定義擴大到「fixed to a mobile platform」的手臂,但明確不處理移動性本身的危害;ISO 3691-4:2023 歷來不處理車上加裝手臂。中間那塊「因為組合才產生的危害」在 ISO 這條線上懸空,已有 ISO/NP 26058-1 在補。美規 ANSI/RIA R15.08-1 走得比較前面——Part 1 直接定義 IMR Type C = AMR/AGV + 機械手臂 attachment。
• MoveIt 2 官方沒有標準的移動底盤支援,官方 Future Projects 頁自己寫著只有「a non-standard way… requires modifying your robot model」。這反過來佐證了「分階段(停穩再動手臂)」不只是保守——那條路在工具層面本來就沒鋪好。

ISO/TS 15066 是否已正式撤銷:公開來源說法不一致,只能確定技術內容已進 ISO 10218:2025 正式條文。文件裡已標明不要對客戶說「TS 15066 已廢止」。

R17 查證抓到的四件事

1. 足式的安全標準是空白,而且是被明確排除的。 ISO 3691-4 明訂不適用於具主動控制穩定性的機器人;ISO 10218 不管移動;ISO 13482 限非工業場域。制定中的 ISO/CD 25785-1(動態穩定工業移動機器人)範疇寫著「需主動控制才能維持平衡、斷電即可能失穩」,正是為此而開,但仍在草案(時程只查到「2026–2027」區間)。
2. teacher-student 特權學習只能歸給 Lee 2020 → Miki 2022 這一支。 Hwangbo 2019 的核心是致動器網路、Rudin 2021 是訓練基礎設施,查不到它們也用同一框架的依據——不要把四篇說成同一套路線。
3. 「zero-moment point」這個詞是 1970–72 才創的,Vukobratović & Juričić 1969 那篇原始論文並沒有用這個名字。
4. Kenneally 那篇直驅足式論文是賓州大學的 Minitaur,不是 MIT Cheetah 系列——我在派工 prompt 裡把它歸錯了,研究 agent 抓出來並更正。

另記:「機身高度會漂」這個現象沒有公認的專有名詞,文獻都是描述性寫法。研究 agent 明確提醒不要杜撰一個聽起來像術語的稱呼——已照辦。

R17 這條線上抓到的三件事(每一件都是下一輪才浮出來的)

1. 把充分條件當成充要。 d ≥ 0.5 ⟹ 無騰空相 成立(對稱步態每一對是 n=2 系統),反過來不成立(amble)。原文寫成雙向。判斷法:寫下「⟺」「必然」「才可能」之前,把箭頭兩個方向分開各證一次——正向證得出來會給人「整條都懂了」的錯覺。
2. 解釋機制比寫對公式更容易錯,也更難被抓到。 capture point 的公式沒寫錯,但配上的物理解釋(動能換位能)跟模型假設(定高)直接矛盾,也跟自己引的兩份來源矛盾。「能量守恆」這類解釋最危險,因為讀起來太順。
3. 修正本身也要被審,而且錯誤的診斷比沒有診斷更糟。 R17.1 把第 1 條的病因診斷成「把統計說法升級成幾何必然」,那是錯的,而它已經被寫進 lessons-learned.md 當成規則。派覆審的專家去讀「修正後的版本」而不是只讀原版,是這一次抓到的關鍵。

三件事全是審查抓的,沒有一件是自己複查抓的。順序也有訊息:學生問「憑什麼」先到(「照 walk 那張圖的排法算,門檻是 0.25」),專家答「對照哪一篇」在後,而第三件要等到下一輪覆審才浮出來。角色分開派 + 修正後再審一次,兩件都有效。

另記一個自己的推導失誤:roll 的旋轉方向我親手推過一次還推錯——逆時針是把 9 點鐘帶到 6 點鐘(壓下去),不是抬起來。推導過不等於推對了,幾何方向這種一步就能翻的東西要用代數驗,不要靠腦內轉圖。

R20 這一輪抓到的四件事

1. 推出了一個文獻沒有的結論,而它必須標明是自己推的。 三輪平衡重式叉車是後輪轉向、前軸驅動,順著無側滑約束算下去,後軸中心對轉向輸入的傳遞函數是 v(Ls−v)/(Ls²)——零點在 s = v/L,前進時落在右半平面,所以車尾會先往錯的方向走,而且閉迴路頻寬被硬性限制在 v/L 的量級。倒車時 v < 0,零點移到左半平面,限制消失。這同時給了「叉車載重常倒著開」一個控制論上的解釋——但文獻與原廠訓練資料講的理由是視野與載重分配,查不到有人把最小相位當成理由。正文已標明這是本篇的推導、不是既有論述。
2. 圖的分類標籤要對得上實體,不是對得上數學模型。 第一版的舵輪 ICR 圖把「轉向輪在前」那半標成前移式 / 電動拖板車——但 reach truck 的舵輪在遠離貨叉那端,貨叉朝前行駛時它是後輪轉向,落在圖的另一半。數學模型沒錯(tricycle 就是 tricycle),錯的是把它掛到哪台車上。改成以「行進方向」為準的標題後才自洽,而且正好把倒車那一節的伏筆埋進圖裡。渲染核對抓到的,量測抓不到這種。
3. 研究 agent 對叉車構型的描述自相矛盾,而既有文件是對的。 agent 回報「三輪平衡重式:後方單一舵輪(驅動+轉向同一輪),前方兩個驅動輪不轉向」——後輪既驅動又轉向、前輪也驅動,自己打自己。project-forklift-rmf-gazebo.md §3.1 早就查證過(標明來源 Toyota/Raymond/Hyster):前兩輪驅動、後單輪主動轉向。採信既有文件,並在本篇連回去,沒有重新裁定。
4. 邊界量測與重疊檢查抓的是不同的病,兩個都要做。 getBoundingClientRect 換算回 viewBox 抓到一處真溢出(標籤超出右緣 8 px)與六處邊界過緊 / 留白過寬,但完全抓不到標籤壓在曲線上——那三處是渲染成 PNG 後看出來的(I 與 P 兩個標籤疊字、D 的切線與曲線重合到分不出來、P+I 的說明壓在藍色曲線上)。

待查證(正文 §15 已列):各機型舵輪的轉向角範圍、ISO 2328 / 2331 各級叉齒尺寸(所以正文只寫「扣掉厚度後剩幾十毫米」不給精確餘裕)、ISO 3691-4 的具體速度與停止距離(標準原文付費未購買)、Balyo / Seegrid / Fox Robotics 的官方定位精度、叉車領域明確以 gain scheduling 命名的公開文獻(查不到,正文標明是把通用理論套上去的推導)、Apollo lat_controller.cc 現行原始碼(取用路徑回 404,狀態向量定義來自二手來源)。

R20.1 抓到的三件事

1. 審查 agent 的診斷要自己驗算,它可能只對一半。 專家對引用的指控成立,但它附帶的推論「Safonov & Athans 1977 已被 Doyle 1978 反駁」是錯的——1977 講的是狀態回授 regulator 的多迴路裕度,1978 講的是含 Kalman 濾波器的 LQG,兩者對象不同、並不衝突。照抄那個推論會在文件裡種下一個新的假斷言。最後只採納「引用錯位」這一半,把 Safonov 保留為多變量推廣並註明它處理的是狀態回授。
2. 它確認對的那一行旁邊,才是真正錯的那一行。 專家指出 §13.1 的 Ad = I + A*T 對這個 A(A² = 0)是精確值不是近似——正確,而且是個好教學點。但同一段裡 Bd = B*T 才是錯的:精確的零階保持是 Bd = (T·I + T²A/2)·B,漏掉 T²/2·AB 讓 K 的第二個元素偏掉 2.2%(10.395 → 10.168)。專家沒抓到。是自己按著它的提示往下驗算才發現的——驗證一個斷言時,順手把它的鄰居也算一遍。
3. 選視角本身就是物理判斷。 穩定三角形圖的第一版畫成側視圖,渲染出來才發現 d(重心到傾覆軸的水平距離)幾乎變成 0——因為側視圖表達的是前後傾覆,而 §11.1 講的轉彎傾覆是側向的,要用後視圖才畫得出來。公式沒寫錯,錯的是用一個看不到該現象的視角去畫它。這和 R20 那條「圖的分類標籤要對得上實體」是同一類病的兩種形狀。

另記一個學生的判準值得留著:它讀完之後被要求用自己的話回答三個問題,「為什麼是二次型」答得完整、「K 從哪來」答得出來源但答不出每一步、「倒車為什麼好控制」只能複述而無法解釋機制。答不出來的那兩題,精確對應到文中真正缺的兩塊(矩陣微積分、頻域直覺)。比起請它列出「哪裡看不懂」,請它複述更能定位裂縫。

R21 查證抓到的四件事

1. 先 grep 自己的庫,答案就在裡面。 要回答「Nav2 為什麼不做 LQR」時,第一步不是上網搜,而是 grep docs/_refs/ ——那裡躺著 Nav2 維護者親寫的 survey 全文 PDF。pdftotext 抽出來一 grep:全文零次提及 LQR。這個負面證據兩秒就拿到,而且比任何二手討論權威。它的 Table II(各 controller 的 Max. Frequency:MPPI 125 Hz、Graceful 1800 Hz、RPP >4000 Hz)與五類分法(reactive / predictive / geometric / machine-learning / control-law)也直接給出了「LQR 會落在哪一格、那格已經被誰佔住」的答案。
2. agent 的引文要回原文核對,因為格式標記會在轉述中丟失。 研究 agent 正確找到了 navigation2#1710 裡 Macenski 對 LQR 的定性,但回報的純文字裡看不出那一行帶刪除線(~LQR/iLQR/CiLQR …~ MPPI supersedes)。刪除線正是「評估過、決定不做」與「還沒排到」的分野——用 gh api 讀原始 markdown 才看得到。
3. 文件與原始碼不一致時,以原始碼為準,而且要主動去核對。 agent 自己誠實標了「參數預設值只是文件層級,建議另做原始碼級核對」。照做之後:預設值全部吻合(batch_size 1000、time_steps 56、model_dt 0.05、temperature 0.3、gamma 0.015),但Savitzky-Golay 濾波器在文件裡不明顯、原始碼確實有呼叫(optimizer.cpp 的 savitskyGolayFilter)。這種只有讀碼才看得到的東西,正是筆記該寫進去的。
4. 拿不到原文時,能自己推的就自己推,不要引用沒核對過的式號。 論文 PDF 抓不到(判定為掃描影像),agent 給的自由能式子是經 HTML 轉譯後的摘要,而且不同文獻的定義差一個 −λ 因子。處置是自己重推一次 Gibbs 變分原理——只用 KL 散度非負這一個性質,四行就推完,結論自洽且與文獻一致。正文標明這是本篇自推、未逐式核對原文,並註記那個因子差異不影響 q* 的形式。

R21.1 抓到的三件事

1. 文字定義不能拿來對消算式。 KL 散度在 §13.2 之前只有一句文字描述(「衡量兩個分布差多少,恆非負」),然後推導裡直接把 E_q[log(q/q*)] 記成 D_KL(q‖q*)。對已經知道定義的人這是同義反覆,對不知道的人這是憑空跳步——學生的原話是「一個從沒被寫成算式的東西,被拿去對消一個算式」。規則:凡是會在推導中被當成算式操作的符號,就必須先以算式的形式出現過。
2. 描述動作的措辭要對得上實際做的動作。 「分母上下同乘 Z」在數學上是錯的描述——實際做的是用 Zq* = e^{−S/λ}p 這個已知等式做代換。學生說這句話「誤導我去找一個乘法步驟」。這種錯專家抓不到(知道答案的人會自動腦補成正確操作),只有真的在跟著推的讀者會卡住。
3. 專家與學生抓到的是不相交的兩組問題。 這一輪特別明顯:專家的四條全在「斷言精不精確」(QP vs NLP、因果簡化、缺前提、最優性的範圍),學生的四條全在「跟不跟得上」(缺中間步驟、缺公式定義、符號衝突、圖少一個箭頭)。兩組沒有任何重疊。 只派一邊,另一邊的問題會完整地留在文件裡。

R22 抓到的四件事

1. 文件與原始碼的落差要主動找,而且它藏在最不起眼的地方。 AMCL 有兩種雷射模型,beam 是教科書的四項混合(z_hit/z_short/z_max/z_rand),但 Nav2 常用的 likelihood_field 只有 z_hit 與 z_rand 兩項——z_short 與 z_max 在那個模型裡根本不存在。照著教科書調 z_short 卻用著 likelihood field,那個參數不會被讀到。這只有讀 likelihood_field_model.cpp 才看得見,官方文件沒有點出來。同一個檔案裡還有一行自承:逐光束的組合是 p += pz³ 這種經驗式(註解寫「works well though」),不是嚴謹的機率連乘。
2. 「文件沒給的公式」有兩種,處理方式不同。 一種是原始碼裡有(Hybrid-A* 的 max 組合與 travel_cost 分段、Simple Smoother 的更新式、Graceful 的控制律、RPP 的四層調節)→ 讀碼補上並標明以原始碼為準;另一種是連原始碼都沒有現成式子的(Savitzky-Golay 的係數表)→ 自己算:window=7, poly=3 的係數是 (−2,3,6,7,6,3,−2)/21,並驗證了係數和為 1、三次以下完全保留、四次以上才平滑。第三種是兩邊都查不到的(Smac 2D 的啟發式、State Lattice 的代價組合、Constrained Smoother 的逐項解析式)→ 標待查證,不臆造。
3. 既有的筆記就是新篇的骨架,前提是先去找。 Simple Smoother 的原始碼更新式一看就眼熟,於是把它跟 path-smoothing-and-trajectory.md §6 的離散平滑器目標函數接了起來。⚠ 這個連結的數學推導在 R22.2 被專家推翻——它不是曲率能量的梯度下降,是一階長度能量的。正確版本見 R22.2 第 1 條。
4. 全庫掃描比單篇驗證划算。 為了驗自己新寫的錨點做了一個掃描器,順手掃全庫,抓到 3 個既有斷鏈——而且它們和我當下踩的坑是同一條規則的兩個方向:GitHub 的錨點會移除標點、但把空格轉成連字號。所以標點兩側有沒有空格,決定了兩個詞是黏在一起(MPC:MPPI → mpcmppi,我踩的)還是留下連字號() — 用 → -用,那三個斷鏈踩的)。全庫 764 個內部連結現在全通。

R22.2 抓到的兩件事

1. 用自己的錯誤假設寫的驗算,驗不出那個假設是錯的。 R22 宣稱「Simple Smoother 的更新式正是曲率能量 Σ‖y_{i−1}−2y_i+y_{i+1}‖² 的梯度下降」,而且當時跑了驗算腳本自我確認。錯在哪:y_i 出現在三個相鄰的二階差分項裡(k = i−1, i, i+1),完整偏導是五點的重調和算子 (1,−4,6,−4,1),四階;我當時只取了「含 y_i 的主項」,而那個腳本裡寫的正是這個錯誤簡化,所以它當然「吻合」。真相是:三點更新式是一階長度能量 Σ‖y_{i+1}−y_i‖² 的精確梯度下降(對它取偏導得 2y_i − y_{i−1} − y_{i+1},取負號正好是原始碼那一行),而原始碼註解自己就寫著「Smooth based on local 3 point neighborhood」。 規則:當一個變數出現在多個項裡、而你只取其中一項時,那不是「取主項」的簡化,是換了一個不同階的算子。 「只取主項」這句話在推導裡出現,本身就該是警訊——寫下它的時候要停下來問「丟掉的那些項是同階的嗎」。
2. 兩個 agent 給不同答案時,可能兩個都只對一半。 查證 agent 抄 RPP 原始碼給 ln(253),專家核對膨脹層給 252,而專家據此判定「文中誤植」。自己回頭讀兩邊原始碼才看到真相:RPP 確實寫 log(253.0f),而膨脹層的正向乘數確實是 (INSCRIBED_INFLATED_OBSTACLE − 1) = 252——是 Nav2 自己這兩處不一致。 誤差量 ln(253/252)/f,f=3 時 1.3 mm,實務可忽略。但它比「改個常數」更值得寫:這個「從 costmap 值反推距離」的技巧把一個模組的實作常數硬寫進另一個模組,任何一邊改了公式形狀,另一邊都不會有編譯錯誤、不會有警告,只會安靜地算出偏掉的距離。採信任一個 agent 的單邊結論,都會寫出不完整的東西。

R22.3 的教訓:統計乾淨不等於畫面正確

這一輪的檢查順序值得記下來,因為前三步全部通過、問題出在第四步:

1. 本地 $$ 成對 ✓
2. 線上 mjx-container 數量與原始檔公式數相符(58/58、23/23)✓
3. <mjx-merror> 為 0、正文無殘留標記 ✓
4. 截圖看 → 下標與分母被裁掉 ✗

前三項都是可程式化的統計,而它們對「內容被 CSS 切掉」這件事完全無感——MathJax 成功渲染了元素,DOM 裡什麼都在,只是被 overflow 藏起來。能用數據驗的就用數據驗這條原則的邊界正在這裡:數據能證明「東西在」,不能證明「看得到」。

與 R19 那個 img{height:auto} 蓋掉 HTML height 屬性的坑同源:版面 CSS 的副作用不會報錯,只會安靜地改變畫面,而且兩次都是全站範圍。

可重用的量測方法:別靠截圖判斷「有沒有被裁」

截圖能發現問題,但判斷「修好了沒」用截圖既貴又不精確(要裁對位置、要用 vision token)。正確的做法是把問題本身量成數字:對每個公式容器比較 scrollHeight 與 clientHeight,差值 > 0 就是有內容被 overflow 藏起來。

做法是把線上 HTML 抓下來、在 </body> 前注入一段量測 script(等 MathJax 跑完再測),用 --dump-dom 取回結果:

c.scrollHeight - c.clientHeight > 1   →   這條公式有內容被裁,超出 N px

這個量測抓到了截圖看不出來的殘留:第一次把 padding 修成 .45em 之後,58 條裡已經全乾淨,但另一篇還有 1 條超出 3 px——AMCL 的運動模型是三行 aligned 環境,比單行公式高,餘裕不夠。提到 .7em 才收乾淨。3 px 用肉眼看截圖是看不出來的。

最終複驗四篇有公式的文件:feedback-control-pid-lqr 58 條、nav2-plugin-algorithms 23 條、robot-dynamics 22 條、gaussian-from-first-principles 5 條,合計 108 條公式,0 被裁、0 渲染錯誤。

往後改 _layouts/ 的 CSS,順序是:先跑這個量測,再截一張圖做最終確認。

R23 的教訓:掃 markdown 會同時給你假警報和漏報

這一輪先用 python 掃 markdown 原始檔找壞連結,掃出 30 筆。逐項核對之後:

假警報與漏報都來自同一件事:掃的是輸入,不是產出。連結對不對取決於 Jekyll 實際產生了哪些檔案、kramdown 實際寫了哪些 id,這兩件事都只在 _site/ 裡才有答案。

所以流程固定成:Docker 裡 jekyll build(約 3 秒)→ 掃 _site 的 href/src 與 id → 比對。順帶還能算出孤兒頁(沒有任何頁面連進去的檔案),那是掃原始檔算不出來的。

外部連結另外掃:抓 URL 時要分開處理 markdown 行內連結、<...> 自動連結與裸 URL,並剝掉尾隨的全形標點——不然 <https://renode.io/> 會被抓成 https://renode.io/> 而回報 404,一份乾淨的站看起來會像有上百條死連結。

外部連結:掃完之後還壞著的

510 條去重後的外部連結全掃過一遍。扣掉擷取假象(程式碼裡的 RMF_WEB_HOST 佔位、 被吃掉結尾括號的維基連結)與擋機器人的回應(GitHub 429 限流、iso.org / sciencedirect / elifesciences 的 403/406、st.com 要瀏覽器標頭才給 200),修掉的是這些:

沒有修、確認是死的(找不到等價來源,替換等於換掉論據,不是修連結):

• github.com/open-rmf/rmf/discussions/466 — 該 repo 的 Discussions 整個關掉了
• app.gazebosim.org/fuel — 這條本來就是刻意留著的,simulation-asset-sources.md §「Fuel 深層路徑」正是在記錄它回 404
• optics.org/op/news/16/4/25、roboticscenter.ai/learn/...、nvidia.com/en-us/geforce/news/geforce-rtx-real-time-ray-tracing/、 mosesnah-shared.github.io/robotics_null_space_projection.html、blog.saphira.ai/... — 文章下架,站台本身還在
• webstore.iec.ch/publication/22850(IEC 61800-5-2)、/63273(IEC 60204-1)— IEC 改過編號, 同檔另一條 /27412(IEC 62368-1)仍有效
• agvnetwork.com/r15-08-safety-amr — 連線逾時;robotattractor.com — TLS 憑證過期

外部連結的維護成本跟站內連結不同:站內壞掉是自己的錯、修法唯一; 站外壞掉多半是對方改版或下架,能不能修取決於有沒有等價來源,沒有就該老實留著標記, 而不是隨手換一個看起來相關的頁面頂上——那會讓論據和來源對不上。

後續形態輪次(待做)

判斷結論

• section-map.md 不需要配圖:它是純查表用的對照索引(§N → 檔案),不是概念。圖只會把一張可以 Ctrl-F 的表變難查。真正該做的是把跨檔 §N 改成帶連結的引用,讓這張表逐步不必被查。

內容原則

• 第一性原理優先(貫穿全專案):每篇都要從「這東西要解決什麼根本問題」「為什麼是這個設計/公式」推導,不只堆事實。既有文件後續輪次回頭補「為什麼」視角(見下方 backlog)。
• 繁體中文、中性技術風格;程式碼/識別符保留原文。
• 每個專有名詞首次出現當場一句話翻譯(對照 CONTEXT.md)。
• 圖解優先:ASCII 圖先行,概念圖在 R6 由 designer 補。
• 硬體不熟的讀者是主要受眾之一 → 從「它解決什麼問題」講起,再進細節。
• 正確性 > 可讀性 > 美觀;不確定的標「待查證」,不臆造。