ming-probe-langchain

乾坤镜（Mingjing）LangChain 自动探针 —— pip install 即自动激活，零代码改动。

pip install ming-probe-langchain

装完即生效，所有 LangChain 调用（LLM invoke、tool call、retriever、stream、batch）自动上报到乾坤镜。

---

功能

1. 自动上报

安装后无需任何 import 或配置，首次使用时自动激活：

# 一切照常 —— 探针自动拦截
llm.invoke("你好")            # → 上报 llm_invoke 事件
tool.invoke("搜索天气")       # → 上报 tool_call 事件
retriever.invoke("文档")      # → 上报 memory_retrieve 事件

支持 11 类事件：llm_invoke、llm_output、tool_call、memory_retrieve、agent_step、error、stream_token、chat_model_start、cache_hit、relevance_scores、chunk。

2. 查询乾坤镜健康状态

from ming_probe_langchain import get_health

report = get_health()
print(report["archiver_lag"]["desc"])  # "0.5 秒"
print(report["overall"])               # "ok" / "warn" / "no_archiver"

返回 6 项指标：

指标	说明	警告阈值
archiver_lag	归档器延迟	>5s
wal_size	WAL 文件大小	>100MB
hot_dir_pileup	热轨文件堆积	>200文件 或 >50MB
disk_free	磁盘剩余空间	<500MB
lit_lite	诊断引擎输出	无文件 = 未启用
mirror	OTEL Bridge 状态	未运行 = 正常（非必需）

也支持纯文本格式（适合 LLM 消费）：

from ming_probe_langchain import get_health_text

print(get_health_text())
# 乾坤镜健康报告 — 总体状态: OK
#   ✓ archiver_lag: 0.5 秒 (ok) [阈值: <5s]
#   ✓ wal_size: 0.14 MB (ok) [阈值: <100MB]
#   ...

3. 给 LangChain Agent 查健康工具

把 MingHealthTool 加入你的工具列表，Agent 自主决定何时查健康：

from langchain.agents import create_react_agent
from ming_probe_langchain import MingHealthTool

tools = [MingHealthTool()]
agent = create_react_agent(llm, tools)

# 当 Agent 发现异常或需要排查系统状态时，会自动调用

---

手动初始化（不依赖自动激活）

from ming_probe_langchain import init_langchain_probe

probe = init_langchain_probe(system="my_app", mode="white")

可用参数：

• system：自定义系统名（默认 langchain），用于在乾坤镜中区分不同应用
• mode："white"（默认，上报 11 类事件）或 "black"（仅通过 /proc 系统级观测，完整性降至 0.6）

Session ID 传递

llm.invoke("你好", config={"configurable": {"session_id": "user_123"}})

---

前置条件

需乾坤镜后端（归档器）在后台运行。两种方式：

# 方式 1：pip 安装完整乾坤镜（推荐）
pip install mingjing
ming start            # 启动归档器守护进程
ming web start        # 启动 Web 面板（可选，端口 18088）

# 方式 2：Docker
docker run -d --name ming -p 18088:18088 mingjing

没有归档器时，探针仍可正常发射事件（写入热轨文件），归档器启动后自动消费。

---

升级兼容性

探针通过 monkey-patch 和 PEP 302 import hook 自动激活，升级 langchain-core 后需要验证探针是否仍正常工作。

升级 langchain-core 后，探针会自动检测版本并输出到 stderr：

[ming-probe-langchain] langchain-core 0.3.25 detected. Tested: >=1.0. See README for compatibility.

验证方法：

1. 启动任意使用 LangChain 的 Python 脚本，检查 stderr 是否有版本信息
2. 运行快速验证：python -c "import ming_probe_langchain; print('OK')"
3. 检查热轨目录 ~/.ming/hot/ 是否有新 .jsonl 文件
4. 确认归档器运行正常：python -m mingjing health

注意：LangChain 大版本升级可能改变内部模块路径或方法签名，导致 monkey-patch 静默失效（探针不报错但不产生事件）。如果升级后探针不工作，请检查 langchain-core 版本是否仍在支持范围内。

兼容性

环境	要求
Python	>= 3.10
langchain-core	>= 1.0（含 langchain >= 0.3）
第三方依赖	零（仅 Python 标准库）

---

原理

LangChain 调用 → monkey-patched invoke() / BaseCallbackHandler
              → ProbeUni.emit()
              → ~/.ming/hot/*.jsonl（热轨）
              → 乾坤镜归档器消费 → SQLite / MySQL

PEP 302 import hook 机制，在 langchain_core 首次导入时自动注入。不需要改代码、不需要配 callback、不需要手动初始化。

---

许可

Business Source License 1.1 — 与乾坤镜主包一致。全球年收入低于 $100,000 USD 的公司和个人可免费生产使用。详见主仓库 LICENSE 文件。