明鉴 MingJian

See Clearly, Judge Wisely

An open-source strategic intelligence cockpit for evidence-grounded decisions, multi-agent debate, scenario simulation, and auditable recommendations.

Language / 语言

English · 中文 · हिन्दी · 日本語

_{证据先于观点 · 多源求证 · 多方辩论 · 持续校验}

Signal	What MingJian Delivers
Evidence first	Every recommendation is grounded in collected sources, extracted claims, and replayable traces.
Debate, not monologue	Specialized agents challenge assumptions before the system returns a recommendation.
Local sovereignty	Community runs locally with open-source code, local data control, and a 24-hour monitoring window.
Decision memory	Sessions, recommendation versions, refreshes, source health, and user outcomes stay connected.

Product Read

MingJian is built for people who need to make consequential decisions under uncertainty: founders, analysts, operators, researchers, strategists, and teams that need evidence they can inspect instead of answers they have to blindly trust.

The product experience is closer to a strategic intelligence cockpit than a chat box. A user submits a decision-support request; MingJian gathers evidence, runs analysis and simulation, convenes a debate council, returns a first recommendation, then keeps a versioned record that can be refreshed when source material changes.

Edition Boundary

Edition	Distribution	Core Workflow	Commercial Layer
Community	Apache 2.0 self-hosted upstream	Full public decision workflow with 24-hour local monitoring	None
Cloud	Hosted SaaS subscription	Superset of Community public core	Subscription, metering, tenant operations
Enterprise	Private / on-prem deployment	Superset of Community public core	License, audit, governance, private connectors

This repository is the Community edition. It must remain a strong open-source core: no Cloud subscription surfaces, no Enterprise-only governance code, and no proprietary mobile entry point unless explicitly published later.

Decision Workflow

Question
  -> source discovery
  -> evidence extraction
  -> analysis and simulation
  -> role-based debate
  -> recommendation
  -> version timeline
  -> scheduled / source-change refresh
  -> decision record and outcome feedback

Stage	Purpose	User-Visible Proof
Gather	Collect multi-source evidence from news, code, social, and public data feeds.	Source list, cursor health, last checked time.
Reason	Convert evidence into arguments, risks, simulations, and structured claims.	Analysis artifacts, report sections, debate rounds.
Debate	Let role-based agents critique, revise, and arbitrate the decision.	Support/challenge/arbiter traces.
Remember	Persist sessions, recommendation versions, refresh triggers, and outcomes.	Timeline, recommendation history, feedback records.

What Makes It Different

Old AI Analysis	MingJian
One answer, little context.	Evidence chain, debate trail, and recommendation versions.
Single-model blind spots.	Multi-agent critique with support, challenge, and arbitration roles.
Static responses.	Scheduled refresh and source-change triggered updates.
Hard to audit.	Deterministic traces, source attribution, and decision records.
Generic workflow.	Strategy, risk, market, policy, technical, social, and security perspectives.

🔬 Core Features

1. Evidence-Driven, Not Guess-Driven

The Problem: Traditional AI tools give you answers without showing their work.

Our Solution: 明鉴 grounds every decision in real-world evidence from 10+ data sources. Every claim is traceable, every decision is auditable.

2. Multi-Agent Debate Protocol

The Problem: Single AI models have blind spots and biases.

Our Solution: Multiple AI models (GPT, Gemini, Claude, Grok) debate your decisions, challenging assumptions and reaching evidence-backed conclusions.

3. Dual-Domain Expertise

The Problem: Most AI tools are generic and don't understand your specific domain.

Our Solution: 明鉴 supports both Corporate (market analysis, competitive intelligence) and Military (operational planning, logistics) with domain-specific rules and models.

4. Full Auditability with Decision Traces

The Problem: You can't explain how AI reached a conclusion.

Our Solution: Every simulation produces a deterministic decision trace — a step-by-step record of how the AI reached its conclusion. No black boxes.

5. Jarvis Self-Repair Engine

The Problem: AI outputs can be wrong, but you don't know until it's too late.

Our Solution: 明鉴 reviews its own outputs, identifies weaknesses, and iterates until quality thresholds are met — all without human intervention.

6. Real-Time Streaming Analysis

The Problem: You wait for AI to finish, then get a black-box result.

Our Solution: Submit an analysis request and watch the AI work in real-time — streaming progress events, source attribution, and intermediate results.

7. 9-Agent Decision Council

The Problem: Single AI models have blind spots and biases.

Our Solution: 明鉴 deploys 9 specialized AI agents — each with a distinct role, perspective, and model — to form a decision council:

Role	Agent	Function
🟢 Strategic Advocate	Core	Argues FOR, finds supporting evidence
🔴 Risk Challenger	Core	Argues AGAINST, finds counter-evidence
⚖️ Chief Arbitrator	Core	Delivers final verdict based on evidence
🔍 Intelligence Analyst	Perspective	Assesses evidence quality
🌍 Geopolitical Expert	Perspective	Geopolitical analysis
💰 Economic Analyst	Perspective	Economic/market analysis
⚔️ Military Strategist	Perspective	Military/security analysis
🔮 Tech Forecaster	Perspective	Technology trend analysis
👥 Social Impact Assessor	Perspective	Social/public opinion analysis

Inspired by Mixture of Experts (MoE) architecture: core agents are always active, perspective agents are activated as needed — sparse activation at the software layer.

🆚 明鉴 vs The Competition

Feature	明鉴	Manus	Traditional AI	Single-Agent	LangChain
Data Sources	✅ 10+ real-time	⚠️ General search	❌ Manual input	⚠️ Limited	⚠️ Limited
Evidence Chain	✅ Full traceability	❌ No tracking	❌ No tracking	❌ No tracking	❌ No tracking
Multi-Agent Debate	✅ 9-agent adversarial	⚠️ Orchestrator + sub-agents	❌ Single model	❌ Single model	⚠️ Basic
Decision Traces	✅ Deterministic	❌ Black box	❌ Black box	❌ Black box	❌ Black box
Self-Repair	✅ Jarvis engine	⚠️ Dynamic re-planning	❌ None	❌ None	❌ None
Streaming Analysis	✅ Real-time	✅ Real-time	❌ Batch only	❌ Batch only	⚠️ Limited
Continuous Monitoring	✅ WatchRule + auto-update	❌ One-shot tasks	❌ None	❌ None	❌ None
Corporate Domain	✅ Full support	❌ Generic	⚠️ Generic	❌ Generic	❌ Generic
Military Domain	✅ Full support	❌ Generic	⚠️ Generic	❌ Generic	❌ Generic
Scenario Branching	✅ Beam-search	❌ None	❌ Manual	❌ None	❌ None
Knowledge Graph	✅ Embedding-backed	❌ None	❌ None	❌ None	❌ None
Code Execution	⚠️ Planned	✅ Full sandbox VM	❌ None	⚠️ Limited	❌ None
Data Sovereignty	✅ Self-hosted	❌ Cloud only	⚠️ Varies	⚠️ Varies	✅ Self-hosted
Open Source	✅ Apache 2.0	❌ Closed source	⚠️ Varies	⚠️ Varies	✅ Various

🧭 明鉴的定位：AI 决策参谋

不是通用工具，而是专属参谋团。

AI Agent 时代已经到来。编排层（Orchestrator）协调多个子 Agent 和工具，在沙箱环境中自主完成复杂任务 — 这已经被证明是有效的范式。

明鉴在此基础上更进一步，专注于决策智能：

设计理念

设计原则	明鉴的实践
编排层 > 底层模型	9智能体注册中心，按角色分配模型
实时流式展示建立信任	辩论逐轮渲染，用户看到每一步推理
多工具协同完成任务	12个数据源 + 辩论引擎 + 仿真引擎
动态重规划应对失败	辩论失败时自动调整策略重新论证

核心差异化

维度	明鉴
目标	做出更好的决策
推理方式	9个智能体独立论证、交叉质询、仲裁裁决
证据基础	12个数据源结构化采集 → 证据提取 → 知识图谱
持续性	WatchRule 持续监控 + 定时更新 + 突发事件检测
领域深度	企业/军事双领域仿真，KPI 追踪，场景分支
透明度	展示推理过程 + 用户可投票质疑
数据主权	自部署，数据完全在本地
成本	自有模型，边际成本趋近于零

MoE 架构思想

明鉴的 9 智能体系统借鉴了 Mixture of Experts (MoE) 的核心思想：

用户问题 → 路由器（辩论流程）→ 选择专家组合 → 独立推理 → 加权裁决

就像 DeepSeek-V3 用 256 个专家中只激活少数最相关的，明鉴在 9 个智能体中根据问题类型选择最合适的组合。核心 3 角色（支持方/挑战方/仲裁官）始终激活，视角 6 角色按需参与 — 这就是软件层的稀疏激活。

🎯 Use Cases

Use Case	Description	Benefit
📊 Investment Research	Analyze market trends, debate investment theses	Faster research, better decisions
🏭 Corporate Strategy	Competitive intelligence, scenario planning	Data-driven decisions, reduced risk
⚔️ Military Planning	Operational analysis, logistics optimization	Strategic advantage, better outcomes
🛡️ Risk Management	Multi-perspective risk assessment	Reduced uncertainty
📈 Market Analysis	Real-time market intelligence	Faster insights, better positioning
🎯 Policy Analysis	Multi-stakeholder impact assessment	Informed policy, better outcomes

🚀 Quick Start

One-Click Docker Setup

The fastest way to run 明鉴 locally is the Docker setup script. It checks Docker, creates .env from .env.example, asks for your OpenAI API key, and starts the full stack.

Prerequisites

Install Docker Desktop first, then run:

chmod +x setup.sh
./setup.sh

When the script finishes, open:

Service	URL
Frontend	http://localhost:3001
API	http://localhost:8000
MinIO Console	http://localhost:9001

MinIO login: use PLANAGENT_MINIO_ACCESS_KEY / PLANAGENT_MINIO_SECRET_KEY from your .env.

To stop the Docker stack:

docker compose -f docker-compose.yml down

Manual Development Setup

Use this path if you want to run the backend and frontend directly on your machine for development.

Frontend Directory Policy

frontend-v2/ is the active Vite frontend. The older frontend/ and frontend-new/ experiments have been retired, so new product UI, builds, and Docker development should target frontend-v2/.

Prerequisites

Before you begin, ensure you have the following installed:

Requirement	Version	Installation
Python	3.12+	python.org
Node.js	18+	nodejs.org
npm	9+	Comes with Node.js
Git	2.30+	git-scm.com
PostgreSQL	14+ (optional)	postgresql.org
Redis	7+ (optional)	redis.io

System Requirements

Component	Minimum	Recommended
CPU	2 cores	4+ cores
RAM	4 GB	8+ GB
Storage	10 GB	50+ GB
OS	macOS, Linux, Windows	macOS or Linux

Environment Variables

Create a .env file in the project root with the following variables:

# ═══════════════════════════════════════════════════════════════
# AI Model Configuration
# ═══════════════════════════════════════════════════════════════
# You only need ONE API key to get started.
# The system automatically uses the same key for all 7 model slots
# (primary, extraction, x_search, report, debate_advocate,
#  debate_challenger, debate_arbitrator) unless you override them.

PLANAGENT_OPENAI_API_KEY=your_api_key_here

# Override individual targets (all fall back to shared if unset).
# Set the API key first, run the provider connection test to fetch available models,
# then paste one of the returned model IDs if you need a manual override.
# PLANAGENT_OPENAI_PRIMARY_MODEL=
# PLANAGENT_OPENAI_PRIMARY_API_KEY=sk-...
# PLANAGENT_OPENAI_EXTRACTION_MODEL=
# PLANAGENT_OPENAI_DEBATE_ADVOCATE_MODEL=
# PLANAGENT_OPENAI_DEBATE_CHALLENGER_MODEL=
# PLANAGENT_OPENAI_DEBATE_ARBITRATOR_MODEL=

# ═══════════════════════════════════════════════════════════════
# Database (optional — defaults to SQLite for local dev)
# ═══════════════════════════════════════════════════════════════
# PLANAGENT_DATABASE_URL=postgresql+psycopg://planagent:planagent@localhost:5432/planagent

# ═══════════════════════════════════════════════════════════════
# Redis (optional — for event bus in production)
# ═══════════════════════════════════════════════════════════════
# PLANAGENT_REDIS_URL=redis://localhost:6379/0

# ═══════════════════════════════════════════════════════════════
# MinIO Object Storage (optional)
# ═══════════════════════════════════════════════════════════════
# PLANAGENT_MINIO_ENDPOINT=localhost:9000
# PLANAGENT_MINIO_ACCESS_KEY=minioadmin
# PLANAGENT_MINIO_SECRET_KEY=minioadmin

# ═══════════════════════════════════════════════════════════════
# X / Twitter (optional — for social intelligence)
# ═══════════════════════════════════════════════════════════════
# X_BEARER_TOKEN=your_x_bearer_token

# ═══════════════════════════════════════════════════════════════
# Frontend
# ═══════════════════════════════════════════════════════════════
NEXT_PUBLIC_API_URL=/api

💡 Key Point: Even if you only have access to one model provider (e.g., OpenAI, or any OpenAI-compatible API), you can use it for all 7 model slots. Just set PLANAGENT_OPENAI_API_KEY — the system fills in the rest automatically. No need for 4 different API keys to get started.

Compatible Providers

All slots use the OpenAI-compatible /chat/completions endpoint. You can mix and match providers freely:

Provider	Base URL
OpenAI	`https://api.openai.com/v1`
Anthropic (Claude)	`https://api.anthropic.com/v1/openai`
DeepSeek	`https://api.deepseek.com/v1`
Google Gemini	`https://generativelanguage.googleapis.com/v1beta/openai`
xAI Grok	`https://api.x.ai/v1`
Xiaomi MiMo	`https://token-plan-cn.xiaomimimo.com/v1`
Zhipu GLM	`https://open.bigmodel.cn/api/paas/v4`
MiniMax	`https://api.minimax.chat/v1`
Any compatible proxy	Your proxy URL

Installation Steps

# 1. Clone the repository
git clone https://github.com/dashitongzhi/MingJian.git
cd planagent

# 2. Create and activate Python virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# 3. Install Python dependencies
pip install -e ".[dev]"

# 4. Install frontend dependencies
cd frontend-v2
npm install
cd ..

# 5. Configure environment
cp .env.example .env
# Edit .env file with your API keys and settings

# 6. Initialize database (if using PostgreSQL)
# Create database named 'planagent'
# Run migrations
alembic upgrade head

# 7. Start backend server
uvicorn planagent.main:app --reload --host 127.0.0.1 --port 8000

# 8. Start frontend (in a new terminal)
cd frontend-v2
npm run dev
# Open http://localhost:3000

Community local mode is loopback-only and uses a deployment-local single-user session. Do not bind the API to 0.0.0.0 or another non-loopback address unless PLANAGENT_REMOTE_ACCESS_ENABLED=true and a persistent PLANAGENT_AUTH_SECRET_KEY of at least 32 bytes are configured. Remote self-registration is always disabled in Community; remote mode exposes only the bootstrap admin login. setup.sh stores the initial administrator password in PLANAGENT_BOOTSTRAP_ADMIN_PASSWORD inside the local .env; rotate it after the first remote administrator login through POST /auth/change-password, then update the local .env copy.

Worker Commands

The Docker Compose stack starts the configured workers automatically. For a manual installation, list the available worker IDs and run only the workers needed by the local deployment:

planagent-worker list
planagent-worker ingest-worker --loop
planagent-worker strategic-watch-worker --loop

Each worker records terminal failures in the dead-letter table. Stream-backed workers also reclaim stale pending events and retry them up to the configured PLANAGENT_WORKER_MAX_ATTEMPTS limit.

PDF export is included in the default Python installation through WeasyPrint. Report Markdown is treated as untrusted input during PDF rendering: external http(s), file, and other resource fetches are disabled. Embed approved images as data: URLs when a self-contained PDF needs them. Inline resources are restricted to approved image MIME types, 5 MiB per image, and 16 images per report; Markdown input is capped at 500,000 characters. The Docker image already includes WeasyPrint's native Pango/Cairo libraries; manual installations must provide the equivalent native libraries for their operating system.

📦 Dependencies

Backend Dependencies (Python)

Package	Version	Purpose
FastAPI	0.110+	High-performance async API framework
SQLAlchemy	2.0+	Database ORM
Alembic	1.16+	Database migrations
Pydantic	2.11+	Data validation
OpenAI	2.28+	OpenAI API client
Anthropic	0.52+	Anthropic API client
Redis	6.2+	Event bus and caching
pgvector	0.3+	Vector similarity search
MinIO	7.2+	Object storage
HTTPX	0.28+	Async HTTP client
Uvicorn	0.35+	ASGI server
WeasyPrint	66+	Restricted Markdown-to-PDF rendering

Frontend Dependencies (Node.js)

Package	Version	Purpose
Vite	8+	Frontend build tool
React	19+	UI library
TypeScript	6.0+	Type safety
Tailwind CSS	4.2+	Utility-first CSS
React Router	7+	Client-side routing
Recharts	3.8+	Charting library

Development Dependencies

Package	Version	Purpose
pytest	8.4+	Testing framework
pytest-asyncio	1.1+	Async test support
Ruff	0.12+	Python linter
ESLint	9+	JavaScript linter
Prettier	3+	Code formatter
vitest	^4.1.5	Unit testing framework
@testing-library/react	^16.x	React component testing
@testing-library/jest-dom	^6.x	Custom Jest matchers

🏗️ System Architecture

graph TB
    subgraph "User Interface"
        Console[Strategic Console]
        API[FastAPI Control Plane]
    end
    
    subgraph "Core Services"
        Evidence[Evidence Ingestion]
        Simulation[Simulation Engine]
        Debate[Debate Engine]
        Jarvis[Jarvis Integration]
    end
    
    subgraph "Data Sources"
        RSS[RSS Feeds]
        News[Google News]
        Reddit[Reddit]
        GitHub[GitHub]
        X[X/Twitter]
        GDELT[GDELT]
    end
    
    subgraph "Storage"
        PostgreSQL[(PostgreSQL)]
        Redis[(Redis)]
        MinIO[(MinIO)]
    end
    
    Console --> API
    API --> Evidence
    API --> Simulation
    API --> Debate
    API --> Jarvis
    
    Evidence --> RSS
    Evidence --> News
    Evidence --> Reddit
    Evidence --> GitHub
    Evidence --> X
    Evidence --> GDELT

📁 Project Structure

Backend:

src/planagent/
├── config/              # Settings package (was config.py 527 lines → 4 files)
│   ├── __init__.py
│   ├── base.py          # Core settings (DB, Redis, Minio)
│   ├── openai.py        # Dynamic OpenAI target resolution
│   └── main.py          # Composed Settings class
├── services/
│   ├── debate/          # Debate package (was debate.py 3273 lines → 7 modules)
│   │   ├── prompts.py   # Agent role prompts & round plans
│   │   ├── rounds.py    # Round execution logic
│   │   ├── llm.py       # LLM calls & retry
│   │   ├── adjudication.py # Verdict & recommendations
│   │   ├── revisions.py # Stance revision tracking
│   │   └── triggers.py  # Auto-trigger logic
│   ├── simulation/      # Simulation package (was simulation.py 2281 lines → 6 modules)
│   │   ├── engine.py    # Core simulation engine
│   │   ├── scenarios.py # Scenario generation
│   │   ├── impact.py    # Impact assessment & scoring
│   │   ├── report.py    # Report generation
│   │   └── domain_packs.py # Domain pack management
│   └── ...              # Other services
├── db.py                # Database layer (cleaned, Alembic-only migrations)
└── ...

Frontend:

frontend-v2/src/
├── components/
│   ├── layout/          # App shell, sidebar, navigation chrome
│   └── ui/              # Shared cockpit surfaces and status components
├── pages/               # Dashboard, assistant, monitoring, reports, settings
├── api/                 # API endpoint helpers
├── hooks/               # Theme and app-level React hooks
└── main.tsx             # Vite entry point

🧪 Testing

Backend Tests (pytest)

# Run the complete backend suite
python -m pytest -q

# Run only unit tests while iterating
python -m pytest tests/unit/ -v

Frontend Tests (Vitest)

cd frontend-v2
npm run lint
npm test
npx tsc -b
npx vite build

Stress Test

# 7-dimension stress test (requires running backend)
python tests/stress_test.py

Latest Results:

✅ Backend: 613 passed, 1 skipped
✅ Frontend: ESLint passed, 10 tests passed, TypeScript passed, production build passed
✅ Quality gates: full Ruff check/format and full mypy passed
✅ PDF security: external resource fetch regression passed; native rendering uses the Docker image's Pango/Cairo libraries

📊 Quality & Performance

Metric	Value
Backend test suite	613 passed, 1 environment-dependent PDF skip
Frontend test suite	10 passed
Python lint and format	Passed across `src/` and `tests/`
Python type check	Passed across `src/planagent/`
Frontend lint and type check	Passed
Frontend production build	Passed

📚 Documentation

🤝 Contributing

We welcome contributions! See our Contributing Guide.

# 1. Fork the repository
# 2. Create a feature branch
git checkout -b feature/amazing-feature

# 3. Make your changes
# 4. Run tests
pytest

# 5. Commit your changes
git commit -m "feat: add amazing feature"

# 6. Push to the branch
git push origin feature/amazing-feature

# 7. Open a Pull Request

📄 License

This project is licensed under the Apache License 2.0 - see LICENSE for details.

🙏 Acknowledgments

FastAPI - High-performance async APIs
Vite - Frontend build tooling
PostgreSQL + pgvector - Database
Redis Streams - Event streaming
MinIO - Object storage
Linux.do - 开源社区支持与交流

📞 Support & Contact

If you're interested in this project — whether for collaboration, feedback, or just a chat — feel free to reach out! We'd love to hear from you.

📧 Email: cajd6876@gmail.com | 2965866908@qq.com
🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions

🌟 Star History

明鉴 — 明察秋毫，鉴往知来

明鉴 — See Clearly, Judge Wisely

Made with ❤️ by the 明鉴 Team

Name		Name	Last commit message	Last commit date
Latest commit History 305 Commits
.github		.github
config		config
docker		docker
docs		docs
examples		examples
frontend-v2		frontend-v2
migrations		migrations
output		output
outputs		outputs
rules		rules
scripts		scripts
src/planagent		src/planagent
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
COMMERCIAL.md		COMMERCIAL.md
CONTRIBUTING.md		CONTRIBUTING.md
DESIGN.md		DESIGN.md
Dockerfile		Dockerfile
EDITION.md		EDITION.md
LICENSE		LICENSE
MCP_TOOLS.md		MCP_TOOLS.md
README.hi.md		README.hi.md
README.ja.md		README.ja.md
README.md		README.md
README.zh-CN.md		README.zh-CN.md
SECURITY.md		SECURITY.md
TECHNICAL_DEBT_BACKLOG.md		TECHNICAL_DEBT_BACKLOG.md
alembic.ini		alembic.ini
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
setup.sh		setup.sh

Folders and files

Latest commit

History

Repository files navigation

明鉴 MingJian

See Clearly, Judge Wisely

Product Read

Edition Boundary

Decision Workflow

What Makes It Different

🔬 Core Features

1. Evidence-Driven, Not Guess-Driven

2. Multi-Agent Debate Protocol

3. Dual-Domain Expertise

4. Full Auditability with Decision Traces

5. Jarvis Self-Repair Engine

6. Real-Time Streaming Analysis

7. 9-Agent Decision Council

🆚 明鉴 vs The Competition

🧭 明鉴 的定位：AI 决策参谋

设计理念

核心差异化

MoE 架构思想

🎯 Use Cases

🚀 Quick Start

One-Click Docker Setup

Prerequisites

Manual Development Setup

Frontend Directory Policy

Prerequisites

System Requirements

Environment Variables

Compatible Providers

Installation Steps

Worker Commands

📦 Dependencies

Backend Dependencies (Python)

Frontend Dependencies (Node.js)

Development Dependencies

🏗️ System Architecture

📁 Project Structure

🧪 Testing

Backend Tests (pytest)

Frontend Tests (Vitest)

Stress Test

📊 Quality & Performance

📚 Documentation

🤝 Contributing

📄 License

🙏 Acknowledgments

📞 Support & Contact

🌟 Star History

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

🧭 明鉴的定位：AI 决策参谋

Packages