← 资源广场

资源专题

41 项资源

Skills 资源技能包

bootstrapping-deepagents-env

在一台干净机器上装好 DeepAgents 运行环境、接入一个 OpenAI 兼容大模型凭证，并跑通第一个 create_deep_agent 工具调用闭环。Use when 需要初始化 DeepAgents 开发环境、系统 Python 版本不达标装不上包、不确定装到了哪个版本、接 DeepSeek 之类国产模型报 ImportError 或 404 这类环境层故障时。涵盖解释器版本核对、虚拟环境置备、主包与提供方包安装、版本核验、凭证注入、最小示例验收；不含 Agent 各项能力的用法（见 tracking-task-progress-with-todos 等能力型 skill）。

Skills 资源技能包

inspecting-agent-graph-and-tools

把一个 create_deep_agent 建出来的智能体拆开看：列出执行图节点、列出实际挂载的工具、捕获框架预装的中间件清单、抓取每轮真正发给模型的工具集。Use when 需要确认某项能力是否真的挂上了、排查「我的工具去哪了 / 这些工具哪来的 / 内置工具到底几个」、验证自定义中间件是否进了图、或要在改配置前后做结构对照时。涵盖图节点自省、工具清单反查、中间件清单捕获、编译期与运行期工具集差异；不含具体能力的用法。

Skills 资源技能包

tracking-task-progress-with-todos

让智能体把多步任务拆成结构化待办清单写进状态，并从调用结果里取出清单、渲染成实时进度、兜底检测「勾完清单却没给答案」的失败形态。Use when 需要给长任务做进度面板、想稳定触发 write_todos、发现规划没被触发、或要把 todos 推给前端 UI 与日志时。涵盖稳定触发写法、取清单的两条路径、三态进度渲染、失败形态检测；不含子任务委派（见 delegating-subtasks-to-subagents）。

Skills 资源技能包

delegating-subtasks-to-subagents

定义子智能体并挂进主智能体，用内置的 task 工具把多步子任务整体委派出去，主上下文只收一条结论。Use when 主智能体的消息历史被子任务中间过程撑爆、想让不同子任务跑在不同模型上做成本分层、需要隔离子任务上下文、或排查「委派没发生 / 子智能体不知道用户交代过的约束」这类路由与信息真空问题时。涵盖子智能体字典三必填字段、挂载与触发、双向隔离边界、描述写法、开销与适用判据；不含单个智能体内部的规划（见 tracking-task-progress-with-todos）。

Skills 资源技能包

configuring-conversation-compaction

配置摘要中间件、把默认高触发阈值调到当堂可见，让长对话在撞上下文窗口前先被压缩，并看清压缩前后各发生了什么。Use when 长程智能体对话越积越长、要自定义压缩触发阈值与保留条数、想给摘要单独配一个更便宜的模型、排查压缩死活不触发、卸载写文件报只读文件系统、或保留条数与配置值对不上时。涵盖中间件配置写法、阈值量纲与近似计数、触发确认判据、工具参数截断、执行顺序与主动压缩工具；不含压缩造成的信息丢失回归检查（见 auditing-compaction-information-loss）。

Skills 资源技能包

auditing-compaction-information-loss

给长程智能体建一份压缩信息丢失的回归检查——在正确的观测位点统计关键词存活率、用行为探针验证模型是否真的答不出来、并从无损原文里找回被丢掉的内容。Use when 要在长程智能体上线前确认压缩会不会吃掉关键约定、怀疑智能体压缩后悄悄忘了早先交代的事、存活率统计永远 100% 测不出衰减、或要把这套检查挂进持续集成时。涵盖观测位点铁律、关键词埋设方式、行为探针判据、原文找回、逐代衰减观察；不含压缩阈值本身的配置（见 configuring-conversation-compaction）。

Skills 资源技能包

offloading-large-tool-output-to-files

用智能体的虚拟文件系统把大块工具输出移出上下文——既走「模型主动 write_file 存盘、需要时 read_file 取回」，也走「框架按阈值自动卸载并留一条引用」。Use when 工具一次返回几十 KB 文本、上下文被大输出撑爆、账单随历史线性上涨、或要配置自动卸载阈值、排查 write_file 报已存在与 edit_file 报字符串出现多次这类文件工具报错时。涵盖两条卸载路径、阈值量纲与配置入口、文件生命周期、写入与编辑契约；不含对话历史摘要压缩（见 configuring-conversation-compaction）。

Skills 资源技能包

persisting-cross-session-memory

用组合后端把 /memories/ 前缀路由到键值仓库后端，让智能体写下的用户偏好在换一个全新会话后仍能读回，并按命名空间隔离多用户。Use when 智能体换个会话就失忆、要做跨会话的用户偏好或长期事实记忆、需要区分「会话内连续」与「跨会话持久」两条轴、或排查配好了却读不回、抄官方命名空间写法报 AttributeError、进程重启后记忆全没这类问题时。涵盖后端选型、路由配置、两次会话调用、命名空间隔离、持久级别切换；不含单次会话内的大产物卸载（见 offloading-large-tool-output-to-files）。

Skills 资源技能包

integrating-mcp-tools

用 MultiServerMCPClient 把一个 MCP server 暴露的整套工具接进智能体，并与自己写的普通函数工具混挂在同一个 tools 列表里。Use when 想一行配置换来一整套现成工具、要接文件系统或记忆这类官方 server、需要在 stdio 与 http 传输之间选型、或排查 coroutine object is not iterable、ExceptionGroup 连接失败、MCP 工具不能同步调用、内置工具被同名 MCP 工具顶替这类接入报错时。涵盖最小接入代码、异步入口写法、传输配置、混挂与同名覆盖、每次调用的开销与选型判据。

Skills 资源技能包

swapping-agent-models

把同一套智能体架构代码切到另一个大模型上——两种 model 入参写法、OpenAI 兼容端点接法、集成包依赖边界，以及主智能体与子智能体各跑不同模型的混用。Use when 要把智能体从旗舰闭源模型换到国产便宜模型、接一个新的 OpenAI 兼容端点、字符串写法报 ImportError、换完模型后工具不再被触发、或要做「主贵规划、子便宜干活」的成本分层时。涵盖两条 model 解析路径的差异、换模型的最小改动面、换完后的验收清单；不含按型号调优的配置档注册（见 configuring-model-profiles）。

Skills 资源技能包

configuring-model-profiles

注册并核验两类配置档——提供方配置档控制模型怎么被构造（初始化参数注入），装具配置档控制模型造好后智能体怎么跑（系统提示后缀、工具与中间件裁剪）。Use when 想给某个提供方统一设初始化参数、要给某个型号追加调优提示、注册了配置档却发现没生效、给一家注册的配置档意外影响了别的模型、或排除中间件时报 ValueError 时。涵盖两类配置档的注册写法、两条 model 解析路径下的命中差异、离线核验手段、可剥与不可剥边界；不含换模型本身（见 swapping-agent-models）。

Skills 资源技能包

authoring-agent-skills

写一份合规的技能文件目录并挂进智能体，让它在任务匹配时才加载全文、按你定的规范稳定产出。Use when 想把一段可复用的领域规范交给智能体、system_prompt 被各种规范撑成告示墙、技能挂上却静默不加载、缺字段导致技能从清单消失、或要做多来源分层覆盖与跨平台复用时。涵盖技能目录结构、逐字段写法、挂载路径与后端要求、三级加载的观测方法、正文克制纪律与省上下文的真实边界。

Skills 资源技能包

gating-tool-calls-with-approval

给智能体按工具名装人工审批门、按文件路径装权限规则，让危险操作在执行前停下等人拍板，四种决策送回后从断点续跑。Use when 智能体会写文件删数据或执行命令而需要人工把关、合规要求留下审批记录、要按路径一律硬拦某些目录、或排查恢复时报没有检查点保存器、换了会话标识后中断永远恢复不了、审批通过了文件却没写这类问题时。涵盖审批门与检查点保存器配置、中断载荷读法、四种决策语义、路径级权限三模式、副作用重放与会话标识管理。

Skills 资源技能包

writing-custom-middleware

继承 AgentMiddleware 写一件自己的中间件并挂进智能体，用六个钩子在模型调用与工具调用的前后插入逻辑——注入系统提示、按需裁剪工具、统计用量、短路、重试、提前终止循环。Use when 需要在不改框架源码的前提下扩展智能体行为、要运行时动态改发给模型的请求、要监控或拦截工具调用、要按条件叫停循环、或排查挂了中间件却没触发、改请求不生效、智能体卡住不返回这类问题时。涵盖最小可观测中间件、六钩子分工与触发时机、两大家族的挂载差异、请求覆写与短路重试。

Skills 资源技能包

running-coding-tasks-with-dcode

装上官方成品终端编码智能体 dcode，配好模型，在自己的工程目录里跑通多步改码任务——交互模式看差异与审批、无交互模式接脚本与持续集成。Use when 想用成品 CLI 而不是自己写脚本、要让终端编码智能体接国产模型或本地模型、排查 command not found、服务健康检查 60 秒超时、配了某家模型却在调另一家、缺提供方依赖这类启动与配置故障时。涵盖三个同名包的区分、隔离安装与验证、模型四层优先级、任务目录准备、交互与无交互两种跑法、审批与用量入口。

Skills 资源技能包

authoring-brain-pages

用 Compiled Truth / Timeline 双区结构编写 GBrain markdown 页面、批量 import 入库、并按 git-commit 约定同步知识演进。Use when 需要往 brain 里建人物/公司/会议/概念页面、设计页面 frontmatter 与 typed wikilink、把一批 markdown 导入 brain、或更新某条事实又保留历史证据时。涵盖双区页面结构、frontmatter slug 陷阱、gbrain import、Compiled Truth 重写 + Timeline 追加、modify→commit→sync 工作流；不含检索用法（见 querying-brain-first）与自动建图（见 building-typed-link-graph）。

Skills 资源技能包

benchmarking-retrieval-quality

用 BrainBench 跑 GBrain 完整检索管线对比 BM25 baseline 的 P@5 / R@5 检索质量评测。Use when 需要量化衡量 brain 的检索召回质量、拿 gbrain 完整管线与 grep-only baseline 做 side-by-side、复现 P@5/R@5 数字、或判断某个检索基准数字能不能拿来横评别的记忆系统时。涵盖 gbrain-evals 仓库、bun run eval:run:dev、P@5/R@5 解读、self-produced ablation 的批判性使用与该用哪些第三方数据集做横评。

Skills 资源技能包

building-typed-link-graph

用零 LLM 的正则 cascade 从 markdown wikilink 自动建带类型的知识图谱，并用 graph-query / backlinks 遍历。Use when 需要从页面里的 wikilink 自动抽出 founded/invested_in/advises/works_at/mentions/attended 等 typed-link、查一个实体的邻居图谱、做反向引用查询、或排查 typed-link 类型推断不符预期（如被相邻 verb 污染）时。涵盖 gbrain put 触发 verb cascade、graph-query 多跳遍历、backlinks JSON、meeting 页面 ATTENDED 特殊路径、per-edge context 污染的数据设计规避。

Skills 资源技能包

deploying-gbrain-runtime

在一台干净机器上从零部署 GBrain second-brain 运行时并跑通首次检索。Use when 需要安装 GBrain、初始化 PGLite brain、配置 DashScope embedding、或排查 Bun 全局缓存装到旧版本、DashScope 国内端点被拒、gbrain 命令卡死这类部署故障时。涵盖依赖安装、缓存陷阱绕过、embedding provider 配置、China endpoint 源码补丁、doctor 校验、首次 put/search/query；不含 brain 内容建模（见 authoring-brain-pages）与检索用法（见 querying-brain-first）。

Skills 资源技能包

developing-gbrain-skill

用 GBrain 的 skillify 工具链开发一个自定义 skill——scaffold 骨架、填空替换 sentinel、check-resolvable 与 routing-eval 双质量门、注册路由并真实触发。Use when 需要给 brain 新增一个自定义功能扩展、走完 skill 从骨架到触发的完整生命周期、修复 SKILLIFY_STUB 未替换或路由准确率不足、或在 RESOLVER.md/AGENTS.md 注册 trigger 时。涵盖 skillify scaffold、SKILLIFY_STUB sentinel、check-resolvable --strict、routing-eval Top-1 accuracy、MECE 路由纪律、deterministic script 触发验证。

Skills 资源技能包

operating-minions-queue

在 Postgres 后端上运行 GBrain 的 Minions 持久化任务队列，用 supervisor 实现 worker crash 自动恢复。Use when 需要给长时间运行的异步任务（enrichment、embed 等）加崩溃恢复能力、切到 Postgres 后端起 supervisor、提交/监控 job、模拟 kill worker 验证 durability、或理解 9-status 状态机与 exponential backoff 时。涵盖 Postgres 容器 + gbrain init --supabase、supervisor 生命周期、job 提交与 lock_token、kill -9 crash 恢复、backoff 曲线、优雅停止；不含 dream/enrichment 的 phase 逻辑（见 running-dream-cycle）。

Skills 资源技能包

organizing-multi-brain-sources

用 GBrain 的 brain 轴（数据库边界）与 source 轴（同库内容仓）两轴正交模型组织多个 brain 与多来源数据。Use when 需要把知识拆成互相隔离的多个 brain（如个人/团队）、在同一 brain 内让同 slug 的不同来源内容共存、注册跨 brain 挂载、写 cross-brain fan-out 检索脚本、或排查 GBRAIN_HOME/GBRAIN_SOURCE 路由不生效时。涵盖 GBRAIN_HOME 建库与隔离、mounts add 注册、fan-out 联合检索、GBRAIN_SOURCE 分源写入、import 无 --source flag 的绕过。

Skills 资源技能包

querying-brain-first

按 brain-first 4 步序列（search→query→get→external fallback）在调外部 API 之前先查 brain，并封装成可复用脚本。Use when Agent 要从 brain 检索一条事实、决定该用 keyword 还是 hybrid 检索、判断 brain 命中还是该走外部 fallback、或把「先查自己脑库再问外面」做成可重用查询例程时。涵盖 gbrain search / query --no-expand / get 的 cost-speed 递进、brain miss 双形态（干净 miss vs 语义错误 match）、fallback 判定的 LLM relevance 必要性；不含向量索引启用与检索调优（见 tuning-hybrid-retrieval）。

Skills 资源技能包

recovering-brain-database

从损坏的 PGLite brain 数据库或软删除的页面中恢复一个可用的 GBrain brain。Use when 所有 gbrain 命令报 "PGLite failed to initialize its WASM runtime. Original error: Aborted()"、某个 page 处于 soft-deleted 状态导致 put 报 "attempted to delete invisible tuple"、或强制 kill gbrain 后数据目录进入 crash recovery 状态时。涵盖损坏数据目录的备份重建、从 markdown 回放、restore_page 恢复软删除页面、PGLite 单 writer 局限。

Skills 资源技能包

running-dream-cycle

跑 GBrain 的 dream cycle 离线维护循环，触发 16 phase 的 enrichment 与 cross-session 整合。Use when 需要手动跑 gbrain dream 让 brain 自我整理、预览 16 个 phase 的调度清单、配置 synthesize 语料目录、理解为何 fresh brain 首次 dream 无变化、或验证 dream 幂等性时。涵盖两个 API key（DashScope embed + Anthropic synthesize/patterns/propose_takes）、dry-run 预览、真跑与耗时、16 phase 语义、idempotent 机制；不含把 dream 注册成后台守护进程（见 scheduling-brain-autopilot）。

Skills 资源技能包

scheduling-brain-autopilot

把 GBrain 的 dream cycle 注册成 launchd/systemd 后台守护进程，实现按健康度自适应间隔的自动维护。Use when 需要让 brain 在无人操作时自动跑 dream、安装/查询/卸载 autopilot daemon、给非交互 shell 的 daemon 注入 API key、或排查 daemon 跑了但 embed 缺 key 这类问题时。涵盖 autopilot --install/--status/--uninstall 生命周期、~/.zshenv 密钥注入、score 自适应间隔、双日志调试；不含 dream cycle 本身的 phase 机制（见 running-dream-cycle）。

Skills 资源技能包

serving-brain-over-mcp

把 GBrain brain 通过 MCP 协议暴露给 Claude Code、Cursor、Windsurf 等 AI 工具，或以 HTTP 模式接远程客户端。Use when 需要让 AI 编辑器直接查询/操作 brain、注册 stdio MCP server、查看暴露的工具清单、起 HTTP + Admin Dashboard、或换一个 brain 而不重配 MCP 时。涵盖 claude mcp add stdio 接入、--tools-json 工具发现、gbrain call 等价调用、HTTP 模式与 OAuth、Cursor/Windsurf 配置、thin-wrappers 一致性、GBRAIN_HOME 换库。

Skills 资源技能包

tuning-hybrid-retrieval

启用向量索引、用 whoknows --explain 拆解检索打分、切换 search mode 调 GBrain 的 7 阶段 hybrid 检索管线。Use when 需要给 brain 建 embedding 让 hybrid 检索可用、对比 BM25 与 hybrid 的召回差异、看某条结果为何得这个分、切换 conservative/balanced/tokenmax 搜索模式、或核对 --explain / --no-graph / --mode 这些 flag 的真实 CLI 行为时。涵盖 embed --stale、whoknows factor 分解、graph_augment 关系召回、3 mode 与 cost 权衡；不含基础 4 步查询序列（见 querying-brain-first）与批量评测（见 benchmarking-retrieval-quality）。

Skills 资源技能包

applying-builtin-middleware

给 LangChain Agent 一行声明挂上开箱即用的内置 middleware，直接获得模型与工具调用限流、敏感信息脱敏、失败重试、模型降级等横切能力。Use when 需要控住 Agent 的模型调用成本、防止失控循环、把用户消息里的邮箱手机号挡在模型之外、给不稳定的工具加自动重试、或排查「内置 middleware 参数报 TypeError」「脱敏没生效」这类问题时。涵盖内置清单、限流参数与超限行为、脱敏内置类型与自定义正则、重试与降级签名差异；不含自己写钩子（见 writing-agent-middleware）与人工审批（见 gating-agent-actions-with-approval）。

Skills 资源技能包

bootstrapping-langchain-env

在一台干净机器上从零装好 LangChain v1 生态、配好大模型凭证，并跑通第一个 create_agent 工具调用循环示例。Use when 需要初始化 LangChain 开发环境、排查 Python 版本不达标、pip 装完不确定装到哪个版本、模型不发起工具调用这类环境层故障时。涵盖 Python 版本核对、虚拟环境隔离、分层包安装、版本核验、API Key 安全注入、首个示例验收；不含 Agent 的写法与参数体系（见 building-tool-calling-agent）。

Skills 资源技能包

building-agentic-rag

把一批本地文档变成向量知识库，包成检索工具交给 LangChain Agent，让模型自己决定何时检索、检索什么、要不要换关键词重查。Use when 需要给 Agent 外接私有知识库做问答（产品手册、公司制度、技术文档、个人笔记）、要把固定的先检索再作答改造成自主检索、或排查「中文检索返回的全是不相关文档」「导入向量化依赖报 UnicodeDecodeError」这类问题时。涵盖文档切分、向量化与入库、检索器封装成工具、Agent 组装与自主改写观察、embedding 选型、换知识库复用；不含检索结果质量门控（见 grading-retrieved-documents）。

Skills 资源技能包

building-long-horizon-agent

用 deepagents 的 create_deep_agent 搭一个能扛十几步以上长链路任务的智能体，自动获得待办清单规划、子智能体委派与虚拟文件暂存三大机制。Use when 任务超过三步、需要多源资料汇总或分章节写作或多步数据处理、要防止 Agent 走到后面忘了前面的计划、要防止中间数据把上下文撑爆、或排查「长任务抛 GraphRecursionError」「不传模型参数报弃用」这类问题时。涵盖安装与接口核对、最小示例、待办清单驱动、子智能体定义与委派、虚拟文件读写、换任务复用、三层抽象选型；不含单步工具调用 Agent（见 building-tool-calling-agent）与自定义中间件（见 writing-agent-middleware）。

Skills 资源技能包

building-tool-calling-agent

用 LangChain v1 的 create_agent 把一组业务函数组装成能自主调用工具的智能体，并从消息流里逐步核对它每一步做了什么。Use when 需要搭一个会调工具的 Agent、把已有业务函数接给模型、给 Agent 加新能力、或排查「模型不调工具 / 反过来追问参数 / 组装时报 must have a docstring」这类问题时。涵盖工具函数规范、create_agent 组装、invoke 与 stream 两种调用、单工具与并行多工具消息流解读、扩能力复用；不含结构化输出（见 extracting-structured-output）与多轮记忆（见 persisting-agent-memory）。

Skills 资源技能包

deploying-langfuse-selfhost

用 Docker Compose 在本机起一整套自托管的 Langfuse 可观测服务栈，并让它在首次启动就自动预置好组织、项目与 API Key。Use when 需要一个数据不出境的 LLM 追踪后端、要给 Agent 准备上报目标、或排查「postgres 端口绑定失败」「LANGFUSE_INIT 变量不生效没建出项目」「trace 到了后端却无法持久化」「浏览器访问 localhost:3000 返回 502」这类部署故障时。涵盖编排文件获取、端口冲突改法、初始化变量链、密码一致性、代理绕过、启动后验证与取 API Key；不含把 Agent 接上上报（见 tracing-langchain-agent）。

Skills 资源技能包

extracting-structured-output

让 LangChain Agent 不返回自由文本，而是返回经 Pydantic 校验、下游程序可直接按字段取值的结构化对象。Use when 需要从文本里抽字段（评论分类、订单要素、简历解析、工单分级）、要把模型输出接进统计或数据库、或排查「让模型输出 JSON 结果却是中文键名与字符串数字」「ProviderStrategy 报 400 This response_format type is unavailable now」这类问题时。涵盖 schema 定义、response_format 配置、structured_response 消费、两种策略选型与兼容边界、批量抽取；不含工具调用循环本身（见 building-tool-calling-agent）。

Skills 资源技能包

gating-agent-actions-with-approval

给 LangChain Agent 的不可逆动作加一道人工审批闸门：工具执行前暂停、把审批信息抛给人、批准才继续、拒绝就不执行。Use when 需要让 Agent 在退款、转账、删数据、发邮件这类高危操作前等人点头，或排查「暂停没触发」「审批被绕过」「续跑时副作用重复发生」「续跑报 TypeError string indices must be integers」这类问题时。涵盖危险工具改造、暂停信号判定、批准与拒绝两条续跑路径、节点重执行行为、四条工具编写纪律；不含存档器本身的用法（见 persisting-agent-memory）。

Skills 资源技能包

grading-retrieved-documents

给知识库问答加一道评分门控：每次检索后逐篇判断文档与问题是否相关，相关就作答、全不相关就改写查询重试，重试到上限仍无命中就明说知识库里没有。Use when 需要防止 Agent 拿知识库里根本没有的内容编答案、要给检索改写循环设一个明确的停止条件、或排查「with_structured_output 在国产模型上报 400 This response_format type is unavailable now」时。涵盖评分模型定义、结构化判断的兼容写法、停止与改写的判定规则、重试上限与兜底、有无门控的效果对比；不含知识库与检索器的搭建（见 building-agentic-rag）。

Skills 资源技能包

inspecting-checkpoint-state

打开 LangChain Agent 的会话存档，用 get_state 与 get_state_history 看清某一会话当前存了什么、每一步产生了哪些快照，并从指定历史快照重放继续对话。Use when 需要调试「Agent 记住了什么 / 为什么答错」、审计一次会话的完整消息与执行位置、做时间旅行重放对比、或排查「从历史点重放报 400 an assistant message with tool_calls must be followed by tool messages」时。涵盖状态快照字段解读、消息历史展开、快照时间线、稳态快照筛选与重放；不含如何给 Agent 加记忆（见 persisting-agent-memory）。

Skills 资源技能包

persisting-agent-memory

给 LangChain Agent 挂上 checkpointer 与 thread_id，让它在同一会话里记住前文、不同用户之间互不串台，并按需从内存存档升级到重启不丢的持久化存档。Use when 需要把一问一答的 Agent 变成多轮连续对话、做多用户会话隔离、让记忆在进程重启后仍在、或排查「Agent 忘了上一句」「两个用户记忆串台」「SQLite 存档报文件锁错误」这类问题时。涵盖 checkpointer 挂载、thread_id 会话隔离、三档存储选型与迁移、跨进程持久化验证；不含查看存档内部与历史重放（见 inspecting-checkpoint-state）。

Skills 资源技能包

tracing-langchain-agent

给已有的 LangChain / LangGraph Agent 挂上追踪回调，把一次请求背后的模型与工具调用链完整上报，并在面板上逐节点读出输入、输出、消耗与错误。Use when 需要看清 Agent 内部到底调了什么、定位某次工具调用为什么失败、评估一次请求的 token 与延迟、或排查「追踪没上报到后端」「连接校验超时」「导入 CallbackHandler 报错」这类接入故障时。涵盖 SDK 安装与导入路径、四个环境变量、回调挂载、调用树三类节点解读、失败链路定位、自托管与云服务两条路径选型；不含追踪后端的部署（见 deploying-langfuse-selfhost）。

Skills 资源技能包

writing-agent-middleware

用 LangChain v1 的 middleware 钩子把日志、审计、错误兜底、合规拦截这类横切逻辑写成独立单元，声明式挂到任意 Agent 上而不改工具与主流程。Use when 需要给 Agent 加自定义日志或审计、在调模型前拦截违禁内容、让工具抛错时 Agent 不崩溃、或排查「hook 触发次数比预期多」「wrap_tool_call 报 execute() missing 1 required positional argument」「用了 jump_to 却运行时报错」这类问题时。涵盖装饰器式与类式写法、六个钩子的时机、执行顺序规律、工具错误接管、提前退出、跨 Agent 复用；不含开箱即用的内置 middleware（见 applying-builtin-middleware）。