PyPTO-Pro 编程指南索引 doc-index主题导航、检索边界与本地文档缓存装配【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym导读本文以 doc-index.md 为核心系统讲解 PyPTO-Pro 编程指南的主题式导航方式如何把我想学 Kernel 函数 / Tiling / 调试这类主题翻译成$PYPTO_DEVKIT_DIR/docs/下的具体缓存路径如何限定关键词检索范围以及这套本地文档缓存devkit是如何由 sync_devkit.py 装配、校验并被 PyPTO-Pro 五阶段算子开发工作流复用的。读完本文你将掌握 Pro 指南资料的主题索引表、检索边界规则、缓存装配命令与退出码语义并能在缓存缺失时正确报告缺项而不是编造路径。一、doc-index 在 Pro 资料体系中的定位PyPTO-Pro 工作流把上游文档缓存到本地$PYPTO_DEVKIT_DIR并配套三份互补的检索索引索引回答的问题文档位置doc-index本文编程指南 / 快速入门 / 调试调优按主题导航references/doc-index.mdapi-indexAPI 名称 / 功能类别按类别定位签名与约束references/api-index.mdsample-index官方指定算子样例找参考实现references/sample-index.mddoc-index 是主题级导航表它不枚举每一个文件而是把用户常见的编程诉求编程范式、Kernel 函数、Tile 编程、编译执行、调试调优、快速入门映射到缓存中的目录入口。它遵守一条关键原则见 SKILL.md 的边界说明本索引用于按主题发现、跨文件定位已确定确切路径时直接读取即可。同时该 skill 明确不用于普通 PyPTO 文档与算子仓检索即只服务 Pro 侧资料。二、主题 → 路径对照表核心骨架doc-index 给出的导航表如下路径均相对$PYPTO_DEVKIT_DIR/docs/且下表使用上游当前guide路径各分区的全部条目以其index.md为准主题路径PyPTO 共享简介guide/introduction.md编程指南总览guide/programming_guide/pro/index.md编程范式与抽象硬件架构guide/programming_guide/pro/programming_paradigm/index.mdKernel 函数guide/programming_guide/pro/development/kernel_function.mdTile / Reg / Cube 编程、Tiling 与尾块处理guide/programming_guide/pro/development/tile_based_python_programming/index.mdJIT 与离线编译guide/programming_guide/pro/development/compilation_and_execution/index.md高级编程与自动流水并行guide/programming_guide/pro/advanced_programming/index.md功能调试与性能调优guide/programming_guide/pro/debug/index.md快速入门SIMD / SIMT 样例guide/quick_start/pro/index.md使用要点总览入口先读index.mdguide/programming_guide/pro/index.md与guide/quick_start/pro/index.md是两级入口doc-index 只负责把主题带到分区根分区内部的完整条目清单以各分区自己的index.md为准。快速入门按版本变化文档明确指出从快速入门总索引读取当前版本的样例页面路径不同版本可能采用子目录或同级文件布局。因此在 quick start 下不要硬编码深层路径而应先读guide/quick_start/pro/index.md再沿其链接进入当前版本布局。简介是共享的guide/introduction.md是 PyPTO Tensor 与 Pro 共享的简介文件SKILL.md 明确简介使用共享的introduction.md。三、关键词检索的三段限定范围doc-index 对按关键词补充发现规定了严格的检索范围这是防止幻觉与越界引用的核心约束按关键词补充发现时仅检索guide/programming_guide/pro/、guide/quick_start/pro/和guide/introduction.md。也就是说缓存里虽然存在完整文档树但关键词检索不允许扩大到整个docs/guide/。其背后有两层原因缓存本身就有意排除了 Tensor 侧sync_devkit.py装配时不下载api/tensor_api、guide/programming_guide/tensor、guide/quick_start/tensor等目录详见下文第六节因此缓存中不存在普通 PyPTO / Tensor指南检索范围收窄是自然的。检索与导航分工PRO_MATERIAL_INDEX.md§C 覆盖上述三个范围的全部 Markdown 文件含各级index.md是完整清单而 doc-index 这张表用于主题导航不替代 §C 的完整清单。实际工作流中pypto-pro-material-explore 用 build_material_index.py 从同一缓存生成PRO_MATERIAL_INDEX.md模板见 pro_material_index.md其 §C 章节的来源正是programming_guide/pro/**/*.md、quick_start/pro/**/*.md与introduction.md三个范围与 doc-index 的限定完全一致。四、缓存内容与排除项什么在、什么不在缓存根由$PYPTO_DEVKIT_DIR指定默认当前项目的.devkit/内部结构如下见 SKILL.md子目录内容docs/Pro API、编程指南、快速入门、共享简介及配套图片pro_ops/官方指定算子样例仅装配统一样例清单内文件入口见 sample-index.md缓存不包含的内容是明确列举的Tensor API / Tensor 专属指南目录api/tensor_api、guide/programming_guide/tensor、guide/quick_start/tensor等docs/install/安装文档普通 PyPTO 算子与测试pro_ops/只装官方样例清单内的文件不另设普通 PyPTO 的ops/、tests/目录。此外 doc-index 还提示两点资源特性配套图片随缓存保留guide/figures/pro/在装配的DOC_PATHS中未被缓存的安装与通用配置页面由指南正文中的远端链接指向装配时自动改写见第六节。当前缓存不含独立的错误码排障资料报错时应从guide/programming_guide/pro/debug/index.md功能调试与性能调优定位并结合实际日志排查而不是期望缓存里有一份独立错误码表。五、缓存装配命令、环境变量与退出码5.1 首次装配 / 更新在项目根目录执行命令取自 SKILL.mdexport PYPTO_DEVKIT_DIR$(pwd)/.devkit CANNBOT_ROOT$CANNBOT_CONFIG_ROOT python $CANNBOT_ROOT/skills/pypto-pro-docs-search/scripts/sync_devkit.py \ --samples $CANNBOT_ROOT/skills/pypto-pro-material-explore/references/official_samples.md要点已安装资源根由init.sh渲染的$CANNBOT_CONFIG_ROOT提供--samples指向 official_samples.md——它是整个工作流的统一官方样例清单当前含 add、matmul 系列、FlashAttention 系列、VF LayerNorm/Softmax 等 13 个样例脚本会从清单中提取所有pro_ops/...py路径并按名装配清单之外的样例文件不写入缓存正常装配按清单复制样例并校验结果无需手动清理pro_ops/。5.2 只校验不装配--check在同一调用末尾追加--check即进入只读校验模式不联网、不修改文件输出退出码含义READY0缓存就绪可直接检索NEED_PROVISION4缓存缺失或不完整需要装配5.3 环境变量与参数语义变量 / 参数作用默认值PYPTO_DEVKIT_DIR缓存目录cwd/.devkitPYPTO_SRC指定已有 PyPTO 工作树本地模式自动向上查找含docs/zh/api/pro_api的目录PYPTO_SRC_URL覆盖远端源上游pypto.git仓库git clone 场景--pin git-ref从远端获取指定版本不修改已有工作树不固定取远端 HEAD--check仅校验缓存关闭装配成功后脚本在缓存根写入MANIFEST.json和就绪标记.pro-docs-v2记录kind、layout、modelocal/download、source、revision、docs与samples清单以便核对缓存来源与版本——以目标运行环境对应的资料为准。5.4 子代理路径传递规则在 Pro 工作流中装配由 orchestrator 在会话开始时执行一次并向所有子代理传递同一缓存的绝对路径。子代理检索时PYPTO_DEVKIT_DIR缓存绝对路径 CANNBOT_CONFIG_ROOT资源根绝对路径 python 脚本绝对路径即仅将给定的两个路径原样传入单条命令不使用export、不猜测或更换路径、不设置其他环境变量未收到路径时返回env_error交回编排器见 SKILL.md 与 orchestration.md。六、装配脚本实现原理源码级sync_devkit.py 是一个不依赖普通 PyPTO 同步器的独立脚本其关键机制6.1 装配清单常量DOC_PATHS ( api/pro_api, guide/programming_guide/pro, guide/quick_start/pro, guide/introduction.md, guide/figures/pro, ) FRONTEND python/tests/st/pypto_pro/frontend下载模式git clone --depth 1 --filterblob:none --no-checkout后用sparse-checkout非 cone 模式只检出docs/zh/下DOC_PATHS对应路径及FRONTEND下的样例源文件最大程度减小缓存体积本地模式local_source()优先取PYPTO_SRC否则在 cwd 及其父目录中查找含docs/zh/api/pro_api的 PyPTO 工作树require_docs()是装配前置校验必须存在api/pro_api/index.md、guide/programming_guide/pro/index.md、guide/quick_start/pro/index.md与guide/introduction.md否则直接失败。6.2 兼容副本与外部链接改写compatibility_api()把docs/api/pro_api/整体复制为docs/pypto_pro/api/并生成docs/api/index.md跳转页保证新旧两种 API 路径均可检索api-index 中docs/api/pro_api/与docs/pypto_pro/api/保留同一份上游 API 原文即源于此装配末尾只改写指南中明确指向未缓存资料的相对链接install/prepare_environment.md与api/tensor_api/config/pypto-set_{host,pass,codegen,verify,debug}_options.md会被替换为指向装配时固定 revision的远端 blob 链接代码块、图片和 Pro 内部链接原样保留。6.3 就绪判定ready()--check与装配末尾都会调用ready()判定条件包括就绪标记.pro-docs-v2与MANIFEST.json均存在四个必需文档入口齐全且docs/pypto_pro/api/index.md存在不存在任何排除目录install、contribute、invocation、api/tensor_api、guide/programming_guide/tensor、guide/quick_start/tensor、pypto_pro/tutorials——一旦混入即视为不合法缓存pro_ops/下的全部.py文件集合与官方样例清单精确相等文件名、数量都必须一致。这一白名单 黑名单双重校验保证了 doc-index 检索时的三个限定范围在物理上就是缓存内容的全部。七、测试用例固化的行为契约test_sync_devkit.py 用本地 source fixture 覆盖了缓存行为的全部关键边界可作为理解装配语义的权威参考测试验证的行为test_provision_is_standalone_and_preserves_only_pro_resources独立装配不修改源工作树缓存不产生符号链接Tensor/install/contribute 目录不存在必需入口齐全--check返回READY且退出码 0删除任一指南根索引后--check转为未就绪test_missing_sample_never_marks_new_cache_ready清单中任一样例源缺失 → 退出码 4不写就绪标记test_failed_refresh_preserves_existing_docs_and_samples刷新失败时保留既有 docs 与 pro_ops不出现半新半旧状态test_check_rejects_wrong_names_even_when_counts_match样例数量相同但文件名不匹配大小写、清单外替换→ 判未就绪test_invalid_explicit_source_does_not_fall_back_to_downloadPYPTO_SRC无效时不静默回退到远端下载而是失败test_cache_cannot_replace_local_source缓存目录不得覆盖源资料目录防误删源test_pinned_download_with_empty_git_template--pin固定版本下载在空 git 模板下也正常工作这些测试与 doc-index不编造路径、缓存缺失时报告缺项的原则互相印证缓存必须是确定性的、可校验的检索不得越出缓存范围。八、在 PyPTO-Pro 工作流中的协作角色doc-index 并非孤立文档它在五阶段算子开发流程中承担指南导航职责会话开始时装配一次orchestrator 按 orchestration.md 在调度 Stage 1 前完成缓存准备只做装配和校验不检索随后 pypto-pro-material-explore 扫描同一缓存生成PRO_MATERIAL_INDEX.md§C 即 doc-index 三个范围的完整清单。子代理只检索不装配所有子代理按子代理路径传递规则复用同一缓存绝对路径缓存未就绪NEED_PROVISION或发现缺项时报告具体缺项并交回 orchestrator 处理子代理不自行同步、不切换缓存、不改用普通 PyPTO 同步器或在线索引。离线约束离线无法装配时如实报告缺项不编造路径或索引——这正是 doc-index 反复强调以缓存中的索引为准以实际日志定位的原因。九、常见问题Q1--check返回NEED_PROVISION怎么办说明缓存未装配或已失效按第五节命令重新装配装配失败时脚本会打印具体缺失路径与原始错误退出码 4据此修复源或网络后重试。Q2想查某个 API 的签名该用哪份索引API 名称与签名属于 api-index.md 的范围在$PYPTO_DEVKIT_DIR/docs/pypto_pro/api/下按*API名*.md递归查找并读全文doc-index 只负责编程范式、Tiling、调试这类主题导航。Q3需要参考官方算子实现走 sample-index.md以 official_samples.md 为唯一清单在$PYPTO_DEVKIT_DIR/pro_ops/中按关键词或 API 调用定位且只读取清单内文件。Q4报错想查错误码当前缓存不含独立错误码排障资料应回到guide/programming_guide/pro/debug/index.md功能调试与性能调优结合实际日志定位这符合 doc-index 对缓存边界的如实说明。【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考