QUICKSTART

这份文档面向第一次部署和第一次跑通 CollabVibe 的读者，目标是在最短路径内完成：

• 安装依赖
• 配置环境变量
• 准备 backend 与 workspace
• 启动服务
• 在 Feishu 中验证消息与卡片链路

Placeholder：在这里插入“从本地启动到飞书收消息”的总览图，建议标出 .env、data/、workspace、Feishu App 四个关键点。

1. 运行前提

项目	说明
Node.js	用于运行 tsx、VitePress、测试脚本
npm / pnpm 兼容环境	当前仓库脚本以 npm run 形式提供
本地文件系统	保存 data/、配置、日志、SQLite、workspace
Feishu 应用凭据	当前主平台必需
backend 可执行命令	例如 codex app-server

node -v
npm -v

2. 安装依赖

npm install

3. 准备环境变量

推荐从现有环境模板或本地部署变量开始整理，至少准备以下变量：

变量	必填	作用
FEISHU_APP_ID	是	Feishu 应用 ID
FEISHU_APP_SECRET	是	Feishu 应用密钥
FEISHU_SIGNING_SECRET	否	事件签名校验；Stream 模式通常可不填
FEISHU_ENCRYPT_KEY	否	加密事件支持
CODEX_APP_SERVER_CMD	建议	backend 启动命令
CODEX_WORKSPACE_CWD	建议	工作区根目录
CODEX_SANDBOX	否	默认 sandbox 策略
CODEX_APPROVAL_POLICY	否	默认审批策略
APPROVAL_TIMEOUT_MS	否	审批超时
PORT	否	服务监听端口
SYS_ADMIN_USER_IDS	建议	初始系统管理员 ID 列表

cp .env.example .env

FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=xxx
CODEX_APP_SERVER_CMD=codex app-server
CODEX_WORKSPACE_CWD=/abs/path/to/workspace
SYS_ADMIN_USER_IDS=ou_xxx
PORT=3100

Placeholder：在这里插入 .env 示例或部署平台环境变量配置截图。

4. 准备本地目录

运行时会依赖以下目录：

路径	说明
data/codex-im.db	SQLite 主库
data/config/	backend 配置目录
data/logs/	运行日志
CODEX_WORKSPACE_CWD	代码工作区根目录

mkdir -p data/config data/logs
mkdir -p /abs/path/to/workspace

5. 启动服务

开发模式：

npm run start:dev

生产模式：

npm run start

文档预览：

npm run docs:dev

Placeholder：在这里插入服务启动成功的终端截图，建议保留端口、日志文件目录和 Feishu WS 启动信息。

6. 完成 Feishu 平台接入

CollabVibe 当前主平台是 Feishu。第一次部署时，需要先在平台侧完成 Bot 创建、权限开通、事件订阅与可见范围发布。

• 平台步骤详见 Feishu 平台接入
• 如果只是了解现状，可同时参考 Slack 平台接入

Placeholder：在这里插入 Feishu 平台配置完成页截图。

7. 最小验证

建议按下面顺序验证：

1. 服务已启动，无启动时报错
2. Bot 已加入目标群聊或单聊可见
3. 用户发送消息后可触发事件
4. 机器人可返回消息或卡片
5. data/logs/app.log 中可以看到对应日志

tail -f data/logs/app.log

npm run test:workspace

8. 常用命令

npm run start:dev
npm run start
npm run docs:dev
npm run docs:build
npm run test:workspace
npm test

Placeholder：在这里插入 1~3 分钟 Quickstart 录屏，建议包含“启动服务 -> 飞书发消息 -> 查看日志”。

下一步

• 想理解系统全貌：看 系统总览
• 想理解三大核心对象：看 核心类：Project / Thread / Turn
• 想理解日志：看 日志系统