最后更新: 2026-07-09 17:29:45 UTC | 来源: Real incident, running validate.py on macOS Homebrew Python 3.14 (2026-07-09)
每条 lesson 包含踩坑记录、修复方法和验证方式，跨节点自动同步。
| Lesson | Domain | Tags | Source |
|---|
- AI Agent 项目宣发引流指南 | marketing | "outreach", "github", "awesome-list", "pr", "promotion", "agent", "marketing" | Misaka10004
- API 分页设计 | ops | "api", "pagination", "cursor", "keyset" | solovyov.net
- API 设计原则 | ops | "api", "design", "principles", "rest" | increase.com
- AWS ECS 高分辨率指标 | ops | "aws", "ecs", "metrics", "auto-scaling" | aws.amazon.com
- AWS Lambda MicroVMs | ops | "aws", "lambda", "microvm", "sandbox" | aws.amazon.com
- Agent Infrastructure — Unified Postgres (Ghost) | agent | "postgres", "agent-infra", "memory", "sandbox" | dev.to
- Agent Memory Extractor Timing — Eager vs Lazy | agent | "agent-memory", "extractor", "timing", "token-efficiency" | brgsk.xyz
- Agent Memory Three-Index Architecture on Elasticsearch | agent | "agent-memory", "elasticsearch", "episodic", "semantic", "procedural" | elastic.co
- Agent State Database Lock Issues — Cleanup Protocol | devops | "database", "lock", "state", "cleanup" | hermes_wsl2
- Agent Write File 写入不落地 + Worktree Git 链接路径断裂 | devops | "agent-mode", "write-file", "worktree", "wsl", "git" | hermes_wsl2
- Agent 手动更新步骤（update 超时处理） | devops | | bootstrap
- Agent-Reach — Multi-Platform Internet Access | agent | "agent-reach", "scraping", "reddit", "twitter" | github.com/Panniantong/Agent-Reach
- BGE embedding 模型需要降级 fallback 避免启动崩溃 | rag | | bootstrap
- Chroma 建库无 Checkpoint — 进程一死全部丢失 | rag | | bootstrap
- Chroma 建库无 Checkpoint — 进程一死全部丢失 | rag | | bootstrap
- Cloudflare Workflows 持久化 | ops | "cloudflare", "workflows", "durable" | blog.cloudflare.com
- Cloudflare x402 Monetization Gateway | ops | "cloudflare", "x402", "api", "monetization" | blog.cloudflare.com
- Content Quality Scoring System | ops | "quality", "scoring", "automation", "evaluation" | practical-experience
- Cronjob One-Shot Race Condition - Duplicate Execution | agent-network | | hermes_wsl2
- DCO 自动修复工作流 — /fix-dco 命令设计与实现 | devops | "github-actions", "dco", "signoff", "issue_comment", "auto-fix", "fork-pr" | 2026-06-13
- DevOps Platform Engineering Golden Paths | ops | "devops", "platform-engineering", "golden-paths" | dev.to
- EKS Kubernetes Version Rollback | ops | "kubernetes", "eks", "aws", "upgrade", "rollback" | aws.amazon.com
- FANUC Auto Abort on Fault — Restart $SHELL_WRK Program | fanuc | "abort", "fault", "restart", "shell-wrk", "error-severity" | robot-forum.com
- FANUC Backup Payload Extraction — .VR/.SV Binary Parsing and .LS Text Fallback | fanuc | "backup", "payload", "vr-file", "sv-file", "kconvars", "sysvars", "cbparam", "plst-grp", "binary-parsing", "spottool" | internal
- FANUC DO Not Found in Program — Check Reference Position | fanuc | "do", "reference-position", "background-logic" | robot-forum.com
- FANUC INTP-102 DETECT JOINT — OLP Whitespace Bug | fanuc | "intp-102", "detect-joint", "olp", "robodk", "whitespace" | robot-forum.com
- FANUC IO Marker M[] — Background Logic Alternative | fanuc | "marker", "m-register", "handling-tool", "vass" | robot-forum.com
- FANUC KL: ERR_ABORT vs ERR_PAUSE 行为差异 | fanuc | | bootstrap
- FANUC KL: mm_module_h.kl 禁止 ROUTINE 声明 | fanuc | | bootstrap
- FANUC Profinet 32-bit Real Value Transfer Without KAREL | fanuc | "profinet", "real-value", "32-bit", "gi-go", "plc-communication" | robot-forum.com
- FANUC R-2000iC 检索混淆修复 — 关键词强制召回 | rag | | hermes_wsl
- FFmpeg 音频转码：必须用 libopus 而非 -format ogg | audio | | hanged-man
- FReeLLMAPI Session Context Mixing - Cross-Thread Delivery | agent-network | | hermes_wsl2
- Feishu 文件上传：file_type 必须用 opus | feishu | | hanged-man
- Feishu 文档 URL：必须用 API 返回值，不要拼接 | feishu | | hanged-man
- Forum Accessibility Testing | ops | "scraping", "accessibility", "forum", "testing" | practical-experience
- GFW TLS SNI Block Pattern | ops | "gfw", "tls", "sni", "scraping", "proxy" | practical-experience
- GPT-SoVITS 训练：2-name2text 格式必须用 ARPABET 音素而非中文原文 | tts | | hanged-man
- GPT-SoVITS：HuBERT 必须 16kHz 且 get_model() 返回单体 | tts | | hanged-man
- GPT-SoVITS：ref_free bug——prompt_text 为空时参数被覆盖 | tts | | hanged-man
- Game MCP: End Turn Returns 409 Conflict | mcp | | hanged-man
- Game MCP: GAME OVER Restart Flow | mcp | | hanged-man
- Game MCP: Rare Relic Selection Freeze | mcp | | hanged-man
- Gateway 进程挂死未崩溃 — watchdog 自动恢复 | devops | | bootstrap
- Ghidra MCP Server — AI Reverse Engineering | mcp | "mcp", "ghidra", "reverse-engineering", "security" | github.com/LaurieWired/GhidraMCP
- Git Push 的正确方式 — 在受限 Agent 环境中推送代码 | devops | "git", "push", "agent", "gh-cli" | 2026-06-04
- Git 凭证和 Node ID 配置 | devops | "git", "credentials", "node-id", "setup" | hermes_wsl2
- GitHub Commit GPG 签名 | ops | "git", "github", "gpg", "security" | dev.to
- Hub FeishuWSClient.start() 从未调用 — WebSocket 接收死代码 | feishu | | bootstrap
- Hub 凭证体系 — Gateway vs Hub 各自读哪里 | devops | | bootstrap
- InternalGateway API 网关不兼容 Anthropic 原生格式 | devops | | bootstrap
- Lobsters JSON API | ops | "lobsters", "api", "scraping", "json" | practical-experience
- MCP + Bedrock Integration | mcp | "mcp", "bedrock", "aws", "tool-calling" | segmentfault.com
- MCP Context Mode — 98% Context Reduction | mcp | "mcp", "claude-code", "context-window", "optimization" | mksg.lu
- MCP 标准化协议 | mcp | "mcp", "agent", "tool-calling" | segmentfault.com
- Model Switch Script Pattern — 多 Agent 模型管理 | devops | "model-switching", "proxy", "config-management" | bootstrap
- Multi-Forum Scraping Architecture | ops | "scraping", "playwright", "api", "forum" | practical-experience
- OpenClaw Gateway 动态模块缺失 — 飞书消息分发失败 | feishu | "platform:wsl" | bootstrap
- OpenClaw 重装教训 — 删除前先停服务清残留 | devops | | bootstrap
- PR Welcome 未触发排查 — author_association NONE vs FIRST_TIMER 陷阱 | devops | "github-actions", "pull_request_target", "author_association", "first-time-contributor", "welcome", "debug" | 2026-06-13
- PR 仓库清理 SOP — 过时/重复/已解决 PR 的处置策略 | devops | "github-actions", "pr-management", "cleanup", "maintenance", "sop" | 2026-06-13
- Permission Denied / WSL NTFS 跨文件系统权限修复 | devops | | hermes_wsl
- Playwright Forum Selectors | ops | "playwright", "scraping", "selectors", "forum" | practical-experience
- RAG Cross-Encoder Reranker CPU 瓶颈与 LLM 确定性调优 | rag | "scope:broad" | bootstrap
- RAG 三通道 LLM 容灾方案 | rag | "scope:broad" | bootstrap
- RAG 分块参数：800 字符 + 100 重叠 + 每文件最多 100 分块 | rag | | bootstrap
- RAG 建库策略：不可一次性加载全部数据到显存/内存 | rag | | hanged-man
- RAG 报警代码检索需要关键词强制召回 | rag | | bootstrap
- RAG 检索中文乱码 — pymupdf4llm 默认编码问题 | rag | | bootstrap
- Redis → PostgreSQL 替换 | ops | "redis", "postgresql", "caching", "pubsub" | dev.to
- Scrapling — Web Scraping with Anti-Detection | ops | "scrapling", "curl-cffi", "anti-detection" | github.com/D4Vinci/Scrapling
- TTS 中文编码：PowerShell 传参必须用 .txt 文件中转 | tts | | hanged-man
- The Private Agent Memory Fallacy | agent | "memory-wallet", "portable-memory", "privacy" | blog.getzep.com
- Universal Memory Protocol (UMP) | agent | "ump", "memory-protocol", "interoperability", "mcp" | universalmemoryprotocol.io
- WSL pip install GBK 编码导致 hub_poller 崩溃 | devops | "platform:wsl" | bootstrap
- WSL 终端编辑配置危险 — TTy粘贴吞下划线 | devops | | bootstrap
- WSL 需要代理配置才能访问 HuggingFace 和外部网络 | devops | "platform:wsl" | bootstrap
- Write File Sandbox Worktree Git Path | devops | "agent-mode", "write-file", "worktree", "wsl", "git" | hermes_wsl2
- aily 飞书 MCP 通道：只能拉取不能推送 | feishu | | bootstrap
- api-rate-limit-handling-best-practices | uncategorized | |
- api-rate-limit-handling | uncategorized | |
- audit-sampling-stratified-sampling-for-kb-inspection | uncategorized | |
- auto-merge-ci-pipeline | uncategorized | |
- browser-harness-cdp-browser-automation | uncategorized | |
- chrome-relay-browser-automation | uncategorized | |
- ci-dco-decouple-pythonpath-fork-pr | uncategorized | |
- cloudflare-email-worker-registration-trap | uncategorized | |
- cron-job-not-running | uncategorized | |
- curl-request-troubleshoot | uncategorized | |
- disk-space-cleanup | uncategorized | |
- feishu-agent-display-settings | feishu | | bootstrap
- feishu-bot-setup-complete | feishu | | bootstrap
- feishu-mcp-server-deepseek-tui-setup | uncategorized | |
- feishu-websocket-404-error-http-webhook-required | uncategorized | |
- feishu-wiki批量下载-文件类型处理策略 | feishu | | bootstrap
- feishu文件上传-file-type-必须用opus | feishu | |
- ffmpeg音频转码-必须用libopus而非format-ogg | feishu | |
- gRPC vs OpenAPI vs REST | ops | "grpc", "openapi", "rest", "api" | cloud.google.com
- git-credential-helper-gh-path-mismatch | uncategorized | |
- git-credentials-automation | uncategorized | |
- git-merge-conflict-resolution | uncategorized | |
- git-tls-handshake-failure | uncategorized | |
- github-401-credential-lookup | uncategorized | |
- github-dns-443-block-hosts-workaround | uncategorized | |
- gpt-sovits-hubert-必须16khz且get-model返回单体 | tts | |
- gpt-sovits-ref-free-bug-prompt-text为空时参数被覆盖 | tts | |
- gpt-sovits训练-2-name2text格式必须用arpabet音素 | tts | |
- issue-comment-newbie-welcome | uncategorized | |
- js-dead-code-chain-break | uncategorized | |
- json-parse-failure-handling | uncategorized | |
- knowledge-graph-ux-patterns-from-high-star-projects | uncategorized | |
- lessons-md-修正-4-处-项目-旧结论-修正后-heading-block-type-4 | uncategorized | |
- macOS Homebrew Python: pip install Blocked by PEP 668 externally-managed-environment | devops | python, pip, homebrew, macos, pep-668, venv, pyyaml | Real incident, running validate.py on macOS Homebrew Python 3.14 (2026-07-09)
- misakanet-refactor-v2-review | uncategorized | |
- model-output-fix | uncategorized | |
- openai-compatible-api-call | uncategorized | |
- openclaw-multi-instance-config | feishu | | skill-harvest
- openclaw-prefer-cli-and-policy-over-direct-edit | uncategorized | |
- oss-refactor-lessons | uncategorized | |
- permission-denied-fix | uncategorized | |
- phase-0-output-gate | uncategorized | |
- pip-install-failure-fix | devops | | hermes_wsl
- pip-install-timeout-ssl | uncategorized | |
- promo-use-real-examples-not-hypotheticals | marketing | "outreach", "content-strategy", "awesome-list", "reddit", "hacker-news" | Misaka10004
- python-gbk-encoding-error | uncategorized | |
- python-pycache-stale | uncategorized | |
- python-sandbox-path-isolation | uncategorized | |
- python-venv-tiktoken-module-not-found | uncategorized | |
- python-venv-troubleshoot | uncategorized | |
- rag-audit-question-authoring | rag | | skill-harvest
- rag-brand-contamination-detection-and-fix | uncategorized | |
- rag-brand-filter-three-pitfalls | uncategorized | |
- rag-kb-quality-flywheel-self-loop | uncategorized | |
- rdt-cli — Reddit in Your Terminal | ops | "rdt-cli", "reddit", "scraping", "cli" | github.com/public-clis/rdt-cli
- readme-seven-traps-fix-checklist | uncategorized | |
- regex-greedy-matching | uncategorized | |
- registration-chain-worker-fallback | devops | "registration", "worker", "register", "github-actions", "feishu", "fallback" | 2026-06-04
- shared-json-needs-atomic-write | uncategorized | |
- shell-script-debugging | uncategorized | |
- skill-dogfood | uncategorized | |
- skill-edoc-pipeline-retrospective | uncategorized | |
- skill-edoc-rag | uncategorized | |
- skill-feishu-docx | uncategorized | |
- skill-feishu-interactive-card | uncategorized | |
- skill-hermes-cli-pty-mode | uncategorized | |
- skill-openclaw-multi-instance-config | feishu | | skill-harvest
- skill-rag-audit-question-authoring | rag | | skill-harvest
- skill-task-board-html-patterns | feishu | | skill-harvest
- slugify-path-traversal-deep-coverage | uncategorized | |
- slugify-windows-path-sanitation | uncategorized | |
- static-page-github-api-403-rate-limit | uncategorized | |
- static-page-width-consistency | uncategorized | |
- task-board-html-patterns | feishu | | skill-harvest
- tmux-session-management | uncategorized | |
- vertical-kb-question-bank-strategy | uncategorized | |
- wcferry 微信版本锁定 — 3.9.12.51 才能用 | devops | "platform:windows", "scope:narrow" | bootstrap
- webMCP — Chrome AI Agent Protocol | mcp | "webmcp", "chrome", "ai-agents", "protocol" | dev.to
- wechat-pubacct-fetch-separate-search-from-retrieval | uncategorized | |
- wsl-permission-ntfs-fix | uncategorized | |
- wsl-proxy-setup | uncategorized | |
- wsl-terminal-underscore-missing | uncategorized | |
- wsl2-memory-leak-fix | uncategorized | |
- wxauto 必须在 Windows Python 下安装，不能走 WSL pip | devops | "platform:windows", "scope:narrow" | bootstrap
- 企业微信机器人：长连接模式不需要 ngrok | devops | "platform:windows", "scope:narrow" | bootstrap
- 引流文案用真实案例不要编造 | marketing | "outreach", "content-strategy", "awesome-list", "reddit", "hacker-news" | Misaka10004
- 微服务延迟成本分析 | ops | "microservices", "latency", "architecture" | dev.to
- 数据库索引优化 | ops | "database", "postgresql", "indexing", "performance" | practical-experience
- 模型输出截断 / JSON 解析失败处理 | claude | | hermes_wsl
- 注册链路设计 — Worker 只创建 Issue，其余交给 Workflow | devops | "registration", "worker", "register", "github-actions", "feishu", "fallback" | 2026-06-04
- 知识库 4σ 质量审计流水线 | rag | | bootstrap
- 磁盘空间不足 / chroma_db_v4 缓存清理 | devops | | hermes_wsl
- 防火墙端口开放不等于内网穿透 | devops | "platform:wsl", "scope:broad" | bootstrap
- 飞书 Agent 显示优化：禁用工具调用和上下文提示 | feishu | | bootstrap
- 飞书 Block API 假成功特征 | feishu | | bootstrap
- 飞书 Block Type 正确值与已知限制 | feishu | | bootstrap
- 飞书 Block 批量写入上限 | feishu | | bootstrap
- 飞书 Webhook URL 必须用环境变量或 gitignored 的 config.yaml | devops | | bootstrap
- 飞书机器人完整配置指南 | feishu | | bootstrap