context-pack

Context Pack

将任意代码库、文件夹或 ZIP 归档打包成一个格式清晰的文本块，非常适合放入大模型上下文窗口。支持智能筛选、交互式选择和整洁的 Markdown 输出。

何时使用

在以下情况使用此技能：

• 将整个代码库发送给大模型进行分析或修改
• 与其他 AI Agent 分享项目以进行协作
• 为代码审查或调试创建上下文
• 将文档和代码打包在一起，供 AI 使用
• 将旧项目转换为适合大模型使用的格式

功能

1. 智能发现文件

• 自动查找目录或 ZIP 中的所有文件
• 遵循 .gitignore 规则
• 过滤常见的冗余内容（node_modules、.git、构建产物）
• 处理嵌套目录结构

2. 文件类型检测

• 文本文件：原样包含（代码、文档、配置）
• 二进制文件：可选 Base64 编码（图像、可执行文件、二进制文件）
• 未知文件：智能检测，无法判定时按二进制文件处理

3. 交互式选择

• 打包前预览文件树
• 选择或取消选择特定文件或目录
• 按文件类型、大小或模式筛选
• 查看统计信息（总大小、文件数、Token 估算）

4. 智能格式化

输出格式：

# Context Pack: project-name

## Summary
- Source: /path/to/project
- Files: 42
- Size: 156 KB
- Token estimate: ~50,000

## File Tree

src/ ├── index.ts ├── utils/ │ └── helpers.ts └── components/ └── Button.tsx

## Files

### src/index.ts
```typescript
// File content here...

src/utils/helpers.ts

// File content here...

src/components/Button.tsx

// File content here...

### 5. Binary Handling
```markdown
## Binary Files (Base64 Encoded)

### assets/logo.png
```base64
iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAABhWlDQ1BJQ0MgcHJvZmlsZQAAKJF9kT1I
g1AcxV/TaqVVHuwQxCFDdwURXQQXU8QII0M9k9q0QhGzBjOjog7WFpaCujgEC/pBj6Bg56KOqI4K7gN+
...

## Examples

### Pack a folder
```bash
# Pack current directory
bash scripts/pack.sh .

# Pack specific directory
bash scripts/pack.sh /path/to/myproject

# Pack with binary files included
bash scripts/pack.sh . --include-binary

# Pack with specific file limit
bash scripts/pack.sh . --max-files 50 --max-size 1MB

打包 ZIP 归档

bash scripts/pack.sh project.zip

# Extract and pack
bash scripts/pack.sh archive.zip --extract-to ./temp

筛选文件

# Only include TypeScript files
bash scripts/pack.sh . --include "*.ts" --include "*.tsx"

# Exclude tests
bash scripts/pack.sh . --exclude "*test*" --exclude "*spec*"

# Include only src directory
bash scripts/pack.sh . --include-dir "src"

交互式选择

# Preview and select interactively
bash scripts/pack.sh . --interactive

# This shows a file tree where you can:
# - [x] Select files/folders with checkboxes
# - See file sizes and types
# - Toggle binary inclusion
# - Preview before generating

输出选项

# Output to file
bash scripts/pack.sh . --output project-context.md

# Copy to clipboard (if available)
bash scripts/pack.sh . --clipboard

# JSON output for programmatic use
bash scripts/pack.sh . --format json

文件类型支持

文本文件（默认包含）

• 代码：.js、.ts、.jsx、.tsx、.py、.java、.c、.cpp、.go、.rs、.php、.rb
• Web：.html、.htm、.css、.scss、.sass、.less
• 配置：.json、.xml、.yml、.yaml、.toml、.ini、.conf、.env
• 文档：.md、.txt、.csv、.tsv、.log
• 脚本：.sh、.bash、.zsh、.ps1、.bat

二进制文件（可选 Base64）

• 图像：.png、.jpg、.jpeg、.gif、.svg、.ico、.webp、.bmp
• 可执行文件：.exe、.bin、.app、.dll、.so、.dylib
• 归档：.zip、.tar、.gz、.rar、.7z
• 文档：.pdf、.doc、.docx、.xls、.xlsx、.ppt、.pptx
• 其他：.mp3、.mp4、.wav、.avi、.mov、.ttf、.otf、.woff

脚本

scripts/pack.sh

用于打包的主脚本，支持筛选和输出选项。

bash scripts/pack.sh [OPTIONS] <path>

Options:
  -i, --include PATTERN      Include files matching pattern
  -e, --exclude PATTERN      Exclude files matching pattern
  -d, --include-dir DIR      Include only this directory
  --include-binary            Include binary files as Base64
  --max-files N              Maximum number of files
  --max-size SIZE            Maximum total size (e.g., 10MB, 1GB)
  --max-tokens N             Maximum token estimate
  -o, --output FILE          Output file (default: stdout)
  --format FORMAT            Output format: markdown, json, plain
  --clipboard                Copy output to clipboard
  --interactive              Interactive file selection
  -v, --verbose              Verbose output
  -h, --help                 Show help

scripts/pack-web.sh

启动基于 Web 的交互式文件选择界面。

# Launch web UI
bash scripts/pack-web.sh [path]

# Opens browser with:
# - File tree browser with checkboxes
# - Size statistics
# - Token count estimates
# - Preview before packing

scripts/unpack.sh

将上下文包解压还原为文件。

bash scripts/unpack.sh <context-file> [output-dir]

# Extracts files from markdown format
# Reconstructs directory structure
# Decodes Base64 binary files

输出格式

Markdown（默认）

# Context Pack: my-project

## Summary
- **Source**: /path/to/my-project
- **Packed**: 2024-03-08T10:30:15Z
- **Files**: 42 (38 text, 4 binary)
- **Size**: 156 KB
- **Token Estimate**: ~52,000 tokens

## File Tree

my-project/ ├── src/ │ ├── index.ts │ ├── utils/ │ │ └── helpers.ts │ └── components/ │ └── Button.tsx ├── package.json └── README.md

## Files

### package.json
```json
{
  "name": "my-project",
  "version": "1.0.0",
  "type": "module"
}

src/index.ts

import { Button } from './components/Button';

export function init() {
  const button = new Button('Click me');
  button.render();
}

src/utils/helpers.ts

export function formatDate(date: Date): string {
  return date.toISOString().split('T')[0];
}

二进制文件（Base64 编码）

assets/logo.png

iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAA...

---

使用 Context Pack 技能打包

### JSON Format
```json
{
  "pack": {
    "name": "my-project",
    "source": "/path/to/my-project",
    "packed_at": "2024-03-08T10:30:15Z",
    "stats": {
      "files": 42,
      "text_files": 38,
      "binary_files": 4,
      "size_bytes": 156432,
      "estimated_tokens": 52000
    },
    "file_tree": {
      "name": "my-project",
      "type": "directory",
      "children": [...]
    }
  },
  "files": [
    {
      "path": "package.json",
      "type": "text",
      "size": 234,
      "content": "{...}"
    },
    {
      "path": "src/index.ts",
      "type": "text",
      "size": 567,
      "content": "import..."
    },
    {
      "path": "assets/logo.png",
      "type": "binary",
      "size": 12345,
      "encoding": "base64",
      "content": "iVBORw0KGgo..."
    }
  ]
}

Token 估算

大模型上下文窗口的 Token 数量粗略估算：

文件类型	估算 Token 数
英文文本	每个 Token 约 4 个字符
代码	每个 Token 约 3 个字符
JSON	每个 Token 约 2 个字符
Base64 二进制数据	每个 Token 约 1 个字符

快速估算：

• 1 KB 代码 ≈ 300 个 Token
• 1 KB 文本 ≈ 250 个 Token
• 1 KB Base64 ≈ 1000 个 Token（避免大型二进制文件）

上下文窗口限制：

• GPT-4：约 8K-32K 个 Token
• Claude：约 100K-200K 个 Token
• Gemini：约 1M 个 Token

交互模式

使用 --interactive 时，你会看到用于选择文件的 TUI（文本用户界面）：

Context Pack - Interactive Mode
================================

File Tree (use arrows to navigate, space to select)
[✓] my-project/
  [✓] src/
    [✓] index.ts                                      567 B
    [✓] utils/
      [✓] helpers.ts                                 1.2 KB
    [✓] components/
      [✓] Button.tsx                                  890 B
  [✓] package.json                                  234 B
  [ ] node_modules/                                 [skip]
  [ ] .git/                                         [skip]

Statistics:
  Selected: 5 files, 2.9 KB
  Skipped: 847 files (node_modules, .git)
  Est. tokens: ~9,500

Commands:
  [SPACE] Toggle selection  [A] Select all  [N] None
  [E] Exclude pattern       [I] Include pattern
  [B] Toggle binary files   [P] Preview
  [ENTER] Generate pack     [Q] Quit

备注

• 隐私：所有处理均在本地进行，不会上传任何文件
• 大型代码库：使用 --max-files 和 --max-tokens 将内容控制在限制范围内
• 二进制文件：大型二进制文件会占用大量上下文空间，可考虑将其排除
• Token 数量：估算值仅供参考，实际数量因模型而异
• 优先使用 Markdown：大模型能很好地解析 Markdown 结构
• 文件顺序：文件按路径排序，确保输出一致
• 去重：相同的文件只会包含一次
• 循环引用：会解析并处理符号链接