# DWS 知识问答最佳实践
面向 AI Agent 的 **DWS数据仓库服务离线知识库**。内置华为云官方文档 ，支持 agent 离线检索并带官方 URL 出处回答。
**纯离线运行**：检索阶段零联网、零第三方依赖（Python 3 stdlib 即可）。检索由脚本完成，LLM 只读命中的 chunk 正文。
Skill 地址：hwc-dws-knowledge-qa（随 hwc-dws-cli 分发，源码位于 dws-cli 仓库 agent_skills 目录）
#### 快速开始
1. 目录结构。
   ```
   dws-knowledge-qa/
   ├── SKILL.md                 # Agent 协议（触发词/检索流程/行为约束）——挂载给 agent 的核心
   ├── README.md                # 说明
   ├── references/
   │   ├── search-guide.md      # 检索策略手册（LLM 检索时参考）
   │   └── index/
   │       ├── catalog.json     # 文档域元数据
   │       ├── sections.json    # 每域页面清单（标题/官方URL/chunk区间）
   │       └── pack/*.jsonl     # 全量 DWS 文档切分的 chunk
   └── scripts/
       ├── common.py            # 共享工具
       ├── search.py            # 分层检索入口（LLM 唯一需要的工具）
       ├── fetch_llms.py        # 从华为云 llms.txt 下载官方文档（数据更新用）
       └── build_pack.py        # 构建索引（数据更新用）
   ```
   
2. 挂载到你的 Agent。 挂载后，agent 会通过 SKILL.md 的触发词识别 DWS 问题场景，然后调用 search.py 完成分层检索（--list-docs → --list-sections → --query → --read）。
   
3. 验证挂载成功。
   ```
   python scripts/search.py --list-docs          # 应列出所有文档域
   python scripts/search.py --query "集群扩容" --doc mgtg-dws --topk 5
   python scripts/search.py --read mgtg-dws:0001
   ```
   
 
#### search.py 使用说明
search.py命令说明如[表1]所示。
 表1**search.py命令** 
| 命令                                                                               | 说明                         |
|:---|:---|
| --list-docs                                                                       | 列出全部文档域（slug/页数/chunk数）    |
| --list-sections \<slug\>                                                         | 某域的页面清单（标题/官方URL/chunk区间） |
| --query "\<关键词\>" \[--doc \<slug\>\] \[--section \<子串\>\] \[--topk N\] \[--json\] | 分层检索，只输出元数据（不含正文）         |
| --read \<doc:chunk-id\>...                                                      | 输出 chunk 全文（唯一放大文本的入口）      |
   
示例：
```
python scripts/search.py --query "GDS" --doc migration-dws --topk 5
python scripts/search.py --query "列存表" --doc devg-dws --section "选择DWS表存储模型"
python scripts/search.py --read sqlreference-dws:0001 tg-dws:0007
```
**出处格式**：答案引用 \[页面标题\](官方URL)，如 \[DWS SSD云盘和SSD本地盘的区别\](https://support.huaweicloud.com/dws_faq/dws_03_2141.md)。 联网可单击直达原文；不联网时 URL 作为稳定标识，仍可追溯页面标题。
#### 数据更新
内置库已打包好，**开箱即用**。如需更新到华为云最新文档：
```
# 1. 下载最新官方文档（需联网，可访问 support.huaweicloud.com）
python scripts/fetch_llms.py --url https://support.huaweicloud.com/dws/llms.txt
# 2. 重建索引
python scripts/build_pack.py
```
增量更新（两种模式）：
```
# 模式A：只下载新增页面，已存在的跳过（不检查内容是否变化）
python scripts/fetch_llms.py --skip-existing --url https://support.huaweicloud.com/dws/llms.txt
# 模式B：已存在的也重新下载，内容有变化才覆盖（推荐用于日常更新）
python scripts/fetch_llms.py --update-changed --url https://support.huaweicloud.com/dws/llms.txt
# 两种模式执行后都要重建索引
python scripts/build_pack.py
```
--update-changed 会输出每页状态：\[SAME\] 内容未变保留 / \[CHANGED\] 已更新覆盖 / \[OK\] 新增。
自定义文档：把自己的 md 放进 sources/\<域\>/ 后重跑 build_pack.py 即可并入索引。
#### 文档域一览
内置文档域如[表2]所示。
 表2**文档域一览** 
| slug（域前缀）                                | 内容                           |
|:---|:---|
| sqlreference-dws / sqlreference-911-dws | SQL 语法参考（9.1.0 / 9.1.1）        |
| devg-dws / devg-911-dws                | 开发指南（9.1.0 / 9.1.1）          |
| mgtg-dws                                | 用户指南（集群管理/控制台操作）              |
| api-dws                                  | API 参考                       |
| dws_faq                                | 常见问题                          |
| trouble-dws                             | 故障排除                          |
| bestpractice-dws                          | 最佳实践                         |
| migration-dws                            | 数据迁移与同步                       |
| tg-dws                                   | 工具指南（gsql/GDS/DSC/DataCheck） |
| errorcode-dws / errorcode-new-dws         | 错误码（8.2.0 及以下 / 8.2.1 及以上）   |
| productdesc-dws                          | 产品介绍                           |
| price-dws                              | 计费说明                          |
| bulletin-dws                             | 服务公告/版本说明                      |
| qs-dws                                    | 快速入门                        |
| pwp-dws / pwp-910-dws / pwp-911-dws     | 性能白皮书                        |
| sdkreference-dws / clir-dws             | SDK / CLI 参考                  |
   
#### 常见问题
- **Q: 需要联网吗？**
  检索阶段不需要------索引和 chunk 全部离线内置。只有「数据更新」 需要联网拉取华为云文档。
  
- **Q: 需要安装第三方库吗？**
  不需要。search.py / build_pack.py / fetch_llms.py 全部 使用 Python 3 标准库（urllib/argparse/json/re/pathlib）。
  
- **Q: 支持哪些 Python 版本？**
  Python 3.8+ 均可（含 3.12）。