openclaw-doc-finder（OpenClaw DOC 查找器）

openclaw-doc-finder

OpenClaw 官方文档检索技能。识别用户意图，路由到正确文档，给出精确 URL + 关键命令片段。

检索流程（Pipeline）

用户问题 → 意图识别 → 诊断决策树（可选）→ 文档路由 → 本地片段 → 缓存命中 → 远程拉取 → 回答 → 记录速查

严格顺序，不得跳步：

1. 意图识别：解析用户问题，判断属于哪个场景类别
2. 诊断决策树（可选）：如问题模糊（"任务卡住"、"没有反应"），先用 references/diagnostic-tree.md 引导用户细化
3. 文档路由：查 references/doc-index.md 定位目标文档列表
4. 本地片段优先：检查 references/ 已有片段
5. 缓存命中：检查 references/fetched/<doc-name>.md 是否已有缓存且未过期（7 天内）
6. 远程拉取：本地/缓存均无 → 按"远程拉取规则"拉取，成功后自动缓存
7. 版本检查：回答结尾检查 VERSION
8. 记录速查：将问题与结论追加到 references/doc-lookups.md

意图识别规则

见 references/doc-index.md 的「意图→文档路由表」。优先精确匹配场景关键词。

常见场景映射：

本地片段优先级

• references/doc-index.md — 始终可用，路由总表
• references/diagnostic-tree.md — 新增"症状→排查路径"决策树
• references/config-guide.md — gateway 配置高频片段
• references/troubleshoot.md — 常见报错速查
• references/doc-lookups.md — 已查阅问题速查（查阅前优先检查）
• references/fetched/<doc-name>.md — 新增已缓存的远程文档（7 天有效期）

远程拉取规则

拉取顺序（降级策略）

当本地和缓存均无目标内容时，按以下顺序尝试：

1. web_fetch
   ↓ 失败（Blocked / 网络错误）
2. firecrawl_scrape
   ↓ 失败（Blocked / 超时）
3. exec → curl（最终兜底）
   ↓ 失败
4. 提供手动查询链接

curl 降级命令模板

# 文档 URL 格式：https://docs.openclaw.ai/<path>
# 用 curl 拉取并提取正文（去除 HTML 标签）
curl -sL "<完整URL>" | python3 -c "
import sys, re
html = sys.stdin.read()
html = re.sub(r'<script[^>]*>.*?</script>', '', html, flags=re.DOTALL)
html = re.sub(r'<style[^>]*>.*?</style>', '', html, flags=re.DOTALL)
text = re.sub(r'<[^>]+>', ' ', html)
text = re.sub(r'&nbsp;', ' ', text)
text = re.sub(r'\s+', ' ', text).strip()
# 提取核心内容（从第一个段落开始）
idx = text.find('。') if '。' in text else text.find('. ')
if idx > 0: print(text[idx:idx+3000])
"

自动缓存规则

• 缓存目录：references/fetched/
• 命名规范：<doc-name>.<timestamp>.md>（如 queue.20260405.md）
• 有效期：7 天（自动清理过期缓存）
• 写入时机：远程拉取成功后立即写入

无法拉取时的兜底

如三种方式均失败，回答格式：

⚠️ 无法自动拉取文档（网络限制）。请手动查看： - 文档地址：https://docs.openclaw.ai/<path> - 文档站搜索：https://docs.openclaw.ai/search?q=<关键词>

版本管理

• 版本文件：VERSION（语义化版本，格式 v1.0.0）
• 每次更新 references/ 内容，必须同步更新 VERSION
• 大版本更新（文档 breaking changes）：主版本号 +1，并记录 CHANGELOG

版本同步策略（优化）

不要在每次回答前都运行 sync-version.py（开销太大）。

正确做法：

• 技能初始化时检查一次（后台静默执行）
• 用户手动触发：/openclaw_doc_finder_check
• OpenClaw 大版本升级后主动提醒

# 手动触发版本同步（干跑）
python3 scripts/sync-version.py --dry-run

# 执行同步
python3 scripts/sync-version.py

输出格式规范

回答必须包含：

1. 文档标题 + 完整 URL（https://docs.openclaw.ai/<path>）
2. 关键命令（从文档中提取的 CLI 命令，用 ```bash 包裹）
3. 配置片段（关键配置项示例）
4. 版本提示（如已拉取最新内容，提醒技能版本）

当无法拉取时：

⚠️ 无法自动拉取文档。请手动查看：
- https://docs.openclaw.ai/<path>

当问题模糊时（先用决策树引导）：

在给出具体文档之前，我需要先确认一下：
[引用 diagnostic-tree.md 中的关键问题]

禁止：

• 不带 URL 的泛泛回答
• 混用多个不相关的文档链接

速查记录规则

每次使用本技能查询文档后，必须将问题与结论追加到 references/doc-lookups.md：

• 已有相同问题记录 → 更新对应条目而非重复追加
• 新问题 → 在对应分类下按格式追加
• 记录内容：问题、官方结论、相关文档路径、查阅时间
• 这样下次遇到同类问题时可直接复用，无需重复查阅

CHANGELOG

v1.2.0

• 新增：远程拉取降级策略（web_fetch → firecrawl → curl）
• 新增：自动缓存机制（references/fetched/，7 天有效期）
• 新增：诊断决策树（references/diagnostic-tree.md）
• 优化：版本同步改为手动触发，不再每次回答前执行
• 新增：无法拉取时的兜底说明

v1.1.0

• 优化触发条件：增加主条件+排除场景结构
• 提升激活准确性，防止误触发其他专业技能场景