ECC 性能优化实战指南：模型选择、上下文窗口管理与扩展思维调优-平芜编程栈

ECC 性能优化实战指南：模型选择、上下文窗口管理与扩展思维调优

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC

导读

本文基于 docs/ja-JP/rules/common/performance.md 整理而成，面向使用 ECC（The agent harness performance optimization system）的开发者，讲解在 Claude Code、Codex 等 Harness 环境中降低 Token 成本、提升多 Agent 协作效率的完整方案。你将掌握三层能力：按任务类型选择 Haiku/Sonnet/Opus 的模型分层策略、通过上下文窗口管理与MAX_THINKING_TOKENS等环境变量控制隐性成本，以及使用build-error-resolverAgent 快速修复构建失败的标准流程。

一、模型选择策略：让每个任务跑在最合适的模型上

原文档给出的核心原则是"按任务复杂度分层选模型"，避免为简单任务支付过高推理成本，也避免让轻量模型承担深度推理任务。

Haiku 4.5：高频轻量任务的成本担当

定位：约具备 Sonnet 功能的 90%，但成本仅为三分之一（3 倍成本节省，原文表述为 "コスト 3 分の 1"）。
适用场景：
- 频繁调用的轻量 Agent；
- 结对编程与代码生成（快速生成、快速校验）；
- 多 Agent 系统中的 Worker Agent（只做有限、明确的子任务）。

Sonnet 5：日常编码的主力模型

定位：最佳编码模型（"最高のコーディングモデル"）。
适用场景：
- 主开发工作（日常 CRUD、业务逻辑实现）；
- 多 Agent 工作流的编排（Orchestration）；
- 复杂编码任务（需要理解多文件关联但不需极端推理深度）。

Opus 5：深度推理的保留席位

定位：推理深度最强（"最も深い推論"）。
适用场景：
- 复杂架构决策；
- 最大推理需求的任务；
- 研究与分析类任务。

仓库源码印证：模型分层在 ECC 中的落地

ECC 在src/llm/providers/claude.py中定义了各模型的规格与能力，这正是文档所述策略的底层实现依据：

模型 ID	上下文窗口	最大输出	备注
`claude-opus-4-8`	1,000,000	64,000	使用`thinking: {"type": "adaptive"}`自适应思维（见 src/llm/providers/claude.py）
`claude-sonnet-4-6`	1,000,000	64,000	源码中`_DEFAULT_MODEL`默认值，即 ECC 的默认模型
`claude-haiku-4-5`	200,000	16,000	轻量快速，适合 Worker 场景

注意：当前仓库实际注册的模型为 Opus 4.8 / Sonnet 4.6 / Haiku 4.5（见 src/llm/cli/selector.py），与文档中的 4.5/5/5 世代命名略有差异，本文以仓库实际模型为准。仓库同时将 Opus 系列（claude-opus-4-7、claude-opus-4-8）标记为"仅自适应思维"（_uses_adaptive_thinking_only），即这类模型不再手动控制 temperature，而是由模型自行决定思维深度。

Agent 级模型分配的实际证据：在 agents/ 目录下，每个 Agent 的 frontmatter 都显式声明model字段：

Opus 级（深度推理）：architect、planner、spec-miner、healthcare-reviewer；
Sonnet 级（日常编码）：code-reviewer、build-error-resolver、a11y-architect等绝大多数 Agent；
Haiku 级（轻量查找/文档）：docs-lookup、comment-analyzer、conversation-analyzer、doc-updater、opensource-forker。

这种"Agent 元数据直接绑定模型"的设计，让多 Agent 系统在编排时天然实现文档所述的模型分层，无需每次手动切换。

二、上下文窗口管理：避免在"最后 20%"窗口内执行高敏感任务

大语言模型的输出质量在上下文窗口尾部会显著衰减。文档给出的经验法则是：当上下文填充接近窗口末尾的 20% 时，避免执行对上下文敏感的任务。

高上下文敏感任务（应避免在尾部 20% 执行）

大规模重构（需同时理解多个文件的调用关系）；
跨多文件的 Feature 实现；
复杂交互的 Debug（错误可能由早期上下文中的某段代码引发）。

低上下文敏感任务（可在尾部执行）

单文件编辑；
独立工具函数创建；
文档更新；
简单 Bug 修复。

配套的上下文管理实操（来自仓库指南）

README.md 的 Token Optimization 一节给出了日常会话命令：

命令	使用时机
`/model sonnet`	大多数任务默认起点
`/model opus`	复杂架构、调试、深度推理
`/clear`	无关任务之间（免费、即时重置）
`/compact`	逻辑断点处（调研完成、里程碑达成）
`/cost`	会话期间监控 Token 花费

配合 docs/token-optimization.md 的"战略压缩"建议：在探索之后、实现之前，在调试完成之后、开启新工作之前主动/compact；而在多文件重构进行中、活跃问题调试中则不要压缩。

另一个保护主上下文的有效手段是子 Agent 隔离：用子 Agent（Task 工具）去读取大量文件，子 Agent 读完 20 个文件后只向主会话返回摘要，主上下文保持干净——这正是文档"多 Agent 系统"策略的延伸。

三、扩展思维（Extended Thinking）+ 计划模式（Plan Mode）

什么是扩展思维

扩展思维默认启用，为内部推理预留最多31,999 个输出 Token。这些 Token 不直接出现在最终回答中，但对复杂任务的正确性至关重要。

控制扩展思维的四种方式

控制手段	操作
开关切换	`Option+T`（macOS）/`Alt+T`（Windows/Linux）
配置文件	在`~/.claude/settings.json`中设置`alwaysThinkingEnabled`
预算上限	bash：`export MAX_THINKING_TOKENS=10000`；PowerShell：`$env:MAX_THINKING_TOKENS = "10000"`
详细模式	`Ctrl+O`显示思考输出

深度推理任务的推荐流程

确认扩展思维已启用（默认启用）；
启用**计划模式（Plan Mode）**以获得结构化方法；
使用多轮批评（Critique）进行彻底分析；
使用角色分工的子 Agent 获得多样视角。

预算调优：隐性成本可削减约 70%

扩展思维虽默认预留学生思维 Token 高达 31,999，但很多日常任务并不需要这么深的推理。仓库文档与 README 一致推荐将其下调：

{ "model": "sonnet", "env": { "MAX_THINKING_TOKENS": "10000", "CLAUDE_CODE_SUBAGENT_MODEL": "haiku" } }

配置项	默认值	推荐值	影响
`model`	opus	sonnet	约 60% 成本削减；可处理 80%+ 编码任务
`MAX_THINKING_TOKENS`	31,999	10,000	单次请求隐性思维成本降低约 70%
`CLAUDE_CODE_SUBAGENT_MODEL`	继承主模型	haiku	子 Agent 用于探索、读文件、跑测试，Haiku 便宜约 80%
`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`	95	50	更早触发压缩，长会话质量更好

依据 README.md 与 docs/token-optimization.md。需要说明：MAX_THINKING_TOKENS设为0可对琐碎任务完全禁用扩展思维；CLAUDE_AUTOCOMPACT_PCT_OVERRIDE存在社区反馈——某些 Claude Code 版本中它只能降低阈值（即比默认更早压缩而非更晚），若遇到该问题建议移除覆盖并依赖手动/compact（详见 docs/TROUBLESHOOTING.md 与 docs/token-optimization.md）。

会话中途切换模型

/model sonnet # 大多数工作默认 /model opus # 复杂推理 /model haiku # 快速查找

四、构建故障排查（Build Troubleshooting）

当构建失败时，文档给出的标准流程是：

使用build-error-resolverAgent；
分析错误信息；
分步修正；
每次修正后验证。

Agent 定义与职责边界

agents/build-error-resolver.md 明确定义了该 Agent：

frontmatter：model: sonnet、工具集Read, Write, Edit, Bash, Grep, Glob；
核心使命：以最小改动让构建通过——"No refactoring, no architecture changes, no improvements"；
职责范围：TypeScript 类型错误、编译失败、模块解析、依赖问题（导入错误、缺失包、版本冲突）、配置错误（tsconfig、webpack、Next.js）；
最小 Diff 原则：禁止重构无关代码、禁止改动架构、禁止新增功能，改动行数控制在受影响文件的 5% 以内。

诊断命令与常见修复

npx tsc --noEmit --pretty npx tsc --noEmit --pretty --incremental false # 显示全部错误 npm run build npx eslint . --ext .ts,.tsx,.js,.jsx

常见错误对照表（摘自 Agent 文档）：

错误	修复
`implicitly has 'any' type`	添加类型注解
`Object is possibly 'undefined'`	可选链`?.`或空值检查
`Property does not exist`	加入 interface 或使用可选`?`
`Cannot find module`	检查 tsconfig paths、安装包或修正导入路径
`Type 'X' not assignable to 'Y'`	类型转换或修正类型
`Generic constraint`	添加`extends { ... }`
`Hook called conditionally`	将 Hook 移到顶层
`'await' outside async`	添加`async`关键字

错误优先级与快速恢复

级别	症状	行动
CRITICAL	构建完全损坏、无 Dev Server	立即修复
HIGH	单文件失败、新代码类型错误	尽快修复
MEDIUM	Linter 警告、弃用 API	条件允许时修复

快速恢复手段：清空缓存（.next、node_modules/.cache）后重建；重装依赖；用npx eslint . --fix处理可自动修复项。

与其他 Agent 的交接边界

构建问题交给build-error-resolver，但当问题性质变化时应换人：

需要重构 →refactor-cleaner；
需要架构变更 →architect；
需要新功能 →planner；
测试失败 →tdd-guide；
安全问题 →security-reviewer。

在 AGENTS.md 的 Build troubleshooting 一节中也固化了同一流程："Use build-error-resolver agent → analyze errors → fix incrementally → verify after each fix"，说明这一排查流程已内化为 ECC 的整体 Agent 工作约定。

五、成本与性能监控速查

将上述策略整合为日常运维清单：

# 日常工作流 /model sonnet # 大多数任务起点 /model opus # 仅在复杂推理时切换 /clear # 无关任务之间 /compact # 逻辑断点处 /cost # 监控花费 # 环境变量（写入 ~/.claude/settings.json 的 "env" 块） MAX_THINKING_TOKENS=10000 CLAUDE_CODE_SUBAGENT_MODEL=haiku

订阅用户若觉得上下文监控器的 API 费用估算与真实账单不符，可仅关闭面向 Agent 的费用警告（保留上下文耗尽、范围、循环警告）：

export ECC_CONTEXT_MONITOR_COST_WARNINGS=off

Windows PowerShell：

[Environment]::SetEnvironmentVariable('ECC_CONTEXT_MONITOR_COST_WARNINGS', 'off', 'User')

ECC 性能优化实战指南：模型选择、上下文窗口管理与扩展思维调优