packx

PACKX - AI 上下文打包器

为 AI 上下文打包并筛选代码文件。

关键：始终使用 --limit 49k

强制要求：除非用户明确要求不同的限制值，否则每条 packx 命令都必须包含 --limit 49k。这一点没有商量余地。使用 49k 而非 50k 可提供安全缓冲。

# CORRECT - always include --limit 49k
packx --limit 49k -c src/
packx --limit 49k -s "pattern" -i "*.ts" -c

# WRONG - never omit the limit
packx -c src/                        # NO! Missing --limit
packx -s "pattern" -i "*.ts" -c      # NO! Missing --limit

前置条件

packx --version    # Verify installed
npm install -g packx   # If not installed

标准命令模式

packx --limit 49k [filters] [output] [paths]

始终以 --limit 49k 开头，然后添加筛选器和输出选项。

命令行参考

Token 预算（必填）

# Standard (default for all commands)
packx --limit 49k -c src/

# Only use different limits if user explicitly requests
packx --limit 32k -c src/            # User said "32k"
packx --limit 128k -c src/           # User said "large context"

# Split into chunks if content exceeds limit (requires -o for numbered files)
packx -M 49k -o context src/         # Creates context-1.xml, context-2.xml

限制格式： 8k=8,000 | 32K=32,768 | 50000=50,000

搜索与筛选

# Find files containing text
packx --limit 49k -s "TODO" -c
packx --limit 49k -s "useState" -i "*.tsx" -c
packx --limit 49k -s "error" -s "warning" -c

# Exclude content
packx --limit 49k -S "test" -S "mock" -c

# Filter by glob patterns
packx --limit 49k -i "*.ts" -c
packx --limit 49k -i "src/**/*.tsx" -c
packx --limit 49k -x "*.test.ts" -x "*.spec.ts" -c

# Regex patterns
packx --limit 49k -R -s "function\s+\w+" -c

# Case-sensitive
packx --limit 49k -C -s "Error" -c

Git 集成

packx --limit 49k --staged -c        # Staged files
packx --limit 49k --diff -c          # Changed from main
packx --limit 49k --dirty -c         # Modified/untracked

处理选项

# Strip comments (reduces tokens)
packx --limit 49k --strip-comments -c src/

# Minify (remove empty lines)
packx --limit 49k --minify -c src/

# Both (maximum token efficiency)
packx --limit 49k --strip-comments --minify -c src/

# Context lines around matches
packx --limit 49k -s "TODO" -l 5 -c

# Follow imports
packx --limit 49k --follow-imports src/index.ts -c

# Related files (tests, stories)
packx --limit 49k -r src/utils.ts -c

输出选项

# Copy to clipboard (most common)
packx --limit 49k -c src/

# Save to file (use --stdout > to avoid WriteFile hook limits)
packx --limit 49k --stdout src/ > context.md

# Output formats
packx --limit 49k -f xml -c src/         # XML (default)
packx --limit 49k -f markdown -c src/    # Markdown
packx --limit 49k -f plain -c src/       # Plain text
packx --limit 49k -f jsonl -c src/       # JSONL

重要： 始终使用 --stdout > <file> 而非 --output <file>，以避免触发 WriteFile hook 对大型打包文件的大小限制。

预览（打包前检查）

# Preview matching files without packing
packx --limit 49k --preview src/
packx --limit 49k -s "pattern" --preview

交互模式

packx --limit 49k -I src/            # Interactive selection
packx --limit 49k --no-interactive src/  # Scripting mode

控制键： Tab=预览焦点 | PgUp/PgDn=滚动 | Enter=确认

打包配置（已保存的配置）

packx -b api                         # Load .pack/bundles/api

常见工作流

默认：功能上下文

# Most common - search for feature, copy to clipboard
packx --limit 49k -s "auth" -i "*.ts" -c

PR 审查上下文

packx --limit 49k --diff -c
packx --limit 49k --staged -f markdown --stdout > pr.md

调试上下文

packx --limit 49k --follow-imports src/problem.ts -c
packx --limit 49k -r src/problem.ts -c    # Include tests

最小上下文（最高效率）

packx --limit 49k --strip-comments --minify -i "*.ts" -c src/

特定文件

# List specific files directly
packx --limit 49k src/auth.ts src/user.ts src/api.ts -c

最佳实践

1. 始终使用 --limit 49k - 除非用户指定，否则没有例外
2. 使用 -c 复制到剪贴板 - 最常用的输出方式
3. 先预览 - 使用 --preview 检查文件选择
4. 去除噪音 - 在 token 紧张时使用 --strip-comments --minify
5. 保持具体 - 使用 -s 搜索和 -i glob 缩小范围
6. 检查 git 状态 - 使用 --diff 和 --staged 获取 PR 上下文

疑难解答

问题	解决方案
Token 过多	添加 -i "*.ts"、-x "test" 或 --strip-comments
文件缺失	检查 glob，使用 --preview
需要超过 49k	使用 -M 49k -o output 拆分（会创建带编号的文件）
WriteFile hook 错误	使用 --stdout > file.md 而非 --output file.md