Files
streamline/control-web/COLLABORATOR.md
T
2026-11-16 17:26:44 -08:00

7.5 KiB
Raw Blame History

前端协作开发指南(给同事的 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 后确认:

  1. 看板能加载出任务卡片(说明 /api/tasks 通了)。
  2. 新任务/状态变化会实时出现(说明 /ws WebSocket 通了)。
  3. 浏览器 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 等私有网络互联。这种情况下:

  1. 让 host 负责人邀请你加入 Tailnet。
  2. 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、看共享真实数据、别碰后端和破坏性按钮。完。