Vibe-Research 部署教程：搭建本地金融研究工作台

本教程将指导你部署 Vibe-Research——一个基于 OpenAI Codex Harness 的本地金融研究工作台，支持 A股/美股/港股的个人投研 Agent，包含每日复盘、资讯雷达、个股研究、回测等功能。

📋 准备工作

1. 环境要求

  • 操作系统：Windows 11、macOS 或 Linux。
    • Windows 原生支持：使用 PowerShell 脚本，不强制要求 WSL。
  • Node.js：版本 ≥ 22.18，推荐 24 LTS。
    • 关键检查：必须安装支持 TypeScript 的官方构建版本（从 nodejs.org、nvm、fnm 或 Volta 安装）。运行 node -p process.features.typescript 应输出 strip 或 transform。部分 Linux 发行版仓库提供的 Node 可能不满足此要求。
  • Python：版本 ≥ 3.11，推荐并已验证 3.12。
  • 模型服务（二选一）：
    • 订阅方式：有效的 ChatGPT (Codex CLI) 或 Claude.ai (Claude Code CLI) 订阅。
    • API 方式：支持 Responses API 的模型服务（如 OpenAI、DeepSeek、Qwen 等）的 API Key。

🚀 安装与启动

方式一：Windows 快速启动（推荐）

使用 PowerShell（以管理员身份运行，以确保脚本权限）：

1
2
3
4
5
6
7
8
9
# 克隆仓库
git clone https://github.com/simonlin1212/Vibe-Research.git vibe-research-agent
cd vibe-research-agent

# 运行安装脚本（创建虚拟环境、安装依赖、初始化配置）
.\scripts\setup-windows.cmd

# 启动应用（启动本地 API 和浏览器界面）
.\scripts\start.cmd

启动后，浏览器会自动打开 http://127.0.0.1:5930。

方式二：macOS / Linux 手动启动

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 克隆仓库
git clone https://github.com/simonlin1212/Vibe-Research.git vibe-research-agent
cd vibe-research-agent

# 安装 Node 依赖
npm install --prefix orchestrator
npm install --prefix desktop

# 创建 Python 虚拟环境并安装依赖
python3 -m venv .venv
.venv/bin/pip install -r .agents/skills/data-access/scripts/requirements.txt

# 全局安装 Codex CLI (需 0.149.0 版本)
npm install -g @openai/codex@0.149.0

# 初始化产品
scripts/init --python "$(pwd)/.venv/bin/python"

启动服务（需要两个终端）：
终端 1：启动本地 API

1
node orchestrator/src/api.ts --port 8765

终端 2：启动 UI 界面

1
npm run dev --prefix desktop

浏览器打开 http://127.0.0.1:5930。

🔌 连接 AI 模型

首次启动后，需要在 Web 界面中配置 AI 后端，所有 Agent 功能共用此配置。

1. 订阅方式（推荐）

ChatGPT 订阅（Codex）：

  1. 在界面中进入 接入 AI (Connect AI) → 订阅接入。
  2. 点击 登录 Codex，会自动打开 OpenAI 官方授权页面完成登录。
  3. 授权完成后，页面会自动检测登录状态，点击 测试并保存。
    • 注意：产品使用独立的 CODEX_HOME 目录，不会影响你系统全局的 ~/.codex 配置。

Claude.ai 订阅：

  1. 确保本机已安装并登录 Claude Code CLI。
  2. 在设置页会自动检测到登录状态，无需手动填写密钥。

2. API 接入方式

  1. 进入 接入 AI (Connect AI) → API 接入。
  2. 选择供应商（内置 OpenAI、DeepSeek、Qwen、GLM、Kimi 等模板），填写 API 地址、模型名称和 API Key。
  3. 点击 测试并保存。系统会先发起一次真实模型对话，成功后才保存配置。
    • 安全提示：API Key 仅保存在浏览器 localStorage 中，随请求传递给本机后端，不写入仓库或日志。

🧩 核心功能与使用示例

1. 个股研究（A股完整六阶段）

在首页或个股研究模块，输入 A 股代码（如 300308）即可启动六阶段研究：

  1. 公司画像 → 2. 财务分析 → 3. 一致预期 → 4. 估值 → 5. 风险识别 → 6. 研究报告

研究产出不是单一文本，而是包含以下文件的完整报告包（保存在 .local/runs/<run-id>/）：

  • report.md：最终研究报告。
  • evidence.json：每条证据保留来源、资料期和原文引用。
  • calculations.json：派生数字的输入、函数和计算 DAG。
  • conflicts.json：跨来源冲突记录，不会静默取舍。
  • manifest.json：模型、版本、阶段、状态和运行清单。
  • viewer.html：浏览器查看证据与报告的可视化页面。

2. 命令行运行一次研究（高级用户）

1
2
3
4
5
6
7
8
9
10
11
# macOS / Linux
node orchestrator/src/run.ts \
  --symbol 300308 \
  --market SZ \
  --python "$(pwd)/.venv/bin/python" < /dev/null

# Windows PowerShell
node orchestrator/src/run.ts `
  --symbol 300308 `
  --market SZ `
  --python "$PWD\.venv\Scripts\python.exe"

完整研究通常需要 15–19 分钟。进度会持续显示，结果写入 .local/runs/<run-id>/。退出码：0 表示完成，2 表示不完整，3 表示失败。

3. 数据覆盖范围

当前注册表包含 117 个数据端点，覆盖 CN（A股）、US（美股）、HK（港股）市场：

  • 数据类别：行情、K线、财务、一致预期、公告、研报、资金、筹码、期权、SEC/FINRA/CBOE、新闻、宏观、产业温度计等。
  • 重要提示：六阶段个股研究目前仅支持 A 股。港美市场不会启动没有完整数据链的研究。

⚙️ 配置与运维

1. 目录结构

1
2
3
4
5
6
7
8
9
10
Vibe-Research/
├── desktop/                # React + Vite 浏览器 UI
├── orchestrator/           # Agent 编排、API、验证、对话管理
├── backtest/               # 回测引擎
├── calc/                   # 确定性计算库
├── datasources/            # 数据端点注册表
├── .agents/skills/         # 金融研究 SOP 和工具定义
├── providers/              # 模型 Provider 模板
├── scripts/                # 初始化与启动脚本
└── .local/                 # 用户私有数据、报告、运行产物 (已 gitignore)

2. 安全与隐私特性

  • 数据本地化：原始研报文件只保存在本机，模型仅接收检索命中的正文片段。
  • Agent 隔离：研究阶段 Agent 无网络访问；取数由编排器使用受控脚本完成，原始响应落盘并记录哈希。
  • API 安全：本机 API 默认只绑定 127.0.0.1，写请求需要鉴权。
  • 合规边界：输出只包含数据、分析框架和情景概率，不提供建仓、加减仓、目标价或止损位等投资建议。

3. 开发与测试

1
2
3
4
5
6
7
8
9
10
11
# 运行 TypeScript 类型检查和测试
npm run typecheck --prefix orchestrator
npm test --prefix orchestrator

npm run typecheck --prefix desktop
npm test --prefix desktop

# 运行 Python 测试（计算库、回测、数据脚本）
.venv/bin/python -m pytest calc/tests -q
.venv/bin/python -m pytest backtest/tests -q
.venv/bin/python -m pytest .agents/skills/data-access/scripts/tests -q

当前验证基线：orchestrator 539 项通过，desktop 25/25 通过，Python 575/575 通过。

❓ 常见问题排查

  • 启动时报 ERR_UNKNOWN_FILE_EXTENSION ".ts"：你的 Node.js 不是支持 TypeScript 的官方构建版本。请从 nodejs.org 重新安装，或使用 nvm/fnm/Volta 安装正确的版本。运行 node -p process.features.typescript 验证。
  • Codex 登录失败或未自动检测：确保按照步骤在“接入 AI”中点击“登录 Codex”完成官方授权。也可以使用命令行后备登录：CODEX_HOME="$(pwd)/.local/codex-home" codex login。Windows 使用 $env:CODEX_HOME="$PWD\.local\codex-home"; codex login。
  • 提示“请先到接入 AI 重新连接”：表示 Codex 或 Claude Code 的本机登录态已失效，需要重新登录，这不是研究逻辑的问题。
  • 个股研究（美股/港股）无法启动：六阶段个股研究目前只支持 A 股。美股和港股可以作为自选股和资料查询，但不会启动完整的六阶段研究流水线。
  • Windows 脚本执行报错：请确保以管理员身份运行 PowerShell，并执行 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser 以允许运行本地脚本。

通过以上步骤，你应该能成功运行一个本地、可扩展的金融研究工作台。它利用 Codex Harness 的能力，将数据获取、研究流程、证据校验和报告生成整合为自动化 Agent 任务，适合个人投资者进行系统化的投研分析。如需完整功能列表和端点目录，可查阅项目 docs/ 和 datasources/CATALOG.md。