skill-system-debug

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

skill-system-debug

Debugging toolkit for AI agents: diagnose, trace, bisect, compare.

AI Agent调试工具包：诊断、追踪、二分定位、对比。

Operations

操作功能

diagnose

诊断

Search memory cache (5-dimension diagnostic), then behavior cache (

*.behavior.yaml

), then codebase grep to generate ranked hypotheses.

bash

python3 scripts/debug_tool.py diagnose --symptom "alert file missing" --context "pipeline run"

通过内存缓存（5维度诊断）、行为缓存（

*.behavior.yaml

）、代码库搜索来生成带优先级的假设。

bash

python3 scripts/debug_tool.py diagnose --symptom "alert file missing" --context "pipeline run"

trace

追踪

Walk backward through data flow from an output file to its influencing inputs.

bash

python3 scripts/debug_tool.py trace --output-file reports/profile.yaml --input-files data/train.csv

从输出文件反向追溯到影响它的输入文件的数据流。

bash

python3 scripts/debug_tool.py trace --output-file reports/profile.yaml --input-files data/train.csv

bisect

二分定位

Run

git bisect

to find the first bad commit given a test command.

bash

python3 scripts/debug_tool.py bisect --good abc123 --bad def456 --test "pytest tests/ -q"

运行

git bisect

，根据测试命令定位首个错误提交。

bash

python3 scripts/debug_tool.py bisect --good abc123 --bad def456 --test "pytest tests/ -q"

compare

对比

Compare two directories (senior reference vs current) and highlight key differences.

bash

python3 scripts/debug_tool.py compare --senior reports/senior/ --current reports/current/ --format json

skill

{
  "schema_version": "2.0",
  "id": "skill-system-debug",
  "version": "0.1.0",
  "capabilities": ["debug-diagnose", "debug-trace", "debug-bisect", "debug-compare"],
  "effects": ["proc.exec", "fs.read", "db.read"],
  "operations": {
    "diagnose": {
      "description": "Diagnose a symptom using memory cache -> behavior cache -> codebase grep. Returns ranked hypotheses with confidence scores.",
      "input": {
        "symptom": { "type": "string", "required": true, "description": "Symptom description" },
        "context": { "type": "string", "required": false, "description": "Additional context" }
      },
      "output": {
        "description": "JSON with hypotheses list, memories_found count, behavior_matches count, and code_matches count",
        "fields": { "hypotheses": "array", "memories_found": "integer", "behavior_matches": "integer", "code_matches": "integer" }
      },
      "entrypoints": {
        "unix": ["python3", "scripts/debug_tool.py", "diagnose", "--symptom", "{symptom}"],
        "windows": ["python3", "scripts/debug_tool.py", "diagnose", "--symptom", "{symptom}"]
      }
    },
    "trace": {
      "description": "Trace data flow from an output file back to influencing input files.",
      "input": {
        "output_file": { "type": "string", "required": true, "description": "Output file to trace from" },
        "input_files": { "type": "array", "required": false, "description": "Known input files" }
      },
      "output": {
        "description": "JSON with files list, transforms list, depth integer",
        "fields": { "files": "array", "transforms": "array", "depth": "integer" }
      },
      "entrypoints": {
        "unix": ["python3", "scripts/debug_tool.py", "trace", "--output-file", "{output_file}"],
        "windows": ["python3", "scripts/debug_tool.py", "trace", "--output-file", "{output_file}"]
      }
    },
    "bisect": {
      "description": "Run git bisect to find the first bad commit.",
      "input": {
        "good": { "type": "string", "required": true, "description": "Known good commit" },
        "bad": { "type": "string", "required": true, "description": "Known bad commit" },
        "test": { "type": "string", "required": true, "description": "Test command (exit 0=good, 1=bad)" }
      },
      "output": {
        "description": "JSON with commit, author, date, message, is_first_bad",
        "fields": { "commit": "string", "author": "string", "date": "string", "message": "string", "is_first_bad": "boolean" }
      },
      "entrypoints": {
        "unix": ["python3", "scripts/debug_tool.py", "bisect", "--good", "{good}", "--bad", "{bad}", "--test", "{test}"],
        "windows": ["python3", "scripts/debug_tool.py", "bisect", "--good", "{good}", "--bad", "{bad}", "--test", "{test}"]
      }
    },
    "compare": {
      "description": "Compare two directories and highlight key differences.",
      "input": {
        "senior": { "type": "string", "required": true, "description": "Senior/reference directory" },
        "current": { "type": "string", "required": true, "description": "Current directory" },
        "format": { "type": "string", "required": false, "default": "text", "description": "text | json | csv" }
      },
      "output": {
        "description": "JSON with key_diffs list and summary counts",
        "fields": { "key_diffs": "array", "summary": "object" }
      },
      "entrypoints": {
        "unix": ["python3", "scripts/debug_tool.py", "compare", "--senior", "{senior}", "--current", "{current}"],
        "windows": ["python3", "scripts/debug_tool.py", "compare", "--senior", "{senior}", "--current", "{current}"]
      }
    }
  }
}

对比两个目录（资深参考版本 vs 当前版本）并高亮关键差异。

bash

python3 scripts/debug_tool.py compare --senior reports/senior/ --current reports/current/ --format json

skill

{
  "schema_version": "2.0",
  "id": "skill-system-debug",
  "version": "0.1.0",
  "capabilities": ["debug-diagnose", "debug-trace", "debug-bisect", "debug-compare"],
  "effects": ["proc.exec", "fs.read", "db.read"],
  "operations": {
    "diagnose": {
      "description": "Diagnose a symptom using memory cache -> behavior cache -> codebase grep. Returns ranked hypotheses with confidence scores.",
      "input": {
        "symptom": { "type": "string", "required": true, "description": "Symptom description" },
        "context": { "type": "string", "required": false, "description": "Additional context" }
      },
      "output": {
        "description": "JSON with hypotheses list, memories_found count, behavior_matches count, and code_matches count",
        "fields": { "hypotheses": "array", "memories_found": "integer", "behavior_matches": "integer", "code_matches": "integer" }
      },
      "entrypoints": {
        "unix": ["python3", "scripts/debug_tool.py", "diagnose", "--symptom", "{symptom}"],
        "windows": ["python3", "scripts/debug_tool.py", "diagnose", "--symptom", "{symptom}"]
      }
    },
    "trace": {
      "description": "Trace data flow from an output file back to influencing input files.",
      "input": {
        "output_file": { "type": "string", "required": true, "description": "Output file to trace from" },
        "input_files": { "type": "array", "required": false, "description": "Known input files" }
      },
      "output": {
        "description": "JSON with files list, transforms list, depth integer",
        "fields": { "files": "array", "transforms": "array", "depth": "integer" }
      },
      "entrypoints": {
        "unix": ["python3", "scripts/debug_tool.py", "trace", "--output-file", "{output_file}"],
        "windows": ["python3", "scripts/debug_tool.py", "trace", "--output-file", "{output_file}"]
      }
    },
    "bisect": {
      "description": "Run git bisect to find the first bad commit.",
      "input": {
        "good": { "type": "string", "required": true, "description": "Known good commit" },
        "bad": { "type": "string", "required": true, "description": "Known bad commit" },
        "test": { "type": "string", "required": true, "description": "Test command (exit 0=good, 1=bad)" }
      },
      "output": {
        "description": "JSON with commit, author, date, message, is_first_bad",
        "fields": { "commit": "string", "author": "string", "date": "string", "message": "string", "is_first_bad": "boolean" }
      },
      "entrypoints": {
        "unix": ["python3", "scripts/debug_tool.py", "bisect", "--good", "{good}", "--bad", "{bad}", "--test", "{test}"],
        "windows": ["python3", "scripts/debug_tool.py", "bisect", "--good", "{good}", "--bad", "{bad}", "--test", "{test}"]
      }
    },
    "compare": {
      "description": "Compare two directories and highlight key differences.",
      "input": {
        "senior": { "type": "string", "required": true, "description": "Senior/reference directory" },
        "current": { "type": "string", "required": true, "description": "Current directory" },
        "format": { "type": "string", "required": false, "default": "text", "description": "text | json | csv" }
      },
      "output": {
        "description": "JSON with key_diffs list and summary counts",
        "fields": { "key_diffs": "array", "summary": "object" }
      },
      "entrypoints": {
        "unix": ["python3", "scripts/debug_tool.py", "compare", "--senior", "{senior}", "--current", "{current}"],
        "windows": ["python3", "scripts/debug_tool.py", "compare", "--senior", "{senior}", "--current", "{current}"]
      }
    }
  }
}