# 開發索引與 API 文件
## 功能文件
- [MetricKit 本機效能報告](METRICKIT.md)
- [ScreenCaptureKit 本地錄影：錄後壓縮](RECORDING_COMPRESSION.md)
## 開啟方式
雙擊 `Scripts/change_log.cmd`，點「功能／API／近期改動索引」。原有新增／修改變更紀錄功能保留。
也可執行 `python Scripts/change_log.py serve --no-browser`，依終端機列出的本機位址開啟 `/development`。搜尋包含功能狀態、Swift 宣告、文件內容。點宣告或文件可在瀏覽器閱讀帶行號的原始內容。
若要一起搜尋 HaishinKit，先設定環境變數 `REPLYKIT_HAISHINKIT_ROOT` 為底層 checkout 的絕對路徑，再啟動工具。不會自動下載、修改或更新套件。
## 程式結構
`Scripts/change_log.py` 與 `Scripts/dev_index.py` 只是相容入口（薄殼）；實作拆分在 `Scripts/changelog/` 套件：
| 模組 | 職責 |
| --- | --- |
| `changelog/storage.py` | ChangeHistory.md 解析、組版與讀寫 |
| `changelog/devindex.py` | 功能／API／文件／近期改動索引 |
| `changelog/server.py` | 本機 HTTP 伺服器與路由 |
| `changelog/cli.py` | 命令列（add／list／show／serve） |
| `changelog/assets.py` + `changelog/assets/` | 網頁資產載入與檔案 |
網頁樣式與行為全在 `Scripts/changelog/assets/`：`theme.css`（色票與共用元件，含深／淺色）、`index.*`（變更歷史）、`dev.*`（開發索引）、`file.*`（檔案檢視）、`highlight.js`（語法上色）、`markdown.js`（Markdown 渲染）。改版面或配色只需動這些資產，不必改 Python。各頁右上角可切換深／淺色（存在 localStorage，並跟隨系統偏好）。開發索引的 API 宣告註釋以 markdown 呈現，檔案檢視支援行號就地跳轉與高亮，不需重載。開發索引的「近期改動」分頁可展開每個提交或工作區變更、檢視其 unified diff（含語法上色）。開啟 `.md` 檔時**預設以排版檢視呈現**（標題、清單、表格、程式碼區塊與 `> [!TIP]` 之類提示框），可一鍵切回原始碼；文件內的相對連結會改寫為站內檔案檢視連結。
## 各資料的責任
| 資料 | 來源與限制 |
| --- | --- |
| 功能／接入 | features.json：固定 ID、用途、兩種來源、UI、驗證狀態及檔案連結；人工維護 |
| API 宣告 | 掃描 Swift 宣告及相鄰文件註釋，只作定位；不是編譯器解析，不能完整辨識條件編譯、跨行宣告或呼叫關係 |
| 近期改動 | Git 最近 20 筆提交與未提交／未追蹤檔案；可展開檢視該提交或工作區的 unified diff（含語法上色），不推測變更的功能語意 |
| 版本 | App HEAD、鎖定套件 revision、選填底層 HEAD；不是已安裝 App 的 BuildInfo |
| DocC | 由 Xcode 編譯器與文件註釋產生；獨立於本機文字索引 |
搜尋結果最多先顯示 250 筆；文件搜尋內容上限為每份 100000 字元，檔案閱讀上限 2 MB。僅提供 Git 可見且未忽略的 Swift／Markdown，排除隱藏路徑；不提供任意本機檔案下載。
## 更新規則
新增或改變功能時，在同一筆變更更新 features.json；ID 保持穩定。ChangeHistory 可引用功能 ID 與相關文件。TODO 繼續集中管理未完成事項，索引提供入口，不複製完整待辦。
接入和驗收要分開描述。缺乏證據填「待驗證」，底層存在但上游沒接就明確寫出；不能只用「完成」概括。宣告索引由程式重建，不手抄函數清單。
執行 `python Scripts/test_dev_index.py` 驗證資料、失效連結、路徑限制與 HTTP 接線。Development index workflow 在 push／PR 執行相同檢查。
提交前先跑 `python Scripts/check_markdown.py`（Windows）或 `python3 Scripts/check_markdown.py`（macOS／Linux）；它與 CI 共用 MD001 標題階層與 MD012 空行檢查。可選啟用 repo hook：
```bash
git config core.hooksPath .githooks
```
之後每次 commit 前會自動檢查，不必等 CI 才發現連續空白行。
## DocC 建置
macOS Xcode 使用 Product → Build Documentation。另提供 DocC documentation workflow（`.github/workflows/documentation.yml`：手動觸發，或 push 到 main 且動到 `.docc`／專案／Package.resolved／Docs 文件／README／TODO／`.changelog.toml`／DocC 或靜態站腳本，或 Swift 的 `///`／`public`／`open` 等文件相關變更時執行），使用專案既有 xcode-27 runner，產出 doccarchive、App revision、Package.resolved 與建置日誌，將 ChangeLogKit 分類文件匯出到 `site/project/`，並部署到 GitHub Pages。單純 Swift 實作變更會由輕量的 `changes` preflight 跳過，不啟動 macOS docbuild；需要強制重建時用手動觸發。
**目前 `xcodebuild docbuild` 只產出 HaishinKit（相依套件）的模組文件**——App 的 `liveAPP/Documentation.docc` 目錄尚未加入 Xcode 專案，`docbuild` 因此不為 App target 產生模組頁。要讓 App 自身有文件，需把該 `.docc` 目錄加入 `liveAPP` target。Windows 的宣告搜尋不需要 Xcode。
## 文件（DocC）
這裡的「API 宣告」是**文字掃描**（收錄 func／型別／存取修飾的屬性／init，含多行簽名與相鄰 `///` 註釋），目的是在本機快速定位，不是 Swift AST，也不含呼叫關係。
真正的 Apple DocC（`.doccarchive`）**無法在 Windows 產生**：
- `docc` 工具鏈官方只隨 macOS 與 Linux 的 Swift 發佈（Windows 需自行從原始碼編譯）。
- 更關鍵的是符號圖（symbol graph）需要 Swift 編譯器**型別檢查**原始碼，而本 App 依賴 `AVFoundation`／`UIKit`／`ScreenCaptureKit` 等 **Apple 專屬框架**，Windows 的 Swift 沒有這些 SDK；`.xcodeproj` 也只能在 macOS／Xcode 建置。
要在 Mac 或 CI（macOS runner）產生：
```bash
xcodebuild docbuild -scheme liveAPP -destination 'generic/platform=iOS' \
-derivedDataPath build
# 產物：build/Build/Products/Debug-iphoneos/liveAPP.doccarchive
```
`.doccarchive` 是用 `swift-docc-render` 做前端渲染的靜態站，直接開 `index.html` 即可。可在 CI 加一個 job 產出並發佈，再由開發索引連過去。純 Swift、不依賴 Apple 框架的 package（例如可跨平台的部分）才可能在 Windows 用 `swift package generate-documentation` 產出。
本專案已提供 `.github/workflows/documentation.yml`：在 `xcode-27` runner 建置 DocC、`docc process-archive transform-for-static-hosting` 轉成靜態站、打包 `documentation-<sha>.zip`（docarchive＋日誌＋revision；DocC 會產生含 `:` 的符號檔名，故以 zip 打包），並部署到 GitHub Pages。要啟用線上瀏覽，請到 repo **Settings → Pages → Source 選「GitHub Actions」**；之後網址為 `https://<owner>.github.io/ReplyKit/`，根目錄會自動轉址到實際模組目錄。
## 主頁維護入口
主頁第一批已按責任拆檔，請先看 [主頁模組說明](HOME_MODULES.md)，再定位排版、RTMP 表單或廣播操作。