mcpField
D
debug-cli

debug-cli

github.com/tailcallhq开发7.6k69 次安装今天更新
代码仓库

关于 debug-cli

debug-cli 是面向 forge CLI 开发者的调试与变更验证技能，提供构建和测试流程，并要求克隆对话后再复现问题。

主要功能

  1. 01使用 cargo build 调试构建
  2. 02查看最新命令帮助
  3. 03用 -p 运行非交互测试
  4. 04将对话导出为 JSON 或 HTML
  5. 05复现前克隆对话

适用场景

  1. 01验证 forge CLI 新命令
  2. 02复现已报告的对话问题
  3. 03检查提示词与对话输出

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/tailcallhq/forgecode --skill debug-cli

安装后在 Claude Code 中输入/debug-cli确认已加载。

附带文件scripts/README.mdscripts/test_cli.sh

详细介绍

CLI 调试技能

本技能提供了一套系统化工作流，用于调试和验证对 forge CLI 应用程序所做的更改。

核心原则

  1. 始终先获取最新文档：运行 --help 查看当前命令和选项
  2. 使用 -p 进行测试：使用 -p 标志向 forge 分配任务来进行测试
  3. 切勿提交：这仅用于调试——不要提交更改
  4. 克隆对话：调试对话问题时，先克隆源对话，再复现问题

工作流

1. 构建应用程序

进行更改后，始终以调试模式构建：

cargo build

调试时切勿使用 cargo build --release——它会显著拖慢速度，对验证也没有必要。

2. 获取最新文档

始终先查看最新帮助信息，了解当前命令和选项：

# Main help - do this first
./target/debug/forge --help

# Command-specific help
./target/debug/forge [COMMAND] --help

# Subcommand help
./target/debug/forge [COMMAND] [SUBCOMMAND] --help
3. 使用 -p 标志进行测试

使用 -p 标志向 forge 分配任务，无需进入交互模式即可完成：

# Test with a simple prompt
./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"

# Test with complex tasks
./target/debug/forge -p "analyze the code structure and suggest improvements"
4. 使用对话转储进行调试

调试提示词或对话问题时，使用 conversation dump 导出对话。该命令会自动创建带时间戳的文件：

# Dump conversation as JSON (creates: YYYY-MM-DD_HH-MM-SS-dump.json)
./target/debug/forge conversation dump <conversation-id>

# Export as HTML for human-readable format (creates: YYYY-MM-DD_HH-MM-SS-dump.html)
./target/debug/forge conversation dump --html <conversation-id>

# Use dumped JSON to reproduce issues
./target/debug/forge --conversation 2025-11-23_12-28-52-dump.json
5. 复现 Bug 前先克隆

重要：用户提供包含 Bug 的对话时，务必先克隆：

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

# This creates a new conversation ID - use that for testing
./target/debug/forge --conversation-id <new-cloned-id>

# Keep cloning the source until the fix is verified
# Never modify the original conversation

为什么要克隆？

  • 保留原始 Bug 证据
  • 支持多次尝试复现
  • 可以对修复进行 A/B 测试
  • 保持源对话不受影响

常见测试模式

测试新功能
# 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"
复现报告的 Bug
# 1. Dump the conversation (creates timestamped JSON file)
./target/debug/forge conversation dump <bug-conversation-id>

# 2. Clone it for testing (preserves original)
./target/debug/forge conversation clone <bug-conversation-id>

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

# 4. After fix, verify with new clone
./target/debug/forge conversation clone <bug-conversation-id>
./target/debug/forge --conversation-id <new-clone-id> -p "verify fix"
测试边缘情况
# Test with missing arguments
./target/debug/forge command

# Test with invalid input
./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..."
调试提示词优化
# 1. Dump conversation to analyze prompts (creates timestamped JSON)
./target/debug/forge conversation dump <id>

# 2. Review the conversation structure
cat 2025-11-23_12-28-52-dump.json | jq '.messages[] | {role, content}'

# 3. Export as HTML for easier reading
./target/debug/forge conversation dump --html <id>

# 4. Test modified prompts
./target/debug/forge -p "your optimized prompt here"

与开发工作流集成

代码更改后
  1. 构建：cargo build
  2. 文档：./target/debug/forge --help（验证文档）
  3. 测试：./target/debug/forge -p "relevant task"
  4. 验证：检查输出是否符合预期
调试 Bug 报告
  1. 克隆：./target/debug/forge conversation clone <source-id>
  2. 构建：cargo build（包含可能的修复）
  3. 测试：./target/debug/forge --conversation-id <cloned-id> -p "reproduce"
  4. 迭代：重复上述步骤，直到验证通过
  5. 调试期间切勿提交——只有在全面验证后才能提交

快速参考

# Standard debug workflow
cargo build
./target/debug/forge --help  # Always check docs first
./target/debug/forge -p "your test task"

# Dump conversation (creates timestamped file)
./target/debug/forge conversation dump <id>
# Output: 2025-11-23_12-28-52-dump.json

# Export as HTML for review
./target/debug/forge conversation dump --html <id>
# Output: 2025-11-23_12-28-52-dump.html

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

# Clone and test 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)
cat 2025-11-23_12-28-52-dump.json | jq '.messages[] | {role, content}'

# Test with verbose output
./target/debug/forge --verbose -p "test task"

提示

  • 始终先运行 --help：测试前获取最新文档
  • 使用 -p 进行测试：不要交互式测试，使用提示词
  • 克隆对话：切勿修改原始 Bug 对话
  • 切勿提交：这仅用于调试
  • 转储会创建文件：dump 会自动创建带时间戳的文件（无需使用 >）
  • HTML 导出：使用 --html 标志查看便于阅读的对话
  • 使用相对路径：从项目根目录运行时，二进制文件位于 ./target/debug/forge
  • 检查退出代码：使用 echo $? 验证退出代码
  • 留意警告：构建警告通常意味着存在问题

评论

支持 Markdown