Vibe-Research: Instructions file for Codex

Vibe-Research — 给 Agent 的部署与开发指南

你是来帮使用者部署、使用或改造本仓库的 Agent(Claude Code、Codex、WorkBuddy / CodeBuddy、Muse 一类个人云端 Agent……)。动手前先读完这一页。

研究方法论不在这里。研究线程的最高纪律是 methodology/constitution.md(研究宪法), 研究 SOP 在 .agents/skills/,计算函数契约在 calc/SPEC.md。产品在每个研究阶段把它们放进提示词,对所有大脑一视同仁; 它们约束的是研究线程里的大脑,不是你在本仓库里的工作方式。

1. 这是什么

本地运行的 A 股个股研究工作台:浏览器页面 + 本机服务 + 六阶段研究编排器 + Python 取数层 + 确定性计算库(calc/)。 研究的「大脑」可以换,换了以后受控工具、方法论、校验与合规 gate 都是同一套:

大脑	接法	登录与凭据
Claude Code	本机 claude CLI	使用者本人在终端用 claude.ai 订阅登录(API key / Bedrock / Vertex 登录不算订阅);产品不读、不存、不复制登录文件
Codex	本机 codex CLI	使用者本人在终端 codex login 用 ChatGPT 账号登录(Codex 里配的 API key 登录不认);同上
WorkBuddy / CodeBuddy	本机 codebuddy CLI(独立 CLI 或 WorkBuddy 桌面版内置)	使用者本人在终端运行 codebuddy 登录独立 CLI(新版 WorkBuddy 桌面版的登录加密保存,产品借不到);同上
模型 API	任意 Chat Completions 兼容接口(模板见 providers/)	页面里填的 key 只存在浏览器 localStorage,随请求交给本机服务,不落盘;命令行研究从模板声明的环境变量读 key

研究线程里的大脑没有 Shell、没有网络、没有任意文件读写,只有 5 个受控工具:列文件、读文件、确定性计算、写阶段产物、写报告。 取数由编排器在每个阶段开始前执行完;大脑想收工时,产品先做收工检查,产物缺失或校验不过就把问题清单交回去接着修。

2. 帮使用者部署

环境:Node.js ≥ 22.18、Python ≥ 3.11(推荐 3.12)、git。

git clone https://github.com/simonlin1212/Vibe-Research.git
cd Vibe-Research
scripts/setup     # Windows:scripts\setup-windows.cmd
scripts/start     # Windows:scripts\start.cmd

• scripts/setup 创建 .venv、安装依赖、生成产品私有层 .local/ 并跑体检;scripts/doctor 可单独再跑(--json 给机器读)。
• scripts/start 同时拉起本机 API 与页面,健康检查通过后打开 http://127.0.0.1:5930。 默认端口(页面 5930、API 8765)被占用或被系统保留时自动换空闲端口并在终端说明,以终端打印的地址为准; 换了页面端口时,浏览器里存的模型 API 设置和对话记录按地址分开,要在新地址重新设置(终端会提醒;默认端口空出来后重启就回到原来的); 要固定端口用 --port / --api-port(Windows -Port / -ApiPort)或环境变量 VRA_UI_PORT / VRA_API_PORT,指定的端口不能用时直接报错。 启动时提示「已经有一个 Vibe Research 在运行」:让使用者直接打开那个地址,不要终止别的进程去抢端口。
• 页面打开后到左侧栏最下方的「接入 AI」选大脑并做一次真实对话测试,测试通过才会保存。 本机 CLI 要先由使用者本人登录(claude / codex login / codebuddy);登录发生在使用者自己的终端和浏览器里,你不代填、不转存任何账号信息。
• Windows 上 WorkBuddy 装在别的盘也会从「已安装的程序」登记或正在运行的 WorkBuddy 里自动找到; 仍显示「未安装」时:先打开 WorkBuddy 再点「重新检测」,或在「接入 AI」的 WorkBuddy 卡片里填它的安装文件夹, 或在启动前设环境变量 CODEBUDDY_BIN / CLAUDE_BIN / CODEX_BIN(设了就只认它)。
• 所有私有数据(配置、运行产物、对话、台账、上传资料)都在 .local/,已被 git 忽略。不要把它提交、打包或发给任何第三方。
• 使用者不想装 Node / Python / git 时,让他到 Releases 下载免安装包(Windows x64 / Apple 芯片 / Intel Mac),解压后双击 Start-VibeResearch; 数据在包文件夹的 .local/,升级 = 新版本解压到新文件夹再把 .local/ 整个复制过去。包由 .github/workflows/portable.yml 构建 (本机构建:node scripts/portable/build.mts;冒烟:node scripts/portable/smoke.mts <解压出来的目录>), 包里 Node / Python 的版本、下载地址和 SHA256 只写在 scripts/portable/runtimes.json,升级运行时只改这一个文件。
• 页面每天查一次 GitHub 最新正式版本(只带版本号;没查成隔一小时再试);设环境变量 VRA_UPDATE_CHECK=0 完全不联网。