First
用探索收获新知
这里是 code 栏目——一组技术探索笔记。记录对开源库、框架、协议的理解与落地：不追求面面俱到的文档复述，而是把"这个东西是什么、怎么用、坑在哪"用自己能看懂的笔记形式沉淀下来。
这个栏目记什么
- 库 / 框架解读：qiankun、react-virtuoso、nanostores、async-validator、scroll-lock、vgpu 等，写清用法、原理与最佳实践；
- 协议与方案：MCP、微前端、虚拟列表、WebRTC 101 系列、部署方案等横向主题；
- 场景化示例：每个项目尽量配"实战场景"，把笔记变成可复用的速查。
子项目导航
| 项目 | 一句话简介 | 首篇 |
|---|---|---|
| qiankun | 微前端框架：主/子应用接入、沙箱、Nginx 统一托管部署 | 入门 |
| react-virtuoso | 虚拟列表库：动态高度、表格/网格/分组/聊天场景 | 入门 |
| MCP | Model Context Protocol：AI 应用连接工具的开放协议 | 入门 |
| nanostores | 轻量状态管理器（原子存储） | guide |
| async-validator | 异步校验库（schema 校验） | guide |
| zod | TypeScript 优先的 schema 库（v4，5 篇）：入门 / MCP 与 Zod / 类型推导剖析（v3 vs v4 类型性能实测）/ 源码剖析（_zod 内部与 parse 管线）/ Mini·Standard Schema·JSON Schema·zod/compile | 入门 |
| scroll-lock | 页面滚动锁定库 | README |
| antd-mobile | 移动端组件库通用设计规范 | 通用 |
| gods-pen | 在线代码编辑器探索 | 文档仓库 |
| Perry 的 101 | 跨端框架对比（Electron / Flutter / Tauri / RN / Qt 等）选型速查 | 入门 |
| hooks | React Hooks 用法合集（useActionState 等） | useActionState |
| InkOS | 故事创作 AI Agent 4 篇：入门/深度体验（CLI 全命令与流水线拆解）/架构拆解（agent 分类、状态机、FTS5 检索、37 维审计、原子提交）/为什么不用 LangGraph（零依赖事实 + 四件套对照：reducer·图·checkpointer·interrupt 各拿什么替的）；pi-agent harness + 输入治理 | 入门 |
| pi | TS agent 运行时（Mario Zechner）：pi-ai 统一几十家 LLM 接入 + pi-agent-core 的 Agent harness（工具循环/事件流/会话），InkOS 的底层 | 入门 |
| frontend-agent | 用前端技术栈写 Agent（纯 Node/TS，真实模型实测 3 篇）：循环/运行时 → 简单工具调用 Agent → 复杂多步 Agent（文件落盘、以结果为准） | 入门 |
| langchain-langgraph | LangChain.js + LangGraph.js 入门 6 篇（真实模型实测）：消息/提示/LCEL/结构化输出 → 状态图·条件边·记忆 → ReAct Agent 实战 → LangGraph 图解（mermaid + 逐步执行轨迹）→ 可观测性（Langfuse 与 LangSmith：legacy→OTel 迁移、两代上报端点与格式、不 flush 就丢 trace 的实测） | 入门 |
| deepagents | LangChain Deep Agents 入门（1.13.4 实测）：一行创建「会规划/读写文件/派子任务」的 Agent——中间件与后端体系、真实工具调用时间线、产物落盘验证与坑 | 入门 |
| cmux | 终端复用器 + 面向 Agent 的「资源客户端」（Rust/libghostty，npm 分发）：会话/工作区/面板/终端/浏览器/agent 资源 + --json 编排 | 入门 |
| llm-format | 剖析 OpenAI / Anthropic 两家 chat 协议：请求/返回骨架逐字段拆解 + 一张表对照 + TS 类型与 zod 运行时校验 + 一发一收完整脚本（同 key 两端真实实测） | OpenAI 与 Anthropic 消息格式 |
| JSONL | 一行一个 JSON（JSON Lines / NDJSON）：与 JSON 数组·JSON-seq·CSV 的取舍、两份社区规范互相打架（扩展名/末行换行/空行）、七个坑（美化即破坏、末尾无换行会静默丢最后一行、BOM、截断尾行）+ 七组本机实测 | 入门 |
| Agent Skills | Agent 的可装载知识包（SKILL.md 一个文件夹）：渐进式披露三层（描述常驻 / 正文按需 / 脚本只执行不载入）+ 两家对照（Claude Code 的 1% 预算与按使用频率淘汰 vs OpenClaw 的加载期门控·声明式装依赖·ClawHub·命令直连绕模型）+ Skill 与 MCP·Hook 的三方分工 | 入门 |
| vgpu | WebGPU 库（Vercel Labs）：一套 API 跑浏览器/Node/mock；agent-first 工具链——随包 CLI 文档、官方 Skill、MCP、sha256 可信示例 | 入门 |
| WebRTC | 实时通信协议栈 101 系列：采集 → 信令/SDP → ICE/NAT 穿透 → SRTP 媒体平面 → DataChannel → 生产选型 | 入门 |
| spring | Spring & Spring Boot 入门系列：家族名份 + 用 Boot 4 写出第一个 REST 服务（分层/配置/打包/Actuator），Boot 藏起来的 Spring 内核待后续拆 | 入门 |
| nestjs | NestJS 入门指南（v12 实测）：Node 界的 Spring——Module/Controller/Provider 三件套 + 依赖注入 + 第一个 REST 接口 | 入门 |
| maven | Java 构建工具 Maven 入门（3.9.16 实测）：坐标/仓库/生命周期/pom.xml + thin vs fat jar；看得懂 Spring Boot 的 pom 与 mvnw | 入门 |
| gradle | Java 构建工具 Gradle 入门（8.14.5 实测）：任务图/增量 UP-TO-DATE/Wrapper/Kotlin DSL；与 Maven 对照、Spring Boot 也能用 | 入门 |
| pnpm monorepo | 用 pnpm 管多包仓库（11.26.0 实测）：pnpm-workspace.yaml + workspace:*、三层 node_modules 与硬链接佐证（链接数=4）、幽灵依赖实测 MODULE_NOT_FOUND、--filter 四种方向与 [since]、catalog 一处改版本、发布时 workspace:*→真实版本、版本管理交给 Changesets | 入门 |
| mysql | MySQL 8.4 入门到精通 8 篇（本机实测）：连接/CRUD/查询进阶/索引与 EXPLAIN/事务隔离/表设计/视图过程触发器/生产调优 | 入门 |
| sqlite | 高性能 SQLite 2 篇（Node 24 本机实测）：理论入门（写瓶颈=提交次数×fsync、实测 280 倍差距、WAL/synchronous/页缓存与索引）+ 驱动写法横向对比（node:sqlite / better-sqlite3 / @libsql/client / sql.js 同一任务四种写法、大整数静默丢精度等五个坑） | 入门 |
| milvus | Milvus 2 篇（2.5.10 单机实测）：入门（三种部署形态、核心概念、混合检索 BM25+稠密+RRF 含分数验算、六个必踩的坑）+ 企业级开发运维方案（索引召回-延迟曲线、过滤+ANN 的召回陷阱、flush≠就绪与流量闸门、一致性 40 倍延迟代价、组件与可观测性） | 入门 |
| pgvector | Postgres 的向量扩展 2 篇（17.11 + pgvector 0.8.6 实测）：入门（为什么选它：同事务/同 SQL/少运维一个组件、HNSW vs IVFFlat 与参数建议、★算子与 opclass 必须匹配 233ms vs 3.7ms、★★后过滤召回、量化 30 倍省内存、RRF 混合检索一条 SQL）+ 实战（拿真实 RAG 链路走一遍索引：裸 vector 列建不出普通索引、表达式索引库自己用不上、ALTER 补维度 33s、★规划器因 HNSW 代价估算不选索引、后过滤静默 0 条、查询期 GUC 怎么落地） | 入门 |
| neo4j | 图数据库 101 系列 6 篇（5.26.4 community 本机实测，一张 27 节点 / 44 关系的电商图贯穿全系列）：入门（从表到图、Community 四条边界、本机跑起来）+ 建模（电商 ER 图逐条翻译成属性图：中间表退化成边、属性 vs 关系、反模式）+ 写入与约束（MERGE 其实不是 upsert：从窄键走向宽键会建出重复节点、唯一约束才是并发下的原子性来源、CE 只支持 UNIQUENESS）+ 查询与路径（辟谣 5.x「关系默认可选」、变长与最短路径：两品牌间有 6 条并列最短路）+ 索引与执行计划（五种索引、NodeByLabelScan ≠ AllNodesScan、复合索引最左前缀、EXPLAIN/PROFILE 逐算子读）+ 聚合与边界（无 GROUP BY 的聚合、count(*) 3 vs count(p) 0、UNWIND、什么时候别用图） | 入门 |
| agent-engineering | Agent 工程化 4 篇（TS 完整实现 + 真实 demo 输出，Mock 无需 API Key）：总览（两道门槛/两条阶梯/五个控制杆）+ 结构化输出五层防护链（裸解析→JSON Mode→Zod→jsonrepair→错误分类+智能重试+DLQ）+ 弹性容错五层链（重试→熔断三态机→双向降级→舱壁，实测 L0 1/20 成功→L4 20/20）+ 五个控制杆与可观测性 | 总览 |
| Vue3 | Vue2→Vue3 系列（3.5.42，面向熟练 Vue2 开发）：快车道/Composition/迁移深水区 + 响应式原理、模板编译优化两篇深拆（实验实测）+ 组合式进阶×TS×工程化 + 用 customRef 实现防抖（track/trigger 分离、清理与 async 作用域两个静默坑、与 VueUse refDebounced 的诚实对比） | 入门 |
| Pinia | Vue 3 状态管理入门到精通 6 篇（pinia 4.0.3 实测）：入门/state·getters·actions/组合式与多 store/解构·订阅·插件/进阶工程/原理 | 入门 |
| Zustand | React 状态管理 101（5.0.15 + React 19.3.1 实测）：一套 store 两种用法——create 的 hook 与 selector 渲染边界（含 useShallow 无限循环实测、transient update），以及 createStore 的无框架订阅（原生 DOM、订阅语义、subscribeWithSelector、replace） | 入门 |
| Vitest | Vite 生态的测试运行器（5.0.2 本机实测，43 条测试 300ms）：以访问者模式实现的对象深遍历器为被测对象，讲清「过程型代码怎么测」——记录器访问者把过程变成可断言序列、不变量测试、spy 断言调用次序、环与 DAG 的区分、类型测试 --typecheck，外加一次变异测试回答「覆盖率 100% 到底保护了什么」（5 个变异里 4 个覆盖率仍是 100%） | 入门 |
| rag | RAG 专题 8 篇（真跑模型 + 公开失败案例核到一手来源）：入门（一条链路的五个环节与每环的坑）+ Rerank 深拆（5W1H：双塔 vs cross-encoder、实测分差中位 0.11 vs 4.86、阈值过滤两边都不成立、RRF 公式复算误差 1e-9 且 k 不影响顺序、STAR 复盘：top-1 没变但下游能力变了）+ 切片与向量化（按文档类型分：Markdown/PDF/表格/Word/代码；955 token 长块静默丢尾部、块越大命中越低 4/8→1/8、PDF 抽出的康熙部首字符致关键词 0 命中与 [UNK]、不同日期不同价格的句子相似度只差 0.0001）+ 检索能力边界（22 条 query × 四类问题 × 稠密/BM25/混合 RRF/加重排并排测：没有一种组合在各类上都最好、重排在条件否定型上帮倒忙、污染数据下 BM25 掉 3 个 top-1 而稠密不动、以及一个被消融实验否证的猜测）+ 失败案例拆解（6 个公开坏案例按固定模板填空：阈值语义反转致向量通道被静默关闭的 GitHub issue、召回不全 vs 排序不对的一刀切判别、U 型曲线、入库前的失败；并给模板补了两条——第 0 问「评测口径」和第 5 类根因「数据获取/入库层」）+ 向量相似度的原理（余弦值本身不含语义，是训练把「语义近」定义成了「余弦大」；分布式假设 → 损失函数 → 几何可行性的三层拆解）+ 架构演进之路（Naive → Advanced → Modular，三代划分逐字引自 RAG 综述）+ PDF 解析（抽取器默认参数就能打断检索通道：pdfplumber 默认 x_tolerance=3 丢词间空格致短语命中 2/8 与 0/8，而 pypdf 默认 8/8、改成 1 即恢复；双栏阅读顺序用「分栏裁剪」当标准答案，12 页量出 11.5% 相邻词对是伪相邻，并附第一版指标纯属噪声的翻车复盘；同页 MinerU 实测对照——表格重建正确、跨栏断词接回，但公式分档：flash 档的 equation 块 content 是空串，standard 档才给出完整 LaTeX（\frac{QK^T}{\sqrt{d_k}}，行内公式也一并还原），同页耗时 2.1 s vs 14.4 s；并实测到单独取 markdown 时图片 base64 内联占 96.9%、改用 zip 小 32.5 倍，而 middle_json 的归一化 bbox 才是做引用定位与按类型过滤噪声的本钱；再逐条核对一份流传较广的 MinerU 教程：mode="flash"/precision 与 CLI 名 mineru-open-cli 在 4.0 并不存在、50 页 OOM 与官方滑窗说法相反、OmniDocBench 95.75 属 1.2B VLM 而非 Pipeline 的 86.47、复现 gist 是 example 占位；并厘清「官方的两个集成」其实在生态仓库 MinerU-Ecosystem 而非核心项目、LangChain 标 Official 而 LlamaIndex 标 Community、核心路线图仍把二者列在 P2——附带一次「核心仓库里没有 ≠ 不存在」的自我纠错） | 入门 |
| sherpa-onnx | 本地语音推理引擎 101 系列（1.13.8 本机实测 + 浏览器实测，Node/前端视角）：入门（两条 Node 路线怎么选——原生 addon 多线程 vs WASM 单线程实测慢 3.4mergedDecoder 与 npm JSDoc 不一致）+ 识别落地（流式 partial 时间线首字 1.1reset() 会吃掉最后一句致结果为空串、长音频整条流式 vs VAD 切段 RTF 0.104 vs 0.065 但会切在句中丢字、24 kHz 自动重采样、可抄的 VAD 门控流水线）+ 听懂黑话（热词把 LIBRAR/LIVE AFTER TOMORROW 拉回 礼拜二；三个坑：冒号前少空格致进程 abort 退出码 134、X-ASR 汉字带 ▁ 前缀全 OOV、英文词逐字符 BPE 对不上；同音词替换 玄界芯片→玄戒芯片 与自建 10 条前端黑话规则 买点→埋点，并澄清规则的左边要写「听错的那个词」的拼音）+ 说话与待机（Kokoro 54 音色中英混读、RTF 1.00 刚好实时、TTS 非确定性实测；KWS 自定义唤醒词三步与英文词大小写/CMU 词典两个静默坑、中英双语模型在连续语流里认出 LIGHT UP、TTS→KWS 闭环 3/3 命中且负样本不误触发）+ 前端集成（官方浏览器产物是编译期把模型打进 .data——逐字节验证内含完整 silero_vad.onnx；无头 Chrome 与 Node 的 VAD 结果逐毫秒一致；npm 的 sherpa-onnx 是 Node 的 WASM 包不是浏览器包；三条落地路线与降级策略） + 视频转字幕（金融评论/编程培训的长口播转 SRT，Python 后端：准确率几乎拉不开差距而速度差 70 倍（内容口径 CER 12%max_speech_duration 不是硬上限（源码里只是把静音判定放宽到 0.1 秒），要自己按能量谷兜底切分；标点不在模型里（SenseVoice/FireRedASR2 一个标点都不吐）而外挂标点会与自带标点叠加成 聊,，；编程视频的英文术语基本全灭——Redis 被听成 REDIC/reradi，Paraformer 干脆一个英文片段都不输出；评测基准取自烧录字幕的 OCR，并用「一帧几个文本框」自动剔掉图表污染时段） + 词表工程（词表不是写出来的，是挖出来的：同一期 Vue3 教程五个模型全都没认对 Vue3（VI三/Viu3/View3/Vue 三），所以换模型只是换一种错法；四种挖法——拼音对齐（只对中文有效：玄界/玄戒 1.0，Vue3/VI三 只有 0.22）、形态启发+最近词猜词（TILE→title/PI→API）、长片段歧义对齐、多模型分歧；实测自动挖的词表命中 106 处、手工 98 处，召回 87%；五个「写了却不起作用」的坑：\b 在中英混排失效、行内注释被灌进字幕、模型空格不稳定、短碎片钻进正确词（PI=>API 把 API 改成 AAPI）、空右侧会删词） + 并发与吞吐（把流水线做成 Docker 服务：MinIO 取件 → 异步转写 → 回传 SRT → 回调；并发的单位只能是进程——多线程共享一个 recognizer 结果对但被内部锁串行化（解码耗时累加 10.9s→158s、墙钟不动、显存 2.7→19.7GB）；真正提效的是批处理 decode_streams（单进程 75×→200×，文本逐字一致），批 16 × 6 进程叠乘到 437× 实时；端到端瓶颈是 VAD 占 50.2% 而 ASR 只占 32.9%；分块并行 VAD 能快 4.6× 但会丢掉 1.2% 的字，所以默认不开） | 入门 |
阅读约定
- 每个子项目的首篇顶部标注了 创建日期 / 最近更新，一眼看到新鲜程度；
- 目录用数字前缀排序（
0.入门 →1.→ …），从0开始读即可； - 侧边栏 URL 会自动剥离文件名数字前缀（如
0.入门→/入门、0.guide→/guide）。
维护约定
- 新增子项目：在
docs/code/下建目录，0.开头写入门/介绍，其余按学习路径编号； - 每个子项目首篇标注创建与更新日期；
- 内容偏"探索笔记"：结论要可验证（有代码/场景支撑），引用他人成果注明来源。
慢慢加，不追求多，只求每篇都值得回看。