zhihu-reproduce

name	zhihu-reproduce
description	复刻或验证知乎的产品功能、交互、接口、字段、分页、创作流程和视觉行为，并落地到 Zhihu++。当需求包含“知乎有什么我全要”、官方行为对齐、API 字段/include 判断、Web 与 Android 差异、真实请求取证或协议稳定性时使用。

Zhihu Reproduce

证据门禁

扩展协议前先核对现有字段与调用链，不得从 UI 需求推导新的后端 action、seed 或数据库结构。要求线上写入时必须使用真实管理执行面并读回确认，否则明确报告阻塞。

唯一原则

按“产品事实 → 协议事实 → 项目事实 → 稳定成功 → 实现交付”的顺序推进。前一层没有证据，后一层禁止开始；不能用单次成功、测试夹具、字段名猜测或相似功能替代缺失证据。

开始任务时创建证据账本，使用 references/evidence-ledger.md 的模板。功能很多时先列完整能力图，再逐行关闭未知项；不要边看边写代码。

Gate 1：定义成功态、优先级与空间预算

先写用户可达的成功态，并按入口拆成功能行：

• 从哪里进入；看到什么；如何操作；成功后什么变化；返回后保留什么。
• 浏览、搜索、筛选、分页、关注/取消、分享、创作、草稿、发布、深链和其他页面引用分别列行。
• “全部功能”必须覆盖官方可见入口、空/错/登录态、反向操作和跨页面归属，不能只列 API 名称。
• 使用 references/evidence-ledger.md 的首屏预算表，先为每个元素标出信息/操作优先级、频率、同组关系和折叠后的空间占用，再谈尺寸。高频主操作不能比低频操作更小，本应同组的操作不能拆成额外整行挤占内容。
• 明确非目标和不可执行写操作。可逆关注可做往返验证；发布内容等真实写入没有授权就停在草稿或请求构造。

Gate 1 未通过条件：仍用“应该有”“大概类似”“顺便支持”描述行为，或无法说出用户如何触达成功。

Gate 2：选择证据密度最高的执行面

按以下优先级选主执行面，不按目标客户端机械选择：

1. 官方 Web 能完整操作：使用独立已登录 Edge/Chrome + JavaScript/CDP。它适合 DOM、批量交互、N+1 边界和网络捕获，是默认主执行面。
2. 已知接口契约：使用 zhurl 重放原始 JSON；Web 和 Android headers 分开验证。
3. 官方 Android：只补 Web 缺失的移动端专属入口、UI、灰度或协议。记录包名、版本、API、登录态和导航路径。
4. Zhihu++：只用于验证项目生产链路，不能反过来证明官方产品行为。

浏览器必须使用独立 profile。此 Mac 使用：

mkdir -p "/Users/zhaoliyan/.codex/edge-devtools-profile"
open -na "/Applications/Microsoft Edge.app" --args \
  --remote-debugging-port=9223 \
  --user-data-dir="/Users/zhaoliyan/.codex/edge-devtools-profile"

禁止使用没有 --user-data-dir 的远程调试命令。必须验证进程参数、/json/version 和 /json/list，并通过 /api/v4/me 确认登录态。不要抢占用户日常浏览器标签页。

Gate 3：关闭产品与协议矩阵

每项功能必须同时有以下证据，缺一项就保持 UNKNOWN：

1. 产品：真实可见文案、布局层级、操作前后状态、分页触发方式、失败与空状态。
2. 请求：最终 URL、host、method、query、headers/client 类型、body、状态码。
3. 响应：字段路径、类型、null/缺失/变体、分页 next、关系状态。
4. 边界：反向操作、N+1、重复操作、返回栈、首屏/分页/重试。
5. 归属：这是 Web 通用、Android 专属、账号/灰度专属，还是项目自有适配。

UI 复刻硬矩阵

按顺序执行，任何一步未知都不允许开始排版：

1. 语义层级：为信息和操作标 P0/P1/P2。频率只影响层级，不直接推出视觉大小；结合风险、可逆性和页面任务确定主操作。
2. 空间预算：记录首屏顺序、同组关系、宽度比例、行数、间距、折叠高度和首屏后还能看到什么。新增元素必须说明从哪里取得空间，不能无预算地增加整行。
3. 项目原语：先搜索语义相同的现有实现，复用完整交互契约，而非复制表面文案。折叠契约至少包含溢出判定、裁剪视口、渐变遮罩、控件 overlap、展开/收起动画与展开后的空间恢复；只用 maxLines 加独立按钮判定为未实现。
4. 状态矩阵：逐项检查加载、短内容、长内容折叠、展开、收起、失败、不可用和窄屏。按钮组必须在每个状态保持同一空间层级，不能因为一个按钮 loading 就换行或跳动。
5. 三方对照：把官方参考、项目既有同语义页面、当前提交真实 APK 截图并排核对。逐项填写位置、尺寸、间距、对齐、遮罩起止、overlap 和首屏信息密度；“功能能点”不能替代视觉通过。

UI Gate 未通过条件：没有首屏空间预算；高频/主操作被低频/次操作压过；同组操作不在同一行；项目已有同语义原语却只复刻表面；或没有真实 APK 截图证明空间关系。

创作功能硬矩阵

创作话题必须分别证明：

• 编辑器里如何输入、展示、删除和修改；是正文内联、独立选择器还是两者组合。
• 正文/结构化内容如何编码；payload 出现数组不能证明 UI 是 chips/picker。
• 草稿与发布最终请求分别携带什么。
• 数量边界必须实际操作到 N+1；未触发限制就不能写上限。

不得发布真实内容。需要验证发布 payload 时，优先捕获官方请求、保存草稿或在发送前中止。

分页硬矩阵

必须证明首屏 URL、触发方式、下一页最终 URL、去重、到底、失败重试和切 tab 竞态。项目连续列表默认复用触底分页；不能为了调试方便交付“加载更多”按钮。

字段硬矩阵

字段可用性按“列表原字段 → 当前 include → 候选 include → 流程已有详情 → 独立 fallback”验证。分别检查原始 JSON 和项目 decoder；某个数据源缺字段不能推出所有数据源都缺。

知乎入站响应的解码路径也是硬契约：先读取 JsonElement，再统一调用项目的 ZhihuJson.decodeJson()，由它把 snake_case 转成模型的 camelCase。入站模型禁止用 @SerialName("snake_case") 或手工改键，也禁止直接 response.body<ResponseModel>() 绕过统一转换；测试必须使用与生产相同的 ZhihuJson 路径。@SerialName 只允许用于已经取证的出站请求字段，或序列化框架所需的类型标识，不能混进入站字段模型。

全项目真实响应回归语料

用户要求优化“所有测试”或建立真实接口解析语料时，必须先从生产请求调用点生成完整接口族清单，不能因为当前正在修改某个模块就把范围收缩到该模块。项目实际使用的每个列表接口族至少采集 50 条真实数据，并记录请求模式、客户端/header、分页覆盖、字段变体和解码结果；单对象接口应覆盖不少于 50 个真实对象，不能把同一对象重复请求算成 50 条样本。

进入仓库的 fixture 必须逐条来自真实响应，只允许对用户身份字段做可审计的一致性脱敏，保持引用关系有效；正文 HTML、转义、null/缺失、嵌套结构、分页形态和造成过历史 bug 的异常字段必须原样保留。不得为了缩短 fixture、迎合模型或让测试通过而手写、补造或规范化响应。先从采集语料中识别历史 bug 样本、代表性类型和边界变体，再选最小覆盖集进入生产解码测试；完整原始语料保存在仓库外的私有证据目录，不能把账号凭据或未脱敏用户信息提交进仓库。

新增接口或修复既有接口解析 bug 时，真实响应回归测试是实现的一部分，不能只改模型或补手写 JSON。某接口族每再次发生一次解析 bug，该接口族下一轮的采样数量、数据源/header 组合、字段变体和边界样本要求都必须在上一轮标准上翻倍；这条升级只约束发生过 bug 的接口族，不能用大量同质样本冒充变体覆盖。

Gate 4：证明生产链路稳定

接口一次 200 只证明样本，不证明产品可用。新增 host/client 或认证路径必须用项目生产代码的最终请求验证：

• 同一首屏连续成功至少 5 次；高风险跨主机或曾出现偶发失败时至少 10 次。
• 至少完成 2 次真实分页过渡，并证明出现下一批独有内容。
• 主动制造一次可恢复失败，确认错误包含可诊断信息且重试能成功。
• 写操作做成功、读回、反向恢复；失败时 UI 状态和计数完整回滚。
• 记录成功率、状态码分布和最终 client/headers；不能只写“重试后好了”。

跨 www.zhihu.com 与 api.zhihu.com 时尤其检查 Android headers、UA、Cookie/Bearer 和签名环境。若官方移动接口依赖 Android 请求伪装，复用项目已有 Android client 能力，不让通用 Web fetch 碰运气。

Gate 4 未通过条件：真实设备出现高频失败、错误只显示 null/泛化文案、一次重试才成功，或生产请求与取证请求不一致。

Gate 5：最小实现与闭环

实现前写最小数据流和请求预算：每个新增状态、模型、请求、UI、测试必须对应 Gate 3 的一行证据。优先复用已有强类型模型、导航、分页和 client；不要新增薄 wrapper 或猜测性 fallback。

实现后依次验证：

1. 原始响应解码与请求捕获测试。
2. ViewModel 的加载、成功、空、失败、重试、切换和回滚。
3. 包含当前提交的 APK，在真实登录态走完整用户路径。
4. 相邻入口与归属：例如问题话题不能在回答页重复，折叠内容应一起折叠。
5. 连续稳定性矩阵重新执行，不复用实现前证据。
6. 真实截图、定向构建/测试、CI 终态、PR 文案与边界一致。

只有五个 Gate 全部通过才能说“完成”。CI pending、单次 AVD 成功、草稿 payload 单测通过或失败保护都不是完成。

纠错协议

用户或真实设备推翻结论时：

1. 立即把相关证据行标为 INVALID，停止基于它继续扩张。
2. 删除或回退未经证明的产品承诺，例如虚构上限、错误 UI 形态、显式分页按钮。
3. 从最早失效的 Gate 重新执行，不在旧实现上堆补丁。
4. 将根因提炼成对应 Gate 的硬门槛；不要继续追加散落“失败经验”。
5. 修复、稳定性重放、提交、截图和 CI 收尾连续完成。

条件参考

• 只有任务涉及 segment_infos 正文划线时，读取 references/segment_infos.md。
• 其他历史案例不能替代当前任务的证据账本。