abc/analysis_claude_code
1
0
Fork 0
mirror of https://github.com/shareAI-lab/analysis_claude_code.git synced 2026-06-21 04:33:36 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #346 from Gui-Yue/document-read-file-compact-tradeoff

Browse Source 
Document read_file compact trade-off
This commit is contained in:
gui-yue
2026-06-03 22:54:39 +08:00
committed by GitHub
parent 91682fa7fc ae94cda0ed
commit 7c385819cd
3 changed files with 24 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
s08_context_compact/README.en.md
View File

@@ -252,6 +252,12 @@ The real order in CC source `query.ts`:
The teaching version's budget → snip → micro order matches this. The teaching version does not have the contextCollapse mechanism. The teaching version's budget → snip → micro order matches this. The teaching version does not have the contextCollapse mechanism.
### read_file Trade-off
The teaching version's `micro_compact` replaces old `tool_result` blocks with placeholders uniformly, including `read_file`. This usually does not affect functional correctness: if the model needs the file contents later, it can read the file again. The cost is an extra tool call and potentially lower prompt cache hit rates.
Claude Code does not solve this with the teaching version's simple rule. It also puts `Read` in the microcompactable tool set, but maintains a separate `readFileState`: repeated reads of unchanged files return `FILE_UNCHANGED_STUB`, and after compaction it restores recently read file contents within a budget (for example, up to 5 files, 5K tokens per file, 50K tokens total). That is a production-level cache and recovery mechanism. The teaching version does not expand into that machinery; it keeps the simpler trade-off of compacting old results and re-reading when needed.
### Full Constant Reference ### Full Constant Reference
| Constant | Value | Source File | | Constant | Value | Source File |
@@ -282,6 +288,7 @@ CC's compression prompt has two hard requirements:
### Teaching Version Simplifications Are Intentional ### Teaching Version Simplifications Are Intentional
- micro_compact uses text placeholders → we don't have API-level `cache_edits` access - micro_compact uses text placeholders → we don't have API-level `cache_edits` access
- read_file is not special-cased → the teaching version accepts re-reading when needed instead of introducing readFileState and post-compaction recovery
- Tokens estimated via character count → precise tokenizers are out of scope - Tokens estimated via character count → precise tokenizers are out of scope
- Post-compaction recovery omitted → teaching version only keeps summary, does not auto re-attach files - Post-compaction recovery omitted → teaching version only keeps summary, does not auto re-attach files
- Two auxiliary mechanisms not covered → they fall in the 10% detail category - Two auxiliary mechanisms not covered → they fall in the 10% detail category
@@ -290,4 +297,4 @@ The core design principle, cheap first, expensive last, is fully preserved.
</details> </details>
<!-- translation-sync: zh@v1, en@v1, ja@v1 --> <!-- translation-sync: zh@v2, en@v2, ja@v2 -->

9
s08_context_compact/README.ja.md
View File

@@ -252,6 +252,12 @@ CC ソース `query.ts` での実際の順序：
教学版の budget → snip → micro の順序はこれと一致する。教学版には contextCollapse メカニズムがない。 教学版の budget → snip → micro の順序はこれと一致する。教学版には contextCollapse メカニズムがない。
### read_file のトレードオフ
教学版の `micro_compact` は、古い `tool_result` を一律にプレースホルダへ置き換える。`read_file` も例外ではない。これは通常、機能的な正しさには影響しない。後でファイル内容が必要になれば、モデルはもう一度そのファイルを読めばよい。代償は、追加のツール呼び出しが発生し得ることと、prompt cache のヒット率が下がり得ること。
Claude Code は、この問題を教学版のような単純なルールでは処理していない。`Read` も microcompact 可能なツール集合に入れる一方で、別途 `readFileState` を維持している。変更されていないファイルの再読込では `FILE_UNCHANGED_STUB` を返し、compact 後には予算内で直近に読んだファイル内容を復元する（例：最大 5 ファイル、1 ファイル 5K token、合計 50K token）。これは本番実装向けのキャッシュと復元メカニズムである。教学版ではそこまで展開せず、「古い結果を圧縮し、必要なら再読込する」という単純な trade-off を残している。
### 完全な定数リファレンス ### 完全な定数リファレンス
| 定数 | 値 | ソースファイル | | 定数 | 値 | ソースファイル |
@@ -282,6 +288,7 @@ CC の圧縮プロンプトには 2 つの厳格な要件がある：
### 教学版の簡略化は意図的 ### 教学版の簡略化は意図的
- micro_compact でテキストプレースホルダを使用 → API 層の `cache_edits` 権限がないため - micro_compact でテキストプレースホルダを使用 → API 層の `cache_edits` 権限がないため
- read_file は特別扱いしない → 教学版では必要時の再読込を受け入れ、readFileState と圧縮後復元の仕組みを導入しない
- token を文字数で推定 → 精密な tokenizer は教学の対象外 - token を文字数で推定 → 精密な tokenizer は教学の対象外
- 圧縮後のリカバリを省略 → 教学版は要約のみを保持し、ファイルの自動再付加を行わない - 圧縮後のリカバリを省略 → 教学版は要約のみを保持し、ファイルの自動再付加を行わない
- 2 つの補助メカニズムを展開しない → 10% の細部に属する - 2 つの補助メカニズムを展開しない → 10% の細部に属する
@@ -290,4 +297,4 @@ CC の圧縮プロンプトには 2 つの厳格な要件がある：
</details> </details>
<!-- translation-sync: zh@v1, en@v1, ja@v1 --> <!-- translation-sync: zh@v2, en@v2, ja@v2 -->

9
s08_context_compact/README.md
View File

@@ -252,6 +252,12 @@ CC 源码 `query.ts` 中的真实顺序：
教学版的 budget → snip → micro 顺序与此一致。教学版没有 contextCollapse 机制。 教学版的 budget → snip → micro 顺序与此一致。教学版没有 contextCollapse 机制。
### read_file 的取舍
教学版的 `micro_compact` 会把旧 `tool_result` 统一替换成占位符，包括 `read_file`。这通常不影响功能正确性：如果后续还需要文件内容，模型可以重新读一次。代价是可能多一次工具调用，也可能降低 prompt cache 命中率。
Claude Code 没有用教学版这种简单规则解决这个问题。它把 `Read` 也放进可 microcompact 的工具集合，但同时维护 `readFileState`：重复读取未变化文件时返回 `FILE_UNCHANGED_STUB`，compact 后再按预算恢复最近读过的文件内容（例如最多 5 个文件、每个 5K token、总预算 50K token）。这是生产级实现里的缓存和恢复机制，教学版不展开，保留“压缩旧结果，必要时重新读取”的简单 trade-off。
### 完整常量参考 ### 完整常量参考
| 常量 | 值 | 源文件 | | 常量 | 值 | 源文件 |
@@ -282,6 +288,7 @@ CC 的压缩 prompt 有两个硬性要求：
### 教学版的简化是刻意的 ### 教学版的简化是刻意的
- micro_compact 用文本占位 → 我们没有 API 层的 `cache_edits` 权限 - micro_compact 用文本占位 → 我们没有 API 层的 `cache_edits` 权限
- read_file 不特殊处理 → 教学版接受必要时重新读取，避免引入 readFileState 和后压缩恢复机制
- token 用字符数估算 → 精确 tokenizer 不在教学范围内 - token 用字符数估算 → 精确 tokenizer 不在教学范围内
- 后压缩恢复省略 → 教学版只保留摘要，不自动重新附加文件 - 后压缩恢复省略 → 教学版只保留摘要，不自动重新附加文件
- 两个辅助机制不展开 → 属于 10% 的细节 - 两个辅助机制不展开 → 属于 10% 的细节
@@ -290,4 +297,4 @@ CC 的压缩 prompt 有两个硬性要求：
</details> </details>
<!-- translation-sync: zh@v1, en@v1, ja@v1 --> <!-- translation-sync: zh@v2, en@v2, ja@v2 -->