qt-doc · Qt 智能文档 Skill

Tue, 13 Oct 2026 00:00:00 +0000

不要死记硬背 Qt 类名，告诉它你想干什么。

一个为 opencode 设计的 Qt 领域智能体 Skill：你只需要用中文描述需求（“查一下线程怎么用”），它会自动映射为 QThread，抓取官方文档，并返回小白能看懂的核心 API 总结。

这不是搜索引擎，这是一个懂 Qt 的领域智能体。

✨ 它能做什么

能力	说明	示例
意图感知	中文概念自动映射为 Qt 类名	“线程” → `QThread`，“画形状” → `QPainterPath`
继承链展开	自动递归抓取父类文档	查 `QTcpSocket` 返回整个 `QAbstractSocket→QIODevice→QObject` 族，2 个 API → 216 个
来源标注	每个 API 标注来自哪个类	`connectToHost`（来自 `QAbstractSocket`）
小白化总结	官方文档降维成通俗解释	构造函数 / 最常用函数 / 关键信号 / 示例 / 注意事项
三级数据源	在线 → 本地离线文档 → JSON 缓存	断网可用，二次查询秒回
会话隔离	显式开启专家模式，不误触发	未开启时零劫持 Web/Java 等非 Qt 问题

🚀 快速开始

环境要求

Python 3.10+
依赖：requests、beautifulsoup4
opencode（可选用任意支持 Skill 的 Agent 运行器）

安装

git clone <your-repo-url> qt-doc
cd qt-doc
pip install -r requirements.txt
# 安装 skill 到 opencode 全局（可选）
cp -r qt-doc ~/.config/opencode/skills/

使用

重启 opencode 后，在会话中：

qt-doc（Qt 智能文档）

Tue, 13 Oct 2026 00:00:00 +0000

仅当用户显式要求开启 Qt 专家模式时触发，如说"开启Qt专家模式"、“进入Qt专家模式”、 “Qt专家模式"等。

一旦触发，本会话进入 Qt 专家模式，直到会话结束：

之后该会话内的所有 Qt/C++ 问题都用本 skill 流程回答（映射类名→抓文档→小白化总结）。
会话保持生效：通过 /sessions 恢复该对话，专家模式依然生效。
新开对话默认不加载本 skill，需再次显式开启——实现会话级隔离。
在专家模式下，非 Qt 的通用编程问题（如 Java/Web）正常回答，不套用 Qt 文档流程。

流程

把用户描述映射为 Qt 类名（Q 开头）。
- 先查本 skill 目录下的 mapping.json 精确匹配。
- 未命中则凭 Qt 领域知识推断（如"画形状”→QPainterPath）。
- 无法确定时询问用户。
调用抓取脚本（可传多个类名，一次抓取）：
- 优先使用环境变量 QT_FETCH_CMD 指向脚本（如 python /path/to/qt_fetch.py）。
- 未设置时，用当前仓库内脚本：python <repo>/qt_fetch.py <类名1> <类名2>...。
- 示例：python ../qt_fetch.py QThread QTimer
读取 stdout JSON。若 errors 非空，说明该类未找到，提示用户检查拼写或模块。
基于 JSON 的 title/brief/apis 做小白化总结。

输出规范（中文，开头带 [qt-doc]）

这是什么：一句话说明该类用途。
构造函数：核心 1-2 个。
最常用函数：数量视类而定——核心常用类 5-8 个，简单类 3-4 个。
关键信号：1 个 + 触发时机（有信号时）。
示例代码：简短 5-8 行。
⚠️ 注意：继承或使用要点。

继承链

查询结果含 inheritance_chain（从派生到基类）与每个 API 的 inheritsFrom 来源。若某类 API 很少（如 QTcpSocket），说明它继承自父类，常用函数多在父类文档中—— 总结时应说明函数来自哪个父类（如 connectToHost 来自 QAbstractSocket）。

Qt-Doc on 鹿鸣青野的blog