grepai-chunking 是 GrepAI 的一个技能，覆盖 GrepAI 如何将代码文件拆分为用于嵌入的片段（chunk），以及如何针对代码库优化分块配置。
【用途】 该技能适用于以下场景：优化搜索准确度、根据代码风格（冗长或简洁）调整分块、排查搜索结果问题、理解索引的工作方式。
【分块及其重要性】 分块是把源文件切成更小片段以进行嵌入的过程。例如一个 1000+ token 的大源文件会被切成多个约 512 token 的片段，每个片段获得自己的嵌入。嵌入模型有最佳输入大小：片段过大导致搜索结果不够精确；片段过小则丢失上下文、结果碎片化；合适的大小可在精确度与上下文之间取得平衡。
【配置方式】 在 .grepai/config.yaml 中进行基础配置： chunking: size: 512 # Tokens per chunk overlap: 50 # Overlap between chunks
片段大小（size）是每个片段的目标 token 数。256 更精确但上下文更少；512 为平衡（默认）；1024 上下文更多但精确度更低。重叠（overlap）是相邻片段共享的 token 数，用于保留边界处的上下文。0 表示无重叠，可能丢失边界上下文；50 为标准重叠（默认）；100 上下文更多，索引更大。
【参数可视化与语言建议】 以 size=512、overlap=50 处理一个 1000 token 的 auth.go 为例：片段 1 为 token 1-512，片段 2 为 token 463-974，片段 3 为 token 925-1000，相邻片段之间有 50 token 的重叠。 按语言的推荐设置：冗长语言（Java、C#）建议 size: 768、overlap: 75，以捕获完整方法；简洁语言（Go、Python）建议 size: 512、overlap: 50；极简语言（Rust、Zig）建议 size: 384、overlap: 40，以获得更精确的结果。 按代码库的推荐设置：小函数（微服务）建议 size: 384、overlap: 40，捕获单个函数；大类（单体）建议 size: 768、overlap: 100，捕获更多上下文；混合代码库建议使用平衡默认值 size: 512、overlap: 50。
【Token 计数与索引影响】 GrepAI 使用近似 token 计数：约 4 个字符等于 1 个 token（英文文本），代码会因标识符和语法而有所不同。例如一段 calculateTotal 函数约等于 45 tokens。更大的重叠意味着更多片段和更大索引：512/0 每 10K tokens 约 20 个片段（最小）；512/50 约 22 个（标准）；512/100 约 24 个（+10%）；256/50 约 44 个（+100%）。
【对搜索质量的影响】 片段过小（size: 128）时，查询“authentication middleware”会返回缺少上下文的片段，如“...c.AbortWithStatus(401)...”。合适（size: 512）时会返回带上下文的完整函数。片段过大（size: 2048）时结果会混入多个无关函数，噪声过多。
【试验与调整】 尝试更小片段以获得更精确结果时，可设置 size: 384、overlap: 40，然后重新索引： rm .grepai/index.gob grepai watch 使用 grepai search "your query" 测试，并反复调整直到满意。比较结果时，可在修改设置前保存搜索结果：grepai search "authentication" > before.txt，修改设置并重新索引后执行 grepai search "authentication" > after.txt，再用 diff before.txt after.txt 对比。
【片段边界】 GrepAI 会尽量在逻辑边界处切分：空行（函数/类边界）、闭合括号、语句结尾。这意味着实际片段大小可能略偏离目标值。
【最佳实践】 从默认值开始（512/50 适用于大多数代码库）；根据代码风格调整（冗长=更大，简洁=更小）；用真实查询测试；修改后必须重新索引以重新生成嵌入；慎重考虑重叠，除非索引大小非常关键，否则不要设为 0。
【常见问题与解决】 搜索结果过于碎片化：增大片段大小（size: 768）。搜索结果包含过多无关上下文：减小片段大小（size: 384）。结果遗漏函数边界处的相关代码：增大重叠（overlap: 100）。索引过大：减小重叠、增大片段大小、增加更多忽略模式。
【输出格式】 分块状态输出示例包括：Size: 512 tokens、Overlap: 50 tokens；索引统计包括文件总数、片段总数、平均每文件片段数、平均片段大小；以及相关建议。