Vibe-Research 环境配置清单：Node、Python 与 Git 安装避坑指南-港品优选

Vibe-Research 环境配置清单：Node、Python 与 Git 安装避坑指南

【免费下载链接】Vibe-ResearchVibe-Research: Your Personal Trading Research Agent · A股/美股/港股的个人投研 Agent：每日复盘、资讯雷达、个股数据、板块中心、我的持仓、研究记录、回测。Vibe-Research 把数据和功能配齐，由你自己的 Agent 驱动投资研究。基于开源的 Codex Harness 打造。项目地址: https://gitcode.com/gh_mirrors/vi/Vibe-Research

Vibe-Research 是面向 A股/美股/港股的个人投研 Agent，支持每日复盘、资讯雷达、个股研究、回测等功能。从源码运行它只需备好三样软件：Node.js、Python 和 Git。这份环境配置清单帮你确认版本要求、完成一键安装，并绕开 5 个最常见的坑，约 10 分钟跑起本地投研工作台。

一、环境要求速览：1 分钟看清 3 个工具版本

软件	最低版本	推荐版本	用途
Node.js	≥ 22.18	24 LTS	驱动后端编排器与浏览器界面
Python	≥ 3.11	3.12（官方已验证）	计算库、回测引擎与取数脚本
Git	近期任意版本	最新稳定版	克隆仓库与日常更新

操作系统支持Windows 11（原生运行，不要求 WSL）、macOS 和 Linux，三端都走同一套源码流程。

⚠️ 关键前提：无需单独安装全局 Codex，Agent 引擎随依赖安装，初始化脚本会一并处理。

二、Node.js 安装：2 个硬性要求要记牢

这是新手最容易踩坑的地方，请对照自查 👇

要求 1：版本必须 ≥ 22.18。项目不做构建打包，而是让 Node 原生执行 TypeScript 源码（22.18 起"类型剥离"默认开启），版本不够直接跑不起来。

要求 2：必须是启用了 TypeScript 支持的构建。部分 Linux 发行版 apt / yum 仓库里的 Node 编译时关闭了这一项，版本号够了也会报错。

安装完在终端执行一条自查命令：

node -p process.features.typescript

输出strip或transform即合格 ✅。如果输出undefined或启动时报ERR_UNKNOWN_FILE_EXTENSION ".ts"/ERR_NO_TYPESCRIPT，说明你装到了发行版特供构建，请改用nodejs.org 官方安装包，或用nvm / fnm / Volta重新安装 Node 22.18+ / 24 LTS。

这个检查逻辑写在 scripts/check-node.mjs，setup、start、doctor等脚本启动前都会先跑它，并给出可照做的中文提示，不会只甩一个晦涩的报错。

三、Python 安装：版本达标即可，虚拟环境全自动

需要Python ≥ 3.11，推荐3.12（项目已在本机验证）。
无需手动建虚拟环境：setup会按python3.12 → python3.11 → python3 → python的顺序自动探测合格的解释器，然后创建项目内.venv并安装取数依赖。
如果提示"未找到 Python 3.11 或更高版本"，装好新版 Python 重跑一次即可，不用重新克隆仓库。

Python 侧的依赖清单见 .agents/skills/data-access/scripts/requirements.txt，安装脚本已替你处理，一般不用关心细节。

四、Git 克隆仓库 + 3 条命令完成一键安装

Git 只负责一件事：把仓库克隆到本地。

git clone https://gitcode.com/gh_mirrors/vi/Vibe-Research vibe-research-agent cd vibe-research-agent

然后按系统选择安装脚本（均在仓库根目录执行）：

macOS / Linux

scripts/setup

Windows（PowerShell / CMD）

scripts\setup-windows.cmd

setup会一口气做完 6 件事，不用你逐个敲命令：

检查 Node / npm 是否存在，并跑 scripts/check-node.mjs 预检
探测合格的 Python，创建.venv虚拟环境
pip安装数据访问依赖
npm ci安装后端（orchestrator/）与前端（desktop/）依赖
初始化产品私有数据层.local/（目录、配置骨架、.gitignore），不读写你的~/.codex
运行产品体检（doctor），并给出中文修复提示

脚本细节与 Windows PowerShell 版入口（init.ps1/doctor.ps1）说明见 scripts/README.md。

五、doctor 体检：安装后的"环境体检单"

初始化最后会自动跑一次体检；如需手动复查，直接运行：

scripts/doctor # macOS / Linux scripts\doctor.ps1 # Windows PowerShell

体检覆盖 Node 版本、产品配置链、Codex 引擎二进制、登录态、Python 与取数依赖、calc 自检、注册表、数据根写权限和密钥扫描，每一项都标注ok / warn / fail / skip并附中文修复提示，报告写入.local/doctor/<时间>.json。

记住退出码含义：0全部正常，2只有警告（可先启动，按提示处理），3存在失败项（必须先修复）。

六、启动工作台：看到首页就配置成功了

一切就绪后，启动命令只有一条：

scripts/start # macOS / Linux scripts\start.cmd # Windows

start会先做端口与安装状态预检，同时拉起本机 API 和浏览器界面，真实健康检查通过后才自动打开浏览器，无需开两个终端。默认地址：

浏览器界面：http://127.0.0.1:5930
后端 API 回环端口：8765

macOS / Linux 可加--no-open阻止自动打开浏览器；按Ctrl+C会同时关闭两端。看到首页出现，即代表环境配置全部到位 🎉

端口被占用的提醒：5930/8765是默认地址，不代表当前已有服务在跑；若提示端口占用，先确认端口属于哪个项目，不要贸然终止其他服务。更多交付背景见 docs/source-delivery.md。

七、5 个高频坑位速查表

现象	原因	解决方案
报`ERR_UNKNOWN_FILE_EXTENSION ".ts"`或`ERR_NO_TYPESCRIPT`	发行版 Node 关闭了 TypeScript 支持	换 nodejs.org 官方安装包，或 nvm / fnm / Volta 装 24 LTS
`node -v`够新但仍启动失败	同上，构建问题不是版本问题	跑`node -p process.features.typescript`自查
setup 提示"未找到 Python 3.11 或更高版本"	系统 Python 过旧	安装 Python 3.12 后重跑`setup`，无需重新克隆
`npm ci`慢或失败	网络波动	重跑一次`setup`（可重复执行）；必要时配置 npm 镜像
doctor 退出码`3`（有 fail）	环境某项未通过	按屏幕中文提示逐项处理，或看`.local/doctor/`下的 JSON 报告

写在最后

把这份清单收好：Node ≥ 22.18（TS 构建）+ Python ≥ 3.11 + 任意近期 Git，克隆后一条setup、一条start，本地投研工作台即可开工。遇到任何报错，优先跑doctor看中文修复提示，比盲目重装更高效。

配置完成后，记得进入"接入 AI"连接你自己的模型订阅或 API，Vibe-Research 的复盘、研究、回测功能就能真正跑起来了。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析