repo-context-packaging

仓库上下文打包

将仓库整理成一个节省 token 的单一包，方便 Agent 理解：包含目录树、重要文件，不包含任何浪费预算的内容。优化的是 每个 token 的信号量，而非完整性。

适用场景

• 让 Agent 熟悉陌生代码库，以便进行审查、调试或开发功能。
• 仓库无法（或勉强能够）放入上下文，需要精简。
• 生成可粘贴到模型中或附加到任务的便携快照。

如果任务只涉及少数几个已知文件，请直接阅读这些文件。

操作流程

1. 先梳理，再打包

git ls-files | sed 's|/.*||' | sort -u        # top-level layout
git ls-files | wc -l                          # tracked file count
tokei . 2>/dev/null || cloc .                  # size by language

识别架构核心：入口点、主要模块、定义结构的配置。

2. 毫不留情地排除

绝不包含：锁文件、node_modules/vendor/构建产物、.git、压缩/生成的代码、二进制文件、媒体文件、快照/测试夹具、dist/coverage。它们占用了大部分字节，却几乎不包含有效信息。

git ls-files \
  | grep -vE '(lock|min\.|\.map$|/dist/|/build/|/vendor/|\.snap$)' \
  | grep -vE '\.(png|jpg|jpeg|gif|pdf|zip|woff2?|ttf|mp4)$'

如果有工具可用，优先使用：npx repomix 或 files-to-prompt 可以生成结构化打包内容，并采用合理的默认设置——检查它们的排除列表，不要盲目信任。

3. 根据预算分级处理内容

1. 始终包含：目录树、README、主要入口点、公共接口/类型、关键配置。
2. 预算允许时包含：核心业务逻辑模块。
3. 总结，不要内联：大型叶模块、测试、重复的处理器 → 每项用一行说明用途。
4. 仅作引用：以上排除的所有内容。

预先说明 token 预算，并从最低优先级开始删减，直到符合预算。

4. 输出打包内容

# <repo> context bundle

## Structure
<tree, depth-limited>

## Architecture (3–6 sentences: how it fits together, entrypoints, data flow)

## Files
### path/to/file
```<lang>
<contents, or a summary line if tier 3>

未包含内容

<排除的 glob 模式及原因——让 Agent 知道它无法看到什么>

The "Omitted" section is mandatory: an agent that knows what it's missing asks for it instead of hallucinating it.

## Quality bar

- Fits the stated budget with the architecture summary intact.
- A reader can locate where any feature lives from tree + summary alone.
- Zero generated/lock/binary content inlined.
- Omissions are listed, not silent.

## Anti-patterns

- Dumping every file until truncation eats the important ones.
- Inlining lockfiles or `dist/` "for completeness".
- Tree only, no architecture prose — structure without meaning.
- Silent omission, so the agent confidently reasons about code it never saw.