# Prototype(原型需求)—— 第四种任务类型
> 目标:纯 UI / 交互类需求,从「提交」到「看到效果截图」压到几十分钟以内,
> 绕开 2 小时以上的编译 + 云端回拉;用户多轮加意见到满意后,再把
> 「UI 产物 + Frida 脚本 + 源码定位」作为 Context 交给现有 Feature 链路做原生实现。
## 一句话流程
```
提交原型需求 ──▶ awaiting_prototype ──▶ prototyping ──▶ prototype_ready ──▶ (加意见) ──▶ awaiting_prototype …
│
└──▶ 「转正式实现」 ──▶ promoted + 新建一个普通 Feature(附接手包)
```
- **不评估、不确认**:没有 eval 阶段,创建即入队。原型本身就是"评估"——效果对不对,人看截图说了算。
- **不编译、不装包**:卫星直接拿设备上**已经装着的基线 App**(Android:设备里的 TikTok-M;iOS:`~/iosapp/TikTokM.app` 的 macCatalyst 进程),用 Frida 脚本做运行时热改造。
- **不改代码仓**:代码仓只允许只读查询(`git grep` / `git show origin/:`),用来把 hook 点映射回源码符号。没有分支、没有 MR。
- **原生实现不另起炉灶**:「转正式实现」= 用 `createFeature()` 建一个普通 Feature,`remark` 里塞接手包;后续 eval → 人工确认 → 实现 → MR 全走既有链路。原型行上记 `promotedFeatureId`,Feature 描述里注明来源。
## 为什么「UI 产物 + Frida 脚本」是有意义的 Context
调研结论(2026-09-09,见飞书《TikTok 私信单条消息自由编辑|Frida 原型与 iOS 源码接手包》):
1. **Frida hook 点天然就是源码符号。** iOS 的 `-[AWEIMUserMessageCellView layoutSubviews]`、Android 的 `com.ss.android.ugc.aweme.xxx.Foo.bar` 直接能 `git grep` 到文件;仓库里 `shared/src/method_coverage.ts` 已经在做同一件事的反方向(diff → Frida selector)。那份文档 10 个 hook 点映射到了 14 个源码文件 + 行号,是接手包的骨架。
2. **脚本本身是"运行时 diff"。** 它记录了:在哪个类的哪个时机、改了什么状态、参数是多少(尺寸/颜色/阈值集中在 `CONFIG`)。这比一段自然语言需求精确得多,且已被真机验证过。
3. **截图是验收基线。** 原生实现的验收标准从"实现方案里推断的"变成"和原型截图逐项对齐",评估器少猜很多。
4. **但脚本不是实现方案。** Frida 直接改 view、绕过 ViewModel / 组件系统、用全局单例存状态——这些原生实现都不能照搬。所以接手包强制带一节「原型不可照搬之处」,Feature 的 remark 里也明写"脚本用于定位触点和行为契约,不是移植对象"。
## 状态机(`shared/src/types.ts::PrototypeStatus`)
| 状态 | 含义 | 出边 |
|---|---|---|
| `awaiting_prototype` | 排队等卫星(创建即此态) | 卫星 claim → `prototyping` |
| `prototyping` | 卫星上 Agent 在跑 | `STATUS: PROTOTYPE_READY` → `prototype_ready`;否则 → `prototype_failed`;基础设施/鉴权错误 → 回 `awaiting_prototype`;用户 abort → `prototype_failed`(failureReason=用户中止) |
| `prototype_ready` | 有截图 + 脚本 + 报告,等人看 | 加意见(`/feedback`)→ `awaiting_prototype`(同工作区、同脚本继续迭代,`attempts+1`,`reviewHistory` 追加 human 注记);「转正式实现」→ `promoted`;归档 → `archived` |
| `prototype_failed` | Agent 做不出来 / 中止 | 重开 → `awaiting_prototype` |
| `promoted` | 已建出 Feature(终态) | — |
| `archived` | 搁置(终态,统计记失败) | 重开 → `prototype_ready` |
| `cancelled` | 用户取消 | — |
## 数据
- 表 `prototypes`(`drizzle/0026_prototypes.sql`),与 features 结构平行但**不共用**:没有 branch/MR/plan/regen/readable 列;多了 `baseline`(JSON:包名/bundle、版本、build、探测时间)、`script`(最新 `hooks/prototype.js` 全文)、`report_markdown`(最新 `ProtoReport.md` 全文)、`promoted_feature_id`。
- 表 `prototype_rounds`(prototype_id, round, script, markdown, created_at):每轮归档,晋升时能回看演进。
- 脚本与报告在卫星每轮结束时随 `/api/internal/prototypes/:id/update` 的 patch 上送,控制面落库并归档到 rounds。文件本体仍在卫星 `~/taskLog/prototype-/`。
## 卫星(`satellite/src/prototype_runner.ts`)
- 工作区:`~/taskLog/prototype-/{OriginalIntro.md, hooks/prototype.js, ProtoReport.md, evidence/, logs/}`。
- 跑之前**机械探测基线**:Android `adb shell dumpsys package ` 取 versionName/versionCode;iOS 读 `~/iosapp/TikTokM.app/Contents/Info.plist`(macCatalyst 布局)或 `Info.plist` 的 `CFBundleShortVersionString/CFBundleVersion`。探测结果写进 prompt 的「基线 App」块和行的 `baseline` 字段。探测失败不阻塞,写 `note`。
- Prompt:`shared/src/prototype_prompt.ts` 的 `DEFAULT_PROTOTYPE_RUN_FIRST_TEMPLATE` / `SECOND`(阶段 key `prototype.run.first` / `prototype.run.second`,控制面派发时随任务下发代码里的正文,与其他 track 一致)。
- 与 fix 循环同一个 claim 通道(同一台设备不能同时被两个 Agent 驱动),但控制面 `claimAnyFixForNode` **先看 prototypes 再看其它三张表**:原型几分钟就完,插队的代价远小于让它排在 2 小时构建后面。要彻底不排队,用 `clusters` 标签给原型单独划节点。
- 不需要代码 checkout 锁(不 checkout);不跑 tracking / method-coverage 扫描;不做 KB / TTKB / conditions;不生成可读性报告(面板直接渲染 `ProtoReport.md`,与 security 一样)。
- 结束时杀掉本工作区拉起的 frida 进程(App 回到基线,是预期行为)。
## 控制面
- `/api/prototypes`:list / get / create / feedback / promote / archive / reopen / abort / pin / unpin / delete / watchers / description / report / script / rounds / rounds/:round / log-file / logs / evidence* / handover。
- `/api/internal/prototypes/:id/{update,notify}` + `attachment/:uuid`。
- 通知卡:`dispatched` / `prototype_ready` / `prototype_failed` / `promoted`,深链 `?prototype_id=`。
- 接手包 `control-server/src/prototype_promote.ts::buildPrototypeBrief()`:原始需求 + 反馈脉络 + 最终 ProtoReport 全文 + 脚本全文(fenced js)+ 截图 URL 列表 + 「如何使用这份材料」规则。
## 前端
- kind `prototype`,路由 `/prototype?id=`,legacy `?prototype_id=`。
- 卡片 chip「原型」;抽屉:ProtoReport 渲染、脚本查看/复制、证据、「添加修改意见」、「转正式实现」(成功后显示到 Feature 的跳转)。
- 分桶:`awaiting_prototype→queued`、`prototyping→running`、`prototype_ready→review`、`prototype_failed/cancelled→failed`、`promoted→merged`、`archived→archived`。
## 明确不做(v1)
- Asking(与 Agent 聊)、可读性报告、跨端移植、Meego 写回、TTKB、KB 回灌。
- 让原型脚本"常驻"设备:Frida 退出即恢复,多任务共用设备只能这样。
## 生产前提
- Android 节点:`frida` 16.7.19 + 设备上 root 的 `frida-server`(fei-android-01 已验证)。
- **iOS 节点:frida attach 必须以 root 跑。** 实测(2026-09-10, fei-ios-01 / temp-ios-01):
普通用户 `frida -p ` 必定 `Failed to attach: timeout was reached`,同一条加 `sudo` 秒回。
与 `DevToolsSecurity` 无关——两台都已 `-enable`、用户也在 `_developer` 组,普通用户照样不行。
根因是被测 App 是 adhoc 签名、**没有 `get-task-allow`**,非 root 拿不到 task port。
所以节点需要一条 NOPASSWD sudoers 规则(见下),否则无人值守的任务用不了 frida:
```
# /etc/sudoers.d/streamline-frida (chmod 440)
<节点用户> ALL=(root) NOPASSWD: /opt/homebrew/bin/frida, /Users/<用户>/Library/Python/3.9/bin/frida
```
frida 在 iOS 节点装在 pip 目录(`~/Library/Python/3.9/bin`),不在 homebrew——两处都写进规则。
`frida-ps`(只枚举进程)不需要 root。
备选通道 **不可用**:macCatalyst(platform 6)走 iOS 式 AMFI,`DYLD_*` 会被剥离,frida-gadget 注入静默失效。