| name | pypto-fracture-point-detector |
| description | 分析当前 session 上下文，识别 PyPTO 框架或文档不完善导致的断裂点，产出可转化为 Issue 的结构化报告。当用户在 pypto 相关 skill 运行结束后提到"断裂点"、"识别断裂点"、"检测断裂点"、"fracture point"时触发此 skill。也适用于用户对 session 中遇到的问题进行复盘、想要生成问题报告、或希望改进 pypto 框架/文档质量的场景。 |
PyPTO 断裂点识别
分析当前 session 的对话历史，识别由 PyPTO 框架或文档不完善导致的"断裂点"——即 skill 运行过程中的失败、重试、效率低下等问题——并产出结构化的 Markdown 报告。
核心概念
- 断裂点：session 中因 pypto 框架或文档不完善导致的问题点
- 实体：session 中涉及的 API（如
pypto.add）、文件、概念等对象
- 信号：断裂点的可观察表现（如搜索失败、反复重试、操作报错）
- 置信度：断裂点判定的可靠程度，低置信度的断裂点会被过滤掉
共 19 种断裂点类型，分为文档类（D1-D3, D5-D6）、API/框架类（A1-A5）、错误信息类（E1-E4）、行为模式类（C1-C2, C4-C6）。完整定义见 references/fracture-points.md。
使用场景
典型场景：用户在主 agent 会话中调用此 skill，分析当前会话。
用户工作流程：
1. 用户在 session 中开发 PyPTO 算子（可能调用多个 subagent）
2. 开发完成后，用户说："识别断裂点"或"生成断裂点报告"
3. skill 分析当前 session（默认）或当前 session 及其所有子会话（scope=full）
4. skill 输出断裂点报告
两种分析模式：
| 模式 | 分析范围 | 数据来源 |
|---|
scope=current（默认） | 仅当前 session | LLM 直接回顾对话历史 |
scope=full | 当前 session + 所有子会话 | SQLite 数据库查询 |
工作流程
按以下步骤顺序执行。默认使用 scope=current 模式。
步骤 0：确定分析模式
根据参数确定分析范围：
- 无参数或
scope=current（默认）：只分析当前 session，跳过步骤 0.1-0.3，直接进入核心分析步骤
scope=full：获取当前 session 及其所有子会话的原始数据，执行步骤 0.1-0.3
子会话数据获取（scope=full）
重要说明：子会话数据获取功能依赖于 opencode 框架的特定实现（SQLite 数据库）。在其他 agent 框架下，此功能可能不可用或需要重新实现数据访问层。若当前环境不支持数据库访问，应使用 scope=current 模式。
当使用 scope=full 时，通过 opencode 的 SQLite 数据库读取会话数据。默认路径为 ~/.local/share/opencode/opencode.db，可通过环境变量 OPENCODE_DB_PATH 覆盖。
步骤 0.1：获取当前 Session ID
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)
步骤 0.2：确认 Session 正确性
情况 A：推断的 session 标题与当前对话内容匹配
继续执行。
情况 B：推断的 session 标题与当前对话内容不匹配
from scripts.session_db import list_recent_root_sessions
recent_sessions = list_recent_root_sessions(limit=10)
仅在无法确定时才需要用户确认。
步骤 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。
核心分析步骤（步骤 1-10）
以下步骤为两种模式共用，用于分析单个 session：
步骤 1：读取各个 Session（主session + 子Session） 上下文
读取 session 的完整对话历史，重点关注：
- 工具调用及其返回结果（尤其是错误和空结果）
- 用户消息中的修正、澄清、不满表达
- 搜索/读取操作的频次和模式
- 任务是否最终完成
成功标准：完成回顾后，应能列出 session 中涉及的所有关键实体和操作。
步骤 2：实体识别
从对话历史中识别所有涉及的 pypto 实体。识别模式见 references/entity-patterns.md，主要包括：
- API：匹配
pypto.xxx 模式的 API 调用
- 文件：涉及的
.py、.md 等文件路径
- 概念：tile、tensor、pass、codegen、ub、gm 等框架概念
为每个实体确定复杂度等级（简单/中等/复杂），规则见 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：去重与合并
同一实体 + 同一断裂点类型 = 同一个断裂点。合并所有触发的信号和证据片段。
scope=full 模式：合并所有 session（主 + 子）的断裂点，为每个断裂点标记来源 session（"主 Session" 或 "子 Session-{short_id}"）。
步骤 6：二次校验（根因归属判定）
目的：排除因模型自身原因导致的误报，确保断裂点根因确实归属于框架或文档。
对去重后的候选断裂点，必须实际读取相关文档后执行检查。具体检查项和判定规则见 references/detection-rules.md 中的"二次校验规则"章节。
检查结果处理：
- 根因归属 PyPTO框架/PyPTO文档/PyPTO样例/Agent框架 → 计入断裂点总数，输出到报告正文
- 根因归属模型自身 → 标记为"模型能力"，在报告末尾单独列出，不计入断裂点总数
步骤 7：关联标记
相同实体的不同断裂点自动标记为关联。例如 pypto.reshape 同时有 D1（文档缺失）和 C1（反复重试），它们互相关联。
步骤 8：置信度过滤
剔除所有低置信度的断裂点。只有中/高置信度的断裂点进入最终报告。
步骤 9：环境信息获取
执行以下命令获取环境信息，任何命令失败则对应字段标记为"未知"，不影响报告生成：
| 信息 | 命令 |
|---|
| CANN 版本 | echo $ASCEND_HOME_PATH | grep -oP 'cann-\K[\d.]+' |
| PyPTO Commit | git 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 "Unknown" |
| Python 版本 | python --version 2>/dev/null || echo "Unknown" |
| 操作系统 | cat /etc/os-release 2>/dev/null | grep PRETTY_NAME || echo "Unknown" |
步骤 10：报告生成
根据检测结果生成报告：
有断裂点的情况：
- 使用
templates/report-template.md 中的模板生成报告
- 文件名：
fracture-point-YYYY-MM-DD-HHMMSS.md
- 保存到当前工作目录
- 断裂点按优先级排序：致命 > 高 > 中
- 每个断裂点包含：类型、优先级、根因归属、Issue 建议、证据片段、优化建议
- Issue 类型映射和标题模板见
references/issue-mapping.md
scope=full 模式下，报告包含"子会话分析概览"章节，每个断裂点标记来源 session
无断裂点的情况：
- 不生成报告文件
- 在屏幕直接输出摘要：session 基本信息、操作统计、涉及实体列表、"未检测到断裂点"提示
重要提醒
- 证据片段必须是 session 中的原文引用，不要编造或概括
- 每个断裂点的"问题描述"应清晰到能让不了解 session 上下文的人理解发生了什么
- 优化建议要具体、可操作，指向具体的文件或 API
- Session 级断裂点（C5、C6）不针对特定实体，单独列为一个章节
scope=full 模式使用"最近活跃推断策略"获取当前 session ID，在多 session 同时活跃时可能不准确，报告中需说明此限制- 分析子会话时，完整读取用户消息、助手回复、推理过程和工具调用链
- 二次校验：必须执行步骤 6 的两项检查，验证根因是否确实归属于框架或文档。断裂点分类包含：PyPTO框架、PyPTO文档、PyPTO样例、Agent框架、模型能力。前四个是问题，模型能力是非问题（不应计入断裂点总数）。
