检索与数据转换：完整实践与解答

需能阅读 Python 3.11+ 与 JSON 数组，不依赖 ripgrep 或 jq。完整转换器按标题子串筛选、校验唯一 id、排序并输出 Markdown；先对照 documents.json 与特殊标题静态预期，再看README。a.md、b.md 是链接目标占位，本包不包含这些文章。示例未执行。

检索 完整索引转换

检索 完整索引转换：检索完整索引转换器把JSON文档数组筛选成Markdown目录。示例未执行；它使用casefold做不区分大小写的子串匹配，拒绝重复id，输出转义标题中的Markdown特殊字符。

特殊标题输入包含HTML样式、星号、反引号、方括号和反斜线。转换器对全部ASCII标点转义；静态预期经CommonMark解析应全部保留为链接字面文字，不产生图片标签、强调或行内代码。CR/LF会变为空格；其他控制字符未规范化，其他Markdown扩展仍需另行检查。

检索 精确匹配练习

题目：搜索a.b希望只找到字面键而不是axb，应该怎样选择？

参考答案

检索 精确匹配练习：文本工具选择固定字符串模式；若处理JSON键则解析后检查键名相等。本例标题筛选本来就是子串匹配，不假称精确键检索。

检索 转换恢复

检索 转换恢复：检索转换恢复保留原始JSON，本例仅向标准输出写Markdown。重定向到文件由读者Shell控制，若目标已有内容可能覆盖；清理只删除自己生成的目录文件，不改原始资料。

完整源码、配置与输入

下列文件与仓库同源，包含完整实现和输入；不是运行证明。部分练习只需人工阅读配置，不强制构造模拟器。

documents.json

[{"id":"b","title":"API [Guide]","tags":["http"]},{"id":"a","title":"API Basics","tags":["http","start"]},{"id":"c","title":"Storage","tags":["disk"]}]

special-titles.json与静态预期

[{"id":"literal","title":"API <img src=x> & *bold* `code` [bracket] \\path"}]

- [API \<img src\=x\> \& \*bold\* \`code\` \[bracket\] \\path](./literal.md)

index.py

import json
import string
import sys
from pathlib import Path

def escape_title(value):
    normalized = value.replace("\n", " ").replace("\r", " ")
    return "".join("\\" + char if char in string.punctuation else char for char in normalized)

def render(documents, term):
    if not isinstance(documents, list):
        raise ValueError("expected array")
    seen = set()
    selected = []
    for doc in documents:
        if not isinstance(doc, dict) or not isinstance(doc.get("id"), str) or not isinstance(doc.get("title"), str):
            raise ValueError("each document needs string id and title")
        identity = doc["id"]
        if not identity or any(not (c.isascii() and (c.isalnum() or c in "-_")) for c in identity):
            raise ValueError("id must contain ASCII letters, digits, dash or underscore")
        if identity in seen:
            raise ValueError("duplicate id")
        seen.add(identity)
        if term.casefold() in doc["title"].casefold():
            selected.append(doc)
    return "\n".join(f"- [{escape_title(d['title'])}](./{d['id']}.md)" for d in sorted(selected, key=lambda d: d["id"]))

if __name__ == "__main__":
    try:
        if len(sys.argv) != 3:
            raise ValueError("usage: python index.py documents.json TERM")
        print(render(json.loads(Path(sys.argv[1]).read_text(encoding="utf-8")), sys.argv[2]))
    except (ValueError, OSError) as exc:
        print(str(exc), file=sys.stderr)
        sys.exit(2)

requirements.txt

# Python 3.11+ standard library only; no ripgrep or jq needed by this example.

项目README与完整依赖

README提供前置、完整自跑或阅读方式、预期、失败案例与恢复清理。本轮没有执行任何示例、产品CLI、模型或外部API。

# 检索与数据转换：完整教学包

示例未执行。全部输入为教学虚构资料，不能用于真实账号、生产数据或外部系统。

## 前置与依赖

Python3.11以上标准库，不依赖ripgrep或jq；转换出的a.md/b.md是目录目标示例，本包不声称已存在文章。

## 文件与输入

- `documents.json`：本包完整文件。
- `special-titles.json`：含HTML样式、强调、反引号、方括号和反斜线的标题。
- `special-expected.txt`：特殊标题转换后的静态预期Markdown文本。
- `index.py`：本包完整文件。
- `requirements.txt`：本包完整文件。

## 读者将来自跑或阅读

复制本包所有文件到独立目录，在该目录作为当前工作目录。以下是读者自用资料，本轮禁止执行。

```text
python index.py documents.json API
```

## 正常预期

按id排序输出两行：API Basics链接./a.md，其后API [Guide]链接./b.md，方括号在Markdown标题转义。

特殊输入：未来读者可将命令的输入改成special-titles.json，搜索词仍为API。标题原文为：

```text
API <img src=x> & *bold* `code` [bracket] \path
```

完整预期见special-expected.txt。CommonMark渲染后的链接文字应与上述原文一致；不产生img标签、强调或行内代码。转换器对string.punctuation中的全部ASCII标点逐字符加反斜杠，CR/LF先替换为空格；其中小于号、大于号和&也按字面文本处理。

## 失败案例与恢复

重复id或非法id字符会退出2；空匹配只输出换行，表示无结果而非输入错误。

## 清理及能力边界

程序只写标准输出，不改JSON；读者重定向输出须选新文件避免Shell覆盖，不能把标签过滤与标题子串匹配混淆。

转义策略只面向CommonMark链接文字，不能用于HTML属性、Shell或其他模板语境。链接目标仅由已校验的ASCII id构造，不采用标题。控制字符除CR/LF外未规范化；输出仍需按目标渲染器检查，不宣称任意Markdown扩展均保持相同行为。

## 来源

- [官方依据](https://github.com/BurntSushi/ripgrep/blob/master/GUIDE.md)（2026-10-17资料核对；不是运行证明）

依据与适用范围

• 本课官方依据，资料核对日2026-10-17。

本课完成的是列明任务的理论与静态资料，不代表产品全部能力或三平台运行通过。历史文档保留旧URL；涉及账号、版本、价格与界面位置时，以对应官方资料及实际授权环境为准。