仓库体量与重心

当前 src/ 一共约 1902 个文件，重心非常明显：

• src/utils/：564 个文件，承担权限、文件系统、git、sandbox、telemetry、插件、prompt 等横切能力
• src/components/：389 个文件，终端 UI 组件很多，说明交互层很重
• src/commands/：207 个文件，命令系统非常丰富
• src/tools/：184 个文件，模型可调用工具是核心能力面
• src/services/：130 个文件，承接 API、MCP、LSP、compact、analytics、tool orchestration 等服务

这意味着它更像一个“终端中的应用平台”，而不是一组零散脚本。

总体架构图

用户 / CLI / SDK / Desktop

src/main.tsx
启动、参数解析、模式分流

src/entrypoints/init.ts
配置、环境、遥测、清理注册

src/commands.ts
命令注册与启用判断

src/replLauncher.tsx
挂载 App + REPL

src/QueryEngine.ts
无头 / SDK 会话封装

src/state/*
AppState + createStore

src/ink.ts + src/ink/* + src/components/* + src/screens/REPL.tsx
终端渲染与交互

src/query.ts
模型查询与 tool_use 闭环

src/services/api/*
模型与平台 API

src/tools.ts
内建工具 + MCP 工具装配

src/services/tools/*
并发调度、权限、hooks、执行

src/tools/*
Bash / File / Agent / Skill / Web / MCP

src/Task.ts + src/tasks/*
Shell / LocalAgent / RemoteAgent / Workflow

src/services/mcp/*
src/utils/plugins/*
src/skills/*

src/bridge/* + src/remote/* + src/server/*
远程会话、桥接、直连

一次请求的主执行流

UserREPL / QueryEnginequery()services/api/*runTools()ToolTask输入文本 / 触发命令组装 messages / systemPrompt / toolUseContext发起模型流式请求assistant 消息 / tool_use按批次调度工具调用串行或并行执行长任务后台化或子 Agent 化输出 / 进度 / 状态tool_result / progress / context 更新携带 tool_result 继续推理最终 assistant 输出消息、状态、成本、错误UI 刷新或结构化输出UserREPL / QueryEnginequery()services/api/*runTools()ToolTask

这条链路在源码中的关键落点是：

• src/screens/REPL.tsx：交互式入口直接驱动 query()
• src/QueryEngine.ts：无头模式对会话生命周期做封装，再调用 query()
• src/query.ts：维护消息流、compact、tool_use 循环
• src/services/tools/toolOrchestration.ts：决定工具串行还是并发
• src/services/tools/toolExecution.ts：真正执行单个工具，并处理权限、hooks、进度、结果

模块拆分

层级	主要目录 / 文件	作用	说明
启动装配层	src/main.tsx、src/entrypoints/init.ts、src/bootstrap/*	程序启动、配置加载、环境变量处理、模式分流	是所有运行形态的总入口
状态中心	src/state/*、src/context/*、src/history.ts	全局状态、订阅、通知、会话信息	使用自定义 store，而不是 Redux 一类框架
终端 UI 层	src/ink.ts、src/ink/*、src/components/*、src/screens/REPL.tsx	Ink 渲染、输入处理、终端交互	UI 复杂度很高，说明 REPL 是一等公民
命令层	src/commands.ts、src/commands/*、src/types/command.ts	/command、本地命令、Local JSX 命令	命令分 prompt、local、local-jsx 三类
查询内核	src/query.ts、src/QueryEngine.ts	管理消息、系统提示词、模型请求、tool loop	REPL 与 SDK 共用这一层核心逻辑
工具定义层	src/Tool.ts、src/tools.ts、src/tools/*	工具 schema、权限、并发安全、具体实现	assembleToolPool() 是工具装配中枢
工具执行层	src/services/tools/*	工具调度、hooks、权限决策、结果落盘、并发控制	真正把模型输出的 tool_use 执行起来
任务 / Agent 层	src/Task.ts、src/tasks.ts、src/tasks/*	shell、子 agent、远程 agent、workflow 生命周期管理	把长耗时动作抽成可跟踪任务
CLI 适配层	src/cli/*	非交互输出、结构化 IO、传输适配	面向 SDK、SSE、WebSocket 等宿主
扩展层	src/services/mcp/*、src/utils/plugins/*、src/skills/*	MCP 连接、插件发现与加载、技能注入	外部能力的主要接入口
远程 / 桥接层	src/bridge/*、src/remote/*、src/server/*	远程会话、bridge worker、直连会话	说明它不只服务本地单机 REPL
横切基础设施	src/utils/*、src/services/*	git、文件、telemetry、sandbox、permissions、LSP 等	这是仓库最大的公共能力层

核心抽象

1. Command

命令是“用户入口”级别的能力，定义在 src/types/command.ts，主要分三类：

• prompt：把命令转成 prompt 内容，交给模型继续执行
• local：本地逻辑命令
• local-jsx：会渲染终端 UI 的本地命令

这说明命令系统负责“进入哪条流程”，而不是直接承担底层执行。

2. Tool

工具是“模型在推理过程中可调用的原子能力”，核心定义在 src/Tool.ts 和 src/tools.ts。
典型工具包括：

• BashTool
• FileReadTool
• FileEditTool
• AgentTool
• SkillTool
• WebSearchTool
• MCP 相关工具

Command 和 Tool 是这套架构里最重要的一次分层：

• Command 负责入口与意图转换
• Tool 负责模型可调用的底层动作

3. Task

Task 是长时操作的统一载体，定义在 src/Task.ts。已经能看到的任务类型包括：

• local_bash
• local_agent
• remote_agent
• in_process_teammate
• local_workflow
• monitor_mcp
• dream

这意味着项目天然支持“前台对话 + 后台执行 + 结果回流”。

4. AppState

src/state/AppStateStore.ts 把消息、任务、MCP、插件、通知、权限、agent 定义等状态都收进一个中心 store。
src/state/store.ts 则是一个非常轻量的自定义 store 实现。

这层设计让它可以同时服务：

• 终端 UI 渲染
• 工具执行上下文
• 任务状态刷新
• 插件 / MCP 接入后的动态状态变化

5. Skill

src/tools/SkillTool/SkillTool.ts 表明 Skill 不是单纯的文档目录，而是一类可执行能力：

• 可以作为命令被加载
• 可以以内联 prompt 的方式运行
• 也可以 fork 成子 agent 执行
• 还能与插件和 MCP 技能一起进入命令空间

所以 Skill 更接近“高阶能力模板”，而不是纯静态说明文件。