PyPTO 断裂点识别Fracture Point Detector让 Agent 开发算子会话可复盘、可转化为 Issue 的系统方法【免费下载链接】pyptoPyPTO发音: pai p-t-oParallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto导读本文介绍 CANN / PyPTO 仓库中内置的pypto-fracture-point-detector技能当用户或主 Agent在一个会话session中基于 PyPTO 框架开发算子、运行各类 skill 之后该技能会回顾整个对话历史识别出由框架或文档不完善导致的失败、重试、效率低下等问题点即断裂点并产出一份结构化的 Markdown 报告。通过本文你将掌握断裂点的完整分类体系19 种类型、基于 10 类信号与置信度阈值判定断裂点的检测规则以及将断裂点映射为 GitCode Issue 的标题模板从而把一次模糊的用起来很痛苦的 Agent 会话沉淀为可执行、可追踪、可复现的框架/文档改进清单。一、什么是断裂点从会话复盘到质量归因在 PyPTO 的 Agent 辅助开发流程中用户往往会在一个 session 里调用多个 subagent 完成算子开发例如基于pypto.Tile、pypto.Tensor编写算子再借助 golden 实现做精度比对。当 session 结束时很多卡住的经历——搜索不到文档、按文档写代码却报错、同一个操作反复重试——都散落在对话历史里难以沉淀。pypto-fracture-point-detector技能定义见 .agents/skills/pypto-fracture-point-detector/SKILL.md解决的就是这个问题它把上述现象抽象为四个核心概念断裂点session 中因 PyPTO 框架或文档不完善导致的问题点如搜索失败、反复重试、操作报错实体session 中涉及的 API如pypto.add、文件、概念等对象信号断裂点的可观察表现如搜索失败、反复重试、操作报错置信度断裂点判定的可靠程度低置信度的断裂点会被过滤掉。一个关键的设计原则是根因归属判定断裂点的根因被划分为 PyPTO 框架、PyPTO 文档、PyPTO 样例、Agent 框架、模型能力五类其中前四类是问题计入断裂点总数而模型能力属于非问题不计入总数仅在报告末尾单列。这意味着该技能不仅发现问题还刻意避免把模型自身的错误误报为框架缺陷——这正是它区别于简单日志复盘工具的核心价值。二、使用场景与两种分析模式典型工作流该技能的触发词包括断裂点识别断裂点检测断裂点fracture point也适用于用户对 session 中遇到的问题进行复盘、生成问题报告、或希望改进 PyPTO 框架/文档质量。典型流程为用户在 session 中开发 PyPTO 算子可能调用多个 subagent开发完成后用户说识别断裂点或生成断裂点报告skill 分析当前 session默认或当前 session 及其所有子会话scopefullskill 输出断裂点报告。两种分析模式模式分析范围数据来源scopecurrent默认仅当前 sessionLLM 直接回顾对话历史scopefull当前 session 所有子会话SQLite 数据库查询scopecurrent模式实现最简单LLM 直接基于当前对话上下文做回顾无需访问外部存储。scopefull模式则依赖 opencode 框架的 SQLite 数据库实现默认路径为~/.local/share/opencode/opencode.db可通过环境变量OPENCODE_DB_PATH覆盖因此在其他 agent 框架下该能力可能不可用或需要重新实现数据访问层此时应退回scopecurrent模式。三、完整工作流程从确定模式到生成报告技能规定按步骤 010 顺序执行默认使用scopecurrent模式。整体分为模式确定步骤 0与核心分析步骤 1-10两大阶段。步骤 0确定分析模式无参数或scopecurrent默认只分析当前 session跳过步骤 0.1-0.3直接进入核心分析步骤scopefull获取当前 session 及其所有子会话的原始数据执行步骤 0.1-0.3。步骤 0.1 获取当前 Session ID调用scripts/session_db.py提供的函数from scripts.session_db import get_current_session_id, get_session_title current_session_id get_current_session_id() current_session_title get_session_title(current_session_id)从实现看.agents/skills/pypto-fracture-point-detector/scripts/session_db.pyget_current_session_id通过查询 SQLite 中parent_id IS NULL且time_updated最近的一条根会话记录来推断当前 session即最近活跃推断策略。步骤 0.2 确认 Session 正确性如果推断出的 session 标题与当前对话内容匹配继续执行否则调用list_recent_root_sessions(limit10)列出最近的根会话根据当前对话内容判断正确的 session。仅在无法确定时才需要用户确认。步骤 0.3 获取子会话数据from scripts.session_db import get_child_sessions, get_session_parts # 获取子会话列表 children get_child_sessions(current_session_id) # 获取每个子会话数据 child_parts [get_session_parts(c.id) for c in children]主 session 数据直接回顾当前对话历史即可对每个会话执行核心分析步骤 1-8然后汇总到步骤 5。get_session_parts会按part表的type字段将数据归类为 tool 调用含状态、输入、输出、错误、文本消息按message.role区分 user/assistant、推理过程、step 标记等为后续信号检测提供结构化数据源。步骤 1读取各个 Session 上下文读取 session 的完整对话历史重点关注工具调用及其返回结果尤其是错误和空结果用户消息中的修正、澄清、不满表达搜索/读取操作的频次和模式任务是否最终完成。成功标准完成回顾后应能列出 session 中涉及的所有关键实体和操作。步骤 2实体识别从对话历史中识别所有涉及的 PyPTO 实体识别模式见 references/entity-patterns.md主要包括三类API匹配pypto\.[a-zA-Z_][a-zA-Z0-9_]*模式的 API 调用如pypto.add、pypto.matmul、pypto.Tile、pypto.compile同一 API 的不同调用形式视为同一实体文件匹配.py、.md、.json等扩展名的路径只关注与 PyPTO 相关的文件路径含pypto、operator、golden、docs等关键词排除通用工具文件概念tile、tensor、pass、codegen、ub、gm、l1、tiling、schedule、operator、golden、ascend、cann、npu、aiv/aic、dtype、shape、broadcast、reduce、workspace、kernel 等预定义关键词。概念实体只有在 session 中围绕该概念出现问题时才算作实体单纯提及不算。为每个实体确定复杂度等级简单/中等/复杂规则见 references/entity-complexity.md。步骤 3信号检测按实体聚合逐一检测 10 类信号每个信号对应一个或多个断裂点类型检测规则和阈值见 references/detection-rules.md。关键信号包括搜索失败搜索返回空或未找到 → D1, D5操作失败工具调用返回 Error/Exception/Failed → A1, A2, E1, E2重复操作同一实体上相同操作出现 ≥3 次简单实体 → C1过度探索搜索/读取次数超过阈值 → C4用户介入用户消息中包含修正或手动指导 → C6任务未完成session 最终未达到预期目标 → C5。阈值会根据实体复杂度加权调整复杂实体的阈值更宽松。步骤 4断裂点判定将检测到的信号匹配到 19 种断裂点类型并评估置信度。置信度评估基于 4 个条件有明确错误信息Error/Exception/Failed多个信号佐证≥2 个信号触发同一断裂点证据完整能清晰复现问题用户明确反馈表达困惑或不满。判定规则满足 ≥2 个条件 → 高置信度 → 输出满足 1 个条件 → 中置信度 → 输出不满足任何条件 → 低置信度 →剔除。步骤 5去重与合并同一实体 同一断裂点类型 同一个断裂点合并所有触发的信号和证据片段。scopefull模式下还需合并所有 session主 子的断裂点并为每个断裂点标记来源 session主 Session或子 Session-{short_id}。步骤 6二次校验根因归属判定目的排除因模型自身原因导致的误报确保断裂点根因确实归属于框架或文档。对去重后的候选断裂点必须实际读取相关文档后执行两项检查详见 references/detection-rules.md 中二次校验规则章节检查 1信息是否已存在于 skill 参考文档中——若答案已存在且模型已被告知流程要求读取该文件标记为模型能力-未遵循流程若答案已存在但模型未被告知保留断裂点并标记文档可读性建议若答案不存在保留断裂点检查 2文档信息是否实际完整——若文档实际存在或信息完整但模型搜索不当/未交叉引用/理解错误标记为模型能力-{具体原因}若文档确实缺少关键信息保留断裂点。检查结果处理根因归属 PyPTO 框架 / PyPTO 文档 / PyPTO 样例 / Agent 框架 → 计入断裂点总数输出到报告正文根因归属模型自身 → 标记为模型能力在报告末尾单独列出不计入断裂点总数。步骤 7关联标记相同实体的不同断裂点自动标记为关联。例如pypto.reshape同时有 D1文档缺失和 C1反复重试它们互相关联并在每个断裂点详情的可能关联字段中标注。步骤 8置信度过滤剔除所有低置信度的断裂点只有中/高置信度的断裂点进入最终报告。步骤 9环境信息获取执行以下命令获取环境信息任何命令失败则对应字段标记为未知不影响报告生成信息命令CANN 版本echo $ASCEND_HOME_PATH \| grep -oP cann-\K[\d.]PyPTO Commitgit merge-base HEAD origin/master 2/dev/null git log -1 --format%H %ci $(git merge-base HEAD origin/master) \|\| echo Unknown服务器类型lspci -n -D \| grep 19e5:d80[23] \| sed s/.*d80\([23]\).*/A\1/ 2/dev/null \|\| echo UnknownPython 版本python --version 2/dev/null \|\| echo Unknown操作系统cat /etc/os-release 2/dev/null \| grep PRETTY_NAME \|\| echo Unknown环境信息用于帮助 Issue 阅读者复现问题CANN 版本、PyPTO commit、服务器类型等都与算子行为强相关。步骤 10报告生成有断裂点的情况使用 templates/report-template.md 中的模板生成报告文件名fracture-point-YYYY-MM-DD-HHMMSS.md保存到当前工作目录断裂点按优先级排序致命 高 中每个断裂点包含类型、优先级、根因归属、Issue 建议、证据片段、优化建议Issue 类型映射和标题模板见 references/issue-mapping.mdscopefull模式下报告包含子会话分析概览章节每个断裂点标记来源 session。无断裂点的情况不生成报告文件在屏幕直接输出摘要——session 基本信息、操作统计、涉及实体列表、未检测到断裂点提示。四、19 种断裂点类型全解断裂点共 19 种类型分为 3 个优先级、4 个类别文档类 D1-D3/D5-D6、API/框架类 A1-A5、错误信息类 E1-E4、行为模式类 C1-C2/C4-C6、2 个层级实体级与 Session 级完整定义见 references/fracture-points.md。致命优先级9 个直接导致任务失败必须修复文档类根因归属文档类型名称信号描述典型表现D1文档缺失搜索某个 API/概念但找不到任何文档Grep/Glob 搜索返回空结果Read 找不到对应文件D3文档误导按文档操作失败文档与实际行为不一致按文档说明编写代码运行时报错或结果不符D6示例无效文档中的示例代码无法运行或报错复制示例代码运行后报 ImportError、AttributeError 等API/框架类根因归属框架类型名称信号描述典型表现A1API 不存在调用某个 API 但返回未定义或不存在AttributeError: module pypto has no attribute xxxA2API 行为异常API 返回结果与预期严重不符API 执行成功但输出数据错误或静默返回错误结果错误信息类根因归属框架类型名称信号描述典型表现E1错误信息缺失操作失败但没有任何错误提示程序静默失败、返回空结果、或挂起无响应E2错误信息模糊错误信息太笼统无法定位问题Error: internal error、Failed、Unknown error occurredE3错误信息误导错误信息指向错误的原因报 shape mismatch 但实际是 dtype 不支持Session 级根因归属两者类型名称信号描述典型表现C5意外中断任务在某个点停止未达到预期目标session 结束时任务未完成用户表达不满高优先级8 个严重影响效率或成功率应优先修复类型名称根因归属信号描述典型表现D2文档不完整文档找到文档但缺少关键信息参数、返回值、示例文档存在但信息不全需要额外搜索或试错D5示例缺失文档需要代码示例但只有文字描述文档只有 API 签名和文字说明没有可运行的代码示例E4错误信息无建议框架错误信息只说失败但不说如何修复错误信息缺少修复提示、文档链接或可能的原因C1反复重试两者同一操作被重复尝试多次相同或高度相似的工具调用在 session 中反复出现C4过度探索两者为完成简单任务进行了大量搜索和读取围绕同一实体的 Grep/Glob/Read 操作数量远超正常水平C6用户介入两者Session 级需要用户多次手动干预才能继续用户多次提供修正信息、手动指导操作方向A3参数限制框架某些合理的参数组合不被支持合理的参数组合报错需要 workaroundA5边界未定义框架某些边界条件行为未定义或崩溃特殊输入空 tensor、极大维度等导致崩溃中优先级2 个有一定影响建议修复类型名称根因归属信号描述典型表现A4类型不匹配框架类型转换失败、shape 不匹配等dtype 或 shape 相关的错误C2路径摇摆两者在多个方案间反复切换无法决策尝试方案 A → 放弃 → 尝试方案 B → 放弃 → 回到方案 A层级分类层级断裂点类型说明实体级D1-D6, A1-A5, E1-E4, C1, C2, C4针对特定实体的问题Session 级C5, C6整个 session 级别的问题从该分类体系可以看出实体级断裂点覆盖了文档找不到 → 文档不全 → 文档错误 → API 不存在 → API 行为异常 → 报错不可用的完整链路而 Session 级断裂点则关注任务整体是否完成、是否需要用户反复介入。五、10 类信号与检测规则详解检测规则文件 references/detection-rules.md 定义了 10 类信号每类信号有明确的检测规则和对应断裂点类型。信号 1搜索失败检测规则搜索操作Grep、Glob、WebSearch返回空结果或结果中包含未找到、不存在、no results、not found对应断裂点D1文档缺失、D5示例缺失区分方式搜索文档/API 说明返回空 → D1搜索代码示例/用法返回空 → D5。信号 2操作失败检测规则工具调用特别是 Bash返回错误输出中包含Error、Exception、Failed、Traceback、fatal对应断裂点A1API 不存在、A2API 行为异常、E1错误信息缺失、E2错误信息模糊区分方式AttributeError: module pypto has no attribute→ A1API 执行但结果明显错误 → A2操作失败但无错误输出 → E1操作返回空输出或无输出期望有输出的场景→ E1错误信息过于笼统如 internal error、failed→ E2。信号 3重复操作检测规则同一实体上相同类型的操作相同工具 相似参数在 session 中重复出现对应断裂点C1反复重试阈值按实体复杂度加权见阈值表。信号 4过度探索检测规则同一实体上的搜索Grep/Glob或读取Read操作数量超过阈值对应断裂点C4过度探索阈值按实体复杂度加权见阈值表。信号 5错误关键词检测规则错误信息中包含特定模式对应断裂点E2错误信息模糊、E3错误信息误导、E4错误信息无建议区分方式错误信息过短20 字符或只有错误码 → E2按错误信息排查后发现真实原因不同 → E3错误信息没有包含任何修复建议、文档链接、可能的原因列表 → E4。信号 6用户介入检测规则用户消息中包含修正性内容如应该用 xxx、正确的写法是、不是这样、不对、你搞错了、试试 xxx、去看 xxx 文件对应断裂点C6用户介入。信号 7任务未完成检测规则session 最后状态显示任务未达到预期目标如用户明确表达不满或放弃算了、不行、太慢了或任务目标未达成operator 没有编译通过、测试没有通过对应断裂点C5意外中断。信号 8文档问题检测规则先搜索/读取了文档然后按文档操作但仍然失败对应断裂点D2文档不完整、D3文档误导、D6示例无效区分方式找到文档但信息不全需要额外搜索 → D2按文档操作但结果与文档描述不一致 → D3运行文档中的示例代码但报错 → D6。信号 9类型/参数问题检测规则错误信息中包含type、shape、dimension、dtype、parameter、argument、unsupported对应断裂点A3参数限制、A4类型不匹配、A5边界未定义区分方式合理的参数组合不被支持 → A3dtype/shape 转换或匹配失败 → A4边界值0、空、极大导致异常 → A5。信号 10路径摇摆检测规则在多个实现方案间反复切换 ≥2 次尝试方案 A → 遇到问题 → 切换方案 B → 遇到问题 → 回到方案 A对应断裂点C2路径摇摆。六、检测阈值按实体复杂度加权阈值按实体复杂度加权实体复杂度根据 golden 接口的 torch 主操作数个数确定见 references/entity-complexity.md参数简单≤ 8 个操作中等9-20 个操作复杂21 个操作重复操作阈值≥3 次≥5 次≥6 次过度探索-搜索10 次15 次20 次过度探索-读取15 次22 次30 次什么是torch 主操作指 golden 函数体中直接调用的torch.*函数不计算以下内容torch.tensor()等纯构造函数.shape、.dtype等属性访问.to()、.contiguous()等类型/内存转换Python 控制流语句。复杂度判定方式如果 session 中涉及的实体是 PyPTO API/算子查看其 golden 接口中使用了多少个 torch 主操作来实现等价功能如果无法确定如概念实体、文件实体默认按简单处理如果 session 上下文中有明确的 golden 实现代码直接计数 torch 操作数。复杂度阈值倍数分别为简单 x1.0、中等 x1.5、复杂 x2.0。对于无法确定复杂度的实体如概念类实体默认使用简单实体的阈值。这一设计避免了复杂算子的调试过程天然更长被误报为反复重试/过度探索。七、置信度评估如何避免误报置信度评估在步骤 4 中执行基于 4 个条件编号条件说明C1有明确错误信息session 中出现 Error/Exception/Failed/Traceback 等明确错误C2多个信号佐证同一断裂点被 ≥2 个不同信号触发C3证据完整能从证据片段中清晰复现问题的完整过程C4用户明确反馈用户在 session 中明确表达了困惑、不满、或指出问题置信度判定置信度条件处理高满足 ≥2 个条件输出到报告中满足 1 个条件输出到报告低不满足任何条件剔除不输出去重与合并规则为同一实体 同一断裂点类型 同一个断裂点合并所有触发的信号与证据片段信号数量作为置信度评估的辅助依据。关联标记规则为相同实体的不同断裂点自动标记为关联在每个断裂点详情中标注可能关联字段列出同一实体的其他断裂点编号和类型。八、Issue 映射从断裂点到可执行的 GitCode Issue断裂点识别的最终产物是可转化为 Issue 的结构化报告。类型到 GitCode Issue 的映射关系见 references/issue-mapping.md如下断裂点类型Issue 类型标签D1, D2, D5DocumentationdocumentationD3, D6Bug Reportbug,documentationA1, A2, A4, A5Bug ReportbugA3Feature RequestenhancementE1, E2, E3, E4Bug ReportbugC1, C2, C4Bug Report 或 Feature Request视具体情况判断C5, C6Bug Report 或 Feature Request视具体情况判断C 类断裂点的 Issue 类型判定如果根因明确指向框架 bug如 API 返回错误导致重试→ Bug Report如果根因指向缺少功能或文档如没有示例导致过度探索→ Feature Request 或 Documentation如果根因不明确 → Bug Report默认。Issue 标题模板断裂点类型标题模板D1[Doc] {实体名} 文档缺失D2[Doc] {实体名} 文档不完整{缺失内容}D3[Doc] {实体名} 文档与实际行为不一致D5[Doc] {实体名} 缺少代码示例D6[Doc] {实体名} 示例代码无法运行A1[Bug] {实体名} API 不存在A2[Bug] {实体名} API 行为异常A3[Feature] {实体名} 参数限制{具体限制}A4[Bug] {实体名} 类型不匹配A5[Bug] {实体名} 边界行为未定义E1[Bug] {实体名} 操作失败无错误提示E2[Bug] {实体名} 错误信息模糊E3[Bug] {实体名} 错误信息误导E4[Bug] {实体名} 错误信息无修复建议C1[Bug] {实体名} 导致反复重试C2[Bug] {实体名} 信息不足导致决策困难C4[Bug] {实体名} 信息分散导致过度探索C5[Bug] Session 意外中断C6[Bug] Session 需要用户介入模板使用说明{实体名}替换为具体实体名称如pypto.reshape、pypto.Tile{缺失内容}替换为具体缺失的信息类型如参数说明、返回值类型{具体限制}替换为具体的参数限制描述如不支持 float16 输入Session 级断裂点C5、C6的标题不包含实体名。九、报告结构让不了解上下文的人也能看懂报告模板见 templates/report-template.md结构如下摘要会话时间、检测时间、断裂点总数、按优先级分布致命/高/中、按根因归属分布文档/框架/两者、按 Issue 类型分布Bug Report/Documentation/Feature Request环境信息CANN 版本、PyPTO Commit、服务器类型、Python 版本、操作系统子会话分析概览仅scopefull分析模式、子会话总数、子会话断裂点总数、每个子会话的断裂点分布表按创建时间排序优先修复列表优先级、编号、类型、实体、来源 Session、Issue 类型、置信度按优先级排序致命 高 中同优先级内按置信度排序高 中Session 级断裂点如无 C5、C6 则省略每个断裂点含类型、优先级、根因归属、Issue 类型、建议 Issue 标题、置信度、问题描述、证据片段、优化建议实体级断裂点详情每个断裂点含类型、优先级、根因归属、Issue 类型、建议 Issue 标题、置信度、来源 Session、可能关联以及问题描述、证据片段、复现步骤、期望行为、实际行为、相关链接、优化建议。报告质量有明确要求证据片段必须是 session 中的原文引用不要编造或概括每个断裂点的问题描述应清晰到能让不了解 session 上下文的人理解发生了什么优化建议要具体、可操作指向具体的文件或 API。十、仓库佐证断裂点涉及的实体在 PyPTO 中真实存在该技能分析的实体并非虚构而是 PyPTO 框架中的真实 API。例如pypto.add定义于 python/pypto/op/math.py#L61def add(input_tensor: Tensor, other: Union[Tensor, float, int]) - Tensor支持张量与张量/标量相加是典型的简单实体golden 通常只需 1 个torch.add操作pypto.matmul定义于 python/pypto/op/matmul.py#L23def matmul(input, mat2, out_dtype, *, a_transFalse, b_transFalse, c_matrix_nzFalse, extend_paramsNone) - Tensor参数较多且支持转置等选项其 golden 实现通常涉及 10 个 torch 调用属于中等实体——这也解释了为何检测阈值按复杂度加权pypto.reshape定义于 python/pypto/operation.py#L183Tensor类定义于 python/pypto/tensor.py#L61。从源码结构看该技能所引用的实体识别模式pypto\.[a-zA-Z_][a-zA-Z0-9_]*与 PyPTO 的公开 API 命名完全一致python/pypto/op/目录下按功能组织的math.py、matmul.py、conv.py、convbp.py、reduction.py等模块正是断裂点报告中实体名最常见的来源。十一、使用注意事项与最佳实践技能文档明确列出以下使用约束对实际运行至关重要证据片段必须是 session 原文引用不要编造或概括Session 级断裂点C5、C6不针对特定实体单独列为一个章节scopefull模式使用最近活跃推断策略获取当前 session ID在多 session 同时活跃时可能不准确报告中需说明此限制分析子会话时完整读取用户消息、助手回复、推理过程和工具调用链二次校验步骤 6必须执行验证根因是否确实归属于框架或文档断裂点分类包含 PyPTO 框架、PyPTO 文档、PyPTO 样例、Agent 框架、模型能力五类前四类是问题模型能力是非问题不应计入断裂点总数子会话数据获取依赖 opencode 框架的 SQLite 数据库实现scripts/session_db.py默认路径~/.local/share/opencode/opencode.db可通过OPENCODE_DB_PATH覆盖在其他 agent 框架下此功能可能不可用应使用scopecurrent模式。从实践角度看该技能的价值在于形成闭环Agent 开发算子的 session 不再是一次性的、无法复盘的过程而是可以系统性地产出哪里让使用者困惑、哪里文档缺失、哪里 API 行为不符合预期的结构化反馈。这既帮助 PyPTO 维护者以用户真实痛点驱动文档与框架改进也帮助开发者在下一次 session 中避开已知的坑——每次断裂点报告都是 PyPTO 框架与文档质量持续演进的一份可执行清单。【免费下载链接】pyptoPyPTO发音: pai p-t-oParallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考