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

10 KiB
Raw Permalink Blame History

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。