使用说明
分类账——第9-10周入门代码
快速开始
# 1. Install dependencies
pip install -r requirements.txt
# 2. Start PostgreSQL
docker run -d -e POSTGRES_PASSWORD=apex -e POSTGRES_DB=apex_ledger -p 5432:5432 postgres:16
# 3. Set environment
cp .env.example .env
# Edit .env — add your ANTHROPIC_API_KEY
# 4. Generate all data (companies + documents + seed events → DB)
python datagen/generate_all.py --db-url postgresql://postgres:apex@localhost/apex_ledger
# 5. Validate schema (no DB needed)
python datagen/generate_all.py --skip-db --skip-docs --validate-only
# 6. Run Phase 0 tests (must pass before starting Phase 1)
pytest tests/test_schema_and_generator.py -v
# 7. Begin Phase 1: implement EventStore
# Edit: ledger/event_store.py
# Test: pytest tests/test_event_store.py -v
什么开箱即用
- 完整事件模式（45种事件类型）--
ledger/schema/events.py - 完整的数据生成器（GAAP PDF、Excel、CSV、1200多个种子事件）
- 事件模拟器（所有5个代理管道，确定性）
- 模式验证器（根据EVENT_REGISTRY验证所有事件）
- 第0阶段测试：10/10通过
你实施什么
| 组件 | 文件 | 阶段 |
|---|---|---|
| 活动商店 | ledger/event_store.py |
1 |
| 申请人注册客户 | ledger/registry/client.py |
1 |
| 域聚合 | ledger/domain/aggregates/ |
2 |
| 文档处理代理 | ledger/agents/base_agent.py |
2 |
| 信用分析代理 | ledger/agents/base_agent.py |
2（参考文献） |
| 欺诈检测代理 | ledger/agents/base_agent.py |
3 |
| 合规代理 | ledger/agents/base_agent.py |
3 |
| DecisionOrchestrator代理 | ledger/agents/base_agent.py |
3 |
| 投影+守护进程 | ledger/projections/ |
4 |
| Upcasters | ledger/upcasters.py |
4 |
| MCP服务器 | ledger/mcp_server.py |
5 |
按阶段划分的闸门测试
pytest tests/test_schema_and_generator.py -v # Phase 0: all must pass before Phase 1
pytest tests/test_event_store.py -v # Phase 1
pytest tests/test_domain.py -v # Phase 2
pytest tests/test_narratives.py -v # Phase 3: all 5 must pass
pytest tests/test_projections.py -v # Phase 4
pytest tests/test_mcp.py -v # Phase 5
账本——代理事件存储和审计基础架构
Apex金融服务贷款决策平台。五个LangGraph代理。完整的事件源审计跟踪。PostgreSQL支持。
先决条件
- Python 3.11+
- PostgreSQL 14+
- 无烟煤API键
安装
pip install -r requirements.txt
环境
复制 .env.example 到 .env 并填写您的值：
cp .env.example .env
所需变量：
ANTHROPIC_API_KEY=sk-ant-...
DATABASE_URL=postgresql://ledger:ledger@localhost:5432/apex_ledger
TEST_DB_URL=postgresql://ledger:ledger@localhost:5432/apex_ledger_test
DOCUMENTS_DIR=./documents
REGULATION_VERSION=2026-Q1
LOG_LEVEL=INFO
数据库设置
创建数据库：
psql -U postgres -c "CREATE DATABASE apex_ledger;"
psql -U postgres -c "CREATE DATABASE apex_ledger_test;"
psql -U postgres -c "CREATE USER ledger WITH PASSWORD 'ledger';"
psql -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE apex_ledger TO ledger;"
psql -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE apex_ledger_test TO ledger;"
运行迁移：
psql -U ledger -d apex_ledger -f src/schema.sql
psql -U ledger -d apex_ledger_test -f src/schema.sql
种子数据
运行数据生成器（一次--幂等）：
python datagen/generate_all.py \
--applicants 80 \
--db-url postgresql://ledger:ledger@localhost:5432/apex_ledger \
--docs-dir ./documents \
--output-dir ./data \
--random-seed 42
预计产量：80家公司，320份文件，1847场种子活动。
运行测试
# Phase 1 — InMemoryEventStore (no DB required)
pytest tests/phase1/ -v
# Concurrency test (mandated)
pytest tests/test_concurrency.py -v
# All tests
pytest tests/ -v
运行管道
端到端处理一个应用程序：
python scripts/run_pipeline.py --app APEX-0007 --phase document
python scripts/run_pipeline.py --app APEX-0012 --phase credit
MCP 服务器
python -m ledger.mcp_server
默认情况下，服务器在端口8765上运行。
项目结构
apex-ledger/
├── schema/events.py # Canonical event schema — never modify
├── agents/ # LangGraph agents
├── registry/client.py # Applicant Registry — read-only
├── src/ # Core implementation
│ ├── schema.sql # PostgreSQL schema
│ ├── event_store.py # EventStore + InMemoryEventStore
│ ├── models/events.py # Re-exports from schema/events.py
│ ├── aggregates/ # Domain aggregates
│ ├── commands/handlers.py # Command handlers
│ ├── projections/ # Read model projections
│ ├── upcasting/ # Schema evolution
│ ├── integrity/ # Audit chain + Gas Town
│ └── mcp/ # MCP server
├── tests/ # Test suite
├── datagen/ # Data generator
├── scripts/ # Pipeline + demo scripts
└── artifacts/ # Generated outputs
