PyPTO-Gym 文档检索技能 pypto-docs-search 实战指南：本地缓存发现、四类检索模板与离线排障索引

PyPTO-Gym 文档检索技能 pypto-docs-search 实战指南：本地缓存发现、四类检索模板与离线排障索引

【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym

导读

pypto-docs-search 是 CANNBot Skills 中面向普通 PyPTO（Tensor）算子开发的文档检索技能，核心思路是"按关键词在本地缓存发现资源位置，再直接读取全文"：通过sync_devkit.py将 PyPTO 官方文档仓与 PyPTO-Gym 算子仓装配成本地纯文件缓存，随后用原生Grep/Glob在缓存中检索 API 文档、算子参考实现、golden 与测试，全程可离线。读完本文，你将掌握缓存目录结构与环境变量配置、同步脚本的符号链接复用与 sparse-checkout 下载原理、四类检索模板的精确写法，以及按错误码 / API 名 / 教程主题 / 参考实现四条入口键查索引的完整排障路径。

技能定位：本地优先、纯文件缓存

pypto-docs-search 服务于 PyPTO 算子开发工作流中的"查文档"环节，与 pypto-api-explore 配合：后者负责 API 映射、约束检查与 Tiling 需求分析，其Exploresubagent 统一使用本技能按需搜索 API 文档、参考实现与 golden。PyPTO-Pro（Tile 算子）资料则走独立的 pypto-pro-docs-search，两者缓存形态与装配方式不同，检索时需区分。

本技能的设计取舍非常明确：

• 缓存是纯文件：可用原生Grep/Glob，不依赖文档站的远程检索能力；
• 可离线：一次装配后即可脱离网络工作；
• 文档站不能远程检索：因此缓存缺失时，只能按确定路径直接取文档全文。

边界同样清晰：已知确定路径或 URL 的单点读取直接Read/WebFetch，不经本检索；本检索只用于按关键词发现、跨算子 / 跨文件定位。

资源缓存结构

缓存根目录由环境变量PYPTO_DEVKIT_DIR指定，未设置时默认取${XDG_CACHE_HOME:-$HOME/.cache}/pypto-devkit。其下三个子目录对应三类资源：

从缓存布局可以看出它与仓库源码的对应关系：ops/直接符号链接或下载自仓库的 src/pypto_gym/ops（含pypto_tensor/<模型>/算子实现与pypto_pro/目录），tests/对应 tests/ops（按模型分组的test_*.py与*_golden*.py），docs/则来自 PyPTO 主仓的docs/zh。

准备缓存：sync_devkit.py 装配原理

首次使用或需要更新时，在技能目录下运行一次：

python3 cannbot-skills/ops/pypto-docs-search/scripts/sync_devkit.py

成功标准：$PYPTO_DEVKIT_DIR下出现docs/ ops/ tests/三个目录，并写入MANIFEST.json。

两类资源、两条装配请求

从 sync_devkit.py 源码看，脚本内部构造两条装配请求（ProvisionRequest）：

符号链接复用：磁盘上每类只有一份

装配的核心策略是"当前工作树已含某类资源时符号链接复用、免重复下载"：

1. 优先检查环境变量PYPTO_SRC/PYPTO_GYM_SRC指定的本地工作树；
2. 否则用find_up()从$PWD逐级向上查找含 marker 子路径的仓库根（例如从当前项目往上找到含docs/zh/api的 PyPTO 工作树）；
3. 找到则relink()建立符号链接（等价ln -sfn），并在MANIFEST.json中记录mode: "symlink"；
4. 找不到才走 sparse-checkout 下载。

这样做保证了"磁盘上每类只有一份"，grep不会命中两份不一致的副本——符号链接与真实目录在文件系统层面共享同一份数据。

下载分支：blobless 克隆 + sparse-checkout

当本地没有可复用工作树时，脚本执行：

git clone --depth 1 --filter=blob:none --no-checkout <url> <tmp> git config core.sparseCheckout true git config core.sparseCheckoutCone true git sparse-checkout set <子目录列表> git checkout --detach HEAD

即一次性完成浅克隆（depth 1）+ blobless（--filter=blob:none）+ 稀疏检出，只拉取docs/zh、src/pypto_gym/ops、tests/ops三条子树，大幅减少下载量与磁盘占用。下载完成后记录mode: "download@<short-revision>"，MANIFEST.json的source字段记录远端 URL 与子路径，可追溯缓存来源。

环境变量与常用参数

退出码约定：0成功；3表示缺少git或无法创建缓存目录；4表示下载 / sparse 初始化 / pin 切换失败。

检索：四类模板与精确减噪

缓存就绪后，用原生Grep/Glob在缓存三类中按关键词发现。子串匹配即可（例如搜mul会连带命中matmul）；已知 API 名时传精确名（如pypto-rms_norm）可减噪。四类模板如下（<kw>换成关键词）：

排除规则：避免命中 Pro 资料

普通 PyPTO 检索需避开 PyPTO-Pro 专属内容：

• 文档检索排除docs/api/pro_api/和docs/guide/下的pro/子树；
• 测试检索排除tests/pypto_pro/。

这与仓库中 src/pypto_gym/ops/pypto_pro（PyPTO-Pro 算子）与pypto_tensor/（普通 PyPTO 算子）的目录分层一致，两条技术栈的资料互不污染。

命中后的读取与高级检索

命中后直接Read全文，不再二次检索。高级检索（正则、大小写不敏感-i、上下文-A/-B、限定文件类型）直接用Grep/Glob的对应参数即可。大范围或多角度检索（如"找某能力的全部参考实现、跨目录定位"）应派Exploresubagent，并给出明确目标与范围，例如："在$PYPTO_DEVKIT_DIR/ops/pypto_tensor找 attention 的融合实现"。

缓存未就绪时的兜底路径

当缓存缺docs/ops/tests时：

1. 先运行python3 cannbot-skills/ops/pypto-docs-search/scripts/sync_devkit.py装配；
2. 若无法装配但文档站可访问，按下方索引的入口键拿到确定文档路径后，直接WebFetch https://pypto.gitcode.com/_sources/<sub>.md.txt取全文——<sub>为去掉docs/前缀的路径，例如api/tensor_api/operation/pypto-add；
3. 工具等例外入口见对应索引；
4. 注意：算子参考实现与 golden 无文档站形态，仅缓存在场可查，此类资源必须依赖缓存。

详细索引：四条入口键直达资源

索引文件位于 cannbot-skills/ops/pypto-docs-search/references，按问题入口键分四类：

• 报错带错误码→ error-code-index.md（前缀 → 组件排障文档）；
• 知道算子 / API 名→ api-index.md；
• 查教程 / 安装 / 工具文档→ doc-index.md；
• 找算子参考实现 / golden→ sample-index.md。

入口一：按错误码排障

报错带Errcode: Fxxxxx!/ErrCode: Fxxxxx!时，按前缀定位组件排障文档：缓存在场读$PYPTO_DEVKIT_DIR/docs/guide/appendix/trouble_shooting/<doc>.md，无缓存则在线取https://pypto.gitcode.com/_sources/guide/appendix/trouble_shooting/<doc>.md.txt。例如错误码F70001前缀F7→ MACHINE →<doc>=machine。

核心前缀映射表：

其中distributed、verify、operation、view_op仅旧站有专页。无错误码（FFFFF/UNKNOWN/ 无码报错）时，从报错信息与日志入手，排查教程见 doc-index.md 的guide/programming_guide/tensor/debug。

入口二：按 API 名查文档

api-index.md 覆盖全部 API 文档，按<类>/<name>两级定位：<类>取operation / tensor / config / datatype / symbolic / controlflow / element / others之一，<name>为区下条目（已含pypto-前缀）。缓存在场读$PYPTO_DEVKIT_DIR/docs/api/tensor_api/<类>/<name>.md，无缓存则在线.../_sources/api/tensor_api/<类>/<name>.md.txt。各区随版本增删，最新以缓存目录或_sources/api/tensor_api/<类>/index.md.txt为准。

八类分区要点：

对算子开发而言，config区的 Tiling 文档（set_vec_tile_shapes/set_cube_tile_shapes）与others区的pypto-from_torch是约束核查的高频入口，与 pypto-api-explore 中"必查项"一一对应。

入口三：教程 / 安装 / 工具文档

doc-index.md 按主题组织（<path>为去掉docs/前缀的路径）：缓存在场读$PYPTO_DEVKIT_DIR/docs/<path>.md，无缓存则在线.../_sources/<path>.md.txt。

• install/安装与环境：prepare_environment（环境准备）、build_and_install（编译安装）；
• guide/教程：introduction（简介）、quick_start/tensor/quick_start（快速入门）、programming_guide/tensor/program_paradigms（编程范式）、programming_guide/tensor/development/（tensor_creation、tensor_operation、tiling、compile、loops、conditions）、programming_guide/tensor/debug/（debug、precision、performance、matmul_performance_guide、debug_case_ffn、performance_case_quantindexerprolog、performance_case_GDR）、programming_guide/tensor/pytorch_integration（PyTorch 集成）、appendix/（faq/index、glossary）；
• 配套可视化与分析工具：工具文档走独立的官方工具站（pypto-tools.gitcode.com/_sources/），不在主仓缓存中，涵盖introduction/（简介、安装、快速入门、数据准备）、control_flow/index（控制流图）、computation_graph/index（计算图）、swimlane_graph/index（泳道图）、three_column/three_column（三栏联动视图）、others/others、appendix/index。

入口四：算子参考实现与 golden

sample-index.md 说明：算子参考实现与 golden 只在缓存里，无文档站形态，按模型 / 算子名定位后直接Read取全文。

算子参考实现常见路径为$PYPTO_DEVKIT_DIR/ops/pypto_tensor/<模型>/<算子>/<算子>_impl.py（模型与算子名随版本增删，用命令取、不写死）：

ls "$PYPTO_DEVKIT_DIR/ops/pypto_tensor" # 列全部模型 find -L "$PYPTO_DEVKIT_DIR/ops/pypto_tensor" -ipath "*<算子名>*" # 按算子名跨模型定位（如 rms_norm / attention / moe） grep -RIl "<符号>" "$PYPTO_DEVKIT_DIR/ops/pypto_tensor" # 按 API/符号找哪些实现用到

例如$PYPTO_DEVKIT_DIR/ops/pypto_tensor/<模型>/rms_norm/rms_norm_impl.py；attention / matmul 类算子含BWD/FWD、quant等变体子目录，需按名称定位。

golden / 测试路径为$PYPTO_DEVKIT_DIR/tests/<模型>/（算子子目录可有可无），含*_golden*.py（参考实现）与test_*.py。写 golden 时先在此找同类算子的现成 golden 对照：

grep -RIl --exclude-dir=pypto_pro "<算子名>" "$PYPTO_DEVKIT_DIR/tests"

这套布局与仓库实际目录完全对应：模型目录在 src/pypto_gym/ops/pypto_tensor（如deepseek_v4/、kimi_linear_48b_a3b/、qwen3_1_7b/），测试与 golden 在 tests/ops（如deepseek_v4/test_mla_prolog_v4.py、qwen3_1_7b/rms_norm_rope_golden.py），开发者可直接把缓存中的实现当作"照着写的权威范本"。

典型工作流串联

一个完整的"查 PyPTO 文档"流程可归纳为：

1. 判断入口键：有错误码 → 查 error-code-index.md；知道 API 名 → 查 api-index.md；找教程 → 查 doc-index.md；找实现范本 → 查 sample-index.md；
2. 确认缓存：缓存缺失时先python3 cannbot-skills/ops/pypto-docs-search/scripts/sync_devkit.py装配（本地有工作树则符号链接复用，否则 sparse-checkout 下载）；
3. 按模板检索：用Glob/Grep在docs/、ops/pypto_tensor/、tests/三类范围内按关键词发现，命中后直接Read全文；
4. 兜底：无法装配但文档站可访问时，按索引拿确定路径WebFetch https://pypto.gitcode.com/_sources/<sub>.md.txt；算子参考实现与 golden 无在线形态，必须依赖缓存。

这套"本地纯文件缓存 + 原生搜索工具 + 索引兜底"的组合，让文档检索在离线环境、Agent 自动化场景下同样可靠，是 PyPTO 算子开发链路中稳定可复用的资料入口。

【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym