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

171 lines
18 KiB
Plaintext
Raw Permalink 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.
请使用中文生成实现方案以及 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`。