Kb Query

SKILL.md

---
name: kb_query
description: Answer Research KB questions from the team Gitea-backed knowledge base with OpenClaw reasoning, optional reference attachments, stable citations, OpenClaw-led evidence selection, and optional high-value Q&A persistence.
---

# kb_query

## 职责边界

`kb_query` 只负责“对话”页面的知识库查询。用户输入可以是纯文字，也可以带附件；附件一律是本轮参考材料，用于辅助理解问题、补充上下文或做临时对比，稳定来源仍以知识库证据页为准。

本 skill 不负责登录、权限、会话历史、文件上传、任务调度或资料源入库。Java 后端负责这些系统动作。OpenClaw 负责理解用户问题、判断需要参考哪些 KB 页面、综合证据、生成回答、判断证据是否充分，以及判断是否值得沉淀为 `qa/` 页面。Python 脚本只做确定性动作：读取 catalog/index 和探索卡片、按 OpenClaw 选择读取证据页面、抽取附件文本预览、校验 OpenClaw 输出、可选写入 `qa/`、维护 `catalog.json`/`index.md`、写出后端 result JSON。

不要提供脚本兜底的抽取式简化回答。没有真实 OpenClaw 理解时，任务应失败或返回明确错误，而不是用脚本假装完成问答。

## 输入约定

后端 payload 通常包含：

- `taskId`: 后端生成的查询任务 ID，当前格式为 `query-<conversationId>-<messageId>`，用于共享 payload/result 文件和 OpenClaw session key。
- `skill`: `kb_query`。
- `question`: 用户问题。
- `conversationId`: 当前会话 ID。
- `messageId`: 用户消息 ID。
- `attachments[]`: 本轮参考附件，字段包括 `attachmentId`、`fileName`、`mimeType`、`storagePath`、`sha256`、`size`、`temporary=true`。
- `answerPolicy.scopeSelection`: `auto_by_openclaw`。
- `answerPolicy.knowledgeBaseFirst`: `true`，表示事实性回答必须优先基于团队 KB。`answerPolicy.allowNonKbSupplementWhenInsufficient=true` 时，知识库证据不足可以在明确说明后补充非 KB 或附件分析。
- `answerPolicy.writeHighValueAnswerToQa`: 是否允许高价值问答写入 `qa/`。
- `payloadFile`、`resultFile`、`sharedDir`: 后端共享目录路径。

环境变量包括 `GITEA_URL`、`GITEA_BOT_TOKEN`、`GITEA_BOT_USERNAME`、`GITEA_ORG`、`TEAM_KB_REPO`、`OPENCLAW_SHARED_DIR`。

## 执行流程

必须使用四段式流程，让“选哪些页面作为参考”由 OpenClaw 完成，而不是由脚本用关键词配对决定。

上下文预算必须保守执行。`prepare`/`fetch` 命令会把完整 JSON 写入文件，终端只输出摘要；OpenClaw 应阅读文件路径指向的 JSON，不要把完整 context/evidence 粘贴回聊天。页面选择应坚持“够用即可”：通常选择 1-4 个最关键 KB 页面，最多不得超过 `context.analysisLimits.maxSelectedPages`。如果 OpenClaw 判断问题本身不适合由 KB 回答，或者没有任何相关 KB 页面，可以写出合法的空选择 `{"selectedPages":[],"rationale":"...","unresolvedQuestions":[]}`，继续运行 fetch/apply，并在答案中按证据不足规则说明。不要因为证据不足而停止在 selection 阶段；如果少量证据已经能回答，不要扩大读取范围；如果证据不足，按不足规则回答，而不是继续尝试读取大量页面。

所有中间 JSON 文件必须是严格合法 JSON。写 `page-selection.json` 和 `answer.json` 时不要加入 Markdown 代码围栏、注释、尾随逗号或半截文本；文件写好后再运行下一步脚本。`answer` 正文通常包含 Markdown、双引号和表格，优先用 `python3` 的 `json.dump`/`json.dumps` 写出整个 `answer.json`，不要手写长 JSON 字符串。

1. 运行准备脚本：

```bash
python3 scripts/run_task.py prepare --input <payload.json> --context-output <context.json>
```

准备脚本会读取 `catalog.json`、`index.md`、页面元数据、少量探索卡片和附件文本预览，输出 OpenClaw 可读的查询规划上下文。命令行只返回摘要，完整内容在 `<context.json>` 中。`starterPageCards` 只是帮助 OpenClaw 快速了解可能相关的页面，不是最终证据，也不能直接作为引用依据。脚本不会生成答案，也不会决定最终参考页面。

2. OpenClaw 阅读 `<context.json>`，根据用户问题、目录、索引、页面卡片、预算限制和附件上下文，思考并生成 `<page-selection.json>`。OpenClaw 可以选择任意可见 catalog 页面，不限于 `starterPageCards`，但应选择最小充分集合。

`page-selection.json` 示例：

```json
{
  "rationale": "为什么这些页面需要被读取作为证据",
  "selectedPages": [
    {
      "path": "projects/example.md",
      "reason": "用于确认项目边界和当前实现",
      "expectedUse": "回答功能进度和边界"
    }
  ],
  "unresolvedQuestions": []
}
```

3. 按 OpenClaw 选择读取证据页：

```bash
python3 scripts/run_task.py fetch --input <payload.json> --context <context.json> --selection <page-selection.json> --evidence-output <evidence.json>
```

`fetch` 只负责校验路径、读取 OpenClaw 选择的 KB 页面、解析 frontmatter `sources[]`，并输出 `<evidence.json>`。命令行只返回证据页摘要，完整内容在 `<evidence.json>` 中。它不做答案判断，也不替 OpenClaw 增删参考范围。

4. OpenClaw 阅读 `<context.json>` 和 `<evidence.json>`，进行知识库问答，生成 `<answer.json>`。`answer.json` 必须符合“OpenClaw 输出格式”。答案中的 `sources[]` 只能引用 `<evidence.json>` 中实际读取到的稳定 KB 页面；临时附件不能作为稳定 KB 来源。

5. 运行应用脚本：

```bash
python3 scripts/run_task.py apply --input <payload.json> --context <context.json> --evidence <evidence.json> --answer <answer.json>
```

应用脚本会校验答案、确保结尾有参考来源、必要时写入 `qa/` 并更新 `catalog.json` 和 `index.md`，最后把后端 result JSON 写入 payload 指定的 `resultFile`。

6. 最终回复后端：

```json
{"success": true, "resultFile": "<result.json>"}
```

## 回答规则

OpenClaw 必须先判断团队 KB 证据是否足以回答问题。证据充分性判断基于 OpenClaw 自己选择并通过 `fetch` 读取到的稳定 KB 页面。

如果 KB 证据足够：先直接回答结论，再给出必要解释、比较、步骤或建议。回答必须以中文为主，除非用户明确要求其他语言。

如果 KB 证据不足：回答开头必须明确说明“知识库内容无法回答这个问题”或等价表达，然后说明缺少哪些证据。可以在下方补充一般性回答或基于附件的临时分析，但必须标注“以下为非知识库结论/本轮参考附件推断”。

附件只能帮助理解问题、补充本轮上下文或做临时对比；不要把临时附件当作长期 KB 来源，不要因为附件出现就写普通知识页。若答案主要依赖附件且缺少稳定 KB 证据，通常不要沉淀为 `qa/`。

回答正文不强制套固定模板。可以按用户问题自然组织成结论、解释、对比、步骤、表格或建议；但不要为了模板牺牲可读性。

答案结尾必须包含“参考来源”小节，这是唯一强制模板。稳定来源应优先列出 KB 页面路径和标题；如果证据页带有 `sources[]`，同时列出对应源文件、归档路径、仓库 URL、commit 或其他可追溯线索。若没有可引用 KB 页面，写明“知识库中未找到可支撑本问题的页面”。

## 高价值问答沉淀

高价值问答不是“回答得长”或“用户问了一个问题”就沉淀，而是要成为团队以后可复用的知识入口。OpenClaw 必须先做结构化评估，再决定是否把 `highValue` 或 `qa.write` 设为 `true`。

硬性门槛：

- `knowledgeSufficient=true`，且答案有稳定 KB 页面支撑。
- 主要依据不是本轮临时附件；附件只能帮助理解问题或补充临时上下文。
- 问题不是一次性操作、临时状态查询、简单事实定位、格式转换、寒暄、泛泛建议或纯外部常识问答。
- 结论足够稳定，后续成员在相同或相近问题下可以直接复用。

正向信号：

- 跨多个稳定 KB 页面综合，或者把一个重要单页中的规则/边界整理成可复用的规范答案。
- 回答澄清了项目架构、功能边界、资料源处理规则、实验结论、技术选型、风险判断或工作流程。
- 答案包含明确判断、适用条件、例外情况和后续行动，而不是只摘录原文。
- 该问题预计会反复出现，沉淀后能减少后续检索和解释成本。

建议采用 0-5 分评估：`reuseValue`、`synthesisDepth`、`evidenceQuality`、`stability`、`actionability` 各 0/1 分。总分至少 4 分，且通过全部硬性门槛时，才允许写入 `qa/`。

OpenClaw 必须在 `answer.json` 中给出 `qaEvaluation`，说明为什么是或不是高价值问答。apply 脚本只执行确定性拦截：缺少评估、证据不足、无稳定来源、附件驱动、临时/一次性、分数不足时，即使 OpenClaw 请求写入，也不沉淀。

`qa/` 页面应包含：问题、可复用回答、证据页面、适用场景、更新时间。QA 页面只应引用稳定 KB 页面作为来源；临时附件不能作为唯一长期证据。

## OpenClaw 输出格式

`answer.json` 是 OpenClaw 生成、apply 脚本读取的文件：

```json
{
  "answer": "完整回答。正文不需要固定模板；结尾可以已包含参考来源，apply 会补齐缺失的参考来源。",
  "knowledgeSufficient": true,
  "sources": [
    {
      "path": "projects/example.md",
      "title": "Example",
      "type": "project",
      "snippet": "可选引用片段",
      "sourceIds": [],
      "sourceTraces": [
        {
          "sourceId": 1,
          "sourceType": "local_folder",
          "title": "原始资料标题",
          "fileName": "example.pdf",
          "archivedPath": "source_files/local_folder/example.pdf",
          "url": "",
          "commitHash": ""
        }
      ]
    }
  ],
  "usedAttachments": [
    {
      "attachmentId": 1,
      "fileName": "context.docx",
      "role": "query_reference"
    }
  ],
  "highValue": false,
  "qaEvaluation": {
    "reuseValue": 0,
    "synthesisDepth": 0,
    "evidenceQuality": 0,
    "stability": 0,
    "actionability": 0,
    "attachmentDriven": false,
    "ephemeral": false,
    "reason": "为什么适合或不适合沉淀"
  },
  "qa": {
    "write": false,
    "path": "qa/example.md",
    "title": "可复用问答标题",
    "content": "可选；不填时 apply 根据 answer 自动生成"
  },
  "errors": []
}
```

后端最终读取 `resultFile` 中的字段：

```json
{
  "success": true,
  "answer": "...",
  "sources": [],
  "createdQaPath": "qa/example.md",
  "processedSources": ["team-kb"],
  "createdPages": [],
  "updatedPages": [],
  "errors": [],
  "commitId": ""
}
```