前言¶

在 C/C++（含 Qt）項目的維護中，編寫和更新 Doxygen 註釋往往需要大量重複勞動。AI 編寫註釋時，常出現覆蓋原有內容、忽略簽名變化或遺漏參數說明的情況。DeepSeek Harness（DSH）插件生態強調“一切皆插件”，通過集成專用技能可以解決這類工程問題。

這是什麼¶

dsh-doxygen 是一個 DSH 插件（技能），由用戶 FantastyQAQ 維護。它提供了一套完整的 Doxygen 註釋工作流，覆蓋文件頭、函數、模塊組、尾隨註釋及短註釋等場景。它不僅能生成新註釋，還能在代碼變更時通過“簽名指紋”檢測並標記過時的註釋，是維護項目文檔的工具。

核心功能¶

該插件提供以下核心能力：

1. 函數定位與解析：支持通過行號或函數名定位目標函數，解析函數簽名（包括參數方向），並輸出 JSON 格式的簽名指紋。
2. 六種模板支持：提供文件頭、函數、模塊頭、模塊尾、尾隨註釋、短註釋共六種模板，對應編輯器片段前綴。
3. 增量填充策略：採用“填充而非重寫”的機制。當已有註釋存在時，僅補充缺失字段，保留原有措辭和行順序。
4. 簽名指紋校驗：爲每個函數塊附加 16 位十六進制簽名指紋。掃描時可對比代碼當前簽名與註釋中的指紋，標記出代碼變更但註釋未更新的情況。
5. 安全操作模式：默認僅打印 Diff 預覽，用戶確認後通過 --write 應用修改，避免誤操作覆蓋文件。
6. CJK 文本友好：腳本強制 UTF-8 輸出，確保中文註釋在 Windows 控制台正確顯示。

安裝與啓用¶

安裝前需確保環境滿足 Python 依賴。

1. 安裝依賴：需要 Python 3.10+，並安裝 C/C++ 解析器。

    pip install tree-sitter tree-sitter-cpp

（也可使用 `requirements.txt` 安裝）

2. 安裝插件：使用 DSH 官方命令安裝。

    dsh plugin add github:FantastyQAQ/dsh-doxygen

3. 驗證安裝：

    python scripts/parse_function.py --file demo.cpp --list

若能輸出函數列表，說明安裝成功。

典型用法¶

插件包含兩個核心腳本：parse_function.py（只讀解析）和 gen_doxygen.py（生成與寫入）。

1. 解析函數簽名
   先定位函數並獲取簽名指紋：

    python scripts/parse_function.py --file src/rtc.cpp --line 42 --body-lines 30

輸出包含函數名、參數、返回類型及 16 位指紋 `ac50cb812857de87`。

2. 生成或更新註釋
   將解析結果交給模型生成文檔 JSON，然後渲染並預覽：

    python scripts/gen_doxygen.py --file src/rtc.cpp --line 42 --kind fun --doc doc.json --diff

確認無誤後寫入：

    python scripts/gen_doxygen.py --file src/rtc.cpp --line 42 --kind fun --doc doc.json --write

3. 掃描倉庫
   對整個源碼目錄進行掃描，檢查註釋狀態：

    python scripts/gen_doxygen.py --scan src

掃描會返回包含 `missing`（缺失）、`stale`（簽名過期）、`partial`（部分缺失）、`ok`（正常）的列表。

4. 其他模板
   • 文件頭：python scripts/gen_doxygen.py --file src/rtc.cpp --kind source --brief "RTC 驅動" --diff
   • 模塊組：python scripts/gen_doxygen.py --file src/rtc.cpp --kind module --line 30 --group rtc_api --diff
   • 尾隨/短註釋：python scripts/gen_doxygen.py --file src/rtc.h --kind rear --line 18 --diff

適用場景與注意¶

• 適用人羣：C/C++ 項目開發者、Qt 開發者、需要自動化文檔維護的團隊。
• Windows 注意：在 Windows 環境下，請始終使用 python 命令（避免使用 python3，某些環境將其視爲別名陷阱）。
• 批量操作：掃描後不要一次性重寫數百個文件。請按狀態（如 stale 或 missing）分組，讓用戶手動選擇寫入。

短結尾¶

dsh-doxygen 通過簽名指紋機制解決了代碼與文檔不同步的痛點，提供了從解析、生成到校驗的完整閉環。對於追求文檔質量與維護效率的 C/C++ 項目，這是一個落地的解決方案。

• 目錄頁
• GitHub 倉庫