乾坤镜 Mingjing

仓库 Ming_qiankun · PyPI mingjing · CLI ming

AI Agent 观测阵列 · 档案管理局 · 诊断引擎 — 全量记录 Agent 平台的 LLM 调用、工具执行、记忆检索与编排行为，支持可扩展的插件化诊断（标配诊断插件 LIT lite 目前支持 157 种病症规则）。

🌏 English | 📖 完整手册

许可声明：乾坤镜采用 Business Source License 1.1。年收入 <$100K 的公司和个人免费商用，非商用无限制。2030-12-31 自动转换为 Apache 2.0。

乾坤镜是 LIT 1.4 的轻量折射阵列，也是 Agent 行为的档案管理局。 它通过热轨 JSONL 文件 + SQLite/MySQL 持久层，为 OpenClaw、Hermes、LangChain 等 Agent 框架提供全量行为记录与可扩展的插件化诊断（LlamaIndex、CrewAI、OpenHands、AutoGPT 适配器 Coming Soon）。

为什么选乾坤镜？

乾坤镜是 Agent 行为的档案管理局：探针全量记录 LLM 调用、工具执行、记忆检索与编排行为，哈希链防篡改，本地零依赖。标配诊断插件 LIT lite 内置 157 种病症规则，插件化架构支持扩展至更多。Standalone 模式：0 LLM 调用 · 0 写回 · 0 联网，数据不离机。

按场景选择

乾坤镜的差异化

定位：不是要替代 LangSmith/Langfuse，而是为纯本地部署、资源受限、需要语义诊断而非原始指标的场景提供零依赖方案。

本地全量记录 + 哈希链完整性 + 可配置保留策略，天然支持 EU AI Act Art. 12/19 记录保留合规。

📖 完整手册：请参阅 updocs/ 目录下的完整文档。

5 分钟上手

1. 安装

# 方式一：PyPI 安装（推荐）
pip install mingjing

# 方式二：从源码克隆
git clone https://github.com/wulun811/Ming_qiankun.git
cd Ming_qiankun

2. 启动服务（零依赖）

为什么分两个入口？ python3 -m src.ming start 只启动归档器（40MB RSS）， ming web serve 额外启动 Web 面板（40MB100MB，视页面内容）。 资源受限场景可只开归档器，通过 CLI ming dx 查诊断，零前端开销。

# Standalone 模式 — 纯 Python 标准库，零第三方依赖
# 启动归档器守护进程（PyPI / 源码通用）：
python3 -m src.ming start

# 启动 Web 面板（可选）：
ming web serve

3. 发射测试事件

PyPI 安装用户（无需 git clone）： 安装后直接使用，探针模块自动在包路径中。

# PyPI 用户：一行命令发射测试事件
python -m mingjing demo

# 源码用户：以下命令需在项目根目录执行
python -c "
import sys; sys.path.insert(0, 'src')
from probe_uni import ProbeUni
p = ProbeUni(system='demo', mode='white')
p.emit('llm_invoke', {
    'layer_agent': {'step_id': 'test', 'session_id': 's1', 'agent_name': 'demo'},
    'layer_llm': {'model': 'gpt-4', 'input_tokens': 100, 'output_tokens': 50, 'latency_ms': 230, 'cache_hit': False},
    'layer_network': {'target_host': 'api.openai.com', 'status_code': 200}
})
print('Event emitted!')
"

4. 查看诊断

# 查看当前系统诊断（无需启动 Web 面板）
ming dx list

5. 查看 Web 目镜

# 启动 Web 服务（自动导出 + 自动刷新，绑定 127.0.0.1:18088）
ming web serve

# 局域网访问
ming web serve --port 18088
# 浏览器打开 http://localhost:18088 或 http://<本机IP>:18088

自动更新：Web 服务内置每 30 秒自动导出 data.json + 前端自动刷新，无需手动执行 export 命令。

局域网访问：

Docker 一键运行

docker build -t ming .
docker run -d --name ming -p 18088:18088 ming
# 默认启动归档器 + Web 面板（总 RSS ~140MB）
# 打开 http://localhost:18088

架构概览

┌─────────────┐     JSONL hot files      ┌──────────────┐
│  Probes     │ ───────────────────────► │  Archiver    │
│  (无状态)    │                          │  (唯一写入者) │
└─────────────┘                          └──────┬───────┘
       │                                        │
       │  OpenClaw / Hermes                     │ SQLite / MySQL
       │  LangChain / LlamaIndex                ▼
       │  CrewAI / OpenHands / AutoGPT   ┌──────────────┐
       │                                 │  Query       │
       └────────────────────────────────►│  Bridge      │
                                         └──────┬───────┘
                                                │
                                          ┌─────▼─────┐
                                          │  Web UI   │
                                          └───────────┘

核心模块

适配器（官方参考实现）

标记"Coming Soon"的适配器代码已实现，正在集成测试中，欢迎提前试用并反馈。

适配器升级检查清单

升级宿主平台（OpenClaw / OpenCode / Hermes / LangChain）后，按以下步骤验证探针是否正常工作：

所有适配器升级后均可通过 python -m mingjing health 检查归档器状态。

诊断能力（50 种典型病症示例）

标配诊断插件 LIT lite 内置 157 种病症检测规则（插件化架构支持扩展至更多），以下是 OpenClaw 运行时可自动诊断的 50 个典型示例：

系统层

网络层

模型层

工具层

Agent 层

探针底座 & 数据质量

标配诊断插件 LIT lite 的 157 种病症定义 见 config/diseases.yaml。通过 ming dx list 查看当前系统诊断结果。

当前规则内置在包中，需随版本更新。用户自定义规则引擎已在路线图中。

性能

882K 测试中 0.1% 未归档是热轨缓存中的事件，在测试窗口关闭时尚末被扫描到，非数据丢失。归档器持续运行后全部落库。

双模式

# Standalone（默认）
python3 -m src.ming start

# Cluster
MING_MODE=cluster \
  WQ_DB_HOST=127.0.0.1 \
  WQ_DB_USER=root \
  WQ_DB_PASSWORD=secret \
  WQ_DB_NAME=ming \
  python3 -m src.ming start

性能调参

Standalone 模式下，归档器默认处理 1000 事件/秒。通过环境变量可灵活调整：

场景推荐

# 场景 1: 默认（大多数用户，1000 events/s）
MING_MODE=standalone python3 -m src.ming start

# 场景 2: 高吞吐（写入密集，~5000 events/s）
WQ_ARCHIVER_BATCH_SIZE=5000 \
WQ_ARCHIVER_FLUSH_SEC=0.5 \
MING_MODE=standalone python3 -m src.ming start

# 场景 3: 省电模式（低负载设备，~200 events/s）
WQ_ARCHIVER_BATCH_SIZE=200 \
WQ_ARCHIVER_FLUSH_SEC=5.0 \
MING_MODE=standalone python3 -m src.ming start

提示：调整参数后需重启归档器生效。前端 Config 面板可查看当前配置值（只读）。

运行测试

# 全量测试
python -m pytest tests/ -v

# 仅适配器 Mock 测试
python -m pytest tests/test_probe_*_mock.py -v

当前状态：440 passed, 0 failed, 2 skipped

代码量预算

核心底座 < 2,000 行 — 探针 + 归档器 + CLI + 查询，零第三方依赖。删除任一则写流水线失效。

以下为可选扩展，按需加载，配置见 config/budget.json：

目录结构

├── src/                    # 源代码
│   ├── ming.py       # 统一入口
│   ├── probe_uni.py        # 探针
│   ├── archiver.py         # 归档器
│   ├── cli.py              # CLI
│   ├── adapters/           # 适配器
│   └── plugins/            # 插件
├── tests/                  # 测试
├── config/                 # 配置
│   └── budget.json         # 代码量预算
├── updocs/                 # 文档（架构+探针+诊断+数据+接口+运维+测试）
└── .github/workflows/      # CI/CD

贡献

见 CONTRIBUTING.md。

铁律（违反即 P0）

• Standalone 零第三方依赖：仅 Python 标准库
• Cluster 唯一额外依赖：仅 pymysql
• 探针纯粹：probe_uni.py 不 import sqlite3/pymysql
• 唯一写入者：只有归档器可写入持久层
• 只读对外：查询模块使用只读连接

许可

Business Source License 1.1 — 年收入 <$100K 的公司和个人免费商用，非商用无限制。2030-12-31 自动转换为 Apache 2.0。详见 LICENSE 文件。

作者

• 陈正 (Chenzheng) · @wulun811
• 官方邮箱：zhulong007ai@163.com
• 灵感始于：诛仙协议 / THEOCLAST Protocol (TCL)

乾坤镜 v0.11.12.post8 — 为社区而生。

⚠️ 测试阶段声明：乾坤镜目前处于活跃开发阶段（版本 0.x），尚未发布 1.0 正式版。 软件按"现状"提供，不附带任何明示或暗示的担保。使用者应自行承担风险。 生产环境使用前请充分测试。详见 LICENSE。