debug-diagnosis

name: debug-diagnosis description: "在修改 Sirius Pulse 核心模块（core/memory/providers/platforms 等）后，系统化排查异常、定位根因并验证修复。关键词：调试诊断、bug排查、异常定位、核心模块、修复验证。"

调试诊断指南

目标

在修改 sirius_pulse 核心模块后出现异常或行为偏离预期时，通过结构化的排查流程快速定位根因，避免盲目猜测和过度修复。

语言规范（强制）

• 本 SKILL 及所有后续新增/修改的 SKILL 必须使用中文。
• description 和正文必须为中文。
• 若任务中发现英文 SKILL 内容，需在同一任务中同步中文化。

触发条件

当以下场景出现时，必须执行本流程：

• 修改 sirius_pulse/core/、sirius_pulse/memory/、sirius_pulse/providers/、sirius_pulse/platforms/ 后测试失败或行为异常
• 修改 sirius_pulse/models/ 数据模型后引发上下游兼容性问题
• 修改 sirius_pulse/config/ 配置系统后导致引擎初始化失败
• 运行时出现未捕获异常、无限循环、内存泄漏或响应延迟剧增
• 用户明确要求"帮我排查这个问题"或"为什么出错了"

核心原则

1. 先复现，后修复：没有稳定复现步骤的修复是赌博。
2. 最小改动验证：每次只改一个地方，确认因果关系。
3. 日志优先：先看日志和堆栈，不要直接读代码猜原因。
4. 隔离变量：用 MockProvider 和临时目录排除外部干扰。

排查流程

步骤 1：收集异常信息

必须收集的信息：

• 完整的异常堆栈（traceback）
• 触发异常的最小输入/操作序列
• 最近的代码变更范围（git diff HEAD~1 --name-only）
• 相关日志片段（logs/ 或控制台输出）

快速命令：

# 查看最近改动
git diff HEAD~1 --name-only

# 查看改动统计
git diff HEAD~1 --stat

# 查看特定文件的改动
git diff HEAD~1 -- sirius_pulse/core/emotional_engine.py

步骤 2：定位异常层级

根据异常类型和堆栈，判断问题发生在哪个架构层级：

步骤 3：缩小变更范围

二分法定位：

1. 回退到上一个稳定 commit，确认问题是否消失。
2. 逐步应用改动，找到引入问题的最小变更集。
3. 若改动较大，优先检查数据流变更（新增/删除字段、修改函数签名）。

关键检查点：

• 是否有函数签名变更但未同步所有调用点？
• 是否有新增字段未设置默认值导致旧数据反序列化失败？
• 是否有异步/同步混用（如 async def 被同步调用）？
• 是否有路径变更导致文件读写失败？
• 是否有导入循环（circular import）？

步骤 4：编写最小复现测试

在修复前，先写一个能稳定复现问题的测试：

import pytest
from sirius_pulse.core.emotional_engine import EmotionalGroupChatEngine
from sirius_pulse.models.persona import PersonaProfile
from sirius_pulse.providers.mock import MockProvider
from sirius_pulse.models.models import Message, Participant

@pytest.mark.asyncio
async def test_reproduce_issue(tmp_path):
    """复现 [问题描述]"""
    provider = MockProvider(responses=["测试回复"])
    engine = EmotionalGroupChatEngine(
        work_path=tmp_path,
        persona=PersonaProfile(name="DebugBot"),
        provider_async=provider,
    )

    # 构造触发异常的输入
    participant = Participant(name="u1", user_id="u1")
    msg = Message(role="human", content="触发内容", speaker="u1")

    # 执行并观察异常
    reply = await engine.process_message(msg, [participant], "group_a")

    # 断言异常行为或错误结果
    # assert ...

步骤 5：修复与验证

修复原则：

• 只修改根因，不附带"优化"或"清理"。
• 若涉及接口变更，同步更新所有调用点和测试。
• 修复后运行相关测试：pytest tests/test_<module>.py -xvs

验证清单：

• 最小复现测试现在通过。
• 该模块的全部测试通过：pytest tests/test_<module>.py -q
• 全量测试通过：pytest tests/ -q
• python main.py --help 正常输出。
• 若修改了外部接口，sirius_pulse/__init__.py 已同步更新。

步骤 6：日志与监控增强（可选）

若问题是隐蔽的（如时序问题、状态竞争），考虑增强日志：

• 在关键路径添加 logger.debug() 记录状态变更。
• 使用 pytest -xvs -k <test_name> 查看详细输出。
• 检查 engine_state/ 和 logs/ 中的持久化状态是否一致。

常见陷阱速查

完成检查清单

• 异常已稳定复现。
• 根因已定位到具体代码行或逻辑。
• 修复方案已验证（最小复现测试通过）。
• 相关模块全量测试通过。
• 未引入新的异常或副作用。
• 若涉及 SKILL/文档相关变更，已同步更新（参考 code-change-sync SKILL）。

交付输出

提供一份简要诊断报告，包含：

1. 问题描述：异常现象与复现步骤。
2. 根因分析：定位到的具体原因。
3. 修复方案：修改了哪些代码。
4. 验证结果：测试通过情况。
5. 后续建议：是否需要增强日志、补充测试或更新文档。