From 83eb8d0dd0fce60458c7991493631ff7e152e8a7 Mon Sep 17 00:00:00 2001
From: kplam <kplam@qq.com>
Date: Sat, 1 Aug 2026 00:11:05 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E6=96=B0=E5=A2=9E=20QMDSearch=20Agent?=
 =?UTF-8?q?=20Skill=20=E5=8C=85=E4=B8=8E=E4=B8=8B=E8=BD=BD=E5=85=A5?=
 =?UTF-8?q?=E5=8F=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增 skills/qmdsearch-agent（SKILL.md + references/api-examples.md），文档化
  AI Agent 鉴权、文本/文件上传入库（异步轮询）与分层检索调用方式
- 打包 QMDSearch-Agent-Skill.zip 至 app/static/agent-skill/
- 后端新增 GET /agent-skill 免登录下载路由（随 ./app 卷挂载，restart 即生效）
- 前端 API 说明页新增「AI Agent Skill 下载」卡片，链接至 /agent-skill
---
 app/main.py                                   |  18 ++
 .../agent-skill/QMDSearch-Agent-Skill.zip     | Bin 0 -> 5892 bytes
 frontend/src/views/ApiDocs.vue                |  28 ++-
 skills/qmdsearch-agent/SKILL.md               | 145 +++++++++++++++
 .../references/api-examples.md                | 170 ++++++++++++++++++
 5 files changed, 360 insertions(+), 1 deletion(-)
 create mode 100644 app/static/agent-skill/QMDSearch-Agent-Skill.zip
 create mode 100644 skills/qmdsearch-agent/SKILL.md
 create mode 100644 skills/qmdsearch-agent/references/api-examples.md

diff --git a/app/main.py b/app/main.py
index e58ddce..749c7e7 100644
--- a/app/main.py
+++ b/app/main.py
@@ -144,3 +144,21 @@ async def admin_spa(rest: str):
         return FileResponse(file_path)
     # SPA 客户端路由兜底
     return FileResponse(spa_dir / "index.html", media_type="text/html")
+
+
+# AI Agent Skill 压缩包（用于 Agent 上传文档与检索），随 ./app 卷挂载，restart 即生效
+_AGENT_SKILL_ZIP = _STATIC_DIR / "agent-skill" / "QMDSearch-Agent-Skill.zip"
+
+
+@app.get("/agent-skill", include_in_schema=False)
+async def agent_skill_download() -> FileResponse | JSONResponse:
+    """下载 AI Agent Skill 压缩包（qmdsearch-agent skill，含 SKILL.md 与示例）"""
+    if not _AGENT_SKILL_ZIP.is_file():
+        return JSONResponse(
+            status_code=404, content={"code": 1002, "message": "Skill 包不存在"}
+        )
+    return FileResponse(
+        _AGENT_SKILL_ZIP,
+        media_type="application/zip",
+        filename="QMDSearch-Agent-Skill.zip",
+    )
diff --git a/app/static/agent-skill/QMDSearch-Agent-Skill.zip b/app/static/agent-skill/QMDSearch-Agent-Skill.zip
new file mode 100644
index 0000000000000000000000000000000000000000..d3e2ba3aa7b209a3a3241992b9cf3dfee6e0618d
GIT binary patch
literal 5892
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

literal 0
HcmV?d00001

diff --git a/frontend/src/views/ApiDocs.vue b/frontend/src/views/ApiDocs.vue
index cb625bd..b94948c 100644
--- a/frontend/src/views/ApiDocs.vue
+++ b/frontend/src/views/ApiDocs.vue
@@ -1,6 +1,6 @@
 <script setup>
 import { computed } from 'vue'
-import { ApiOutlined, SafetyCertificateOutlined, CodeOutlined } from '@ant-design/icons-vue'
+import { ApiOutlined, SafetyCertificateOutlined, CodeOutlined, DownloadOutlined } from '@ant-design/icons-vue'
 
 // 以下内容整理自项目 README.md 的「API 文档」章节
 const apiList = [
@@ -29,6 +29,8 @@ const methodColor = {
 
 const baseUrl = computed(() => `${window.location.origin}/admin/`.replace(/\/admin\/$/, ''))
 
+const agentSkillUrl = computed(() => `${window.location.origin}/agent-skill`)
+
 const loginExample = `curl -X POST ${baseUrl.value}/api/v1/auth/login \\
   -H "Content-Type: application/json" \\
   -d '{"username": "admin", "password": "your-password"}'`
@@ -59,6 +61,23 @@ const uploadExample = `curl -X POST ${baseUrl.value}/api/v1/documents/upload \\
       message="需要鉴权的接口请在请求头携带 Authorization: Bearer &lt;token&gt;，token 通过 /auth/login 获取。"
     />
 
+    <!-- AI Agent Skill 下载 -->
+    <section class="apidocs__block apidocs__skill">
+      <h3 class="section-subtitle">
+        <DownloadOutlined /> AI Agent Skill 下载
+      </h3>
+      <p class="apidocs__p">
+        为 AI Agent 提供的接入包（含 <code>SKILL.md</code> 与 Python 客户端示例），覆盖文档上传（文本 / 文件）与分层检索。
+        下载后解压到 Agent 的 skills 目录即可启用。
+      </p>
+      <a :href="agentSkillUrl" target="_blank" rel="noopener">
+        <a-button type="primary">
+          <template #icon><DownloadOutlined /></template>
+          下载 QMDSearch-Agent-Skill.zip
+        </a-button>
+      </a>
+    </section>
+
     <!-- 统一响应格式 -->
     <section class="apidocs__block">
       <h3 class="section-subtitle">
@@ -152,6 +171,13 @@ const uploadExample = `curl -X POST ${baseUrl.value}/api/v1/documents/upload \\
   margin-bottom: 20px;
 }
 
+.apidocs__skill {
+  padding: 16px 18px;
+  border: 1px solid rgba(22, 119, 255, 0.25);
+  border-radius: 10px;
+  background: rgba(22, 119, 255, 0.04);
+}
+
 .apidocs__block {
   margin-bottom: 24px;
 }
diff --git a/skills/qmdsearch-agent/SKILL.md b/skills/qmdsearch-agent/SKILL.md
new file mode 100644
index 0000000..84b290c
--- /dev/null
+++ b/skills/qmdsearch-agent/SKILL.md
@@ -0,0 +1,145 @@
+---
+name: qmdsearch-agent
+description: 通过 QMDSearch REST API 让 AI Agent 上传文档（文本/文件）并执行分层检索查询。配置服务地址与 Bearer Token 后，即可在对话中入库知识库并检索答案。
+metadata: {"clawdbot":{"emoji":"📚"}}
+---
+
+# QMDSearch Agent 接入 Skill
+
+本 skill 指导 AI Agent 调用 **QMDSearch**（面向 AI Agent 的分层信息检索服务）的 HTTP API，完成两类核心操作：
+
+1. **上传文档**：把文本或文件送入知识库（异步入库，自动三级总结 + 向量化）。
+2. **查询 / 检索**：对知识库做分层语义检索，返回最相关原文 chunk。
+
+## 何时使用
+
+- 用户希望把一份文档 / 笔记 / 网页内容加入知识库 → 调用上传接口。
+- 用户就知识库内容提问 → 调用检索接口。
+- 用户想确认文档是否入库成功 → 轮询任务状态。
+- 需要列出 / 删除知识库文档、查看统计 → 调用对应只读 / 管理接口。
+
+## 前置配置（必须）
+
+启用前先确定：
+
+- `QMDSEARCH_BASE_URL`：服务基地址，例如 `http://localhost:8000` 或 NAS 地址 `http://<nas-ip>:8000`。
+- `QMDSEARCH_TOKEN`：Bearer Token。通过 `POST {BASE}/api/v1/auth/login`（用户名 + 密码）获取；session TTL 12h，失效后重新登录。
+
+> 所有变更类请求（上传 / 删除）与检索请求都必须在 Header 携带 `Authorization: Bearer <token>`。
+> 当前代码实现中，查询类只读接口（文档列表 / 详情 / 类目 / 统计 / 健康）同样要求 Bearer（与登录态绑定），请始终携带 token 以避免 `1005` 未认证。
+
+## 统一约定
+
+- 路径前缀：`{BASE}/api/v1`
+- 响应体：`{ "code": 0, "data": {...}, "message": "ok" }`，`code=0` 成功；`1xxx` 客户端错误；`2xxx` 服务端错误。
+- 入库是**异步**的：上传返回 `202 + task_id`，需轮询 `GET /documents/tasks/{task_id}` 直到 `status=done`（或 `failed`）。
+
+## 1. 获取 Token
+
+```bash
+curl -X POST {BASE}/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"<password>"}'
+# → {"code":0,"data":{"token":"<JWT>","username":"admin","role":"admin","must_change_password":false},"message":"ok"}
+```
+
+`must_change_password=true` 时，登录成功但调用其他接口会返回 `1006`，需先 `POST /api/v1/auth/password` 改密。
+
+## 2. 上传文档（文本）
+
+`POST {BASE}/api/v1/documents`，JSON body `{text, title?, source?, metadata?}`。
+
+```bash
+curl -X POST {BASE}/api/v1/documents \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"text":"QMDSearch 支持 L1/L2/L3 分层检索……", "title":"QMDSearch 介绍", "source":"notes"}'
+# → 202 {"code":0,"data":{"task_id":"<uuid>","status":"pending"},"message":"ok"}
+```
+
+- `text` 必填且非空；`title` / `source` 可选；`metadata` 为 `dict[str,str]`。
+- 相同 `sha256(text)` 会命中**去重**，直接复用旧文档（`data` 中 `deduplicated=true`）。
+
+## 3. 上传文件
+
+`POST {BASE}/api/v1/documents/upload`，`multipart/form-data`：
+
+- `file`：必填，支持 `.txt .md .html .htm .pdf .docx`
+- `title` / `source`：可选（默认取原文件名）
+- `metadata`：可选 JSON 字符串
+
+```bash
+curl -X POST {BASE}/api/v1/documents/upload \
+  -H "Authorization: Bearer <token>" \
+  -F "file=@document.pdf" \
+  -F "source=manual"
+# → 202 {"code":0,"data":{"task_id":"<uuid>","status":"pending","saved_path":"..."},"message":"ok"}
+```
+
+服务端按扩展名提取纯文本（PDF 扫描件自动 OCR 降级），再复用同一入库流水线。
+
+## 4. 轮询入库任务
+
+`GET {BASE}/api/v1/documents/tasks/{task_id}`（无需鉴权）：
+
+```bash
+curl {BASE}/api/v1/documents/tasks/<task_id>
+# done   → {"code":0,"data":{"task_id":...,"status":"done","result":{...文档ID/总结/分类...},"created_at":...,"updated_at":...}}
+# failed → {"code":0,"data":{"task_id":...,"status":"failed","error":"..."}}
+```
+
+建议：提交后每 1–2s 轮询，直到 `status∈{done,failed}`；`done` 的 `result.document_id` 即入库文档 ID。
+
+## 5. 检索（查询）
+
+`POST {BASE}/api/v1/search`，JSON `{query, top_k?, summarize?}`：
+
+```bash
+curl -X POST {BASE}/api/v1/search \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"query":"如何配置 Redis 缓存","top_k":5,"summarize":false}'
+```
+
+返回 `data`：`{query, hits[], routed_categories[], fallback, extracted_info, summary?}`。
+每个 `hit`：`{text, doc_id, title, section_path, score, doc_summary}`。
+
+- `top_k`：返回条数（默认 `RETRIEVAL_FINAL_K`，通常 5）。
+- `summarize=true`：额外返回 `summary`（对检索结果做 AI 总结）。
+- `fallback=true`：走了全库兜底（未走类目路由），召回较广。
+- `extracted_info`：query 解析出的关键词 / 实体 / 意图 / 命中类目。
+
+## 6. 其他管理接口（按需）
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `/documents` | 文本入库（202 + task_id） |
+| POST | `/documents/upload` | 文件入库（202 + task_id） |
+| GET | `/documents/tasks/{task_id}` | 任务状态（done / failed） |
+| GET | `/documents?limit=&offset=` | 文档列表（分页游标） |
+| GET | `/documents/{doc_id}` | 文档详情（L1 + L2/L3 + chunks 数） |
+| GET | `/documents/{doc_id}/file` | 下载原始文件 |
+| DELETE | `/documents/{doc_id}` | 删除文档（幂等） |
+| GET | `/knowledge/categories` | 知识分类类目集 |
+| GET | `/knowledge/stats` | 统计（四层点数 + 类目分布） |
+| GET | `/health` | 健康检查 |
+
+## 错误码速查
+
+- `1001` 参数 / 格式错误（空文本、不支持的类型、弱密码、超大小）
+- `1004` 资源不存在（task / doc 不存在）
+- `1005` 未认证或凭证无效 / 账号已禁用
+- `1006` 权限不足 / 首次登录须先改密
+- `2000` 服务端内部错误（检索 / 入库 / 列表失败）
+- `2001` 认证服务暂不可用
+
+## Agent 最佳实践
+
+1. **先登录拿 token**，缓存 12h，失效再用 `/auth/login` 刷新。
+2. **上传走异步**：拿到 `task_id` 后轮询，不要在对话里阻塞等待，可告诉用户“正在入库，稍后查询”。
+3. **去重友好**：重复提交同文本会自动复用，不必担心重复。
+4. **大文件 / 批量**：逐文件上传并各自轮询；注意 `UPLOAD_MAX_SIZE_MB`（默认 20MB）。
+5. **检索调参**：召回不足调大 `top_k`；需要摘要设 `summarize=true`；关注 `fallback` 判断是否需要改写 query。
+6. **凭证安全**：token 等同会话，不要写入日志或外发。
+
+完整请求 / 响应示例（含 Python 客户端封装）见 `references/api-examples.md`。
diff --git a/skills/qmdsearch-agent/references/api-examples.md b/skills/qmdsearch-agent/references/api-examples.md
new file mode 100644
index 0000000..228a156
--- /dev/null
+++ b/skills/qmdsearch-agent/references/api-examples.md
@@ -0,0 +1,170 @@
+# QMDSearch API 示例与 Python 客户端封装
+
+> 基址占位符 `{BASE}` 替换为实际服务地址，例如 `http://localhost:8000` 或 `http://<nas-ip>:8000`。
+
+## 一、curl 示例
+
+### 登录
+
+```bash
+curl -s -X POST {BASE}/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"<password>"}'
+```
+
+### 文本入库（202 + task_id）
+
+```bash
+curl -s -X POST {BASE}/api/v1/documents \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"text":"QMDSearch 是面向 AI Agent 的分层信息检索服务……","title":"QMDSearch 介绍","source":"notes"}'
+```
+
+### 文件上传（202 + task_id）
+
+```bash
+curl -s -X POST {BASE}/api/v1/documents/upload \
+  -H "Authorization: Bearer <token>" \
+  -F "file=@document.pdf" \
+  -F "source=manual"
+```
+
+### 轮询任务状态
+
+```bash
+curl -s {BASE}/api/v1/documents/tasks/<task_id>
+```
+
+### 检索
+
+```bash
+curl -s -X POST {BASE}/api/v1/search \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"query":"如何配置 Redis 缓存","top_k":5,"summarize":false}'
+```
+
+## 二、Python 客户端封装
+
+可直接在 Agent 工具代码里复用：
+
+```python
+import time
+import requests
+
+
+class QMDSearchClient:
+    """QMDSearch 最小客户端：登录、入库（文本/文件）、轮询、检索。"""
+
+    def __init__(self, base_url: str, username: str, password: str,
+                 poll_interval: float = 1.5, poll_timeout: float = 120.0):
+        self.base = base_url.rstrip("/")
+        self.username = username
+        self.password = password
+        self.poll_interval = poll_interval
+        self.poll_timeout = poll_timeout
+        self.token: str | None = None
+
+    # ---- 鉴权 ----
+    def login(self) -> str:
+        r = requests.post(
+            f"{self.base}/api/v1/auth/login",
+            json={"username": self.username, "password": self.password},
+            timeout=30,
+        )
+        r.raise_for_status()
+        body = r.json()
+        if body.get("code") != 0:
+            raise RuntimeError(f"登录失败: {body}")
+        self.token = body["data"]["token"]
+        return self.token
+
+    def _headers(self) -> dict:
+        if not self.token:
+            self.login()
+        return {"Authorization": f"Bearer {self.token}"}
+
+    def _ok(self, resp: requests.Response):
+        resp.raise_for_status()
+        body = resp.json()
+        if body.get("code") != 0:
+            raise RuntimeError(f"API 错误 code={body.get('code')} msg={body.get('message')}")
+        return body["data"]
+
+    # ---- 入库 ----
+    def ingest_text(self, text: str, title: str = "", source: str = "",
+                    metadata: dict | None = None) -> str:
+        data = {"text": text}
+        if title:
+            data["title"] = title
+        if source:
+            data["source"] = source
+        if metadata:
+            data["metadata"] = {str(k): str(v) for k, v in metadata.items()}
+        resp = requests.post(f"{self.base}/api/v1/documents",
+                             headers=self._headers(), json=data, timeout=30)
+        return self._ok(resp)["task_id"]
+
+    def upload_file(self, path: str, title: str = "", source: str = "",
+                    metadata: dict | None = None) -> str:
+        files = {"file": open(path, "rb")}
+        data = {}
+        if title:
+            data["title"] = title
+        if source:
+            data["source"] = source
+        if metadata:
+            data["metadata"] = str({str(k): str(v) for k, v in metadata.items()})
+        resp = requests.post(f"{self.base}/api/v1/documents/upload",
+                             headers=self._headers(), files=files, data=data, timeout=60)
+        return self._ok(resp)["task_id"]
+
+    # ---- 轮询 ----
+    def wait_task(self, task_id: str) -> dict:
+        deadline = time.time() + self.poll_timeout
+        while time.time() < deadline:
+            resp = requests.get(f"{self.base}/api/v1/documents/tasks/{task_id}", timeout=30)
+            data = self._ok(resp)
+            if data["status"] == "done":
+                return data["result"]
+            if data["status"] == "failed":
+                raise RuntimeError(f"入库失败: {data.get('error')}")
+            time.sleep(self.poll_interval)
+        raise TimeoutError(f"任务 {task_id} 轮询超时")
+
+    def ingest_text_wait(self, *args, **kwargs) -> dict:
+        return self.wait_task(self.ingest_text(*args, **kwargs))
+
+    def upload_file_wait(self, *args, **kwargs) -> dict:
+        return self.wait_task(self.upload_file(*args, **kwargs))
+
+    # ---- 检索 ----
+    def search(self, query: str, top_k: int | None = None,
+               summarize: bool = False) -> dict:
+        payload = {"query": query, "summarize": summarize}
+        if top_k is not None:
+            payload["top_k"] = top_k
+        resp = requests.post(f"{self.base}/api/v1/search",
+                             headers=self._headers(), json=payload, timeout=60)
+        return self._ok(resp)
+
+
+# 用法
+if __name__ == "__main__":
+    client = QMDSearchClient("http://localhost:8000", "admin", "<password>")
+    client.login()
+    # 文本入库并等待完成
+    result = client.ingest_text_wait("这是一篇关于分层检索的笔记……", title="笔记")
+    print("document_id =", result["document_id"])
+    # 检索
+    hits = client.search("分层检索是什么", top_k=5)["hits"]
+    for h in hits:
+        print(f"[{h['score']:.3f}] {h['title']}: {h['text'][:80]}")
+```
+
+## 三、响应结构速记
+
+- 文本 / 文件入库 `202` → `data = {task_id, status:"pending"[, saved_path]}`
+- 任务 `done` → `data.result = {document_id, summary:{l1_summary,l2_outline,l3_content_outline,level}, category, chunks_count, tags, category_confidence, deduplicated}`
+- 检索 → `data = {query, hits:[{text,doc_id,title,section_path,score,doc_summary}], routed_categories, fallback, extracted_info, summary?}`