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
+171
View File
@@ -0,0 +1,171 @@
请使用中文生成实现方案以及 REASON 行的内容(含每个 NEEDS_INPUT 哨兵里的说明)。章节标题与固定小标签逐字沿用模板给出的中文写法,**不要加 `// English` 副标题**;代码标识符、文件路径、AB Key、日志与 UI 原文按原样引用,不要翻译。
You are evaluating a feature request and, if it is actionable, drafting an implementation spec that a downstream coding agent will follow. You may research the repository under your cwd to ground every claim in real code.
Feature request:
- Title: 消息盒子支持置顶
- Platform: android
Description (OriginalIntro):
希望能把会话置顶
Reporter remark / supplemental info:
补充:只在国内版生效
STEP 1 — Decide actionability. Check all three:
A) Is the user value / target scenario specific enough to design against (no vague "improve X" with no anchor)?
B) Is the change surface clear — at least which page / module / API the work touches, after a quick repo scan?
C) Are the acceptance signals distinguishable (a future reviewer could say "yes that's done" or "no")?
STEP 2 — Output. Use EXACTLY this format, no preamble, no trailing prose:
ASSESSMENT: <READY | NEEDS_INFO>
REASON: <one-sentence rationale; if NEEDS_INFO, name the specific gap the reporter should fill>
If and only if ASSESSMENT is READY, emit the implementation spec between the markers below, following every rule.
<PLAN>
**铁律(贯穿全文,违反即视为不合格)**:Feature 实现方案的任意部分都必须基于真实客观事实、知识库、以及对仓库代码的调研。**严禁在未经验证的情况下编造接口/调用关系/产品意图/约束条件**。任何你无法从需求描述或代码调研中确定的内容,**不要猜**,改为在该位置原样写一行哨兵:
`<<<<<<< NEEDS_INPUT: <一句话说明缺什么、需要用户补充什么> >>>>>>>`
哨兵会被工具识别为"待人工补充",入队前会拦截提示。能确定的照常写,不要滥用哨兵。
**给哨兵配候选(可选,默认不配)**:如果你在起草过程中**已经读到**了这一处的可能取值——工单里写着的机型/账号、你翻代码时看到的枚举或默认值、知识库里的历史条件——就在哨兵的提示后面接着写候选,最多 3 个,**全部写在同一个哨兵里、同一行上**:
`<<<<<<< NEEDS_INPUT: <一句话提示> @OPTION <20 字以内的短标签> | <出处:工单原话 / 代码符号与文件 / 知识库条目> | <被选中后用来替换整个哨兵的成品文本> @OPTION <标签> | <出处> | <成品文本> >>>>>>>`
**整个哨兵必须是一行,绝对不要换行**——行首的 `>>>>>>>` 会被 markdown 当成引用块吃掉,那个哨兵就废了。
纪律:
- **没有出处就不要写候选。** 大多数哨兵都写不出候选,那是正常且正确的——哨兵的意思本来就是"这件事我定不了"。靠常识推测出来的候选看起来很像对的,会诱使人直接点下去,比不给候选坏得多。
- **不要为了凑候选再去翻一遍仓库。** 候选是你已有调研的副产品,不是新一轮调研;顺手写不出来就不写。
- 第三段会**原样替换整个哨兵**,所以它必须是替换后能直接读通的成品句子:不要带括号说明,不要再出现"待确认/待补充",也不要把 `@OPTION` 或哨兵标记本身写进去。
- 候选之间要互斥,不要把同一个答案换种说法凑数。成品文本里不要再出现 `@OPTION`。
**特例——门控 AB Key**。哨兵问的是"这个能力受哪个 AB 实验 / feature flag / 实验位控制"时,按这个顺序:
1. **先找既有的**:工单原话、你在仓库里读到的实验位、知识库里的历史条件。找到就**逐字引用**(连命名空间/前缀一起),给成候选,出处写清是从哪读到的。**绝不改名、绝不另起 key。**
2. **跨端对齐的需求尤其不许自创**:源端已有的 Key 与 Enum 档位必须逐字沿用,否则同一份实验配置没法同时开启两端 —— 这种情况下找不到就老实留空候选,让人工补。
3. **只有确认这是一个全新门控、没有任何既有实验位可复用时**,才可以给一个"本地新建"的候选:Key 按语义用下划线连接命名(形如 `studio_effects_panel_discover`),同时给出配套的 AB Class / 常量名(与 Key 同义的驼峰写法,参照仓库里相邻实验位的既有命名习惯)。出处里必须**如实写明"本地新建(未找到可复用的既有实验位)"**,不要伪装成查到的 —— 人工要一眼看出这是你新起的名字,而不是既有事实。
**输出纪律**:最终结果里**只允许出现两类内容**——(a) 你确定的真实内容,(b) NEEDS_INPUT 哨兵(可带候选行)。**严禁把本模板里的说明文字、括号提示、示例占位、省略号、"(根据……补充)" 之类的脚手架原样抄进结果**;**也不要新增模板未列出的条目、字段或章节**(不要自创 hint、result、备注 等行)。每个章节只保留模板规定的条目,填上真实内容或哨兵。
按下面的结构与每节的约束产出(**章节标题与固定小标签逐字沿用下面的写法,不要翻译、不要加副标题**,顺序也不要变;括号里的指引只是写作要求,不要抄进结果):
## 目标
- 一句话描述这个 Feature 要达成的产品/用户价值。
- 触发场景:用户在哪个入口/场景会用到这个能力。无法确定用哨兵。
## 范围与约束
- 包含范围:本次要做哪些子项(简短列表,不超过 5 条)。
- 不包含范围:与本次需求"相邻但不做"的事项,避免范围蔓延;无可裁剪也写一句"无"。
- 硬性约束:平台 / 版本 / 接口 / 数据格式 / 性能 / 兼容性等显式要求。**调研仓库后**写实,不确定的用哨兵。
## 实现方案
(**基于代码调研**给出可执行的实现路径;一般 3~7 步。**不要写得过于细节**——尚未真机运行,过细的猜测往往是错的,留出执行期的变通空间。无法确定的关键改动用哨兵。**实现应接入真实数据/真实调用链,而非硬编码假值、mock UI、stub 空实现或只在 demo 路径生效**;若某处确实只能先占位,在该步注明"临时占位,正确做法待定"。)
1. ...
2. ...
涉及的关键文件 / 模块(基于 cwd 下的代码调研列出真实路径,不要编):
- ...
## 服务端范围
(**判定规则,不要跳过也不要过度声明**:只有当这个需求**必须改服务端代码**才声明 PSM。仅仅"要调服务端接口""数据由服务端下发"**不算** —— 客户端消费服务端已有能力是常态。典型需要声明的情况:要新增/修改下发字段、要改接口行为、要新增服务端分群或配置逻辑。判断不了就用哨兵,让人在确认时决定。)
- 涉及 PSM: 形如 `tiktok.xxx.yyy`,多个用顿号分隔;**确认不需要服务端改动就写"无"**。
- 服务端改动: 服务端要做什么(改哪个接口/字段/逻辑)。上一行为"无"时本行写"无"。
- 服务端验证方式: 怎么证明服务端改对了(打哪个接口、看什么字段/日志)。上一行为"无"时本行写"无"。
(**PSM 怎么查**:上一行写"无"时整段跳过。判定需要服务端改动、却答不出 PSM 时**不要猜**,按下面做:
1. 从需求里提炼**业务域词**(如 Comment / Privacy / Profile / Story),跑 `serverline discover --domain <业务域词>`。它不需要 URL,输出里 `clientFacing` 为真的就是端上接口(http + IDL),其余是客户端调不到的内部服务。
2. 手边正好有客户端代码里的接口 URL **字面量**时,再补一次 `serverline discover --path <该路径> --product tiktok` 交叉验证 —— 它命中率低(实测 4%),但命中时是 AGW 与 IDL 两路独立印证,置信最高。
3. **最多试两三个业务域词就停。**这个动作的期望收益结构上就低(--domain 实测 75%、--path 4%),继续加码只会吃掉本该用于代码调研的预算。verdict 为 `not-found`、或这台机器上**没有 serverline**、或命令报错,都直接进第 4 步 —— 那不是故障,也不要因为缺工具就把任务判成阻塞或凭印象编一个 PSM。`ambiguous` 同理:它的语义就是「没定论」,不要从候选里自行挑一个。
4. **产出写成带候选的哨兵,而不是直接填一个 PSM。**除非某个候选被 `--path` 交叉印证过,否则一律保留哨兵并把候选挂上去,让人在确认闸上一键选定:
`<<<<<<< NEEDS_INPUT: 需要确认承载该能力的 PSM @OPTION tiktok.xxx.api | discover --domain "Xxx" 端上接口候选,服务树 |TikTok|…| | 涉及 PSM: \`tiktok.xxx.api\` @OPTION … >>>>>>>`
**为什么不允许直接填**:这两条通道失败时给的不是空集,是**看起来完全合理的错答案** —— 实测 Post 查出 `tiktok.post.api`(真值 `tiktok.video.post_api`)、Like 查出 `tiktok.like.api`(真值 `tiktok.basic.api`),两个错答案都真实存在、都是端上接口、名字都比真值更像。而 PSM 一旦定下,后面 checkout / 泳道 / MR 全照着它走,错一个字改动就落到毫不相干的服务上。查不到、或候选都不像,就只留哨兵不挂候选 —— 那也是完全正常的结果。)
## 验证环境
(这节写的是**验收时怎么把这个能力真的跑出来**,不是实现细节。四行都要在,不要整节省略。
**逐行按下面的判定来写,每行只问一个问题**:只给执行 Agent「本方案 + 代码仓 + 一台在线设备 + 一个普通已登录测试账号 + 标准构建」,它能不能走到该能力生效的场景并完成验收?
- **能** → 写出这个结论("任意已登录测试账号即可" / "无特殊要求" / "标准构建"),**不要打哨兵**——写明"不需要"本身就是有用信息;
- **不能,但代码调研查得出来**(入口路径、开关 Key 与默认取值、接入点)→ **去查,查到写实**;查不到才退回哨兵;
- **不能,且只有提需求的人知道**(白名单 / 内部账号 / 指定地区或身份 / 需要预置的历史数据 / 实验 Key / 指定机型)→ 打哨兵。
哨兵会拦住入队,**只给"缺了就真的验不了"的项打**;为求稳妥每行都打哨兵 = 把评估的活推回给人,同样视为不合格。)
- 账号/权限: 验收需要的账号、权限、地区、身份。**尤其别漏"需要预置数据"**这一类(如需本人已有一条 Story / 已有订单 / 有粉丝),它最容易漏,而且一漏就直接卡死验收。
- 入口路径: 从 App 首页走到该能力生效场景的操作路径(Tab → 入口 → 页面)。**先做代码调研再写**;若入口正是本次新建的,写清它挂在哪个已有页面下、那个页面怎么进。
- 实验/开关: 验收是否必须开启某个 AB / feature flag / mock,给出 Key 与需要的取值;本次不加门控或默认全量就写明。
- 构建/设备: 特殊构建命令、包类型、必须真机 / 模拟器 / 特定机型 / 多台设备等;无特殊要求就写"标准构建 + 任意在线设备"。
## 验收标准
(下游实现 Agent 会逐条自验、复核者也会逐条核对,所以每条都要**可验证、可区分"真做到 / 没做到"**,并覆盖以下四类角度——不要只写"UI 看起来对了"。以"当…时,应…"结构撰写;每类 1~2 条,总共不超过 8 条,无法确定的取值用哨兵。)
1. 功能达成(正向):目标能力在主路径上真的可用/可见/走通,产出「目标」里承诺的用户价值。
2. 机制级(真实接入):关键行为背后接的是真实数据 / 真实调用 / 真实状态,而非硬编码、写死假数据、mock、stub 或只在 demo 生效的假实现。把"如何证明是真实接入"写成可观测命题(判定点 + 可观测量 + 期望取值)。
3. 对抗性 / 边界:在最容易暴露"假实现 / 浅实现"的条件下仍成立 —— 优先冷启动、空数据 / 无网 / 异常输入、与默认值不同的输入。只保留最关键的几条,不要堆边界。
4. 无回归:相邻入口 / 复用同一组件或接口的既有功能不被破坏(基于代码调研点名受影响面;无法确定用哨兵)。
## 风险点
(**必须基于真实事实 / 代码调研**,无法确定的用哨兵;严禁泛泛而谈或编造。)
- ...
</PLAN>
**输出边界**:把填好的实现方案放在 <PLAN> 与 </PLAN> 之间;</PLAN> 之后**禁止**再输出任何文字——不要写 "=== END ===" 等结束标记,也不要写"已逐条落实…/变更小结/确认语句/说明"。
## 设备驱动 / 抓包 / 环境切换(Android)—— 探测工具之前先读这一节
**先看清这台机器上有什么。** 不要从 `command -v` 的空结果推断"环境坏了",更不要满盘 `find /`:
- **有**:`adb`、`frida`、`jadx`、`scrcpy`、`node`、`python3`、`brew`(都在 `/opt/homebrew/bin`)。设备通过 USB 直连、**已 root**。
- **没有**:`bytedcli` / `bits` / `mitmproxy` / `whistle`。工单里若写着用它们,那是提单人按自己机器写的,**不要照抄,也不要为此把任务判成 BLOCKED**。
- `sudo` 需要密码,非交互下用不了;但 `/opt/homebrew` 属于当前用户,`brew install` 和 `npm i -g` **不需要 sudo**。
- **绝对不要执行 `find /`、`grep -r /` 这类全盘扫描。** Bash 工具 120s 超时会把命令挪到后台,而后台任务会吊住整个 agent 进程不退出,已经因此把一次做完的评估拖成"超时终止"。要找东西就到明确的目录下找。
**`rax`(rax-cli)是这台机器上的主力工具**,`command -v rax` 没有就装,一条命令、无需 sudo:
```bash
npm install -g @tiktok-fe/rax-cli@latest --registry=https://bnpm.byted.org --loglevel=error
rax daemon start && rax device list # 看到 [D1] … USB: YES 就能用
```
**`rax ttmock` 子命令走的是 adb,不需要 `RAX: YES`。** 设备列表里 `RAX: NO`(App 内 RaxDebugger 开关没开)时,
下面这些照样生效 —— 只有 `rax network capture` 那条通道才要求 RAX 已连接:
```bash
rax ttmock boe --ppe --ppe_lane <lane> --restart # 指向 PPE 泳道
rax ttmock capture --restart # castore=false,关包加密
rax ttmock proxy <host>:<port> --restart # TTNet 代理指向本机 mitmproxy
rax ttmock header 'k=v' --restart # 注入请求头
rax ttmock get # 读端上当前 ttmock.json
```
- **配置类**(boe / capture / proxy / region / ab / sp / keva …)写端上 `/data/local/tmp/ttmock.json`,**冷启动才加载,必须带 `--restart`**;不带就是写了文件、行为没变。**广播类**(login / logout / feed)要求 App 正在前台。
- 不用 rax 就自己拼 `ttmock.json` 后 `adb push /data/local/tmp/ttmock.json` 再冷启动。指向 PPE 的三个字段缺一不可,**`enable` 不为 true 时 `enablePPE` 完全不生效**:
```json
{"boe": {"enable": true, "enablePPE": true, "ppeLane": "<lane>"}}
```
**抓包按这个顺序试,并把每一档的真实报错记进报告:**
1. `rax network capture network` + `rax network search --url_pattern <path> --fields response_body` —— 最省事,但要求 App 高级 Debug 面板(长按 Inbox Tab)里 **RaxDebugger Enable** 已开,卸载重装要重开。
2. **mitmproxy**:`brew install mitmproxy` 起在本机,再 `rax ttmock capture --restart` + `rax ttmock proxy <本机局域网IP>:8080 --restart`。`castore` 是 TTNet 的包加密开关,**不关就只能抓到密文**。设备已 root,证书可以装进系统信任区。
3. **frida**(已装):hook 解析入口打印原始入参。当你要看的是**客户端尚未定义的新字段**时这是唯一可靠的一档 —— 见下条。
**判据只认原始 JSON。** 服务端新下发的字段,只要客户端的数据类里没有对应 `@SerializedName`,Gson 解析时会**直接丢弃**;所以"App 里没看到变化""客户端对象里取不到"**都不能作为 FAIL 的依据**。要么抓到网络层原文,要么 hook 到反序列化之前的 `JsonObject`。同理,"接口返回 200"不是判据,字段在不在、值对不对才是。
**下这个结论之前的硬性前提:** 要在报告里写「无法抓包」/「无法切泳道」/「验证环境阻塞」,
你必须已经把上面三档抓包路径**逐档试过**,并在「验证局限」里逐档写清:装了什么、跑的哪条命令、
报错原文是什么。用一句"节点上没有抓包工具"就收尾,等于把一次可完成的验证记成基础设施故障。
## 取证声明 —— 采集前要写清楚的四件事(会被记录,且会覆盖下文「能录必录」)
1. **画面本来就不该动的场景,start 时带 `--static-scene "<为什么静止>"`。** 长按态、静态弹窗、
低帧率录制都属于这类。带了之后「画面没刷新 / 帧率过低 / 疑似冻结」会从 fail 降级成告警,
不再吃掉你仅有的一次重录名额;不带就会被判 fail,而那多半是误判。理由会原样写进 manifest
和报告供人复核,**所以写真实理由,不要拿它当消掉红字的开关**。
2. **前后对比的两张/两段,各自带 `--scene "<语言/页面>"`**(如 `--scene "zh/个人页"`)。
两边场景标识不同、或画面尺寸不同,会被标 `scene-mismatch`:中文页对英文页、这条 Story
对那条 Story、这台机对那台机,都不叫前后对比,报告会把两件事讲成一件。
3. **重录时改 `--intent` / `--expect-moment` 会被记一条 `redeclare`,报告里必须说明为什么改。**
第一次声明写错了是可以改的;但**不要**把「必须录到的瞬间」改成一个更容易录到的瞬间,
再把它当成原来那件事已经证完了 —— 那是把「先声明后对照」变成「先录到再补声明」。
4. **性能 / 帧率 / 尺寸(≤4dp)/ 埋点 这几类缺陷不要求演示视频。** 视频拍不出"卡顿"、拍不出
8px 的位移、拍不出埋点参数,硬录出来的是一段自己也讲不清的画面。这几类改用**可量化对照**:
CPU% / Janky% / uiautomator bounds 数值 / 事件参数 dump,前后各一组数,写进报告。
录不了就 `skip --reason` 记一笔,不算缺证据 —— 下文「能录必录」对这四类不适用。
**命名决定它进不进报告:** `flow-*`(排查步骤)和 `probe-*`(探索录制)**都不是证据** ——
`probe-*` 根本不进报告,`flow-*` 只能作为过程记录出现在末尾,两者都不会被选成核心证据或
前后对比。真正要支撑结论的用 `demo/before/after/mech/edge`。