Dev Lessons — 个人开发踩坑知识库

来源：CharacterSeed（15 篇 dev_lessons）、frontend/项目开发总结、luyan/2026-06-28-开发经验总结、pr/MoneyPrinterTurbo-PR1291 等，2026-09-03 蒸馏整合。 原始文档保留在各自项目内，本库每条经验带 溯源 字段可回查完整上下文。

使用方式（按索引检索，勿整读）

1. 开发前：按下方场景路由表定位领域 → 打开该领域文件先只读头部的「条目索引」表（编号 / 标题 / 场景标签）→ 用 search_content 搜编号或关键词（如 ### M-22、CRLF、supervisor）精确读取命中的那一条。不要整读大文件：misc.md 有 57 条（≈ 5.0 万字符）、deploy-env.md 26 条，而单条通常只有 1 KB。
2. 排查时：直接在 references/ 目录按关键词/标签搜（#行尾、#浏览器自动化、GROUP_NOT_FOUND…），命中即读该条目。
3. 项目结束时（用户说"结束"时）：按文末进化协议追加新经验。 ⚠️ 追加前先读目标文件头部的条目索引，取该前缀的下一个可用编号——2026-09-23 发生过并行会话撞号（两组 M-13/14/15、两组 E-09），修复代价是重编号 + 更新所有交叉引用。追加后顺手同步该文件的索引表（用同样格式加一行）。

场景路由表

十五条元原则（跨场景，最高优先级）

1. 结构化优先：凡是要 LLM 稳定遵循的属性（年龄/风格/格式），必须结构化存储（DB 列/枚举），注入 prompt 并进优先级表；自由文本字段不可靠。反向同样成立——要求模型输出的字段也必须显式声明结构（完整 schema + 枚举词表），否则模型只填提示词里点过名的那一个字段，下游分组/打分全部退化（2026-09-11 修订，见 L-10）。
2. 降级路径与主路径同等重要：fallback 也要多样化、可识别、可救援；修 fallback 时必须检查主路径是否同样有病。
3. 状态三处一致：内存变量、DB、前端展示。任何用户 override 都要问一句"写回 DB 了吗？"——后台异步任务只信 DB。
4. 异步任务的前端契约：占位状态显式建模（如 pending_enrich），前端识别后走"生成中"分支 + 轮询（如 5s×6）；绝不把占位文本当最终结果，绝不显示"生成失败"，显示"生成中"。
5. 迁移幂等：ALTER TABLE 前先查列是否存在；迁移脚本重跑不能炸。
6. 半截路检查：新数据流必须贯穿 model → migration → API → caller 四层，只写 crud 层就是埋雷。
7. 复用不复制：上游代码用动态引用（importlib + 独占 namespace + stub 注入），只引用纯函数；逐行复制 = 双份 bug 维护。
8. 部署三件事：缓存策略（nginx Cache-Control + hash chunk）、MOCK 数据清理、可选依赖优雅降级（缺 SMTP/OAuth key 不崩，降级运行）。
9. 协作先行：开源 PR 先沟通占坑 → 用数据回应 maintainer 顾虑 → 快速响应 review → 完整测试证据链。
10. 超时预算：LLM read timeout 按 prompt 规模和 max_tokens 设定（复杂 prompt ≥60s）；警惕超时静默走 fallback——症状是"结果突然变短/变烂"，不是报错。
11. 工具读数二次确认：诊断结论不能只依赖单一工具输出——控制台可能用错误编码渲染（GBK 渲染 UTF-8 制造"假性乱码"）、搜索可能跨同名副本串台（或对点目录/超大文件静默 0 命中，见 M-54）、命令行内联 JSON 可能被转义吞引号。改代码前必须用第二种手段交叉验证（换工具读同一数据源、打印 repr()/码点、比对文件行数与章节标题），否则会基于幻觉修坏本来正确的代码。
12. 对外宣称必须可验证、且三处同源：README / 落地页 / 视频 / 宣传文案里的每一句"能力、路径、口径"，都要能指向一条命令可复现的验证手段（端点、文件行号、脚本）；只写"清单公开""支持 X"这类笼统话，就必须补上"在哪验、怎么验"。源码 / 文档 / 对外画面必须同源 —— 本次教训：视频卡片写 /api/assistant/meta，实际端点叫 /api/assistant/status，而这个错路径同时躺在卡片源码里，重渲一次就会再错一次。发现不一致时二选一：改口径，或补实现；已发布物无法回改时，用可公开追溯的方式更正（评论区 / 更正说明），并把源头一起修掉（2026-09-21 新增）。
13. 交付形态即验收对象：验收必须打在"用户/评审真正会拿到的那一形态"上 —— 发布后下载下来的资产、冻结后的 exe、线上 URL；本地构建通过 ≠ 发布物可用（打包命令、产物结构、数据落盘位置都可能不同）。它是 E-08（本地 QA 根目录对齐生产前缀）、M-10（本地验证的假成功/假失败）的第三次同类出现，按"同一问题第三次出现即提升"入库：今后凡发布，必须补一次"下载资产 → 解压 → 运行 → 查版本/健康/页面"的闭环（2026-09-21 新增；2026-09-26 补一条边界：当本机网络取不回交付物时——例如 release 资产在受限网络下无法下载——退一步用“同一条构建命令产出的等价产物”做字节校验（本例：本地 git archive 的 zip 内脚本与本机实跑脚本 sha256 一致），并在交付说明里显式声明未验证到的那一层，别让“已验证”无限背书）。
14. 共享可写文件只追加、不重写：同一个文件可能被多个会话/写者改时（当日日志、当日决策记录、共享配置），永远不要整篇重写——用文件末尾锚点做追加，且写之前先读一次尾部确认锚点还在、内容没被换掉。整篇重写会静默吞掉别人的记录，且事后只能靠"我记得写过"才发现；权威记录要落到仓库/带版本控制的地方（2026-09-26 新增，同族 M-28）。
15. 长任务先读系统守护的规则：在装有"自动杀进程"组件（内存守护一类）的机器上跑长任务（构建/渲染/编译），开工前先读守护的规则与阈值，再选姿势：优先用其可热加载的白名单临时豁免（任务结束立刻恢复原状），其次限进程内存、让产物可续跑。进程一旦"静默消失"（无报错、无栈、日志停在半途），第一个取证对象是守护自己的日志/告警文件，而不是应用日志。它是 E-09（先查内存）→ E-18（按阈值设门禁）→ E-25（临时白名单豁免）第三次同类出现后的提升：前两次都在"被动适应守护"，白名单豁免才把它变成可协商的组件（2026-10-04 新增）。

进化协议（保持资产活性的规则）

追加新经验（项目"结束"时执行）：

1. 按 lesson card 模板写入对应领域文档（不知道归哪类就放 references/misc.md 并新建）：

   ### L-<序号> <一句话标题>
   - 场景：<标签，如 #LLM #异步>
   - 问题：<现象>
   - 根因：<为什么>
   - 方案：<怎么修，保留关键代码/命令>
   - 反模式：<千万别这样做>
   - 溯源：<原始文档路径或会话日期>

2. 如果新经验验证/推翻了某条元原则，直接修改 SKILL.md 的原则条目并在末尾注明修订日期。
3. 同一问题第三次出现时，提升为元原则。
4. 收尾校验：同步 SKILL.md 中的条数声明，跑 node scripts/check.js——编号 / 索引 / 计数的 error 必须清零（历史条目缺字段的 warning 可暂留）。

维护规则：

• 每条经验必须带溯源，不可凭空写。
• 蒸馏时删业务细节，留通用规律；代码片段只留骨架。
• 元原则控制在 15 条以内，超了就合并。

修订记录：2026-09-24 collab-testing.md 增补 C-04（环境自适应测试必须两条分支都过：测试按 web/dist 存在与否选入口 → 本地有 dist 永远走 run.py、CI 没有则走 server.py，而启动参数是照 run.py 写死的 → argparse exit(2) 让「进程活着」必红，CI 四个 job 全红、发布零资产；修法 = 参数按入口构造 + 打印 exit code + 闸门放进与真实交付入口同条件的 job）、deploy-env.md 增补 E-16（发版卫生：git grep 先枚举版本号同步点 / 零资产的失败 tag 可安全删重建 / 查资产别看 /releases/tags 那个会把 assets 报 0 的端点，要查 /releases/<id>/assets）、E-17（验收的「采样时机」假红：设备是异步选定的，服务一响应就采样会采到中间态 → 轮询到落定，并用 packets 增长交叉验证）、frontend-backend.md 增补 F-11（React 18 批处理：await 后子组件 setResult 与父组件 setState 同批渲染 → 条件渲染的子组件当场卸载、成功提示从未上屏；修法 = 先显示提示再刷新，或把提示上提到不会被卸载的父级）、misc.md 增补 M-27（第三方内核依赖「能自动到什么程度」由许可决定：不得再分发 / 限 N 台 / 静默安装属商业版 → 只能做半自动引导 + 直链，且不为查版本主动出站）、M-28（多会话共享当日日志会被整篇重写吞掉记录 → 追加用文件末尾锚点、权威记录落仓库）。本批再次验证元原则 13（v1.0.3 的验收全打在「下载下来的发布资产」上，两个包逐个闭环）与元原则 11（Get-Content 对无 BOM UTF-8 中文文件给出错误行数、glob 写法导致搜索零命中，都与直接整读冲突 —— 以直接读为准）。来源项目：flowwatch v1.0.2 → v1.0.3（首启引导 + 免重启重试 + Npcap 许可说明），2026-09-23/24 会话。

修订记录：2026-09-24（晚）misc.md 增补 M-29（定位器逐项读文本会累加 30 s 超时 → 撞满执行器硬限后任务与标签页一起丢；正解 = 一次 evaluateAll 批量读 + 每步显式小超时 + 长流程拆段 + 事后深链重开）、M-30（B 站投稿/字幕自动化的判据与走位，补 M-13：判据优先级 结构 > 数值 > 文案 —— input.files.length / 进度条 class、封面 canvas 均值变化、线上 og:image 与 view 接口复核；字幕编辑器可深链直开；列表滞后 12 分钟别当失败）、M-31（程序化宣传片：幕边界必须由句子区间单一来源生成、且幕与句的 key 前缀不可复用 —— 撞名会让整片黑屏；交付前四项 QC = 对齐偏移 / 整片解码 / 帧数 == 时长 × fps / 交付形态抓回比对）、deploy-env.md 增补 E-18（内存守护边缘跑长任务：按守护阈值设门禁 + 产物可续跑 + 压进程内存，承接 E-09）。本批再次验证元原则 11（"上传区仍在""上传中"这类文案/可见性读数会误判，须用结构或数值读数交叉验证）与元原则 13（封面与成片都以交付形态验收：线上图抓回与设计稿同图、帧数对齐），并再次验证 L-08（精确编排类视频直接程序化，AI 生成影像只作素材补位）。来源项目：memfuse 宣传片（63.85 s 逐帧渲染 + 双比例封面 + B 站投稿 BV17Haw6UEKU、字幕 offset 0.090 s），2026-09-24 会话。 修订记录：2026-09-26 deploy-env.md 增补 E-19（发布资产在受限网络下传不上去：uploads.github.com / codeload.github.com 同被 hosts 钉住 + DoH 被丢包拿不到真实 IP → 把“构建 + 挂载”搬到 runner，workflow_dispatch 还能给老 tag 补挂资产，不必删 tag 重建）、E-20（Windows 交付的“双击可用”：.cmd 启动器恒定带 -ExecutionPolicy Bypass 一次绕过“下载标记 + 执行策略”两道闸、无参数只打印用法、goto 结构且别在括号块里 echo 含 ( 的文本、.cmd 必须 CRLF）；misc.md 增补 M-32（ConvertFrom-Json 吃不了 curl 的多行 stdout / "$v:" 是盘符变量陷阱 / git push 进度走 stderr 被渲染成假报错）、M-33（会“误伤用户”的自动化：默认向后兼容 + 风险能力显式开关 + 清单/演练命令 + 配置热加载）；collab-testing.md 增补 C-05（杀伤类工具的端到端验证：受控沙包“拒绝关闭” + 用全量白名单把它变成唯一候选 + A/B 断言两条分支）。本批再次验证元原则 11（stderr 红字 ≠ 失败，判定看 [new branch] + ls-remote 复核；/releases/tags/<tag> 的 assets 恒为 0 的缓存坑）与元原则 13，并据后者补一条边界（取不回交付物时的降级验收与显式声明）。来源项目：memfuse 开源仓（窗口保护 + 白名单热加载分支、memfuse.cmd 启动器、v1.0.0/v1.1.0 双 Release），2026-09-23 ~ 09-26 跨日会话。 修订记录：2026-09-26（晚）新增元原则 14「共享可写文件只追加、不重写」——同日两次实测复发：① usercontext/2026-09-24.md 被宣传片会话整篇重写，吞掉了 memory-guard 的"原版冻结/走分支"决策；② 当日流水 .codebuddy/memory/2026-09-26.md 被 RAG 会话整篇重写，吞掉了本会话的收尾与 PR 合并记录（两处都靠"读尾部 + 追加"补齐）。这是 M-28「多会话共享当日日志」同类问题第三次出现，按"第三次即提升"规则入元原则（现共 14 条）。同时再次验证元原则 11：GET /pulls/1 首次返回 mergeable= 空值（异步计算中），若把空值当"可合并"就会撞 405——判据必须是明确的 true，守卫因此正确拦下一次误合。来源项目：memfuse PR #1 合并 + 记忆文件并发覆盖（2026-09-26）。 修订记录：2026-09-28 新建 references/eval-method.md（V-01V-05：基准日锚定 / 两边跑满同一查询集 / n 小时报 CI / 数字带数据版本 / 增益在补偿什么），路由表与索引同步 —— 这批复盘来自一次 RAG 检索 + 生成层评测，5 条全是"指标算得出来但结论站不住"的坑，与 rag.md（评测对象怎么搭）互补。本批另增 deploy-env.md E-21（增量部署两规矩：先量代码差集，再让"验证通过才重启" —— 实测"只推 4 个文件"让线上服务宕机，根因是代码静默分叉 10 天 + 把上传与重启做成连续动作；门禁位置必须在停服之后、启动之前）、rag.md R-14（分块策略改版后的索引重建：存量因幂等键 _chunk_0 永不自更新、块数变少留孤儿块、原文只能从 chunk 去重叠还原 → 重建前必须量化 4 条前提，其中"疑似有重叠但边界错位必须为 0"是唯一会重复正文的形态；⚠️ 分块器改版后**"新旧形态混杂"的库不可重建**，会让标题串进正文；重建后必查时间戳字段类型，字符串会让时间窗静默匹配不到）、misc.md M-34（别人给的预览/沙箱 URL 可能是旧快照 → 先做"是否当前源码"的归属判据，本次靠 /projects 里真实项目数为 0 识破）、M-35（MDX 裸 <tag> 被当 JSX 会打断整站构建 / 行尾必须 LF / 内容层工具只写不删留孤儿条目 / eol=lf 与 core.autocrlf 组合制造的 git 幽灵 M）。本批再次验证元原则 11（三处：预览 URL 的归属判据；"54.7% 相邻块匹配不上"看似异常，与一份已验证语料逐位对照后判定为正常；单次测量的增益与差值都可能误导）与元原则 13（E-21 的门禁正是把验收打在"真实启动形态"上，而非"文件传上去了"）。结构维护：标题 ## 十三条元原则 与实际 14 条不符，已订正为「十四条」。⚠️ 新增候选元原则（尚未满三次，先记不升级）："不可逆操作前先量化其依赖的前提，并做双份备份" —— 本次为第 1 次成型实例（语料重建前量化 4 条前提 + 服务器侧整目录副本 + 打包异地下载），后续同类再出现两次即可提升。来源项目：VDB-News 分块层重构 + 线上埋点部署（含一次真实宕机与回滚）+ 线上语料重建（2026-09-28 会话）。 修订记录：2026-09-29 新增 scripts/check.js（零依赖一致性校验：前缀归属 / 编号唯一 / 索引↔正文双向一致 / 顺序递增 / 卡片六字段 / SKILL.md 计数 / 交叉引用死链；机械问题报 error，历史条目缺字段报 warning），并纳入进化协议第 4 步作收尾门禁。首跑即抓出三类存量缺陷并修复：misc.md 索引表 M-23 因 2026-09-23 重编号残留排在 M-26 之后（正文一直是正确序）、SKILL.md 多处计数漂移（misc.md 26→35、deploy-env.md 15→21、rag.md 14→15——后者属新增 R-15 未同步计数）。⚠️ 边界：并行会话同时选号只能事后发现，卡片内容质量仍归人工审查——「编号纪律」原文不变，脚本只是事后闸门。 修订记录：2026-09-29（TechLog 站内改版）frontend-backend.md 增补 F-12~F-15：F-12 Tailwind 变体类（dark:prose-invert）不在 classList 里 → 按类名写的覆盖规则是静默死代码（无报错、无警告），覆写要写 .dark .prose；F-13 内联元素的负 margin 会减少内联前进量 → 给标题前置图标加大负 margin 会把标题文字整体带偏、压住刚生成的编号（现象像"CSS 计数器没生效"），正解 = margin ≈ 图标自身宽度；F-14 给已发布内容加自动编号不要改写标题文本（会同时牵动锚点 id 与目录两处权威源），用 CSS 计数器 + 运行时按同一规则算目录；F-15 动效先算「浏览器覆盖 × 交互频率」再想 reduced-motion 兜底（View Transitions 只有 Chrome/Edge；全局 scroll-smooth 浏览器不会因 reduced-motion 自动关掉）。misc.md 增补 M-36（npm script 里的 $VAR 在 Windows cmd 下不展开 → Unbound variable，别误判成依赖损坏，直跑底层命令绕过）。本批再次验证元原则 11（"伪元素没渲染"其实是文字被负 margin 带偏——只有量 getComputedStyle(el,'::before').width 才看破，光看 content 会得到未解析值）与元原则 13（线上以交付形态复核：/about.html 的 <title>、h1、图片 /techlog 前缀都验过）。来源项目：TechLog 站内三项改版 + 关于页收口（2026-09-29 会话）。 修订记录：2026-09-30 deploy-env.md 增补 E-23（前端构建被环境变量静默改写 API 基址：VITE_API_BASE=/ 残留 → replace(/\/+$/,'') 得空串 → 全打静态服务器 → 整页「连接中断」；修法 = 构建前清环境 + 构建后自查 dist 含预期 API 主机，诊断口诀"页面全空先查 dist 里的 API 基址"）、E-24（手动起的常驻服务不落输出 → 崩溃后死因不可考；用 cmd /c "... >> log 2>&1" 包装落盘）；misc.md 增补 M-38（会话"服务化"后 stdout 被吞 → 结果写文件 + read_file 读；复杂 python 一律临时 .py 脚本，别硬凑 -c 单行）、M-39（探测本机服务只认状态码会被"别的进程占同端口"骗过：校验响应体特征，不只看 200；服务发现 = 按序探测 + 严格校验 + 失败下跳）；upstream-reuse.md 增补 U-04（对接第三方插件系统：协议以官方插件源码为准，别信文档概要——本次事件载荷形态猜错导致按钮无响应，对照官方源码十行定死）。本批再次验证元原则 11（三处：页面全空的三个直觉全指向"不可能"、端口占用被猜成"僵尸进程"、服务死因无日志只能靠 explorer 时间反推——均以第二种手段才定论）与元原则 13（构建成功 ≠ 口径正确，验收要打在"产物里的实际字符串"上）。来源项目：flowwatch（4173 页面空白修复 + 8788 静默死亡重启 + Catrace 告警集成收尾），2026-09-19 ~ 09-30 会话。

修订记录：2026-09-29（晚·第二批，TechLog 文章页改版收尾）frontend-backend.md 增补 F-16（中文内容站的阅读时长口径：构建期英文库 reading-time + 渲染期自写 lib/wordCount → 同一事实两个数字、中英混杂；修法 = 构建期与渲染期共用同一实现）、deploy-env.md 增补 E-22（第三方嵌入"代码里配了"≠线上可用：giscus 缺 NEXT_PUBLIC_GISCUS_* → 线上渲染 repo=undefined 的坏 iframe，而构建/部署/页面 200 全绿；验收要打在线上 DOM + console，不用的功能显式下线并留恢复说明）、upstream-reuse.md 增补 U-03（参考产品的"效果呈现"≠"产出机制"：Showcase 是逐篇 AI 定制产物而非可套用主题 → 复用目标从"复制效果"改为"借鉴方法论"）、misc.md 增补 M-37（一条命令内 Set-Location 不保证后续相对路径的解析基准 → 跨工作区一律绝对路径）。本批再次验证元原则 13（E-22：构建与部署全绿，坏的是线上页面里的第三方区块）与元原则 11（M-37：命令内相对路径的解析基准与直觉不符，须打印实际位置二次确认）。来源项目：TechLog 文章页改版（2026-09-28~29 会话）。

领域文档索引

• references/llm-app.md — LLM 应用开发（15 条）
• references/frontend-backend.md — 前后端异步与状态、前端动画（17 条）
• references/data-db.md — 数据库与迁移（3 条）
• references/upstream-reuse.md — 上游代码复用（4 条）
• references/deploy-env.md — 部署与环境（26 条）
• references/collab-testing.md — 开源协作与测试（5 条）
• references/misc.md — 工具使用与排查方法（57 条）
• references/rag.md — RAG 系统：向量库/检索/报告生成/知识库（15 条）
• references/eval-method.md — 评测方法论：指标可信度/可复现性/对照设计（5 条）

修订记录：2026-09-20 新建 references/rag.md（R-01R-13：入库幂等键、检索归属建模、冷启动长窗、生成物幂等、幻觉溯源校验、费用闸门、向量库统计缓存、管道埋点、报告进化对比、知识资产视图、联网搜索主动发现、"追问"闭环、宣称口径红线），路由表与索引同步。R-02 是元原则 6（半截路）在检索过滤上的实例；R-11 印证元原则 11（"静默返回空"是比异常更隐蔽的单读数陷阱）。 来源项目：vectordb-news（8 步管道 / Agent 主动搜索 / 知识资产库 / 首报快报 / 进化感知，2026-09-1417 会话）。 修订记录：2026-09-16 misc.md 增补 M-09~M-12（平台生成物开源前清洗的 BOM/行尾/引用误删三坑、本地端口验证的"假成功/假失败"、Playwright 录屏做 GIF 的四个坑、本环境 safe-delete 拦截 rmtree 与 pytest sys.path 两个固定约束）。本批同时再次验证元原则 11——BOM 导致的锚点失配、视频时间轴的常量偏移，都是"单一工具读数/单一推断不足以定论，必须用第二种手段交叉验证"的实例。来源项目：portwatch 开源 + 作品集接入。 修订记录：2026-09-24 deploy-env.md 增补 E-15（官方安装器的"安装目录守卫"是白名单制——安装目录下任何非白名单目录都算"用户项目"，而程序自己每次启动 23 s 后会把 deviceInfo.json 写进安装目录的 .marscode\ → 自己拦自己；过关姿势 = 不重启应用、在当前窗口内清掉该目录后立刻触发更新，命中"守卫只在 doCheckForUpdates() 入口短路、doQuitAndInstall() 不含守卫"这条实现细节；配套脚本 C:\scripts\cb_update_unblock.ps1）、misc.md 增补 M-26（从 1.8 MB 压缩单行产物里定位逻辑：IndexOf + Substring 按字符窗口截取后落盘再读，别用"带上下文"的按行检索——会把整行上百万字符打进输出、连续两次拿不到结果；附带 powershell -Command 里 $ 被外层 shell 提前展开的传参坑）。本批再次验证元原则 11——"弹窗说被拦"≠"此刻仍被拦"：日志比对显示 08:15 / 08:35 两次确实被守卫拦下，而清理后 08:41 那次检查已通过（无 blocked by ... guard 行），只看弹窗会把"已通"误判成"仍拦"。来源项目：CodeBuddy CN 1.106.1 升级受阻排障（2026-09-23/24 跨日会话）。 修订记录：2026-09-23 misc.md 增补 M-21（微信公众平台自动化发布的三个连环坑：insertHTML 被降级 / 标题框设值不生效 / 必须走"页面内 paste 事件 + 平台原生 Markdown 转换"）、M-22（CRLF 行尾让 frontmatter 报"假 YAML 错"——报错列号随内容长度移动、极具迷惑性，靠字节级对比定位）、M-23（进程"杀-重生"循环：先查清 supervisor 再决定杀叶/杀根/跳过）；deploy-env.md 增补 E-13（Windows 计划任务守护自愈配方：RepetitionDuration 省略=无限重复、双触发器 + IgnoreNew + 注册后校验）。本批第三次验证元原则 11——"报错说第 6 行第 138 列"实为行尾 \r（白改两版文案）、"封面设置失败"实为检查了错误的 DOM 位置（截图即真相）。同日结构维护：修复与并行会话的编号撞车（本批原编 M-13/14/15、E-09 → 重编号为 M-21/22/23、E-13；备份移入 _backup/，不留 references/），给全部 8 个 references 文件生成「条目索引」表，SKILL.md 使用方式改为"按索引检索、勿整读"。来源项目：memory-guard / TechLog / 公众号发布。 修订记录：2026-09-23（晚）deploy-env.md 增补 E-14（SSH 交互式会话老掉线：客户端 ServerAliveInterval/ServerAliveCountMax 保活 + tmux 兜底；服务端 ClientAliveInterval=0 不代表安全，锅多在中间 NAT/睡眠）、E-13 补第三个坑（Register-ScheduledTask 带 -Principal 在非提权会话直接 Access is denied.，省掉即成功）；misc.md 增补 M-24（PowerShell 5.1 的 Get-Process 没有 CommandLine 属性 → 按命令行筛进程必须走 Get-CimInstance Win32_Process；$null -match 静默为 $false，会让守护脚本"每轮都判进程不存在"反而制造堆积）、M-25（云安全组是否放行：从外部探测，refused = 已放行 / timeout = 被丢包，比回控制台翻规则快）。本批再次验证元原则 11（同日第二批）——"属性不存在导致过滤静默不命中"与"ss 显示在听但公网超时"都是单读数/单推断误导，须换第二种手段（CIM 复查命中集、换端口实测）交叉验证。来源项目：京东云 111.228.0.160 交互式 SSH 保活 + 反向隧道 + C:\scripts\ssh_heartbeat.ps1（2026-09-23 会话）。 修订记录：2026-09-10 新增元原则 11（工具读数二次确认）；新建 references/misc.md；deploy-env.md 增补 E-05 同名 editable 包污染、E-06 pytest 误收集、E-07 控制台假性乱码。来源项目：AI-driven-viral-content-analysis-system 接手过程。 修订记录：2026-09-11 llm-app.md 增补 L-08 AI 生视频精确编排不可控→程序化兜底；frontend-backend.md 增补 F-07F-10（rAF 双调度、smoothDamp 钳制外置、MutationObserver 唤醒、CSS 3D 残留层级失效）；misc.md 增补 M-03 Edit 未持久化 grep 复核、M-04 headless rAF 节流失真。来源项目：vectordb-news Dify 头像注视跟随。 修订记录：2026-09-11 misc.md 增补 M-05 ffmpeg MP4 muxer 静默丢自定义 metadata（use_metadata_tags+ffprobe 复核）、M-06 Tabbit CLI Windows 兼容模式调用法；M-02 补充本地 exe 双引号 JSON 参数断裂变体（Python subprocess 列表传参）；deploy-env.md 增补 E-08 本地 QA 服务器根目录对齐生产 URL 前缀；llm-app.md 增补 L-09 豆包 vid 溯源取无水印原片+保留 AIGC 标签。来源项目：vectordb-news 豆包水印去除。 修订记录：2026-09-12 misc.md 增补 M-08 不克隆仓库提取开源项目协议知识（GitHub API 列树→raw 读单文件→commits?path 追变更史，回馈上游用 issue）；llm-app.md L-09 补接口失效更新路径引用 M-08 及图片链路未实测注记。来源项目：vectordb-news 豆包水印去除会话复盘。

修订记录：2026-10-01 llm-app.md 增补 L-13~L-15（L-13 图生视频"锁不锁首帧"由协议决定：旧接口 image_url 只当宽松参考 → 三段画面全漂移（办公室变书房/森林）+ 幻觉出英文字幕；2.5 系列 mode:"keyframe" + first_frame 才锁首帧，字段名不同、传 image_url 直接 400。L-14 TTS 偶发"长尾伪影"：7 字句生成成 12 s 且不是静音（silencedetect 抓不到，按静音裁剪会切掉真台词）→ 正解 = 时长合理性上限（字数 × 0.42 s ÷ 语速 + 1 s）+ 本地 ASR 内容闸门（命中率 ≥ 60%、多出字数 ≤ 3）+ 只做尾部收口 + 最多重试 4 次取最优。L-15 AIGC 音色"像不像角色"只能人耳验收：自动指标全绿的句子被用户全否 → 候选制 + 两阶段交付：每句出 N 条候选（dub.py --audition N --lines ...）→ 用户按"句号-编号"点单 → 选定后才合成画面）；misc.md 增补 M-40（cmd 下含 %xx% 的 URL 被当 %VAR% 展开 → curl / Invoke-WebRequest 齐报"文件名、目录名或卷标语法不正确"，把排查引向"中文文件名/编码"，正解 = 把带百分号的下载写进脚本文件）。本批再次验证元原则 11（自动指标是"单读数"：ASR 命中率 100% 的 take 仍被判"不像角色"，须换人耳这第二种手段；含 % 命令行的报错文本把方向带偏）与元原则 13（验收打在成片形态：逐帧抽检 + 成片音轨 ASR 复核），并再次印证 L-08（AI 生视频只出素材，最终成片由 ffmpeg 程序化合成）。⚠️ 新增候选元原则（尚未满三次，先记不升级）："感知类质量（像不像/好不好听/好不好看）只能由人判定，自动指标只配做废片剔除" —— 本次为第 1 次成型实例。来源项目：bear-boss《熊出没》二创（三镜头 keyframe 重制 + 两句改词 + Moss 配音 + 10 s 定稿），2026-09-29 ~ 10-01 会话。 修订记录：2026-10-02 misc.md 增补 M-41（验证"技能/知识库到底有没有用"用三臂对照——without 先验基线 / inject 静态注入 reference 全文 / retrieve 真 agentic 自主走"索引→读 references"；并点出 agentic 执行器默认只注册 load_skill、测"可检索"须补读 references 工具，否则把"读不到"误判成"库无用"）、M-42（"按索引检索、勿整读"原则必须在 read 工具层落实：references 大文件整读会顶爆 token 预算且检索发散，工具须支持"按编号精确读单条"）。本批首次用 R1 三臂量化验证本库效用：inject 6/6（知识正确）、without 1/6（先验答不出私有经验）、retrieve 6/6（5/6 自主走通检索链路），证实本库"可检索"形态可被 agent 自主消费，非形式主义。来源项目：agent-skill-framework R1 验证实验（复制 dev-lessons 到 skills/ 隔离、继承 AgenticExecutor 加 read_skill_ref 工具实现三臂），2026-10-02 会话。 修订记录：2026-09-11 llm-app.md 增补 L-10 提示词必须声明完整 schema+受控标签（印证并扩充元原则 1）、L-11 长输出撞网关 524 须拆阶段、L-12 模型字段类型漂移须统一 normalize；misc.md 增补 M-07 幂等后处理脚本优于全量重跑。来源项目：AI-driven-viral-content-analysis-system 内容分析与短视频脚本生成。 修订记录：2026-09-21 misc.md 增补 M-13M-15（真实浏览器执行平台写操作的七条规矩 / 视频时间轴"收紧"的工程化与交付前 QC / 管道截断看进度会掐掉上游进程）、deploy-env.md 增补 E-09（渲染等长任务前先查可用内存 —— 本机守护会静默杀进程）；新增元原则 12「对外宣称必须可验证、且三处同源」 —— 它是 R-13「落地页宣称必须逐项对照实现」的同类问题第三次出现（①落地页 L2"四层记忆"无实现 ②宣传草稿 3 条不成立 ③视频卡片写 /api/assistant/meta 而真实端点是 /api/assistant/status，且错路径同时躺在卡片源码里），按"同一问题第三次出现即提升"的规则入库。来源项目：flowwatch 演示片（跳剪收紧 170.81→154.24 s、Tabbit CLI 投稿、B 站封面双比例返工、工具清单口径修正与 README 同步，2026-09-21 会话）。 修订记录：2026-09-21（晚）deploy-env.md 增补 E-10E-12（打 exe 的构建环境与体积、冻结后的可写数据路径模型、发布流水线自带把关 + 资产卫生 + 以下载物为准的验收）、misc.md 增补 M-16~M-18（工作流 YAML 的 name: 冒号坑、工作区里"非本次改动"的破损编辑要先分离归属、清理类操作写成可复跑脚本）；新增元原则 13「交付形态即验收对象」（E-08 / M-10 / 本次为第三次同类出现）。来源项目：flowwatch v1.0.1 —— 一键包（run.py 单端口 + start.cmd）与免 Python exe（PyInstaller onedir，干净 venv 33 MB vs conda 基环境 207 MB）、datadir.py 统一可写数据路径、release.yml 三 job 发版，线上资产实测通过（2026-09-21 会话）。

修订记录：2026-10-04 frontend-backend.md 增补 F-17（静态导出站（basePath + .html）里别用 usePathname() 推导站内链接：客户端返回真实 URL /techlog/blog.html、服务端返回路由路径 /blog，.html 剥不掉 → 生成 blog.html/page/2.html → 点「下一页」必 404；SSR/CSR 不一致时 React 19 保留服务端 DOM、console 也无 hydration 报错，只有点击才炸，判据是点击瞬间的 RSC 请求 URL。修法 = 链接根路径与激活态显式 prop 传入；验证必须在"静态导出 + BASE_PATH + 前缀目录托管"形态下点一遍，dev 模式复现不了）、deploy-env.md 增补 E-25（内存守护会杀掉 next build：日志无 error / 无栈 / 进程消失 / avail 回升；取证只能看守护自己的日志（按"守护启动日"找文件名）+ 桌面 memory-guard-alert.txt；解法 = protect-list.txt 热加载白名单临时豁免（"顺位下一个"的带窗应用也要保护）+ --max-old-space-size 压峰值 + 用完即恢复。同族 E-09 / E-18）、misc.md 增补 M-43（稍复杂的命令一律落脚本文件再执行：内联反引号转义 / %VAR% 会让整条命令被当 cmd 解析，报 '$x' 不是内部或外部命令；机制未定论但规避姿势稳定有效。同族 M-26 / M-38 / M-40）。新增元原则 15「长任务先读系统守护的规则」——E-09 → E-18 → E-25 第三次同类出现后按"第三次即提升"入原则（前两次都在"被动适应守护"，白名单豁免才是可协商姿势），标题同步改为「十五条元原则」。结构维护：misc.md 索引表补齐历史遗漏的 M-41 / M-42 两行（2026-10-02 会话只加正文未同步索引）。本批再次验证元原则 13（修复必须在"静态导出 + basePath 前缀托管"的交付形态上点击验证，dev 与 SSR 输出都不作数）与元原则 11（"构建静默死亡"单看应用日志会误判为 Webpack/Node 的 bug，须以守护日志/桌面告警这第二种手段定论）。来源项目：TechLog 分页 404 修复（提交 aa55b72，已上线并线上点击验证），2026-10-03 ~ 10-04 会话。

修订记录：2026-10-08 misc.md 增补 M-44（B站新版「封面制作」弹窗：4:3/16:9 是独立面板，file input 随激活面板动态变化——先点槽位标题激活（判据=底部预览标签变化）再重新查询 input 并按容器坐标核对归属；承接 M-30 旧版判据、覆盖新版差异）、M-45（B站评论区是 web components：穿透定位须手动 shadowRoot、操作栏按钮身份读 BILI-ICON 的 icon 属性、「…」是 hover 显现型（静态 0×0）须 DOM click、菜单项叫「设为置顶」、点菜单项用物理坐标、新知识获取用 page.on("request"/"response") 抓真实调用（拿到 /x/v2/reply/top + rpid 参数——手工调用漏 rpid 即报 -400）、验收看页面「置顶」徽标——审核中稿件接口 data.top 不返回别当失败）、M-46（PIL 缺字形静默画方框：consola 无中文、雅黑缺 ✓；渲染脚本内置 --preview 抽帧过目，避免 3540 帧全量重跑）。本批再次验证元原则 11（三处：①「菜单关闭」≠ 操作成功——只有抓到响应 code:0 才定论；②exact:true 匹配「置顶」漏掉「设为置顶」；③静态可见性读数对 hover 显现型控件失效）与元原则 13（置顶验收打在页面徽标这一用户可见形态上）。来源项目：gh-fast-download 盘点篇（竞品盘点视频制作 + B站投稿 BV1nRHm64ExU + 评论区放演示文档链接并置顶），2026-10-07 ~ 10-08 会话。

修订记录：2026-10-09 misc.md 增补 M-47~M-51。M-47 抓不到屏的五个"假 API 失败"：五种抓屏方式各有各的报错形态（screen grab failed / 全黑图 / handle is invalid / 图缺元素 / 文件不生成），根因常是窗口比屏幕大，而屏幕尺寸还被 Win32_VideoController 骗成 1360（真值以 GetSystemMetrics 为准 = 2880×1800）；可靠姿势 = ffmpeg gdigrab 录屏抽帧、抓前把窗口搬进屏幕，并记住 PrintWindow 拍不到自绘子窗口（"抓不到"≠"屏幕上没有"）。M-48 ctypes 不声明 argtypes 时句柄/指针被静默截成 32 位 —— FindWindowW 返回 0 / 点击无反应 / HWND_TOPMOST 失效三处同病。M-49 SS_OWNERDRAW 自绘卡片四条规矩：子窗口 + 父窗口 WM_DRAWITEM、位置在显示前现算（别依赖 layout() 时机，它在 WM_CREATE 时 DPI 还没到手）、多行文案一次 DrawTextW、windows-sys 缺的 API 用 GetProcAddress 动态取。M-50 ffmpeg 合成 GIF 不显式传 -framerate 会悄悄加速 2.08 倍，且纯键盘场景因轨迹为空走了另一条渲染路径 → 同片各段速度不一致；附"整数遍吸附用 floor"与"GIF 延迟 10ms 量化"。M-51 跟外部系统要列表位置用快照 diff 而非序号推算（本机 91 个桌面图标、一屏只放 36 个，推算必错），且外部系统刷新有延迟必须重试；反馈分两次更新（先立即、后补精确）。本批强验证元原则 11（屏幕尺寸被单一工具误导、五种抓屏失败全被当成"环境不支持"、PrintWindow 没拍到 ≠ 屏幕上没有）与元原则 13（验收最终打在"用户看到的画面"上），并再次验证 M-10 同族（抓屏的"假失败"与"假成功"）。来源项目：ExeTrace native 版「钉桌面强反馈 + 桌面方位八区」（浮层卡片自绘 + 跨进程只读桌面图标坐标）与短片 v3 的 GIF 帧率修复，2026-10-09 会话。

修订记录：2026-10-14 deploy-env.md 增补 E-26（Android APK 发版前必查 launchable-activity：launcher category 常量误写成 android.intent.action.LAUNCHER → 安装成功但桌面无入口；发版闸门 = aapt dump badging 必须有 launchable-activity 行，设备侧用 cmd package query-activities … LAUNCHER 闭环，疑义时解开 AXML 按 UTF-16LE 搜字符串池仲裁；目检 Manifest 常量不可信——aapt2 xmltree 与编辑器会把错误值宽容"校正显示"）。本批再次验证元原则 11（宽容型渲染工具的"假正确"读数：「打印正确」≠「字节正确」≠「系统语义正确」，必须换与系统同规则的严格匹配型工具二次确认）与元原则 13（构建成功 + 能安装 + 验过签名 ≠ 交付物可用，验收要打在系统真实识别的入口契约上；v1.0 发版时恰好漏了真机/模拟器验证）。来源项目：TechLog 薄壳 APK v1.0 桌面无图标事故 → v1.0.1 修复（提交 a3911f1，模拟器旧包复现/新包转好 + 线上 SHA256 一致），2026-10-14 会话。