文件驱动AI交易引擎OpenAlice：透明、可审计的自动化交易框架-深圳市維司達科技有限公司

1. 项目概述：一个文件驱动的AI交易代理引擎

如果你曾经幻想过拥有一个全天候为你工作的私人量化交易团队，但又对复杂的部署、臃肿的数据库和难以理解的API望而却步，那么OpenAlice的出现，可能会让你眼前一亮。这是一个将“文件驱动”理念贯彻到底的AI交易代理引擎，它把复杂的交易逻辑、AI决策和系统状态，全部浓缩在了你本地硬盘上那些可读的Markdown和JSON文件里。简单来说，它试图用最朴素的方式——读写文件，来构建一个最复杂的系统——一个能自主研究、分析和执行交易的AI。

OpenAlice的核心定位是“你一个人的华尔街”。它不是一个提供“圣杯”策略的黑盒系统，而是一个高度可定制、透明且由你完全掌控的框架。无论是加密货币还是传统证券，你都可以通过定义AI的“人设”（Persona）、配置交易规则（Guards）和连接经纪商（Broker），来打造一个专属于你的自动化交易伙伴。它的设计哲学非常极客：没有数据库，没有容器，一切状态和行为都通过文件来定义和追溯。这种设计带来的直接好处是极致的透明度和可调试性——你可以随时打开一个JSONL文件，查看AI的每一次思考、每一次决策的完整记录。

这个项目适合谁？首先，它适合有一定编程基础，尤其是熟悉Node.js/TypeScript生态的开发者或量化交易爱好者。其次，它适合那些不满足于使用现成交易软件，希望深入理解并控制交易自动化每一个环节的极客。最后，它也适合研究人员和教育工作者，作为一个研究AI在金融领域决策行为的绝佳实验平台。但必须强调，正如其文档中醒目的警告所言，这是一个处于活跃开发阶段的实验性软件，绝对不应用于真实资金交易，除非你完全理解并接受其中涉及的所有风险。

2. 核心架构与设计哲学解析

2.1 为何选择“文件驱动”？

在当今云原生、微服务大行其道的时代，OpenAlice反其道而行之，选择了“文件驱动”作为其基石。这并非技术上的倒退，而是一种深思熟虑的架构选择，旨在解决特定场景下的核心痛点。

透明性与可审计性：金融交易容错率极低，任何一个决策都需要可追溯、可审计。当所有状态——AI的记忆、交易指令、市场数据快照——都以纯文本（JSONL, Markdown）的形式存储在本地时，你相当于拥有了一个永不丢失的“黑匣子”。你可以用最熟悉的文本编辑器、grep、jq等命令行工具直接审查历史，甚至进行事后分析。这种透明度是任何封闭数据库或二进制存储格式难以比拟的。

开发与调试体验：开发者与AI的交互，被抽象为对文件的读写。这被称为“Vibe Coding”或“Vibe Trading”。你可以手动编辑一个persona.md文件来改变AI的性格和任务目标，可以查看events.jsonl来追踪系统内部事件流，也可以通过修改accounts.json来动态启用或禁用某个交易账户。这种模式将复杂的系统控制权，下放到了最通用、最易理解的接口——文件系统。调试时，你无需连接复杂的监控面板，直接看文件变化就能知道系统在做什么。

简化与零依赖：摒弃数据库和容器，意味着部署变得极其简单。理论上，你只需要Node.js环境和一个代码仓库。这降低了入门门槛，也减少了因中间件（如Redis, PostgreSQL）配置错误或版本不兼容导致的运维复杂度。所有数据都是自包含的，迁移、备份、回滚都变成了简单的文件拷贝操作。

一个重要的注意事项：文件驱动并非银弹。它意味着你需要自己处理数据一致性（例如，避免多个进程同时写入同一个文件）、性能（大量小文件IO可能成为瓶颈）和持久化可靠性。OpenAlice通过使用追加写的JSONL格式、原子性操作和合理的文件分区来缓解这些问题，但在设计自己的扩展时，必须将这些因素考虑在内。

2.2 统一交易账户：交易即Git

这是OpenAlice最具创新性的设计之一。它将软件工程中成熟的版本控制概念——Git，引入到了交易执行流程中，创造了“Trading-as-Git”工作流。

UTA的核心概念：每个统一交易账户都是一个独立的实体。它不仅仅是一个经纪商API的封装，而是一个包含了经纪商连接、交易操作历史、风控检查管道和账户快照调度器的完整组合。你可以把它想象成一个专用于某个交易策略或资产的Git仓库。AI和前端界面只与UTA交互，完全不用关心底层连接的是Interactive Brokers、Alpaca还是某个加密货币交易所。这种抽象极大地提高了系统的模块化和可测试性。

Stage-Commit-Push工作流：

暂存：当AI（或你通过UI）决定要下一个订单时，它并不直接发送给经纪商，而是调用stagePlaceOrder等工具，将操作“暂存”到UTA的暂存区。这类似于git add。
提交：暂存一个或多个操作后，需要执行tradingCommit并提供一个描述性的消息。这会生成一个包含所有暂存操作的“交易提交”，并分配一个唯一的8字符哈希值。这类似于git commit -m “...”。
推送与执行：提交本身不会触发真实交易。必须显式调用tradingPush。这个操作是关键的安全阀门，它会依次执行：
- 风控检查：运行该UTA配置的所有守卫，检查是否违反最大仓位、交易冷却时间、标的物白名单等规则。
- 经纪商执行：只有通过所有守卫，操作才会被分发给底层的经纪商适配器执行。
- 状态快照：执行成功后，自动捕获一次账户状态快照，用于后续绘制资金曲线。
- 历史记录：将本次推送记录为一个不可更改的提交历史。

这种设计带来的核心优势：

明确的审批流程：push操作相当于一次人工或自动的代码合并请求。你可以配置为需要手动在UI上点击确认，也可以设置为自动。这为实现不同级别的自动化（全自动、半自动、手动复核）提供了清晰的框架。
完整的历史回溯：通过tradingLog和tradingShow工具，你可以像查看代码提交历史一样，回顾每一笔交易的决策上下文、执行结果和当时的账户状态。这对于归因分析和策略优化至关重要。
原子性与回滚：一个提交内的多个操作（例如，平掉旧仓同时开新仓）在push时被视为一个原子单元。如果其中部分操作失败，整个提交可以回滚，有助于保持账户状态的一致性。

2.3 双AI引擎与工具生态

OpenAlice没有将自己绑定在某个特定的AI模型提供商上，而是设计了一个可热切换的Provider层。目前主要支持两种后端：

Claude Agent SDK：这是默认且功能最强大的选项。它利用Anthropic官方的@anthropic-ai/claude-agent-sdk，最大的特点是支持通过OAuth使用你的Claude Code（Claude Pro/Max）订阅身份，无需额外配置API密钥。它通过MCP协议在进程内将工具暴露给Claude模型，提供了最深度、最稳定的工具调用体验。
Vercel AI SDK：这是一个更通用、更轻量的选择。它直接调用各大模型提供商（Anthropic, OpenAI, Google等）的API。你需要自行配置API密钥，但它提供了更大的模型选择灵活性。

运行时热切换：你可以在data/config/ai-provider.json中指定当前使用的Provider，甚至可以通过Web UI动态切换。系统核心的ProviderRouter会在每次请求时读取这个配置，将请求路由到对应的后端。这意味着你可以根据任务需求（比如，需要复杂推理时用Claude-3.5-Sonnet，需要快速简单响应时用GPT-4o-mini）或者预算情况，灵活调整。

工具中心：所有AI可用的功能，都被抽象为“工具”，并在ToolCenter中集中注册。src/tool/目录下的每个文件都是一个“桥接层”，它们将底层src/domain/中的复杂业务逻辑（如交易、市场数据获取、新闻分析）包装成AI可以理解和调用的标准化工具函数。ToolCenter负责将这些工具同时以Vercel AI SDK和MCP两种格式导出，供不同的Provider使用。这种设计使得添加一个新功能变得非常清晰：在domain中实现逻辑，在tool中创建桥接，工具就会自动出现在AI的“工具箱”里。

3. 核心模块深度实操指南

3.1 环境搭建与首次运行

虽然项目宣称“开箱即用”，但为了获得最佳体验并避免踩坑，遵循一个清晰的初始化流程至关重要。

前置条件检查：

Node.js 22+：这是硬性要求。许多新的ES模块特性在此版本中稳定。建议使用nvm管理Node版本。
pnpm 10+：这是一个monorepo项目，使用pnpmworkspace进行依赖管理，npm或yarn可能无法正确处理。
Claude Code CLI：如果你计划使用默认的Claude Provider，这是必须的。前往Anthropic官网安装并完成claude auth login。这将允许Alice使用你的Claude订阅身份，免去API密钥的烦恼和费用。

克隆与初始化：

# 克隆仓库 git clone https://github.com/TraderAlice/OpenAlice.git cd OpenAlice # 安装依赖并构建 pnpm install pnpm build # 启动开发服务器（后端 + 前端代理） pnpm dev

执行pnpm dev后，后端服务会在端口3002启动。此时，不要直接打开localhost:3002，因为这个端口在开发模式下仅提供API服务。

访问Web UI：真正的用户界面由Vite开发服务器提供。你需要新开一个终端，运行：

pnpm dev:ui

这个命令会启动前端开发服务器（通常在端口5173），并配置了热重载和到后端（3002端口）的代理。现在，打开浏览器访问http://localhost:5173，你应该能看到OpenAlice的聊天界面。

一个常见的坑：直接访问localhost:3002看到404或空白页。这是因为生产构建后，前端静态文件才会被后端服务托管。在开发时，必须使用pnpm dev:ui启动的前端服务器。

首次对话：在UI中，你可以直接向Alice打招呼，比如“Hello, Alice”。系统会自动从default/persona.default.md复制默认人设到data/brain/persona.md，并开始初始化。如果一切正常，Alice会回应你，并展示其可用的工具。

3.2 配置系统详解：从零到一配置一个交易账户

OpenAlice的所有配置都位于data/config/目录下，采用JSON格式并用Zod进行强类型验证。如果文件不存在，系统会使用内建的默认值。理解几个关键配置文件是自定义系统的第一步。

1. 选择AI提供商(ai-provider.json)：

{ "provider": "agent-sdk", // 或 "vercel-ai-sdk" "agentSdk": { "type": "oauth", // 使用Claude Code OAuth登录。也可用 "api-key" "model": "claude-3-5-sonnet-20241022" }, "vercelAiSdk": { "model": "openai:gpt-4o", "apiKey": "your-openai-key-here" // 从环境变量读取更安全 } }

agent-sdk(推荐)：无缝对接Claude，体验最好。确保你的Claude Code CLI已登录。
vercel-ai-sdk：更灵活，支持多模型。你需要将API密钥放在这里或通过环境变量OPENAI_API_KEY等传递。

2. 创建你的第一个交易账户(accounts.json)：这是连接真实市场的关键。假设我们要添加一个用于测试的Alpaca纸账户。

[ { "id": "alpaca-paper-1", "name": "My Alpaca Paper Trading", "type": "alpaca", "enabled": true, // 运行时可以热启用/禁用 "guards": { "maxPositionSize": { "enabled": true, "maxUsd": 1000 }, "cooldown": { "enabled": true, "seconds": 60 }, "symbolWhitelist": { "enabled": true, "symbols": ["AAPL", "MSFT", "SPY"] } }, "brokerConfig": { // 以下字段由 `alpaca` 经纪商类型自行定义和验证 "paper": true, "keyId": "YOUR_ALPACA_API_KEY_ID", "secretKey": "YOUR_ALPACA_SECRET_KEY" } } ]

id：账户的唯一标识符，在系统内部使用。
type：决定使用哪个经纪商适配器（alpaca,ccxt,ibkr）。
guards：这是你的安全网。maxPositionSize限制单笔交易最大金额；cooldown防止过于频繁的交易；symbolWhitelist限定可交易的标的，避免AI误操作不熟悉的品种。
brokerConfig：这部分是动态的。每个经纪商类型会在系统中注册自己的配置模式。当你填写type: alpaca时，系统就知道brokerConfig应该符合Alpaca适配器期望的结构（包含keyId,secretKey等）。这种设计使得添加新经纪商无需修改框架核心代码。

3. 配置市场数据源(market-data.json)： OpenAlice内置了强大的opentypebb（OpenBB的TypeScript移植版）作为默认数据引擎。

{ "provider": "opentypebb-sdk", "cacheTtlSeconds": 300, "equity": { "provider": "yfinance" // 也可用 "polygon", "intrinio" 等，需对应API key }, "crypto": { "provider": "yfinance" } }

如果你有Polygon、Intrinio等专业数据源的API密钥，可以在这里配置，获取更实时、更丰富的数据。

4. 个性化AI人设与心跳：

data/brain/persona.md: 这里定义了AI的角色、目标、行为准则。你可以把它写成“你是一个谨慎的价值投资者”或“你是一个活跃的日内动量交易者”。AI会根据这个文件来塑造它的决策风格。
data/brain/heartbeat.md: 定义了“心跳”任务时AI的思考流程。心跳是定期（可配置）执行的任务，AI会检查市场状况，并决定是否需要主动向你汇报。你可以修改它来改变AI的“主动性”。

实操心得：建议在修改任何配置后，通过Web UI的“设置”页面（通常有配置管理器）或直接重启pnpm dev来重载配置。对于accounts.json，很多更改（如启用/禁用账户）支持热重载，但修改经纪商密钥可能需要重启相关服务。

3.3 风控守卫与交易执行流程拆解

风控是自动化交易的命脉。OpenAlice的守卫系统提供了一套可插拔、可配置的检查机制，在订单到达经纪商之前进行最后一道拦截。

守卫的工作原理：每个UTA在初始化时，会根据accounts.json中的guards配置，加载一系列守卫函数。当tradingPush被调用时，系统会遍历该UTA的所有已启用守卫，并传入待执行的操作列表（即本次提交的内容）。任何一个守卫返回false或抛出错误，整个推送过程都会中止，所有操作都不会发送到经纪商。

内置守卫类型：

最大仓位守卫：计算本次提交中所有开仓操作的总名义价值（或数量），与预设的maxUsd或maxQuantity进行比较。这对于控制单次风险暴露至关重要。
冷却时间守卫：记录上一次成功推送的时间戳。如果当前时间与上次推送的间隔小于设定的seconds，则阻止本次推送。这能有效防止因市场噪音或AI“兴奋”导致的过度交易。
标的物白名单守卫：检查提交中所有操作涉及的金融工具（如股票代码AAPL）是否都在预设的symbols列表中。这是防止AI交易不熟悉或高风险品种的简单有效方法。

自定义守卫：系统的强大之处在于你可以编写自己的守卫。你只需要在src/domain/trading/guards/目录下创建一个新的.ts文件，实现一个符合GuardFunction类型签名的函数，并在守卫注册表中添加它即可。例如，你可以实现一个“最大回撤守卫”，在账户总权益从高点回撤超过一定比例时禁止开新仓。

交易执行的完整链路：让我们跟踪一个“买入10股AAPL”的指令在系统中的旅程：

AI决策：AI通过分析市场数据，决定买入AAPL。
工具调用：AI调用stagePlaceOrder工具，参数为{ symbol: ‘AAPL’， action: ‘BUY’， quantity: 10， orderType: ‘MARKET’ }。该工具调用被路由到对应的UTA。
暂存：UTA将此订单对象存入其“暂存区”。此时，订单仅存在于内存中，尚未持久化。
提交：AI（或用户）调用tradingCommit，并附上消息“Buy AAPL on breakout”。暂存区的内容被序列化，与消息一起生成一个唯一的提交哈希（如a1b2c3d4），并持久化到data/trading/[account-id]/commits/下的文件中。
推送：用户（或自动流程）调用tradingPush。
守卫检查：系统依次运行该UTA的所有守卫。比如，检查AAPL是否在白名单内，检查账户是否在冷却期，计算10股AAPL的市值是否超过1000美元。
经纪商适配：守卫全部通过后，系统将标准的订单对象（使用IBKR类型系统）传递给Alpaca经纪商适配器。适配器负责将通用订单转换为Alpaca API特定的请求格式。
执行与反馈：适配器调用Alpaca API下单。收到响应后，将执行结果（成交价、数量、状态）返回给系统。
历史记录与快照：系统将完整的执行结果关联到之前的提交，更新历史。同时，触发一次账户快照，记录下交易后的资产组合和权益曲线点。
用户通知：通过ConnectorCenter，将交易执行结果推送到用户最后交互的渠道（Web UI或Telegram）。

关键注意事项：tradingPush是同步操作，它会阻塞直到所有守卫检查完成且经纪商API调用返回。对于市价单，这通常很快；但对于需要等待成交的限价单，你可能需要考虑异步处理或状态轮询，当前版本可能需要根据经纪商支持情况做额外处理。

3.4 市场数据、新闻与AI研究能力集成

一个强大的交易AI离不开高质量的数据输入。OpenAlice通过opentypebb引擎和新闻收集器，为AI提供了深度的研究能力。

统一数据层：domain/market-data/模块封装了所有数据获取逻辑。它提供了一个统一的搜索接口marketSearchForResearch，AI可以用自然语言搜索标的物，如“苹果股票”或“比特币”，系统会返回匹配的标准化符号列表。此外，还有获取K线数据、基本面数据（财务报表、估值比率）、宏观经济指标等的专用工具。

技术指标计算：domain/analysis/模块提供了技术分析工具。AI可以请求计算RSI、MACD、布林带等指标。这些计算在本地进行，响应迅速，且不依赖于外部服务的限制。例如，AI可以自主执行一个分析流程：“获取SPY过去50天的日线数据，计算其20日移动平均线和RSI(14)，如果价格在均线之上且RSI低于30，则提示超卖机会。”

新闻收集与情感分析：domain/news/模块运行一个后台RSS收集器。你可以在news.json中配置多个新闻源（如路透社、CoinDesk的财经RSS）。收集到的新闻会以结构化格式（标题、摘要、来源、时间戳）存入data/news-collector/的JSONL文件中。 AI可以通过globNews（按日期模式查找）、grepNews（全文搜索关键词）、readNews（阅读特定新闻）等工具来获取信息。结合其推理能力，AI可以做到：“搜索过去24小时内关于‘美联储’和‘利率’的新闻，总结市场情绪，并评估其对科技股的可能影响。”

让AI进行深度研究：你可以给AI下达这样的指令：“研究一下特斯拉(TSLA)最近一个季度的财报，看看其毛利率变化趋势、自由现金流情况，以及分析师对未来一年的每股收益预测。同时，查看一下过去一个月与电动汽车行业相关的重大新闻。” AI会链式调用多个工具：getCompanyProfile获取公司信息，getFinancialStatements获取财务报表，getAnalystEstimates获取预测，最后用grepNews搜索相关新闻。它会在一个完整的思考周期内整合这些信息，并给出带有引用的分析报告。

数据缓存策略：所有外部API调用都有缓存机制（配置在market-data.json的cacheTtlSeconds），这减少了重复请求，提高了响应速度，也节省了API调用成本。缓存文件存储在data/cache/目录下。

4. 高级功能与定制化开发

4.1 进化模式：让AI修改自己的代码

这是OpenAlice最大胆的功能之一。进化模式是一个权限开关，位于agent.json中。

{ "maxAgentSteps": 100, "evolutionMode": false, // 设置为 true 以启用进化模式 "claudeCodeTools": ["filesystem", "bash"] }

正常模式：AI被沙箱化，只能读写data/brain/目录下的文件（人设、记忆、情绪日志）。这是安全的生产模式。
进化模式：当evolutionMode设为true，并且AI提供商（如Claude Code）被授予了bash和filesystem工具权限后，AI将获得对整个项目目录的读写权限，甚至可以执行Bash命令。

这意味着什么？AI可以：

修复它自己代码中的bug（例如，你报告了一个错误，AI可以定位到src/下的相关文件并提交修复）。
根据你的需求添加新功能（例如，你要求“增加一个计算夏普比率的功能”，AI可能会修改analysis域并添加相应的工具）。
优化其性能或配置。

巨大的风险与注意事项：

警告：这是一个极其危险的特性，仅供实验和研究使用。让AI拥有修改自身源代码的能力，相当于给了它“上帝权限”。一个错误的Bash命令（如rm -rf /）或一个有缺陷的代码修改，可能导致系统崩溃、数据丢失甚至安全漏洞。绝对不要在存有重要数据或连接了真实交易账户的系统上开启此模式。建议仅在干净的开发环境或容器中尝试。

使用场景：想象你在开发一个新的数据提供商适配器，你可以向AI描述接口规范，然后开启进化模式，让它帮你生成初始的TypeScript代码框架。这更像是一个结对编程的辅助工具，而非全自动的代码生成器。

4.2 心跳与定时任务：让AI主动与你沟通

一个被动的AI需要你不断询问。OpenAlice的心跳和定时任务系统，让AI能够主动运行并汇报。

心跳：在heartbeat.json中配置，例如每30分钟运行一次。当心跳触发时，系统会加载data/brain/heartbeat.md中的提示词，让AI执行一个固定的分析流程。这个流程通常包括：

检查主要持仓的市场表现。
扫描预设的新闻关键词。
分析大盘指数或关键宏观指标。
根据一套逻辑决定是否需要主动发起对话。

AI必须返回一个结构化响应：HEARTBEAT_OK（一切正常，无需打扰）、CHAT_NO（有情况但认为无需报告）、或CHAT_YES（有重要信息需要立即报告）。如果是CHAT_YES，AI会生成一条消息，并通过ConnectorCenter发送到你最后使用的聊天渠道（Web UI或Telegram）。

定时任务：更灵活的是Cron系统。你可以在data/cron/jobs.json中定义复杂的定时任务。

[ { "id": "morning-briefing", "name": "每日晨报", "schedule": "0 9 * * 1-5", // 每周一到周五早上9点 "prompt": "现在是东部时间早上9点。请生成一份今日交易晨报，内容包括：隔夜市场回顾、主要股指期货表现、今日重要经济数据发布日程、以及对我当前持仓（{portfolio}）的简要风险提示。报告需简洁，突出重点。" } ]

当Cron引擎触发任务时，它会将任务prompt和任何预定义的上下文变量（如{portfolio}会被替换为当前持仓信息）发送给AgentCenter执行。执行结果同样会发送到最后一个交互渠道。

实操技巧：你可以用心跳来做常规健康检查，用Cron任务来做更复杂的、需要注入动态数据的定期分析报告。两者的输出都会记录在data/event-log/events.jsonl中，方便你追溯。

4.3 扩展OpenAlice：添加一个新的数据源或工具

OpenAlice的模块化设计使得扩展变得相对清晰。这里以添加一个简单的“天气对能源价格影响分析”工具为例，演示扩展流程。

第一步：在领域层实现逻辑(src/domain/weather/)。创建一个新的领域模块，例如src/domain/weather/impact-analysis.ts。这里实现核心业务逻辑，比如从一个天气API获取数据，并与能源期货价格进行相关性分析。

// src/domain/weather/impact-analysis.ts export class WeatherImpactAnalyzer { constructor(private apiKey: string) {} async analyzeGulfHurricaneAndOilPrice(days: number): Promise<AnalysisResult> { // 1. 从天气API获取墨西哥湾近期飓风活动数据 // 2. 从市场数据模块获取WTI原油期货价格 // 3. 进行简单的统计分析或规则判断 // 4. 返回分析结果 } }

第二步：创建工具桥接层(src/tool/weather.ts)。在tool目录下创建新文件，将领域逻辑包装成AI工具。这里需要导入ToolCenter，注册工具。

// src/tool/weather.ts import { tool } from ‘../core/tool-center‘; // 假设有这样的装饰器或注册函数 import { WeatherImpactAnalyzer } from ‘../domain/weather/impact-analysis‘; export const weatherTools = { async analyzeWeatherImpactOnEnergy({ days = 7 }: { days: number }) { const analyzer = new WeatherImpactAnalyzer(process.env.WEATHER_API_KEY); const result = await analyzer.analyzeGulfHurricaneAndOilPrice(days); return { conclusion: result.conclusion, confidence: result.confidence, rawData: result.data // 注意：返回给AI的数据要简洁，避免token浪费 }; } }; // 在某个初始化函数中，需要将 weatherTools 注册到 ToolCenter

第三步：将工具暴露给AI。确保你的工具注册函数被主应用初始化流程调用。ToolCenter会自动将其转换为Vercel AI SDK和MCP兼容的格式。

第四步：更新AI人设。修改data/brain/persona.md，在AI的能力描述中加上一句：“我还可以分析极端天气事件（如飓风）对短期能源期货价格的潜在影响。” 这样AI在规划任务时，才会意识到自己拥有这个新工具。

第五步：测试。重启服务，在聊天中询问AI：“分析一下最近墨西哥湾的天气对油价可能有什么影响。” AI应该能识别意图并调用你新添加的工具。

扩展经纪商：流程类似，但需要在src/domain/trading/brokers/下创建新的经纪商类，实现标准的IBroker接口，并在registry.ts中注册。brokerConfig的验证逻辑也需要在经纪商类内部定义。

5. 常见问题、故障排查与实战心得

5.1 安装与启动问题

问题：运行pnpm install时出现ELIFECYCLE错误或依赖解析失败。
- 排查：首先确认Node.js版本为22或以上，pnpm版本为10或以上。可以尝试删除node_modules和pnpm-lock.yaml，然后使用pnpm store prune清理缓存，再重新执行pnpm install。对于网络问题，可以考虑配置国内镜像源。
问题：pnpm dev启动成功，但pnpm dev:ui无法连接后端或页面空白。
- 排查：检查两个终端窗口的输出是否有错误。确保后端（3002端口）已先运行。查看前端控制台（浏览器F12）的网络请求，看对localhost:3002的代理请求是否失败。可能是端口被占用或代理配置问题。可以尝试手动指定端口：pnpm dev:ui --port 3003，并确保Vite配置中的代理目标正确。
问题：Claude Provider 报错，提示认证失败。
- 排查：运行claude auth status确认Claude Code CLI已登录。检查ai-provider.json中agentSdk.type是oauth还是api-key。如果是OAuth，确保没有其他进程占用默认的OAuth回调端口。可以尝试重启Claude Code服务或重新登录。

5.2 交易与账户相关

问题：创建了账户，但AI说找不到或无法交易。
- 排查：
  1. 检查accounts.json中账户的enabled是否为true。
  2. 检查brokerConfig中的API密钥或连接参数是否正确。对于IBKR，确保TWS或Gateway正在运行，且API连接端口、客户端ID设置正确。
  3. 查看后端日志。当UTA初始化时，会尝试连接经纪商，连接失败会有明确错误信息。
  4. 使用Web UI的“交易”面板或tradingListAccounts工具，查看账户状态。
问题：订单被守卫拒绝。
- 排查：调用tradingPush后，如果失败，错误信息会明确指出是哪个守卫拦截。仔细阅读错误信息，例如Guard “maxPositionSize” rejected: order value 1500 exceeds max 1000。然后去accounts.json中调整对应守卫的配置参数。
问题：tradingPush成功，但经纪商那边没有订单。
- 排查：
  1. 检查经纪商平台：首先登录你的Alpaca/IBKR纸账户界面，确认订单是否真的没收到。有时是延迟显示。
  2. 查看日志：OpenAlice的后端日志会记录经纪商API的请求和响应。检查是否有网络超时或API返回错误。
  3. 订单参数：确保订单参数符合经纪商要求。例如，某些交易所对最小交易量有要求，某些市场在非交易时段不接受市价单。AI生成的订单参数可能需要根据具体经纪商规则进行调整。

5.3 AI行为与性能

问题：AI似乎“忘了”之前对话的内容。
- 排查：OpenAlice使用“记忆压缩”机制来管理上下文窗口。检查compaction.json配置。当对话轮数或token数超过阈值时，旧的记忆会被自动总结压缩。你可以调高阈值，但会增加API成本。更可持续的做法是优化persona.md和提示词，让AI更有效地利用有限上下文。
问题：AI调用工具很慢，或者经常超时。
- 排查：
  1. 网络：如果使用Vercel AI SDK且调用OpenAI/Anthropic的API，网络延迟是主要因素。
  2. 工具本身慢：某些工具，如webSearch（如果配置了）或复杂的analysis计算，可能耗时较长。考虑为这些工具设置更长的超时时间（如果框架支持），或者优化其实现。
  3. 模型速度：不同的AI模型响应速度差异很大。GPT-4比GPT-4o慢，Claude-3.5-Sonnet比Haiku慢。在ai-provider.json中切换模型试试。
问题：AI不按我期望的方式使用工具。
- 解决：这本质上是提示工程问题。仔细打磨data/brain/persona.md。明确指令AI的决策流程，例如：“在做出交易决定前，你必须依次调用以下工具：1.getQuote获取最新价；2.getIndicators计算关键技术指标；3.searchNews查看近期相关新闻。只有三者都符合条件时，才可stagePlaceOrder。” 更详细、更结构化的提示词能极大改善AI的行为。

5.4 数据与新闻

问题：市场数据获取失败或返回空。
- 排查：
  1. 检查market-data.json中的provider配置。opentypebb-sdk是本地引擎，openbb-api需要网络和有效的OpenBB Hub令牌。
  2. 检查data/cache/目录是否有写入权限。
  3. 对于特定数据源（如polygon），确认是否在market-data.json的对应区块配置了正确的API密钥，并且密钥有足够权限。
  4. 尝试使用marketSearchForResearch工具搜索一个非常常见的符号（如“AAPL”），如果还失败，可能是网络或上游API问题。
问题：新闻收集器没有收集到任何新闻。
- 排查：
  1. 检查news.json中的feeds列表，确保RSS链接是有效的。可以用浏览器直接打开链接测试。
  2. 查看data/news-collector/目录下是否有新的.jsonl文件生成。新闻收集是后台定时任务，可能需要等待一个周期。
  3. 检查后端日志，看新闻收集任务是否有报错（如网络错误、解析错误）。

5.5 实战心得与建议

从小处着手，用模拟盘：绝对不要一开始就投入真金白银。用Alpaca的纸账户或CCXT连接的交易所测试网，充分测试你的配置、人设和守卫规则。观察AI在多个市场周期下的表现。
人设即策略：persona.md是你最重要的配置文件。把它当成你招聘的交易员的职位描述。写得越具体、越有约束性，AI的行为就越可控。例如，明确风险偏好（“单笔亏损不超过本金的2%”）、交易品种偏好（“只交易市值前100的加密货币”）、交易时间（“避免在财报发布前后一小时交易”）。
善用守卫：守卫是你的安全防火墙。即使你完全信任AI的逻辑，也应设置基础的仓位和冷却守卫，防止程序错误或市场极端情况下的灾难性损失。
监控事件日志：data/event-log/events.jsonl是系统运行的“仪表盘”。定期用tail -f或写个小脚本监控它，可以实时看到心跳结果、Cron任务执行、错误信息等，便于快速发现问题。
版本控制你的配置：data/config/和data/brain/目录下的文件是你的核心资产。使用Git对其进行版本控制。这样，当你对persona.md或守卫参数进行修改后，如果效果不好，可以轻松回滚到之前的版本。
性能考量：如果你计划7x24小时运行，并连接多个数据源和账户，考虑将项目部署在稳定的云服务器上。注意监控内存和CPU使用情况，特别是当新闻收集和市场数据缓存量变大时。可以调整snapshot.json中的快照频率和news.json中的留存时间，以控制数据增长。