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

86 lines
10 KiB
Markdown
Raw 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.
# 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`。