Initial import of streamline

This commit is contained in:
2026-11-16 17:26:44 -08:00
commit 8e4aec1855
1221 changed files with 274256 additions and 0 deletions
+85
View File
@@ -0,0 +1,85 @@
# Streamline — 给 Claude 的项目说明
架构、目录、部署、HTTPS 见 `README.md`,此处不重复。这里只写**在这个仓库里干活时的规矩**。
## 生产环境的三条边界
这个仓库的代码跑在生产上,且本机能直接够到生产数据。所以:
1. **默认只读。** 读生产状态(任务记录、日志、证据、报告)随便读;任何写操作——重跑/abort 任务、改 plan、发 MR、改 Meego 状态、发飞书通知——**必须先跟用户确认**,即使它只是"顺手把这个卡住的任务重启一下"。
2. **生产 DB 只允许 SELECT。** 生产环境的 `DATABASE_URL` 指向线上 PG,本机虽可直连,仍禁止 INSERT / UPDATE / DELETE / DDL;schema 变更一律走 `drizzle/` 迁移 + 部署流程,不要手改线上表。本地开发应使用 README 中的隔离 PG,绝不能把 dev server 指向生产库。
3. **不要把 `.env` 的内容打印到对话里。** 里面有 PG 口令、Meego / Lark / TOS 凭据。需要引用配置项时引用 `.env.example` 的键名。
## 读生产状态:走内网只读 API,不要直连 DB
| 用途 | 入口 |
|---|---|
| 面板(人看) | `https://streamline.bytedance.net` |
| 只读 API(Agent 用) | `https://streamline-internal-api.bytedance.net/api/*` — 内网直达,无需 token |
| 生产部署 | devbox `fdbd:dc01:ff:31a:6973:d9b4:988a:23c0`,`/data00/home/jiaopengwen/streamline`,以 `jiaopengwen` 身份运行 |
优先用只读 API 而不是直连 PG,原因不是麻烦,是**能力更全**:session 日志、ImplReport、证据都在各卫星的本地磁盘上(`~/taskLog/<id>/`),只有控制面知道某个任务落在哪个 home node 并替你代理过去;DB 里只有元数据。走 API 一个 host 通吃,且不用把生产库口令放进任何脚本。
## 部署到生产:用 `streamline-deploy` skill
用户说"部署 / 上线 / 发布"时,走 `.claude/skills/streamline-deploy/`:`deploy.sh` 一条命令完成
拉代码 → 构建 → 重启 → 验证,并在预检阶段拦住脏工作区。`--check` 是纯只读的预检。
手写这套命令几乎一定会错:仓库在 `/data00/home/jiaopengwen/streamline`(不是 `~/…`)、
必须 `sudo -u jiaopengwen` 跑(否则 git 报 dubious ownership)、`bun` 不在该账号的
非交互 PATH 里、而且**没有 `streamline-web` 这个 unit**——前端是 control-server 自己
静态托管 `control-web/dist`,重启 `streamline-server` 就够了。细节与理由见该目录 `SKILL.md`。
注意它只覆盖控制面。改了 `shared/` 或 `satellite/`(典型是 prompt)时卫星仍跑旧代码,
需要另行发布;改了报告生成逻辑时历史数据不会被追溯重写,要回填。
### DeviceSim 的 skill 由节点自己维护,卫星只上报
iOS 节点上 `ai_workspace/.claude/skills/{airbuild,catuse-cli}` 卫星**不再接管**(曾随卫星包强制分发,已撤掉):
卫星启动时只读看一眼它们指向哪里、是哪个 DeviceSim commit,随心跳上报(`/api/nodes` 的 `devicesimSkills`),
不写任何文件。以前分发留下的 `~/.streamline/devicesim-skills/<sha>/` 快照和软链原样留在节点上,要更新 skill
得去节点上自己改。见 `satellite/src/devicesim_skills.ts` 头注释。
## 回溯某个任务:用 `streamline-retro` skill
用户丢一个 task id / 面板 URL 过来问"为什么失败 / 当时发生了什么"时,走 `.claude/skills/streamline-retro/`:一条命令把该任务的全部产物拉到本地,再把 3–5 MB 的 session 日志压成可读时间线。细节见该目录下的 `SKILL.md`。
首次使用需要把 `.claude/skills/streamline-retro/settings-snippet.json` 里的两块合并进 `.claude/settings.local.json`(Claude 改不了权限配置,必须人工粘)。
## 改 prompt:直接改代码
所有提示词(评估、执行、critic、可读性报告……)都是代码常量,在 `shared/src/*_prompt.ts`
等文件里,`shared/src/prompt_registry.ts` 列了每一份在哪、共用了哪些片段。**直接改常量,
部署即生效**——控制面派发时把正文随任务下发,可读性报告也由控制面用代码基线生成。
版本历史就是 git,回滚就是 revert。没有库版本、激活指针或提案审批(2026-10-12 拆掉,
原因见 `control-server/src/agent_prompt_db.ts` 头注释)。
- 唯一的例外是**产品定制 prompt**:管理页「产品与分支」里每个产品 × 端一段文字,存在 `settings` 表,
派单时由控制面拼到 Bug / Feature 评估与执行 prompt 的末尾(`control-server/src/product_profiles.ts::withProductPrompt`)。
它只该放产品事实(被测 App、包名、构建命令、账号),没有 git 历史;阶段措辞仍然改代码常量。见 `docs/product-profiles.md`。
- `agent_prompts` 表只存 RSI 自动实验回路的候选,只在实验机上复跑,碰不到生产;
报告实验室里的版本只是草稿。实验验证有效的改法,也是改进代码常量才上线。
- 质量指标、失败模式、工具缺口的定义与真值来源见 `docs/rsi.md`;
新加指标时记住那条底线:**真值只认执行结果(真机核实的条件 / 工单终态),
不认另一个模型的意见。**
## 五种任务类型不要混
`tasks`(bugfix) / `features` / `security` / `prototypes` / `verifications`(验证) 是五套并行的表 + 路由 + runner,字段和状态机相似但**不通用**:
- 报告文件名不同:`FixReport.md` / `ImplReport.md` / `SecurityReport.md` / `ProtoReport.md` / 验证按格式是 `evidence/Case-Run-Report.md`(用例验证)或 `evidence/UI-Audit-Report.md`(UI 走查)(HTTP 路径上 bug 和 feature 都叫 `fix-report`,只有 satellite 落盘时才分叉;prototype 走 `/report` + `/script`,验证走 `/report` + `/audit-report`)。
- 终态语义不同:bug 有 `UNREPRODUCIBLE`,feature 没有(feature 只有 `IMPLEMENTED` / `IMPLEMENTATION_FAILED`);prototype 没有 eval 阶段、没有分支 / MR,终态是 `promoted`(晋升成一个普通 Feature);验证同样没有 eval / 分支 / MR,终态是 `accepted`(哨兵 `VERIFY_DONE` / `VERIFY_FAILED`)。
- prototype 和验证是**不改代码仓**的两条线:prototype 用 Frida 热改造设备上已装的基线 App,交付截图 + 脚本 + 接手包(`docs/prototype.md`);验证按建单时定下的用例(或走查规约)真机采证据,交付证据 + 结构化报告(`docs/verify.md`)。两者在 `claimAnyFixForNode` 里**插队**(prototype 先、验证次之,都先于其它三张表),因为不需要构建的活不该排在两小时构建后面。唯一的例外是验证里的「改动验证」:它要检出提交人的提交并编译,仍然插队,因为提交人正等着结果接着改。
- kind 字符串:验证在 WorkItem / 流转账本 / 证据镜像 / 看板里叫 `verify`,在按表名区分的地方(`readable_report_runs.target_type`、`ReadableCallback.kind`)叫 `verification`。
改动其中一类时,先确认另外几类是否需要同步——很多字段是多份平行定义,不是共享的。
### 验证曾经是 feature 的一个变体,已拆出
验证最早是 `features.deliverable = 'report'` 的 feature,共用表、id、状态机和执行模板。结果服务端的创建 / 完成数、周报、KB 效果全把走查算成 Feature,执行 prompt 是 Feature 模板加一段「前面的规矩不适用」。2026-09 拆成独立的 `verifications` 表(迁移 `drizzle/0036`,旧列由 `0037` 在上线后删除)。**别再往 feature 上加「只有某一类 feature 才用」的开关**——出现第二种交付物时,先考虑是不是又一条 track。
验证有四种报告格式,规约里的 `format` 决定:**用例验证**(`case-run`,基础格式、默认)拿建单时从 Bits 测试计划拉下的用例逐条执行,每个检查点一个结论,附截图和按检查点打点的录像;**UI 走查**(`ui-audit`,定制格式)按页面 × 语言采截图、逐页记问题;**CI 包覆盖率验证**(`ci-coverage`,实验、仅管理员从 bug / feature 抽屉一键建)由卫星先装上 MR 流水线的插桩包、按 R8 mapping 用 Frida 记改动方法的执行,再让 agent 按来源单验证过的路径重走,报告把录像、点击、改动代码按时间轴对齐。**改动验证**(`change-run`,只能从命令行 `streamline verify` 建;2026-10-26 起暂停新建,见 `docs/verify.md`)由节点先检出提交人已推送的提交,agent 编译装包后按提交人用 coding agent 写的用例执行,报告是用例验证的骨架加「被测提交」和「建议」。四者的执行模板(`verify.case.*` / `verify.run.*` / `verify.cicov.*` / `verify.change.*`)、报告契约、面板视图各是一套;后两种的设计与边界见 `docs/verify.md`。老卫星会把不认识的格式当 UI 走查跑:新加格式时,卫星认领要声明它(`verifyFormats`),控制面只派给声明了的卫星。
验证的可读性报告不是模型写的:用例验证走 `shared/src/case_run_report.ts`——解析 `Case-Run-Report.md`,按文件名把截图 / 录像对到检查点上,从 `manifest.jsonl` 里截图的拍摄时刻算录像打点,逐条结论不调模型——唯一例外是报告顶上的「结论卡」(`shared/src/case_run_verdict.ts`),生成时由模型读报告原文写,检查点号 / 截图只能引这单真有的、状态以逐条结论为准,历史单 regen 也会补上;UI 走查走 `shared/src/audit_report.ts`——解析 `UI-Audit-Report.md`,再用截图旁边那份同一时刻的 `catuse ui` 结构树把问题标到截图上,模型只被问「这条问题指的是哪个控件」,且只能从封闭候选里选 `@序号`,编不出坐标。prompt 里的报告骨架和解析器是同一份契约的两端,改一边必须改另一边。
读 Bits 测试计划用的是**建单人自己**的授权:控制面只认 SSO 邮箱,在本机跑 bytedcli(按人一个 profile),没授权时表单直接给设备码授权链接;读到的用例随规约(`verify_spec` 字符串)落库、认领时下发,卫星不碰 Bits。设计、边界与待办见 `docs/verify.md`。