小德子调研：仔细阅读 Dexter 仓库的完整源码，输出一份详细中文调研报告。要求：1) 项目定位与核心功能 2

一、项目定位与核心功能

Dexter 是一个面向个人用户的自主金融研究 Agent，定位是"终端里的 Claude Code，但专为金融研究而生"。它不是一个简单的 RAG 问答系统，而是一个具备完整 ReAct 循环（推理→工具调用→观察→迭代）的自主 Agent。

核心功能：

• 金融数据查询：股价、财务报表（三张表）、关键比率、分析师预测、内幕交易、SEC 文件全文
• 股票筛选：自然语言描述筛选条件，自动转换为结构化 API 过滤器
• DCF 估值：内置 8 步 DCF 工作流 Skill，含敏感性分析矩阵
• 网络研究：Exa/Perplexity/Tavily 搜索 + Playwright 浏览器 + web_fetch 静态页面读取
• X/Twitter 情绪研究：专用 Skill，多轮搜索 + 情绪分类
• 持久记忆：SQLite + 向量嵌入 + BM25 混合检索，支持时间衰减和 MMR 去重
• 定时任务（Cron）：支持 at/every/cron 三种调度，含指数退避和抑制去重
• WhatsApp 网关：通过 Baileys 库接入 WhatsApp，支持群聊 @mention 触发
• 多轮对话：InMemoryChatHistory + LLM 相关性筛选，跨轮注入历史上下文

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

二、技术栈与依赖

运行时：Bun（主要），兼容 Node.js（gateway 用 tsx 运行）

核心框架：

• @langchain/core — 工具抽象（DynamicStructuredTool、StructuredToolInterface）、消息类型、Runnable 链
• @langchain/openai/anthropic/google-genai/ollama — 各 LLM provider 适配器
• zod v4 — 所有工具 schema 和结构化输出的类型验证

UI：

• @mariozechner/pi-tui — 纯 TypeScript 的终端 UI 框架（非 Ink/React，注意 README 描述有误）

数据库：

• bun:sqlite（Bun 环境）/ better-sqlite3（Node 环境）— 记忆系统的向量+FTS5 索引

WhatsApp：

• @whiskeysockets/baileys 7.0.0-rc.9 — WhatsApp Web 协议实现

其他关键依赖：

• playwright — 浏览器自动化（postinstall 自动安装 Chromium）
• croner — Cron 表达式解析与调度
• @mozilla/readability + linkedom — HTML 内容提取
• gray-matter — SKILL.md YAML frontmatter 解析
• exa-js — Exa 搜索 SDK
• langsmith — 评估追踪（可选）
• diff — 文件编辑 diff 工具

版本：CalVer 格式（2026.3.25），当前版本显示项目仍在活跃开发中。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

三、核心架构与代码流程（逐文件分析）

3.1 整体架构图

src/index.tsx
└── src/cli.ts (runCli)
├── AgentRunnerController (controllers/agent-runner.ts)
│ └── Agent.create() → Agent.run() [agent/agent.ts]
│ ├── buildSystemPrompt() [agent/prompts.ts]
│ ├── callLlm() [model/llm.ts]
│ ├── AgentToolExecutor [agent/tool-executor.ts]
│ │ └── tool.invoke() → 各 tools/
│ └── Scratchpad [agent/scratchpad.ts]
├── ModelSelectionController
└── pi-tui 组件树

3.2 入口：src/index.tsx + src/cli.ts

index.tsx 只有 4 行，直接调用 runCli()。

cli.ts 是整个 CLI 的编排层，使用 pi-tui（不是 Ink/React，README 有误）构建终端 UI。关键设计：

• 用 AgentRunnerController、ModelSelectionController、InputHistoryController 三个 Controller 分离关注点
• 渲染逻辑全部在 renderSelectionOverlay() 和 renderMainView() 中，状态变化触发 tui.requestRender()
• 文件写入工具（write_file、edit_file）需要用户审批，通过 agentRunner.pendingApproval 状态机实现

3.3 Agent 核心：src/agent/agent.ts

这是整个系统最核心的文件，实现了完整的 ReAct 循环：

Agent.create()
→ getTools(model) // 按环境变量条件注册工具
→ loadSoulDocument() // 加载 SOUL.md 人格文件
→ MemoryManager.get() // 初始化记忆系统
→ buildSystemPrompt() // 构建系统提示词

Agent.run(query)
→ buildInitialPrompt() // 注入历史对话上下文
→ while (iteration < maxIterations):
→ callModel() // 调用 LLM（带工具绑定）
→ if no tool_calls: // 直接回答，结束
yield done event
→ else:
→ toolExecutor.executeAll() // 并发执行工具
→ manageContextThreshold() // 上下文管理
→ buildIterationPrompt() // 构建下一轮提示词
上下文管理策略（Anthropic 风格）：

• 不做内联摘要，保留完整工具结果
• 当 estimateTokens(systemPrompt + query + toolResults) > 100_000 时，触发上下文清理
• 清理时先尝试 Memory Flush（将工具结果写入记忆文件），再清除最旧的工具结果，保留最近 5 条
• 上下文溢出错误时最多重试 2 次，每次保留最近 3 条工具结果

Token 估算：用字符数 / 3.5 粗估，保守但够用。

3.4 Scratchpad：src/agent/scratchpad.ts

设计亮点：双轨持久化——JSONL 文件是不可变的追加日志（用于调试），内存中的 clearedToolIndices: Set<number> 控制哪些条目对 LLM 可见。

Scratchpad
├── JSONL 文件（.dexter/scratchpad/）— 永久保存，不删除
├── clearedToolIndices — 内存中标记已清除的条目
├── toolCallCounts — 每个工具的调用次数（软限制，默认 3 次）
└── toolQueries — 用 Jaccard 相似度检测重复查询（阈值 0.7）
工具调用限制是软限制（warn but allow），通过在 buildIterationPrompt 中注入 ## Tool Usage This Query 段落来引导 LLM 自我约束，而不是硬性阻断。这是一个有趣的设计取舍。

3.5 提示词工程：src/agent/prompts.ts

系统提示词的构建逻辑相当精细：

• SOUL.md：先查 .dexter/SOUL.md（用户覆盖），再 fallback 到仓库根目录的 SOUL.md
• Channel Profile：CLI 和 WhatsApp 有不同的格式规范（表格样式、响应长度等）
• 工具描述：每个工具有独立的 rich description，注入到系统提示词的 ## Available Tools 段落，而不是依赖 LangChain 的默认 schema 描述
• 记忆上下文：启动时加载 MEMORY.md 的摘要注入到系统提示词
• Anthropic 缓存：对 Anthropic provider，系统提示词用 cache_control: { type: 'ephemeral' } 标记，节省约 90% 的输入 token 成本

buildIterationPrompt 的设计：每轮迭代都重建完整提示词（Query + 所有工具结果 + 工具使用状态），而不是追加消息历史。这是 Anthropic 风格的上下文管理，避免了多轮消息历史的 token 累积问题。

3.6 LLM 抽象层：src/model/llm.ts + src/providers.ts

providers.ts 是单一数据源，所有 provider 元数据（id、displayName、modelPrefix、apiKeyEnvVar、fastModel）集中在 PROVIDERS 数组中。路由逻辑基于模型名前缀（claude- → Anthropic，gemini- → Google，ollama: → Ollama 等）。

callLlm 的关键逻辑：

• 有 outputSchema → 用 withStructuredOutput（结构化输出）
• 有 tools → 用 bindTools（工具调用）
• 两者都没有 → 直接返回文本内容
• Anthropic 特殊处理：手动构建 SystemMessage + HumanMessage，注入 cache_control
• 其他 provider：用 ChatPromptTemplate.fromMessages 构建链

重试逻辑：指数退避（500ms × 2^attempt），最多 3 次，非重试错误（context overflow、billing、auth）直接抛出。

3.7 工具注册表：src/tools/registry.ts

工具注册是条件性的：

• web_search：按优先级选 Exa → Perplexity → Tavily（取决于哪个 API key 存在）
• x_search：需要 X_BEARER_TOKEN
• skill：只有发现了 SKILL.md 文件才注册

每个工具有两个描述：一个简短的 LangChain schema description（用于工具调用），一个 rich description（注入系统提示词，指导 LLM 何时用、何时不用）。

3.8 金融工具的"元工具"模式

get_financials、get_market_data、read_filings、stock_screener 都是元工具（meta-tool），内部再次调用 LLM 进行路由：

get_financials 流程：
自然语言 query
→ callLlm(routerPrompt, FINANCE_TOOLS) // LLM 选择子工具
→ Promise.all(toolCalls.map(tc => tool.invoke(tc.args))) // 并发执行
→ 合并结果，返回 { data, sourceUrls }
read_filings 流程（最复杂，3 次 LLM 调用）：
query
→ callLlm(planPrompt, outputSchema=FilingPlanSchema) // 结构化输出：ticker + filing_types
→ Promise.all([getFilings.invoke(), getFilingItemTypes()]) // 并发获取元数据
→ callLlm(step2Prompt, STEP2_TOOLS) // 选择具体 filing items
→ Promise.all(limitedToolCalls.slice(0,3).map(...)) // 最多读 3 个文件
这种设计让顶层 Agent 只需一次工具调用，内部复杂性被封装。代价是每次调用会产生额外的 LLM 费用。

3.9 记忆系统：src/memory/

这是代码库中最复杂的子系统，实现了完整的 RAG 管道：

MemoryManager (单例)
├── MemoryStore — 文件 I/O（MEMORY.md、daily logs、session files）
├── MemoryDatabase — SQLite（chunks 表 + FTS5 虚拟表 + embedding_cache）
└── MemoryIndexer — 文件监听 + 增量同步 + 嵌入生成

hybridSearch()
├── embedSingleQuery() → 向量搜索（余弦相似度，手动实现）
├── searchKeyword() → FTS5 BM25 关键词搜索
├── 加权合并（默认 vector:0.7, keyword:0.3）
├── applyTemporalDecay() — 时间衰减（半衰期 30 天，MEMORY.md 豁免）
└── applyMMRToHybridResults() — MMR 去重（Jaccard 相似度，λ=0.7）
数据库设计细节：

• 嵌入向量存为 Float32Array 的 Uint8Array blob
• 有 embedding_cache 表避免重复嵌入相同内容
• provider_fingerprint 机制：切换嵌入模型时自动清空旧向量
• 支持 bun:sqlite（Bun 原生）和 better-sqlite3（Node.js）双后端

Session 历史也被索引：sessions/chat_history.json 中的对话记录会被分块嵌入，让记忆搜索能跨越历史对话。

3.10 WhatsApp 网关：src/gateway/

架构分层清晰：
gateway.ts (startGateway)
├── ChannelManager — 管理多个 WhatsApp 账号连接
├── WhatsApp Plugin (Baileys) — 处理 inbound/outbound 消息
├── resolveRoute() — 根据 chatId/senderId 路由到 agentId + sessionKey
├── access-control.ts — 白名单/黑名单控制（防止消息发给陌生人）
└── group/ — 群聊支持（mention 检测、成员追踪、历史缓冲）
群聊处理逻辑：未被 @mention 的消息会被缓冲到 groupHistoryBuffer，当 @mention 触发时，将缓冲的历史作为上下文注入 query，让 Agent 了解对话背景。

3.11 Cron 系统：src/cron/

支持三种调度类型（at/every/cron），用 croner 库解析 cron 表达式。

executeCronJob 的关键设计：

• 抑制机制：如果 Agent 回答与上次相同（文本相似），不发送消息（避免重复推送）
• HEARTBEAT_OK_TOKEN：Agent 回答 [OK] 时静默抑制，不发送消息
• 指数退避：错误时按 [30s, 1m, 5m, 15m, 60m] 退避
• fulfillment 模式：once 触发后自动禁用，ask 触发后询问用户是否继续

3.12 Skills 系统：src/skills/

Skills 是 Markdown 文件驱动的工作流，通过 gray-matter 解析 YAML frontmatter 获取元数据。

skill 工具的执行逻辑（src/tools/skill.ts）：读取 SKILL.md 内容，将其作为 user 消息注入到当前 Agent 的上下文中，让 Agent 按照 Skill 的指令执行。每个 Skill 在一次 query 中只能执行一次（通过 scratchpad.hasExecutedSkill() 去重）。

内置 Skills：

• dcf-valuation：8 步 DCF 估值，含 WACC 行业参考表（sector-wacc.md）
• x-research：X/Twitter 情绪研究，多轮搜索 + 情绪分类

3.13 对话历史：src/utils/in-memory-chat-history.ts

多轮对话的上下文注入有两个层次：

1. 最近 N 轮：直接注入完整 query + answer
2. 较早的轮次：用 LLM 生成摘要（generateSummary），注入摘要而非全文

相关性筛选：每次新 query 时，用 LLM（结构化输出）从历史中选出相关的消息 ID，只注入相关历史，避免无关上下文干扰。结果按 query hash 缓存。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

四、部署方式

（via kiro248 全自动调研）