wiki-query

Query — 询问 Wiki

遵循 wiki/CONVENTIONS.md 中的格式约定、链接和语言要求。

语言

使用用户的语言撰写产物。遵循正确的语法，并使用所需的变音符号或特定文字。如果无法确定用户使用的语言，请先询问，再生成输出。

项目根目录

此技能会在相对于项目根目录（工作所在的仓库）的路径下写入产物，而不是相对于 Agent 当前的工作目录。

• 如果从项目内部调用，请使用此技能中显示的相对路径。
• 如果从其他目录调用（例如，从同级仓库调用，或项目位于其他位置），请在每个产物路径前加上 <project-root>/。
• 如果项目根目录不明确，请在写入前通过 harness 提问工具向用户确认。

提示

遵循项目级约定 CLAUDE.md / AGENTS.md（“Skill Prompting Conventions”）。对于以下决策点，请使用 harness 的结构化提问工具：AskUserQuestion（Claude Code）、ask_user_question（Codex）或 question（OpenCode）。

决策点	原因	建议选项
搜索策略	影响召回率与精确度	QMD MCP · QMD CLI · grep/glob 回退方案
回答语言	与语言环境保持一致	Wiki 语言 · 用户语言 · 双语

自由文本提示（不使用结构化工具）：

• 实际查询文本

无暂停模式：如果用户明确禁用了技能执行过程中的澄清，则将每个结构化提示转换为 Open questions（或同等章节）中的条目，并继续执行，不要等待回复。

查询语言对齐

当用户使用的语言与 Wiki 语言不同时，在搜索前将检索查询翻译成 Wiki 语言。先从 .wiki-guardrails.yml（query_language 或 language）确定 Wiki 语言；如果没有 guardrails，则根据 Wiki 的 frontmatter/index 确定。产品名称和代码标识符须保持不变。

• 使用 Wiki 语言撰写 intent:、vec: 和 hyde:。
• 适用时，在 lex: 中加入两种语言的精确术语。
• 除非用户另有要求，否则使用用户的语言回答。
• 如果翻译不确定，请说明翻译了哪些术语，并在 lex: 中保留原文。

检索——优先使用 QMD

推荐的检索引擎是 QMD（本地混合搜索：BM25 + 向量 + LLM 重排）。每个仓库只需进行一次设置，详见此技能仓库中的 docs/wiki/qmd-setup.md。

每次查询前检测是否可用：

• MCP 可用（已注册 mcp__qmd__status 和 mcp__qmd__query 工具）→ 使用 MCP 工具。
• CLI 可用（which qmd 执行成功）→ 使用 qmd query --json --files --min-score 0.4。
• 两者均不可用 → 回退到下文所述的 grep/index 路径。告知用户一次 QMD 尚未配置，并指向 docs/wiki/qmd-setup.md。

切勿自动运行 qmd embed、qmd update 或 qmd collection add——这些是由所有者执行的设置命令。此技能只会查询已构建的索引。

步骤

1. 规划搜索 — 将用户的问题转换为结构化查询文档。始终提供 intent: 行，让重排和片段提取始终围绕实际目标进行：

   intent: <one-sentence framing of what the user actually wants>
   lex: <exact terms / phrases / -negations>
   vec: <natural-language paraphrase of the question>
   hyde: <one short paragraph that looks like the ideal answer>
   

   如果某个子查询不能提供更多有效信息，就将其删去（词汇表查询只需要 lex；“X 是如何工作的”主要使用 vec / hyde）。

2. 通过 QMD 检索

   • MCP：使用结构化的 searches 数组（或多行 q 字符串）和 intent 字段调用 mcp__qmd__query。如果问题仅限于单个集合而非跨仓库查询，请通过 collections 限定范围。
   • CLI：qmd query "$(cat <<EOF intent: ... lex: ... vec: ... hyde: ... EOF )" --json --files -n 8 --min-score 0.3
   • 使用 mcp__qmd__get / mcp__qmd__multi_get（或通过 CLI 使用 qmd get / qmd multi-get）阅读排名前 3-5 的结果。如果片段信息不足以确定内容，请获取完整正文；遵循 QMD 返回的 context 字段 — 其中包含由所有者整理的集合级指导。

3. 备用路径（无 QMD）

   • 阅读 wiki/index.md，并使用“按主题”表格查找可能相关的页面。
   • 使用第 1 步提炼出的关键词，通过 grep / Glob 搜索。
   • 完整阅读找到的页面。

4. 综合答案：

   • 直接回答问题。
   • 使用链接引用所用的 wiki 页面：[page](wiki/path.md)（使用 QMD 返回的路径，而不是 docid）。
   • 如果来源互相矛盾，请呈现不同观点并指出冲突。
   • 如果 wiki 中没有相关信息，请明确说明，并建议可以导入哪些来源。

5. 评估答案是否具有持久价值

   • 如果答案以新颖且实用的方式综合了多个页面 → 提议将其保存为 wiki/sources/ 中的页面（跨主题摘要），或添加为现有页面的新章节。
   • 如果只是简单的一次性答复 → 无需保存。

6. 记录（仅当查询导致 wiki 更新时）：

   ## [YYYY-MM-DD] query | <question summary>
   - Retrieval: qmd | grep-fallback
   - Pages consulted: ...
   - Result saved: yes/no (which page, if yes)
   

规则

• 优先依据 wiki 回答 — 如果答案已经存在，不要从头开始使用代码或外部来源重新综合。
• 始终向 QMD 提供 intent: 行 — 这是提升相关性的最重要手段。
• 信任 QMD 的 context 字段 — 它反映了经过整理的元数据（例如，raw/ 并非权威来源）。不要根据训练时的直觉“纠正”它。
• 如果找不到相关信息，请建议可以导入哪些来源来填补空白。
• 始终引用所用的 wiki 页面。
• 如果问题揭示了信息缺口，请建议可以创建哪些页面（但不要自动创建 — 留待导入处理）。