sc-log-fix

Log-Fix：基于日志分析的迭代式错误修复

分析来自多个来源的日志，识别错误，执行根因分析，并通过模式学习交互式地修复问题。

快速开始

# Analyze recent errors from all log sources
/sc:log-fix

# Filter by time and severity
/sc:log-fix --time 1h --level ERROR

# Target specific log source
/sc:log-fix --source backend --component app.services

# Trace a specific request
/sc:log-fix --request-id abc-123-def

# Dry run - analyze without fixing
/sc:log-fix --dry-run

行为流程

1. 发现 - 检测可用的日志来源（文件、docker、systemd）
2. 加载知识 - 检查此前修复中学到的模式
3. 收集 - 解析并规范化检测到的来源中的日志
4. 分类 - 对错误进行聚类，按严重性排序，并匹配已知模式
5. 分析 - 结合堆栈跟踪和代码检查进行根因分析
6. 修复 - 通过交互式修复循环进行修复
7. 学习 - 将成功的修复模式保存到知识库
8. 报告 - 总结本次会话及剩余问题

标志

标志	类型	默认值	说明
--time	string	1h	时间范围：30m、1h、1d、7d
--source	string	all	日志来源：backend、frontend、docker、all
--level	string	ERROR	最低严重性：ERROR、WARNING、all
--component	string	-	按记录器/模块名称筛选
--request-id	string	-	跨日志跟踪特定请求
--dry-run	bool	false	仅分析和报告，不应用修复
--fix	bool	true	启用交互式修复循环

阶段 0：发现日志来源

在分析前自动检测所有可用的日志来源。

检测策略

来源	检测方法	常见位置
文件日志	对 logs/**/*.log、*.log 执行 Glob 搜索	logs/、var/log/
Docker	检查 docker compose ps	docker-compose.yml
Systemd	检查 journalctl 是否可用	系统服务
PM2	检查 pm2 list	Node.js 应用

日志格式检测

自动检测日志格式：

• JSON（结构化）- 使用 jq 解析
• 文本（非结构化）- 使用正则表达式模式解析
• 组合格式（nginx/apache 风格）- 使用特定格式的正则表达式解析

# Detect format by reading first line
head -1 logs/app.log | python3 -c "import sys,json; json.loads(sys.stdin.read()); print('json')" 2>/dev/null || echo "text"

阶段 1：加载知识

加载历史修复知识，以增强分析能力。

知识文件结构

{
  "version": "1.0",
  "error_patterns": [
    {
      "id": "pattern-001",
      "signature": {
        "message_pattern": "Connection refused.*port \\d+",
        "component": "app.services.database",
        "exception_type": "ConnectionError"
      },
      "fixes": [{
        "description": "Check database is running, verify connection string",
        "file_changed": "src/config.py",
        "validation_command": "pytest tests/test_db.py -v",
        "success_count": 3,
        "confidence": 0.9
      }]
    }
  ],
  "component_knowledge": {},
  "metadata": {
    "total_fixes": 0,
    "updated_at": null
  }
}

位置：.claude/knowledge/log-fix-knowledge.json

加载知识后：

• 分类：为此前出现过的错误显示“已知问题”徽标
• 根因：根据历史成功率建议修复方案
• 修复循环：提供一键应用经过验证的修复方案

阶段 2：分类与聚类

事件聚类

按以下条件分组：

1. 相同错误类型（相同/相似的消息）
2. 相同组件（记录器/服务名称）
3. 相同请求（request_id 关联）
4. 相同时间窗口（5s 内的错误）

严重性排序

优先级	标准
P0	堆栈跟踪、服务崩溃、数据库错误
P1	ERROR 级别、API 故障、身份验证问题
P2	WARNING 级别、弃用、性能问题
P3	信息提示、清理建议

分类摘要输出

## Error Triage Summary

**Time Range**: [start] to [end]
**Total Errors**: N | **Unique Types**: M | **Known Patterns**: K

### Top Issues by Frequency

| # | Count | Component | Error Pattern | Priority | Historical |
|---|-------|-----------|---------------|----------|------------|
| 1 | 15 | app.services.api | Connection timeout | P1 | Known: 3 fixes, 90% |
| 2 | 8 | app.models | Validation failed | P1 | New pattern |

阶段 3：根因分析

针对每个事件集群：

1. 堆栈跟踪分析 - 提取文件路径，识别出错行，并映射到相应组件
2. 日志关联 - 跨服务追踪 request_id
3. 模式匹配 - 检查知识库，然后执行代码级分析
4. 代码检查 - 读取相关源文件，识别错误

根因输出

## Root Cause: [Error Type]

**Occurrences**: N | **Component**: [logger]

### Error Details
[Full error and stack trace]

### Relevant Code
**File**: `src/services/api.py:145`
[Code context with highlighted line]

### Probable Cause
[Analysis explaining why the error occurs]

### Suggested Fix
[Specific code change with diff preview]

阶段 4：交互式修复循环

修复工作流

1. 展示 - 显示错误、根因和受影响的文件
2. 显示差异 - 展示提议的精确代码更改
3. 征求许可 - 用户批准、跳过或修改
4. 批准后应用 - 使用 Edit 工具
5. 验证 - 运行相关测试
6. 学习 - 提供将模式保存到知识库的选项

用户选项

操作	描述
应用	应用建议的修复
跳过	跳过此问题，转到下一个
编辑	应用前修改建议的修复
先测试	修复前编写测试（调用 /sc:tdd）
详情	显示更多错误上下文
退出	退出修复循环

修复后验证

修复类型	验证
Python 代码	pytest -k "test_function" -v
JavaScript	npm test -- --testPathPattern=file
配置	重启并验证运行状况
数据库	运行迁移

阶段 5：知识学习

成功修复后，提供保存此模式的选项：

1. 提取错误特征 - 将具体值转换为正则表达式模式
2. 记录修复详情 - 修改内容、位置和验证命令
3. 更新知识文件 - 追加或更新现有模式
4. 报告置信度 - 初始置信度为 1.0，随后随时间调整

学习提示词

Fix applied and validated!

Save this pattern for future similar errors?
  [Y] Yes, save pattern and fix
  [n] No, this was a one-off fix
  [e] Yes, but let me edit the description first

阶段 6：会话报告

## Log-Fix Session Summary

**Logs Analyzed**: [sources] | **Time Range**: [range]
**Errors Found**: N | **Unique Issues**: M

### Issues Addressed

| # | Component | Issue | Status | Action |
|---|-----------|-------|--------|--------|
| 1 | app.services | Connection timeout | FIXED | Added retry config |
| 2 | app.models | Validation error | SKIPPED | User deferred |

### Files Modified
- src/services/api.py
- src/config.py

### Patterns Learned
- 1 new pattern saved to knowledge base

### Next Steps
- Run `/sc:pr-check` to validate all changes
- Consider `/sc:tdd` for issues without test coverage

MCP 集成

PAL MCP（调试与分析）

工具	使用时机	用途
mcp__pal__debug	复杂错误	多阶段根因分析
mcp__pal__thinkdeep	模式不明确	深入调查反复出现的问题
mcp__pal__codereview	修复验证	审查建议修复的质量
mcp__pal__apilookup	依赖错误	获取版本问题对应的最新文档

PAL 使用模式

# Debug complex error pattern
mcp__pal__debug(
    step="Investigating recurring connection timeout in API layer",
    hypothesis="Connection pool exhaustion under load",
    confidence="medium",
    relevant_files=["src/services/api.py", "src/config.py"]
)

# Deep analysis of unclear pattern
mcp__pal__thinkdeep(
    step="Why do these errors only occur during peak hours?",
    hypothesis="Race condition in connection pooling",
    confidence="low"
)

Rube MCP（通知）

工具	使用时机	用途
mcp__rube__RUBE_SEARCH_TOOLS	外部日志记录	查找日志服务工具
mcp__rube__RUBE_MULTI_EXECUTE_TOOL	通知	将修复摘要发布到 Slack/Jira

工具协同

• Bash - 日志解析（jq、grep）、测试执行、docker 命令
• Glob - 查找日志文件
• Grep - 搜索错误模式、追踪请求 ID
• Read - 检查源代码、读取日志文件
• Edit - 应用代码修复
• Write - 更新知识库、生成会话报告

相关技能

• /sc:tdd - 修复前编写测试（TDD 方法）
• /sc:pr-check - PR 前验证所有更改
• /sc:analyze - 根因不明确时进行更深入的代码分析