评估
强在平台化与治理，弱在顶层装配复杂度、隐式耦合和 feature 矩阵膨胀
这套代码已经具备产品级终端 agent 平台的关键能力，但这些能力几乎都在同一棵运行内核里叠加，导致顶层装配和横切依赖越来越重。真正的风险不是“代码不高级”，而是“组合复杂度越来越难被局部理解”。
本页回答什么问题
- 这套架构真正强在哪里？
- 哪些设计是有意识的 trade-off，而不是偶然堆出来的？
- 最危险的复杂度热点在哪里？
- 未来改动时，哪些区域最容易引入回归？
架构优势
- 共享内核清晰：
query.ts作为共享执行内核，让 REPL 与 headless 路径至少在 turn 逻辑上复用同一机制。 - 产品治理意识强：permissions、classifier、sandbox、cleanup、profiling、migration、transcript 恢复等都不是后补丁，而是执行链的一部分。
- 扩展通路明确：plugins、MCP、skills 三条路径虽然分开，但边界意图清晰，各自面向不同问题域。
- 恢复性设计存在：
QueryEngine预写 transcript、REPL 提交前刷新工具集、任务/agent 有清理路径，说明作者在为长会话和异常中断做设计。
主要 trade-offs
- 选择显式上下文而非 IoC：好处是调用链透明、类型可见；代价是
ToolUseContext和AppState容易膨胀成巨型接口。 - 选择单体运行时而非服务拆分：好处是交互延迟和本地能力整合更自然；代价是顶层装配复杂、跨层依赖变多。
- 选择大量 feature gate：好处是同一代码库承载多产品形态；代价是测试矩阵和行为推理成本急剧增加。
主要弱点
src/main.tsx、src/commands.ts、src/tools.ts、src/screens/REPL.tsx都是明显的复杂度中心，承担的装配责任已经接近产品级路由器。src/utils/*体量巨大，容易继续吸收新的横切逻辑，削弱模块边界。AppState与ToolUseContext过重，使局部修改经常牵动多个系统。feature('...')与动态加载共同导致“代码存在但未必可达”的情况增加，提升阅读和测试难度。
隐藏约束
- transcript 必须在进入真正模型循环前写入，否则 headless 恢复语义会变弱。
- REPL 必须在提交前重新读取 tools/MCP，否则长期运行组件会持有过期能力集合。
- 工具默认不是并发安全、不是只读，这会直接影响调度策略和权限压力。
- MCP server 是否可见不仅取决于本地配置，还受企业/托管设置和 connector 去重影响。
最难安全修改的区域
src/query.ts
牵涉模型流、compact、tool_use、budget、fallback，任何改动都可能改变 turn 级语义。
src/services/tools/toolExecution.ts
工具执行与权限、hooks、telemetry、tool result storage 的交汇点，容易产生“局部看合理、全局出回归”的问题。
src/screens/REPL.tsx
运行态总集成壳，局部改动极易对消息流、任务、通知或 compact 产生副作用。
技术债判断
最大的技术债不是代码风格，而是产品能力叠加带来的组合复杂度：
- 命令来源越来越多，聚合器越来越重。
- 工具类型越来越多，权限与并发治理更难统一推理。
- 运行模式越来越多，启动与配置分支更难穷举验证。
- 扩展通路越来越多，插件、MCP、skills 之间的边界需要持续维护。