Civitas

Civitas 是一个自主的多智能体食品采购系统，结合了协商、证据谱系分析、自适应重新规划、确定性优化和受保护的 MCP 执行。其目标产品接口是一个与 Codex 兼容的 MCP 服务器：操作员以对话方式陈述采购目标，Codex 调用 Civitas 的意图级工具，而 Civitas 主导完整的规划与安全流程。

专门的 Parliament 智能体调查相互竞争的目标，并比较求解器生成的采购备选方案。随后，一个具备证据意识的 Jury 会评估来源出处、真实的来源独立性、矛盾以及对抗性异议，然后操作才能通过执行安全边界。

React 应用程序是一个可选的、只读的证据与执行审计查看器，而非产品的主要入口点。该仓库包含严格的入站 MCP 契约、传输无关的采购外观、确定性集成套件，以及基于查看器的错误共识演示。将这些部分连接到 PostgreSQL、持久化工作器和真实采购提供方的部署组合仍然因环境而异。参见 MCP_INTERFACE.md、MCP_AGENT_WORKPLAN.md、PLAN.md、AGENTS.md、TECH_STACK.md 和 SECURITY.md。

产品接口

预期的部署在应用程序两侧都使用 MCP：

Operator → Codex → Civitas MCP server → planning / Jury / execution services
                                      → procurement-provider MCP servers

Codex 负责对话、意图捕获、进度叙述和呈现审批请求。Civitas 对类型化输入、证据检索、优化、Parliament、Jury 与 Dissent、重新规划、新鲜度重新验证、审批绑定、幂等性和执行审计保持权威。模型或聊天消息无法绕过这些控制。

主要交互应尽可能精简：

User: Protect seven days of demand across our warehouses while minimizing waste.
Codex: Civitas found false consensus on a stale lead-time source and replanned.
       The revised plan has Integrity 92/100 and all hard gates pass.
       Approve the exact plan for execution?

Related MCP server: mendicant-mcp-server

开发

前提条件：Python 3.12、uv、Node.js 24、pnpm 10.31.0 和 Docker Compose。

uv sync --frozen --all-groups
pnpm install --frozen-lockfile
docker compose up -d postgres
uv run alembic upgrade head

PostgreSQL 默认监听端口 55432，以避免与本地安装冲突。设置 CIVITAS_POSTGRES_PORT 可覆盖该端口。

使用以下命令运行必要的检查：

uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run pytest
pnpm format
pnpm lint
pnpm typecheck
pnpm build

使用以下命令在本地运行当前的演示 API 和可选的审计查看器：

uv run uvicorn civitas.api.app:create_app --factory --host 127.0.0.1 --port 8001
pnpm --filter @civitas/web dev

Vite 开发服务器将 /api 请求代理到 http://127.0.0.1:8001。

civitas.api.app:create_app 是本地模拟的演示 API。它不使用任何真实提供方，也不会产生真实的采购副作用。请保持其绑定在回环地址上。civitas.api.guarded_api 中由持久化支持的 API 工厂在被部署组合时，需要至少 32 个字符的 bearer token 和一个组织绑定。

演示

当前的端到端集成演示是一个错误共识案例文件。它从供应商 A 基于共享的过期证据获胜开始，经过洁净室 Dissent 检查，重新打开规划，在新鲜公开证据出现后批准供应商 B，然后执行新鲜度重新验证和防重复的 MCP 执行。

使用以下命令运行黄金套件：

uv run pytest tests/golden/test_scenarios.py -q

使用以下命令运行集成相关的检查：

uv run pytest tests/integration/test_demo_api.py tests/unit/execution/test_service.py tests/contract/test_mcp_integration.py -q

对于离线查看器演示，请打开 http://127.0.0.1:5173，选择 False consensus with clean-room dissent，然后开始运行。SSE 流在场景执行期间生成。事件记录应显示以下顺序：

evidence retrieval
→ Parliament proposal / challenge / concession
→ Jury investigate
→ clean-room Dissent evidence
→ replanning
→ Jury approve
→ freshness revalidation
→ execution succeeded
→ duplicate execution downgraded to duplicate