Skip to content

02-repo-map-and-reading-order.md

Latest commit

 

History

History
158 lines (120 loc) · 4.96 KB

02-repo-map-and-reading-order.md

File metadata and controls

158 lines (120 loc) · 4.96 KB

02. 目录导览与阅读顺序

这篇讲什么

这一章把 src/ 里的主要目录压缩成一张“查找地图”，告诉你想看什么时应该先去哪里。

先给结论

如果你只记住一条规则，请记住：

  • 想找用户入口，看 main.tsx 和 commands.ts。
  • 想找模型能做什么，看 tools.ts 和 Tool.ts。
  • 想找系统如何跑起来，看 QueryEngine.ts、AppStateStore.ts、screens/REPL。
  • 想找扩展能力，看 skills/、plugins/、services/mcp/、services/lsp/。
  • 想找安全边界，看 utils/permissions/。

主要目录速查

路径 关注点
src/main.tsx 全局入口，启动和初始化总控
src/commands.ts 所有 slash command 的统一注册与过滤
src/tools.ts 所有 tool 的统一注册与启用逻辑
src/Tool.ts tool 相关核心类型和上下文
src/QueryEngine.ts 会话执行主循环
src/components/ 可复用 UI 组件
src/screens/ 主要页面级界面
src/state/ 全局状态定义和状态变更
src/services/ 外部系统与跨模块服务层
src/utils/ 底层通用工具和基础设施
src/bridge/ Bridge 和远程控制链路
src/remote/ 远程会话管理
src/tasks/ 任务模型与任务运行时
src/skills/ 技能体系
src/plugins/ 内建插件与插件配套逻辑

Mermaid 图：阅读路径图

flowchart TD
    A[开始阅读] --> B[路线 A\n总览]
    A --> C[路线 B\n用户交互]
    A --> D[路线 C\n执行与安全]
    B --> B1[main.tsx]
    B --> B2[commands.ts]
    B --> B3[tools.ts]
    B --> B4[QueryEngine.ts]
    C --> C1[main.tsx]
    C --> C2[replLauncher.tsx]
    C --> C3[App.tsx]
    C --> C4[REPL]
    D --> D1[QueryEngine.ts]
    D --> D2[Tool.ts]
    D --> D3[tools.ts]
    D --> D4[permissions]
Loading

关键目录的实际角色

src/commands/

这是 slash command 的实现目录。用户在 REPL 中输入 /help、/login、/doctor、/plugin、/mcp、/tasks 等，最终都会落到这里。

src/tools/

这是模型/系统调用的动作能力层。比命令更底层、更通用，也更接近“执行器”。

src/services/

这里通常放跨功能的服务接口，例如：

  • api/
  • mcp/
  • oauth/
  • plugins/
  • analytics/
  • compact/
  • policyLimits/

src/utils/

这是底层支撑层，覆盖：

  • 权限
  • 文件系统
  • git
  • 设置
  • 插件
  • shell
  • sandbox
  • telemetry
  • task
  • worktree

src/bridge/ 与 src/remote/

这两块都和“远程/外部控制”相关，但角度不同：

  • bridge/ 更像面向 IDE/远程控制的桥接基础设施。
  • remote/ 更像一个会话管理客户端。

src/skills/ 与 src/plugins/

这是两个非常值得关注的扩展面：

  • skills/ 倾向于基于 markdown/frontmatter 的能力注入。
  • plugins/ 则更像安装包/市场/内置插件体系。

三种推荐阅读顺序

路线 A：10 分钟认识全局

  1. src/main.tsx
  2. src/commands.ts
  3. src/tools.ts
  4. src/QueryEngine.ts
  5. src/state/AppStateStore.ts

路线 B：研究用户交互

  1. src/main.tsx
  2. src/replLauncher.tsx
  3. src/components/App.tsx
  4. src/screens/REPL.*
  5. src/commands.ts
  6. src/commands/<具体命令>/

路线 C：研究执行与安全

  1. src/QueryEngine.ts
  2. src/Tool.ts
  3. src/tools.ts
  4. src/utils/permissions/PermissionMode.ts
  5. src/utils/permissions/permissionSetup.ts

按问题定位文件

你想回答的问题 先看哪里
启动时先做了什么 src/main.tsx
某个命令为什么会出现或消失 src/commands.ts
某个工具是否受 feature flag 控制 src/tools.ts
权限模式有哪些 src/types/permissions.ts
子代理怎么启动 src/tools/AgentTool/AgentTool.tsx
技能从哪里加载 src/skills/loadSkillsDir.ts
插件命令如何变成 slash command src/utils/plugins/loadPluginCommands.ts
MCP 配置从哪里来 src/services/mcp/config.ts
LSP 何时初始化 src/services/lsp/manager.ts
Remote 会话怎么连接 src/remote/RemoteSessionManager.ts

阅读时的高性价比技巧

  • 先看注册表，再看实现目录。
  • 先看类型定义，再看具体分支逻辑。
  • 先找 feature flag，再判断功能是不是默认启用。
  • 先找“是否可见/是否启用”的过滤函数，再看界面层。

这四条规则在本仓库里非常有效，因为很多功能不是简单地“有文件就启用”，而是会经过 availability、isEnabled、feature gate、权限模式、登录状态等多重过滤。