virattt/dexter - 项目详情

项目介绍快速开始学习路径项目截图 2 贡献者 7 增长趋势代码统计生态关系项目时间线项目竞品依赖分析上榜历史

学习路径指南

难度等级

中级

预计时长

3-5天

适合人群

有一定TypeScript/JavaScript基础的开发者、对金融数据分析感兴趣的量化分析师、希望了解自主智能体（Agent）工作原理的技术爱好者

学习目标：你将学会如何配置和运行一个金融研究自主智能体，理解其任务分解、自我验证的工作流程，并能利用其评估套件测试智能体的回答准确性。

前置知识

TypeScript/JavaScript基础熟悉

项目使用TypeScript开发，需要能理解基本的语法、模块导入导出和异步编程（Promise/async/await）。

Node.js/Bun运行时了解

项目使用Bun作为运行时，需要了解基本的包管理和脚本运行命令。如果熟悉Node.js，迁移到Bun很容易。

命令行操作了解

需要在终端中执行克隆仓库、安装依赖、设置环境变量和运行项目等操作。

API密钥概念了解

项目运行需要配置多个第三方服务的API密钥（如OpenAI），需要知道如何获取和设置。

金融基础知识（可选）了解 (可选)

了解利润表、资产负债表等基本概念，有助于更好地理解智能体分析的问题和结果，但不是运行项目的硬性要求。

学习步骤

环境与项目准备

1-2小时

安装Bun运行时

根据你的操作系统（macOS/Linux或Windows），按照README中的命令安装Bun。安装后，在终端输入 `bun --version` 验证安装成功。

如果已安装Node.js，Bun可以与其共存。Bun的安装速度很快，提供了更快的包管理工具。

获取必要的API密钥

1. 前往 OpenAI 平台创建API密钥。 2. 前往 Financial Datasets 获取其API密钥。 3. （可选）前往 Exa 获取API密钥以启用网络搜索功能。

建议先获取前两个必选密钥。OpenAI API需要账户有可用额度。妥善保管这些密钥，不要泄露。

克隆项目并安装依赖

1. 在终端中执行 `git clone https://github.com/virattt/dexter.git` 克隆项目。 2. 进入项目目录：`cd dexter`。 3. 运行 `bun install` 安装所有依赖包。

`bun install` 的速度通常比 `npm install` 快很多。如果遇到网络问题，可以尝试配置镜像源。

配置环境变量

在项目根目录创建 `.env` 文件，并按照 `.env.example` 的格式填入你的API密钥：`OPENAI_API_KEY`、`FINANCIAL_DATASETS_API_KEY` 和可选的 `EXA_API_KEY`。

确保 `.env` 文件名前面有一个点。这个文件被 `.gitignore` 排除，不会上传到GitHub，保证了密钥安全。

首次运行与验证

1小时

以交互模式运行Dexter

在项目目录下运行命令 `bun run start`。程序启动后，在终端输入一个简单的金融研究问题，例如：“苹果公司2023年的营收是多少？” 观察智能体的思考、规划和执行过程。

第一次运行可能会因为下载模型或初始化稍慢。观察终端输出的“思考”步骤，这是理解Agent工作逻辑的关键。

探索开发监视模式

运行 `bun run dev` 启动开发模式。尝试修改 `src/` 目录下的某个TypeScript文件（例如一个简单的日志输出），保存后观察程序是否自动重启。

开发模式使用了 `--watch` 标志，方便你进行代码修改和测试。

查看调试记录（Scratchpad）

运行一次查询后，前往 `.dexter/scratchpad/` 目录，找到最新的 `.jsonl` 文件。用文本编辑器打开，查看智能体完整的工具调用记录、原始数据和推理摘要。

这是理解智能体“黑箱”内部运作的最直接方式。JSONL格式可以用支持它的编辑器更好地查看，或者使用 `tail -f` 命令实时跟踪。

理解核心工作流程

3-4小时

分析一个完整查询的日志

提出一个更复杂的问题，如：“对比特斯拉和丰田最近一个季度的毛利率”。运行后，仔细研究scratchpad文件，理解“任务分解 -> 工具执行 -> 结果总结 -> 自我验证/反思 -> 迭代”的完整循环。

关注 `toolresult` 部分，看它具体调用了哪些工具（如 `getIncomeStatement`），以及LLM如何从原始数据中提取摘要。

阅读核心源代码结构

浏览 `src/` 目录的主要文件： 1. `agent/`：智能体的核心逻辑，如规划、反思。 2. `tools/`：定义智能体可以使用的各种数据获取工具。 3. `index.ts`：主程序入口。目标是理解各模块如何通过 `LangChain` 或类似框架组织在一起。

不必深究每一行代码，先把握整体架构。可以配合项目作者的推文或博客（如果有）来理解设计思路。

运行评估套件

执行 `bun run eval:all` 或 `bun run eval:sample`。观察终端出现的实时评估UI，了解智能体在预设问题集上的表现，包括准确率等统计信息。

评估需要调用API，可能会消耗额度和时间。`eval:sample` 是更快的选择。这展示了项目如何系统性地验证其效果。

实践与自定义

4-8小时

尝试修改或添加一个工具

在 `src/tools/` 目录下，参考现有工具（如 `financials.ts`）的格式，创建一个新的工具。例如，创建一个获取新闻头条的工具。然后在 `src/tools/index.ts` 中导出它。

工具通常继承自某个基类，并需要明确定义输入参数（schema）和执行函数（`_call`）。修改后重启应用测试。

调整智能体提示词（Prompt）

在 `src/agent/` 的相关文件中（可能是 `prompts.ts` 或直接写在代码中的字符串），找到定义智能体角色、任务规划、反思逻辑的提示词。尝试微调其中一部分，观察对智能体行为的影响。

每次只修改一小部分，并设计一个测试用例来对比修改前后的输出差异。提示词工程是Agent项目的核心。

构建一个简单的前端界面（可选）

使用简单的Web框架（如Express.js）或静态页面，创建一个HTML表单，允许用户通过网页输入问题，并将请求发送到Dexter后端，最后展示结果。

这能让你将智能体集成到一个更完整的应用中。可以从一个非常简单的、仅回显结果的接口开始。

常见错误与避坑指南

环境变量配置错误

确保 `.env` 文件在项目根目录，且变量名与 `.env.example` 完全一致，并且没有多余的空格或引号。在代码中可以用 `console.log(process.env.OPENAI_API_KEY?.substring(0,5))` 来验证是否成功读取（仅输出前几位以防泄露）。

未安装Bun或版本过低

严格按照README要求安装指定版本（v1.0+）。使用 `bun --version` 检查，如果已安装Node.js，注意命令是 `bun` 而不是 `node` 或 `npm`。

API密钥无额度或权限错误

首先确认OpenAI账户有可用额度。其次，检查Financial Datasets的API密钥是否有效，以及其服务套餐是否包含你要查询的数据（如特定公司的财务报表）。

直接修改 `dist/` 目录下的编译文件

所有源代码修改都应在 `src/` 目录下进行。`dist/` 是编译输出目录，修改会被覆盖。修改 `src/` 后，需要重新运行 `bun run start` 或 `bun run build`。

提出的问题过于模糊或非金融领域

Dexter是专为金融研究设计的，问题应围绕公司财务、市场指标等。尝试从具体、可数据化的问题开始，例如：“微软最新的每股收益（EPS）是多少？”，而不是“微软怎么样？”。

下一步探索

1. **深入研究架构**：分析Dexter如何集成不同的数据源（实时数据、搜索），并学习其安全机制（循环检测）的具体实现。 2. **性能优化**：尝试优化提示词或工具调用逻辑，以减少API调用次数、缩短响应时间或提高答案准确性。 3. **集成与部署**：将Dexter作为服务部署到云服务器（如Railway, Fly.io），并为其构建一个更友好的Web或聊天界面。 4. **领域扩展**：借鉴其架构，尝试构建用于其他垂直领域（如法律研究、医疗文献分析）的自主智能体。 5. **参与贡献**：在GitHub上寻找标记为 `good first issue` 的工单，尝试修复bug或添加小功能，向原作者提交Pull Request。