# 前端协作开发指南(给同事的 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. 一次性准备 ```bash # 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`: ```bash # 在仓库根执行。把 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://`)。 其余步骤不变。 --- ## 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(最短路径) ```bash 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、看共享真实数据、别碰后端和破坏性按钮。完。