Skip to content

13-source-research-playbook.md

Latest commit

 

History

History
193 lines (128 loc) · 5.32 KB

13-source-research-playbook.md

File metadata and controls

193 lines (128 loc) · 5.32 KB

13. 源码研究操作手册

这篇讲什么

这一章不是讲产品怎么用，而是讲研究者如何高效读懂这份快照：从哪开始找、用什么命令搜、如何追踪一个功能的完整链路。

先给结论

面对这类大型源码快照，最有效的方法不是“顺读”，而是“从注册表和类型开始，按链路向实现钻”。对于本仓库，最重要的四个锚点是：

  • src/main.tsx
  • src/commands.ts
  • src/tools.ts
  • src/QueryEngine.ts

Mermaid 图：源码研究方法流程图

flowchart TD
    A[研究问题] --> B[找注册表 / 总入口]
    B --> C[看类型定义与 schema]
    C --> D[查 feature flag / isEnabled / availability]
    D --> E[进入具体实现]
    E --> F[回看状态层与服务层]
    F --> G[形成结论]
    G --> H[记录源码事实与边界]
Loading

源码研究的基础原则

1. 先看总入口，再看子目录

不要一开始就钻进 src/commands/ 或 src/tools/ 的某个子目录。先看谁在注册、谁在过滤、谁在装配。

2. 先看类型，再看分支

本仓库大量逻辑受类型和 schema 驱动。读 src/types/command.ts、src/Tool.ts、src/types/permissions.ts 的收益非常高。

3. 先查 feature flag

看到一个功能时，马上搜索它有没有被 feature('...') 包住。否则你很容易把实验功能误当默认能力。

4. 先确认来源，再谈行为

很多命令和技能不是 built-in，而是来自 plugin、bundled、skills、MCP。先确认来源，再解释行为。

一套高效的研究流程

步骤 1：确认仓库边界

先看：

然后确认顶层结构：

ls -la
find src -maxdepth 2 -type d | sort

步骤 2：建立能力总表

先看注册中心：

sed -n '1,220p' src/main.tsx
sed -n '1,220p' src/commands.ts
sed -n '1,220p' src/tools.ts

然后统计 feature flag：

rg -n "feature\\('" src/main.tsx src/commands.ts src/tools.ts

步骤 3：追一个 slash command

例子：想追 /plugin

sed -n '1,160p' src/commands/plugin/index.tsx
rg -n "name: 'plugin'|name: \"plugin\"" src/commands/plugin

然后进入实现文件和相关 UI。

步骤 4：追一个 tool

例子：想追 AgentTool

rg -n "export const AgentTool" src/tools/AgentTool
sed -n '1,260p' src/tools/AgentTool/AgentTool.tsx

如果还想看整个工具面：

find src/tools -maxdepth 1 -mindepth 1 | wc -l
sed -n '1,260p' src/tools.ts

步骤 5：追权限链

sed -n '1,200p' src/types/permissions.ts
sed -n '1,220p' src/utils/permissions/PermissionMode.ts
sed -n '1,260p' src/utils/permissions/permissionSetup.ts

步骤 6：追扩展链

技能：

sed -n '1,220p' src/skills/loadSkillsDir.ts

插件：

sed -n '1,220p' src/utils/plugins/loadPluginCommands.ts
sed -n '1,220p' src/types/plugin.ts

MCP：

sed -n '1,220p' src/services/mcp/client.ts
sed -n '1,220p' src/services/mcp/config.ts

LSP：

sed -n '1,220p' src/services/lsp/manager.ts

步骤 7：追远程链

sed -n '1,220p' src/bridge/bridgeMain.ts
sed -n '1,220p' src/remote/RemoteSessionManager.ts

研究不同主题时的起手式

主题 第一锚点 第二锚点
启动链路 src/main.tsx src/replLauncher.tsx
命令系统 src/commands.ts src/types/command.ts
工具系统 src/tools.ts src/Tool.ts
权限 src/types/permissions.ts src/utils/permissions/permissionSetup.ts
UI/REPL src/screens/REPL.tsx src/state/AppStateStore.ts
多代理 src/tools/AgentTool/AgentTool.tsx src/commands/tasks/index.ts
插件/skills src/skills/loadSkillsDir.ts src/utils/plugins/loadPluginCommands.ts
MCP src/services/mcp/client.ts src/services/mcp/config.ts
Remote/Bridge src/bridge/bridgeMain.ts src/remote/RemoteSessionManager.ts

研究时最容易踩的坑

1. 只看目录名，不看注册表

你会看到很多目录，以为功能已经启用，但实际上它可能受 feature gate 控制，或者根本不在当前命令/工具列表里。

2. 把 commands/ 和 tools/ 混为一谈

命令是用户入口，工具是执行能力。这两个层级不能混看。

3. 忽略快照边界

如果某个行为依赖远程服务、OAuth、IDE、remote worker，本仓库只能说明结构，不能单凭静态代码证明它“当前一定可运行”。

4. 忽略状态层

很多行为不是在单个命令文件里闭合，而是会更新 AppState、任务状态、权限上下文、MCP 客户端列表等。

推荐输出模板

如果你要写研究笔记、分享或报告，建议每个专题都按以下模板整理：

  1. 目标能力是什么。
  2. 它的入口文件是什么。
  3. 它是否受 feature flag 控制。
  4. 它依赖哪些状态或外部系统。
  5. 哪些内容能被源码确认，哪些只能推断。

这一章的工作结论

对这类大型 agentic CLI 快照，最重要的研究能力不是“会不会读 TypeScript”，而是能不能迅速找到注册点、状态边界和 feature gate。只要这三件事做对，阅读成本会骤降。