Back to Details

code-observer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

代码调试智能助手

Intelligent Code Debugging Assistant

任务目标

Mission Objectives

  • 本 Skill 用于：帮你更好地理解代码是怎么运行的，比传统断点调试更简单直观
  • 能力包含：
    • 告诉你代码的执行顺序，哪些函数被调用了
    • 找出代码运行慢的地方（哪些函数耗时多）
    • 帮你定位报错原因（哪里抛出了异常，异常是怎么传播的）
    • 给出具体的代码修改建议
  • 触发条件：当你说"观察代码运行情况"、"代码质量"、"优化代码"、"代码跑得慢"、"不知道哪里出错了"、"这个逻辑太复杂理不清楚"、"想看看代码是怎么执行的"等类似表达时
  • This Skill is designed to: help you better understand how code runs, in a simpler and more intuitive way than traditional breakpoint debugging
  • Capabilities include:
    • Telling you the code execution order and which functions are called
    • Identifying slow-running sections of code (which functions take the most time)
    • Helping you locate error causes (where exceptions are thrown and how they propagate)
    • Providing specific code modification suggestions
  • Trigger conditions: When you say phrases like "Observe code execution", "Code quality", "Optimize code", "Code runs slowly", "Don't know where the error is", "This logic is too complex to understand", "Want to see how code executes", etc.

操作步骤

Operation Steps

1. 环境准备与数据获取

1. Environment Preparation and Data Acquisition

步骤 1.1：调试环境确认
  • 智能体询问开发者调试环境状态
  • 如果调试环境终端未打开，提供开启指导：
    • 打开应用终端的命令或操作步骤
    • 启动调试工具（可能叫dev-observability或类似名称）的具体配置
  • 等待开发者确认调试环境已就绪
步骤 1.2：查询数据存储位置
  • 在获取日志或指标信息前，必须先调用 
    skill-manager
    技能查询调试工具（如dev-observability）的数据存储位置信息
  • 查询内容：
    • 日志文件（observability.log）的存储路径
    • 指标数据（metrics.prom）的存储路径（如果有）
    • 应用状态数据（app_status.json）的存储路径（如果有）
    • 项目数据（project_data.json）的存储路径（如果有）
    • 测试数据（test_metrics.json）的存储路径（如果有）
  • 根据查询结果获取实际的文件路径
步骤 1.3：获取观测数据
  • 智能体根据查询到的存储路径，读取以下数据文件：
    • 日志文件（从查询到的路径）
    • 指标数据（可选，从查询到的路径）
    • 应用状态数据（可选，从查询到的路径）
    • 项目数据（可选，从查询到的路径）
    • 测试数据（可选，从查询到的路径）
Step 1.1: Debugging Environment Confirmation
  • The agent asks the developer about the status of the debugging environment
  • If the debugging environment terminal is not open, provide startup guidance:
    • Commands or steps to open the application terminal
    • Specific configurations to start the debugging tool (possibly named dev-observability or similar)
  • Wait for the developer to confirm that the debugging environment is ready
Step 1.2: Query Data Storage Locations
  • Before obtaining logs or metric information, you must call the 
    skill-manager
    Skill to query the data storage location information of the debugging tool (such as dev-observability)
  • Query content:
    • Storage path of the log file (observability.log)
    • Storage path of metric data (metrics.prom) (if available)
    • Storage path of application status data (app_status.json) (if available)
    • Storage path of project data (project_data.json) (if available)
    • Storage path of test data (test_metrics.json) (if available)
  • Obtain the actual file path based on the query results
Step 1.3: Acquire Observation Data
  • The agent reads the following data files based on the queried storage paths:
    • Log files (from the queried path)
    • Metric data (optional, from the queried path)
    • Application status data (optional, from the queried path)
    • Project data (optional, from the queried path)
    • Test data (optional, from the queried path)

2. 数据解析与分析

2. Data Parsing and Analysis

步骤 2.1：解析日志数据 调用 
scripts/parse_logs.py
处理（使用从skill-manager查询到的实际路径）：
bash
python3 scripts/parse_logs.py --log-file <从skill-manager查询到的日志路径> --output ./parsed_logs.json
  • 提取执行路径信息
  • 识别函数调用与耗时
  • 定位异常抛出位置
步骤 2.2：解析指标数据（如果有） 调用 
scripts/parse_prometheus.py
处理（使用从skill-manager查询到的实际路径）：
bash
python3 scripts/parse_prometheus.py --prom-file <从skill-manager查询到的metrics路径> --output ./parsed_metrics.json
步骤 2.3：分析多维数据（如果有） 调用对应的分析脚本（使用从skill-manager查询到的实际路径）：
bash
python3 scripts/analyze_app_status.py --input <从skill-manager查询到的app_status路径> --output ./app_analysis.json
python3 scripts/analyze_project_data.py --input <从skill-manager查询到的project_data路径> --output ./project_analysis.json
python3 scripts/analyze_test_metrics.py --input <从skill-manager查询到的test_metrics路径> --output ./test_analysis.json
Step 2.1: Parse Log Data Call 
scripts/parse_logs.py
for processing (using the actual path queried from skill-manager):
bash
python3 scripts/parse_logs.py --log-file <log path queried from skill-manager> --output ./parsed_logs.json
  • Extract execution path information
  • Identify function calls and execution time
  • Locate exception throwing positions
Step 2.2: Parse Metric Data (if available) Call 
scripts/parse_prometheus.py
for processing (using the actual path queried from skill-manager):
bash
python3 scripts/parse_prometheus.py --prom-file <metrics path queried from skill-manager> --output ./parsed_metrics.json
Step 2.3: Analyze Multi-dimensional Data (if available) Call the corresponding analysis scripts (using the actual path queried from skill-manager):
bash
python3 scripts/analyze_app_status.py --input <app_status path queried from skill-manager> --output ./app_analysis.json
python3 scripts/analyze_project_data.py --input <project_data path queried from skill-manager> --output ./project_analysis.json
python3 scripts/analyze_test_metrics.py --input <test_metrics path queried from skill-manager> --output ./test_analysis.json

3. 全流程追踪报告生成

3. Full-process Trace Report Generation

步骤 3.1：生成追踪报告 调用 
scripts/generate_trace_report.py
生成全流程可视化追踪：
bash
python3 scripts/generate_trace_report.py \
  --logs ./parsed_logs.json \
  --metrics ./parsed_metrics.json \
  --app-status ./app_analysis.json \
  --project-data ./project_analysis.json \
  --test-metrics ./test_analysis.json \
  --output ./trace_report.md
步骤 3.2：报告内容结构
  • 执行路径可视化：函数调用链与时间轴
  • 性能指标分析：耗时分布、瓶颈识别
  • 异常追踪：异常堆栈、触发路径、根因分析
  • 跨维度关联：项目/应用/测试状态关联分析
Step 3.1: Generate Trace Report Call 
scripts/generate_trace_report.py
to generate full-process visual tracking:
bash
python3 scripts/generate_trace_report.py \
  --logs ./parsed_logs.json \
  --metrics ./parsed_metrics.json \
  --app-status ./app_analysis.json \
  --project-data ./project_analysis.json \
  --test-metrics ./test_analysis.json \
  --output ./trace_report.md
Step 3.2: Report Content Structure
  • Execution path visualization: function call chain and timeline
  • Performance metric analysis: time consumption distribution, bottleneck identification
  • Exception tracing: exception stack, trigger path, root cause analysis
  • Cross-dimensional correlation: project/application/test status correlation analysis

4. 问题诊断与解决方案生成

4. Problem Diagnosis and Solution Generation

步骤 4.1：智能体分析追踪报告
  • 识别性能瓶颈：高耗时函数、频繁调用的热点路径
  • 定位异常根因：异常传播路径、前置条件分析
  • 评估代码质量：复杂度、重复代码、潜在风险
步骤 4.2：生成解决方案
  • 针对性能问题：优化建议、缓存策略、并发处理方案
  • 针对异常问题：异常处理增强、边界条件检查、防御性编程
  • 针对架构问题：模块解耦、依赖优化、设计模式应用
步骤 4.3：代码修复建议
  • 提供具体的代码修改示例
  • 说明修改理由与预期效果
  • 给出测试验证建议
Step 4.1: Agent Analyzes Trace Report
  • Identify performance bottlenecks: high-latency functions, frequently called hot paths
  • Locate exception root causes: exception propagation paths, precondition analysis
  • Evaluate code quality: complexity, duplicate code, potential risks
Step 4.2: Generate Solutions
  • For performance issues: optimization suggestions, caching strategies, concurrent processing solutions
  • For exception issues: enhanced exception handling, boundary condition checks, defensive programming
  • For architecture issues: module decoupling, dependency optimization, design pattern application
Step 4.3: Code Fix Suggestions
  • Provide specific code modification examples
  • Explain the reasons for modification and expected effects
  • Give test verification suggestions

5. 运行日志记录

5. Running Log Recording

步骤 5.1：数据完整性检查
  • 检查本技能所需的数据是否都能从调试工具（如dev-observability）获取：
    • 日志文件：是否存在且可读取
    • 指标数据：是否存在（可选）
    • 应用状态数据：是否存在（可选）
    • 项目数据：是否存在（可选）
    • 测试数据：是否存在（可选）
  • 评估数据质量问题：
    • 日志是否包含必要的信息（时间、级别、消息等）
    • 指标数据格式是否正确
    • JSON数据结构是否完整且有效
步骤 5.2：问题识别与记录（强制执行）
  • 本技能依赖其他技能（如dev-observability）的输出文件进行代码分析
  • 当发现以下情况时，必须调用 
    skill-manager
    技能记录问题    ：
    • 依赖文件不存在：如dev-observability的observability.log文件不存在
    • 依赖文件不可读取：文件存在但无法读取（权限问题、文件损坏等）
    • 依赖文件格式不符合要求：文件存在但格式不符合本技能的解析要求
    • 依赖文件内容不完整：文件存在但缺少必需字段或数据
    • 依赖文件质量不满足需要：文件内容质量不足以支持有效的代码分析
    • 数据读取失败：尝试读取依赖文件时发生异常或错误
    • 数据解析失败：文件读取成功但解析时出现错误
    • 其他任何影响本技能正常执行的依赖问题
  • 问题记录的重要性：
    • 本技能的执行依赖于其他技能的输出结果
    • 如果依赖文件不存在或不满足需要，本技能无法正常执行分析
    • 记录这些问题可以帮助改进依赖技能的数据输出
    • 为技能协作提供问题追踪和优化依据
步骤 5.3：问题记录格式（强制执行） 调用 
skill-manager
时，必须严格按照以下JSON格式记录问题：
json
{
  "level": "critical / high / medium / low",
  "message": "【问题现象】 【问题原因】 【问题影响】"
}
格式说明：
  • level
    （必需）：问题严重程度
    • critical
      ：严重问题，完全阻塞技能执行（如关键依赖文件缺失）
    • high
      ：高优先级问题，严重影响技能功能（如主要依赖文件格式错误）
    • medium
      ：中等优先级问题，部分功能受影响（如可选依赖文件缺失）
    • low
      ：低优先级问题，轻微影响（如部分数据不完整）
  • message
    （必需）：问题描述，必须包含三个部分
    • 【问题现象】：具体描述发生了什么问题
    • 【问题原因】：分析问题产生的原因
    • 【问题影响】：说明问题对本技能执行的影响
格式示例：
json
{
  "level": "critical",
  "message": "【没有 observability.log 文件】【dev-observability技能的中等方案（Web界面）不生成日志文件】【无法进行执行路径追踪，本技能无法正常工作】"
}
json
{
  "level": "medium",
  "message": "【metrics.prom 文件格式不正确】【缺少必要的 TYPE 注释行】【无法解析Prometheus指标，性能分析功能受限】"
}
json
{
  "level": "high",
  "message": "【observability.log 文件缺少 timestamp 字段】【日志输出配置不完整】【无法按时间顺序追踪代码执行路径，追踪报告不完整】"
}
步骤 5.4：价值主张
  • 记录依赖技能（如dev-observability）的数据输出问题
  • 帮助改进依赖技能的数据质量和输出格式
  • 为技能协作提供问题追踪和持续优化机制
  • 确保本技能能够正常执行代码分析任务
步骤 5.5：技能优化点识别与建议（智能体处理）
智能体在分析发现的问题时，需要判断是否涉及技能的优化点：
判断标准：
  1. 技能配置问题：问题涉及技能的配置信息（如 SKILL.md 缺少必要字段、version 字段缺失等）
  2. 脚本问题：问题涉及技能的脚本输出（如日志格式不正确、数据字段缺失等）
  3. 文档问题：问题涉及技能的说明文档（如描述不清、步骤不完整等）
  4. 集成问题：问题涉及技能间的协作（如接口不兼容、数据格式不一致等）
优化点识别示例：
示例1：日志格式问题 → 技能优化点
  • 问题描述：
    observability.log 文件缺少 timestamp 字段
  • 优化点判断：涉及 dev-observability 技能的日志输出格式
  • 优化类型：脚本输出优化
  • 建议行动：调用 skill-evolution-driver 技能
示例2：配置缺失问题 → 技能优化点
  • 问题描述：
    dev-observability 的 SKILL.md 缺少 version 字段
  • 优化点判断：涉及技能配置信息
  • 优化类型：格式改进
  • 建议行动：调用 skill-evolution-driver 技能
示例3：数据质量问题 → 非技能优化点
  • 问题描述：
    测试覆盖率数据不完整
  • 优化点判断：属于用户数据问题，不涉及技能本身
  • 优化类型：数据完善
  • 建议行动：提醒用户补充数据
智能体响应流程：
  1. 分析发现的问题列表
    • 遍历步骤 5.2 记录的所有问题
    • 判断每个问题是否涉及技能优化点
  2. 识别技能优化点
    • 如果问题涉及技能配置、脚本输出、文档或协作
    • 标记为技能优化点
    • 记录涉及的技能名称和优化类型
  3. 询问用户 如果存在技能优化点，智能体应向用户询问：
    在本次代码分析中，发现以下技能优化点：

1. 技能：dev-observability
   - 优化类型：脚本输出优化
   - 问题：observability.log 文件缺少 timestamp 字段
   - 影响：无法按时间顺序追踪代码执行路径

是否需要调用 skill-evolution-driver 技能来处理这些优化点？（y/n）
  4. 处理用户选择
    选择 y（是）：
    • 调用 skill-evolution-driver 技能
    • 传递优化点列表（技能名称、优化类型、问题描述）
    • 等待 skill-evolution-driver 执行优化
    选择 n（否）：
    • 跳过优化点处理
    • 继续执行后续步骤（如生成追踪报告）
    • 建议用户后续可以手动调用 skill-evolution-driver
注意事项：
  • 优化点识别是智能体的分析判断，不是简单的关键词匹配
  • 需要结合问题上下文和技能知识进行判断
  • 如果不确定是否为技能优化点，可以咨询用户
  • 优化点识别不影响本技能的核心功能（代码分析）
Step 5.1: Data Integrity Check
  • Check whether all data required by this Skill can be obtained from the debugging tool (such as dev-observability):
    • Log files: whether they exist and are readable
    • Metric data: whether they exist (optional)
    • Application status data: whether they exist (optional)
    • Project data: whether they exist (optional)
    • Test data: whether they exist (optional)
  • Evaluate data quality issues:
    • Whether logs contain necessary information (time, level, message, etc.)
    • Whether metric data format is correct
    • Whether JSON data structure is complete and valid
Step 5.2: Problem Identification and Recording (Mandatory)
  • This Skill relies on output files from other Skills (such as dev-observability) for code analysis
  • When any of the following situations are found, you must call the 
    skill-manager
    Skill to record the problem    :
    • Dependent file does not exist: e.g., the observability.log file from dev-observability does not exist
    • Dependent file is unreadable: file exists but cannot be read (permission issues, file corruption, etc.)
    • Dependent file format does not meet requirements: file exists but format does not meet the parsing requirements of this Skill
    • Dependent file content is incomplete: file exists but lacks required fields or data
    • Dependent file quality does not meet requirements: file content quality is insufficient to support effective code analysis
    • Data reading failed: exceptions or errors occur when attempting to read dependent files
    • Data parsing failed: file is read successfully but errors occur during parsing
    • Any other dependency issues that affect the normal execution of this Skill
  • Importance of Problem Recording:
    • The execution of this Skill depends on the output results of other Skills
    • If dependent files do not exist or do not meet requirements, this Skill cannot perform normal analysis
    • Recording these problems can help improve the data output of dependent Skills
    • Provide problem tracking and optimization basis for Skill collaboration
Step 5.3: Problem Recording Format (Mandatory) When calling 
skill-manager
, you must strictly record the problem in the following JSON format:
json
{
  "level": "critical / high / medium / low",
  "message": "[Problem Phenomenon] [Problem Cause] [Problem Impact]"
}
Format Description:
  • level
    (required): Severity of the problem
    • critical
      : Severe problem that completely blocks Skill execution (e.g., critical dependent file missing)
    • high
      : High-priority problem that severely affects Skill functionality (e.g., main dependent file format error)
    • medium
      : Medium-priority problem that affects partial functionality (e.g., optional dependent file missing)
    • low
      : Low-priority problem with minor impact (e.g., partial data incomplete)
  • message
    (required): Problem description, must include three parts
    • [Problem Phenomenon]: Specific description of what problem occurred
    • [Problem Cause]: Analysis of the cause of the problem
    • [Problem Impact]: Explanation of the impact of the problem on the execution of this Skill
Format Examples:
json
{
  "level": "critical",
  "message": "[No observability.log file] [The medium solution (Web interface) of dev-observability Skill does not generate log files] [Cannot perform execution path tracing, this Skill cannot work normally]"
}
json
{
  "level": "medium",
  "message": "[metrics.prom file format is incorrect] [Missing necessary TYPE comment lines] [Cannot parse Prometheus metrics, performance analysis functionality is limited]"
}
json
{
  "level": "high",
  "message": "[observability.log file lacks timestamp field] [Log output configuration is incomplete] [Cannot trace code execution path in chronological order, trace report is incomplete]"
}
Step 5.4: Value Proposition
  • Record data output problems of dependent Skills (such as dev-observability)
  • Help improve data quality and output format of dependent Skills
  • Provide problem tracking and continuous optimization mechanism for Skill collaboration
  • Ensure that this Skill can perform code analysis tasks normally
Step 5.5: Skill Optimization Point Identification and Suggestions (Handled by Agent)
When analyzing identified problems, the agent needs to determine whether they involve Skill optimization points:
Judgment Criteria:
  1. Skill configuration issues: Problems related to Skill configuration information (e.g., SKILL.md lacks required fields, version field is missing, etc.)
  2. Script issues: Problems related to Skill script output (e.g., incorrect log format, missing data fields, etc.)
  3. Documentation issues: Problems related to Skill documentation (e.g., unclear descriptions, incomplete steps, etc.)
  4. Integration issues: Problems related to collaboration between Skills (e.g., incompatible interfaces, inconsistent data formats, etc.)
Examples of Optimization Point Identification:
Example 1: Log Format Issue → Skill Optimization Point
  • Problem description: 
    observability.log file lacks timestamp field
  • Optimization point judgment: Related to log output format of dev-observability Skill
  • Optimization type: Script output optimization
  • Recommended action: Call skill-evolution-driver Skill
Example 2: Configuration Missing Issue → Skill Optimization Point
  • Problem description: 
    SKILL.md of dev-observability lacks version field
  • Optimization point judgment: Related to Skill configuration information
  • Optimization type: Format improvement
  • Recommended action: Call skill-evolution-driver Skill
Example 3: Data Quality Issue → Non-Skill Optimization Point
  • Problem description: 
    Test coverage data is incomplete
  • Optimization point judgment: Belongs to user data issue, not related to the Skill itself
  • Optimization type: Data improvement
  • Recommended action: Remind user to supplement data
Agent Response Process:
  1. Analyze the list of identified problems
    • Traverse all problems recorded in Step 5.2
    • Determine whether each problem involves a Skill optimization point
  2. Identify Skill optimization points
    • If the problem involves Skill configuration, script output, documentation or collaboration
    • Mark it as a Skill optimization point
    • Record the involved Skill name and optimization type
  3. Ask the user If there are Skill optimization points, the agent should ask the user:
    During this code analysis, the following Skill optimization points were identified:

1. Skill: dev-observability
   - Optimization type: Script output optimization
   - Problem: observability.log file lacks timestamp field
   - Impact: Cannot trace code execution path in chronological order

Do you need to call the skill-evolution-driver Skill to handle these optimization points? (y/n)
  4. Handle user selection
    Select y (Yes):
    • Call the skill-evolution-driver Skill
    • Pass the list of optimization points (Skill name, optimization type, problem description)
    • Wait for skill-evolution-driver to perform optimization
    Select n (No):
    • Skip optimization point processing
    • Continue with subsequent steps (such as generating trace report)
    • Suggest that the user can manually call skill-evolution-driver later
Notes:
  • Optimization point identification is an analytical judgment by the agent, not simple keyword matching
  • Need to combine problem context and Skill knowledge for judgment
  • If unsure whether it is a Skill optimization point, consult the user
  • Optimization point identification does not affect the core functionality of this Skill (code analysis)

资源索引

Resource Index

必要脚本

Required Scripts

  • scripts/parse_logs.py
    ：解析结构化日志，提取执行路径、函数调用与异常信息
  • scripts/parse_prometheus.py
    ：解析Prometheus指标数据，提取性能指标
  • scripts/analyze_app_status.py
    ：分析应用模块状态与完成率
  • scripts/analyze_project_data.py
    ：分析项目迭代进度与任务状态
  • scripts/analyze_test_metrics.py
    ：分析测试埋点与异常情况
  • scripts/generate_trace_report.py
    ：整合多维数据，生成全流程可视化追踪报告
  • scripts/parse_logs.py
    : Parse structured logs, extract execution paths, function calls and exception information
  • scripts/parse_prometheus.py
    : Parse Prometheus metric data, extract performance indicators
  • scripts/analyze_app_status.py
    : Analyze application module status and completion rate
  • scripts/analyze_project_data.py
    : Analyze project iteration progress and task status
  • scripts/analyze_test_metrics.py
    : Analyze test tracking points and exception situations
  • scripts/generate_trace_report.py
    : Integrate multi-dimensional data, generate full-process visual trace reports

领域参考

Domain References

  • references/log_format.md
    ：日志格式规范与解析规则（读取时机：解析日志前）
  • references/prometheus_format.md
    ：Prometheus指标格式规范（读取时机：解析指标前）
  • references/json_data_format.md
    ：JSON数据格式规范（读取时机：分析JSON数据前）
  • references/trace_analysis_guide.md
    ：追踪分析指南与方法论（读取时机：生成报告前）
  • references/log_format.md
    : Log format specifications and parsing rules (read before parsing logs)
  • references/prometheus_format.md
    : Prometheus metric format specifications (read before parsing metrics)
  • references/json_data_format.md
    : JSON data format specifications (read before analyzing JSON data)
  • references/trace_analysis_guide.md
    : Trace analysis guidelines and methodologies (read before generating reports)

输出资产

Output Assets

  • assets/trace_templates/execution_trace.md
    ：执行追踪报告模板
  • assets/trace_templates/performance_metrics.md
    ：性能指标报告模板
  • assets/trace_templates/error_analysis.md
    ：异常分析报告模板
  • assets/trace_templates/execution_trace.md
    : Execution trace report template
  • assets/trace_templates/performance_metrics.md
    : Performance metric report template
  • assets/trace_templates/error_analysis.md
    : Exception analysis report template

注意事项

Notes

  • 重要：在获取日志或指标信息前，必须先调用 
    skill-manager
    技能查询调试工具（如dev-observability）的数据存储位置信息
  • 非常重要（强制执行）：在执行过程中，如果发现依赖的输出文件不存在或不符合要求，必须按照步骤5.3的格式调用 
    skill-manager
    技能记录问题
  • 强制执行规则：当依赖文件缺失、不可读、格式错误、内容不完整或质量不满足需要时，必须记录问题，不得跳过
  • 仅在需要时读取参考文档，保持上下文简洁
  • 技术性数据处理优先调用脚本（日志解析、指标提取、报告生成）
  • 问题分析与解决方案生成由智能体完成，充分利用其推理能力
  • 追踪报告采用Markdown格式，便于可视化展示与版本控制
  • 支持渐进式分析：可仅使用日志数据，也可融合多维数据提升分析深度
  • 所有数据文件的路径都必须从 
    skill-manager
    查询调试工具获得
  • 问题记录必须严格按照步骤5.3的JSON格式，包含level和message字段
  • Important: Before obtaining logs or metric information, you must call the 
    skill-manager
    Skill to query the data storage location information of the debugging tool (such as dev-observability)
  • Very Important (Mandatory): During execution, if dependent output files are found to be missing or do not meet requirements, you must call the 
    skill-manager
    Skill to record the problem in the format specified in Step 5.3
  • Mandatory Rule: When dependent files are missing, unreadable, have format errors, incomplete content or insufficient quality, you must record the problem and cannot skip it
  • Read reference documents only when necessary to keep the context concise
  • Prioritize calling scripts for technical data processing (log parsing, metric extraction, report generation)
  • Problem analysis and solution generation are completed by the agent, making full use of its reasoning capabilities
  • Trace reports use Markdown format for easy visualization and version control
  • Support progressive analysis: can use only log data, or integrate multi-dimensional data to improve analysis depth
  • The path of all data files must be obtained from 
    skill-manager
    querying the debugging tool
  • Problem records must strictly follow the JSON format in Step 5.3, including level and message fields

使用示例

Usage Examples

示例 1：基础代码追踪

Example 1: Basic Code Tracing

用户场景："我想看看这个函数是怎么执行的，为什么这么慢" 执行方式：调用skill-manager查询 + 脚本 + 智能体分析 + 运行日志记录 关键步骤：
bash
undefined
User Scenario: "I want to see how this function executes and why it's so slow" Execution Method: skill-manager query + script + agent analysis + running log recording Key Steps:
bash
undefined

1. 调用skill-manager查询调试工具的日志存储路径

1. Call skill-manager to query the log storage path of the debugging tool

（通过智能体调用skill-manager完成）

(Completed by the agent calling skill-manager)

2. 解析日志（使用查询到的实际路径）

2. Parse logs (using the queried actual path)

python3 scripts/parse_logs.py --log-file <查询到的日志路径> --output ./parsed_logs.json
python3 scripts/parse_logs.py --log-file <queried log path> --output ./parsed_logs.json

3. 生成追踪报告

3. Generate trace report

python3 scripts/generate_trace_report.py --logs ./parsed_logs.json --output ./trace_report.md
python3 scripts/generate_trace_report.py --logs ./parsed_logs.json --output ./trace_report.md

4. 智能体分析报告并生成解决方案

4. Agent analyzes the report and generates solutions

5. 数据完整性检查与问题记录

5. Data integrity check and problem recording

如果发现问题，必须按照步骤5.3的格式调用skill-manager记录问题

If problems are found, must call skill-manager to record the problem in the format specified in Step 5.3

undefined
undefined

示例 2：全面代码分析

Example 2: Comprehensive Code Analysis

用户场景："帮我全面分析一下代码的运行情况，看看有没有性能问题或错误" 执行方式：调用skill-manager查询 + 全脚本 + 智能体深度分析 + 运行日志记录 关键步骤：
bash
undefined
User Scenario: "Help me comprehensively analyze the running status of the code to see if there are any performance issues or errors" Execution Method: skill-manager query + full scripts + agent in-depth analysis + running log recording Key Steps:
bash
undefined

1. 调用skill-manager查询调试工具的所有数据文件存储路径

1. Call skill-manager to query the storage paths of all data files of the debugging tool

（通过智能体调用skill-manager完成）

(Completed by the agent calling skill-manager)

2. 解析所有数据源（使用查询到的实际路径）

2. Parse all data sources (using the queried actual path)

python3 scripts/parse_logs.py --log-file <查询到的日志路径> --output ./parsed_logs.json python3 scripts/parse_prometheus.py --prom-file <查询到的metrics路径> --output ./parsed_metrics.json python3 scripts/analyze_app_status.py --input <查询到的app_status路径> --output ./app_analysis.json python3 scripts/analyze_project_data.py --input <查询到的project_data路径> --output ./project_analysis.json python3 scripts/analyze_test_metrics.py --input <查询到的test_metrics路径> --output ./test_analysis.json
python3 scripts/parse_logs.py --log-file <queried log path> --output ./parsed_logs.json python3 scripts/parse_prometheus.py --prom-file <queried metrics path> --output ./parsed_metrics.json python3 scripts/analyze_app_status.py --input <queried app_status path> --output ./app_analysis.json python3 scripts/analyze_project_data.py --input <queried project_data path> --output ./project_analysis.json python3 scripts/analyze_test_metrics.py --input <queried test_metrics path> --output ./test_analysis.json

3. 生成全面分析报告

3. Generate comprehensive analysis report

python3 scripts/generate_trace_report.py
--logs ./parsed_logs.json
--metrics ./parsed_metrics.json
--app-status ./app_analysis.json
--project-data ./project_analysis.json
--test-metrics ./test_analysis.json
--output ./trace_report.md
python3 scripts/generate_trace_report.py
--logs ./parsed_logs.json
--metrics ./parsed_metrics.json
--app-status ./app_analysis.json
--project-data ./project_analysis.json
--test-metrics ./test_analysis.json
--output ./trace_report.md

4. 智能体进行跨维度关联分析，生成综合解决方案

4. Agent performs cross-dimensional correlation analysis and generates comprehensive solutions

5. 数据完整性检查与问题记录

5. Data integrity check and problem recording

检查所有数据是否完整，如有缺失或格式问题，必须按照步骤5.3的格式调用skill-manager记录

Check if all data is complete, if there is any missing or format issue, must call skill-manager to record it in the format specified in Step 5.3

undefined
undefined

示例 3：性能问题排查

Example 3: Performance Problem Troubleshooting

用户场景："代码运行太慢了，帮我找出哪里慢" 执行方式：调用skill-manager查询 + 脚本提取指标 + 智能体分析瓶颈 + 运行日志记录 关键要点：
  • 调用skill-manager查询调试工具的日志和metrics存储路径
  • 解析日志提取函数调用耗时（使用查询到的实际路径）
  • 分析指标数据识别高耗时操作（使用查询到的实际路径）
  • 智能体生成性能优化建议（缓存、并发、算法优化）
  • 检查数据完整性，如果数据缺失或格式错误，调用skill-manager记录问题
User Scenario: "The code runs too slowly, help me find where the bottleneck is" Execution Method: skill-manager query + script metric extraction + agent bottleneck analysis + running log recording Key Points:
  • Call skill-manager to query the log and metrics storage paths of the debugging tool
  • Parse logs to extract function call execution time (using the queried actual path)
  • Analyze metric data to identify high-latency operations (using the queried actual path)
  • Agent generates performance optimization suggestions (caching, concurrency, algorithm optimization)
  • Check data integrity, if data is missing or format is incorrect, call skill-manager to record the problem

示例 4：错误定位

Example 4: Error Location

用户场景："代码运行到一半就报错了，不知道哪里出问题" 执行方式：智能体分析 + skill-manager记录（强制） 关键要点：
  • 检查到日志文件缺失
  • 必须按照步骤5.3的格式调用 
    skill-manager
    记录问题：
json
{
  "level": "critical",
  "message": "【没有 observability.log 文件】【dev-observability技能的中等方案（Web界面）不生成日志文件】【无法进行执行路径追踪，本技能无法正常工作】"
}
问题记录说明：
  • level
    : "critical" - 因为日志文件是本技能的关键依赖，缺失会完全阻塞技能执行
  • message
    : 包含【问题现象】【问题原因】【问题影响】三个部分，符合步骤5.3的格式要求
User Scenario: "The code throws an error halfway through execution and I don't know where the problem is" Execution Method: agent analysis + skill-manager recording (mandatory) Key Points:
  • Detected that the log file is missing
  • Must call 
    skill-manager
    to record the problem in the format specified in Step 5.3:
json
{
  "level": "critical",
  "message": "[No observability.log file] [The medium solution (Web interface) of dev-observability Skill does not generate log files] [Cannot perform execution path tracing, this Skill cannot work normally]"
}
Problem Recording Explanation:
  • level
    : "critical" - because the log file is a key dependency of this Skill, its absence will completely block Skill execution
  • message
    : Includes three parts [Problem Phenomenon] [Problem Cause] [Problem Impact], which meets the format requirements of Step 5.3