变量	说明
`HOST`	server 监听地址，例如 `127.0.0.1`。
`PORT`	server 监听端口，必须是 `1-65535` 的整数，例如 `7878`。
`DATABASE_URL`	Bright PostgreSQL 连接串；启动 server 和执行 migration 都需要。

本地默认配置如下：

HOST=127.0.0.1
PORT=7878
DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/trade_message_center

OneTalk 开发授权视图

pnpm dev 会以 NODE_ENV=development 启动 server。此时必须配置本地 Mind 授权视图，否则 server 会拒绝启动：

ONETALK_DEV_MIND_USER_ID=mind-user-1
ONETALK_DEV_WORKSPACE_ID=workspace-1
ONETALK_DEV_CHANNEL_ACCOUNT_ID=onetalk-account-1
ONETALK_DEV_BINDING=replace-with-binding
ONETALK_DEV_AUTHORIZATION_VERSION=development-v1
ONETALK_DEV_PERMISSIONS=read,send

变量规则：

ONETALK_DEV_CHANNEL_ACCOUNT_ID 必须与 OneTalk 当前页面 URL 中的 activeAccountId 以及扩展 Popup 显示的 Active account ID 一致。
ONETALK_DEV_BINDING 必须与 Popup 中输入的 binding 一致。binding 不要提交到仓库，也不要写入 URL 或日志。
ONETALK_DEV_PERMISSIONS 只能使用 read、send，或用逗号组合为 read,send；历史读取和同步需要 read。
ONETALK_DEV_AUTHORIZATION_VERSION 是返回给客户端的授权版本字符串；授权视图发生切换时应更新它。
ONETALK_DEV_DEVICE_ID 是可选的兼容字段，不参与开发环境的插件授权匹配。扩展首次运行会自行生成并持久化 device ID，不需要手工生成。
ONETALK_DEV_MIND_USER_ID 和 ONETALK_DEV_WORKSPACE_ID 只属于 server 侧授权上下文，不是扩展 Popup 配置，也不应加入插件消息。

VITE_BRIGHT_WEBSOCKET_URL 用于 Chrome 扩展构建：

VITE_BRIGHT_WEBSOCKET_URL=ws://127.0.0.1:7878/ws

它会在扩展构建时注入，必须使用 ws:// 或 wss://。开发或生产构建未设置该变量时会直接失败，不再回退到代码内置地址。

只有以 VITE_ 开头的变量会暴露给扩展代码，数据库连接串和 binding 等服务端敏感配置不得使用该前缀。

启动 server 与数据库

首次启动或数据库结构有变化时，先执行迁移：

pnpm --filter @trade-message-center/server db:migrate

再从仓库根目录启动 server 和扩展开发构建：

pnpm dev

根命令会统一生成并注入 BUILD_HASH，同时启动 server 和 Popup、MAIN world、ISOLATED world、Service Worker 四个扩展 watch 构建。因此扩展开发不要直接运行底层 Vite 命令。

检查 server 是否启动：

curl http://127.0.0.1:7878/health

预期返回：

{ "status": "ok" }

本地 Bright 联调页位于：

http://127.0.0.1:7878/harness

联调页中的 Mind user、Workspace、OneTalk account 应与 ONETALK_DEV_* 配置一致；认证凭证只在页面内存中使用，不放入 URL。

加载和配置 Chrome 扩展

执行 pnpm dev，确认生成 apps/chrome-extension/dist/。
打开 chrome://extensions，启用“开发者模式”，选择“加载已解压的扩展程序”，加载 apps/chrome-extension/dist/。
打开带有正确 activeAccountId 的 OneTalk 页面 https://onetalk.alibaba.com/，点击扩展图标打开 Popup。
Popup 会从当前页面读取 Active account ID，并首次运行自动生成 Device ID；在 Binding 输入框填入 ONETALK_DEV_BINDING 对应的值后保存配置。
Bright WebSocket URL 仅展示当前构建使用的地址，不在 Popup 中手工填写。配置保存或清除后，Service Worker 会动态建立、重建或关闭 Bright 连接和同步引擎。

扩展配置保存在 chrome.storage.local。Popup 不配置 mindUserId 或 workspaceId；保存 binding 时留空表示保持已有 binding，输入新值才会替换它。清除配置不会重置自动生成的 Device ID。

生产构建：

pnpm build

构建完成后仍可将 apps/chrome-extension/dist/ 作为未解压扩展加载。

Server 数据库迁移

server 使用 Drizzle 的 TypeScript schema 生成版本化 SQL migration。业务表定义放在 apps/server/src/database/schema/，迁移文件和元数据放在 apps/server/drizzle/，相关命令从仓库根目录执行：

pnpm --filter @trade-message-center/server db:generate
pnpm --filter @trade-message-center/server db:check
pnpm --filter @trade-message-center/server db:migrate

生产部署时，先以独立的一次性 job 执行 db:migrate，成功后再启动或滚动更新 server；应用启动不会自动修改数据库结构。已执行的 migration 不可修改，破坏性变更使用新的补偿 migration 和 expand-contract 流程。

测试与质量检查

常用检查：

pnpm format:check
pnpm typecheck
pnpm test
pnpm build
git diff --check

需要执行真实 PostgreSQL 集成测试时，额外提供 TEST_DATABASE_URL：

export TEST_DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/trade_message_center_test
pnpm --filter @trade-message-center/server test

未设置 TEST_DATABASE_URL 时，PostgreSQL 集成测试会明确标记为 skip，不代表真实数据库迁移和事务边界已经验证。

VSCode 开发环境

本项目统一使用 Oxfmt 格式化代码，缩进为 4 个空格。请在 VSCode 中安装 Oxc 插件 oxc.oxc-vscode，否则保存文件时可能使用其它 formatter，导致代码在提交钩子中再次变化。

安装方式：

打开 VSCode 扩展面板（macOS 快捷键：⇧⌘X）。
搜索 Oxc，安装扩展 oxc.oxc-vscode。
重新打开项目窗口，确认右下角或状态栏使用 Oxc formatter。

仓库已经在 .vscode/settings.json 中配置 Oxc 保存格式化，并通过 .oxfmtrc.json 固定 4 空格规则。项目本地依赖已经包含 Oxfmt，不需要单独全局安装。

如果暂时不安装插件，请关闭 VSCode 的 formatOnSave，需要格式化时在项目根目录执行：

pnpm format
pnpm format:check

不要同时启用 Prettier、Biome 或 VSCode 内置 TypeScript formatter。

README.md Unescape Escape

Trade Message Center

本地开发要求

环境变量与授权配置

必填基础配置