Skip to content

AGENTS.md

Latest commit

 

History

History
225 lines (173 loc) · 11.6 KB

AGENTS.md

File metadata and controls

225 lines (173 loc) · 11.6 KB

Repository Guidelines

中文指南 | English

仓库指南

Note: 本项目基于 dexter (v2026.2.21) Fork 而来，在此基础上新增了 A 股市场支持、命令联想等功能。

项目结构

  • 源代码: src/
    • Agent 核心: src/agent/ (智能体循环、提示词、暂存板、token 计数、类型)
    • CLI 接口: src/cli.tsx (Ink/React)，入口: src/index.tsx
    • 组件: src/components/ (Ink UI 组件)
    • Hooks: src/hooks/ (智能体运行器、模型选择、输入历史的 React hooks)
    • 模型/LLM: src/model/llm.ts (多提供商 LLM 抽象)
    • 工具: src/tools/ (金融搜索、网页搜索、浏览器、技能工具)
    • 工具描述: src/tools/descriptions/ (注入到系统提示词的详细描述)
    • 金融工具: src/tools/finance/ (价格、基本面、财报、内幕交易等)
    • A 股工具: src/tools/finance/china/ (A股行情、公司信息、财务报表、技术指标)
    • 搜索工具: src/tools/search/ (优先 Exa，Tavily 备选)
    • 浏览器: src/tools/browser/ (基于 Playwright 的网页抓取)
    • 技能: src/skills/ (基于 SKILL.md 的可扩展工作流，如 DCF 估值)
    • 工具: src/utils/ (环境变量、配置、缓存、token 估算、Markdown 表格)
    • 评估: src/evals/ (带 Ink UI 的 LangSmith 评估运行器)
  • 配置: .alphafin/settings.json (持久化的模型/提供商选择)
  • 环境变量: .env (API 密钥；参见 env.example)
  • 脚本: scripts/release.sh

构建、测试和开发命令

  • 运行时: Bun (主要)。所有命令使用 bun。
  • 安装依赖: bun install
  • 运行: bun run start 或 bun run src/index.tsx
  • 开发模式 (监视): bun run dev
  • 类型检查: bun run typecheck
  • 测试: bun test
  • 评估: bun run src/evals/run.ts (完整) 或 bun run src/evals/run.ts --sample 10 (采样)
  • CI 在 push/PR 时运行 bun run typecheck 和 bun test。

编码风格与约定

  • 语言: TypeScript (ESM，严格模式)。JSX 通过 React (Ink 用于 CLI 渲染)。
  • 优先使用严格类型；避免 any。
  • 保持文件简洁；提取辅助函数而非复制代码。
  • 为复杂或不明显的逻辑添加简短注释。
  • 除非明确要求，否则不要添加日志。
  • 除非明确要求，否则不要创建 README 或文档文件。

LLM 提供商

  • 支持: OpenAI (默认)、Anthropic、Google、xAI (Grok)、OpenRouter、Ollama (本地)、Kimi。
  • 默认模型: gpt-5.2。提供商检测基于前缀 (claude- -> Anthropic, gemini- -> Google 等)。
  • 轻量任务的快速模型: 参见 src/model/llm.ts 中的 FAST_MODELS 映射。
  • Anthropic 在系统提示词上使用显式 cache_control 以节省提示词缓存成本。
  • 用户可通过 CLI 中的 /model 命令切换提供商/模型。

工具

  • financial_search: 所有金融数据查询的主要工具 (价格、指标、财报)。内部委托给多个子工具。
  • financial_metrics: 直接指标查询 (营收、市值等)。
  • read_filings: SEC 财报阅读器，支持 10-K、10-Q、8-K 文档。
  • web_search: 通用网页搜索 (设置了 EXASEARCH_API_KEY 则用 Exa，否则用 Tavily)。
  • browser: 基于 Playwright 的网页抓取，用于阅读智能体发现的页面。
  • skill: 调用 SKILL.md 定义的工作流 (如 DCF 估值)。每个技能每次查询最多运行一次。
  • 工具注册表: src/tools/registry.ts。工具根据环境变量有条件地包含。

技能

  • 技能以 SKILL.md 文件形式存在，包含 YAML 前置数据 (name, description) 和 Markdown 正文 (指令)。
  • 内置技能: src/skills/dcf/SKILL.md。
  • 发现机制: src/skills/registry.ts 在启动时扫描 SKILL.md 文件。
  • 技能作为元数据暴露给 LLM 在系统提示词中；LLM 通过 skill 工具调用它们。

Agent 架构

  • 智能体循环: src/agent/agent.ts。可配置最大迭代次数 (默认 10) 的迭代工具调用循环。
  • 暂存板: src/agent/scratchpad.ts。查询内所有工具结果的单一数据源。
  • 上下文管理: Anthropic 风格。完整工具结果保留在上下文中；超过 token 阈值时清除最旧的结果。
  • 最终答案: 在单独的 LLM 调用中生成，带有完整暂存板上下文 (不绑定工具)。
  • 事件: 智能体产出类型化事件 (tool_start, tool_end, thinking, answer_start, done 等) 用于实时 UI 更新。

环境变量

  • LLM 密钥: OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, XAI_API_KEY, OPENROUTER_API_KEY, KIMI_API_KEY
  • Ollama: OLLAMA_BASE_URL (默认 http://127.0.0.1:11434)
  • 金融数据: FINANCIAL_DATASETS_API_KEY
  • 搜索: EXASEARCH_API_KEY (优先), TAVILY_API_KEY (备选)
  • 追踪: LANGSMITH_API_KEY, LANGSMITH_ENDPOINT, LANGSMITH_PROJECT, LANGSMITH_TRACING
  • 国内镜像: NPM_CONFIG_REGISTRY, BUN_INSTALL_REGISTRY, GITHUB_PROXY
  • 永远不要提交 .env 文件或真实的 API 密钥。

版本与发布

  • 版本格式: CalVer YYYY.M.D (无零填充)。标签前缀: v。
  • 发布脚本: bash scripts/release.sh [version] (默认为当天日期)。
  • 发布流程: 更新 package.json 版本，创建 git 标签，推送标签，通过 gh 创建 GitHub release。
  • 未经用户确认不要推送或发布。

测试

  • 框架: Bun 内置测试运行器 (主要)，Jest 配置用于遗留兼容。
  • 测试文件并排为 *.test.ts。
  • 修改逻辑时在推送前运行 bun test。

安全

  • API 密钥存储在 .env (gitignored)。用户也可通过 CLI 交互式输入密钥。
  • 配置存储在 .alphafin/settings.json (gitignored)。
  • 永远不要提交或暴露真实的 API 密钥、令牌或凭据。

English

Note: This project is forked from dexter (v2026.2.21) with additional features including A-share market support, command autocomplete, and more.

Project Structure

  • Source code: src/
    • Agent core: src/agent/ (agent loop, prompts, scratchpad, token counting, types)
    • CLI interface: src/cli.tsx (Ink/React), entry point: src/index.tsx
    • Components: src/components/ (Ink UI components)
    • Hooks: src/hooks/ (React hooks for agent runner, model selection, input history)
    • Model/LLM: src/model/llm.ts (multi-provider LLM abstraction)
    • Tools: src/tools/ (financial search, web search, browser, skill tool)
    • Tool descriptions: src/tools/descriptions/ (rich descriptions injected into system prompt)
    • Finance tools: src/tools/finance/ (prices, fundamentals, filings, insider trades, etc.)
    • A-Share tools: src/tools/finance/china/ (A-share quotes, company info, financials, technical indicators)
    • Search tools: src/tools/search/ (Exa preferred, Tavily fallback)
    • Browser: src/tools/browser/ (Playwright-based web scraping)
    • Skills: src/skills/ (SKILL.md-based extensible workflows, e.g. DCF valuation)
    • Utils: src/utils/ (env, config, caching, token estimation, markdown tables)
    • Evals: src/evals/ (LangSmith evaluation runner with Ink UI)
  • Config: .alphafin/settings.json (persisted model/provider selection)
  • Environment: .env (API keys; see env.example)
  • Scripts: scripts/release.sh

Build, Test, and Development Commands

  • Runtime: Bun (primary). Use bun for all commands.
  • Install deps: bun install
  • Run: bun run start or bun run src/index.tsx
  • Dev (watch mode): bun run dev
  • Type-check: bun run typecheck
  • Tests: bun test
  • Evals: bun run src/evals/run.ts (full) or bun run src/evals/run.ts --sample 10 (sampled)
  • CI runs bun run typecheck and bun test on push/PR.

Coding Style & Conventions

  • Language: TypeScript (ESM, strict mode). JSX via React (Ink for CLI rendering).
  • Prefer strict typing; avoid any.
  • Keep files concise; extract helpers rather than duplicating code.
  • Add brief comments for tricky or non-obvious logic.
  • Do not add logging unless explicitly asked.
  • Do not create README or documentation files unless explicitly asked.

LLM Providers

  • Supported: OpenAI (default), Anthropic, Google, xAI (Grok), OpenRouter, Ollama (local), Kimi.
  • Default model: gpt-5.2. Provider detection is prefix-based (claude- -> Anthropic, gemini- -> Google, etc.).
  • Fast models for lightweight tasks: see FAST_MODELS map in src/model/llm.ts.
  • Anthropic uses explicit cache_control on system prompt for prompt caching cost savings.
  • Users switch providers/models via /model command in the CLI.

Tools

  • financial_search: primary tool for all financial data queries (prices, metrics, filings). Delegates to multiple sub-tools internally.
  • financial_metrics: direct metric lookups (revenue, market cap, etc.).
  • read_filings: SEC filing reader for 10-K, 10-Q, 8-K documents.
  • web_search: general web search (Exa if EXASEARCH_API_KEY set, else Tavily if TAVILY_API_KEY set).
  • browser: Playwright-based web scraping for reading pages the agent discovers.
  • skill: invokes SKILL.md-defined workflows (e.g. DCF valuation). Each skill runs at most once per query.
  • Tool registry: src/tools/registry.ts. Tools are conditionally included based on env vars.

Skills

  • Skills live as SKILL.md files with YAML frontmatter (name, description) and markdown body (instructions).
  • Built-in skills: src/skills/dcf/SKILL.md.
  • Discovery: src/skills/registry.ts scans for SKILL.md files at startup.
  • Skills are exposed to the LLM as metadata in the system prompt; the LLM invokes them via the skill tool.

Agent Architecture

  • Agent loop: src/agent/agent.ts. Iterative tool-calling loop with configurable max iterations (default 10).
  • Scratchpad: src/agent/scratchpad.ts. Single source of truth for all tool results within a query.
  • Context management: Anthropic-style. Full tool results kept in context; oldest results cleared when token threshold exceeded.
  • Final answer: generated in a separate LLM call with full scratchpad context (no tools bound).
  • Events: agent yields typed events (tool_start, tool_end, thinking, answer_start, done, etc.) for real-time UI updates.

Environment Variables

  • LLM keys: OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, XAI_API_KEY, OPENROUTER_API_KEY, KIMI_API_KEY
  • Ollama: OLLAMA_BASE_URL (default http://127.0.0.1:11434)
  • Finance: FINANCIAL_DATASETS_API_KEY
  • Search: EXASEARCH_API_KEY (preferred), TAVILY_API_KEY (fallback)
  • Tracing: LANGSMITH_API_KEY, LANGSMITH_ENDPOINT, LANGSMITH_PROJECT, LANGSMITH_TRACING
  • China mirror: NPM_CONFIG_REGISTRY, BUN_INSTALL_REGISTRY, GITHUB_PROXY
  • Never commit .env files or real API keys.

Version & Release

  • Version format: CalVer YYYY.M.D (no zero-padding). Tag prefix: v.
  • Release script: bash scripts/release.sh [version] (defaults to today's date).
  • Release flow: bump version in package.json, create git tag, push tag, create GitHub release via gh.
  • Do not push or publish without user confirmation.

Testing

  • Framework: Bun's built-in test runner (primary), Jest config exists for legacy compatibility.
  • Tests colocated as *.test.ts.
  • Run bun test before pushing when you touch logic.

Security

  • API keys stored in .env (gitignored). Users can also enter keys interactively via the CLI.
  • Config stored in .alphafin/settings.json (gitignored).
  • Never commit or expose real API keys, tokens, or credentials.