ZGLab Notes https://zglab.fun/notes/ 项目中的正式问题、技术决策和可复用方法整理。 zh-CN 2C2G 服务器上的生产级 AI Assistant 部署实践：zglab-rag 的运行边界 https://zglab.fun/notes/projects/zglab-rag/06-production-deployment/ https://zglab.fun/notes/projects/zglab-rag/06-production-deployment/ 记录 zglab-rag 在 2 vCPU、2 GB 内存服务器上通过 Nginx、FastAPI、SQLite、systemd 和 HTTPS 长期运行的部署取舍。 Fri, 21 Aug 2026 00:00:00 GMT 从 RAG Demo 到生产级个人 AI Assistant：zglab-rag 的工程演进 https://zglab.fun/notes/projects/zglab-rag/01-from-rag-to-production/ https://zglab.fun/notes/projects/zglab-rag/01-from-rag-to-production/ 复盘 zglab-rag 如何从本地 Markdown 知识处理逐步演进为带公开边界、引用校验、SSE 和生产运行能力的个人知识助手。 Fri, 21 Aug 2026 00:00:00 GMT 让 RAG 从“回答”变成“可信回答”：zglab-rag 的 Grounded Generation 与 Citation https://zglab.fun/notes/projects/zglab-rag/04-grounded-generation-and-citation/ https://zglab.fun/notes/projects/zglab-rag/04-grounded-generation-and-citation/ 说明为何 Answer 加 Sources 仍不足以保证可信，以及 zglab-rag 如何用 Evidence Context、claim 级引用和确定性校验建立生成边界。 Fri, 21 Aug 2026 00:00:00 GMT 如何科学评估 RAG 检索效果：zglab-rag 的数据集、指标与模型选择 https://zglab.fun/notes/projects/zglab-rag/03-rag-evaluation-methodology/ https://zglab.fun/notes/projects/zglab-rag/03-rag-evaluation-methodology/ 记录 zglab-rag 如何用固定检索数据集、分类指标与 hard negative 比较 Embedding、检索与排序策略。 Fri, 21 Aug 2026 00:00:00 GMT 为什么 Personal AI Assistant 不应该直接成为 Search Agent：zglab-rag 的外部研究边界 https://zglab.fun/notes/projects/zglab-rag/07-personal-first-external-research/ https://zglab.fun/notes/projects/zglab-rag/07-personal-first-external-research/ 记录 zglab-rag Phase 11 的架构规划：个人知识优先，外部研究仅在符合资格的证据不足场景中作为临时、可引用的补充。 Fri, 21 Aug 2026 00:00:00 GMT RAG 最难的不是调用模型，而是知识工程：zglab-rag 的文档与 Chunk 设计 https://zglab.fun/notes/projects/zglab-rag/02-rag-knowledge-engineering/ https://zglab.fun/notes/projects/zglab-rag/02-rag-knowledge-engineering/ 说明 zglab-rag 如何把已登记 Markdown 变成可追溯、可增量更新且具备公开边界的 KnowledgeChunk。 Fri, 21 Aug 2026 00:00:00 GMT Vector Retrieval、Hybrid Retrieval 和 Reranker 的工程实践：zglab-rag 的检索取舍 https://zglab.fun/notes/projects/zglab-rag/05-retrieval-system-design/ https://zglab.fun/notes/projects/zglab-rag/05-retrieval-system-design/ 复盘 zglab-rag 如何使用 SQLite、sqlite-vec、FTS5、RRF 与 Cross Encoder，并基于质量和 2C2G 资源预算决定默认检索路径。 Fri, 21 Aug 2026 00:00:00 GMT 从工具列表到工具平台：ZGLab Tools 规模化扩展中的架构演进 https://zglab.fun/notes/projects/zglab-tools-from-tool-list-to-platform-architecture/ https://zglab.fun/notes/projects/zglab-tools-from-tool-list-to-platform-architecture/ 记录 ZGLab Tools 从少量浏览器工具扩展到几十个工具后，如何通过配置驱动、静态路由、职责分层和生命周期管理保持可维护性。 Wed, 29 Jul 2026 00:00:00 GMT 共享组件不是万能组件：工具平台中的受控复用设计 https://zglab.fun/notes/knowledge/controlled-component-reuse-in-tool-platforms/ https://zglab.fun/notes/knowledge/controlled-component-reuse-in-tool-platforms/ 总结 ZGLab Tools 中 ImageTool、TextEnhancer、DesignTool 等共享组件模式，以及为什么显式 mode 映射优于万能组件。 Wed, 29 Jul 2026 00:00:00 GMT 单测和打包都通过，Spring 为什么还在启动时寻找无参构造器 https://zglab.fun/notes/problems/spring-multiple-constructors-startup-failure/ https://zglab.fun/notes/problems/spring-multiple-constructors-startup-failure/ 复盘一个只在发布启动阶段出现的 Bean 实例化故障：组件增加第二个构造器后，Spring 无法判断注入入口并尝试寻找无参构造器；普通单测和 Maven 打包为何漏过，以及如何用容器级测试补上门禁。 Fri, 24 Jul 2026 00:00:00 GMT 一个成熟的 Agent 系统应该具备什么：从 LLM + Tool 到生产级智能体架构 https://zglab.fun/notes/knowledge/production-agent-system-architecture/ https://zglab.fun/notes/knowledge/production-agent-system-architecture/ 从 Runtime、Tool、Memory、Context、Sandbox、Human-in-the-loop、可观测性、评测和容错等维度，系统梳理一个 Agent 从 Demo 走向生产级系统所需要的核心能力。 Fri, 24 Jul 2026 00:00:00 GMT Agent 长期记忆是如何实现的：从 Context Window 到真正可用的 Memory System https://zglab.fun/notes/knowledge/agent-long-term-memory/ https://zglab.fun/notes/knowledge/agent-long-term-memory/ 系统解释 Agent 为什么不能依赖无限聊天历史来实现记忆，以及成熟的短期记忆、长期记忆、检索、写入、冲突处理和遗忘机制应该如何设计。 Fri, 24 Jul 2026 00:00:00 GMT AI Agent 的沙箱机制：模型为什么能执行命令，却不能随意控制你的电脑 https://zglab.fun/notes/knowledge/agent-sandbox-mechanisms/ https://zglab.fun/notes/knowledge/agent-sandbox-mechanisms/ 从文件系统、进程、网络和权限审批四个维度解释 AI Agent 的沙箱机制，并结合 Codex、Claude Code、Gemini CLI 等实际实现理解本地智能体为何能够安全执行命令。 Fri, 24 Jul 2026 00:00:00 GMT 1000 / Bye 明明是正常关闭，为什么却被记成录音失败 https://zglab.fun/notes/problems/normal-websocket-close-misclassified-during-recovery/ https://zglab.fun/notes/problems/normal-websocket-close-misclassified-during-recovery/ 复盘双 WebSocket 录音链路中一次状态误判：协议层正常关闭并不等于业务完成，关闭码必须结合发起方、发生阶段和恢复意图解释。 Thu, 23 Jul 2026 00:00:00 GMT 短会议不是不能生成纪要：如何同时控制幻觉与业务副作用 https://zglab.fun/notes/knowledge/grounding-short-meeting-minutes-and-side-effects/ https://zglab.fun/notes/knowledge/grounding-short-meeting-minutes-and-side-effects/ 针对十几秒短会议容易生成无关纪要的问题，讨论为何不能只按时长拦截，以及如何用证据约束、语义空值判断和副作用门禁分层治理。 Thu, 23 Jul 2026 00:00:00 GMT 同一句话为什么出现两遍：实时转写与最终转写的时间线对齐 https://zglab.fun/notes/knowledge/reconciling-realtime-and-final-transcripts-by-timeline/ https://zglab.fun/notes/knowledge/reconciling-realtime-and-final-transcripts-by-timeline/ 讨论实时转写与会后最终转写共存时的对账策略：句子 ID 可能漂移，应以时间线和文本为组合证据，并保守处理删除与空快照。 Thu, 23 Jul 2026 00:00:00 GMT 页面没有线程锁，为什么仍会发生竞态：用 Generation Fencing 管理浏览器实时生命周期 https://zglab.fun/notes/knowledge/generation-fencing-for-browser-realtime-lifecycles/ https://zglab.fun/notes/knowledge/generation-fencing-for-browser-realtime-lifecycles/ 总结实时网页中用递增代际隔离过期 WebSocket、麦克风启动和网络恢复任务的方法，让旧异步回调失去修改当前状态的资格。 Thu, 23 Jul 2026 00:00:00 GMT 从“录音正常”到证据链完整：移动会议录音的可观测性改造 https://zglab.fun/notes/projects/observable-mobile-recording-pipeline/ https://zglab.fun/notes/projects/observable-mobile-recording-pipeline/ 总结移动会议录音如何用健康快照、状态事件、客户端环境信息和更准确的异常规则建立排障证据链，同时避免历史故障误报和过度采集设备身份。 Mon, 20 Jul 2026 00:00:00 GMT 结束按钮不是最后一步：移动 H5 录音分片持久化与后台续传 https://zglab.fun/notes/knowledge/durable-h5-audio-chunk-upload/ https://zglab.fun/notes/knowledge/durable-h5-audio-chunk-upload/ 结合移动 WebView 录音场景，说明如何把实时音频旁路保存为可校验分片，正确处理 finalize 时序、弱网重试、页面离开和重新打开后的断点续传。 Mon, 20 Jul 2026 00:00:00 GMT 最后音频停了两小时，会议为什么还在进行中：一次僵尸录音会议复盘 https://zglab.fun/notes/problems/meeting-stuck-recording-after-recovery-expiry/ https://zglab.fun/notes/problems/meeting-stuck-recording-after-recovery-expiry/ 复盘移动会议页面进入后台、音频中断、WebSocket 异常关闭并超过恢复窗口后，实时资源已经释放但会议主状态仍长期停在 RECORDING 的原因与改进方向。 Mon, 20 Jul 2026 00:00:00 GMT 把大模型生成限制在事实边界内：Evidence 驱动的内容生成与校验 https://zglab.fun/notes/knowledge/evidence-grounded-resume-generation/ https://zglab.fun/notes/knowledge/evidence-grounded-resume-generation/ 以简历生成为例，说明如何用 Evidence ID、结构化输出和确定性事实闸门控制大模型幻觉，并讨论数字、技术词、用户编辑和最终导出的安全边界。 Fri, 17 Jul 2026 00:00:00 GMT 不靠免密 sudo 的静态站发布：目录授权、严格健康检查与重复覆盖 https://zglab.fun/notes/projects/sudo-free-static-deployment-and-strict-health-check/ https://zglab.fun/notes/projects/sudo-free-static-deployment-and-strict-health-check/ 以 ZGLab Tools 部署审查为例，说明如何用一次性目录授权替代宽泛的 sudo -n，建立路径校验、部署前备份、rsync 覆盖、严格健康检查、失败回滚和备份保留流程。 Fri, 17 Jul 2026 00:00:00 GMT 不上传内容也能生成二维码：从 Payload 封装到 PNG、SVG 下载 https://zglab.fun/notes/projects/zglab-tools-qrcode-generator-implementation/ https://zglab.fun/notes/projects/zglab-tools-qrcode-generator-implementation/ 以 ZGLab Tools 二维码生成器为例，逐步实现文本、URL、邮箱、电话和 Wi-Fi Payload、本地预览、容量校验、颜色提示与文件下载。 Fri, 17 Jul 2026 00:00:00 GMT 从 JSON.parse 到 Web Worker：实现一个不会吞掉错误上下文的 JSON 格式化器 https://zglab.fun/notes/projects/zglab-tools-json-formatter-implementation/ https://zglab.fun/notes/projects/zglab-tools-json-formatter-implementation/ 以 ZGLab Tools 的 JSON 格式化器为例，逐步实现格式化、压缩、递归键排序、错误定位、后台处理、复制下载和边界测试。 Fri, 17 Jul 2026 00:00:00 GMT 从岗位 JD 到可追溯 PDF：ResumeTailor Agent 的可控工作流设计 https://zglab.fun/notes/projects/resume-tailor-agent-controlled-workflow/ https://zglab.fun/notes/projects/resume-tailor-agent-controlled-workflow/ 复盘一个岗位定制简历 Agent 的阶段性设计与实现，重点说明如何划分模型和普通程序的职责，并用证据链、状态机和确定性渲染控制真实性。 Fri, 17 Jul 2026 00:00:00 GMT 从构建到上线：Ubuntu 24.04 + Nginx 部署 Astro 静态网站 https://zglab.fun/notes/projects/deploy-astro-static-site-with-nginx/ https://zglab.fun/notes/projects/deploy-astro-static-site-with-nginx/ 以 ZGLab 为例，整理 Astro 静态网站从本地构建、服务器目录准备、Nginx 配置、备份发布到回滚验证的完整流程，并区分已经验证的步骤与仍需在真实服务器确认的部分。 Fri, 17 Jul 2026 00:00:00 GMT 从五个小工具到可扩展平台：Astro + Preact 构建本地优先工具箱 https://zglab.fun/notes/projects/building-local-first-astro-tool-platform/ https://zglab.fun/notes/projects/building-local-first-astro-tool-platform/ 以 ZGLab Tools 为例，记录如何将 JSON、时间戳、文本与二维码等浏览器工具组织成配置驱动、按页加载、逻辑可测试且能够持续扩展的静态工具平台。 Fri, 17 Jul 2026 00:00:00 GMT 从一张静态页面到可维护的个人数字档案：Astro 个人网站从零搭建实践 https://zglab.fun/notes/projects/from-zero-to-maintainable-astro-personal-site/ https://zglab.fun/notes/projects/from-zero-to-maintainable-astro-personal-site/ 以 ZGLab 为例，说明如何从零规划一个配置驱动、静态构建、可长期扩展的个人网站，并记录技术选型、目录设计、响应式实现和实际验证过程。 Fri, 17 Jul 2026 00:00:00 GMT 断线不等于结束：实时会议录音的可恢复会话设计 https://zglab.fun/notes/projects/recoverable-realtime-recording-session/ https://zglab.fun/notes/projects/recoverable-realtime-recording-session/ 结合移动 H5 实时录音场景，说明如何把浏览器断线从自动结束会议改造成可恢复状态，并协调服务端资源窗口、前端恢复标记和显式结束语义。 Fri, 17 Jul 2026 00:00:00 GMT 结构化大模型调用如何可靠落地：Provider、宽松边界与确定性降级 https://zglab.fun/notes/knowledge/reliable-structured-llm-calls/ https://zglab.fun/notes/knowledge/reliable-structured-llm-calls/ 总结在 DeepSeek、OpenAI 和 Mock Provider 之间建立统一结构化调用边界的实践，包括分层超时、错误分类、宽松响应归一化和节点级安全降级。 Fri, 17 Jul 2026 00:00:00 GMT 静态网站也需要工程化：备份发布、功能开关与动态接口边界 https://zglab.fun/notes/knowledge/static-site-release-and-runtime-boundaries/ https://zglab.fun/notes/knowledge/static-site-release-and-runtime-boundaries/ 总结静态网站如何通过可失败的部署脚本、发布前备份、功能开关和空配置安全降级，在保持纯静态主路径的同时为运行状态和 GitHub 数据预留扩展能力。 Fri, 17 Jul 2026 00:00:00 GMT 浏览器本地处理不等于天然安全：工具网站的数据与隐私边界 https://zglab.fun/notes/knowledge/browser-local-processing-privacy-boundaries/ https://zglab.fun/notes/knowledge/browser-local-processing-privacy-boundaries/ 以 ZGLab Tools 为例，说明本地优先工具如何划分内存、localStorage、剪贴板、Blob 下载、二维码与 Web Worker 的数据边界，以及为什么仍应避免处理高敏感信息。 Fri, 17 Jul 2026 00:00:00 GMT 秒、毫秒与时区之间：用 Intl 实现可靠的时间戳转换器 https://zglab.fun/notes/projects/zglab-tools-timestamp-converter-implementation/ https://zglab.fun/notes/projects/zglab-tools-timestamp-converter-implementation/ 以 ZGLab Tools 的时间戳转换器为例，讲解单位识别、日期合法性校验、IANA 时区换算、夏令时边界、实时钟和测试设计。 Fri, 17 Jul 2026 00:00:00 GMT 内嵌 H5 为什么拿不到麦克风：Cordova 权限桥接与能力探测 https://zglab.fun/notes/knowledge/hybrid-app-microphone-permission-bridge/ https://zglab.fun/notes/knowledge/hybrid-app-microphone-permission-bridge/ 以企业移动 App 内嵌会议 H5 为例，说明浏览器权限、宿主原生权限和 Cordova 插件之间的边界，以及如何通过分层探测和安全降级提高麦克风可用性。 Fri, 17 Jul 2026 00:00:00 GMT 匹配不少，为什么最终简历仍然是空的：一次多节点生成链路复盘 https://zglab.fun/notes/problems/resume-matches-but-generated-document-empty/ https://zglab.fun/notes/problems/resume-matches-but-generated-document-empty/ 复盘岗位要求已经匹配到多条候选人证据，但最终 PDF 只剩页眉的问题，分析 Planner、Writer 和 FactValidator 如何串联造成内容丢失，并给出覆盖下限和字段级校验方案。 Fri, 17 Jul 2026 00:00:00 GMT 去重、自然排序与随机打乱：实现可预测的逐行文本处理流水线 https://zglab.fun/notes/projects/zglab-tools-line-processor-implementation/ https://zglab.fun/notes/projects/zglab-tools-line-processor-implementation/ 以 ZGLab Tools 文本去重与排序工具为例，构建换行标准化、Trim、空行处理、去重、排序和统计组成的确定性流水线。 Fri, 17 Jul 2026 00:00:00 GMT 用 Astro Content Collections、YAML 与 Zod 构建配置驱动网站 https://zglab.fun/notes/knowledge/astro-content-collections-config-driven-content/ https://zglab.fun/notes/knowledge/astro-content-collections-config-driven-content/ 以个人网站项目档案为例，解释如何划分 Markdown Collection 与集中式 YAML 数据、使用 Zod 提前校验内容，并自动生成项目列表和静态详情路由。 Fri, 17 Jul 2026 00:00:00 GMT 长会议 H5 如何避免越用越卡：有界状态、音频自愈与大文件下载 https://zglab.fun/notes/knowledge/long-running-h5-memory-and-download-optimization/ https://zglab.fun/notes/knowledge/long-running-h5-memory-and-download-optimization/ 从实时转写列表、Web Audio 生命周期和大录音下载三个方面，总结长时间运行的移动 H5 如何控制内存增长，并提高系统从后台切换和设备变化中恢复的能力。 Fri, 17 Jul 2026 00:00:00 GMT Emoji 到底算几个字符：实现 Unicode 感知的文本统计器 https://zglab.fun/notes/projects/zglab-tools-text-counter-implementation/ https://zglab.fun/notes/projects/zglab-tools-text-counter-implementation/ 以 ZGLab Tools 文本统计器为例，说明可见字符、中文、英文单词、段落、UTF-8 字节和阅读时间的统计规则与实现。 Fri, 17 Jul 2026 00:00:00 GMT 不要把临时 OSS 地址直接交给前端：录音安全中转与签名链接设计 https://zglab.fun/notes/knowledge/secure-recording-proxy-and-signed-links/ https://zglab.fun/notes/knowledge/secure-recording-proxy-and-signed-links/ 结合会议录音下载场景，说明如何用后端流式代理、域名白名单、会议绑定签名和单段 Range 支持，替代前端直接使用易过期的对象存储地址。 Thu, 16 Jul 2026 00:00:00 GMT 从多入口免登到统一身份：从属应用接入 CAS 的设计实践 https://zglab.fun/notes/projects/subordinate-app-cas-unified-auth/ https://zglab.fun/notes/projects/subordinate-app-cas-unified-auth/ 以一个同时嵌入 OA 网页入口和移动应用入口的从属系统为例，梳理 CAS 单点登录、本地 JWT、移动端 accessToken 桥接和安全回跳的完整设计。 Thu, 16 Jul 2026 00:00:00 GMT 两个长期分叉仓库如何安全同步：以测试仓与生产仓联调为例 https://zglab.fun/notes/projects/dual-repository-sync-with-environment-isolation/ https://zglab.fun/notes/projects/dual-repository-sync-with-environment-isolation/ 总结测试仓库与生产仓库长期并行演进时，如何按共同基线分类差异、保留环境专属内容、同步业务代码并通过构建测试降低覆盖风险。 Thu, 16 Jul 2026 00:00:00 GMT 应用已经启动，却被发布脚本自动回滚：一次过期健康检查的排查复盘 https://zglab.fun/notes/problems/stale-health-check-causes-false-rollback/ https://zglab.fun/notes/problems/stale-health-check-causes-false-rollback/ 复盘 Spring Boot 应用正常启动后，发布脚本因继续探测已删除接口而等待超时并自动回滚的问题，并给出可诊断、可回滚的健康检查脚本模式。 Thu, 16 Jul 2026 00:00:00 GMT