Files
2026-11-16 17:26:44 -08:00

205 lines
15 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# BBBBBBug
本机 Claude 工具的持续 Bug 修复调度台。技术栈:**Bun + Vite + React + PostgreSQL + Drizzle ORM + Hono + WebSocket**。
## 目录结构
本仓库是一个 bun workspaces monorepo,拆成四个包,便于把卫星服务单独部署到其他设备:
```
.
├── shared/ # 纯类型 + 协议常量(无副作用,三端共享,单一真相)
│ └── src/ types.ts · protocol.ts
├── control-web/ # ①控制面前端 (Vite + React)
│ └── src/ App.tsx · components/ · hooks/useTasks.ts · lib/api.ts
├── control-server/ # ②控制面后端 (Bun + Hono):元数据唯一数据源 + API + WS + 调度
│ └── src/
│ ├── index.ts # 入口;HTTP + WS + 注入卫星 host + 启动调度
│ ├── routes.ts # /api/* REST
│ ├── db_client.ts # PostgreSQL/Drizzle 连接池,数据访问的唯一入口
│ ├── db.ts # 任务状态/元信息的数据访问层
│ ├── enrich.ts # 在 DB 行上叠加工作区文件 + watcher 名(供展示)
│ ├── classifier.ts meego.ts importer.ts notify.ts lark*.ts watchers.ts bus.ts
│ └── workspace.ts # 转发 satellite 的 FS 助手 + enrich(保持 ./workspace 导入不变)
└── satellite/ # ③卫星后端 (Bun + Hono):本机能力 + 工作区,可单独部署
└── src/
├── host.ts # 控制面注入的依赖契约(db/bus/notify/enrich)
├── evaluator.ts # claude 评估复现性,产出 TestSpec
├── runner.ts # 任务执行:git reset → checkout → claude -p loop → MR
├── workspace.ts # 工作区 FS(bootstrap/读写/evidence/log/图片下载/watcher)
└── index.ts # 独立进程入口(Phase 2 启用 /sat/* + 自注册)
```
## 集群运行(控制面 + 卫星)
控制面是唯一的元信息/状态数据源;卫星是干活的执行机(评估 + 修复 + 工作区文件),按平台(android/ios)拉取任务。本机既跑控制面、又作为第一个 android 卫星。
```bash
cp .env.example .env # 按需修改(见 # --- Cluster / Satellite 段)
# 终端 1 — 控制面(API + WS + 调度/转发),默认 :5173
bun run start # 生产;或 bun run dev:server 开发热更
# 终端 2 — 前端,绑 127.0.0.1:8080(dev 代理 /api、/ws 到 5173)
bun run dev:web
# 终端 3 — 本机 android 卫星,默认 :5180,自注册到控制面
bun run start:satellite # 或 bun run dev:satellite
```
卫星启动后会出现在面板顶部「集群」栏。再接一台机器(如 iOS):把仓库同步过去(或 `bun run build:satellite` 产出自包含 `satellite/dist/satellite.js` 拷过去),在 `.env` 设 `AGENT_HOST=fei-ios-01.shiro0.icu`、`AGENT_PLATFORM=ios`、`CONTROL_PLANE_URL=http://<控制面host>:5173`,跑 `bun run start:satellite` 即可——该技术栈执行容量随之 +1。多机请在两端设置相同的非空 `CLUSTER_SECRET`。
若某台卫星机只负责 Evaluate,在它的 `.env` 配置 `DISABLE_RUN=true`。该节点仍启动 Evaluate claim 循环,但不上报 Run 容量,也不会启动 Bugfix、Feature、Security、Prototype、Verify 共用的 Run scheduler;评估产出 READY 后会解除任务与该节点的绑定,由同平台、同集群且具备 Run 能力的卫星机继续认领。未配置或设为其他值时保持原行为。
> Phase 2 已落地:卫星独立进程 + 自注册/心跳;控制面按平台分派、文件/abort/retry 转发到承载任务的卫星、状态回写;前端集群栏 + 节点徽标。任务硬绑定到首个 claim 它的卫星(home node),节点掉线则其任务自动释放给同平台健康节点重建工作区。
### Android Security 启动修复
Security 的 pre/patch/post 地址固定在 `satellite/src/security_runner.ts` 与 SDLC 的 procedure 脚本中,并通过 `voffline.byted.org/download/tos/schedule` 多 Region 下载网关访问。当前使用正式产物 `security-tiktok-run-pre_2610222007.sh` 和 `security-tiktok-run-post_2609221459.sh`,pre 固定下载组合 patch `security-tiktok-patch_2610131147.sh`。该 patch 保留 ByteFun YAML/abmock 兼容与 Slardar Custom Event 动态采集;v24 在原有 `pumbaa_standard_event` 规则上,精确过滤 `pumbaa_runtime_performance`、`pumbaa_performance`、`pns_logging_drop_keys_monitor` 的已知 ApmAgent 入口。其余事件和参数保持原样,不做去重。新版 pre 在 patch 完成后补写 `.streamline-live-hot-update-patch.json`,兼容当前 runner 的报告读取,避免任务的 `SecurityPreparation.json` 中 `git_head` 和业务补丁详情被覆盖为 null。后续更新先发布 patch,再更新 pre 的固定地址并发布 pre/post,最后更新 runner;SDLC 的 `comp_check/procedure/publish.md` 记录各产物的 SHA256 与源 commit。继承的 `STREAMLINE_SECURITY_PATCH_URL` 不会改变 Security hook 的固定补丁。
Security evaluate/run 会保留 Cursor CLI 的限长、脱敏错误;钥匙串锁定归类为 `AGENT_AUTH_FAILED`,额度耗尽归类为 `AGENT_USAGE_LIMIT`,不把两者混用。feature、bugfix 与 asking 不启用这项诊断。诊断逻辑不自动解锁或修改钥匙串,不改变现有额度预警、耗尽后的登录轮换流程。
Cursor 账号恢复期间,一张告警卡片对应一次登录流程。原登录进程仍在等待时,轮询、重复告警和并发请求复用原链接,不重复 login/logout,也不结束原进程。进程退出后立即运行 `cursor-agent whoami --format json`,再查询额度;账号身份一致、额度查询成功且所有主额度都达到现有 5% 阈值后才恢复领取任务,同一账号额度恢复也可通过。检查不通过时,清理已退出的句柄,重新发起 login(不再 logout),将新 URL 通过现有 `/api/v1/lark-card` 接口发送。连续快速失败至少间隔 30 秒再生成挑战;卡片发送失败会用同一 URL 补发。额度查询失败的告警也跟踪登录流程,但不会因此暂停领取任务。恢复登录不会自动重跑此前失败的任务。
pre 的业务临时修复记录保存在任务目录的 `SecurityPreparation.json`。报告必须说明已应用的 workaround,不能把修补后的监听逻辑当作原始 targetRef 的运行证据。新版 post 将可选 coverage 收集限制在独立进程组内,最多 240 秒;超时或提取失败仍继续审计与 AppLog,审计 merge/case_name 的必需条件不变。
独立卫星机按阶段完成顺序合并统计 Security evaluate/run 的最终结果。连续三个不同任务执行失败时停止任务循环,给状态写回和持久化回调最多 5 秒收尾,再以退出码 1 退出。自动重试不单独计数,同一任务重复失败只计一次;正常 READY、NEEDS_INFO 或 Run EVIDENCE_READY 会清零,人工取消及 Asking 不计数。Evaluate 超时且无法恢复完整结论、异常或无合法 ASSESSMENT 的情况也算执行失败,沿用原有任务状态与回调口径。计数在进程重启后清零,控制面不会启用此退出策略。整个进程退出可能中断同机其他任务;现有 `run-satellite.sh` 会在退出后自动重启,未改守护配置。
## HTTPS(对外入口)
前端通过 **Caddy 反向代理**对外提供 HTTPS,主域名 `https://streamline.shiro0.icu`(旧域名 `https://fei.shiro0.icu` 保留降级,二者指向同一服务)。Vite 只绑 `127.0.0.1:8080`、由 Caddy 终止 TLS:
```
浏览器 ──https/443──▶ Caddy(占 80/443,自动 80→443 跳转)──▶ 127.0.0.1:8080(Vite)──/api,/ws──▶ :5173
```
- **证书**:`*.shiro0.icu` 通配证书,由 **acme.sh 走 DNS-01(`dns_ali`,Let's Encrypt)**签发,复用 **ddns-go 里同一把阿里云 AccessKey**(无需开放 80/443 给公网,适配动态 IP / 内网)。acme.sh cron 自动续期并 `caddy reload`。
- **ddns-go**:只负责把 `*.shiro0.icu` 的 A 记录指到本机(en1),**不签发证书**。
- 关键文件:Caddyfile `/opt/homebrew/etc/Caddyfile`;证书 `/opt/homebrew/etc/caddy/certs/shiro0.icu.{crt,key}`。
- Caddy 是 `brew services` 托管(开机自启);**Vite 不是托管服务**,需自行常驻 `bun run dev:web`。
- 新增子域 HTTPS:在 Caddyfile 加一段 + 把 host 加进 `control-web/vite.config.ts` 的 `allowedHosts`,通配证书已覆盖、无需重签。
数据落地:
- 任务状态 / 元信息 → `DATABASE_URL` 指向的 PostgreSQL
- 任务日志 / Meego 元数据 / 证据 → `~/taskLog/<taskId>/`
- TikTok 工程位置 → 默认 `~/workspace/TikTok`(可通过 `TIKTOK_REPO` 覆盖)
## 第一次启动
需要先在本机安装 [Bun](https://bun.sh) (≥ 1.1) 和 PostgreSQL。控制面运行时仅支持
PostgreSQL;SQLite 只存在于少数历史迁移/离线脚本中。
以下是 macOS + Homebrew 的本地开发库示例。用户名、密码和库名与
`.env.example` 的 `DATABASE_URL` 一致,均仅用于本机开发:
```bash
# PostgreSQL 只需初始化一次
brew install postgresql@18
brew services start postgresql@18
psql postgres -c "CREATE ROLE streamline WITH LOGIN PASSWORD 'streamline';"
createdb --owner=streamline streamline_dev
# 在仓库根目录;不要把本地开发服务指向生产数据库
cp .env.example .env
bun install
# 从当前 Drizzle schema 创建空的本地开发库结构
bun x drizzle-kit push
# 开发模式:两端各起一个进程
bun run dev:server # 在 http://127.0.0.1:5173 启动后端 + WS + 调度器
bun run dev:web # 在 http://127.0.0.1:5174 启动前端 (代理 /api 和 /ws)
```
若 `streamline` 角色或 `streamline_dev` 数据库已经存在,跳过对应的创建命令即可。
打开 http://127.0.0.1:5174 即可使用。
> 想在 **没有真实仓库 / claude / Meego token** 的情况下试跑 UI:把 `.env` 里 `BBBBBBUG_DRY_RUN=1` 置 1,任务会跳过所有外部调用,只在本地 PostgreSQL + 日志里走完一遍流程。
`bun x drizzle-kit push` 适用于全新、可丢弃的本地开发库。已有数据库或生产数据库必须走
`drizzle/` 中经过评审的迁移文件;不要用 `push` 同步生产 schema。
## 生产打包 & 单进程运行
可选业务知识包的安装、任务选择、审计口径及发布/回退步骤见 [TTKB 集成说明](docs/ttkb-integration.md)。TTKB 作为辅助来源,不替代 Streamline 自有 `kbContext`。
```bash
bun run build # 编出 control-web/dist
bun run start # 控制面后端会自动 fallback 到 control-web/dist 提供静态资源
```
只起一个 Bun 进程,前后端在同一端口下。
## 功能映射(按需求章节对齐)
### 管理段
| 需求 | 实现位置 |
| --- | --- |
| Priority list 三段:已执行 / 正在执行 / 待执行 | `web/src/App.tsx` |
| 已执行任务置灰、可展开看 MR / 截图 / Log / 执行记录下载 | `TaskCard.tsx` → `Details` + `/api/tasks/:id/log-file` + `/api/tasks/:id/evidence/:kind` |
| 打开页面默认导航到正在执行的任务 | `App.tsx`:`runningRef.scrollIntoView` |
| 正在执行:呼吸灯 + 实时已运行时间 | `.breathing` 动画 + `nowTick - startedAt` |
| 待执行:置顶 / 取消置顶,一次仅一个置顶 | `db.ts: pinTask()` (清掉旧置顶后置新) |
| 步骤不清晰始终最低优先级;补充 Remark 后回到正常排序 | `db.ts: rebuildPendingPriority` 中 `effectiveClear` |
| Buglist 批量导入(meego 链接) | `ImportDialog.tsx` + `POST /api/import` |
| 去重、Classifier 打标、入库到合适位置 | `routes.ts: /api/import` + `classifier.ts` + `rebuildPendingPriority` |
| 标签:UI/逻辑、Android/iOS、低中高难度、步骤清晰度 | `classifier.ts` |
### 执行段
| 步骤 | 实现 |
| --- | --- |
| 1. reset 到 develop | `runner.ts`: `git fetch / checkout develop / reset --hard origin/develop / clean -fd` |
| 2. checkout bugfix 分支 | `branchNameFor(meegoId)` → `git checkout -b bugfix/meego-<id>` |
| 3. 提取 Meego 信息 | 已在导入时抓取;运行前再写一份 `~/taskLog/<id>/meego.json` |
| 4. `claude -p` 无头 session 修复+验证 Loop,记录 Log | `runClaudeRound` 用 `claude -p --output-format stream-json --verbose` |
| 4.1 多次复现失败 → 无法复现 | 提示词强制 `STATUS: UNREPRODUCIBLE` |
| 4.2 修复 → 构建 → 再次复现 | 同一会话内逐轮执行 |
| 4.3 超过 5 轮强制结束并标识无法修复 | `MAX_ROUNDS=5`;循环结束默认 status = `unfixable` |
| 4.4 修复前/后证据 | `evidence/before.txt`, `evidence/after.txt` → 复制到 `~/taskLog/<id>/` → 前端可下载预览 |
| 5. 提交 MR 并入库展示 | `git add/commit/push` + `gh pr create` → 解析 URL 落库,前端展示 |
## 自我改进闭环(RSI)
平台会用自己产出的数据改进自己的做事方法:自动实验回路发现问题、提出 prompt
或运行时旋钮的改法,在实验机上拿跑过的历史任务新旧各跑一遍对比;效果成立的改法
由人改进代码上线。配套还有修复质量指标、知识注入的效果归因、以及从会话日志里
挖「该被工具化的重复命令」。
**提示词都是代码**(`shared/src/*_prompt.ts` 等):改常量 + 部署即生效,控制面派发时把
正文随任务下发;版本历史就是 git。没有库版本、激活指针或审批流程。
- 面板:**看板 → 自我改进**(`/rsi`;实验室成员或管理员均可见,暂停 / 撤回类操作需登录身份)
- API:`/api/rsi/*`(读与提案可用 cluster secret;批准与回路操作必须是登录用户)
- 定时:`scripts/rsi-daily.sh`(北京时间每日 09:10,自身按 TZ 自锁)
- 设计与指标定义:**`docs/rsi.md`**
## REST + WebSocket 一览
```
GET /api/health
GET /api/tasks
GET /api/tasks/:id
GET /api/tasks/:id/logs?sinceId=N
GET /api/tasks/:id/log-file
GET /api/tasks/:id/evidence/before
GET /api/tasks/:id/evidence/after
POST /api/tasks/:id/pin
POST /api/tasks/:id/unpin
POST /api/tasks/:id/remark { remark: string }
POST /api/preview { links: string | string[] }
POST /api/import { links: string | string[] } # 要 SSO,建单人只认登录身份
GET /api/stats # 不同难度的召回率基础数据
WS /ws # 推送 task:created / task:updated / queue:reordered
```
## 关于本机 `claude` 工具
执行端调用 `claude -p <prompt> --output-format stream-json --verbose`,工作目录设为 `TIKTOK_REPO`。建议确保 claude CLI 在该工程下能够:
- 操作连接的设备(adb / xcrun simctl 等)
- 修改 / 构建 / 重启 App
- 在 `evidence/before.txt` 和 `evidence/after.txt` 写下复现/修复证据(截图可以 base64 / 路径写入,前端按文本预览)
每轮 prompt 强制以 `STATUS: <FIXED|REPRODUCED_NEEDS_FIX|UNREPRODUCIBLE|BLOCKED ...>` 结尾,runner 据此推进状态机。