总览

# 总览

一、跨源综述（Synthesis · 27）

综合 ≥2 个不同来源才成立、可脱离项目带走的判断。

• 先定位归属层再动手 — 症状看起来在哪一层 ≠ 问题在哪一层；先用最便宜的观测划边界
• 分层要落到运行时才有效 — 分对层只完成一半；契约/适配器没人读，约束就等于不存在
• 判据要用真值而非代理 — 判断用的那个量不是你要问的东西；代理量只在边界处分叉，且静默
• 判断现状要看真正在跑的那一份 — 你查的（文件/状态页/接口返回）不是实际在跑的那一份；观测点要落在执行路径末端
• 口径先于数值 — 数字不可信几乎总是归属问题：先问分子是谁、分母是谁、时间窗是什么
• 可复用物与不可复用物分开 — 按「寿命」分层：会过期的和不会过期的不能放同一层
• 同一状态的多个副本必然漂移 — 「它对应的是哪一条标识？」「我手上这份是同一条吗？」「这中间有没有人又写过？」
• 契约只承载结构，个性留给扩展层 — 共享层只描述「有哪些位置/步骤」，视觉、格式、业务规则一律外推
• 存量不会自动跟上新逻辑 — 改对代码 ≠ 修好现状；存量数据、旧路径、未同步的层要单独带过来
• 活的能力取决于增量机制而不是生成质量 — 派生知识（wiki/索引/摘要/洞察）能不能「活」，取决于触发、存量回填、失效作废这三件事，不取决于第一次生成得多好
• 定义要由使用者确认 — 分类法/术语/协议由单方给出必然错位；定义权要显式交给使用者并确认一次
• 对照才产生信息 — 单点不产生信息，先造一个 A/B；「说不清」多半是缺参照系
• 按实际规模选型而不是按方案先进性 — 判据是这一侧的真实规模与边界，不是方案的成熟度；「规模小上重型」与「深处还手搓」是同一个错
• 收尾要落到确定状态 — 终态必须三选一：成功 / 失败 / 已接管；「等人确认」「idle」都不算结束，任务会安静悬挂
• 更新时序要由本地最新状态决定 — 「谁最新」要靠显式版本记录，不能靠「谁最后返回」
• 本地能跑不等于环境里能跑 — 「环境侧少了哪个默认？」「两侧的 provider 路径是同一段代码吗？」「两侧共享了哪些可变状态？」
• 权威终态到达后迟到的写不能覆盖它 — 「权威事件是哪一个？」「结算点在哪一行？」「终态之后的错误怎么处理？」
• 检索是一条分层链 — 检索是供给/召回/融合/迭代四层链，用单点替代整条链必然静默失效
• 用户价值要在循环内被验证 — 「用户在这一轮能看到什么？」「这一轮的验收标准是什么？」「剩下的部分下一轮怎么接？」
• 真源要按维度显式指定 — 「谁新/谁全/谁像」都不是判据；先按维度把真源写死，再谈同步
• 职责要先分家再谈实现 — 两件不同的东西被当成一个，是因为职责边界没显式分开；先分家再谈同步/缓存/编排
• 能力被环境差异静默改变 — 「真正执行的是哪一个实体？」「参数是在哪一层被消费的？」「响应里能证明它吗？」
• 能力要靠消费方认账 — 提供方就绪 ≠ 可用；每一项能力都要问「对面谁在认账」
• 差异要用使用模式说而不是功能清单 — 功能清单是共有项，天然抹掉差异；差异只在「使用模式」与「去掉它损失什么」两个维度上出现
• 快照只在建立那一刻成立 — 把「会变的输入」与「建立时机」耦合，就得到一个只在建立那一刻成立的状态；跨过边界后静默失效

二、主题聚合（Topics · 20）

标题即主题，页内是该主题下的多条判断。

• AI产品经理的能力三轴 — 产品思考 / agent 理解边界 / AI coding 能力三条并列轴；项目不是叙事单位，能力轴才是
• UI原型保真 — 原型是唯一真源；逐片对照、共享 primitive、不用替代物、判断机制而非抄常量
• 个人知识产品的定位 — 不是更聪明的聊天框，是让知识停在可回看/可视化/可被 AI 洞察的空间；赛道选 learning 而非 coding buddy
• 产品页信息结构 — 每屏一个问题、同类能力用单选纵向 Tab、最精华部分不拆分、roadmap 要标「即将支持」
• 代码库知识工具的选型 — 给项目做「代码库知识」有三类工具，选型先看你要的是哪一种：会动的架构图（Archify）、人能读的 wiki 文档（DeepWiki-Open / OpenDeepWiki / KT Studio）
• 几何题3D化的题库定位 — 产品形态是「题库播放器」；模型与切法由题目决定，用户不选
• 后台任务队列选型 — 当前规模下「不要 Redis」：低频任务别上 BullMQ + 托管 Redis
• 多Agent协作控制面 — 协作控制面分裂；四层职责（入口/当前/隔离/知识）各配一种文件
• 开发流程要按任务大小分级 — 验证强度按「任务大小 × 所处阶段」分级；原型当合同；规则要能落成硬门槛
• 执行力的复盘 — 野心是水不是火；结果锚点 vs 产出锚点；拖延是环境问题；难题逃避待解
• 数据指标的解读 — 整体 vs 净成、ROI 成对看、LTV 链路、必须补自然流量/内容/画像
• 本地优先知识产品的架构演进 — 云端加工厂 + 本地主仓库；Agent 先做可执行入口；AI 执行层可替换
• 测试策略 — 测试由四层共同决定（agent.md 定标准 / skill 约束方法 / scripts 执行 / tests+CI 判定）
• 文档附件解析管线 — 分块按结构、表格交执行器、全局任务遍历全块、附件块绑 Session+TTL、格式分流选型
• 用户访谈与需求挖掘 — 邀约措辞 + 第一句「先给料再提问」
• 本机资源占用排查 — 本机「卡 / 烫 / 占空间」同一条判据：先分层，再按「丢了能不能重建、会不会影响数据与登录态」决定动不动它
• 竞品拆解框架 — 用户在哪 / 痛点需求 / 场景 / 商业价值 / 如何评测
• 简历模板的三层渲染协议与迁移 — data / layout / render 三层分离，section 只分 block|list，逐字段 slot 契约

三、可复用的判断（Concepts · 226）

AI 基础概念（ai-basics · 8）

• dogfooding — dogfooding 是「用真实使用来验证产品价值」——但它是必要条件，不是充分条件
• scaling-law — 模型能力随「参数 / 数据 / 算力」的投入而可预测地提升 —— 沿一条平滑的幂律曲线下降，几乎不会失灵
• 一词多义先确认所指 — 同一个词在语境里有 ≥2 种合理解释时，先确认所指再展开 —— 否则整段回答可能都在回答错误的问题
• 关联规则挖掘的支持度与置信度 — support = 组合出现比例，confidence = 出现 A 时 B 也出现；阈值直接填小数
• 实时与异步 — 选实时还是异步，不看技术难度，看「内容变化有多快」
• 技术性通缩与经济学通缩 — 两种「东西变便宜」完全不同 —— 技术进步带来的降价是好事
• 缓存命中率 — 「cache hit 为 0」通常不是 bug，而是「每次都是新会话的首请求」
• 长尾查询 — 长尾查询（搜索量极低、极具体的查询）是选择搜索源的关键判据 —— 头部词谁都能覆盖，长尾才是拉开差距的地方

LLM 工程（llm-engineering · 41）

• Agent会话要按树保存而不是消息列表 — 一轮 Agent 对话不是「用户消息 + AI 回复」，所以 AiMessage(role, content) 这种表结构装不下它
• Agent管理的记忆以文件为真相源 — OpenClaw 式 Agent 记忆的核心是：Markdown 文件是记忆真相源，SQLite/embedding 索引只是检索加速器（删掉可重建）
• Prompt版本真源在代码而不是平台 — Prompt 的版本真源是代码仓库里的 .md 文件（frontmatter 手写 version 整数 + 内容 SHA 算出的 revision），平台侧（Langfuse）
• RAG是流程不是组件 — RAG = Retrieval → Augmentation → Generation 三段流程
• 一次调用返回多种产物按内容类型组织prompt — 每篇内容只调用一次 AI，一次返回总结、观点、主题/实体等全部产物
• 上下文成本由基础上下文和会话数决定 — 「为什么上下文这么多，不是每轮都压缩吗」——压缩不是每轮发生，且只压历史
• 上下文按卡片切换会话记忆按账号共享 — 侧栏式 Agent 里，「记得什么」（session 记忆）和「当前在看什么」（context）是两个独立维度：默认只做后者按卡片切换、前者按账号固定
• 中间进展与最终回答要按phase区分 — 把 agent 的中间进展（「我先看一下……」）当普通 assistant 消息同步，客户端就会收到一堆半截消息
• 主观判据的prompt规则会随机误触发 — 把「信息是否充足」这类判断完全交给模型主观决定的 prompt 规则，会产生同输入下的随机误报 —— 实测同一篇文章（内容 hash 完全相同、输入 ~5650 tokens 的完整正文）
• 关键词检索的三个打分缺陷 — 「只在标题级文本里做 substring 匹配、按 token 长度打分、中文按整句切分」这三件事叠加，会让检索只在「提问措辞恰好出现在标题」时有效
• 兼容端点要防SDK注入非标准字段 — 兼容层按「对面就是真 OpenAI」塞字段，严格校验的端点直接 400；报错像「接口坏了」，其实多了一个 SDK 自己加的字段
• 分页游标要继承未推进实体的位置 — 多实体共用一个复合游标时，next cursor 必须「继承输入 positions + 仅覆盖本页真正返回边界的实体」
• 可观测正文要按环境分级放开 — 观测平台默认只记元数据（模型名、token、费用、延迟、成败、工具调用链、workflow 类型与状态），正文（用户输入、prompt、模型输出、工具参数与结果）默认不上报
• 多账号模型路由机制 — 同一模型在「国内版 / 国际版」两组账号间混合调用是默认行为，不需要额外配置——因为路由是 model-aware（模型感知） 的，而不是简单的账号轮询
• 实体、关键词、标签的区别 — 三者描述的是不同东西：实体 = 文中出现了谁/什么（内容事实），关键词 = 文章在讨论什么（核心概念），标签 = 用户想怎样组织它（用户意图）
• 工作流按内容类型分开而不是抽象成一条通用流水线 — 「笔记」和「文章」的后台处理不是同一条流水线换了输入，而是两条不同的业务流水线 —— 只共享底层的任务调度
• 开关要映射到模型调用才算生效 — 前端开了"深度思考"、请求参数也透传成功，都不代表模型真的开了思考
• 无入站流量的服务靠数据与配置隔离环境 — 没有入站流量的后台 Worker（队列消费、Cron）不能用域名/端口分环境 —— 它的隔离维度是数据库、env、镜像和调度锁
• 检索要按难度迭代 — 知识库检索不是「搜一次、读一篇」，而是 Agent 主导的迭代 loop：先判任务难度定预算，读不通就换查询再来一轮
• 模型可见性按入口分批 — 「为什么我没有某个模型」多半不是操作错，而是灰度按入口/账号分批放量
• 模型ID是入口相关的 — 同一个模型在不同入口的清单里注册的 ID 可能不同（裸名 vs 带 provider 前缀）；合法性由末端网关的模型表决定
• 派生数据只在写入时入队旧数据要单独回填 — 入队只挂在「新建/更新」事件上，存量数据永远不被处理，失败任务也不会自动复活
• 相似度分数不等于答案可用 — 分数衡量「像不像」不是「能不能用」；先做条件校验（能不能用）再按分数排序（哪个最像）
• 混合检索先用RRF融合 — 向量召回与词法召回的原始分数不可比，首版应该用 RRF（Reciprocal Rank Fusion）按「排名」融合，而不是校准分数
• 物化结果要按版本失效并增量刷新 — AI 生成的结果（洞察、相关推荐、摘要）不要二选一「实时算」或「生成一次就永久存」，而要当成「带版本的物化结果」：存下来、标版本、被触发条件作废、后台增量刷新。 用户问的正是这个 —— 洞察是存一次，还是随时间刷新？
• 流自然结束不等于回答完整 — 「流读完了」只说明连接结束；判据是 finish_reason，不是「循环退出」
• 整体时限不能当首字节时限用 — AbortSignal.timeout(N) 是整体时限，被当成「N 秒无响应就换下一个」会掐死慢启动请求
• 读图能力看声明字段并按模型实测 — 能不能读图由「消费方读的声明字段」与「后端是否真能读」两件事决定，且不按网关齐步走
• 短期记忆与长期记忆的边界 — 区分短期/长期记忆用两条边界：是否参与当前任务、是否跨会话持续影响行为
• 能力链路打通不等于默认开启 — 「模型支持 + 链路完整」不等于「用户能用上」—— 中间可能只差一行写死的开关
• 计数闸门不等于上下文管理 — 用「消息条数 ≤ 20」当护栏不是上下文窗口管理：服务端既不截断也不滑动窗口，要么全塞要么 400
• 评测要先隔离被测层 — 要评「拿到检索结果之后怎么用」，就把检索结果变成可控构造数据，同时让模型调用真实发生
• 评测规模要与结论的推广范围匹配 — 构造的小样本证明不了规模化检索效果与未见题推广；先问结论要推广到哪里再选数据来源
• 评测平台是平台层项目规则是适配层 — Langfuse 这类观测/实验平台能承担 prompt 评测，但永远不知道你的业务规则
• 请求别名不等于实际模型ID — 请求里的模型名可能只是一个别名（路由名），provider 响应里返回的 model 才是实际执行的模型 ID
• 轮换要带健康状态记忆 — 多 key / 多模型轮换不能盲目串行遍历：要记住哪些组合刚坏过、按错误性质设冷却、并给每次尝试设超时，否则一轮请求会把函数执行预算烧光，用户等满超时后仍然失败。
• 重试分三层不要整体重跑 — 「重试」不是一个动作，而是三个层级，必须分清各自动的是什么：
• 长任务不要用固定超时判定 — 用固定 RUN_TIMEOUT_MS（如 10 分钟）来判定一个 agent turn 是否结束，会误杀长任务

Agent 与 Skills 生态（agent-ecosystem · 40）

• Agent Harness 不只是 Tool Loop — 「能调工具、能循环」只是 harness 的骨架，不是 harness
• Agent harness 要隔离复现可收尾 — Agent harness 是给 Agent 搭的「调试房间」，本质回答三件事：隔离谁、怎么复现、怎么收尾
• Agent编排层薄自建优先于重型框架 — 给本地优先的桌面 App 接 Agent，先自建一层很薄的编排层，不要直接引入 LangChain / LangGraph / AutoGen 这类重型框架 —— 能力边界很明确时，重框架带来的抽象成本大于收益。
• Issue完成由用户验收后再关闭 — 用 Linear/MCP 管项目时，agent 实现完 Issue 后要保持 In Progress 等用户验收，不能自己设 Done
• deploy目录是运行配方不是另一套应用 — monorepo 三层分工：apps/ 是程序本身做什么，packages/ 是程序复用哪些能力，deploy/ 是程序怎么运行到服务器上
• skill约束要区分补短板与替模型判断 — 模型足够强时，很重的 skill 约束反而会限制它的能力 —— 判据是：这条约束在「补模型当下做不到的事」，还是在「替模型做它本可动态判断的决策」
• skill跨agent加载差异 — 「磁盘上有」≠「本 session 能用」
• 一次性凭证拿到就落盘 — 授权码换 token 这类「一次性」命令只能成功执行一次
• 两个执行入口共用一套业务规则 — 当「用户手动操作」和「Agent 调工具」都会改同一份数据时，必须把确定性业务规则抽到两者共用的 Service 层
• 交付前先同步主干 — 本地验证通过 ≠ 交付可用；先对齐主干，否则合并时冲突与回归
• 什么该进git什么该ignore — 判断标准是「换台机器 / 换个人能不能复现」：产物与本地状态不进，配方与契约要进
• 作者是AI时协议要唯一规范答案 — 产物的作者是谁，决定协议该怎么设计
• 全绿的单测可能测的不是那条链路 — 测试绿了但真实 bug 还在，通常不是"测试没覆盖到"，而是"测试覆盖的是另一条链路"
• 共享历史不等于共享活会话 — 做「手机看/控电脑上的 Agent」时，「手机和电脑同一个会话」有三个不同层级，别把它们当成一回事：①同一个历史 thread
• 加载skill不等于遵循skill流程 — 系统提示词里带上 skill 清单只解决了「发现」；触发时必须主动读 SKILL.md 并按路由执行，否则会出现「用了检查工具」但没走完整流程的执行偏差 —— 这不是 skill 没生效，而是路由与遵循做错了。
• 协作规则要入Git才算项目资产 — 写给 agent 的协作规则（AGENTS.md、.codex/、.agents/、rules 等）
• 多源更新按维度取真源 — 同一份产物有两个来源时，不要整体选「更新的那个源」，要按维度分别取权威版本
• 委派颗粒度要匹配信息缺口 — research worker 与 issue 不是 1:1；它只用于填补主控暂时不清楚的关键未知点，不是每个 issue 的标配
• 子issue是发现新范围的结果 — 子 issue 不是预先拆好的清单项，而是执行中才发现的新范围
• 工作模式切换改变的是harness而非模型 — 同一个模型在不同「模式」下的差别不是换了个名字，而是 harness 变了：执行环境、上下文注入、工具集、权限模型全都不同
• 手机后台推送要靠服务端远程推送 — 只靠「App 前台 WebSocket + 本地通知」做不到「电脑上的 agent 跑完就推给手机」
• 改协议要同时改两端 — 项目里有两条链路（如 Claude Code 一套、Codex 一套）时，改 WebSocket 协议或连接逻辑不能只改一边
• 无头环境连MCP要用APIKey而非OAuth — 要不要用 OAuth 取决于运行形态，不取决于客户端名字：有 GUI 的桌面版能弹窗就走 OAuth，无头 / CI / 服务器场景没有浏览器，只能预先换成 API Key（Bearer Token）。
• 随时间变化的上下文要逐轮注入 — 会随时间变的值（日期/时间/星期）不能挂在会话级系统提示上，必须逐轮注入
• 真相源位置决定多端关系 — 同一个产品，真相源放在本机还是云端，决定了其他端是什么角色、仓库长什么样
• 终端画面同步Agent状态不稳定 — 用 tmux 把手机接到电脑上同一个 Codex CLI 会话，能实现「电脑和手机看同一个活会话」——因为手机输入真的敲进那个 CLI，电脑 attach 就能看到同一画面。
• 经验沉淀要在问题验证后按需触发 — ce-compound 这类经验沉淀 skill 不是过程日志，也不该在 worker 每完成一步时运行 —— 它只在一个非平凡问题已经解决并验证后，把解决方法沉淀成可搜索的 durable learning。
• 编排器只包装已有CLI — 不要重写 Agent 内核，编排层只负责包装已有的 CLI
• 网页读取工具要受控而不是直连任意URL — 给 agent 加网页能力，不是「让它能访问 URL」，而是新增两个受控工具：web_search(query) 和 web_fetch(url)
• 能从代码库查到的不许问用户 — 凡是能从仓库/配置/日志查到的事实，都不该占用用户的回答带宽
• 自动提交脚本要先确认当前分支 — 自动 commit/push 前先确认当前分支，否则会把改动提交到错误的分支
• 观测平台不能当运行状态真相源 — Langfuse 这类可观测平台适合回答「为什么这样做、花了多少」，不能当 Agent 运行状态的真相源 —— 恢复依据必须存在自己的数据库里
• 远程Agent控制要定义执行协议与状态模型 — 做「手机/网页远程指挥服务器里的 Claude Code/Codex」这类产品，只画 App 页面是不够的
• 远程控制本机Agent要让bridge跑在本机 — 手机 App 不能直连命令行 Agent（Claude Code/Codex 不是 WebSocket 服务），中间要有一个 bridge 把 CLI 包成 WebSocket。
• 通用脚本要靠工具适配器接入 — 跨 agent 的通用脚本不会被某个工具自动执行
• 项目里的技能可能有多份副本 — 「项目本地有一套 skills」这句话不足以定位到具体目录 —— 同一个项目里可能同时存在 .agents/skills、.claude/skills、.codex/skills 多份副本，内容还不一致。
• 验不到的部分要显式记为未验证 — 验收受工具能力限制而没覆盖到的项，必须显式写成 blocker，不能含糊带过、更不能写进"通过"
• 内置能力只覆盖它声明的那一段 — 判断框架「是否内置某能力」，要问它覆盖到链路的哪一段，而不是有没有这个词

前端工程（frontend · 57）

• Cookie不区分端口所以同域多端口共享登录态 — 在 localhost:3018 登录后访问 localhost:3024 能直接用 —— 因为 Cookie 按域名隔离、不按端口隔离
• Electron自带浏览器运行时是内存大头 — 内存高不是页面成本，是先付了一整套 Chromium + V8 + 渲染树的运行时基础成本
• Vercel四个运行环境各填什么变量 — Vercel 一个变量名可以在四个环境填不同值：Production（正式域名吃它）、Preview（PR / 非主分支的临时预览网址）
• flex子项的百分比max-height不可靠 — 想给 flex 子项加 max-h-full + overflow-hidden 来截断超长内容，会因为父 flex 容器没有显式高度而表现不一致
• 依赖版本要锁主版本而非一律取最新 — 装依赖时不要无脑选「更新到最新版本」：脚手架工具可以用最新版，项目运行依赖要按既定主版本锁住
• 保存失败要落本地草稿并自动重试 — 云端保存失败时，正文不应只活在编辑器内存里
• 停止与发送原地互换要加点击守卫 — 「停止」和「发送」放在同一个位置原地互换时，点击停止的瞬间状态已切回 idle、按钮已换成发送，鼠标抬起（click 事件）就落在发送按钮上，把草稿误发出去
• 兼容fallback会让内容重复渲染 — 为旧模板保留的 fallback 路径，会让同一份内容在新模板里被渲染两次
• 列表切换要用master-detail而非重建列表 — 左列表 + 右详情的界面，如果点卡片走「完整路由跳转」（/notes/[slug]），每次切换都会经历详情页挂载、列表重新渲染/排序、编辑器初始化，于是容易「选中后列表跳位」。
• 单例库要显式声明同一版本否则运行时分裂 — 必须全局唯一的库（OTEL provider、React、状态容器等）
• 可调与固定的边界按语义划分 — 「哪些样式允许用户调节」不该全局一刀切，边界由语义角色决定
• 图片加载失败要可重试并升级到HTTPS — 头像/图片「全变成文字」通常是加载失败触发了 fallback，而不是设计改了文案
• 图片粘贴要上传对象存储换永久URL — 笔记正文只能存「图片地址」
• 复制要区分可见文本与富文本 — 编辑器的「复制」要分两种产物：text/plain 只写屏幕可见文字，text/html 保留富文本
• 延迟保存要捕获创建时的实体 — 延迟任务（debounce / setTimeout）在触发时才去读「当前活跃对象」，会在切换期间把 A 的数据写到 B 上
• 引擎不做建模器 — 当渲染引擎需要在代码里手写顶点和面来造模型时，说明分工错了：引擎应该只负责「切模型 / 渲染模型」，建模交给外部工具，产物用标准格式（Blender → GLB）导入。
• 手搓编辑器核心逻辑到深处要评估换社区方案 — Markdown 实时渲染编辑器一旦核心逻辑是自己手搓、且越补越多，长期维护成本会失控
• 折叠动画要有收起态过渡 — isOpen && <内容> 的条件渲染只有「进入动画」——展开时能靠 animate-in 播一次，收起时元素直接从 DOM 卸载，没有可过渡的中间态，所以看起来「无动画」。
• 控件参数要在下游被消费 — 控件能调、值也确实传下去了，不代表会生效 —— 参数必须在消费方被真正消费，否则表现为「调整了没反应」，而且不报错
• 改版后旧路由仍指向旧实现 — 改版后用户点进某个入口却看到旧界面，第一嫌疑不是「新组件写错了」，而是「那条 route 还 import 着旧组件」
• 改环境变量要触发云端重建而非重新上传 — 在 Vercel 上改完环境变量，正确动作是「重新构建已有部署」（vercel redeploy <已有部署URL> --target production），而不是 vercel deploy --prod。
• 新建对话的hero要淡入入场而非加载态 — 用户说「开启新对话的过渡动画」时，指的可能是入场动效（hero 区缓缓淡入 + 轻微上移），而不是转圈加载态
• 显示阈值应按元素可见性而非固定像素 — 「下滑到一定距离后顶栏才显示标题」若用固定像素阈值（如 scrollTop > 18），会因为字号/行高/布局不同而提前或延后出现
• 服务端缓存与浏览器缓存的边界 — Redis 和 IndexedDB 不是可互换的两种缓存 —— 差别不在性能，在「缓存放在哪一层、给谁用」
• 本地优先不等于纯文件 — local-first ≠ file-only；卡顿根因通常是网络请求还在切换内容的关键路径上
• 条件return前必须调用所有hooks — 进入子层白屏、content area 全空、React 渲染 crash，若组件里有「提前 return」，第一嫌疑是 hooks 调用顺序被破坏，而不是后端数据格式。
• 流式更新要合并字段而非替换对象 — 流式渲染时 arr[last] = { role, content } 是整体替换，会把同一对象上后加的 thinking 字段整个丢掉
• 浅层改URL不会切换组件 — 浅层路由只改地址栏，组件树不变，写在目标路由里的 effect 不会跑
• 浮层要收敛到一个共享primitive — 所有弹出卡片（菜单/弹窗/下拉）应共用同一个 primitive，而不是每个局部各写一套
• 滚动层会裁剪溢出内容要与显示层拆开 — 只要一个元素负责 overflow-x: auto，它就会裁剪超出边界的内容
• 滚动条顶到固定栏要调视口而非隐藏滚动条 — 「滚动条轨道穿过了顶部固定 toolbar」的正确修法是让滚动视口从 toolbar 下方开始（margin-top: 46px，滚动容器作为 flex 子项），滚动条天然不会顶到 toolbar。
• 焦点环画在圆角外会露出四角 — 「边框四角有奇怪的蓝色阴影」不是边框坏了，是 focus ring 画在圆角边框外侧：通用 Input 自带的 focus-visible ring 没有跟随圆角。
• 父组件每渲染生成新对象会触发effect循环 — 「Maximum update depth exceeded」
• 环境变量校验要按模块懒加载 — 把所有环境变量都设成「启动/初始化时必填」，会让还没开发到的模块阻塞已经可用的功能：只是想登录，Auth 初始化却因为 AI key、对象存储、邮件配置不齐而报错。正解是按模块懒加载——用到哪个模块才校验那组变量。
• 登录发起与回调必须同域名 — 看到 InvalidCheck: pkceCodeVerifier value could not be parsed 这类登录报错，先查「发起登录的域名」和「回调回来的域名」是否一致。
• 离线存储的三个等级 — 「加缓存」不是一个档位：从会话缓存到完整离线编辑差三个等级，实现与风险都不同 —— 先说清要哪一级，再动手
• 移动应用正式分发需要签名 — iOS 和 Android 的正式安装包都需要签名
• 终态已到达后补写不能覆盖它 — 流式协议里"权威终态"（turn.completed）到达后，尾部的 EOF / 传输错误 / 迟到分片都不能把状态改回进行中或失败 —— 否则用户看到"已完成的回答被截断成半截 + 卡住"。
• 编辑即时反馈与落盘延迟分离 — 不要为了「保存及时」改成每个字符都落盘
• 编辑器与只读渲染要分层 — 编辑场景用完整编辑器引擎（Milkdown/ProseMirror），只读场景用轻量自研渲染器 —— 不要拿编辑器去渲染只读内容
• 编辑器初始化会触发假保存 — 富文本/Markdown 编辑器加载一篇笔记时，会把 Markdown 解析成内部结构再序列化回来，过程中「整理格式」（表格空格、分隔线长度、checkbox 写法）——内容语义没变，但字符串变了。
• 编辑器显示不能脱离真实光标状态 — 只要「显示什么」依赖「光标在哪」，一旦 selection 状态同步滞后，画面就和真实编辑状态分叉 —— 症状是标记莫名消失、或看起来正常但输入落到错误位置，而内容本身没丢。
• 编辑重发与重新生成要先截断后续轮次 — 编辑一条历史消息重发、或对某轮点「重新生成」时，必须先把该轮次及之后的所有消息从会话里截断（DB 层 truncateFromTurn + 模型上下文同步截断），再发送新内容
• 聊天记录要从底部锚定加载 — 进入聊天会话时应该「直接定位到最下方、向上翻才加载更早消息」，而不是「先全屏 loading、加载完再滚到底」
• 虚拟列表与布局动画不能同时接管位置 — 虚拟滚动用绝对定位 + transform 控制卡片位置，布局动画（如 Motion 的 layout）也修改 position/transform —— 两者同时接管布局就会抖动或位置错位。
• 解析器卡死看游标是否推进 — 流式渲染偶发"卡死"、CPU 打满，先怀疑解析循环有没有推进游标，而不是后端或模型
• 跨源取数据要靠自建代理 — 本地不同端口 = 不同源
• 过期响应不能覆盖当前编辑内容 — 「刚写的字被回退」不是文件写错了，而是异步保存返回顺序不可靠：旧请求晚回来时，把过期的 content_md 又合并回了前端内存
• 过程展示按时间线分层而不是分组聚合 — Agent 的执行过程应按「一次 turn 的完整时间线」呈现，而不是把 reasoning 和 tool call 各自聚合成组
• 运行时依赖属于平台不属于业务代码 — 构建时冒出 hermes-engine 之类你不认识的依赖，先分清它是「平台/运行时自带的」还是「业务代码引入的」——多半是前者，不要去动它
• 进度条要由真实进度驱动 — 「点击后加载动画」不能用无限循环动画假装：要么绑定真实加载状态，要么基于经过时间连续推进
• 隐藏态按钮要保留命中区 — 用 pointer-events: none 让 hover 才出现的按钮「不可点」，会让光标先落在该区域时事件被底下的链接/卡片吃掉——按钮随后出现也点不到，表现为「点三点菜单有时候没反应」。
• 页面切换的四种刷新要分清 — 「页面慢 / 数据没更新」这类问题，先要问清是哪一种「刷新」—— 四种刷新走的是四条完全不同的链路，混着讨论必然各说各话
• 页面变慢先查每页鉴权与无分页拉取 — 页面「整体卡」通常不是单点故障，而是三层叠加：① 服务端每个页面都先跑鉴权（被强制动态渲染，先等服务器 + 数据库）
• 首次内容事件不能无条件跳过 — 编辑器为了避免「刚打开就标记为已修改」，常会跳过第一次内容变更事件
• 骨架屏呼吸动画用独立亮度层 — 做骨架屏的呼吸/闪烁效果，要分两层：底层是始终不透明、不变化的灰色块
• 高频手势缩放不要走React状态 — 触控板捏合 / 滚轮缩放掉帧，根因通常不是「事件太多」，而是把每次事件都塞进了 React state，还顺带改了大 DOM 的布局

产品方法论（product · 12）

• 一次循环只做一个可体验的v1能力 — 0-1 产品的一次迭代循环，范围应是「用户能真正体验到的、最小的完整 v1 能力」——不是一个微小补丁，也不是一段多周路线图
• 修复范围分保守彻底与最小闭环 — 同一个问题给两档方案（只改表层 / 从源头重构）是错的提问方式 —— 缺了第三档「最小闭环」：把修复点挪到正确的层，但只加一个字段、不做全量重构
• 先恢复可信基线再谈重构 — 决定「重构项目」之前，先做一次架构与工作流审计，把现状冻结、边界确认 —— 因为要修的往往是契约，不是目录
• 分享要反映品牌与产品调性 — 对外分享出去的页面（分享链接、分享卡片）是品牌触点，不能只是「把内容渲染成普通文档页」
• 北极星指标要量价值闭环 — Agent 产品的北极星不该量「调用得勤不勤」，而要量「价值有没有闭环」——用户是否真的把 Agent 的产出采纳并沉淀成了自己的资产
• 地基阶段先跑通基础件再谈抽象 — 做地基阶段（数据层 / 后端基础件）时，先把基础件跑通，不要过早为每个业务做抽象分层
• 完整蓝图不等于同阶段交付 — 用户要「完整方案」时，不要把完整方案砍成 MVP，也不要把完整蓝图理解成「所有东西同一阶段交付」
• 容器要有超出文件夹的意义才值得独立入口 — 如果一个「知识库」只做到文件夹的形态，它本质上就是笔记的文件夹系统，不该再单独占一个顶层入口 —— 要么降级为笔记里的顶层集合，要么给它文件夹之外的意义
• 用户可感知的价值与差异化表达 — 产品的价值只有变成用户能感知的具体对照时才存在
• 答疑是功能层搜题只是手段层 — 答疑是用户场景层的完整功能（答对 + 讲明白），搜题只是手段、讲题是另一层
• 简历写的是解决方案不是执行动作 — 写动作=执行层，写判断（为什么必须解决/错误在哪/怎么验证）=解决方案层
• 评审设计可行性先问方案再定难度 — 问「这个设计能不能做出来 / 难度多大」时，不能直接给难度分级和实现方向 —— 要先问「你打算怎么做」

自我管理与复盘（self-management · 1）

• 学领域先看一流成品而非方法论 — 方法论是二手归纳；先看一流成品建立「好是什么样」的判据

知识库架构（meta）（knowledge-base · 14）

• Agent读语义文件App读结构化存储 — 知识库不该让 agent 直连数据库：SQLite 是导航系统，Markdown 才是知识本体
• Schema是声明Migration是历史 — schema.prisma 只是「目标结构长什么样」的声明，它不会可靠地把生产库改好
• 入库前先分层清洗 — 噪声不该留到提炼时才处理
• 列表卡片元信息用内容作者而非平台名 — 同一份内容在「列表卡片」和「正文」两处的元信息该显示什么，是两套规则：列表卡片要能认出「这是谁写的」（订阅博主名 / 用户编辑过的名字），正文则沿用剪藏那套元信息。
• 导入要保留来源类型以选对渲染链 — 内容导入时如果把不同来源的正文塞进同一个字段，就会丢掉「它原本是什么格式」这个信息，渲染时自然选错渲染链
• 抓取结果不能无条件覆盖源数据 — 二次抓取（网页全文补全）的结果必须通过有效性检查才能覆盖 RSS 原始内容 —— 否则反爬页面会把干净的标题和摘要覆盖成域名与脚本
• 放宽过滤会连噪声一起放进来 — 为了修「新内容被跳过」而删掉入库过滤条件，会把「只有摘要、没有正文」的条目一起放进来
• 数据权威模型要先于同步与迁移确定 — 多端产品在写同步协议、迁移方案之前，必须先定「谁是数据权威」（source of truth）
• 文章元信息用发布日期而非创建日期 — 剪藏详情页顶部的日期应是「文章发布日期」，不是入库创建日期
• 权威wiki是索引加精选知识 — 权威 Wiki 的作用不是「让文档更好看」，而是给人和 Agent 一个统一的 Project Truth（项目事实入口）：Linear 告诉 Agent「这次要做什么」
• 清洗合并会破坏源格式语义 — 把飞书导出的原文清洗、合并成 Markdown 时，格式语义会静默丢失 —— 而验收标准是「渲染出来的样子」，不是「文本内容对不对」
• 知识入库的筛选标准 — 不是所有 session 都值得入库：只有能提炼出概念或 topic 的轮才进
• 知识库先编译再查而不是查询时拼原文 — 传统 RAG 每次提问都从原始文档的 chunk 里临时拼答案
• 首次导入与增量更新要用不同规则 — 「首次订阅导入」和「定时增量更新」是两种不同任务，不能共用一条固定条数的抓取规则 —— 否则首次的截断设置会被后续增量立刻抵消

本机排障（diagnosis · 53）

• GitHub打不开先分清主站与静态资源域名 — 用户说"打不开某个站点"时，先问清是整站不通还是只有部分资源不通 —— 按域名分层测一遍，比直接归因"被墙了"准确得多
• 清理客户端缓存先分清哪层可丢 — 「浏览器缓存占了 22G」是几层混在一起；判据是「丢了会不会影响数据与登录态」
• INSERT OR IGNORE会让旧行不更新 — 「DB 里新数据的字段是对的，界面上旧数据还是旧值」——先查插入语句是不是 INSERT OR IGNORE
• MCP连不上先分层定位配置令牌与代理 — MCP 连不上时按「配置 → 令牌 → 代理/TLS」分层定位，不要一上来就重装或反复重登
• worktree是独立目录产物与配置都隔离 — git worktree 不是「在当前目录切了个分支」，而是「分支 + 一个独立文件夹」
• 两条写入路径要用内容判重 — 当同一条数据有两条写入路径（本地直写 + 远端镜像回灌）时，只用 id 去重一定会重复 —— 因为两条路径会给出不同的 id
• 中转源不更新先分清是哪一层 — 聚合端「这条源没更新」时，先数一下这条源经过几层中转
• 迁移文件存在不等于数据库已升级 — 有 migration 文件 ≠ 它被执行过；schema 声明与库的真实结构是两件事
• 端口占用会把你连到别人的服务 — 自己刚起的服务端口被别的 worktree 占着，请求打到别人的进程上，症状与根因完全错位
• 仓库残留会误导对现状的判断 — 当运行时的东西已经全部来自数据库，仓库里的 prototypes/、旧文档、旧测试假数据、旧 migration 默认值仍然存在，会让 agent 反复误判「还有一套本地实现」。
• 以前能用最近坏了先查自己改了什么 — 「之前没问题、最近出问题」时，默认假设是自己这边的改动造成的回归：先去翻最近几次提交动了哪条链路，而不是先怀疑外部源（网站改版、上游接口、环境）
• 停机前先确认有可恢复备份 — 对生产数据做需要停机的变更（迁移、替换数据库、重写存储）之前，必须先确认存在可恢复的备份 —— 优先用平台自带的卷级 snapshot，而不是自己临时想办法
• 先分清平台错误还是应用错误 — 500 status code (no body) 这种「有状态码、无响应体」的报错是平台层（Vercel 函数超时/崩溃）的格式
• 凭据正确却被拒先查登录校验哪个字段 — 「账号密码是对的，但 API 说凭据无效」不一定错在密码 —— 先看登录逻辑用哪个字段做校验
• 凭据来源不唯一会让客户端反复刷新 — 同一份 auth 文件里并存登录态与注入 key 两套凭据来源时，客户端刷新会互相触发 —— 表现为「一打开就反复刷新」
• 功能缺失先确认运行的是哪份产物 — 「我本地 app 还是旧版本、新功能都没有」这类症状，第一件事不是查功能代码，而是确认你实际打开的是哪一份产物：安装目录（/Applications/*.app）里的是旧版本，刚构建出的新版本还躺在构建输出目录里。
• 只有第一发失败要查冷启动与连接重试 — 「每个会话第一发必失败、重试就好」是服务端无状态依赖的冷启动，不是业务逻辑
• 合并绿灯要对应当前HEAD — PR 上的绿灯针对的是那个提交，不是刚改好的版本；本地未 push 的修复不在其中
• 合盖仍会睡眠后台任务会被中断 — 想让 Codex/Claude 这类后台任务跑完，不能靠 agent 自己的设置——它们没有「合盖后继续跑」的开关，控制权在 macOS 电源管理
• 同一应用开出两个窗口先查单实例限制 — 桌面应用出现两个窗口，先怀疑两件事：框架没做单实例限制、旧进程没退出 —— 而不是渲染 bug
• 同目录多会话会抢分支 — Git 的 HEAD / 当前分支是「目录级」状态，不是「会话级」状态
• 回滚要保留数据迁移的兼容路径 — 代码可以回滚到上一个版本，但已经跑过的数据迁移不会自己回滚 —— 所以「回滚」这件事必须在写迁移时就设计好兼容路径，而不是出事时才发现回不去
• 备用构建目录不要嵌在next目录里 — 为了在别的端口起第二个 dev server 而改 distDir 时，把临时目录放在 .next 里面（如 .next/codex-3001）
• 对照两端要用同一条标识 — 判断「这条内容到底有没有入库」时，必须拿系统间共享的那条标识去对照
• 开PR前先确认基线的远端状态 — 本地主线领先远端主线很多提交时，从功能分支直接开 PR 会把这一长串与本次任务无关的历史一起带进去
• 异步补齐长期不生效要查写入失败 — 「异步生成的内容（正文、缩略图、转码）标题摘要早就有、正文迟迟不补」，如果已经超过正常窗口很久，那就不是「还在处理中」，而是写入侧失败
• 打不开的app先查隔离标记与签名 — 下载来的 .app 带 quarantine 属性又只有 ad-hoc 签名时会被 Gatekeeper 拦下
• 抓取要存清洗后的正文而不是整页 — 抓取类系统应该存「清洗后的正文」，不是「抓到的原始响应」
• 接口验证通过不等于浏览器已登录 — 「验证 API 登录」和「浏览器页面建立登录会话」是两件事 —— 接口返回 200 只能说明账号有效，不代表浏览器拿到了 session cookie
• 改远端库结构前先确认库身份与回滚 — db:push 这类直接改远端数据库持久结构的操作，执行前必须先确认「这是测试库、共享库还是生产库」以及有无 migration 与回滚能力 —— 它改的不是本地代码，是所有人共用的持久结构。
• 改配置后要确认部署真的用了新配置 — 「重新部署」不一定应用新配置 —— 有些平台会复用旧的部署清单
• 文件被回退先分清是工具还是并发会话 — 看到「文件被 linter 大幅回退了」，第一步不是去查 linter 配置，而是先确认这个工具到底有没有写文件的能力
• 本地开发脚本可能连生产资源 — 聚合式的 pnpm dev 会启动整条后端链路，且很可能读到生产环境变量 —— 本地开发在悄悄消耗生产资源
• 本地测试要显式覆盖数据源 — 分支的 .env.local 常是指向主项目根目录的软链，里面写的是远程/生产数据源
• 本机卡顿先清残留开发进程 — 开发时「莫名越来越卡」，常见根因不是当前代码死循环，而是环境被残留进程拖爆：多个端口的 dev server、遗留的 build 进程、旧的 .next-* 缓存目录同时存在。
• 杀端口要区分服务端与客户端连接 — lsof -ti:PORT | xargs kill -9 会同时杀掉监听该端口的服务端进程和连到该端口的客户端进程（浏览器渲染进程），要先用 lsof -i:PORT 看清 COMMAND 再挑着杀。
• 样式丢失先核对类名再怀疑缓存与权限 — 「CSS 完全没渲染」这类现象，排查顺序应从「当前组件用的类名」与「CSS 文件里实际存在的类名」是否对得上开始，而不是先怀疑缓存或文件权限
• 滚动部署期间改库结构会撞上旧容器的锁 — 在滚动部署（rolling deploy）的平台上对 SQLite 做结构/模式迁移，会失败在 PRAGMA journal_mode=DELETE 这类需要独占锁的步骤上 —— 因为新容器启动时旧容器还持有锁。
• 真机白屏先分清Debug包与证书 — iOS 真机装上 App 却打不开/白屏/闪退，先别怀疑业务代码
• 项目占空间先查构建缓存与旧worktree — 一个 monorepo「占了十几个 G」，通常不是源码占的，而是构建缓存 + 旧 worktree + 构建产物
• 观测平台的环境维度由数据产生 — 观测平台（Langfuse）的环境列表是数据驱动的：只有当至少一条带 environment=X 的 trace 上报过，UI 里才会出现 X 这个选项
• 讲bug先讲现象再讲根因 — 解释一个 bug 时，先说「你会看到什么坏现象」，再说根因和改法
• 远端主线可能与本地主线无共同祖先 — 看到「远端 main 很旧」时，先别假设是普通分叉
• 集成已合并不等于运行时已启用 — 「代码已接入」与「运行时已启用」是两个状态；配置为空时常被设计成静默关闭
• 需要认证的命令不要并行执行 — 并行跑两条需要登录的命令，两条都会各自发现「当前未登录」并各自发起一次授权流程，于是浏览器弹出两个授权页
• 面板多出的固定区块先查数据源再改前端 — 前端"总是显示一个不该有的卡片"，且不随切换条件变化时，问题多半在数据链路而不是渲染逻辑：请求被转发到了固定实例，而该实例的数据里包含了对端实例的信息
• 验收要按唯一标识选中实例 — 跑的是刚构建的新 binary，却用应用名去激活和截图（osascript tell application "Mewmo" / pgrep -x mewmo）
• 高负载发烫先排除负载而非硬件 — 无风扇机型「莫名发烫」的第一假设应是持续负载，不是硬件故障
• 同名provider冲突会让模型路由漂移 — 自定义与内置 provider 同名时，只带模型名、不带 provider 的会话会解析到内置后端；用报错措辞判断请求实际落在谁那里

四、待探索（有问题没答案 —— 最有价值的钩子）

• 遇到具体难题想逃避，怎么破（已有环境/具体动作框架，缺难题切入法）
• 各渠道免费额度的刷新机制横向对比
• 数据缺趋势视角：环比/同周期对比怎么建
• 「RAG vs 微调」补成正式概念页（clean 里只有 agent 提及，缺提问作为依据）
• 访谈中段怎么追深（第一句开场已解决，缺中段追问框架）
• 「一个 Goal 里同时有笔记 / wiki / chat」怎么建模
• 内置能力只覆盖它声明的那一段 —— 仅 2026-08-03 一个来源日
• 迁移要连归属信息一起搬 —— 仅 2026-08-10 一个来源日
• 叙事单位是能力轴，不是项目 —— 仅 2026-08-20 一个来源日
• 构造的测试数据要标为构造，不能算作真实缺陷 —— 缺第二个来源日
• 相似度分数不等于答案可用 —— 缺第二个来源日
• 结论的推广范围决定实验用构造数据还是真实链路 —— 缺第二个来源日

共 273 页 · 更新于 2026-10-11