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

15 KiB
Raw Blame History

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 卫星。

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 (≥ 1.1) 和 PostgreSQL。控制面运行时仅支持 PostgreSQL;SQLite 只存在于少数历史迁移/离线脚本中。

以下是 macOS + Homebrew 的本地开发库示例。用户名、密码和库名与 .env.example 的 DATABASE_URL 一致,均仅用于本机开发:

# 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 集成说明。TTKB 作为辅助来源,不替代 Streamline 自有 kbContext。

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 据此推进状态机。