前言¶

在 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 仓库