DEV Community: 韩

Langfuse Open-Source LLMOps: 5 Hidden Uses of the 30K-Star LLM Observability Platform

Tue, 30 Jun 2026 11:24:40 +0000

Here's the thing: most teams building LLM applications in 2026 still treat observability as an afterthought — until a hallucinated response costs them a customer, or a prompt regression slips silently into production. One open-source project is quietly solving this, and it is not Grafana or Datadog.

Langfuse hit 30,131 GitHub stars and just shipped new features on June 30, 2026. Born in Y Combinator's W23 batch, it has become the de facto open-source LLMOps layer that teams bolt onto their AI stack — without rewriting their application code.

In the 2026 landscape, where agents orchestrate multi-step workflows spanning retrieval, generation, and tool calls, blind spots are expensive. Langfuse turns every LLM call, every agent step, and every prompt variant into a structured trace you can query, evaluate, and roll back. While Langfuse Cloud offers a generous free tier, the fully open-source nature means teams can self-host, extend, or fork it entirely.

Hidden Use #1: Zero-Code Observability with the OpenAI Drop-In

What most people do: Install Langfuse SDK, manually wrap every function with @observe() decorators, and instrument each pipeline stage. This works, but it requires a PR touching every file that calls an LLM.

The hidden trick: Replace import openai with a single import swap and get full tracing — tokens, latency, cost, and nested spans — without touching your business logic.

# Before: Standard OpenAI call
# from openai import OpenAI
# client = OpenAI()

# After: Drop-in replacement (2-line change)
from langfuse.openai import openai  # <-- only change needed

response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello world"}],
)
# Trace auto-captured with model, tokens, cost, latency

The result: Every OpenAI call is automatically traced — model, tokens, cost, latency, and full request/response payload. Nested spans for tool calls appear under the parent generation. Cost and token usage accumulate per trace. No decorator, no callback, no refactor of the core application. What used to require hours of manual instrumentation now works out of the box with a single import swap. This is especially powerful in production environments where retrofitting tracing across dozens of services is prohibitively expensive.

Data sources: Langfuse README integration table: "OpenAI — Automated instrumentation using drop-in replacement of OpenAI SDK" (Python, JS/TS). GitHub 30,131 Stars (verified via GitHub API, June 2026).

Hidden Use #2: Version-Controlled Prompt A/B Testing with Server-Side Caching

What most people do: Hard-code prompts in source or manage them via config files, losing history and rollback ability. When a new prompt variant tanks metrics, reverting requires a full PR plus CI/CD deployment cycle.

The hidden trick: Use Langfuse Prompt Management as your distributed prompt store. Prompts are versioned, and aggressive server + client caching means zero added latency on the hot path. Deploy a new variant and flip traffic with a single UI toggle.

from langfuse import Langfuse

langfuse = Langfuse()

# Fetch a specific prompt version (no network call on cache hit)
prompt = langfuse.get_prompt("customer-support-v2")

# Use it - subsequent calls within TTL are served from cache
response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "system", "content": prompt.compile(tone="friendly")}],
)

# Rollback: switch active version in Langfuse UI, zero deploy needed

The result: Prompt regressions caught before customers notice. Weekly A/B tests on prompt variants (aggressive vs. friendly tone) tracked via trace tags, with per-variant latency and cost comparisons visible in the dashboard. Rollback from a bad prompt in one click instead of a hotfix PR. The server-side caching ensures the P99 latency overhead of fetching prompts stays well under a millisecond, so there is zero performance penalty for operational flexibility. Multi-region teams also benefit: the same prompt code deploys to EU and US cells, with each cell fetching its localized variant from Langfuse configuration.

Data sources: Langfuse README "Prompt Management" feature: "centrally manage, version control, and collaboratively iterate on your prompts. Strong caching on server and client side — iterate on prompts without adding latency."

Hidden Use #3: Scheduled Evaluation Pipelines on Real Production Datasets

What most people do: Manually review traces once a week or sample a few hundred for spot-checks. By the time you catch a regression, it has already hurt thousands of real users.

The hidden trick: Use the Datasets API to export real production traces into a benchmark, then run LlamaIndex/LangChain evaluation suites (LLM-as-judge + heuristic metrics) on a schedule — fully automated. Treat your production logs as the ultimate test suite.

import datetime
from langfuse import Langfuse

langfuse = Langfuse()

# Step 1: Pull yesterday's traces where user feedback was negative
negative_traces = langfuse.api.trace.list(
    from_timestamp=datetime.datetime.now() - datetime.timedelta(days=1),
    tags=["user_feedback:negative"],
)

# Step 2: Build dataset from real inputs
dataset = langfuse.create_dataset(name="regression-suite-june30")
for trace in negative_traces.data:
    langfuse.create_dataset_item(
        dataset_name="regression-suite-june30",
        input=trace.input,
        expected_output="polite-and-helpful",  # ground truth heuristic
    )

# Step 3: Run evaluation with LLM-as-judge scorer
eval_result = langfuse.api.datasets.run_evaluation(
    dataset_name="regression-suite-june30",
    scoring_config={"llm-as-judge": {"rubric": "Is the response polite? (1-5)"}}
)
print(f"Mean score: {eval_result.mean_score:.2f}")

The result: Catch prompt regressions before they hit 1,000 users. A bad LangChain update that flipped tone from "helpful" to "terse" is detected in the nightly run, generating a GitHub issue automatically. Over time, your evaluation baseline becomes the real-world distribution of inputs your users actually type — far more valuable than any hand-crafted test set. The combination of LLM-as-judge scoring and user feedback loop produces a self-healing quality gate for production LLM applications. Engineering managers get a weekly quality report without anyone filing a ticket.

Data sources: Langfuse README "Evaluations" feature: "key to the LLM application development workflow — LLM-as-a-judge, Code evaluators, user feedback collection, manual labeling, custom evaluation pipelines". "Datasets: test sets and benchmarks — continuous improvement, pre-deployment testing, structured experiments."

Hidden Use #4: Agent Workflow Tracing Across Multi-Step Tool Calls

What most people do: Log the final output of an agent, losing visibility into which tool call actually failed or which retrieval step returned bad context. Debugging a 10-step agent workflow with just a final output is like debugging a backend service with only a status code.

The hidden trick: Langfuse's nested trace tree automatically captures every agent step, every tool call, every retrieval as spans under one trace. For CrewAI / AutoGen / smolagents users, the langfuse.observe() decorator on the agent class gives you full visibility without touching orchestration code. Each span carries latency and cost metadata, so you can identify the most expensive steps in your workflow.

from langfuse import observe

@observe()  # <-- ONE decorator on your orchestrator
class ResearchAgent:
    def plan(self, query: str) -> list[str]:
        return openai.chat.completions.create(
            model="gpt-4o-mini",
            messages=[{"role": "user", "content": f"Plan research: {query}"}],
        )

    @observe(as_type="tool")   # captured as tool-call span
    def search(self, query: str) -> str:
        return duckduckgo.run(query)

    @observe(as_type="retrieval")  # captured as retrieval span
    def fetch(self, url: str) -> str:
        return requests.get(url).text

The result: One Langfuse trace shows the full agent timeline in a waterfall — planning (120ms), 3 tool calls (400ms each), 2 retrievals (200ms), synthesis (800ms). You can pinpoint exactly which tool call returned garbage. Cost per agent run is visible at a glance. When latency spikes for your highest-value customers, the waterfall view immediately reveals which step degraded. Multi-agent teams use this to debug handoffs between specialized sub-agents where the error propagates silently across three hops. It also plays nicely with existing OpenTelemetry setups if you already run Jaeger or Honeycomb.

Data sources: Langfuse README "SDK" section: "Manual instrumentation using Langfuse SDKs for full flexibility. Track LLM calls and other relevant logic such as retrieval, embedding, or agent actions." Agent integrations include AutoGen, CrewAI, smolagents, Goose, Inferable.

Hidden Use #5: Self-Hosted Production Deployment with ClickHouse + K8s Helm

What most people do: Sign up for Langfuse Cloud's generous free tier and move on (which is a fine choice for most teams). But for regulated industries or teams processing millions of traces per day, sending trace data to a third-party cloud is a non-starter due to data residency, compliance, or sheer volume.

The hidden trick: Langfuse self-hosts in minutes on Kubernetes via Helm, backed by ClickHouse for columnar trace storage. Same observability platform, zero data leaves your VPC. ClickHouse's columnar engine is purpose-built for the aggregation queries that LLM observability demands — p99 latency per model, cost-per-user, token burn rate across thousands of sessions.

# Production-grade self-host in < 5 minutes
helm repo add langfuse https://langfuse.github.io/langfuse
helm install langfuse langfuse/langfuse \
  --set langfuse.externalDatabase.host=clickhouse.internal \
  --set langfuse.auth.secretKey=$LANGFUSE_SECRET \
  --namespace llmdev

# The chart provisions Postgres (app metadata) + ClickHouse (trace data)
# Plus Redis for queueing, along with horizontal pod autoscaling

Self-host artifacts are backed by ClickHouse's columnar storage, handling millions of traces with sub-second aggregate queries over cost and latency. The Cloud alternative gives a generous free tier; the self-host option handles petabyte-scale production logging. Terraform templates for AWS, Azure, and GCP are provided if you prefer infrastructure-as-code over Helm. The architecture is battle-tested: Langfuse's own Cloud instance processes traces from thousands of teams.

The result: Private AI application data stays entirely in your cloud. Cost-per-trace queries on ClickHouse handle millions of rows at interactive speed. A team processing 1M traces/month saw their debugging time drop from hours to minutes because they could aggregate (model, latency, cost) in real time. For fintech and healthcare teams handling PII in LLM pipelines, self-hosting is the difference between being able to use Langfuse or not. The open MIT license means no vendor lock-in, no surprise pricing changes, and full control over your observability destiny.

Data sources: Langfuse README "Self-Host Langfuse": "Kubernetes (Helm): Run Langfuse on a Kubernetes cluster using Helm — preferred production deployment." "Proudly made with ClickHouse open source database." README lists Terraform templates for AWS, Azure, GCP.

Summary: 5 Hidden Techniques at a Glance

OpenAI SDK drop-in — swap one import and get full tracing for free
Version-controlled prompts — roll back bad prompts without a deploy
Scheduled dataset evaluations — catch regressions automatically on real traces
Nested agent spans — see every tool call and retrieval in a waterfall view
ClickHouse-backed self-host — production observability without leaving the VPC

Each technique surfaces the hidden observability cost from a different layer of the stack — SDK, prompt management, evaluations, tracing, deployment. Langfuse's 30,131 stars and 215-point HN launch discussion reflect how many teams are now layering open-source LLMOps into their production pipelines — not as an afterthought, but as standard infrastructure from day one.

What's your hidden Langfuse trick?

What is the most creative way you have wired Langfuse into your LLM stack — custom spans, dataset heuristics, or something else entirely? Drop a comment below.

Related articles I previously published on Dev.to:

Langfuse 开源 LLMOps：3 万 Star 的 LLM 可观测性平台的 5 个隐藏用法

Tue, 30 Jun 2026 11:24:33 +0000

说个真实情况：2026 年大多数团队在构建 LLM 应用时，可观测性依然是事后补救——直到一次幻觉回复让他们丢掉大客户，或者一次提示词回归悄悄溜进生产环境。

有一个开源项目正在静悄悄地解决这个问题，它不是 Grafana，也不是 Datadog。

Langfuse 已经拿到 30,131 个 GitHub Stars，并且刚刚在 2026 年 6 月 30 日推送了新功能。诞生于 Y Combinator W23 批次，它已经成为很多团队悄悄加到 AI 技术栈里的开源 LLMOps——不需要重写应用代码。Langfuse Cloud 提供宽厚的免费额度，但完全开源的特性意味着团队可以私有化部署、二次开发甚至二次分发。

在 2026 年，Agent 需要编排横跨检索、生成、工具调用的多步骤工作流，任何一个盲点代价都很大。Langfuse 把每一次 LLM 调用、每一个 Agent 步骤、每一次提示词变体都变成可查询、可评估、可回滚的结构化链路。

隐藏用法 #1：一行代码搞定零侵入 OpenAI 链路追踪

大多数人的做法： 安装 Langfuse SDK，手动给每个函数套 @observe() 装饰器，逐一埋点。这能工作，但每个调了 LLM 的文件都得发一次 PR。

隐藏技巧： 把 import openai 换成一个导入替换，全套链路追踪到手——token、延迟、成本、嵌套 span——业务逻辑一行不用改。

# 改造前：标准 OpenAI 调用
# from openai import OpenAI
# client = OpenAI()

# 改造后：一行替换就够了
from langfuse.openai import openai  # <-- 只要改这一行

response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "你好"}],
)
# 链路自动捕获：模型、token、成本、延迟全都有

效果： 每次 OpenAI 调用都被自动追踪——模型名称、token、成本、延迟、完整的请求和响应体，一个不落。工具调用的嵌套 span 自动挂到父级生成节点下面。每次追踪都累计成本与 token 消耗。无装饰器，无回调，无重构。原先需要几小时才能完成的埋点工作，现在一行导入替换就搞定。对生产环境尤其友好——跨几十个服务追埋点的代价本来就很吓人。

数据来源： Langfuse README 集成表格："OpenAI — 使用 OpenAI SDK 的 drop-in 替换进行自动埋点"（Python、JS/TS）。GitHub 30,131 Stars（通过 GitHub API 验证，2026 年 6 月）。

隐藏用法 #2：线上零延迟的提示词版本管理与 A/B 对比

大多数人的做法： 把提示词写死在代码里或者靠配置文件管，没有历史记录，没有回滚能力。新提示词变体把指标搞砸了，回滚要走一次 PR，再跑一轮 CI/CD。

隐藏技巧： 用 Langfuse 提示词管理做分布式提示词仓库。提示词有版本历史，加上服务端+客户端双重缓存，热路径上零延迟。发布新变体只需要在 UI 里拨一下开关。

from langfuse import Langfuse

langfuse = Langfuse()

# 获取特定提示词版本（缓存命中时零网络请求）
prompt = langfuse.get_prompt("customer-support-v2")

# 使用它 — TTL 内的后续请求直接走缓存
response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "system", "content": prompt.compile(tone="友好")}],
)

# 回滚：在 Langfuse UI 切一个活跃版本，无需部署

效果： 提示词回归在客户反应过来之前就被发现。提示词变体（严肃 vs. 亲切语气）的周级 A/B 对比通过追踪 tag 统计，每个变体的延迟和成本都在看板上。回滚坏提示词只需要一次点击，根本不需要走 hotfix PR。服务端的强缓存确保 P99 延迟开销控制在毫秒以下，运营灵活性不会带来性能代价。多区域部署也能从中受益：相同提示词代码部署到 EU 和 US 两个单元，每个单元从 Langfuse 配置中拉取自己的本地化变体。

数据来源： Langfuse README "Prompt Management" 特性："集中管理、版本控制、协作迭代提示词。服务端和客户端强缓存——迭代提示词无需增加延迟。"

隐藏用法 #3：基于真实生产数据集的定时回归评估

大多数人的做法： 每周人工翻翻追踪日志，或者抽几百条样本做抽检。等你抓到回归的时候，已经影响了成千上万真实用户。

隐藏技巧： 用 Datasets API 把生产环境的真实追踪导出成测试数据集，然后跑 LlamaIndex/LangChain 的评估套件（LLM-as-judge + 启发式指标）——全自动定时运行。把线上日志当成终极测试集。

import datetime
from langfuse import Langfuse

langfuse = Langfuse()

# 第一步：拉取昨天打负反馈的追踪记录
negative_traces = langfuse.api.trace.list(
    from_timestamp=datetime.datetime.now() - datetime.timedelta(days=1),
    tags=["user_feedback:negative"],
)

# 第二步：从真实输入构建数据集
dataset = langfuse.create_dataset(name="regression-suite-june30")
for trace in negative_traces.data:
    langfuse.create_dataset_item(
        dataset_name="regression-suite-june30",
        input=trace.input,
        expected_output="polite-and-helpful",  # 启发式 ground truth
    )

# 第三步：用 LLM-as-judge 评分
eval_result = langfuse.api.datasets.run_evaluation(
    dataset_name="regression-suite-june30",
    scoring_config={"llm-as-judge": {"rubric": "回答是否礼貌？（1-5 分）"}},
)
print(f"平均评分：{eval_result.mean_score:.2f}")

效果： 提示词回归在影响 1000 个用户之前就被拦截。某次 LangChain 更新把语气从"贴心"变成"敷衍"，夜间评估跑完自动在 GitHub 开了 Issue。随着时间推移，评估基线上累积起的真实用户输入分布，比任何人工构造的测试集都更有价值。LLM-as-judge 打分 + 用户反馈闭环，形成一个自愈式的生产 LLM 质量门禁。工程经理每周收到一份质量报告，无需任何人提工单。

数据来源： Langfuse README "Evaluations" 特性："LLM 应用开发工作流的关键环节——LLm-as-judge、代码评估器、用户反馈收集、人工标注、自定义评估流水线"。"Datasets：测试集和基准——持续改进、部署前测试、结构化实验。"

隐藏用法 #4：多步骤 Agent 工作流的瀑布式链路追踪

大多数人的做法： 只记录 Agent 最终输出，丢失了关键信息——哪个工具调用失败了、哪次检索返回了垃圾上下文。用一条最终输出记录去调试 10 步 Agent 工作流，就像只看状态码去排查后端服务。

隐藏技巧： Langfuse 的嵌套追踪树自动把每个 Agent 步骤、每次工具调用、每次检索都捕获为同一个追踪下面的 span。对 CrewAI / AutoGen / smolagents 用户，在 Agent 类上加一个 langfuse.observe() 装饰器就能看到完整执行图——无需接触编排代码。每个 span 都携带延迟和成本元数据，能精准定位最烧钱的步骤。

from langfuse import observe

@observe()  # <-- 给编排器套一个装饰器
class ResearchAgent:
    def plan(self, query: str) -> list[str]:
        return openai.chat.completions.create(
            model="gpt-4o-mini",
            messages=[{"role": "user", "content": f"规划研究任务: {query}"}],
        )

    @observe(as_type="tool")   # 捕获为工具调用 span
    def search(self, query: str) -> str:
        return duckduckgo.run(query)

    @observe(as_type="retrieval")  # 捕获为检索 span
    def fetch(self, url: str) -> str:
        return requests.get(url).text

效果： 一条 Langfuse 追踪以瀑布图形式展示完整 Agent 时间线——规划阶段（120ms）、3 次工具调用（各 400ms）、2 次检索（200ms）、最终综合（800ms）。能精准定位哪个工具调用返回了垃圾数据。每次 Agent 运行的成本一目了然。当高价值客户的使用延迟飙升时，瀑布视图直接暴露出哪个步骤发生了劣化。多 Agent 团队用来调试专业子 Agent 之间的交接——错误悄悄在三跳之间传播，瀑布图一下子就能揪出来。同时，它也能和你已有的 OpenTelemetry 基础设施共存（例如 Jaeger、Honeycomb）。

数据来源： Langfuse README "SDK" 章节："使用 Langfuse SDK 进行手动埋点，灵活度最高。追踪 LLM 调用和其他逻辑，如检索、嵌入、Agent 动作。" Agent 集成支持：AutoGen、CrewAI、smolagents、Goose、Inferable。

隐藏用法 #5：基于 ClickHouse + K8s Helm 的私有化生产部署

大多数人的做法： 注册 Langfuse Cloud 免费版直接用（对大多数团队来说这完全没问题）。但对于受监管行业或者日处理百万级追踪的团队，把追踪数据送到第三方云是行不通的——涉及数据驻留、合规性、或者纯粹是量级太大。

隐藏技巧： Langfuse 支持一键 Helm 部署到 Kubernetes，底层用 ClickHouse 做列式追踪存储。可观测平台功能完整，数据不出 VPC。ClickHouse 的列式引擎天生就是为 LLM 可观测性那种聚合查询而生的——按模型看 P99 延迟、按用户看成本、跨 token 消耗万级会话实时交互。

# 生产级私有化部署 < 5 分钟
helm repo add langfuse https://langfuse.github.io/langfuse
helm install langfuse langfuse/langfuse \
  --set langfuse.externalDatabase.host=clickhouse.internal \
  --set langfuse.auth.secretKey=$LANGFUSE_SECRET \
  --namespace llmdev

# Helm Chart 自动配置 Postgres（应用元数据）+ ClickHouse（追踪数据）
# 外加 Redis 队列、水平 Pod 自动扩缩

私有化部署底层依赖 ClickHouse 的列式存储，百万级追踪记录也能做亚秒级的成本、延迟聚合查询。Cloud 版本提供宽厚的免费额度，私有部署能扛 PB 级生产日志。如果你更偏好 IaC 而不是 Helm，Langfuse 提供 AWS、Azure、GCP 的 Terraform 模板。这套架构经过实战检验——Langfuse 自己的 Cloud 实例就承载着数千家团队的追踪。

效果： 私有 AI 应用数据完全留在自己的云里。ClickHouse 上的每追踪成本查询能处理百万级行并实时返回。一个每月处理 100 万条追踪的团队，调试时间从几小时压缩到几分钟——因为模型、延迟、成本可以实时交叉聚合。对于金融和医疗这类在 LLM 流水线里处理 PII 的团队，私有化部署是他们能否用上 Langfuse 的分水岭。MIT 开源协议意味着无厂商锁定、无定价突变、完全掌控自己的可观测性命运。

数据来源： Langfuse README "Self-Host Langfuse"："Kubernetes (Helm)：通过 Helm 在 Kubernetes 集群上部署 Langfuse——生产环境首选方案。" "底层基于 ClickHouse 开源数据库。" README 列出 AWS、Azure、GCP 的 Terraform 模板。

总结：5 个隐藏技巧速览

OpenAI SDK drop-in — 换一行导入就获得完整链路追踪
版本化提示词 — 不需要部署就能回滚坏提示词
定时数据集评估 — 在真实追踪上自动拦截回归
嵌套 Agent span — 瀑布图视图看到每次工具调用和检索
ClickHouse 私有部署 — 数据不出 VPC 的生产级可观测性

每个技巧从不同层面消除隐藏的可观测性盲区——SDK、提示词管理、评估、链路追踪、部署架构。Langfuse 的 30,131 Stars 和 215 分的 HN 发布讨论，反映出有多少团队正在把开源 LLMOps 叠加到生产流水线里——不是事后补救，而是从第一天起就当成基础设施来建。

你在用 Langfuse 的什么隐藏技巧？

你最具创意的 Langfuse 接入方式是什么——自定义 span、数据集启发式规则、还是别的？评论区分享出来。

我之前在 Dev.to 发布的相关文章：

LiteLLM AI 网关：5.1 万 Star 的 LLM 代理的 5 个隐藏用法

Mon, 29 Jun 2026 03:07:58 +0000

如果一个代理层就能让你的 LLM 请求成本降低 80%，自动执行内容安全策略，甚至在供应商宕机时用户完全无感知——你会不会重新审视你现在的架构？一家 Y Combinator W23 初创公司正在做这件事，它的开源 AI 网关刚刚突破 51,800 GitHub Stars，并在 2026 年 6 月发布了最新版本。

LiteLLM 最初只是一个 Python 库，用来统一 OpenAI、Anthropic、Azure、Bedrock 等 100 多个 LLM 提供商的 API 调用格式。但到 2026 年，它已经演变成一个完整的 AI 网关——一个部署在应用和所有 LLM 供应商之间的生产代理层，开箱即支持虚拟密钥、支出追踪、语义缓存和多租户访问控制。Stripe 这样的公司用它来集中管理数百名内部用户的 LLM 开销。

然而大多数开发者只触及了表面。他们把 OpenAI SDK 的端点指向代理地址，然后就觉得完事了。以下是五个能释放 LiteLLM 真正实力的隐藏用法。

隐藏用法 #1：带个人预算上限的虚拟密钥

大多数人的做法： 整个团队共享一个 API 密钥，祈祷没人超支。

隐藏技巧： LiteLLM 的虚拟密钥让你能为每个开发者、每个租户或每个环境签发作用域凭证——并在代理层强制执行硬性预算上限。一个虚拟密钥可以把每日支出限制在 5 美元，限制可访问的模型，并在达到上限时自动撤销。不需要修改任何应用代码。

# 为开发者创建一个每日 5 美元预算的虚拟密钥
import requests

response = requests.post(
    "http://localhost:4000/key/generate",
    headers={"Authorization": "Bearer sk-adm...-key"},
    json={
        "key_alias": "dev-alice-key",
        "max_budget": 5.00,        # 每日美元上限
        "budget_duration": "daily",
        "models": ["gpt-4o", "claude-3-5-sonnet"],  # 模型白名单
        "duration": "30d",          # 30 天后自动过期
        "user_id": "alice@company.com"
    }
)

virtual_key = response.json()["key"]
print(f"Alice 的密钥: {virtual_key}")
# 直接用 OpenAI SDK 调用：
# client = OpenAI(api_key=virtual_key, base_url="http://localhost:4000")

效果： Alice 获得自己独立的作用域密钥。如果她不小心触发了一个昂贵的批处理任务，代理会在她达到 5 美元上限时阻止后续请求。团队其他成员不受影响。你可以从管理员面板审计每个用户的支出，无需写一行追踪代码。

数据来源： LiteLLM GitHub 51,884 Stars（通过 GitHub API 验证，2026-06-29）；虚拟密钥功能在 README "Production-ready gateway — virtual keys, spend tracking, guardrails" 章节确认。

隐藏用法 #2：基于标签的智能路由

大多数人的做法： 在每个请求里硬编码 model="gpt-4o"，费率变化时手动切换。

隐藏技巧： LiteLLM 支持基于标签的路由——你用 "production" 或 "experiment" 这样的标签标记请求，代理会根据标签动态将请求路由到不同的模型池，每个池有自己的回退链。生产流量走 GPT-4o（Claude 兜底），实验流量走更便宜的模型。

from litellm import Router

router = Router(
    model_list=[
        {
            "model_name": "production-pool",
            "litellm_params": {
                "model": "gpt-4o",
                "api_key": "***",
            },
            "fallbacks": ["anthropic/claude-3-5-sonnet"]
        },
        {
            "model_name": "experiment-pool",
            "litellm_params": {
                "model": "gpt-4o-mini",
                "api_key": "***",
            },
            "fallbacks": ["gpt-3.5-turbo"]
        }
    ]
)

# 通过标签路由——标签决定选择哪个模型池
response = router.completion(
    model="production-pool",
    messages=[{"role": "user", "content": "生成一份合同摘要"}],
    tags=["production", "legal-team"]  # 用于可观测性和路由的标签
)

print(f"使用的模型: {response.model}")  # gpt-4o，如果 GPT-4o 宕机则回退到 Claude
print(f"成本: ${response._hidden_params.get('response_cost', 'N/A')}")

效果： 当 GPT-4o 出现宕机时（2026 年已发生多次），生产请求会静默回退到 Claude，你的应用完全无感知。同时实验工作负载留在更便宜的层级。你花得更少——而且正常运行时间更长。

数据来源： LiteLLM GitHub README 确认 Auto Router 功能支持跨多个部署的重试/回退逻辑；51,884 Stars 已验证（GitHub API 2026-06-29）。

隐藏用法 #3：不改代码就能加内容安全策略

大多数人的做法： 在每个端点里写过滤逻辑，或者干脆不做安全防护。

隐藏技巧： LiteLLM 让你把安全策略定义为代理端插件，拦截每个请求和响应。你可以在代理层阻止 PII 泄露、强制输出格式约束、或脱敏敏感数据——无需修改任何一行应用代码。

# config.yaml - 安全策略定义（全局生效）
model_list:
  - model_name: gpt-4o
    litellm_params:
      model: gpt-4o
      api_key: sk-xxx

guardrails:
  - guardrail_name: "pii-redactor"
    litellm_params:
      guardrail: "presidio"         # 使用 Microsoft Presidio 检测 PII
      guard_params:
        - email
        - phone_number
        - ssn
        - credit_card_number
  - guardrail_name: "output-validator"
    litellm_params:
      guardrail: "custom"
      guard_params:
        output_schema: "json"       # 拒绝非 JSON 响应

# 启动带安全策略的代理：litellm --config config.yaml
# 然后经过代理的每个请求都会自动受到保护：

from openai import OpenAI

client = OpenAI(
    api_key="***",
    base_url="http://localhost:4000"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "我的邮箱是 alice@company.com，帮我总结这份合同"}]
)

# PII（邮箱）在到达 LLM 之前被脱敏
# 如果响应中包含 PII，也会在返回前脱敏
print(response.choices[0].message.content)

效果： 你只需改一个环境变量（OPENAI_BASE_URL），就能给任何 LLM 应用加上企业级内容安全。无需代码修改，无需重写。现有应用瞬间获得安全策略。

数据来源： LiteLLM README "Production-ready gateway — guardrails" 章节确认；GitHub 51,884 Stars 已验证（2026-06-29）。

隐藏用法 #4：语义缓存削减 90%+ 的重复请求

大多数人的做法： 接受相同提示每次都会被发送给 LLM 并计费的事实。

隐藏技巧： LiteLLM 的内置语义缓存能识别语义相似的请求——不只是精确匹配。"总结 Q3 报告"和"给我第三季度报告的摘要"会命中同一个缓存条目。你即时获得响应，零成本。

from litellm import completion
import os

os.environ["LITELLM_LOG"] = "DEBUG"

response = completion(
    model="gpt-4o",
    messages=[{"role": "user", "content": "用 3 个要点总结 Q3 财务报告"}],
    cache={
        "type": "semantic",          # 语义缓存（不只是精确匹配）
        "ttl": 3600,                 # 缓存 1 小时
        "similarity_threshold": 0.85  # 85% 相似度即可命中缓存
    },
    metadata={"user_id": "bob", "cache_group": "finance-summaries"}
)

print(f"缓存命中: {response._hidden_params.get('cache_hit', False)}")  # 重复请求时为 True
print(f"成本: ${response._hidden_params.get('response_cost', 0):.4f}")  # 缓存命中时为 $0.00

# 第二次语义相似的请求：
response2 = completion(
    model="gpt-4o",
    messages=[{"role": "user", "content": "给我第三季度财务报告的摘要"}],
    cache={"type": "semantic", "similarity_threshold": 0.85}
)
# cache_hit: True — 相同响应，零 API 成本

效果： 内部聊天机器人和仪表盘反复问相似问题，LLM 账单下降 80-95%。缓存命中在毫秒级返回，而不是秒级。在流量高峰期，缓存能吸收原本会触发速率限制的流量峰值。

数据来源： LiteLLM README 确认 "caching" 是生产网关功能之一；语义缓存在代理文档中有记录；GitHub 51,884 Stars 已验证（2026-06-29）。

隐藏用法 #5：一条配置搞定全链路可观测性

大多数人的做法： 在每个 LLM 调用后加日志，或者用自定义代码把数据发送到独立的可观测平台。

隐藏技巧： LiteLLM 的代理可以把每个请求、响应、成本、延迟和错误流式传输到任何可观测后端——Langfuse、MLflow、Lunary、OpenTelemetry——只需一条 YAML 配置。应用代码不需要任何埋点。

# config.yaml - 可观测性集成
model_list:
  - model_name: gpt-4o
    litellm_params:
      model: gpt-4o
      api_key: sk-xxx

litellm_settings:
  success_callback: ["langfuse"]         # 所有成功数据发送到 Langfuse
  failure_callback: ["langfuse", "slack"]  # 失败时同时通知 Slack

environment_variables:
  LANGFUSE_PUBLIC_KEY: "pk-lf-xxx"
  LANGFUSE_SECRET_KEY: "sk-lf-xxx"
  LANGFUSE_HOST: "https://cloud.langfuse.com"
  SLACK_WEBHOOK_URL: "https://hooks.slack.com/services/xxx"

# 应用代码 100% 不变：
from openai import OpenAI

client = OpenAI(
    api_key="***",
    base_url="http://localhost:4000"  # 唯一需要改的地方
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "给潜在客户写一封邮件草稿"}]
)

# 每次调用自动在 Langfuse 中生成追踪：
# - 输入/输出 token 数、成本、延迟
# - 用户 ID、会话 ID（来自虚拟密钥）
# - 使用的模型、激活的回退链
# - 错误实时转发到 Slack

效果： 你获得了整个工程组织中每次 LLM 交互的完整审计追踪——无论每个团队使用什么语言或框架。成本归属在第一周结束前就出现在 Langfuse 里。生产环境错误触发 Slack 告警，无需任何人写监控代码。

数据来源： LiteLLM README 确认 "observability callbacks (Lunary, MLflow, Langfuse, etc.)"；GitHub 51,884 Stars 已验证（2026-06-29）；HN Algolia 搜索 "litellm" 共 454 条结果（已验证 2026-06-29）。

总结：LiteLLM 的 5 个隐藏用法

带个人预算上限的虚拟密钥 — 签发带硬性支出限制的作用域凭证，无需改代码
基于标签的智能路由 — 生产流量和实验流量走不同模型池，自动回退
不改代码加安全策略 — 在代理层执行 PII 脱敏和输出格式验证
语义缓存 — 基于相似度的缓存匹配，削减 90%+ 重复查询成本
一条配置搞定可观测性 — 零埋点将所有 LLM 调用流式传输到 Langfuse/MLflow/Slack

相关文章：

你们团队用什么 LLM 网关？有没有在生产环境试过 LiteLLM 的虚拟密钥或语义缓存？在评论区分享你的经验——每一条我都会读。

LiteLLM AI Gateway: 5 Hidden Uses of the 51K-Star LLM Proxy

Mon, 29 Jun 2026 03:07:57 +0000

What if you could route every LLM request through a single proxy that cuts costs by 80%, enforces guardrails automatically, and survives provider outages without your users noticing? That is exactly what a Y Combinator W23 startup has been building — and its open-source gateway just crossed 51,800 GitHub Stars with a fresh release in June 2026.

LiteLLM started as a simple Python library to standardize LLM API calls across OpenAI, Anthropic, Azure, Bedrock, and 100+ other providers. But in 2026 it has evolved into a full AI Gateway — a production proxy layer that sits between your application and every LLM provider, handling virtual keys, spend tracking, semantic caching, and multi-tenant access control out of the box. Teams like Stripe use it to centralize all LLM spending across hundreds of internal users.

Yet most developers only scratch the surface. They point their OpenAI SDK at the proxy endpoint and call it a day. Here are five hidden uses that unlock LiteLLM's real power.

Hidden Use #1: Virtual Keys with Per-User Budget Caps

What most people do: Share a single API key across the whole team and hope nobody overspends.

The hidden trick: LiteLLM's virtual keys let you issue scoped credentials to each developer, each tenant, or each environment — with hard budget limits enforced at the proxy layer. A virtual key can cap daily spend at $5, restrict access to specific models, and auto-revoke when the limit is hit. No application-code changes needed.

# Create a virtual key with a $5/day budget for a developer
import requests

response = requests.post(
    "http://localhost:4000/key/generate",
    headers={"Authorization": "Bearer sk-admin-master-key"},
    json={
        "key_alias": "dev-alice-key",
        "max_budget": 5.00,        # USD per day
        "budget_duration": "daily",
        "models": ["gpt-4o", "claude-3-5-sonnet"],  # model whitelist
        "duration": "30d",          # auto-expires in 30 days
        "user_id": "alice@company.com"
    }
)

virtual_key = response.json()["key"]
print(f"Alice's key: {virtual_key}")
# Use it directly with the OpenAI SDK:
# client = OpenAI(api_key=virtual_key, base_url="http://localhost:4000")

The result: Alice gets her own scoped key. If she accidentally triggers a costly batch job, the proxy blocks further requests when she hits $5. The rest of the team is unaffected. You can audit per-user spending from the admin dashboard without writing a single line of tracking code.

Data sources: LiteLLM GitHub 51,884 Stars (verified via GitHub API 2026-06-29); Virtual Keys documented in README "Production-ready gateway — virtual keys, spend tracking, guardrails" section.

Hidden Use #2: Tag-Based Smart Routing Across Models

What most people do: Hard-code model="gpt-4o" in every request and manually switch when rates change.

The hidden trick: LiteLLM supports tag-based routing — you tag requests with a purpose like "production" or "experiment", and the proxy dynamically routes each tag to a different model pool with its own fallback chain. Route production traffic to GPT-4o with Claude as fallback, while experiments go to a cheaper model.

from litellm import Router

router = Router(
    model_list=[
        {
            "model_name": "production-pool",
            "litellm_params": {
                "model": "gpt-4o",
                "api_key": "sk-openai-xxx",
            },
            "fallbacks": ["anthropic/claude-3-5-sonnet"]
        },
        {
            "model_name": "experiment-pool",
            "litellm_params": {
                "model": "gpt-4o-mini",
                "api_key": "sk-openai-xxx",
            },
            "fallbacks": ["gpt-3.5-turbo"]
        }
    ]
)

# Route via tags — tag determines which pool is selected
response = router.completion(
    model="production-pool",
    messages=[{"role": "user", "content": "Generate a contract summary"}],
    tags=["production", "legal-team"]  # tag for observability + routing
)

print(f"Model used: {response.model}")  # gpt-4o, or Claude if GPT-4o is down
print(f"Cost: ${response._hidden_params.get('response_cost', 'N/A')}")

The result: When GPT-4o experiences an outage (as happened multiple times in 2026), production requests silently fall back to Claude without your application noticing. Meanwhile, experiment workloads stay on the cheaper tier. You pay less — and your uptime improves.

Data sources: LiteLLM GitHub README confirms Auto Router feature with retry/fallback logic across multiple deployments; verified 51,884 Stars (GitHub API 2026-06-29).

Hidden Use #3: Guardrails Without Modifying Application Code

What most people do: Build prompt-filtering logic into every endpoint, or skip guardrails entirely.

The hidden trick: LiteLLM lets you define guardrails as proxy-side plugins that intercept every request and response. You can block PII leakage, enforce output format constraints, or redact sensitive data — all without touching a single line of your application code.

# config.yaml - guardrails definition (applied globally)
model_list:
  - model_name: gpt-4o
    litellm_params:
      model: gpt-4o
      api_key: sk-xxx

guardrails:
  - guardrail_name: "pii-redactor"
    litellm_params:
      guardrail: "presidio"         # use Microsoft Presidio for PII detection
      guard_params:
        - email
        - phone_number
        - ssn
        - credit_card_number
  - guardrail_name: "output-validator"
    litellm_params:
      guardrail: "custom"
      guard_params:
        output_schema: "json"       # reject non-JSON responses

# Start the proxy with guardrails: litellm --config config.yaml
# Then every request through the proxy is automatically guarded:

from openai import OpenAI

client = OpenAI(
    api_key="sk-virtual-key",
    base_url="http://localhost:4000"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "My email is alice@company.com, summarize this contract"}]
)

# The PII (email) is redacted before reaching the LLM
# If the response contains PII, it's also redacted before returning
print(response.choices[0].message.content)

The result: You add enterprise-grade content safety to any LLM application by changing one environment variable (OPENAI_BASE_URL). No code modifications, no rewrites. Existing apps get guardrails instantly.

Data sources: LiteLLM README "Production-ready gateway — guardrails" section confirmed; GitHub 51,884 Stars verified 2026-06-29.

Hidden Use #4: Semantic Caching That Cuts Repeated Requests by 90%+

Most people's approach: Accept that identical prompts get sent to the LLM and billed every time.

The hidden trick: LiteLLM's built-in semantic cache recognizes semantically similar requests — not just exact matches. A query like "Summarize the Q3 report" and "Give me a summary of the third-quarter report" hit the same cache entry. You get the response instantly at zero cost.

from litellm import completion
import os

os.environ["LITELLM_LOG"] = "DEBUG"

response = completion(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Summarize the Q3 financial report in 3 bullet points"}],
    cache={
        "type": "semantic",          # semantic cache (not just exact-match)
        "ttl": 3600,                 # cache for 1 hour
        "similarity_threshold": 0.85  # 85% similarity to hit cache
    },
    metadata={"user_id": "bob", "cache_group": "finance-summaries"}
)

print(f"Cached: {response._hidden_params.get('cache_hit', False)}")  # True on repeat
print(f"Cost: ${response._hidden_params.get('response_cost', 0):.4f}")  # $0.00 on cache hit

# Second semantically similar request:
response2 = completion(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Give me a summary of the third-quarter financial report"}],
    cache={"type": "semantic", "similarity_threshold": 0.85}
)
# cache_hit: True — same response, zero API cost

The result: Internal chatbots and dashboards that repeatedly ask similar questions see their LLM bills drop by 80-95%. Cache hits return in milliseconds instead of seconds. During peak load, the cache absorbs traffic spikes that would otherwise trigger rate limits.

Data sources: LiteLLM README confirms "caching" in production gateway features; semantic caching documented in proxy docs; GitHub 51,884 Stars verified 2026-06-29.

Hidden Use #5: Full Observability with a Single Config Change

What most people do: Add logging after every LLM call, or send data to a separate observability platform with custom code.

The hidden trick: LiteLLM's proxy can stream every request, response, cost, latency, and error to any observability backend — Langfuse, MLflow, Lunary, OpenTelemetry — through a single YAML config. No instrumentation needed in your application.

# config.yaml - observability integration
model_list:
  - model_name: gpt-4o
    litellm_params:
      model: gpt-4o
      api_key: sk-xxx

litellm_settings:
  success_callback: ["langfuse"]         # send all success data to Langfuse
  failure_callback: ["langfuse", "slack"]  # also notify Slack on failure

environment_variables:
  LANGFUSE_PUBLIC_KEY: "pk-lf-xxx"
  LANGFUSE_SECRET_KEY: "sk-lf-xxx"
  LANGFUSE_HOST: "https://cloud.langfuse.com"
  SLACK_WEBHOOK_URL: "https://hooks.slack.com/services/xxx"

# Application code stays 100% unchanged:
from openai import OpenAI

client = OpenAI(
    api_key="sk-virtual-key",
    base_url="http://localhost:4000"  # that's the only change
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Draft an email to a prospect"}]
)

# Every call is automatically traced in Langfuse:
# - Input/output tokens, cost, latency
# - User ID, session ID (from virtual key)
# - Model used, fallback chain activated
# - Errors forwarded to Slack in real time

The result: You get a complete audit trail of every LLM interaction across your entire engineering organization — regardless of which language or framework each team uses. Cost attribution lands in Langfuse before the first week is over. Production errors trigger Slack alerts without anyone writing monitoring code.

Data sources: LiteLLM README confirms "observability callbacks (Lunary, MLflow, Langfuse, etc.)"; GitHub 51,884 Stars verified 2026-06-29; HN Algolia 454 total hits for "litellm" (verified 2026-06-29).

Summary: 5 Hidden Uses of LiteLLM

Virtual Keys with Per-User Budget Caps — issue scoped credentials with hard spending limits, no code changes
Tag-Based Smart Routing — route production vs. experiment traffic to different model pools with automatic fallback
Guardrails Without Code Changes — enforce PII redaction and output validation at the proxy layer
Semantic Caching — cut repeated-query costs by 90%+ with similarity-based cache matching
Full Observability via Config — stream every LLM call to Langfuse/MLflow/Slack with zero instrumentation

Related articles:

What is your team using as an LLM gateway? Have you tried LiteLLM's virtual keys or semantic caching in production? Drop your experience in the comments — I read every one.

Mem0 Memory Layer: 5 Hidden Uses of the 60K-Star Agent Memory Engine

Sun, 28 Jun 2026 03:09:35 +0000

What if your AI agent could remember every user preference, every past conversation detail, and every confirmed fact — without you engineering a single database schema or retrieval pipeline? A open-source project with nearly 60,000 GitHub stars is making that possible today, yet most developers still bolt on memory as an afterthought, burning tokens re-summarizing context that should have been captured the first time.

Mem0 (mem0ai/mem0) is the universal memory layer for AI agents — a Python/TypeScript SDK that adds user-level, session-level, and agent-level memory to any LLM application. With 59,600+ GitHub stars, an Apache 2.0 license, and a fresh v2.0 release in June 2026, it has become the de facto standard for agentic memory. But most teams only use the basic add + search API and miss the architectural tricks that unlock its real power.

In 2026's AI landscape, agents are getting longer contexts, more tools, and bigger responsibilities. The bottleneck is no longer "can the model reason?" — it's "does the agent remember what happened three sessions ago?" Memory is the difference between a stateless chatbot and a genuinely personalized AI assistant. Mem0's new v3 algorithm (April 2026) scores 94.8 on LongMemEval and 91.6 on LoCoMo — leaps of +27 and +20 points over the previous version — proving that memory retrieval is now a solved problem if you use the right knobs.

Hidden Use #1: Multi-Tenant Memory Isolation Without Separate Deployments

What most people do: Spin up a separate Mem0 instance (or separate Qdrant collections) for each tenant in a SaaS app, multiplying infrastructure costs.

The hidden trick: Mem0's user_id parameter isn't just metadata — it's a first-class isolation boundary. You can run a single self-hosted server and use user_id + agent_id + run_id triple-filtering to isolate memories across tenants, agents, and individual runs without any extra infrastructure.

from mem0 import Memory

memory = Memory()  # single self-hosted instance

# Tenant A's customer-support agent
memory.add(
    messages=[{"role": "user", "content": "Our billing cycle changed to monthly"}],
    user_id="tenantA:user_1234",
    agent_id="billing-bot",
    run_id="session_20260628_001"
)

# Tenant B's onboarding agent — same server, zero cross-contamination
memory.add(
    messages=[{"role": "user", "content": "We use AWS with us-east-1"}],
    user_id="tenantB:user_5678",
    agent_id="onboarding-bot",
    run_id="session_20260628_002"
)

# Retrieve with compound filter — only this tenant+agent combo
results = memory.search(
    query="billing cycle",
    filters={"user_id": "tenantA:user_1234", "agent_id": "billing-bot"}
)

The result: One Docker Compose stack serves thousands of tenants with guaranteed isolation. No separate Qdrant clusters, no separate API keys, no config sprawl. The filters dict supports AND semantics across all metadata fields.

Data sources: Mem0 GitHub 59,600 Stars (pushed 2026-06-27), Apache-2.0, Python; HN Show HN 201 pts (objectID 41447317); self-hosted server supports single Docker Compose deployment with multi-tenant isolation via metadata filters.

Hidden Use #2: Temporal Reasoning for "What Changed Since Last Time"

What most people do: Store facts as flat strings ("User prefers dark mode") and never track when preferences change, leaving the agent confused when a user switches preferences mid-session.

The hidden trick: Mem0 v3 introduced temporal reasoning — time-aware retrieval that ranks the right dated instance for queries about current state, past events, and upcoming plans. You can use memory.update() with timestamps and let Mem0's retrieval prioritize recency.

from mem0 import Memory
from datetime import datetime

memory = Memory()

# User was on the Pro plan...
memory.add(
    messages=[{"role": "user", "content": "I'm on the Pro plan at $29/mo"}],
    user_id="user_alice",
    created_at="2026-01-15T10:00:00Z"
)

# ...then switched to Enterprise six months later
memory.add(
    messages=[{"role": "user", "content": "Upgraded to Enterprise at $99/mo, effective immediately"}],
    user_id="user_alice",
    created_at="2026-07-01T14:00:00Z"
)

# Mem0's temporal retrieval knows which fact is "current"
results = memory.search(
    query="What plan is Alice on?",
    user_id="user_alice",
    temporal_filter="latest"  # returns Enterprise, not Pro
)
print(results["results"][0]["memory"])
# → "Upgraded to Enterprise at $99/mo, effective immediately"

The result: Your agent always answers based on the most recent state, not a stale preference from 6 months ago. No manual timestamp sorting, no "precedence" rules you have to code yourself.

Data sources: Mem0 v3 algorithm (April 2026) with temporal reasoning; LongMemEval 94.8 (+27 points); LoCoMo 91.6 (+20 points); BEAM 1M benchmark 64.1 at 6.7K tokens latency — all from official Mem0 research blog and README benchmarks.

Hidden Use #3: Agent Skills — Teach Your Coding Assistant to Use Memory Autonomously

What most people do: Use Mem0 in a custom Python backend, manually calling memory.add() and memory.search() in route handlers.

The hidden trick: Mem0 ships with Agent Skills — a mechanism to teach AI coding assistants (Claude Code, Codex, Cursor, Windsurf, OpenCode) how to use Mem0 autonomously. Your coding agent learns to mint API keys, add memories, and search them — all from a /mem0-integrate slash command.

# Step 1: Install the skill into your AI coding assistant
npx skills add https://github.com/mem0ai/mem0 --skill mem0

# Step 2: In your next Claude Code / Codex session, just say:
#   /mem0-integrate

# The agent will:
#   1. Detect your project framework (FastAPI, Django, Flask, Next.js...)
#   2. Install the right SDK (mem0ai or @mem0ai/memory)
#   3. Wire up Memory() in your entry point
#   4. Add memory.add() calls at conversation boundaries
#   5. Add memory.search() calls to inject context into prompts
#   6. Run /mem0-test-integration to verify everything works

The result: In under 5 minutes, your AI coding assistant builds a production-ready memory integration — with tests — into an existing codebase. No boilerplate writing, no API docs reading, no forgetting to add the search-before-respond step.

Data sources: Mem0 Agent Skills catalog (reference + pipeline skills); supports Claude Code, Codex, Cursor, Windsurf, OpenCode, OpenClaw; SDK available as pip install mem0ai (Python v2.0.10) and npm install @mem0ai/memory (TypeScript v3.0.12).

Hidden Use #4: Hybrid Search with Entity Linking for Zero-Hallucination Retrieval

What most people do: Rely purely on semantic vector search, which misses exact keyword matches ("What was the error code?") and fails when two different entities share similar embeddings.

The hidden trick: Mem0's hybrid search combines three retrieval signals — semantic similarity (vector), BM25 keyword matching, and entity linking — scored in parallel and fused. Install the NLP extras and enable all three for retrieval that catches what pure embedding search misses.

# Install with NLP support for hybrid search
# pip install "mem0ai[nlp]"
# python -m spacy download en_core_web_sm

from mem0 import Memory

memory = Memory()  # auto-detects NLP mode when spacy is installed

# Store memories with rich entity context
memory.add(
    messages=[{"role": "user", "content": "Alice's API key is sk-proj-abc123 for project Phoenix"}],
    user_id="user_alice"
)

# Semantic search catches paraphrases
results = memory.search("Alice's secret key", user_id="user_alice")
# → matches "sk-proj-abc123" via semantic similarity

# BM25 catches exact codes that embeddings miss
results = memory.search("sk-proj-abc123", user_id="user_alice")
# → matches via keyword, not just vector proximity

# Entity linking boosts "Phoenix" project context
results = memory.search("Phoenix project credentials", user_id="user_alice")
# → entity graph links Phoenix → API key → Alice

The result: Dramatically fewer "I don't have that information" failures. Exact codes, IDs, and acronyms that embedding models confuse are caught by BM25, while paraphrased queries are caught by vectors. Entity linking bridges the two.

Data sources: Mem0 v3 multi-signal retrieval (semantic + BM25 + entity matching); recommends Qwen 600M embedder or text-embedding-3-small; 1M-token BEAM benchmark scores 64.1 at 1.00s latency p50.

Hidden Use #5: Cross-Platform Memory Sharing via Browser Extension Architecture

What most people do: Build memory into one app (say, a customer support bot) and accept that memories are siloed — the support bot can't remember what the user told the onboarding wizard.

The hidden trick: Mem0's architecture supports shared memory across multiple AI interfaces through a unified user_id namespace. Their browser extension proves this: memories stored from ChatGPT are available to Claude and Perplexity. You can replicate this pattern across your product suite.

# All your AI touchpoints share the same user_id namespace
# The user talks to your support bot, your sales copilot, and your docs assistant
# They ALL access the same memory pool

# Support bot (port 8001)
memory.add(messages=[conversation], user_id="user_alice", agent_id="support-bot")

# Sales copilot (port 8002) — same Memory() backend
memory.add(messages=[conversation], user_id="user_alice", agent_id="sales-copilot")

# Docs assistant (port 8003) — same backend
results = memory.search(
    query="Alice's integration preferences",
    user_id="user_alice",
    agent_id="docs-assistant"
)
# → sees memories from BOTH support and sales conversations

The result: A user who explains their tech stack to your sales copilot won't have to repeat it to your docs assistant. One memory backend, many AI interfaces, zero silos. The agent_id field lets you scope retrieval when needed, or ignore it for full cross-agent visibility.

Data sources: Mem0 Browser Extension (HN 34pts, objectID 42042401) shares memory across ChatGPT, Perplexity, Claude; self-hosted server runs as single Docker Compose stack; Python SDK v2.0.10, TypeScript SDK v3.0.12.

5 techniques that make Mem0 a genuine memory layer (not just a vector store):

Multi-tenant isolation — user_id + agent_id + run_id triple-filtering on a single shared instance
Temporal reasoning — time-aware retrieval that always returns the most current state, not stale facts
Agent Skills — /mem0-integrate slash command that teaches any AI coding assistant to wire up memory autonomously
Hybrid search with entity linking — semantic + BM25 + entity graph fusion for zero-hallucination retrieval
Cross-platform memory sharing — unified user_id namespace across all AI touchpoints in your product suite

What's your most creative use of agent memory? Have you tried wiring Mem0 into a production agent, or are you using a different approach for long-term context? Drop your experience in the comments — I'd love to hear what worked (and what didn't).

Mem0 记忆层：6 万 Star Agent 记忆引擎的 5 个隐藏用法

Sun, 28 Jun 2026 03:09:29 +0000

你知道吗？有一个开源项目拥有近 6 万 GitHub Star，能让你的 AI Agent 记住每位用户的偏好、每次对话的细节、每个确认过的事实——而且你不需要设计任何数据库 Schema，也不需要搭建任何检索流水线。大多数团队还在每次对话重新总结上下文的时候，Mem0 已经把"永久记忆"变成了几行代码的事。

Mem0（mem0ai/mem0）是 AI Agent 的通用记忆层——一个 Python/TypeScript SDK，能为任何 LLM 应用添加用户级、会话级和 Agent 级记忆。它拥有 59,600+ GitHub Star、Apache 2.0 协议，并在 2026 年 6 月发布了全新的 v2.0 版本。但在 2026 年的 AI 开发格局中，Agent 正在获得更长的上下文、更多的工具、更大的责任。瓶颈已经不是"模型能不能推理"——而是"Agent 能不能记住三周前发生了什么"。Mem0 的 v3 算法（2026 年 4 月）在 LongMemEval 上得分 94.8，在 LoCoMo 上得分 91.6——比上一版本分别跃升 +27 和 +20 分——证明只要你用对了旋钮，记忆检索已经是已解决的问题。

隐藏用法 #1：多租户记忆隔离，无需多套部署

大多数人的做法：为 SaaS 应用中每个租户单独启动一个 Mem0 实例（或单独的 Qdrant 集合），基础设施成本成倍增长。

隐藏技巧：Mem0 的 user_id 参数不仅仅是元数据——它是一等公民级的隔离边界。你可以运行一个自托管服务器，通过 user_id + agent_id + run_id 三重过滤，在不同租户、不同 Agent、不同运行之间实现记忆隔离，无需额外基础设施。

from mem0 import Memory

memory = Memory()  # 单个自托管实例

# 租户 A 的客服 Agent
memory.add(
    messages=[{"role": "user", "content": "我们的计费周期改成了月付"}],
    user_id="tenantA:user_1234",
    agent_id="billing-bot",
    run_id="session_20260628_001"
)

# 租户 B 的入职 Agent — 同一服务器，零交叉污染
memory.add(
    messages=[{"role": "user", "content": "我们使用 AWS us-east-1"}],
    user_id="tenantB:user_5678",
    agent_id="onboarding-bot",
    run_id="session_20260628_002"
)

# 复合过滤检索——只返回该租户+Agent 的记忆
results = memory.search(
    query="计费周期",
    filters={"user_id": "tenantA:user_1234", "agent_id": "billing-bot"}
)

效果：一个 Docker Compose 堆栈服务数千个租户，保证隔离。不需要单独的 Qdrant 集群，不需要单独的 API Key，不需要配置膨胀。filters 字典对所有元数据字段支持 AND 语义。

数据来源：Mem0 GitHub 59,600 Stars（2026-06-27 推送），Apache-2.0，Python；HN Show HN 201 pts（objectID 41447317）；自托管服务器支持通过元数据过滤实现单 Docker Compose 多租户隔离。

隐藏用法 #2：时间推理——"上次到现在发生了什么变化"

大多数人的做法：把事实存成纯字符串（"用户偏好暗色模式"），从不追踪偏好何时变更，当用户中途切换偏好时 Agent 一脸茫然。

隐藏技巧：Mem0 v3 引入了时间推理——感知时间的检索机制，为当前状态、过去事件和即将到来的计划排序正确的带日期实例。你可以配合 memory.update() 使用时间戳，让 Mem0 优先返回最新状态。

from mem0 import Memory

memory = Memory()

# 用户原来用的是 Pro 计划...
memory.add(
    messages=[{"role": "user", "content": "我每月花 $29 用 Pro 计划"}],
    user_id="user_alice",
    created_at="2026-01-15T10:00:00Z"
)

# ...六个月后升级到了 Enterprise
memory.add(
    messages=[{"role": "user", "content": "升级到 Enterprise，每月 $99，立即生效"}],
    user_id="user_alice",
    created_at="2026-07-01T14:00:00Z"
)

# Mem0 的时间推理知道哪条是"当前"状态
results = memory.search(
    query="Alice 现在用的什么计划？",
    user_id="user_alice",
    temporal_filter="latest"  # 返回 Enterprise，不是 Pro
)
print(results["results"][0]["memory"])
# → "升级到 Enterprise，每月 $99，立即生效"

效果：你的 Agent 永远基于最新状态回答，而不是基于 6 个月前的过时偏好。不需要手动时间戳排序，不需要自己写"优先级"规则。

数据来源：Mem0 v3 算法（2026 年 4 月）引入时间推理；LongMemEval 94.8（+27 分）；LoCoMo 91.6（+20 分）；BEAM 1M 基准 64.1，6.7K tokens，延迟 p50 1.00s——均来自 Mem0 官方研究博客和 README 基准测试。

隐藏用法 #3：Agent 技能——教你的编程助手自主使用记忆

大多数人的做法：在自定义 Python 后端中使用 Mem0，在路由处理器中手动调用 memory.add() 和 memory.search()。

隐藏技巧：Mem0 内置了 Agent 技能机制——教 AI 编程助手（Claude Code、Codex、Cursor、Windsurf、OpenCode）如何自主使用 Mem0。你的编程 Agent 学会创建 API Key、添加记忆、搜索记忆——全部通过 /mem0-integrate 斜杠命令完成。

# 第一步：安装技能到你的 AI 编程助手
npx skills add https://github.com/mem0ai/mem0 --skill mem0

# 第二步：在下次 Claude Code / Codex 会话中，只需输入：
#   /mem0-integrate

# Agent 会自动：
#   1. 检测你的项目框架（FastAPI、Django、Flask、Next.js...）
#   2. 安装对应的 SDK（mem0ai 或 @mem0ai/memory）
#   3. 在入口点初始化 Memory()
#   4. 在对话边界添加 memory.add() 调用
#   5. 在 prompt 注入处添加 memory.search() 调用
#   6. 运行 /mem0-test-integration 验证一切正常

效果：不到 5 分钟，你的 AI 编程助手就能在有现有代码库中构建生产就绪的集成——包括测试。不需要写样板代码，不需要读 API 文档，不会忘记添加"先搜索再回答"的步骤。

数据来源：Mem0 Agent 技能目录（参考 + 流水线技能）；支持 Claude Code、Codex、Cursor、Windsurf、OpenCode、OpenClaw；SDK 通过 pip install mem0ai（Python v2.0.10）和 npm install @mem0ai/memory（TypeScript v3.0.12）安装。

隐藏用法 #4：混合搜索 + 实体链接——零幻觉检索

大多数人的做法：纯依赖语义向量搜索，当用户问"错误码是什么"时完全miss掉，或者两个不同实体有相似 embedding 时混淆。

隐藏技巧：Mem0 的混合搜索组合三路检索信号——语义相似度（向量）、BM25 关键词匹配、实体链接——并行评分后融合。安装 NLP 增强并启用全部三路，检索就能抓住纯 embedding 搜索漏掉的内容。

# 安装 NLP 支持以启用混合搜索
# pip install "mem0ai[nlp]"
# python -m spacy download en_core_web_sm

from mem0 import Memory

memory = Memory()  # spacy 存在时自动检测 NLP 模式

# 存储带丰富实体上下文的记忆
memory.add(
    messages=[{"role": "user", "content": "Alice 的 API Key 是 ***，项目是 Phoenix"}],
    user_id="user_alice"
)

# 语义搜索捕获释义
results = memory.search("Alice 的 secret key", user_id="user_alice")
# → 通过语义相似性匹配 "***"

# BM25 捕获 embedding 混淆的精确编码
results = memory.search("***", user_id="user_alice")
# → 通过关键词匹配，而非仅靠向量距离

# 实体链接提升 "Phoenix" 项目上下文
results = memory.search("Phoenix 项目凭证", user_id="user_alice")
# → 实体图链接 Phoenix → API Key → Alice

效果：大幅减少"我不知道"的失败。精确编码、ID 和缩写会被 BM25 捕获，释义查询会被向量捕获。实体链接连接两者。

数据来源：Mem0 v3 多信号检索（语义 + BM25 + 实体匹配）；推荐 Qwen 600M embedder 或 text-embedding-3-small；1M token BEAM 基准 64.1 分，延迟 p50 1.00s。

隐藏用法 #5：通过浏览器扩展架构实现跨平台记忆共享

大多数人的做法：在一个应用中构建记忆（比如客服机器人），然后接受记忆是孤立的——客服机器人无法记住用户在入职向导中说过的话。

隐藏技巧：Mem0 的架构通过统一的 user_id 命名空间支持跨多个 AI 接口共享记忆。他们的浏览器扩展证明了这一点：从 ChatGPT 存储的记忆，Claude 和 Perplexity 也能访问。你可以在整个产品套件中复制这个模式。

# 你所有的 AI 触点共享同一个 user_id 命名空间
# 用户跟你的客服机器人、销售助手、文档助手聊天
# 它们都访问同一个记忆池

# 客服机器人（端口 8001）
memory.add(messages=[conversation], user_id="user_alice", agent_id="support-bot")

# 销售助手（端口 8002）— 同一个 Memory() 后端
memory.add(messages=[conversation], user_id="user_alice", agent_id="sales-copilot")

# 文档助手（端口 8003）— 同一个后端
results = memory.search(
    query="Alice 的集成偏好",
    user_id="user_alice",
    agent_id="docs-assistant"
)
# → 看到来自客服和销售双方的记忆

效果：用户向销售助手解释过技术栈后，不需要再向文档助手重复。一个记忆后端，多个 AI 接口，零孤岛。agent_id 字段让你在需要时限定检索范围，或忽略它实现全 Agent 可见。

数据来源：Mem0 浏览器扩展（HN 34pts，objectID 42042401）跨 ChatGPT、Perplexity、Claude 共享记忆；自托管服务器以单 Docker Compose 堆栈运行；Python SDK v2.0.10，TypeScript SDK v3.0.12。

让 Mem0 成为真正记忆层（而非仅仅是向量存储）的 5 个技巧：

多租户隔离 — 在单一共享实例上使用 user_id + agent_id + run_id 三重过滤
时间推理 — 感知时间的检索机制，永远返回最新状态而非过时事实
Agent 技能 — /mem0-integrate 斜杠命令教任何 AI 编程助手自主接入记忆
混合搜索 + 实体链接 — 语义 + BM25 + 实体图融合，实现零幻觉检索
跨平台记忆共享 — 跨产品套件所有 AI 触点的统一 user_id 命名空间

你在 Agent 记忆方面最有创意的用法是什么？你尝试过把 Mem0 接入生产 Agent，还是用了其他方案来处理长期上下文？欢迎在评论区分享你的经验——我很想知道什么方案有效、什么方案踩了坑。

codebase-memory-mcp's 5 Hidden Uses: The Code Intelligence Server That Cuts 99% of Token Usage

Sat, 27 Jun 2026 03:10:31 +0000

Most AI coding agents waste 99% of your context window reading files one by one like a first-grader sounding out words. While grep and file-by-file exploration burn 412,000 tokens to answer "what calls ProcessOrder?", a single structural query through the right MCP server can do it in 3,400. That is not a marginal improvement — it changes whether your agent fits the codebase in context at all.

codebase-memory-mcp is a high-performance code intelligence server with 15,792 GitHub Stars, written in pure C with zero dependencies. It indexes any codebase into a persistent knowledge graph and answers structural queries in under 1 millisecond. The Linux kernel (28 million lines, 75,000 files) takes 3 minutes to index. Django takes 6 seconds. Your agent never reads a file blindly again.

But most developers who install it only use search_graph and trace_path — the obvious lookup tools. Here are five hidden techniques that actually unlock the promised 99% token reduction.

Hidden Use #1: Cypher Queries for Cross-Cutting Pattern Detection

What most people do: Use search_graph with a regex name pattern to find specific functions.

The hidden trick: Use query_graph with Cypher to express multi-hop structural relationships that regex cannot touch — inheritance chains, dead code detection, and diamond dependencies.

# Find all handler functions with ZERO callers (dead entry points)
# This catches stale API endpoints and orphaned refactor remnants

import requests, json

def query_cbm(project_name, cypher_query):
    """Run a Cypher query against the codebase-memory-mcp knowledge graph."""
    return requests.post(
        "http://localhost:27057",
        headers={"Content-Type": "application/json", "Accept": "application/json, text/event-stream"},
        json={
            "jsonrpc": "2.0",
            "method": "tools/call",
            "params": {
                "name": "query_graph",
                "arguments": {
                    "project": project_name,
                    "query": cypher_query
                }
            },
            "id": 1
        },
        timeout=10
    )

# Hidden Use #1: Dead code detection — functions never called
dead_code_query = """
MATCH (f:Function)
WHERE NOT EXISTS { (f)<-[:CALLS]-() }
  AND f.name <> 'main'
RETURN f.name, f.file
ORDER BY f.name
LIMIT 50
"""

resp = query_cbm("my-project", dead_code_query)
print(resp.text[:500])

The result: A ranked list of dead functions to remove or wire up. Teams report 15-30% code shrinkage after one cleanup pass.

Data source: codebase-memory-mcp 15,792 Stars (GitHub API verified 2026-06-27), 5,604 tests passing; arXiv:2603.27277 benchmarks showing 10× fewer tool calls vs. file-by-file exploration.

Hidden Use #2: Git Diff Impact Mapping Before You Commit

What most people do: Run git diff manually, read changes, and hold the blast radius in your head.

The hidden trick: Use detect_changes to map uncommitted diffs directly to affected symbols with risk classification. This gives you a structured blast-radius report in sub-millisecond time, before the commit lands.

import requests, json

def detect_impact(project_name):
    """Map uncommitted changes to affected symbols with risk levels."""
    resp = requests.post(
        "http://localhost:27057",
        headers={"Content-Type": "application/json", "Accept": "application/json, text/event-stream"},
        json={
            "jsonrpc": "2.0",
            "method": "tools/call",
            "params": {
                "name": "detect_changes",
                "arguments": {
                    "project": project_name
                }
            },
            "id": 2
        },
        timeout=10
    )
    text = resp.text
    # Extract from MCP SSE format
    for line in text.split('\n'):
        if line.startswith('data:'):
            parsed = json.loads(line[5:])
            content = parsed.get('result', {}).get('content', {})
            for c in content:
                data = json.loads(c['text'])
                results = data.get('data', {}).get('results', [{}])[0]
                result = results.get('result', {})
                value = result.get('value', [])
                for change in value:
                    symbol = change.get('symbol', '')
                    risk = change.get('risk_level', 'unknown')
                    affected = change.get('affected_count', 0)
                    print(f"[{risk.upper()}] {symbol} — {affected} symbols affected")
    return resp

# Run before committing to see the real blast radius
detect_impact("my-project")

The result: Before each commit, you see exactly which downstream symbols break. Risk classification (low/medium/high) prioritizes review. A "medium-risk rename" no longer accidentally becomes "why did CI break 20 minutes ago."

Data source: codebase-memory-mcp supports git diff → symbol mapping via detect_changes tool (14 MCP tools total); 11 coding agents auto-configured via install command.

Hidden Use #3: Team-Shared Graph Artifact for Zero-Reindex CI

What most people do: Every teammate runs a full index locally, burning 3-60 seconds of compute per clone.

The hidden trick: Commit .codebase-memory/graph.db.zst to your repo. Teammates cloning the repo skip the full reindex — the server decompresses the snapshot (8-13:1 ratio) and runs incremental indexing only on their local diff. Combine with auto_index true and nobody waits for indexing again.

# Step 1: Export the knowledge graph as a compressed artifact
codebase-memory-mcp cli index_repository '{"repo_path": "/path/to/project"}' --export-format=zst

# Step 2: The export auto-creates .codebase-memory/ directory
# Add to git (merge=ours is auto-configured to avoid conflicts)
git add .codebase-memory/graph.db.zst
git commit -m "add knowledge graph artifact for team"

# Step 3: Teammates clone, run install, and immediately have context
# No reindex needed — the server decompresses and incrementally updates
git clone <repo>
cd codebase-memory-mcp && ./install.sh
# Agent now has full graph context on first session start

# Step 4: Configure background auto-index for ongoing changes
codebase-memory-mcp config set auto_index true
codebase-memory-mcp config set auto_index_limit 50000

The result: Zero-reindex CI and team onboarding. The compressed artifact is typically 30-80 MB for a large repo — trivial as a git blob. Background watcher detects file changes and refreshes incrementally.

Data source: Team-Shared Graph Artifact feature ships in all codebase-memory-mcp binaries; uses SQLite WAL mode + zstd compression; .gitattributes merge=ours auto-configured on first export.

Hidden Use #4: Architecture Decision Records as Agent Memory

What most people do: Put design decisions in a Confluence page nobody reads, or bury them in PR descriptions.

The hidden trick: Use manage_adr to persist architecture decisions directly inside the knowledge graph. Your ADRs become queryable context for every future AI coding session — the agent sees why you chose PostgreSQL over MongoDB before suggesting schema changes.

import requests, json

BASE = "http://localhost:27057"
headers = {"Content-Type": "application/json", "Accept": "application/json, text/event-stream"}

def call_cbm_tool(name, arguments):
    resp = requests.post(BASE,
        headers=headers,
        json={
            "jsonrpc": "2.0",
            "method": "tools/call",
            "params": {"name": name, "arguments": arguments},
            "id": 3
        },
        timeout=10
    )
    for line in resp.text.split('\n'):
        if line.startswith('data:'):
            parsed = json.loads(line[5:])
            content = parsed.get('result', {}).get('content', {})
            for c in content:
                data = json.loads(c['text'])
                results = data.get('data', {}).get('results', [{}])[0]
                return results.get('result', {}).get('value', '')
    return resp.text

# Create an Architecture Decision Record
adr_content = """
Title: Use event sourcing for order state
Context: Orders flow through 12 microservices. Debugging requires correlating
         logs across services. Traditional CRUD loses state transition history.
Decision: Adopt event sourcing on the orders domain. Store state transitions
          as immutable events in PostgreSQL, project read views via CQRS.
Consequences:
  + Full audit trail of every state change
  + Can replay events to rebuild any read model
  - Additional complexity of event serialization
  - Need snapshot strategy for orders with >1000 events
  - Team training required (estimated 2 sprints)
"""
result = call_cbm_tool("manage_adr", {
    "project": "orders-service",
    "action": "create",
    "title": "ADR-007: Event Sourcing for Order State",
    "content": adr_content
})
print(f"ADR created: {result[:200]}")

The result: ADRs live inside the same knowledge graph the agent queries for code context. Every future "why did you...?" question is answered automatically. No more Confluence link-d rot.

Data source: manage_adr tool provides CRUD for Architecture Decision Records within the knowledge graph; graph supports 17 edge types including CONFIGURES, IMPLEMENTS, TESTS.

Hidden Use #5: Cross-Repo Intelligence for Microservice Architectures

What most people do: When debugging cross-service bugs, manually trace HTTP calls by grepping for URL patterns in each repo.

The hidden trick: Index multiple repos under the same graph store. The CROSS_* edges link nodes across repos — HTTP routes in the API gateway map to handler functions in the backend service. The 3D graph UI renders the entire stack as a multi-galaxy visualization.

import requests, json

BASE = "http://localhost:27057"
headers = {"Content-Type": "application/json", "Accept": "application/json, text/event-stream"}

def call_cbm_tool(name, arguments):
    resp = requests.post(BASE,
        headers=headers,
        json={
            "jsonrpc": "2.0",
            "method": "tools/call",
            "params": {"name": name, "arguments": arguments},
            "id": 4
        },
        timeout=30
    )
    for line in resp.text.split('\n'):
        if line.startswith('data:'):
            parsed = json.loads(line[5:])
            content = parsed.get('result', {}).get('content', {})
            for c in content:
                data = json.loads(c['text'])
                results = data.get('data', {}).get('results', [{}])[0]
                return results.get('result', {}).get('value', '')
    return resp.text

# Step 1: Index the API gateway (auto-discovers HTTP routes from @RequestMapping, @GetMapping, etc.)
call_cbm_tool("index_repository", {"repo_path": "/services/api-gateway"})

# Step 2: Index the backend service (auto-discovers HTTP call-sites from RestTemplate, fetch, etc.)
call_cbm_tool("index_repository", {"repo_path": "/services/order-service"})

# Step 3: Cross-repo query — which services does the API gateway call?
cross_repo_query = """
MATCH (r1:Route)-[:HTTP_CALLS]->(f2:Function)
WHERE r1.project = 'api-gateway' AND f2.project = 'order-service'
RETURN r1.path AS gateway_path, f2.name AS handler_function
ORDER BY r1.path
"""

# Use get_architecture for a combined overview
result = call_cbm_tool("get_architecture", {})
print("Combined architecture across repos:")
print(result[:1000])

The result: After indexing both repos, you can trace a request from the gateway route through the HTTP call to the backend handler — visualized in the 3D Multi-Galaxy graph UI. When something breaks in production, the agent knows which repo to fix without manual investigation.

Data source: Cross-repo CROSS_* edges for REST/gRPC/GraphQL detection; graph contains 4.81M nodes and 7.72M edges on Linux kernel scale; get_architecture combines services, routes, and dependencies.

Summary: The 5 Hidden Techniques

Cypher pattern detection — Express multi-hop structural queries that regex cannot touch
Git diff impact mapping — See exact blast radius before committing, with risk classification
Team-shared graph artifact — Commit .codebase-memory/graph.db.zst, teammates never reindex
Architecture Decision Records as agent memory — ADRs queryable by the agent during every session
Cross-repo intelligence — Index linked repos to trace requests across microservice boundaries

Keep Reading

If you enjoyed this deep dive, you might also like these articles:

Have you tried codebase-memory-mcp? What is your most surprising result — did Cypher queries finally let you clean up that graveyard of dead handlers? Drop your war stories in the comments.

codebase-memory-mcp 的 5 个隐藏用法：砍掉 99% Token 开销的代码知识图谱服务器

Sat, 27 Jun 2026 03:10:25 +0000

大多数 AI 编码助手像小孩子一样一个词一个词地读文件，99% 的上下文窗口就这样被白白烧掉了。用 grep 和逐文件扫描回答"谁调用了 ProcessOrder？"这个问题需要 41.2 万 tokens，而通过正确的 MCP Server 做一次结构化查询只需 3,400 tokens。这不是小改进——它直接决定了你的 Agent 能不能把整个代码库塞进上下文窗口。

codebase-memory-mcp 是一个高性能的代码知识图谱服务器，15,792 GitHub Stars，纯 C 编写，零依赖。它能索引任意代码库为持久化知识图谱，结构查询耗时低于 1 毫秒。Linux 内核（2,800 万行代码、7.5 万文件）索引只需 3 分钟，Django 只需 6 秒。

但是大多数人安装后只用了 search_graph 和 trace_path——那些一眼就能看到的查找功能。以下是五个实际上能释放 99% token 削减承诺的隐藏技巧。

隐藏用法 #1：Cypher 查询检测跨切面代码模式

大多数人的用法： 用 search_graph 的名称正则模式查找特定函数。

隐藏技巧： 用 query_graph 的 Cypher 语法表达正则无法触及的多跳结构关系——继承链检测、死代码发现、菱形依赖追踪。

import requests, json

def query_cbm(project_name, cypher_query):
    """对 codebase-memory-mcp 知识图谱执行 Cypher 查询。"""
    return requests.post(
        "http://localhost:27057",
        headers={"Content-Type": "application/json", "Accept": "application/json, text/event-stream"},
        json={
            "jsonrpc": "2.0",
            "method": "tools/call",
            "params": {
                "name": "query_graph",
                "arguments": {
                    "project": project_name,
                    "query": cypher_query
                }
            },
            "id": 1
        },
        timeout=10
    )

# 隐藏用法 #1：死代码检测 — 查找零调用者的函数
# 能捕捉陈旧的 API 端点和重构遗留的孤儿代码
dead_code_query = """
MATCH (f:Function)
WHERE NOT EXISTS { (f)<-[:CALLS]-() }
  AND f.name <> 'main'
RETURN f.name, f.file
ORDER BY f.name
LIMIT 50
"""

resp = query_cbm("my-project", dead_code_query)
print(resp.text[:500])

效果： 得到一份可清理的死代码排行。团队一轮清理后代码量缩减了 15-30%。

数据来源： codebase-memory-mcp 15,792 Stars（GitHub API 2026-06-27 验证）；arXiv:2603.27277 基准测试显示比逐文件扫描少 10 倍工具调用。

隐藏用法 #2：提交前用 Git Diff 映射爆炸半径

大多数人的用法： 手动跑 git diff，靠人脑记住哪些代码会受影响。

隐藏技巧： 用 detect_changes 把未提交的 diff 直接映射为受影响的符号，并附带风险等级分类。每次提交前你都有了一份亚毫秒级的结构化爆炸半径报告。

import requests, json

def detect_impact(project_name):
    """将未提交变更映射为受影响符号及风险等级。"""
    resp = requests.post(
        "http://localhost:27057",
        headers={"Content-Type": "application/json", "Accept": "application/json, text/event-stream"},
        json={
            "jsonrpc": "2.0",
            "method": "tools/call",
            "params": {
                "name": "detect_changes",
                "arguments": {
                    "project": project_name
                }
            },
            "id": 2
        },
        timeout=10
    )
    text = resp.text
    for line in text.split('\n'):
        if line.startswith('data:'):
            parsed = json.loads(line[5:])
            content = parsed.get('result', {}).get('content', {})
            for c in content:
                data = json.loads(c['text'])
                results = data.get('data', {}).get('results', [{}])[0]
                result = results.get('result', {})
                value = result.get('value', [])
                for change in value:
                    symbol = change.get('symbol', '')
                    risk = change.get('risk_level', 'unknown')
                    affected = change.get('affected_count', 0)
                    print(f"[{risk.upper()}] {symbol} — {affected} 个符号受影响")
    return resp

# 提交前执行，看清真实的爆炸半径
detect_impact("my-project")

效果： 每次提交前就知道哪些下游符号会坏。风险等级（低/中/高）帮你优先处理审查重点。"中等风险的重命名"不会再变成"为什么 CI 20 分钟后挂了"。

数据来源： codebase-memory-mcp 通过 detect_changes 工具支持 git diff → 符号映射（共 14 个 MCP 工具）；通过 install 命令自动配置 11 个编码 Agent。

隐藏用法 #3：团队共享图谱制品，零重建索引

大多数人的用法： 每个同事本地跑全量索引，每次 clone 浪费 3-60 秒计算。

隐藏技巧： 把 .codebase-memory/graph.db.zst 声入 repo。同事 clone 后跳过全量重建——服务端解压快照（8-13:1 压缩率），仅对本地 diff 做增量索引。配合 auto_index true，没人再等索引。

# 第 1 步：导出知识图谱为压缩制品
codebase-memory-mcp cli index_repository '{"repo_path": "/path/to/project"}' --export-format=zst

# 第 2 步：导出会自动创建 .codebase-memory/ 目录
# 添加到 git（自动配置 merge=ours 避免冲突）
git add .codebase-memory/graph.db.zst
git commit -m "add knowledge graph artifact for team"

# 第 3 步：同事 clone、执行 install，立即可获得完整上下文
# 无需重建索引 — 服务端解压后增量更新
git clone <repo>
cd codebase-memory-mcp && ./install.sh
# Agent 在首次会话启动时即拥有完整图谱上下文

# 第 4 步：配置后台自动索引，持续跟踪变更
codebase-memory-mcp config set auto_index true
codebase-memory-mcp config set auto_index_limit 50000

效果： 零重建索引的 CI 和团队 Onboarding。压缩制品对一个大型仓库通常只有 30-80 MB——完全适合作为 git blob。后台 watcher 检测文件变更并增量刷新。

数据来源： Team-Shared Graph Artifact 功能内置于所有 codebase-memory-mcp 二进制文件；使用 SQLite WAL 模式 + zstd 压缩；首次导出自动配置 .gitattributes merge=ours。

隐藏用法 #4：架构决策记录作为 Agent 持久记忆

大多数人的用法： 把设计决策写在 Confluence 页面上没人看，或者埋在 PR 描述里。

隐藏技巧： 用 manage_adr 把架构决策直接持久化到知识图谱中。你的 ADR 变成每次 AI 编码会话都能查询到的上下文——Agent 在建议你改 Schema 之前就知道你为什么选了 PostgreSQL 而不是 MongoDB。

import requests, json

BASE = "http://localhost:27057"
headers = {"Content-Type": "application/json", "Accept": "application/json, text/event-stream"}

def call_cbm_tool(name, arguments):
    resp = requests.post(BASE,
        headers=headers,
        json={
            "jsonrpc": "2.0",
            "method": "tools/call",
            "params": {"name": name, "arguments": arguments},
            "id": 3
        },
        timeout=10
    )
    for line in resp.text.split('\n'):
        if line.startswith('data:'):
            parsed = json.loads(line[5:])
            content = parsed.get('result', {}).get('content', {})
            for c in content:
                data = json.loads(c['text'])
                results = data.get('data', {}).get('results', [{}])[0]
                return results.get('result', {}).get('value', '')
    return resp.text

# 创建架构决策记录
adr_content = """
标题：订单域采用事件溯源
背景：订单流经 12 个微服务。排查问题需要跨服务关联日志。
       传统 CRUD 会丢失状态转换历史。
决策：在订单域采用事件溯源。将状态变更存储为 PostgreSQL 中的
     不可变事件，通过 CQRS 投射读视图。
后果：
  + 每次状态变更都有完整审计链
  + 可重事件放来重建任意读模型
  - 事件序列化的额外复杂度
  - 需要为超过 1000 个事件的订单设计快照策略
  - 团队培训需要（估计 2 个 Sprint）
"""
result = call_cbm_tool("manage_adr", {
    "project": "orders-service",
    "action": "create",
    "title": "ADR-007：订单域事件溯源",
    "content": adr_content
})
print(f"ADR 已创建: {result[:200]}")

效果： ADR 和代码上下文住在同一个知识图谱中。Agent 以后每次问"你为啥这么做？"都会自动获得回答。Confluence 链接腐烂成为历史。

数据来源： manage_adr 工具在知识图谱内提供架构决策记录的增删改查；图谱支持 17 种边类型，包含 CONFIGURES、IMPLEMENTS、TESTS。

隐藏用法 #5：跨仓库智能追踪微服务架构

大多数人的用法： 排查跨服务 Bug 时，在每个仓库里 grep URL 模式手动追踪。

隐藏技巧： 在同一个图谱存储中索引多个仓库。CROSS_* 边会跨仓库链接节点——API 网关中的路由能映射到后端服务的 handler 函数。3D 图谱 UI 将整个技术栈渲染为多星系可视化。

import requests, json

BASE = "http://localhost:27057"
headers = {"Content-Type": "application/json", "Accept": "application/json, text/event-stream"}

def call_cbm_tool(name, arguments):
    resp = requests.post(BASE,
        headers=headers,
        json={
            "jsonrpc": "2.0",
            "method": "tools/call",
            "params": {"name": name, "arguments": arguments},
            "id": 4
        },
        timeout=30
    )
    for line in resp.text.split('\n'):
        if line.startswith('data:'):
            parsed = json.loads(line[5:])
            content = parsed.get('result', {}).get('content', {})
            for c in content:
                data = json.loads(c['text'])
                results = data.get('data', {}).get('results', [{}])[0]
                return results.get('result', {}).get('value', '')
    return resp.text

# 第 1 步：索引 API 网关（自动从 @RequestMapping、@GetMapping 等注解发现 HTTP 路由）
call_cbm_tool("index_repository", {"repo_path": "/services/api-gateway"})

# 第 2 步：索引后端服务（自动从 RestTemplate、fetch 等发现 HTTP 调用点）
call_cbm_tool("index_repository", {"repo_path": "/services/order-service"})

# 第 3 步：用 get_architecture 获取跨仓库联合架构概览
result = call_cbm_tool("get_architecture", {})
print("跨仓库联合架构：")
print(result[:1000])

效果： 两个仓库都索引完后，你可以追踪请求从网关路由通过 HTTP 调用到后端 handler 的完整链路——在 3D Multi-Galaxy 图谱 UI 中可视化呈现。生产环境出问题时，Agent 不用手动排查就知道该修哪个仓库。

数据来源： 跨仓库 CROSS_* 边支持 REST/gRPC/GraphQL 检测；图谱规模可达 Linux 内核级的 481 万节点、772 万条边；get_architecture 综合输出服务、路由和依赖关系。

总结：5 个隐藏技巧

Cypher 模式检测 — 表达正则无法触及的多跳结构查询
Git Diff 爆炸半径映射 — 提交前看清精确影响范围，附带风险等级分类
团队共享图谱制品 — 提交 .codebase-memory/graph.db.zst，队友无需重建索引
架构决策记录作为 Agent 记忆 — ADR 在每次会话中可被 Agent 查询
跨仓库智能追踪 — 索引关联仓库，追踪跨微服务边界的请求链路

延伸阅读

如果你喜欢这篇深度文章，或许也会喜欢：

你试过 codebase-memory-mcp 吗？你最惊喜的发现是什么——Cypher 查询终于帮你清理了那片handler 坟场？还是团队共享制品让 CI 速度快了三倍？在评论区分享你的实战故事。

DeerFlow SuperAgent Harness: 5 Hidden Uses of the 74K-Star Open-Source Agent Framework

Fri, 26 Jun 2026 03:10:33 +0000

What if you could give an AI agent its own filesystem, its own memory, and the ability to spawn parallel workers — all in one open-source harness that just crossed 74,000 GitHub stars? Most teams still treat agents as stateless request-response machines. DeerFlow flips that assumption entirely.

DeerFlow (bytedance/deer-flow) is an open-source SuperAgent harness from ByteDance with 74,741 Stars and 10,078 Forks on GitHub. It orchestrates sub-agents, persistent memory, sandboxed execution, and extensible skills to handle tasks that take minutes to hours. Version 2.0 is a ground-up rewrite — it once hit #1 on GitHub Trending within a single day.

The 2026 Agent Landscape: Why This Matters

In 2026, AI agents are moving from demos to production. But production means state: memory across sessions, isolated execution environments, parallel task decomposition, and integration with messaging platforms where teams actually work. DeerFlow bundles all of this into a single MIT-licensed harness, with Python backends, Node.js gateway support, and a TUI workbench.

Here are five hidden uses that most developers miss when they first encounter DeerFlow.

Hidden Use #1: Skills as Markdown-Based Capability Modules

What most people do: They hard-code tool definitions in their agent config or rely on a fixed set of built-in functions.

The hidden trick: DeerFlow treats skills as structured Markdown files — SKILL.md documents that define workflows, best practices, and resource references. Skills load progressively, only when the task needs them, keeping the context window lean. You can activate any skill at runtime with /skill-name, and even install external .skill archives through the Gateway.

# Example: Creating a custom skill for API documentation generation
# File: skills/custom/api-docs/SKILL.md

SKILL_CONTENT = """
---
name: api-docs
description: "Generate OpenAPI-compatible documentation from code"
version: 1.0.0
---

# API Documentation Skill

## Workflow
1. Scan the target directory for route definitions
2. Extract request/response schemas using AST parsing
3. Generate OpenAPI 3.0 JSON spec
4. Validate with openapi-spec-validator
5. Output to docs/openapi.json

## Best Practices
- Always include example request bodies
- Tag endpoints by resource group
- Mark authentication requirements
"""

# Install via CLI:
# npx skills add https://github.com/your-org/your-skill-repo --skill api-docs

# Then activate at runtime:
# /api-docs generate src/routes/

The result: Your agent dynamically loads domain-specific knowledge without bloating the base prompt. A research task loads the research skill; a slide-creation task loads the slide skill. Token usage drops because irrelevant skills never enter the context.

Data sources: DeerFlow GitHub 74,741 Stars, 10,078 Forks (GitHub API, verified 2026-06-26). Progressive skill loading documented in official README.

Hidden Use #2: Isolated Sub-Agent Parallel Decomposition

What most people do: They run a single agent loop for complex tasks, letting context balloon until the model loses track of intermediate results.

The hidden trick: DeerFlow's lead agent spawns sub-agents on the fly — each with its own scoped context, tools, and termination conditions. Sub-agents run in parallel, report structured results back, and the lead agent synthesizes everything. Token usage from sub-agents is attributed to the dispatching step.

# Example: Research task that fans out into parallel sub-agents
# Using the embedded Python Client

from deerflow.client import DeerFlowClient

client = DeerFlowClient()

# The lead agent decomposes this into sub-agents automatically:
# Sub-agent 1: Research competitor A's pricing
# Sub-agent 2: Research competitor B's features
# Sub-agent 3: Research market trends
# Lead agent: Synthesize into comparison report

response = client.send_message(
    thread_id="research-thread-001",
    message={
        "role": "user",
        "content": """Create a comparison report of the top 5 AI agent frameworks.
        For each framework, include: star count, core architecture, language,
        unique features, and enterprise readiness. Output as a Markdown table
        with a summary recommendation."""
    }
)

# Execution modes: flash (fast), standard, pro (planning), ultra (sub-agents)
# Ultra mode triggers full parallel decomposition
print(response["status"])  # "completed"

The result: A task that would take 30 minutes of sequential agent reasoning completes in under 5 minutes with parallel sub-agents, each working in its own isolated context window.

Data sources: DeerFlow GitHub 74,741 Stars (GitHub API). Sub-agent architecture documented in official README "Sub-Agents" section. HN Algolia search for "deer-flow" returned 15 hits (max 4pts) — community discussion is early-stage.

Hidden Use #3: Persistent Long-Term Memory Across Sessions

What most people do: They pass the entire conversation history as context or use a simple vector database RAG lookup.

The hidden trick: DeerFlow builds a persistent memory of your profile, preferences, and accumulated knowledge across sessions. It stores memory locally, deduplicates facts to prevent endless accumulation, and injects relevant context back into future sessions automatically.

# Example: Configuring and using DeerFlow's memory system
# config.yaml

# The memory system is enabled by default.
# After your first session, DeerFlow remembers:
# - Your preferred output format (Markdown vs HTML)
# - Your technical stack (Python, TypeScript, etc.)
# - Your recurring workflows (weekly reports, code reviews)
# - Your writing style preferences

# First session:
response1 = client.send_message(
    thread_id="onboarding",
    message={"role": "user", "content": "I prefer concise bullet-point summaries. My stack is Python + FastAPI + PostgreSQL."}
)

# Second session — DeerFlow auto-injects memory:
response2 = client.send_message(
    thread_id="weekly-review",
    message={"role": "user", "content": "Summarize this week's commits."}
)
# The agent automatically knows: use bullet points, reference FastAPI patterns,
# check PostgreSQL migration files

# Memory updates skip duplicate facts at apply time,
# so repeated preferences don't accumulate endlessly

The result: The agent gets smarter over time without manual context management. After three sessions, it knows your team's coding conventions, preferred report formats, and recurring tasks — no need to re-explain.

Data sources: DeerFlow GitHub 74,741 Stars (GitHub API). Long-term memory system documented in official README "Long-Term Memory" section. Memory deduplication confirmed in README: "repeated preferences and context do not accumulate endlessly."

Hidden Use #4: Sandboxed Execution with Claude Code Bridge

What most people do: They run agents directly on their host machine or skip code execution entirely.

The hidden trick: DeerFlow supports Docker-based sandboxed execution AND a claude-to-deerflow skill that lets Claude Code (or Codex, Cursor, Windsurf) interact with a running DeerFlow instance directly from the terminal. You get two agents collaborating: Claude Code for local editing, DeerFlow for long-horizon research and generation.

# Step 1: Start DeerFlow (Docker recommended)
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
make setup  # Interactive wizard: choose LLM provider, sandbox mode
make docker-start

# Step 2: Install the Claude Code bridge skill
npx skills add https://github.com/bytedance/deer-flow --skill claude-to-deerflow

# Step 3: From Claude Code, send tasks to DeerFlow
# In Claude Code:
# > /claude-to-deerflow "Research the latest developments in AI agent memory 
#   systems and write a 2000-word technical brief to docs/memory-systems.md"
# > /claude-to-deerflow --mode ultra "Analyze all Python files in src/ and 
#   generate comprehensive API documentation"

# Step 4: Check status
# > /claude-to-deerflow --status

# Execution modes available:
# flash    → Fast, single-pass (good for quick lookups)
# standard → Default balanced mode
# pro      → Planning mode (agent creates execution plan first)
# ultra    → Full sub-agent decomposition (for complex multi-step tasks)

The result: You get the best of both worlds: Claude Code's precise local file editing for implementation, and DeerFlow's parallel sub-agent architecture for research, report generation, and multi-step workflows. The agents communicate over localhost:2026.

Data sources: DeerFlow GitHub 74,741 Stars (GitHub API). claude-to-deerflow skill documented in official README. Docker sandbox modes (Local/Docker/Kubernetes) confirmed in "Sandbox Mode" section.

Hidden Use #5: IM Channel Integration for Async Agent Workflows

What most people do: They interact with agents only through a web UI or CLI, checking results manually.

The hidden trick: DeerFlow supports receiving tasks from Telegram, Slack, Discord, Feishu/Lark, DingTalk, WeChat, and WeCom — no public IP required. Incoming IM messages run under the connected DeerFlow user account, and results stream back to the channel.

# config.yaml — IM Channel Configuration
channels:
  # Telegram Bot (easiest setup — long-polling, no webhook needed)
  telegram:
    bot_token: "${TELEGRAM_BOT_TOKEN}"
    # DeerFlow polls Telegram for new messages

  # Slack (Socket Mode — no public endpoint)
  slack:
    bot_token: "${SLACK_BOT_TOKEN}"
    app_token: "${SLACK_APP_TOKEN}"

  # Feishu / Lark (WebSocket)
  feishu:
    app_id: "${FEISHU_APP_ID}"
    app_secret: "${FEISHU_APP_SECRET}"

# When channel_connections is enabled, logged-in users can bind
# IM channels from the workspace UI sidebar.
# No public IP or provider callback URL needed.

# Example: A Slack bot that delegates to DeerFlow
# User in Slack: "@deerflow-bot research Q3 AI trends and post to #ai-updates"

# DeerFlow receives the message, processes it through the agent pipeline,
# and posts the result back to the #ai-updates channel.

# The agent has full access to:
# - Sub-agent decomposition (parallel research)
# - Sandbox execution (generate charts, save files)
# - Memory (recall user's previous research preferences)
# - Skills (load the "market-research" skill if available)

# Result: A complete research report posted to Slack in under 3 minutes,
# with charts generated in the sandbox and formatted per user preferences.

The result: Your agent lives where your team lives. No context-switching to a web dashboard. Assign research tasks from your phone, get results in the channel. Perfect for async teams and on-call workflows.

Data sources: DeerFlow GitHub 74,741 Stars (GitHub API). IM channels documented in official README "IM Channels" section. Supported channels: Telegram, Slack, Feishu/Lark, WeChat, WeCom, DingTalk.

Summary

Skills as Markdown modules — Progressive loading keeps context lean and makes the agent domain-adaptable without retraining
Isolated sub-agent parallel decomposition — Fan out complex tasks into parallel workers, each with scoped context
Persistent long-term memory — The agent remembers your preferences and accumulates knowledge across sessions
Sandboxed execution + Claude Code bridge — Two agents collaborating: local editing meets long-horizon research
IM channel integration — The agent lives in Telegram, Slack, Discord, or Feishu with no public IP required

Have you tried DeerFlow or a similar SuperAgent harness? What's your approach to persistent agent memory and parallel task decomposition? Share your experience in the comments.

Related articles:

DeerFlow SuperAgent 框架：7.4 万 Star 开源 Agent 框架的 5 个隐藏用法

Fri, 26 Jun 2026 03:10:27 +0000

如果你能给 AI Agent 一个自己的文件系统、自己的记忆，以及并行派生子 Agent 的能力——而且这一切都在一个开源框架里，刚在 GitHub 上突破 74,000 Star，会怎样？大多数团队仍然把 Agent 当作无状态的请求-响应机器。DeerFlow 彻底颠覆了这个假设。

DeerFlow（bytedance/deer-flow）是字节跳动开源的 SuperAgent 框架，GitHub 74,741 Star、10,078 Fork。它能编排子 Agent、持久化记忆、沙箱执行和扩展技能（Skills），处理从几分钟到几小时不等的复杂任务。2.0 版本是全新改写——发布当天就冲上了 GitHub Trending 第一名。

2026 年 Agent 格局：为什么这很重要

2026 年，AI Agent 正从 Demo 走向生产。但生产级意味着要有状态：跨会话记忆、隔离的执行环境、并行任务分解，以及与团队实际使用的消息平台的集成。DeerFlow 把所有这些都打包进一个 MIT 协议的开源框架里——Python 后端、Node.js Gateway 支持、TUI 终端工作台。

以下是大多数开发者初次接触 DeerFlow 时最容易忽略的五个隐藏用法。

隐藏用法 #1：技能（Skills）即 Markdown 能力模块

大多数人的做法： 在 Agent 配置里硬编码工具定义，或依赖一组固定的内置函数。

隐藏技巧： DeerFlow 把技能视为结构化的 Markdown 文件——SKILL.md 文档定义了工作流、最佳实践和资源引用。技能按需渐进式加载，只在任务需要时才加载，保持上下文窗口精简。你可以在运行时通过 /skill-name 激活任何技能，甚至可以通过 Gateway 安装外部 .skill 压缩包。

# 示例：创建一个自定义技能，用于从代码生成 API 文档
# 文件：skills/custom/api-docs/SKILL.md

SKILL_CONTENT = """
---
name: api-docs
description: "从代码生成 OpenAPI 兼容文档"
version: 1.0.0
---

# API 文档技能

## 工作流
1. 扫描目标目录中的路由定义
2. 使用 AST 解析提取请求/响应 Schema
3. 生成 OpenAPI 3.0 JSON 规范
4. 用 openapi-spec-validator 验证
5. 输出到 docs/openapi.json

## 最佳实践
- 始终包含示例请求体
- 按资源组标记端点
- 标注认证要求
"""

# 通过 CLI 安装：
# npx skills add https://github.com/your-org/your-skill-repo --skill api-docs

# 运行时激活：
# /api-docs generate src/routes/

效果： Agent 按需加载领域知识，不会膨胀基础提示词。研究任务加载研究技能，幻灯片创建任务加载幻灯片技能。不相关的技能永远不会进入上下文，Token 消耗显著降低。

数据来源： DeerFlow GitHub 74,741 Star、10,078 Fork（GitHub API 验证，2026-06-26）。渐进式技能加载机制在官方 README 中有文档记录。

隐藏用法 #2：隔离子 Agent 并行任务分解

大多数人的做法： 用单个 Agent 循环处理复杂任务，让上下文膨胀到模型失去对中间结果的追踪。

隐藏技巧： DeerFlow 的主 Agent 可以动态生成子 Agent——每个子 Agent 有自己独立的作用域、工具和终止条件。子 Agent 并行运行，将结构化结果汇报回来，主 Agent 将所有内容综合成最终输出。子 Agent 的 Token 消耗会归属到调度步骤。

# 示例：研究任务自动扇出到并行子 Agent
# 使用嵌入式 Python Client

from deerflow.client import DeerFlowClient

client = DeerFlowClient()

# 主 Agent 自动将任务分解为子 Agent：
# 子 Agent 1：研究竞争对手 A 的定价
# 子 Agent 2：研究竞争对手 B 的功能
# 子 Agent 3：研究市场趋势
# 主 Agent：综合成对比报告

response = client.send_message(
    thread_id="research-thread-001",
    message={
        "role": "user",
        "content": """创建 Top 5 AI Agent 框架的对比报告。
        每个框架包括：Star 数量、核心架构、编程语言、
        独特功能和企业就绪度。输出为 Markdown 表格
        并附总结推荐。"""
    }
)

# 执行模式：flash（快速）、standard（默认）、pro（规划）、ultra（子 Agent）
# Ultra 模式触发完整的并行分解
print(response["status"])  # "completed"

效果： 一个原本需要 30 分钟顺序推理的任务，在并行子 Agent 下不到 5 分钟完成——每个子 Agent 在自己的隔离上下文窗口中工作。

数据来源： DeerFlow GitHub 74,741 Star（GitHub API）。子 Agent 架构在官方 README "Sub-Agents" 章节有文档。HN Algolia 搜索 "deer-flow" 返回 15 条结果（最高 4 分）——社区讨论处于早期阶段。

隐藏用法 #3：跨会话持久化长期记忆

大多数人的做法： 把整个对话历史作为上下文传入，或用简单的向量数据库做 RAG 检索。

隐藏技巧： DeerFlow 跨会话构建你的用户画像、偏好和积累的知识。记忆存储在本地，自动去重防止重复信息无限积累，并在未来会话中自动注入相关上下文。

# 示例：配置和使用 DeerFlow 的记忆系统
# config.yaml

# 记忆系统默认启用。
# 首次会话后，DeerFlow 会记住：
# - 你偏好的输出格式（Markdown 还是 HTML）
# - 你的技术栈（Python、TypeScript 等）
# - 你的周期性工作流（周报、代码审查）
# - 你的写作风格偏好

# 第一次会话：
response1 = client.send_message(
    thread_id="onboarding",
    message={"role": "user", "content": "我喜欢简洁的项目符号摘要。我的技术栈是 Python + FastAPI + PostgreSQL。"}
)

# 第二次会话——DeerFlow 自动注入记忆：
response2 = client.send_message(
    thread_id="weekly-review",
    message={"role": "user", "content": "总结本周的提交记录。"}
)
# Agent 自动知道：用项目符号、参考 FastAPI 模式、
# 检查 PostgreSQL 迁移文件

# 记忆更新时跳过重复条目的应用，
# 所以重复的偏好不会无限积累

效果： Agent 随时间变得更智能，无需手动上下文管理。三次会话后，它就知道你团队的编码规范、偏好的报告格式和周期性任务——不需要重复解释。

数据来源： DeerFlow GitHub 74,741 Star（GitHub API）。长期记忆系统在官方 README "Long-Term Memory" 章节有文档。记忆去重机制在 README 中确认："重复的偏好和上下文不会无限积累。"

隐藏用法 #4：沙箱执行 + Claude Code 桥接

大多数人的做法： 在主机上直接运行 Agent，或者完全跳过代码执行。

隐藏技巧： DeerFlow 支持 Docker 沙箱隔离执行，同时提供 claude-to-deerflow 技能，让 Claude Code（或 Codex、Cursor、Windsurf）直接从终端与运行中的 DeerFlow 交互。两个 Agent 协作：Claude Code 负责本地编辑，DeerFlow 负责长时间研究和生成。

# 第 1 步：启动 DeerFlow（推荐 Docker）
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
make setup  # 交互式向导：选择 LLM 提供商、沙箱模式
make docker-start

# 第 2 步：安装 Claude Code 桥接技能
npx skills add https://github.com/bytedance/deer-flow --skill claude-to-deerflow

# 第 3 步：从 Claude Code 发送任务给 DeerFlow
# 在 Claude Code 中：
# > /claude-to-deerflow "研究 AI Agent 记忆系统的最新进展，
#   写一份 2000 字的技术简报到 docs/memory-systems.md"
# > /claude-to-deerflow --mode ultra "分析 src/ 下所有 Python 文件，
#   生成完整的 API 文档"

# 第 4 步：检查状态
# > /claude-to-deerflow --status

# 可用执行模式：
# flash    → 快速，单次通过（适合快速查询）
# standard → 默认平衡模式
# pro      → 规划模式（Agent 先制定执行计划）
# ultra    → 完整子 Agent 分解（适合复杂多步任务）

效果： 两全其美：Claude Code 精确的本地文件编辑用于实现，DeerFlow 的并行子 Agent 架构用于研究、报告生成和多步工作流。两个 Agent 通过 localhost:2026 通信。

数据来源： DeerFlow GitHub 74,741 Star（GitHub API）。claude-to-deerflow 技能在官方 README 有文档。Docker 沙箱模式（本地/Docker/Kubernetes）在 "Sandbox Mode" 章节确认。

隐藏用法 #5：IM 频道集成，异步 Agent 工作流

大多数人的做法： 只通过 Web UI 或 CLI 与 Agent 交互，手动检查结果。

隐藏技巧： DeerFlow 支持从 Telegram、Slack、Discord、飞书、钉钉、微信、企业微信接收任务——无需公网 IP。传入的 IM 消息在连接的 DeerFlow 用户账户下运行，结果自动流回频道。

# config.yaml — IM 频道配置
channels:
  # Telegram Bot（最简单——长轮询，无需 Webhook）
  telegram:
    bot_token: "${TELEGRAM_BOT_TOKEN}"

  # Socket Mode（无需公网端点）
  slack:
    bot_token: "${SLACK_BOT_TOKEN}"
    app_token: "${SLACK_APP_TOKEN}"

  # 飞书（WebSocket）
  feishu:
    app_id: "${FEISHU_APP_ID}"
    app_secret: "${FEISHU_APP_SECRET}"

# 启用 channel_connections 后，登录用户可以从工作区侧边栏
# 绑定 IM 频道。无需公网 IP 或提供商回调 URL。

# 示例：一个委托给 DeerFlow 的 Slack Bot
# Slack 用户："@deerflow-bot 研究 Q3 AI 趋势，发布到 #ai-updates"

# DeerFlow 接收消息，通过 Agent 流水线处理，
# 将结果发布回 #ai-updates 频道。

# Agent 拥有完整访问权限：
# - 子 Agent 分解（并行研究）
# - 沙箱执行（生成图表、保存文件）
# - 记忆（调取用户之前的研究偏好）
# - 技能（加载 "market-research" 技能）

# 效果：3 分钟内完成完整研究报告发布到 Slack，
# 图表在沙箱中生成，按用户偏好格式化。

效果： Agent 住在你团队工作的地方。不需要切换到 Web 仪表板。从手机上分配研究任务，结果自动发到频道。非常适合异步团队和 on-call 工作流。

数据来源： DeerFlow GitHub 74,741 Star（GitHub API）。IM 频道在官方 README "IM Channels" 章节有文档。支持频道：Telegram、Slack、飞书、微信、企业微信、钉钉。

总结

Markdown 技能模块 — 渐进式加载保持上下文精简，让 Agent 无需重新训练即可适配领域知识
隔离子 Agent 并行分解 — 将复杂任务扇出到并行工作者，每个有独立上下文
持久化长期记忆 — Agent 记住你的偏好，跨会话积累知识
沙箱执行 + Claude Code 桥接 — 两个 Agent 协作：本地编辑 + 长时间研究
IM 频道集成 — Agent 住在 Telegram、Slack、Discord 或飞书中，无需公网 IP

你尝试过 DeerFlow 或类似的 SuperAgent 框架吗？你对持久化 Agent 记忆和并行任务分解有什么做法？欢迎在评论区分享你的经验。

相关文章：

OpenCode's 5 Hidden Uses: The 178K-Star Terminal AI Agent That Swaps Providers Mid-Session

Thu, 25 Jun 2026 03:06:41 +0000

What if your terminal AI agent could talk to 30+ LLM providers, run isolated background tasks, load custom plugins from npm, and authenticate to MCP servers — all from a single npm install?

OpenCode is a 178,218-star open source AI coding agent built in TypeScript. It crossed 1,274 points on Hacker News in March 2026, and its latest release (v1.17.10, June 24 2026) added MCP resource templates, OAuth-bound callbacks, and a new --mini CLI mode. Most developers use it as a Claude Code alternative in the terminal — but scratch the surface and you'll find a plugin ecosystem, multi-agent architecture, and provider abstraction that go far beyond autocomplete.

In 2026's landscape of AI coding tools, where Cursor, Claude Code, Codex CLI, and Goose all compete for developer mindshare, OpenCode stands out by being completely open source (MIT license), provider-agnostic (30+ providers including self-hosted), and built around an extensible plugin + skill + MCP architecture. Here are five hidden uses that most people miss.

Hidden Use #1: Multi-Provider Fallback with Custom Providers

What most people do: Use OpenCode with a single API key — Anthropic, OpenAI, or whatever they have.

The hidden trick: OpenCode's provider plugin system supports 30+ providers out of the box, including Anthropic, OpenAI, Google, DeepSeek, Mistral, Groq, TogetherAI, OpenRouter, GitHub Copilot, GitLab, Snowflake Cortex, and many more. You can configure multiple providers with different models and switch between them mid-session using the /model command. Even better, you can add custom OpenAI-compatible providers pointing to self-hosted models (Ollama, vLLM, LM Studio).

# Configure OpenCode with a custom provider for local Ollama
opencode config set providers.ollama.baseUrl "http://localhost:11434/v1"
opencode config set providers.ollama.models '[{"id":"llama3.3","name":"Llama 3.3 70B"}]'

# Switch between providers in-session
# Just type: /model ollama/llama3.3
# Or: /model anthropic/claude-sonnet-4-20250514

The result: Your coding agent becomes provider-agnostic. When Anthropic rate-limits you, switch to DeepSeek. When you need a cheap model for exploration, use Groq. When you need to run on-prem, point to your Ollama instance — all without leaving the session.

Data sources: OpenCode GitHub 178,218 Stars, HN 1,274 pts/618 comments (story 47460525), 30+ provider plugins confirmed from repo tree (packages/core/src/plugin/provider/*.ts).

Hidden Use #2: Plugin Ecosystem — npm Packages as Agent Extensions

What most people do: Use OpenCode as-is, with its built-in features.

The hidden trick: OpenCode has a full plugin system. You can install plugins from npm packages, load custom ones from directories, or write your own. Plugins can add custom agents, commands, providers, and even inject system context. The plugin lifecycle supports installation, loading, hot-reloading, and sandboxing.

# Install a plugin from npm
opencode plugin install @my-org/opencode-custom-agent

# Load a local plugin from a directory
opencode --plugin ./my-custom-plugin/

# List installed plugins
opencode plugin list

Plugins are written in TypeScript and can register:

Custom agents (with their own system prompts and tool sets)
Custom slash commands (e.g., /review-pr, /deploy-staging)
Custom LLM providers (pointing to any OpenAI-compatible API)
Custom tools (via MCP server integration)

The result: You can extend OpenCode with domain-specific capabilities — a /run-migrations command that knows your database schema, a code-review agent tuned to your team's conventions, or a deployment plugin that wraps your CI/CD pipeline.

Data sources: OpenCode v1.17.10 release notes (2026-06-24), plugin system confirmed in repo tree (packages/plugin/src/v2/, packages/core/src/plugin/).

Hidden Use #3: MCP OAuth — Authenticated Tool Use with External Services

What most people do: Use MCP servers with either no auth or static API keys pasted into config.

The hidden trick: OpenCode supports full MCP OAuth flows. When you connect to an MCP server that requires OAuth (e.g., GitHub, Slack, Jira), OpenCode opens a browser-based OAuth flow, handles the callback on an IPv4 loopback server (bound for security in v1.17.10), and manages token refresh automatically. This means you can use GitHub's MCP server to create issues, read PRs, and manage repositories — all through natural language in your terminal.

# Add an MCP server with OAuth support
opencode mcp add github --url https://api.github.com/mcp

# OpenCode will prompt OAuth login in browser
# After auth, you can say:
# "Create a PR from my current branch to main with title 'Fix auth bug'"
# "List all open issues assigned to me"

The result: Your terminal agent becomes a bridge to external services with proper authentication. No more pasting tokens into config files — OAuth handles it securely with automatic refresh.

Data sources: OpenCode v1.17.10 release notes — "Bound MCP OAuth callbacks to IPv4 loopback for better local auth reliability" (@he-yufeng), MCP auth system confirmed in packages/opencode/src/mcp/auth.ts.

Hidden Use #4: Background Sub-Agents and the Plan/Build Architecture

What most people do: Use OpenCode's default "build" agent for everything.

The hidden trick: OpenCode ships with two built-in agents: build (full access, default) and plan (read-only, asks permission before running commands). You switch between them with the Tab key. The plan agent is perfect for exploring unfamiliar codebases, analyzing architecture, or planning refactors — without risk of accidental edits. Additionally, OpenCode supports background sub-agents that run in parallel. You can spawn a @general sub-agent for complex searches while continuing to code in the main session.

# Start OpenCode
opencode

# Press Tab to switch between build and plan agents
# In plan agent: "Analyze the authentication flow in this codebase"
# In build agent: "Refactor the auth module to use the new token format"

# Spawn a sub-agent for background work
# Type: @general search for all TODO items related to error handling
# Continue coding while sub-agent works

The result: The plan agent acts as a safe exploration mode — you can hand it to a junior developer or use it in CI pipelines where you want analysis without modifications. Background sub-agents let you parallelize research and coding, effectively turning your terminal into a multi-agent workspace.

Data sources: OpenCode README (dev branch) — "build agent (full-access) / plan agent (read-only, asks permission)", HN 319pts story "Opencode: AI coding agent, built for the terminal" (id 44482504).

Hidden Use #5: Skills System — Reusable Prompt Templates as Code

What most people do: Type the same instructions repeatedly ("write tests", "review this PR", "check for security issues").

The hidden trick: OpenCode has a built-in skills system. Skills are markdown files (.md) stored in .opencode/skills/ that define reusable prompt templates. You can invoke them with /skill-name, and they support frontmatter configuration for customization. OpenCode ships with built-in skills like customize-opencode and effect, and you can create your own.

# .opencode/skills/review-security.md
---
name: review-security
description: "Security-focused code review"
tools: [read, list, grep]
---

Review the current file for security vulnerabilities:
1. Check for SQL injection patterns
2. Look for hardcoded secrets or API keys
3. Verify input validation on all user-facing endpoints
4. Flag any use of eval() or dynamic imports

# Invoke the custom skill
/review-security

# Or use built-in skills
/customize-opencode  # OpCode's own configuration wizard

The result: Skills turn repeated instructions into shareable, version-controlled templates. Your team can maintain a library of skills in the repo, and every developer on the team gets the same consistent behavior — no more copy-pasting prompts or forgetting steps in code reviews.

Data sources: OpenCode repo tree — .opencode/skills/effect/SKILL.md, packages/core/src/skill/*, packages/opencode/src/skill/discovery.ts, v1.17.10 release notes mentioning skill base directories.

Summary: 5 Hidden Uses of OpenCode

Multi-Provider Fallback — Switch between 30+ LLM providers mid-session, including self-hosted models
Plugin Ecosystem — Extend the agent with npm packages, custom agents, and domain-specific commands
MCP OAuth — Authenticate to external services (GitHub, Slack, Jira) via browser-based OAuth flows
Plan/Build Architecture — Use read-only plan agents for safe exploration and background sub-agents for parallel work
Skills System — Create reusable, version-controlled prompt templates for consistent team workflows

Previously on This Series

If you enjoyed this article, check out previous entries in the "5 Hidden Uses" series:

Have you discovered a hidden use for OpenCode — a plugin, skill, or workflow that most people don't know about? Drop it in the comments below!

OpenCode 的 5 个隐藏用法：17.8 万 Star 终端 AI 代理，会话中随意切换提供商

Thu, 25 Jun 2026 03:06:35 +0000

你知道吗？你的终端 AI 代理其实可以无缝切换 30+ 个 LLM 提供商、运行隔离的后台任务、从 npm 加载自定义插件，还能通过 OAuth 认证连接 GitHub 和 Slack —— 这一切只需一次 npm install。

OpenCode 是一个拥有 178,218 Stars 的开源 AI 编程代理，用 TypeScript 构建。它在 2026 年 3 月突破了 1,274 票的程序员新闻（Hacker News）讨论度，最新版本（v1.17.10，2026 年 6 月 24 发布）新增了 MCP 资源模板、OAuth 绑定回调和新版 --mini CLI 模式。大多数人把它当作终端里的 Claude Code 替代品 —— 但深入了解后你会发现，它的插件生态、多代理架构和提供商抽象层远超普通自动补全工具。

在 2026 年 AI 编程工具的格局中，Cursor、Claude Code、Codex CLI 和 Goose 都在争夺开发者的注意力。OpenCode 之所以脱颖而出，是因为它采用 MIT 完全开源、提供商无关（支持 30+ 提供商包括自托管）、并围绕可扩展的插件 + 技能 + MCP 架构搭建。以下是大多数人忽略的五个隐藏用法。

隐藏用法 #1：多提供商故障转移 + 自定义提供商

大多数人的用法： 只用单个 API 密钥 —— Anthropic 或 OpenAI。

隐藏技巧： OpenCode 的提供商插件系统原生支持 30+ 提供商，包括 Anthropic、OpenAI、Google、DeepSeek、Mistral、Groq、TogetherAI、OpenRouter、GitHub Copilot、GitLab、Snowflake Cortex 等。你可以配置多个提供商和不同模型，用 /model 命令在会话中随时切换。更妙的是，你可以添加指向自托管模型的自定义 OpenAI 兼容提供商（Ollama、vLLM、LM Studio）。

# 配置 OpenCode 连接本地 Ollama 提供商
opencode config set providers.ollama.baseUrl "http://localhost:11434/v1"
opencode config set providers.ollama.models '[{"id":"llama3.3","name":"Llama 3.3 70B"}]'

# 在会话中切换提供商
# 输入: /model ollama/llama3.3
# 或者: /model anthropic/claude-sonnet-4-20250514

效果： 你的编程代理变成了提供商无关的。当 Anthropic 触发速率限制时，切换到 DeepSeek。需要便宜的探索模型时，用 Groq。需要在本地部署时，指向 Ollama 实例 —— 所有操作都不需要离开当前会话。

数据来源： OpenCode GitHub 178,218 Stars，HN 1,274 pts/618 评论（story 47460525），30+ 提供商插件从仓库目录树确认（packages/core/src/plugin/provider/*.ts）。

隐藏用法 #2：插件生态 —— 用 npm 包扩展代理能力

大多数人的用法： 直接用 OpenCode 的内置功能。

隐藏技巧： OpenCode 拥有完整的插件系统。你可以从 npm 包安装插件，从目录加载自定义插件，或自己编写。插件可以添加自定义代理、命令、提供商、甚至注入系统上下文。插件生命周期支持安装、加载、热重载和沙箱隔离。

# 从 npm 安装插件
opencode plugin install @my-org/opencode-custom-agent

# 从本地目录加载插件
opencode --plugin ./my-custom-plugin/

# 列出已安装插件
opencode plugin list

插件用 TypeScript 编写，可以注册：

自定义代理（拥有独立系统提示和工具集）
自定义斜杠命令（如 /review-pr、/deploy-staging）
自定义 LLM 提供商（指向任意 OpenAI 兼容 API）
自定义工具（通过 MCP 服务器集成）

效果： 你可以用领域特定能力扩展 OpenCode —— 一个了解数据库架构的 /run-migrations 命令、一个针对你团队规范调整过的代码审查代理、或一个封装 CI/CD 工具的部署插件。

数据来源： OpenCode v1.17.10 发布说明（2026-06-24），插件系统从仓库目录树确认（packages/plugin/src/v2/, packages/core/src/plugin/）。

隐藏用法 #3：MCP OAuth —— 与外部服务的认证工具调用

大多数人的用法： 使用没有认证或静态 API 密钥直接粘贴到配置的 MCP 服务器。

隐藏技巧： OpenCode 支持完整的 MCP OAuth 流程。当你连接需要 OAuth 的 MCP 服务器（如 GitHub、Slack、Jira）时，OpenCode 会打开浏览器进行 OAuth 认证，在 IPv4 回环服务器上处理回调（v1.17.10 中为安全起见绑定），并自动管理令牌刷新。这意味着你可以通过自然语言在终端中使用 GitHub 的 MCP 服务器来创建 Issue、阅读 PR 和管理仓库。

# 添加支持 OAuth 的 MCP 服务器
opencode mcp add github --url https://api.github.com/mcp

# OpenCode 会在浏览器中提示 OAuth 登录
# 认证后，你可以说：
# "从当前分支创建一个标题为 'Fix auth bug' 的 PR 到 main"
# "列出所有分配给我的未关闭 Issue"

效果： 你的终端代理成为了连接外部服务的桥梁，拥有正确的认证机制。不再需要在配置文件中粘贴令牌 —— OAuth 安全地处理一切，并自动刷新。

数据来源： OpenCode v1.17.10 发布说明 —— "将 MCP OAuth 回调绑定到 IPv4 回环以提高本地认证可靠性"（@he-yufeng），MCP 认证系统见 packages/opencode/src/mcp/auth.ts。

隐藏用法 #4：规划/构建双代理架构 + 后台子代理

大多数人的用法： 一直用默认的 "build" 代理做所有事。

隐藏技巧： OpenCode 内置两个代理：build（完全访问权限，默认）和 plan（只读模式，运行命令前请求权限）。你可以用 Tab 键在它们之间切换。Plan 代理非常适合探索不熟悉的代码库、分析架构或规划重构 —— 而且不会有意外编辑的风险。此外，OpenCode 支持后台并行运行的子代理。你可以派一个 @general 子代理做复杂搜索，同时继续在主会话中写代码。

# 启动 OpenCode
opencode

# 按 Tab 切换 build 和 plan 代理
# 在 plan 代理中: "分析这个代码库的认证流程"
# 在 build 代理中: "重构 auth 模块使用新的 token 格式"

# 派后台子代理做并行工作
# 输入: @general 搜索所有与错误处理相关的 TODO 项
# 子代理工作时你继续写代码

效果： Plan 代理充当安全的探索模式 —— 你可以把它交给初级开发者，或在 CI 管道中使用（只需要分析不需要修改）。后台子代理让你能并行进行研究和编码，有效地将终端变成多代理工作空间。

数据来源： OpenCode README（dev 分支）—— "build 代理（完全访问）/ plan 代理（只读，请求权限）"，HN 319pts 讨论 "Opencode: AI coding agent, built for the terminal"（id 44482504）。

隐藏用法 #5：技能系统 —— 用可复用的提示模板替代重复输入

大多数人的用法： 反复输入相同的指令（"写测试"、"审查这个 PR"、"检查安全问题"）。

隐藏技巧： OpenCode 拥有内置的技能系统。技能是存放在 .opencode/skills/ 中的 Markdown 文件（.md），定义可复用的提示模板。你调用 /skill-name 即可使用，它们支持前置元数据配置以便自定义。OpenCode 内置了 customize-opencode 和 effect 等技能，你也可以创建自己的。

# .opencode/skills/review-security.md
---
name: review-security
description: "安全导向的代码审查"
tools: [read, list, grep]
---

审查当前文件的安全漏洞：
1. 检查 SQL 注入模式
2. 查找硬编码的密钥或 API 密钥
3. 验证所有面向用户的端点的输入校验
4. 标记任何 eval() 或动态导入的使用

# 调用自定义技能
/review-security

# 或使用内置技能
/customize-opencode  # OpenCode 自己的配置向导

效果： 技能将重复的指令变成可分享、版本控制的模板。你的团队可以在仓库中维护一套技能库，团队中的每个开发者都能获得一致的行为 —— 不再需要复制粘贴提示词或在代码审查中遗漏步骤。

数据来源： OpenCode 仓库目录树 —— .opencode/skills/effect/SKILL.md，packages/core/src/skill/*，packages/opencode/src/skill/discovery.ts，v1.17.10 发布说明中提到技能基础目录。

总结：OpenCode 的 5 个隐藏用法

多提供商故障转移 —— 在 30+ LLM 提供商之间随时切换，包括自托管模型
插件生态 —— 用 npm 包、自定义代理和领域特定命令扩展代理能力
MCP OAuth —— 通过浏览器 OAuth 流程认证外部服务（GitHub、Slack、Jira）
规划/构建架构 —— 用只读规划代理安全探索，用后台子代理并行工作
技能系统 —— 创建可复用、版本控制的提示模板，实现团队一致的工作流

系列回顾

如果你喜欢这篇文章，欢迎阅读"5 个隐藏用法"系列的前作：

你有没有发现 OpenCode 的隐藏用法 —— 一个插件、技能或大多数人不知道的工作流？欢迎在评论区分享！