7.5 KiB
前端协作开发指南(给同事的 AI Agent)
读者:在同事机器上运行的 AI coding agent(如 Claude Code)。 目标:在同事这台机器上只跑前端(control-web),UI 连到团队中央 control-server(host 那台机器),实现热更新调试 + 编码前端,不在本机跑后端、satellite、数据库。
0. 心智模型(必读,先理解再动手)
这是一个 monorepo(Bun workspaces),分四个包:
| 包 | 作用 | 同事这边要不要跑 |
|---|---|---|
control-server |
控制平面:SQLite 单一真相源 + REST API + WebSocket + 调度 | ❌ 不跑(用 host 那台的) |
satellite |
执行节点:claude 评估/修复、操作 TikTok 仓库 | ❌ 不跑 |
control-web |
前端看板(React + Vite) | ✅ 只跑这个 |
shared |
共享类型 / 协议(被前端 import) | 只读引用,一般不改 |
架构关键点:control-server 是唯一持有数据库的进程。前端从不直连数据库——它通过 /api(HTTP)和 /ws(WebSocket)跟 control-server 通信。所以同事只需把本地 Vite 的代理指向中央 control-server,就能看到和操作和团队完全一样的实时数据,无需任何数据库配置。
同事机器 host(中央服务器)
┌──────────────────────────┐ ┌────────────────────────────┐
│ control-web (Vite :8080) │ /api, /ws │ Caddy :443 │
│ 你在这里改 React 代码 │ ─────────────► │ └─► control-server :5173 │
│ 浏览器 localhost:8080 │ (HTTPS/WSS) │ └─► SQLite (SSOT) │
└──────────────────────────┘ └────────────────────────────┘
1. 硬性约束(DO / DON'T)
DO
- 只修改
control-web/下的代码(React 组件、hooks、样式、lib/)。 - 需要新增/调整共享类型时,可以读
shared/src/types.ts、shared/src/protocol.ts,但改动要谨慎(会影响后端),优先只读。
DON'T
- ❌ 不要启动或修改
control-server/、satellite/。 - ❌ 不要在本机找 / 创建 / 连接 SQLite 数据库——本机没有数据库,也不需要。
- ❌ 不要修改
control-web/vite.config.ts(已做成环境变量驱动,用API_TARGET即可,见下)。 - ❌ 不要提交任何把代理地址、域名、token 写死的临时改动。
⚠️ 数据是共享的生产数据:你连的是团队真实中央库。读取/浏览随意;但点"删除任务""驳回""确认计划"等写操作会真的改到大家的数据。调试 UI 交互时注意别误触发破坏性按钮(delete / abort / reject / confirm)。拿不准就只读浏览。
2. 一次性准备
# 1. 确认在仓库根目录,且 git 是最新的
cd <仓库根> # 包含 control-web/ control-server/ 的那层
git pull
# 2. 装运行时 Bun(如果没有):https://bun.sh
# macOS: curl -fsSL https://bun.sh/install | bash
bun --version # 确认能用
# 3. 安装依赖(在仓库根,Bun workspaces 会装好所有包)
bun install
3. 启动前端(连中央 API)
只要设一个环境变量 API_TARGET 指向中央服务器,然后跑 dev:web:
# 在仓库根执行。把 URL 换成团队 host 的中央地址(向 host 负责人确认域名)。
API_TARGET=https://streamline-internal-api.bytedance.net bun run dev:web
然后浏览器打开 http://127.0.0.1:8080 。
发生了什么:
vite.config.ts检测到API_TARGET,把/api和/ws代理到中央 control-server(自动changeOrigin,HTTPS→WSS 自动换协议)。- 因为是同源代理(浏览器只看到
localhost:8080),没有跨域问题,cookie/请求头照常透传。 - HMR(热更新)走 Vite 默认本地端口,改 React 代码即时刷新。
嫌每次输环境变量麻烦,可在仓库根建一个不提交的
.env.local或直接 export;但不要把它写进vite.config.ts或任何会被 git 跟踪的文件。
4. 验证连通
打开 http://127.0.0.1:8080 后确认:
- 看板能加载出任务卡片(说明
/api/tasks通了)。 - 新任务/状态变化会实时出现(说明
/wsWebSocket 通了)。 - 浏览器 DevTools → Network:
/api/tasks返回 200、/ws是 101 Switching Protocols。
如果加载失败:
/api/*报错 →API_TARGET域名/可达性问题,找 host 负责人确认服务在跑、域名对、你的网络能访问(可能需要 VPN / Tailscale,见第 7 节)。- 页面空白但接口 200 → 是前端代码问题,正常调试即可。
5. 前端代码地图
control-web/src/
├── App.tsx # 主壳 + 看板泳道布局(入口)
├── main.tsx # React 挂载点
├── lib/
│ ├── api.ts # 所有后端接口的 HTTP 封装(要调哪个接口先看这里)
│ ├── sso.ts # SSO 身份(本地开发下大概率拿不到登录态,见第 6 节)
│ └── i18n.ts # 多语言
├── hooks/
│ ├── useTasks.ts # WebSocket 连接 + 任务实时数据(数据流核心)
│ └── useSso.ts # 当前用户/管理员判定
└── components/ # TaskCard / ImportDialog / LogPanel /
# TaskDetailDrawer / Dashboard / Management 等 UI
改 UI → 找 components/。改数据获取/接口 → 找 lib/api.ts + hooks/useTasks.ts。
6. 关于 SSO / 管理员功能
前端有些接口是带身份的(/api/me、/api/admin/*,见 lib/api.ts 里 { authed: true } 的调用)。在同事本机的纯 localhost 环境下,通常拿不到中央 SSO 登录态,所以:
api.me()可能返回email: null, isAdmin: false——这是正常的。- 管理员专属按钮(如
remind、改 admin 名单)在本地可能不可用或报 401/403。
对绝大多数前端 UI 调试没有影响。如果你要调的恰好是管理员功能,找 host 负责人协助(可能需要在中央页面登录、或临时把你的邮箱加进 admin 名单)。
7. 网络访问不通时
如果 API_TARGET 的域名在公网不可达,团队大概率用 Tailscale 等私有网络互联。这种情况下:
- 让 host 负责人邀请你加入 Tailnet。
API_TARGET改用 host 在 Tailnet 内的地址(https://<tailscale-域名或100.x.x.x:端口>)。 其余步骤不变。
8. 提交规范
- 分支:从最新
main切出feat/<你的功能>或fix/<...>,不要直接推 main。 - 改动范围:应当只在
control-web/(必要时含shared/的只读类型补充)。提 PR 前自查git diff --stat没有动到control-server/、satellite/、vite.config.ts。 - 类型检查:
cd control-web && bun x tsc --noEmit(或仓库根bun run typecheck)。 - PR 描述里写清楚改了哪些 UI / 交互,附截图更好。
9. TL;DR(最短路径)
git pull && bun install
API_TARGET=https://streamline-internal-api.bytedance.net bun run dev:web
# 浏览器开 http://127.0.0.1:8080,改 control-web/src/** 即时热更新
只跑前端、连中央 API、看共享真实数据、别碰后端和破坏性按钮。完。