Back to Details

debug-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

CLI Debug Skill

CLI调试技能

This skill provides a systematic workflow for debugging and verifying changes to the forge CLI application.
本技能为调试和验证forge CLI应用的更改提供了系统化的工作流。

Core Principles

核心原则

  1. Always get latest docs first: Run 
    --help
    to see current commands and options
  2. Use 
    -p
    for testing    : Test forge by giving it tasks with the 
    -p
    flag
  3. Never commit: This is for debugging only - don't commit changes
  4. Clone conversations: When debugging conversation bugs, clone the source conversation before reproducing
  1. 先获取最新文档：运行
    --help
    查看当前命令和选项
  2. 使用
    -p
    进行测试    ：通过
    -p
    标志给forge分配任务来进行测试
  3. 切勿提交代码：这仅用于调试 - 不要提交更改
  4. 克隆对话：调试对话相关bug时，先克隆源对话再复现问题

Workflow

工作流

1. Build the Application

1. 构建应用

Always build in debug mode after making changes:
bash
cargo build
Never use 
cargo build --release
for debugging - it's significantly slower and unnecessary for verification.
修改代码后，始终以调试模式构建：
bash
cargo build
绝对不要在调试时使用
cargo build --release
——它的速度明显更慢，而且验证时完全没必要。

2. Get Latest Documentation

2. 获取最新文档

Always start by checking the latest help to understand current commands and options:
bash
undefined
务必先查看最新帮助文档，了解当前的命令和选项：
bash
undefined

Main help - do this first

主帮助文档 - 先执行这个

./target/debug/forge --help
./target/debug/forge --help

Command-specific help

命令专属帮助文档

./target/debug/forge [COMMAND] --help
./target/debug/forge [COMMAND] --help

Subcommand help

子命令帮助文档

./target/debug/forge [COMMAND] [SUBCOMMAND] --help
undefined
./target/debug/forge [COMMAND] [SUBCOMMAND] --help
undefined

3. Test with 
-p
Flag

3. 使用
-p
标志进行测试

Use the 
-p
flag to give forge a task to complete without interactive mode:
bash
undefined
使用
-p
标志给forge分配任务，无需进入交互模式：
bash
undefined

Test with a simple prompt

用简单提示测试

./target/debug/forge -p "create a hello world rust program"
./target/debug/forge -p "create a hello world rust program"

Test with specific functionality

测试特定功能

./target/debug/forge -p "read the README.md file and summarize it"
./target/debug/forge -p "read the README.md file and summarize it"

Test with complex tasks

测试复杂任务

./target/debug/forge -p "analyze the code structure and suggest improvements"
undefined
./target/debug/forge -p "analyze the code structure and suggest improvements"
undefined

4. Debug with Conversation Dumps

4. 借助对话转储调试

When debugging prompts or conversation issues, use 
conversation dump
to export conversations. The command automatically creates a timestamped file:
bash
undefined
调试提示词或对话相关问题时，使用
conversation dump
导出对话。该命令会自动创建带时间戳的文件：
bash
undefined

Dump conversation as JSON (creates: YYYY-MM-DD_HH-MM-SS-dump.json)

将对话导出为JSON（生成：YYYY-MM-DD_HH-MM-SS-dump.json）

./target/debug/forge conversation dump <conversation-id>
./target/debug/forge conversation dump <conversation-id>

Export as HTML for human-readable format (creates: YYYY-MM-DD_HH-MM-SS-dump.html)

导出为HTML格式以便人类阅读（生成：YYYY-MM-DD_HH-MM-SS-dump.html）

./target/debug/forge conversation dump --html <conversation-id>
./target/debug/forge conversation dump --html <conversation-id>

Use dumped JSON to reproduce issues

使用导出的JSON对话复现问题

./target/debug/forge --conversation 2025-11-23_12-28-52-dump.json
undefined
./target/debug/forge --conversation 2025-11-23_12-28-52-dump.json
undefined

5. Clone Before Reproducing Bugs

5. 复现bug前先克隆对话

Critical: When a user provides a conversation with a bug, always clone it first:
bash
undefined
关键步骤：当用户提供存在bug的对话时，务必先克隆它：
bash
undefined

Clone the conversation

克隆对话

./target/debug/forge conversation clone <source-conversation-id>
./target/debug/forge conversation clone <source-conversation-id>

This creates a new conversation ID - use that for testing

这会生成一个新的对话ID - 使用该ID进行测试

./target/debug/forge --conversation-id <new-cloned-id>
./target/debug/forge --conversation-id <new-cloned-id>

Keep cloning the source until the fix is verified

在修复验证完成前，持续克隆源对话

Never modify the original conversation

绝对不要修改原始对话


**Why clone?**

- Preserves original bug evidence
- Allows multiple reproduction attempts
- Enables A/B testing of fixes
- Keeps source conversation clean

**为什么要克隆？**

- 保留原始bug证据
- 允许多次复现尝试
- 支持修复方案的A/B测试
- 保持源对话干净无修改

Common Testing Patterns

常见测试模式

Test New Features

测试新功能

bash
undefined
bash
undefined

Build and test new command

构建并测试新命令

cargo build ./target/debug/forge --help # Verify new command appears ./target/debug/forge new-command --help # Check command docs ./target/debug/forge -p "test the new feature"
undefined
cargo build ./target/debug/forge --help # 验证新命令是否显示 ./target/debug/forge new-command --help # 检查命令文档 ./target/debug/forge -p "test the new feature"
undefined

Reproduce Reported Bugs

复现上报的bug

bash
undefined
bash
undefined

1. Dump the conversation (creates timestamped JSON file)

1. 导出对话（生成带时间戳的JSON文件）

./target/debug/forge conversation dump <bug-conversation-id>
./target/debug/forge conversation dump <bug-conversation-id>

2. Clone it for testing (preserves original)

2. 克隆对话用于测试（保留原始对话）

./target/debug/forge conversation clone <bug-conversation-id>
./target/debug/forge conversation clone <bug-conversation-id>

3. Reproduce with the cloned conversation

3. 使用克隆的对话复现问题

./target/debug/forge --conversation-id <cloned-id> -p "reproduce the issue"
./target/debug/forge --conversation-id <cloned-id> -p "reproduce the issue"

4. After fix, verify with new clone

4. 修复后，用新克隆的对话验证

./target/debug/forge conversation clone <bug-conversation-id> ./target/debug/forge --conversation-id <new-clone-id> -p "verify fix"
undefined
./target/debug/forge conversation clone <bug-conversation-id> ./target/debug/forge --conversation-id <new-clone-id> -p "verify fix"
undefined

Test Edge Cases

测试边缘情况

bash
undefined
bash
undefined

Test with missing arguments

测试缺失参数的情况

./target/debug/forge command
./target/debug/forge command

Test with invalid input

测试无效输入

./target/debug/forge -p "invalid task with special chars: <>|&"
./target/debug/forge -p "invalid task with special chars: <>|&"

Test with boundary values

测试边界值

./target/debug/forge -p "create a file with a very long name..."
undefined
./target/debug/forge -p "create a file with a very long name..."
undefined

Debug Prompt Optimization

调试提示词优化

bash
undefined
bash
undefined

1. Dump conversation to analyze prompts (creates timestamped JSON)

1. 导出对话以分析提示词（生成带时间戳的JSON）

./target/debug/forge conversation dump <id>
./target/debug/forge conversation dump <id>

2. Review the conversation structure

2. 查看对话结构

cat 2025-11-23_12-28-52-dump.json | jq '.messages[] | {role, content}'
cat 2025-11-23_12-28-52-dump.json | jq '.messages[] | {role, content}'

3. Export as HTML for easier reading

3. 导出为HTML以便更易阅读

./target/debug/forge conversation dump --html <id>
./target/debug/forge conversation dump --html <id>

4. Test modified prompts

4. 测试修改后的提示词

./target/debug/forge -p "your optimized prompt here"
undefined
./target/debug/forge -p "your optimized prompt here"
undefined

Integration with Development Workflow

与开发工作流集成

After Code Changes

代码修改后

  1. Build: 
    cargo build
  2. Docs: 
    ./target/debug/forge --help
    (verify documentation)
  3. Test: 
    ./target/debug/forge -p "relevant task"
  4. Verify: Check output matches expectations
  1. 构建：
    cargo build
  2. 文档：
    ./target/debug/forge --help
    （验证文档）
  3. 测试：
    ./target/debug/forge -p "relevant task"
  4. 验证：检查输出是否符合预期

Debugging a Bug Report

调试bug报告

  1. Clone: 
    ./target/debug/forge conversation clone <source-id>
  2. Build: 
    cargo build
    (with potential fixes)
  3. Test: 
    ./target/debug/forge --conversation-id <cloned-id> -p "reproduce"
  4. Iterate: Repeat until verified
  5. Never commit during debugging - only after full verification
  1. 克隆：
    ./target/debug/forge conversation clone <source-id>
  2. 构建：
    cargo build
    （包含潜在修复）
  3. 测试：
    ./target/debug/forge --conversation-id <cloned-id> -p "reproduce"
  4. 迭代：重复直到验证通过
  5. 切勿提交：调试期间不要提交代码 - 仅在完全验证后提交

Quick Reference

快速参考

bash
undefined
bash
undefined

Standard debug workflow

标准调试工作流

cargo build ./target/debug/forge --help # Always check docs first ./target/debug/forge -p "your test task"
cargo build ./target/debug/forge --help # 始终先检查文档 ./target/debug/forge -p "your test task"

Dump conversation (creates timestamped file)

导出对话（生成带时间戳的文件）

./target/debug/forge conversation dump <id>
./target/debug/forge conversation dump <id>

Output: 2025-11-23_12-28-52-dump.json

输出：2025-11-23_12-28-52-dump.json

Export as HTML for review

导出为HTML以便查看

./target/debug/forge conversation dump --html <id>
./target/debug/forge conversation dump --html <id>

Output: 2025-11-23_12-28-52-dump.html

输出：2025-11-23_12-28-52-dump.html

Use dumped conversation

使用导出的对话

./target/debug/forge --conversation 2025-11-23_12-28-52-dump.json
./target/debug/forge --conversation 2025-11-23_12-28-52-dump.json

Clone and test bug

克隆并测试bug

./target/debug/forge conversation clone <source-id> ./target/debug/forge --conversation-id <cloned-id> -p "reproduce bug"
./target/debug/forge conversation clone <source-id> ./target/debug/forge --conversation-id <cloned-id> -p "reproduce bug"

Debug prompts with jq (use actual filename)

使用jq调试提示词（使用实际文件名）

cat 2025-11-23_12-28-52-dump.json | jq '.messages[] | {role, content}'
cat 2025-11-23_12-28-52-dump.json | jq '.messages[] | {role, content}'

Test with verbose output

带详细输出的测试

./target/debug/forge --verbose -p "test task"
undefined
./target/debug/forge --verbose -p "test task"
undefined

Tips

提示

  • Always 
    --help
    first    : Get latest docs before testing
  • Use 
    -p
    for testing    : Don't test interactively, use prompts
  • Clone conversations: Never modify original bug conversations
  • Never commit: This is for debugging only
  • Dump creates files: 
    dump
    automatically creates timestamped files (no 
    >
    needed)
  • HTML exports: Use 
    --html
    flag for human-readable conversation views
  • Use relative paths: Binary is at 
    ./target/debug/forge
    from project root
  • Check exit codes: Use 
    echo $?
    to verify exit codes
  • Watch for warnings: Build warnings often indicate issues
  • 始终先执行
    --help
    ：测试前先获取最新文档
  • 使用
    -p
    进行测试    ：不要在交互模式下测试，使用提示词
  • 克隆对话：永远不要修改原始bug对话
  • 切勿提交代码：这仅用于调试
  • 导出会生成文件：
    dump
    会自动生成带时间戳的文件（无需使用
    >
    ）
  • HTML导出：使用
    --html
    标志获取人类可读的对话视图
  • 使用相对路径：二进制文件位于项目根目录下的
    ./target/debug/forge
  • 检查退出码：使用
    echo $?
    验证退出码
  • 注意构建警告：构建警告通常预示着问题