一套以 REPL 为交互壳、以 query() 为共享执行内核、以权限与任务系统做治理的终端智能体平台
真正要抓住的不是“哪个目录放了什么”，而是三层关系：谁负责装配，谁负责执行，谁负责治理。当前代码最重要的事实是：query.ts 才是共享执行内核，QueryEngine 更像 headless façade，而 REPL 还有自己的一层交互编排。
本页回答什么问题
- 这个仓库到底是 CLI、SDK，还是终端产品运行时？
- 哪些模块是真正的“层”，哪些只是装配点？
- 为什么说它更像模块化单体，而不是严格分层系统？
- 阅读这套代码时，哪些抽象值得当成架构锚点？
系统架构图
这张图展示的是“谁负责装配、谁负责执行、谁负责治理”的真实结构，不是目录树。最关键的代码事实是：src/query.ts 位于中心，而 REPL 与 QueryEngine 只是进入它的两种外壳。
建议的理解分层
入口与生命周期层
src/main.tsx、src/setup.ts、src/entrypoints/init.ts。负责进程入口、会话准备、模式分流与基础设施初始化。
交互壳层
src/screens/REPL.tsx、src/components/*、src/interactiveHelpers.tsx。负责终端 UI、输入提交、权限弹窗与运行态集成。
查询执行层
src/QueryEngine.ts、src/query.ts、src/services/api/claude.ts。其中 query.ts 是共享执行内核，QueryEngine 负责 headless/SDK 路径的会话外壳。
工具与任务层
src/tools.ts、src/Tool.ts、src/services/tools/*、src/Task.ts、src/tasks/*。负责模型可调用能力、工具编排、后台任务与 agent 运行。
扩展与治理层
src/services/mcp/*、src/utils/plugins/*、src/skills/*、src/utils/permissions/*、src/utils/settings/*。负责能力接入、配置、权限和产品治理。
governing ideas
- 共享内核，多入口壳：REPL 和 headless/SDK 最终都进入
query()，但前置上下文装配不同。 - 上下文显式传递，而非 IoC：代码大量依赖
ToolUseContext、AppState、settings 和 runtime context，而不是容器式依赖注入。 - 安全治理内嵌执行链：权限系统并不是执行末端的确认框，而是工具执行协议的一部分。
- 产品形态共存：大量
feature('...')表明同一代码库承载多种版本和运行模式。 - 模块边界逻辑清楚、物理不严：职责分层明显，但跨层协作频繁，属于模块化单体而非强隔离架构。
为什么说它是“模块化单体”
从目录命名看，它像一套分层系统；但从真实调用关系看，REPL.tsx 会直接触达 query、tools、permissions、MCP、tasks、notifications，commands.ts 和 tools.ts 也承担跨来源装配职责。边界存在，但不是靠进程隔离、服务接口或严格的单向依赖来保证，而是靠上下文对象、约定和 feature gate 维持。
两个架构锚点
AppState
它不是狭义 UI state，而是应用运行态容器。任务、MCP、plugins、notifications、session hooks、prompt suggestion、file history 都挂在这里。
ToolUseContext
它是工具层访问应用能力的主要协议。工具之所以能触达任务、MCP、状态、通知、UI，是因为这些能力被放进了同一个上下文对象。
复杂度热点
src/main.tsx：产品模式与入口装配中心。src/commands.ts：命令来源聚合器，不只是 command list。src/tools.ts：工具来源聚合器与启用条件中心。src/screens/REPL.tsx：UI 与运行态总集成壳。src/query.ts：上下文治理、compact、tool loop、budget 的真实状态机。src/utils/*：横切基础设施超级层，吸收了大量治理逻辑。